Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Changes In Branch doc-fixup-and-markdown-localdoc
Excluding Merge-Ins
This is equivalent to a diff from
a8b930a4d3
to 58be278739
|
2019-03-21
| | |
| 19:50 |
|
check-in: e0d7b4dc8e user: aku tags: doc-fixup-and-markdown
|
| 02:16 |
|
Closed-Leaf
check-in: 58be278739 user: aku tags: doc-fixup-and-markdown-localdoc
|
| 01:50 |
|
check-in: 7cfe8cda34 user: aku tags: doc-fixup-and-markdown-localdoc
|
|
2019-03-20
| | |
| 23:39 |
|
check-in: 945be77637 user: aku tags: doc-fixup-and-markdown-localdoc
|
| 22:57 |
|
check-in: a8b930a4d3 user: aku tags: doc-fixup-and-markdown
|
| 05:31 |
|
check-in: 78d88166a8 user: aku tags: doc-fixup-and-markdown
|
| | |
Changes to embedded/index.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
<div class='fossil-doc' data-title='Tcl Library Source Code'>
<h1 align="center">Tcl Library Source Code</h1>
<center>
<form action='../../../docsrch' method='GET'>
<input type="text" name="s" size="40" autofocus>
<input type="submit" value="Search Docs">
</form>
<p><a href="www/toc.html">
Table Of Contents</a>
<a href="www/index.html">
Keyword Index</a>
</center>
<h2>Discussion & Contact</h2>
<ul>
<p>Tcllib has two <a href="https://sourceforge.net/p/tcllib/mailman/">mailing lists</a>,
one for notifications, the other for general discussion. These are managed at SourceForge,
|
|
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
<div class='fossil-doc' data-title='Tcl Library Source Code'>
<h1 align="center">Tcl Library Source Code</h1>
<center>
<form action='../../../docsrch' method='GET'>
<input type="text" name="s" size="40" autofocus>
<input type="submit" value="Search Docs">
</form>
<p><a href="md/toc.md">
Table Of Contents</a>
<a href="md/index.md">
Keyword Index</a>
</center>
<h2>Discussion & Contact</h2>
<ul>
<p>Tcllib has two <a href="https://sourceforge.net/p/tcllib/mailman/">mailing lists</a>,
one for notifications, the other for general discussion. These are managed at SourceForge,
|
| ︙ | | | ︙ | |
Added embedded/md/image/arch_core_container.png.
cannot compute difference between binary files
Added embedded/md/image/arch_core_eplugins.png.
cannot compute difference between binary files
Added embedded/md/image/arch_core_export.png.
cannot compute difference between binary files
Added embedded/md/image/arch_core_import.png.
cannot compute difference between binary files
Added embedded/md/image/arch_core_iplugins.png.
cannot compute difference between binary files
Added embedded/md/image/arch_core_support.png.
cannot compute difference between binary files
Added embedded/md/image/arch_core_transform.png.
cannot compute difference between binary files
Added embedded/md/image/arch_user_app.png.
cannot compute difference between binary files
Added embedded/md/image/arch_user_pkg.png.
cannot compute difference between binary files
Added embedded/md/image/architecture.png.
cannot compute difference between binary files
Added embedded/md/image/expr_ast.png.
cannot compute difference between binary files
Added embedded/md/image/flow.png.
cannot compute difference between binary files
Added embedded/md/image/gen_options.png.
cannot compute difference between binary files
Added embedded/md/index.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
|
[//000000001]: # (Index generated by tcllib/doctools/idx with format 'markdown')
# Keyword Index
----
[3](#c3) · [A](#cA) · [B](#cB) · [C](#cC) · [D](#cD) · [E](#cE) · [F](#cF) · [G](#cG) · [H](#cH) · [I](#cI) · [J](#cJ) · [K](#cK) · [L](#cL) · [M](#cM) · [N](#cN) · [O](#cO) · [P](#cP) · [Q](#cQ) · [R](#cR) · [S](#cS) · [T](#cT) · [U](#cU) · [V](#cV) · [W](#cW) · [X](#cX) · [Y](#cY) · [Z](#cZ)
----
#### <a name='c3'></a>Keywords: 3
|||
|---|---|
|<a name='3des'></a>3DES|[des](tcllib/files/modules/des/des.md) · [tclDES](tcllib/files/modules/des/tcldes.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr.md)|
#### <a name='cA'></a>Keywords: A
|||
|---|---|
|<a name='abstract_syntax_tree'></a>abstract syntax tree|[grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) · [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md)|
|<a name='acceptance'></a>acceptance|[grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md)|
|<a name='acceptor'></a>acceptor|[grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md)|
|<a name='active'></a>active|[transfer::connect](tcllib/files/modules/transfer/connect.md)|
|<a name='adaptors'></a>adaptors|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md)|
|<a name='adjacency_list'></a>adjacency list|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='adjacency_matrix'></a>adjacency matrix|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='adjacent'></a>adjacent|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='adjusting'></a>adjusting|[textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
|<a name='adler32'></a>adler32|[tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md)|
|<a name='aes'></a>aes|[aes](tcllib/files/modules/aes/aes.md)|
|<a name='after'></a>after|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='alias'></a>alias|[interp](tcllib/files/modules/interp/tcllib_interp.md)|
|<a name='amazon'></a>amazon|[S3](tcllib/files/modules/amazon-s3/S3.md)|
|<a name='ambiguous'></a>ambiguous|[grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md)|
|<a name='american_express'></a>American Express|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md)|
|<a name='amex'></a>AMEX|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md)|
|<a name='angle'></a>angle|[math::geometry](tcllib/files/modules/math/math_geometry.md) · [units](tcllib/files/modules/units/units.md)|
|<a name='anonymous_procedure'></a>anonymous procedure|[lambda](tcllib/files/modules/lambda/lambda.md)|
|<a name='ansi'></a>ansi|[term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) · [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) · [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='appender'></a>appender|[logger::appender](tcllib/files/modules/log/loggerAppender.md) · [logger::utils](tcllib/files/modules/log/loggerUtils.md)|
|<a name='application'></a>application|[nns](tcllib/files/apps/nns.md) · [nnsd](tcllib/files/apps/nnsd.md) · [nnslog](tcllib/files/apps/nnslog.md)|
|<a name='approximation_algorithm'></a>approximation algorithm|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='arc'></a>arc|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='arcfour'></a>arcfour|[rc4](tcllib/files/modules/rc4/rc4.md)|
|<a name='archive'></a>archive|[tar](tcllib/files/modules/tar/tar.md)|
|<a name='argument_integrity'></a>argument integrity|[tepam](tcllib/files/modules/tepam/tepam_introduction.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md)|
|<a name='argument_processing'></a>argument processing|[cmdline](tcllib/files/modules/cmdline/cmdline.md)|
|<a name='argument_validation'></a>argument validation|[tepam](tcllib/files/modules/tepam/tepam_introduction.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md)|
|<a name='arguments'></a>arguments|[tepam](tcllib/files/modules/tepam/tepam_introduction.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md)|
|<a name='argv'></a>argv|[cmdline](tcllib/files/modules/cmdline/cmdline.md)|
|<a name='argv0'></a>argv0|[cmdline](tcllib/files/modules/cmdline/cmdline.md)|
|<a name='array'></a>array|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md)|
|<a name='articulation_point'></a>articulation point|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='ascii85'></a>ascii85|[ascii85](tcllib/files/modules/base64/ascii85.md)|
|<a name='asn'></a>asn|[asn](tcllib/files/modules/asn/asn.md)|
|<a name='assembler'></a>assembler|[grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md)|
|<a name='assert'></a>assert|[control](tcllib/files/modules/control/control.md)|
|<a name='assign'></a>assign|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='ast'></a>AST|[grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md)|
|<a name='asynchronous'></a>asynchronous|[cache::async](tcllib/files/modules/cache/async.md)|
|<a name='attribute_control'></a>attribute control|[term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md)|
|<a name='augmenting_network'></a>augmenting network|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='augmenting_path'></a>augmenting path|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='authentication'></a>authentication|[autoproxy](tcllib/files/modules/http/autoproxy.md) · [SASL](tcllib/files/modules/sasl/sasl.md) · [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) · [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) · [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md)|
|<a name='automatic'></a>automatic|[nameserv::auto](tcllib/files/modules/nns/nns_auto.md)|
|<a name='automatic_documentation'></a>automatic documentation|[tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md)|
|<a name='automaton'></a>automaton|[grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md)|
|<a name='aycock'></a>aycock|[grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md)|
#### <a name='cB'></a>Keywords: B
|||
|---|---|
|<a name='bank'></a>bank|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md)|
|<a name='base32'></a>base32|[base32](tcllib/files/modules/base32/base32.md) · [base32::core](tcllib/files/modules/base32/base32core.md) · [base32::hex](tcllib/files/modules/base32/base32hex.md)|
|<a name='base64'></a>base64|[base64](tcllib/files/modules/base64/base64.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md)|
|<a name='bash'></a>bash|[string::token::shell](tcllib/files/modules/string/token_shell.md)|
|<a name='bee'></a>bee|[bee](tcllib/files/modules/bee/bee.md)|
|<a name='bench_language'></a>bench language|[bench_intro](tcllib/files/modules/bench/bench_intro.md) · [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) · [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md)|
|<a name='benchmark'></a>benchmark|[bench](tcllib/files/modules/bench/bench.md) · [bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) · [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) · [bench_intro](tcllib/files/modules/bench/bench_intro.md) · [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) · [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md)|
|<a name='ber'></a>ber|[asn](tcllib/files/modules/asn/asn.md)|
|<a name='bessel_functions'></a>Bessel functions|[math::special](tcllib/files/modules/math/special.md)|
|<a name='bfs'></a>bfs|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='bibliography'></a>bibliography|[bibtex](tcllib/files/modules/bibtex/bibtex.md)|
|<a name='bibtex'></a>bibtex|[bibtex](tcllib/files/modules/bibtex/bibtex.md)|
|<a name='bignums'></a>bignums|[math::bignum](tcllib/files/modules/math/bignum.md)|
|<a name='bind'></a>bind|[uevent](tcllib/files/modules/uev/uevent.md)|
|<a name='bipartite'></a>bipartite|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='bittorrent'></a>BitTorrent|[bee](tcllib/files/modules/bee/bee.md)|
|<a name='bittorrent'></a>bittorrent|[bee](tcllib/files/modules/bee/bee.md)|
|<a name='blanks'></a>blanks|[textutil::repeat](tcllib/files/modules/textutil/repeat.md)|
|<a name='block_cipher'></a>block cipher|[aes](tcllib/files/modules/aes/aes.md) · [blowfish](tcllib/files/modules/blowfish/blowfish.md) · [des](tcllib/files/modules/des/des.md) · [tclDES](tcllib/files/modules/des/tcldes.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr.md)|
|<a name='blocking_flow'></a>blocking flow|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='blowfish'></a>blowfish|[blowfish](tcllib/files/modules/blowfish/blowfish.md)|
|<a name='book_number'></a>Book Number|[valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='breadth_first'></a>breadth-first|[struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='bridge'></a>bridge|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='bwidget'></a>BWidget|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md)|
#### <a name='cC'></a>Keywords: C
|||
|---|---|
|<a name='c'></a>C|[doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md)|
|<a name='c_'></a>C++|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md) · [stooop](tcllib/files/modules/stooop/stooop.md) · [switched](tcllib/files/modules/stooop/switched.md)|
|<a name='cache'></a>cache|[cache::async](tcllib/files/modules/cache/async.md) · [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md)|
|<a name='caesar_cipher'></a>caesar cipher|[tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md)|
|<a name='calculus'></a>calculus|[math::calculus](tcllib/files/modules/math/calculus.md)|
|<a name='callback'></a>callback|[cache::async](tcllib/files/modules/cache/async.md) · [hook](tcllib/files/modules/hook/hook.md) · [lambda](tcllib/files/modules/lambda/lambda.md) · [oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md) · [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md)|
|<a name='callbacks'></a>callbacks|[tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md)|
|<a name='capitalize'></a>capitalize|[textutil::string](tcllib/files/modules/textutil/textutil_string.md)|
|<a name='card_for_credit'></a>card for credit|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md)|
|<a name='cardinality'></a>cardinality|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='cat'></a>cat|[fileutil](tcllib/files/modules/fileutil/fileutil.md)|
|<a name='catalog_package'></a>catalog package|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='catalogue'></a>catalogue|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md)|
|<a name='cell_phone'></a>cell-phone|[valtype::imei](tcllib/files/modules/valtype/imei.md)|
|<a name='cer'></a>cer|[asn](tcllib/files/modules/asn/asn.md)|
|<a name='cfg'></a>CFG|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md)|
|<a name='cfl'></a>CFL|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md)|
|<a name='cgi'></a>CGI|[ncgi](tcllib/files/modules/ncgi/ncgi.md)|
|<a name='cgraph'></a>cgraph|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph_v1](tcllib/files/modules/struct/graph1.md)|
|<a name='changelog'></a>changelog|[doctools::changelog](tcllib/files/modules/doctools/changelog.md) · [doctools::cvs](tcllib/files/modules/doctools/cvs.md)|
|<a name='channel'></a>channel|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) · [transfer::connect](tcllib/files/modules/transfer/connect.md) · [transfer::copy](tcllib/files/modules/transfer/copyops.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) · [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) · [transfer::data::source](tcllib/files/modules/transfer/dsource.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='channel_transformation'></a>channel transformation|[tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='character_input'></a>character input|[term::receive](tcllib/files/modules/term/receive.md) · [term::receive::bind](tcllib/files/modules/term/term_bind.md)|
|<a name='character_output'></a>character output|[term::ansi::send](tcllib/files/modules/term/ansi_send.md) · [term::send](tcllib/files/modules/term/term_send.md)|
|<a name='chat'></a>chat|[irc](tcllib/files/modules/irc/irc.md) · [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) · [picoirc](tcllib/files/modules/irc/picoirc.md)|
|<a name='checkbox'></a>checkbox|[html](tcllib/files/modules/html/html.md) · [javascript](tcllib/files/modules/javascript/javascript.md)|
|<a name='checkbutton'></a>checkbutton|[html](tcllib/files/modules/html/html.md)|
|<a name='checking'></a>Checking|[valtype::common](tcllib/files/modules/valtype/valtype_common.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md) · [valtype::imei](tcllib/files/modules/valtype/imei.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
|<a name='checksum'></a>checksum|[cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [sum](tcllib/files/modules/crc/sum.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md)|
|<a name='chop'></a>chop|[textutil::string](tcllib/files/modules/textutil/textutil_string.md)|
|<a name='cipher'></a>cipher|[pki](tcllib/files/modules/pki/pki.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md)|
|<a name='cksum'></a>cksum|[cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [sum](tcllib/files/modules/crc/sum.md)|
|<a name='class'></a>class|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md) · [stooop](tcllib/files/modules/stooop/stooop.md) · [switched](tcllib/files/modules/stooop/switched.md)|
|<a name='class_methods'></a>class methods|[oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
|<a name='class_variables'></a>class variables|[oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
|<a name='cleanup'></a>cleanup|[defer](tcllib/files/modules/defer/defer.md) · [try](tcllib/files/modules/try/tcllib_try.md)|
|<a name='client'></a>client|[nameserv](tcllib/files/modules/nns/nns_client.md) · [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) · [nameserv::common](tcllib/files/modules/nns/nns_common.md) · [nns](tcllib/files/apps/nns.md) · [nns_intro](tcllib/files/modules/nns/nns_intro.md) · [nnslog](tcllib/files/apps/nnslog.md)|
|<a name='cloud'></a>cloud|[S3](tcllib/files/modules/amazon-s3/S3.md)|
|<a name='cmdline_processing'></a>cmdline processing|[cmdline](tcllib/files/modules/cmdline/cmdline.md)|
|<a name='color_control'></a>color control|[term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md)|
|<a name='columns'></a>columns|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='comm'></a>comm|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md) · [deleg_method](tcllib/files/modules/interp/deleg_method.md) · [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) · [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md)|
|<a name='command'></a>command|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md)|
|<a name='command_line_processing'></a>command line processing|[cmdline](tcllib/files/modules/cmdline/cmdline.md)|
|<a name='command_prefix'></a>command prefix|[lambda](tcllib/files/modules/lambda/lambda.md) · [oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
|<a name='comment'></a>comment|[jpeg](tcllib/files/modules/jpeg/jpeg.md) · [png](tcllib/files/modules/png/png.md)|
|<a name='common'></a>common|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='common_prefix'></a>common prefix|[textutil::string](tcllib/files/modules/textutil/textutil_string.md)|
|<a name='communication'></a>communication|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md)|
|<a name='comparison'></a>comparison|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='complete_graph'></a>complete graph|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='complex_numbers'></a>complex numbers|[math::complexnumbers](tcllib/files/modules/math/qcomplex.md) · [math::fourier](tcllib/files/modules/math/fourier.md)|
|<a name='compression'></a>compression|[tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) · [zipfile::encode](tcllib/files/modules/zip/encode.md)|
|<a name='computations'></a>computations|[math::bigfloat](tcllib/files/modules/math/bigfloat.md)|
|<a name='concatenation_channel'></a>concatenation channel|[tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md)|
|<a name='connected_component'></a>connected component|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='connected_fifos'></a>connected fifos|[tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md)|
|<a name='connection'></a>connection|[transfer::connect](tcllib/files/modules/transfer/connect.md)|
|<a name='constants'></a>constants|[math::constants](tcllib/files/modules/math/constants.md) · [units](tcllib/files/modules/units/units.md)|
|<a name='container'></a>CONTAINER|[pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md)|
|<a name='contents'></a>contents|[doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md)|
|<a name='context_free_grammar'></a>context-free grammar|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md)|
|<a name='context_free_languages'></a>context-free languages|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='control'></a>control|[control](tcllib/files/modules/control/control.md) · [term](tcllib/files/modules/term/term.md) · [term::ansi::code](tcllib/files/modules/term/ansi_code.md) · [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) · [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) · [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) · [term::ansi::send](tcllib/files/modules/term/ansi_send.md) · [term::interact::menu](tcllib/files/modules/term/imenu.md) · [term::interact::pager](tcllib/files/modules/term/ipager.md) · [term::receive](tcllib/files/modules/term/receive.md) · [term::receive::bind](tcllib/files/modules/term/term_bind.md) · [term::send](tcllib/files/modules/term/term_send.md)|
|<a name='control_structure'></a>control structure|[generator](tcllib/files/modules/generator/generator.md)|
|<a name='conversion'></a>conversion|[doctools](tcllib/files/modules/doctools/doctools.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md) · [math::roman](tcllib/files/modules/math/roman.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md) · [units](tcllib/files/modules/units/units.md)|
|<a name='cooked'></a>cooked|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='cookie'></a>cookie|[ncgi](tcllib/files/modules/ncgi/ncgi.md)|
|<a name='copy'></a>copy|[fileutil::multi](tcllib/files/modules/fileutil/multi.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) · [transfer::copy](tcllib/files/modules/transfer/copyops.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) · [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) · [transfer::data::source](tcllib/files/modules/transfer/dsource.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='coroutine'></a>coroutine|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) · [generator](tcllib/files/modules/generator/generator.md)|
|<a name='cost'></a>Cost|[treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='counter'></a>counter|[tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md)|
|<a name='counting'></a>counting|[counter](tcllib/files/modules/counter/counter.md)|
|<a name='cparam'></a>CPARAM|[pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md)|
|<a name='crc'></a>crc|[cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [sum](tcllib/files/modules/crc/sum.md)|
|<a name='crc16'></a>crc16|[crc16](tcllib/files/modules/crc/crc16.md)|
|<a name='crc32'></a>crc32|[cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [sum](tcllib/files/modules/crc/sum.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md)|
|<a name='credit_card'></a>credit card|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md)|
|<a name='cron'></a>cron|[cron](tcllib/files/modules/cron/cron.md)|
|<a name='cryptography'></a>cryptography|[blowfish](tcllib/files/modules/blowfish/blowfish.md)|
|<a name='css'></a>CSS|[doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md)|
|<a name='csv'></a>csv|[bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) · [csv](tcllib/files/modules/csv/csv.md)|
|<a name='currying'></a>currying|[lambda](tcllib/files/modules/lambda/lambda.md) · [oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
|<a name='cut_edge'></a>cut edge|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='cut_vertex'></a>cut vertex|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='cvs'></a>CVS|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='cvs'></a>cvs|[doctools::cvs](tcllib/files/modules/doctools/cvs.md)|
|<a name='cvs_log'></a>cvs log|[doctools::cvs](tcllib/files/modules/doctools/cvs.md)|
|<a name='cyclic_redundancy_check'></a>cyclic redundancy check|[cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [sum](tcllib/files/modules/crc/sum.md)|
#### <a name='cD'></a>Keywords: D
|||
|---|---|
|<a name='data_analysis'></a>data analysis|[math::statistics](tcllib/files/modules/math/statistics.md)|
|<a name='data_destination'></a>data destination|[transfer::data::destination](tcllib/files/modules/transfer/ddest.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md)|
|<a name='data_entry_form'></a>data entry form|[tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md)|
|<a name='data_exchange'></a>data exchange|[huddle](tcllib/files/modules/yaml/huddle.md) · [json](tcllib/files/modules/json/json.md) · [json::write](tcllib/files/modules/json/json_write.md) · [yaml](tcllib/files/modules/yaml/yaml.md)|
|<a name='data_integrity'></a>data integrity|[aes](tcllib/files/modules/aes/aes.md) · [cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [des](tcllib/files/modules/des/des.md) · [pki](tcllib/files/modules/pki/pki.md) · [rc4](tcllib/files/modules/rc4/rc4.md) · [sum](tcllib/files/modules/crc/sum.md) · [tclDES](tcllib/files/modules/des/tcldes.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr.md)|
|<a name='data_source'></a>data source|[transfer::data::source](tcllib/files/modules/transfer/dsource.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='data_structures'></a>data structures|[struct::record](tcllib/files/modules/struct/record.md)|
|<a name='database'></a>database|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md)|
|<a name='dataflow'></a>dataflow|[page_util_flow](tcllib/files/modules/page/page_util_flow.md)|
|<a name='_ddt'></a>.ddt|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md)|
|<a name='de'></a>DE|[doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md)|
|<a name='debug'></a>debug|[debug](tcllib/files/modules/debug/debug.md) · [debug::caller](tcllib/files/modules/debug/debug_caller.md) · [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) · [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md)|
|<a name='decimal'></a>decimal|[math::decimal](tcllib/files/modules/math/decimal.md)|
|<a name='declare'></a>declare|[term::ansi::code](tcllib/files/modules/term/ansi_code.md)|
|<a name='decompression'></a>decompression|[tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) · [zipfile::decode](tcllib/files/modules/zip/decode.md) · [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md)|
|<a name='decryption'></a>decryption|[tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md)|
|<a name='deferal'></a>deferal|[uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md)|
|<a name='define'></a>define|[term::ansi::code](tcllib/files/modules/term/ansi_code.md)|
|<a name='degree'></a>degree|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='degree_constrained_spanning_tree'></a>degree constrained spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='degrees'></a>degrees|[math::constants](tcllib/files/modules/math/constants.md)|
|<a name='delegation'></a>delegation|[deleg_method](tcllib/files/modules/interp/deleg_method.md) · [deleg_proc](tcllib/files/modules/interp/deleg_proc.md)|
|<a name='depth_first'></a>depth-first|[struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='der'></a>der|[asn](tcllib/files/modules/asn/asn.md)|
|<a name='des'></a>DES|[des](tcllib/files/modules/des/des.md) · [tclDES](tcllib/files/modules/des/tcldes.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr.md)|
|<a name='deserialization'></a>deserialization|[doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md)|
|<a name='_dev_null'></a>/dev/null|[tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md)|
|<a name='_dev_random'></a>/dev/random|[tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) · [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md)|
|<a name='_dev_zero'></a>/dev/zero|[tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md)|
|<a name='diameter'></a>diameter|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='dict'></a>dict|[dicttool](tcllib/files/modules/dicttool/dicttool.md)|
|<a name='diff'></a>diff|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='diff_n_format'></a>diff -n format|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='difference'></a>difference|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='differential'></a>differential|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='differential_equations'></a>differential equations|[math::calculus](tcllib/files/modules/math/calculus.md)|
|<a name='dijkstra'></a>dijkstra|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='directory_access'></a>directory access|[ldap](tcllib/files/modules/ldap/ldap.md) · [ldapx](tcllib/files/modules/ldap/ldapx.md)|
|<a name='directory_traversal'></a>directory traversal|[fileutil_traverse](tcllib/files/modules/fileutil/traverse.md)|
|<a name='discover'></a>Discover|[valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md)|
|<a name='discrete_items'></a>discrete items|[struct::pool](tcllib/files/modules/struct/pool.md)|
|<a name='disjoint_set'></a>disjoint set|[struct::disjointset](tcllib/files/modules/struct/disjointset.md)|
|<a name='dispatcher'></a>dispatcher|[term::receive::bind](tcllib/files/modules/term/term_bind.md)|
|<a name='distance'></a>distance|[math::geometry](tcllib/files/modules/math/math_geometry.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md) · [units](tcllib/files/modules/units/units.md)|
|<a name='dns'></a>DNS|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='do'></a>do|[control](tcllib/files/modules/control/control.md)|
|<a name='docidx'></a>docidx|[doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) · [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) · [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md)|
|<a name='docidx_commands'></a>docidx commands|[docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) · [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) · [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md)|
|<a name='docidx_language'></a>docidx language|[docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) · [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) · [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md)|
|<a name='docidx_markup'></a>docidx markup|[docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) · [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) · [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md)|
|<a name='docidx_syntax'></a>docidx syntax|[docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) · [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md)|
|<a name='docstrip'></a>docstrip|[docstrip](tcllib/files/modules/docstrip/docstrip.md) · [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md)|
|<a name='doctoc'></a>doctoc|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md)|
|<a name='doctoc_commands'></a>doctoc commands|[doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) · [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md)|
|<a name='doctoc_language'></a>doctoc language|[doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) · [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md)|
|<a name='doctoc_markup'></a>doctoc markup|[doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) · [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md)|
|<a name='doctoc_syntax'></a>doctoc syntax|[doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) · [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md)|
|<a name='doctools'></a>doctools|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [doctools::changelog](tcllib/files/modules/doctools/changelog.md) · [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) · [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) · [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) · [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) · [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md)|
|<a name='doctools_commands'></a>doctools commands|[doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) · [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) · [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md)|
|<a name='doctools_language'></a>doctools language|[doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) · [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) · [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md)|
|<a name='doctools_markup'></a>doctools markup|[doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) · [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) · [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md)|
|<a name='doctools_syntax'></a>doctools syntax|[doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) · [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) · [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md)|
|<a name='document'></a>document|[doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md)|
|<a name='documentation'></a>documentation|[docstrip](tcllib/files/modules/docstrip/docstrip.md) · [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [doctools](tcllib/files/modules/doctools/doctools.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md) · [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md)|
|<a name='dom'></a>DOM|[treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='dom'></a>dom|[xsxp](tcllib/files/modules/amazon-s3/xsxp.md)|
|<a name='domain_name_service'></a>domain name service|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='_dtx'></a>.dtx|[docstrip](tcllib/files/modules/docstrip/docstrip.md) · [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md)|
#### <a name='cE'></a>Keywords: E
|||
|---|---|
|<a name='e'></a>e|[math::constants](tcllib/files/modules/math/constants.md)|
|<a name='ean'></a>EAN|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='ean13'></a>EAN13|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='earley'></a>earley|[grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md)|
|<a name='ebnf'></a>EBNF|[pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='eccentricity'></a>eccentricity|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='edge'></a>edge|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='emacs'></a>emacs|[doctools::changelog](tcllib/files/modules/doctools/changelog.md) · [doctools::cvs](tcllib/files/modules/doctools/cvs.md)|
|<a name='email'></a>email|[imap4](tcllib/files/modules/imap4/imap4.md) · [mime](tcllib/files/modules/mime/mime.md) · [pop3](tcllib/files/modules/pop3/pop3.md) · [smtp](tcllib/files/modules/mime/smtp.md)|
|<a name='emptiness'></a>emptiness|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='empty_interpreter'></a>empty interpreter|[interp](tcllib/files/modules/interp/tcllib_interp.md)|
|<a name='en'></a>EN|[doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md)|
|<a name='encoding'></a>encoding|[ascii85](tcllib/files/modules/base64/ascii85.md) · [base64](tcllib/files/modules/base64/base64.md) · [uuencode](tcllib/files/modules/base64/uuencode.md) · [yencode](tcllib/files/modules/base64/yencode.md)|
|<a name='encryption'></a>encryption|[aes](tcllib/files/modules/aes/aes.md) · [blowfish](tcllib/files/modules/blowfish/blowfish.md) · [des](tcllib/files/modules/des/des.md) · [pki](tcllib/files/modules/pki/pki.md) · [rc4](tcllib/files/modules/rc4/rc4.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) · [tclDES](tcllib/files/modules/des/tcldes.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr.md)|
|<a name='entry_mask'></a>entry mask|[tepam](tcllib/files/modules/tepam/tepam_introduction.md)|
|<a name='equal'></a>equal|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='equality'></a>equality|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='equivalence_class'></a>equivalence class|[struct::disjointset](tcllib/files/modules/struct/disjointset.md)|
|<a name='error'></a>error|[throw](tcllib/files/modules/try/tcllib_throw.md) · [try](tcllib/files/modules/try/tcllib_try.md)|
|<a name='error_function'></a>error function|[math::special](tcllib/files/modules/math/special.md)|
|<a name='european_article_number'></a>European Article Number|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='event'></a>event|[hook](tcllib/files/modules/hook/hook.md) · [uevent](tcllib/files/modules/uev/uevent.md) · [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md)|
|<a name='event_management'></a>event management|[tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md)|
|<a name='events'></a>events|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='examples'></a>examples|[bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) · [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md)|
|<a name='exception'></a>exception|[try](tcllib/files/modules/try/tcllib_try.md)|
|<a name='exchange_format'></a>exchange format|[huddle](tcllib/files/modules/yaml/huddle.md) · [json](tcllib/files/modules/json/json.md) · [json::write](tcllib/files/modules/json/json_write.md)|
|<a name='exclusion'></a>exclusion|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='execution'></a>execution|[grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md)|
|<a name='exif'></a>exif|[jpeg](tcllib/files/modules/jpeg/jpeg.md)|
|<a name='exit'></a>exit|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='export'></a>export|[doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) · [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md)|
|<a name='expression'></a>expression|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='extended_namespace'></a>extended namespace|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
#### <a name='cF'></a>Keywords: F
|||
|---|---|
|<a name='faq'></a>faq|[docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md)|
|<a name='fetching_information'></a>fetching information|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='fft'></a>FFT|[math::fourier](tcllib/files/modules/math/fourier.md)|
|<a name='fifo'></a>fifo|[tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md)|
|<a name='file'></a>file|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md) · [uri](tcllib/files/modules/uri/uri.md)|
|<a name='file_recognition'></a>file recognition|[fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md)|
|<a name='file_type'></a>file type|[fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md)|
|<a name='file_utilities'></a>file utilities|[fileutil](tcllib/files/modules/fileutil/fileutil.md) · [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) · [fileutil::multi](tcllib/files/modules/fileutil/multi.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md)|
|<a name='filesystem'></a>filesystem|[map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md)|
|<a name='filter'></a>filter|[generator](tcllib/files/modules/generator/generator.md) · [struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='final'></a>final|[try](tcllib/files/modules/try/tcllib_try.md)|
|<a name='finance'></a>finance|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md)|
|<a name='find'></a>find|[struct::disjointset](tcllib/files/modules/struct/disjointset.md)|
|<a name='finite'></a>finite|[struct::pool](tcllib/files/modules/struct/pool.md)|
|<a name='finite_automaton'></a>finite automaton|[grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md)|
|<a name='fips_180_1'></a>FIPS 180-1|[sha1](tcllib/files/modules/sha1/sha1.md) · [sha256](tcllib/files/modules/sha1/sha256.md)|
|<a name='first_permutation'></a>first permutation|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='fisher_yates'></a>Fisher-Yates|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='flatten'></a>flatten|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='floating_point'></a>floating-point|[math::bigfloat](tcllib/files/modules/math/bigfloat.md) · [math::fuzzy](tcllib/files/modules/math/fuzzy.md)|
|<a name='flow'></a>flow|[control](tcllib/files/modules/control/control.md)|
|<a name='flow_network'></a>flow network|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='folding'></a>folding|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='foldl'></a>foldl|[generator](tcllib/files/modules/generator/generator.md)|
|<a name='foldr'></a>foldr|[generator](tcllib/files/modules/generator/generator.md)|
|<a name='foreach'></a>foreach|[generator](tcllib/files/modules/generator/generator.md)|
|<a name='form'></a>form|[html](tcllib/files/modules/html/html.md) · [ncgi](tcllib/files/modules/ncgi/ncgi.md)|
|<a name='format_conversion'></a>format conversion|[pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md)|
|<a name='formatter'></a>formatter|[doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md)|
|<a name='formatting'></a>formatting|[bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) · [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust.md) · [textutil::string](tcllib/files/modules/textutil/textutil_string.md) · [textutil::tabify](tcllib/files/modules/textutil/tabify.md)|
|<a name='formatting_engine'></a>formatting engine|[docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) · [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) · [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md)|
|<a name='fourier_transform'></a>Fourier transform|[math::fourier](tcllib/files/modules/math/fourier.md)|
|<a name='fr'></a>FR|[doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='frame'></a>frame|[term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md)|
|<a name='framework'></a>framework|[tool](tcllib/files/modules/tool/tool.md)|
|<a name='ftp'></a>ftp|[ftp](tcllib/files/modules/ftp/ftp.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) · [ftpd](tcllib/files/modules/ftpd/ftpd.md) · [uri](tcllib/files/modules/uri/uri.md)|
|<a name='ftpd'></a>ftpd|[ftpd](tcllib/files/modules/ftpd/ftpd.md)|
|<a name='ftpserver'></a>ftpserver|[ftpd](tcllib/files/modules/ftpd/ftpd.md)|
|<a name='full_outer_join'></a>full outer join|[struct::list](tcllib/files/modules/struct/struct_list.md)|
#### <a name='cG'></a>Keywords: G
|||
|---|---|
|<a name='generate_event'></a>generate event|[uevent](tcllib/files/modules/uev/uevent.md)|
|<a name='generate_permutations'></a>generate permutations|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='generation'></a>generation|[doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md)|
|<a name='generator'></a>generator|[generator](tcllib/files/modules/generator/generator.md)|
|<a name='geocoding'></a>geocoding|[map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md)|
|<a name='geodesy'></a>geodesy|[map::slippy](tcllib/files/modules/map/map_slippy.md) · [mapproj](tcllib/files/modules/mapproj/mapproj.md)|
|<a name='geography'></a>geography|[map::slippy](tcllib/files/modules/map/map_slippy.md)|
|<a name='get_character'></a>get character|[term::receive](tcllib/files/modules/term/receive.md)|
|<a name='gets'></a>gets|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='global'></a>global|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='golang'></a>golang|[defer](tcllib/files/modules/defer/defer.md)|
|<a name='gopher'></a>gopher|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='gps'></a>gps|[gpx](tcllib/files/modules/gpx/gpx.md) · [nmea](tcllib/files/modules/nmea/nmea.md)|
|<a name='gpx'></a>gpx|[gpx](tcllib/files/modules/gpx/gpx.md)|
|<a name='grammar'></a>grammar|[grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) · [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) · [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) · [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) · [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) · [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) · [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='graph'></a>graph|[grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) · [struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md) · [struct::graph_v1](tcllib/files/modules/struct/graph1.md) · [struct::queue](tcllib/files/modules/struct/queue.md) · [struct::stack](tcllib/files/modules/struct/stack.md)|
|<a name='graph_walking'></a>graph walking|[page_util_flow](tcllib/files/modules/page/page_util_flow.md) · [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md)|
|<a name='green_threads'></a>green threads|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='grep'></a>grep|[fileutil](tcllib/files/modules/fileutil/fileutil.md)|
|<a name='guid'></a>GUID|[uuid](tcllib/files/modules/uuid/uuid.md)|
#### <a name='cH'></a>Keywords: H
|||
|---|---|
|<a name='hashing'></a>hashing|[md4](tcllib/files/modules/md4/md4.md) · [md5](tcllib/files/modules/md5/md5.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) · [otp](tcllib/files/modules/otp/otp.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) · [sha1](tcllib/files/modules/sha1/sha1.md) · [sha256](tcllib/files/modules/sha1/sha256.md)|
|<a name='heartbeat'></a>heartbeat|[debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md)|
|<a name='heuristic'></a>heuristic|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='hex'></a>hex|[base32::hex](tcllib/files/modules/base32/base32hex.md)|
|<a name='hexadecimal'></a>hexadecimal|[tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md)|
|<a name='histogram'></a>histogram|[counter](tcllib/files/modules/counter/counter.md)|
|<a name='hook'></a>hook|[hook](tcllib/files/modules/hook/hook.md) · [uevent](tcllib/files/modules/uev/uevent.md)|
|<a name='horspool'></a>horspool|[grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md)|
|<a name='html'></a>HTML|[doctools](tcllib/files/modules/doctools/doctools.md) · [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand.md)|
|<a name='html'></a>html|[html](tcllib/files/modules/html/html.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) · [javascript](tcllib/files/modules/javascript/javascript.md) · [ncgi](tcllib/files/modules/ncgi/ncgi.md)|
|<a name='http'></a>http|[autoproxy](tcllib/files/modules/http/autoproxy.md) · [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) · [tool](tcllib/files/modules/httpd/httpd.md) · [uri](tcllib/files/modules/uri/uri.md) · [websocket](tcllib/files/modules/websocket/websocket.md)|
|<a name='httpd'></a>httpd|[tool](tcllib/files/modules/httpd/httpd.md)|
|<a name='https'></a>https|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='httpserver'></a>httpserver|[tool](tcllib/files/modules/httpd/httpd.md)|
|<a name='huddle'></a>huddle|[huddle](tcllib/files/modules/yaml/huddle.md) · [yaml](tcllib/files/modules/yaml/yaml.md)|
|<a name='human_readable'></a>human readable|[bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::text](tcllib/files/modules/bench/bench_wtext.md)|
|<a name='hyphenation'></a>hyphenation|[textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
#### <a name='cI'></a>Keywords: I
|||
|---|---|
|<a name='i18n'></a>i18n|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='iban'></a>IBAN|[valtype::iban](tcllib/files/modules/valtype/iban.md)|
|<a name='ident'></a>ident|[ident](tcllib/files/modules/ident/ident.md)|
|<a name='identification'></a>identification|[ident](tcllib/files/modules/ident/ident.md)|
|<a name='identity'></a>identity|[tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md)|
|<a name='idle'></a>idle|[uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md)|
|<a name='image'></a>image|[jpeg](tcllib/files/modules/jpeg/jpeg.md) · [png](tcllib/files/modules/png/png.md) · [tiff](tcllib/files/modules/tiff/tiff.md)|
|<a name='imap'></a>imap|[imap4](tcllib/files/modules/imap4/imap4.md)|
|<a name='imei'></a>IMEI|[valtype::imei](tcllib/files/modules/valtype/imei.md)|
|<a name='import'></a>import|[doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md)|
|<a name='in_memory_channel'></a>in-memory channel|[tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) · [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md)|
|<a name='in_order'></a>in-order|[struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='inclusion'></a>inclusion|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='incr_tcl'></a>Incr Tcl|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md)|
|<a name='indenting'></a>indenting|[textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
|<a name='independent_set'></a>independent set|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='index'></a>index|[docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) · [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md)|
|<a name='index_formatter'></a>index formatter|[docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md)|
|<a name='info'></a>info|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
|<a name='inner_join'></a>inner join|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='input_mode'></a>input mode|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='integer'></a>integer|[math::roman](tcllib/files/modules/math/roman.md)|
|<a name='integration'></a>integration|[math::calculus](tcllib/files/modules/math/calculus.md)|
|<a name='inter_thread_communication'></a>inter-thread communication|[tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md)|
|<a name='international_article_number'></a>International Article Number|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='international_bank_account_number'></a>International Bank Account Number|[valtype::iban](tcllib/files/modules/valtype/iban.md)|
|<a name='international_mobile_equipment_identity'></a>International Mobile Equipment Identity|[valtype::imei](tcllib/files/modules/valtype/imei.md)|
|<a name='international_standard_book_number'></a>International Standard Book Number|[valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='internationalization'></a>internationalization|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='internet'></a>internet|[asn](tcllib/files/modules/asn/asn.md) · [ftp](tcllib/files/modules/ftp/ftp.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) · [imap4](tcllib/files/modules/imap4/imap4.md) · [ldap](tcllib/files/modules/ldap/ldap.md) · [ldapx](tcllib/files/modules/ldap/ldapx.md) · [mime](tcllib/files/modules/mime/mime.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) · [smtp](tcllib/files/modules/mime/smtp.md) · [websocket](tcllib/files/modules/websocket/websocket.md)|
|<a name='internet_address'></a>internet address|[tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md)|
|<a name='interpolation'></a>interpolation|[math::interpolate](tcllib/files/modules/math/interpolate.md)|
|<a name='interpreter'></a>interpreter|[deleg_method](tcllib/files/modules/interp/deleg_method.md) · [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) · [interp](tcllib/files/modules/interp/tcllib_interp.md) · [wip](tcllib/files/modules/wip/wip.md)|
|<a name='intersection'></a>intersection|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='interval'></a>interval|[math::bigfloat](tcllib/files/modules/math/bigfloat.md)|
|<a name='ip'></a>ip|[tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md)|
|<a name='ipc'></a>ipc|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md)|
|<a name='ipv4'></a>ipv4|[tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md)|
|<a name='ipv6'></a>ipv6|[tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md)|
|<a name='irc'></a>irc|[irc](tcllib/files/modules/irc/irc.md) · [picoirc](tcllib/files/modules/irc/picoirc.md)|
|<a name='isa'></a>isA|[valtype::common](tcllib/files/modules/valtype/valtype_common.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md) · [valtype::imei](tcllib/files/modules/valtype/imei.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
|<a name='isbn'></a>ISBN|[valtype::isbn](tcllib/files/modules/valtype/isbn.md)|
|<a name='isthmus'></a>isthmus|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='iterator'></a>iterator|[generator](tcllib/files/modules/generator/generator.md)|
#### <a name='cJ'></a>Keywords: J
|||
|---|---|
|<a name='javascript'></a>javascript|[javascript](tcllib/files/modules/javascript/javascript.md) · [json](tcllib/files/modules/json/json.md) · [json::write](tcllib/files/modules/json/json_write.md)|
|<a name='jfif'></a>jfif|[jpeg](tcllib/files/modules/jpeg/jpeg.md)|
|<a name='join'></a>join|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='jpeg'></a>jpeg|[jpeg](tcllib/files/modules/jpeg/jpeg.md)|
|<a name='json'></a>JSON|[doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md)|
|<a name='json'></a>json|[doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [huddle](tcllib/files/modules/yaml/huddle.md) · [json](tcllib/files/modules/json/json.md) · [json::write](tcllib/files/modules/json/json_write.md)|
|<a name='justification'></a>justification|[textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
#### <a name='cK'></a>Keywords: K
|||
|---|---|
|<a name='keyword_index'></a>keyword index|[docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md)|
|<a name='keywords'></a>keywords|[docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md)|
|<a name='knuth'></a>knuth|[soundex](tcllib/files/modules/soundex/soundex.md)|
#### <a name='cL'></a>Keywords: L
|||
|---|---|
|<a name='l10n'></a>l10n|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='lambda'></a>lambda|[lambda](tcllib/files/modules/lambda/lambda.md)|
|<a name='latex'></a>LaTeX|[docstrip](tcllib/files/modules/docstrip/docstrip.md) · [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md)|
|<a name='latex'></a>latex|[doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md)|
|<a name='latitute'></a>latitute|[map::slippy](tcllib/files/modules/map/map_slippy.md)|
|<a name='ldap'></a>ldap|[ldap](tcllib/files/modules/ldap/ldap.md) · [ldapx](tcllib/files/modules/ldap/ldapx.md) · [uri](tcllib/files/modules/uri/uri.md)|
|<a name='ldap_client'></a>ldap client|[ldap](tcllib/files/modules/ldap/ldap.md) · [ldapx](tcllib/files/modules/ldap/ldapx.md)|
|<a name='ldif'></a>ldif|[ldapx](tcllib/files/modules/ldap/ldapx.md)|
|<a name='least_squares'></a>least squares|[math::linearalgebra](tcllib/files/modules/math/linalg.md)|
|<a name='left_outer_join'></a>left outer join|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='lemon'></a>lemon|[page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md)|
|<a name='level_graph'></a>level graph|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='lexer'></a>lexer|[doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md)|
|<a name='lexing'></a>lexing|[string::token](tcllib/files/modules/string/token.md) · [string::token::shell](tcllib/files/modules/string/token_shell.md)|
|<a name='limitsize'></a>limitsize|[tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md)|
|<a name='line'></a>line|[math::geometry](tcllib/files/modules/math/math_geometry.md)|
|<a name='linear_algebra'></a>linear algebra|[math::linearalgebra](tcllib/files/modules/math/linalg.md)|
|<a name='linear_equations'></a>linear equations|[math::linearalgebra](tcllib/files/modules/math/linalg.md)|
|<a name='linear_program'></a>linear program|[math::optimize](tcllib/files/modules/math/optimize.md)|
|<a name='lines'></a>lines|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='list'></a>list|[struct::list](tcllib/files/modules/struct/struct_list.md) · [struct::queue](tcllib/files/modules/struct/queue.md) · [wip](tcllib/files/modules/wip/wip.md)|
|<a name='listener'></a>listener|[term::receive](tcllib/files/modules/term/receive.md) · [term::receive::bind](tcllib/files/modules/term/term_bind.md)|
|<a name='literate_programming'></a>literate programming|[docstrip](tcllib/files/modules/docstrip/docstrip.md) · [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md)|
|<a name='ll_k_'></a>LL(k)|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='local_searching'></a>local searching|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='localization'></a>localization|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='location'></a>location|[map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) · [map::slippy](tcllib/files/modules/map/map_slippy.md) · [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md)|
|<a name='log'></a>log|[debug](tcllib/files/modules/debug/debug.md) · [debug::caller](tcllib/files/modules/debug/debug_caller.md) · [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) · [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) · [doctools::cvs](tcllib/files/modules/doctools/cvs.md) · [log](tcllib/files/modules/log/log.md) · [logger](tcllib/files/modules/log/logger.md)|
|<a name='log_level'></a>log level|[log](tcllib/files/modules/log/log.md) · [logger](tcllib/files/modules/log/logger.md)|
|<a name='logger'></a>logger|[logger](tcllib/files/modules/log/logger.md) · [logger::appender](tcllib/files/modules/log/loggerAppender.md) · [logger::utils](tcllib/files/modules/log/loggerUtils.md)|
|<a name='longest_common_subsequence'></a>longest common subsequence|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='longitude'></a>longitude|[map::slippy](tcllib/files/modules/map/map_slippy.md)|
|<a name='loop'></a>loop|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='luhn'></a>luhn|[valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md)|
|<a name='luhn_5'></a>luhn-5|[valtype::luhn5](tcllib/files/modules/valtype/luhn5.md)|
#### <a name='cM'></a>Keywords: M
|||
|---|---|
|<a name='macros'></a>macros|[doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md)|
|<a name='mail'></a>mail|[imap4](tcllib/files/modules/imap4/imap4.md) · [mime](tcllib/files/modules/mime/mime.md) · [pop3](tcllib/files/modules/pop3/pop3.md) · [smtp](tcllib/files/modules/mime/smtp.md)|
|<a name='mailto'></a>mailto|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='man_macros'></a>man_macros|[doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md)|
|<a name='manpage'></a>manpage|[doctools](tcllib/files/modules/doctools/doctools.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand.md)|
|<a name='map'></a>map|[generator](tcllib/files/modules/generator/generator.md) · [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) · [map::slippy](tcllib/files/modules/map/map_slippy.md) · [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) · [mapproj](tcllib/files/modules/mapproj/mapproj.md) · [struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='markup'></a>markup|[docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) · [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) · [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) · [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) · [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) · [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) · [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) · [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) · [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) · [doctools](tcllib/files/modules/doctools/doctools.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) · [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) · [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) · [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) · [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md)|
|<a name='mastercard'></a>MasterCard|[valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md)|
|<a name='matching'></a>matching|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='math'></a>math|[math](tcllib/files/modules/math/math.md) · [math::bigfloat](tcllib/files/modules/math/bigfloat.md) · [math::bignum](tcllib/files/modules/math/bignum.md) · [math::calculus](tcllib/files/modules/math/calculus.md) · [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) · [math::constants](tcllib/files/modules/math/constants.md) · [math::decimal](tcllib/files/modules/math/decimal.md) · [math::fuzzy](tcllib/files/modules/math/fuzzy.md) · [math::geometry](tcllib/files/modules/math/math_geometry.md) · [math::interpolate](tcllib/files/modules/math/interpolate.md) · [math::linearalgebra](tcllib/files/modules/math/linalg.md) · [math::optimize](tcllib/files/modules/math/optimize.md) · [math::PCA](tcllib/files/modules/math/pca.md) · [math::polynomials](tcllib/files/modules/math/polynomials.md) · [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) · [math::special](tcllib/files/modules/math/special.md) · [math::trig](tcllib/files/modules/math/trig.md) · [simulation::annealing](tcllib/files/modules/simulation/annealing.md) · [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) · [simulation::random](tcllib/files/modules/simulation/simulation_random.md)|
|<a name='mathematics'></a>mathematics|[math::fourier](tcllib/files/modules/math/fourier.md) · [math::statistics](tcllib/files/modules/math/statistics.md)|
|<a name='matrices'></a>matrices|[math::linearalgebra](tcllib/files/modules/math/linalg.md)|
|<a name='matrix'></a>matrix|[csv](tcllib/files/modules/csv/csv.md) · [math::linearalgebra](tcllib/files/modules/math/linalg.md) · [report](tcllib/files/modules/report/report.md) · [struct::matrix](tcllib/files/modules/struct/matrix.md) · [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) · [struct::queue](tcllib/files/modules/struct/queue.md) · [struct::stack](tcllib/files/modules/struct/stack.md)|
|<a name='max_cut'></a>max cut|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='maximum'></a>maximum|[math::optimize](tcllib/files/modules/math/optimize.md)|
|<a name='maximum_flow'></a>maximum flow|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='md4'></a>md4|[md4](tcllib/files/modules/md4/md4.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md)|
|<a name='md5'></a>md5|[md5](tcllib/files/modules/md5/md5.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md)|
|<a name='md5crypt'></a>md5crypt|[md5crypt](tcllib/files/modules/md5crypt/md5crypt.md)|
|<a name='medicare'></a>medicare|[valtype::usnpi](tcllib/files/modules/valtype/usnpi.md)|
|<a name='mega_widget'></a>mega widget|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md)|
|<a name='membership'></a>membership|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='menu'></a>menu|[term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) · [term::interact::menu](tcllib/files/modules/term/imenu.md)|
|<a name='merge'></a>merge|[tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) · [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md)|
|<a name='merge_find'></a>merge find|[struct::disjointset](tcllib/files/modules/struct/disjointset.md)|
|<a name='merging'></a>merging|[bench](tcllib/files/modules/bench/bench.md)|
|<a name='message'></a>message|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md) · [log](tcllib/files/modules/log/log.md)|
|<a name='message_catalog'></a>message catalog|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='message_level'></a>message level|[log](tcllib/files/modules/log/log.md)|
|<a name='message_package'></a>message package|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md)|
|<a name='message_digest'></a>message-digest|[md4](tcllib/files/modules/md4/md4.md) · [md5](tcllib/files/modules/md5/md5.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) · [otp](tcllib/files/modules/otp/otp.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) · [sha1](tcllib/files/modules/sha1/sha1.md) · [sha256](tcllib/files/modules/sha1/sha256.md)|
|<a name='metakit'></a>metakit|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md)|
|<a name='method'></a>method|[deleg_method](tcllib/files/modules/interp/deleg_method.md) · [interp](tcllib/files/modules/interp/tcllib_interp.md)|
|<a name='method_reference'></a>method reference|[oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
|<a name='mime'></a>mime|[fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) · [mime](tcllib/files/modules/mime/mime.md) · [smtp](tcllib/files/modules/mime/smtp.md)|
|<a name='minimal_spanning_tree'></a>minimal spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='minimum'></a>minimum|[math::optimize](tcllib/files/modules/math/optimize.md)|
|<a name='minimum_cost_flow'></a>minimum cost flow|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='minimum_degree_spanning_tree'></a>minimum degree spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='minimum_diameter_spanning_tree'></a>minimum diameter spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='mobile_phone'></a>mobile phone|[valtype::imei](tcllib/files/modules/valtype/imei.md)|
|<a name='module'></a>module|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md)|
|<a name='montecarlo_simulation'></a>montecarlo simulation|[simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md)|
|<a name='move'></a>move|[fileutil::multi](tcllib/files/modules/fileutil/multi.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md)|
|<a name='multi_file'></a>multi-file|[fileutil::multi](tcllib/files/modules/fileutil/multi.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md)|
|<a name='multiplexer'></a>multiplexer|[multiplexer](tcllib/files/modules/multiplexer/multiplexer.md)|
|<a name='multiprecision'></a>multiprecision|[math::bigfloat](tcllib/files/modules/math/bigfloat.md) · [math::bignum](tcllib/files/modules/math/bignum.md)|
|<a name='my_method'></a>my method|[oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
#### <a name='cN'></a>Keywords: N
|||
|---|---|
|<a name='name_service'></a>name service|[nameserv](tcllib/files/modules/nns/nns_client.md) · [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) · [nameserv::common](tcllib/files/modules/nns/nns_common.md) · [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) · [nameserv::server](tcllib/files/modules/nns/nns_server.md) · [nns](tcllib/files/apps/nns.md) · [nns_intro](tcllib/files/modules/nns/nns_intro.md) · [nnsd](tcllib/files/apps/nnsd.md) · [nnslog](tcllib/files/apps/nnslog.md) · [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md)|
|<a name='namespace_unknown'></a>namespace unknown|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
|<a name='namespace_utilities'></a>namespace utilities|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
|<a name='narrative'></a>narrative|[debug](tcllib/files/modules/debug/debug.md) · [debug::caller](tcllib/files/modules/debug/debug_caller.md) · [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) · [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md)|
|<a name='national_provider_identifier'></a>National Provider Identifier|[valtype::usnpi](tcllib/files/modules/valtype/usnpi.md)|
|<a name='neighbour'></a>neighbour|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='net'></a>net|[ftp](tcllib/files/modules/ftp/ftp.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) · [imap4](tcllib/files/modules/imap4/imap4.md) · [mime](tcllib/files/modules/mime/mime.md) · [smtp](tcllib/files/modules/mime/smtp.md) · [websocket](tcllib/files/modules/websocket/websocket.md)|
|<a name='nettool'></a>nettool|[nettool](tcllib/files/modules/nettool/nettool.md)|
|<a name='network'></a>network|[pop3d](tcllib/files/modules/pop3d/pop3d.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md)|
|<a name='news'></a>news|[nntp](tcllib/files/modules/nntp/nntp.md) · [uri](tcllib/files/modules/uri/uri.md)|
|<a name='next_permutation'></a>next permutation|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='nmea'></a>nmea|[nmea](tcllib/files/modules/nmea/nmea.md)|
|<a name='nntp'></a>nntp|[nntp](tcllib/files/modules/nntp/nntp.md)|
|<a name='nntpclient'></a>nntpclient|[nntp](tcllib/files/modules/nntp/nntp.md)|
|<a name='no_op'></a>no-op|[control](tcllib/files/modules/control/control.md)|
|<a name='node'></a>node|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md) · [struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='nominatim'></a>nominatim|[map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md)|
|<a name='normalization'></a>normalization|[bench](tcllib/files/modules/bench/bench.md) · [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) · [unicode](tcllib/files/modules/stringprep/unicode.md)|
|<a name='npi'></a>NPI|[valtype::usnpi](tcllib/files/modules/valtype/usnpi.md)|
|<a name='nroff'></a>nroff|[doctools](tcllib/files/modules/doctools/doctools.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) · [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand.md)|
|<a name='ntlm'></a>NTLM|[SASL::NTLM](tcllib/files/modules/sasl/ntlm.md)|
|<a name='ntp'></a>NTP|[ntp_time](tcllib/files/modules/ntp/ntp_time.md)|
|<a name='null'></a>null|[tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md)|
|<a name='number_theory'></a>number theory|[math::numtheory](tcllib/files/modules/math/numtheory.md)|
#### <a name='cO'></a>Keywords: O
|||
|---|---|
|<a name='oauth'></a>oauth|[oauth](tcllib/files/modules/oauth/oauth.md)|
|<a name='object'></a>object|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md) · [stooop](tcllib/files/modules/stooop/stooop.md) · [switched](tcllib/files/modules/stooop/switched.md)|
|<a name='object_oriented'></a>object oriented|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md) · [stooop](tcllib/files/modules/stooop/stooop.md) · [switched](tcllib/files/modules/stooop/switched.md)|
|<a name='observer'></a>observer|[hook](tcllib/files/modules/hook/hook.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md)|
|<a name='odie'></a>odie|[cron](tcllib/files/modules/cron/cron.md) · [nettool](tcllib/files/modules/nettool/nettool.md) · [processman](tcllib/files/modules/processman/processman.md)|
|<a name='on_idle'></a>on-idle|[uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md)|
|<a name='one_time_pad'></a>one time pad|[tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md)|
|<a name='optimization'></a>optimization|[math::optimize](tcllib/files/modules/math/optimize.md) · [simulation::annealing](tcllib/files/modules/simulation/annealing.md)|
|<a name='ordered_list'></a>ordered list|[struct::prioqueue](tcllib/files/modules/struct/prioqueue.md)|
|<a name='otp'></a>otp|[tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md)|
|<a name='outer_join'></a>outer join|[struct::list](tcllib/files/modules/struct/struct_list.md)|
#### <a name='cP'></a>Keywords: P
|||
|---|---|
|<a name='package'></a>package|[csv](tcllib/files/modules/csv/csv.md)|
|<a name='package_indexing'></a>package indexing|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md)|
|<a name='page'></a>page|[page_intro](tcllib/files/modules/page/page_intro.md) · [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) · [page_util_flow](tcllib/files/modules/page/page_util_flow.md) · [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) · [page_util_peg](tcllib/files/modules/page/page_util_peg.md) · [page_util_quote](tcllib/files/modules/page/page_util_quote.md)|
|<a name='pager'></a>pager|[term::interact::pager](tcllib/files/modules/term/ipager.md)|
|<a name='paragraph'></a>paragraph|[textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
|<a name='param'></a>PARAM|[pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md)|
|<a name='parameter_entry_form'></a>parameter entry form|[tepam](tcllib/files/modules/tepam/tepam_introduction.md) · [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md)|
|<a name='parser'></a>parser|[doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) · [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) · [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) · [xsxp](tcllib/files/modules/amazon-s3/xsxp.md)|
|<a name='parser_generator'></a>parser generator|[page](tcllib/files/apps/page.md) · [page_intro](tcllib/files/modules/page/page_intro.md) · [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) · [page_util_flow](tcllib/files/modules/page/page_util_flow.md) · [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) · [page_util_peg](tcllib/files/modules/page/page_util_peg.md) · [page_util_quote](tcllib/files/modules/page/page_util_quote.md)|
|<a name='parsing'></a>parsing|[bench::in](tcllib/files/modules/bench/bench_read.md) · [bibtex](tcllib/files/modules/bibtex/bibtex.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) · [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) · [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) · [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) · [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) · [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) · [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) · [huddle](tcllib/files/modules/yaml/huddle.md) · [string::token::shell](tcllib/files/modules/string/token_shell.md) · [yaml](tcllib/files/modules/yaml/yaml.md)|
|<a name='parsing_expression'></a>parsing expression|[grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='parsing_expression_grammar'></a>parsing expression grammar|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [page_util_peg](tcllib/files/modules/page/page_util_peg.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='partial_application'></a>partial application|[lambda](tcllib/files/modules/lambda/lambda.md)|
|<a name='partition'></a>partition|[struct::disjointset](tcllib/files/modules/struct/disjointset.md)|
|<a name='partitioned_set'></a>partitioned set|[struct::disjointset](tcllib/files/modules/struct/disjointset.md)|
|<a name='passive'></a>passive|[transfer::connect](tcllib/files/modules/transfer/connect.md)|
|<a name='password'></a>password|[otp](tcllib/files/modules/otp/otp.md)|
|<a name='patch'></a>patch|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md)|
|<a name='patching'></a>patching|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='pca'></a>PCA|[math::PCA](tcllib/files/modules/math/pca.md)|
|<a name='peg'></a>PEG|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) · [page_util_peg](tcllib/files/modules/page/page_util_peg.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='performance'></a>performance|[bench](tcllib/files/modules/bench/bench.md) · [bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) · [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) · [bench_intro](tcllib/files/modules/bench/bench_intro.md) · [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) · [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) · [profiler](tcllib/files/modules/profiler/profiler.md)|
|<a name='permutation'></a>permutation|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='persistence'></a>persistence|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md)|
|<a name='phone'></a>phone|[valtype::imei](tcllib/files/modules/valtype/imei.md)|
|<a name='pi'></a>pi|[math::constants](tcllib/files/modules/math/constants.md)|
|<a name='plain_text'></a>plain text|[doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md)|
|<a name='plane_geometry'></a>plane geometry|[math::geometry](tcllib/files/modules/math/math_geometry.md)|
|<a name='plugin'></a>plugin|[docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) · [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md)|
|<a name='plugin_management'></a>plugin management|[pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md)|
|<a name='plugin_search'></a>plugin search|[pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md)|
|<a name='png'></a>png|[png](tcllib/files/modules/png/png.md)|
|<a name='point'></a>point|[math::geometry](tcllib/files/modules/math/math_geometry.md)|
|<a name='polynomial_functions'></a>polynomial functions|[math::polynomials](tcllib/files/modules/math/polynomials.md)|
|<a name='pool'></a>pool|[struct::pool](tcllib/files/modules/struct/pool.md) · [struct::queue](tcllib/files/modules/struct/queue.md)|
|<a name='pop'></a>pop|[pop3](tcllib/files/modules/pop3/pop3.md)|
|<a name='pop3'></a>pop3|[pop3](tcllib/files/modules/pop3/pop3.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md)|
|<a name='post_order'></a>post-order|[struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='practcl'></a>practcl|[practcl](tcllib/files/modules/practcl/practcl.md)|
|<a name='pre_order'></a>pre-order|[struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='prefix'></a>prefix|[textutil::string](tcllib/files/modules/textutil/textutil_string.md) · [textutil::trim](tcllib/files/modules/textutil/trim.md)|
|<a name='prime'></a>prime|[math::numtheory](tcllib/files/modules/math/numtheory.md)|
|<a name='prioqueue'></a>prioqueue|[struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) · [struct::queue](tcllib/files/modules/struct/queue.md)|
|<a name='priority_queue'></a>priority queue|[struct::prioqueue](tcllib/files/modules/struct/prioqueue.md)|
|<a name='proc'></a>proc|[lambda](tcllib/files/modules/lambda/lambda.md)|
|<a name='procedure'></a>procedure|[deleg_proc](tcllib/files/modules/interp/deleg_proc.md) · [tepam](tcllib/files/modules/tepam/tepam_introduction.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md)|
|<a name='procedure_documentation'></a>procedure documentation|[tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md)|
|<a name='processman'></a>processman|[processman](tcllib/files/modules/processman/processman.md)|
|<a name='producer'></a>producer|[hook](tcllib/files/modules/hook/hook.md)|
|<a name='profile'></a>profile|[profiler](tcllib/files/modules/profiler/profiler.md)|
|<a name='projection'></a>projection|[mapproj](tcllib/files/modules/mapproj/mapproj.md)|
|<a name='prospero'></a>prospero|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='protocol'></a>protocol|[asn](tcllib/files/modules/asn/asn.md) · [ldap](tcllib/files/modules/ldap/ldap.md) · [ldapx](tcllib/files/modules/ldap/ldapx.md) · [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md)|
|<a name='proxy'></a>proxy|[autoproxy](tcllib/files/modules/http/autoproxy.md)|
|<a name='public_key_cipher'></a>public key cipher|[pki](tcllib/files/modules/pki/pki.md)|
|<a name='publisher'></a>publisher|[hook](tcllib/files/modules/hook/hook.md)|
|<a name='push_down_automaton'></a>push down automaton|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
#### <a name='cQ'></a>Keywords: Q
|||
|---|---|
|<a name='queue'></a>queue|[csv](tcllib/files/modules/csv/csv.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) · [struct::stack](tcllib/files/modules/struct/stack.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md)|
|<a name='quoting'></a>quoting|[page_util_quote](tcllib/files/modules/page/page_util_quote.md)|
#### <a name='cR'></a>Keywords: R
|||
|---|---|
|<a name='radians'></a>radians|[math::constants](tcllib/files/modules/math/constants.md) · [units](tcllib/files/modules/units/units.md)|
|<a name='radiobutton'></a>radiobutton|[html](tcllib/files/modules/html/html.md)|
|<a name='radius'></a>radius|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='random'></a>random|[tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) · [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md)|
|<a name='random_numbers'></a>random numbers|[simulation::random](tcllib/files/modules/simulation/simulation_random.md)|
|<a name='rational_functions'></a>rational functions|[math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md)|
|<a name='raw'></a>raw|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='rc4'></a>rc4|[rc4](tcllib/files/modules/rc4/rc4.md)|
|<a name='rcs'></a>RCS|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='rcs_patch'></a>RCS patch|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='read'></a>read|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='reading'></a>reading|[bench::in](tcllib/files/modules/bench/bench_read.md)|
|<a name='receiver'></a>receiver|[term::receive](tcllib/files/modules/term/receive.md) · [term::receive::bind](tcllib/files/modules/term/term_bind.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md)|
|<a name='reconnect'></a>reconnect|[nameserv::auto](tcllib/files/modules/nns/nns_auto.md)|
|<a name='record'></a>record|[struct::queue](tcllib/files/modules/struct/queue.md) · [struct::record](tcllib/files/modules/struct/record.md)|
|<a name='recursive_descent'></a>recursive descent|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='reduce'></a>reduce|[generator](tcllib/files/modules/generator/generator.md) · [struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='reference'></a>reference|[doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md)|
|<a name='reflected_channel'></a>reflected channel|[tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) · [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) · [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) · [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) · [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) · [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) · [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) · [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) · [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) · [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) · [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='regex'></a>regex|[string::token](tcllib/files/modules/string/token.md)|
|<a name='regular_expression'></a>regular expression|[grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) · [textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::split](tcllib/files/modules/textutil/textutil_split.md) · [textutil::trim](tcllib/files/modules/textutil/trim.md)|
|<a name='regular_grammar'></a>regular grammar|[grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md)|
|<a name='regular_languages'></a>regular languages|[grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md)|
|<a name='remote_communication'></a>remote communication|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md)|
|<a name='remote_execution'></a>remote execution|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md)|
|<a name='remove'></a>remove|[fileutil::multi](tcllib/files/modules/fileutil/multi.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md)|
|<a name='repeating'></a>repeating|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='repetition'></a>repetition|[struct::list](tcllib/files/modules/struct/struct_list.md) · [textutil::repeat](tcllib/files/modules/textutil/repeat.md)|
|<a name='report'></a>report|[report](tcllib/files/modules/report/report.md)|
|<a name='reshuffle'></a>reshuffle|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='residual_graph'></a>residual graph|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='resolver'></a>resolver|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='resource_management'></a>resource management|[try](tcllib/files/modules/try/tcllib_try.md)|
|<a name='restore'></a>restore|[nameserv::auto](tcllib/files/modules/nns/nns_auto.md)|
|<a name='return'></a>return|[throw](tcllib/files/modules/try/tcllib_throw.md)|
|<a name='reverse'></a>reverse|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='rfc_821'></a>rfc 821|[mime](tcllib/files/modules/mime/mime.md) · [smtp](tcllib/files/modules/mime/smtp.md) · [smtpd](tcllib/files/modules/smtpd/smtpd.md)|
|<a name='rfc_822'></a>rfc 822|[mime](tcllib/files/modules/mime/mime.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) · [smtp](tcllib/files/modules/mime/smtp.md)|
|<a name='rfc_868'></a>rfc 868|[ntp_time](tcllib/files/modules/ntp/ntp_time.md)|
|<a name='rfc_959'></a>rfc 959|[ftp](tcllib/files/modules/ftp/ftp.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) · [ftpd](tcllib/files/modules/ftpd/ftpd.md)|
|<a name='rfc_977'></a>rfc 977|[nntp](tcllib/files/modules/nntp/nntp.md)|
|<a name='rfc_1034'></a>rfc 1034|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='rfc_1035'></a>rfc 1035|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='rfc_1036'></a>rfc 1036|[nntp](tcllib/files/modules/nntp/nntp.md)|
|<a name='rfc_1320'></a>rfc 1320|[md4](tcllib/files/modules/md4/md4.md) · [md5](tcllib/files/modules/md5/md5.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md)|
|<a name='rfc_1321'></a>rfc 1321|[md4](tcllib/files/modules/md4/md4.md) · [md5](tcllib/files/modules/md5/md5.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md)|
|<a name='rfc_1413'></a>rfc 1413|[ident](tcllib/files/modules/ident/ident.md)|
|<a name='rfc_1630'></a>rfc 1630|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='rfc_1886'></a>rfc 1886|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='rfc_1939'></a>rfc 1939|[pop3](tcllib/files/modules/pop3/pop3.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md)|
|<a name='rfc_2030'></a>rfc 2030|[ntp_time](tcllib/files/modules/ntp/ntp_time.md)|
|<a name='rfc_2045'></a>rfc 2045|[mime](tcllib/files/modules/mime/mime.md)|
|<a name='rfc_2046'></a>rfc 2046|[mime](tcllib/files/modules/mime/mime.md)|
|<a name='rfc_2049'></a>rfc 2049|[mime](tcllib/files/modules/mime/mime.md)|
|<a name='rfc_2104'></a>rfc 2104|[md4](tcllib/files/modules/md4/md4.md) · [md5](tcllib/files/modules/md5/md5.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) · [sha1](tcllib/files/modules/sha1/sha1.md) · [sha256](tcllib/files/modules/sha1/sha256.md)|
|<a name='rfc_2141'></a>rfc 2141|[uri_urn](tcllib/files/modules/uri/urn-scheme.md)|
|<a name='rfc_2251'></a>rfc 2251|[ldap](tcllib/files/modules/ldap/ldap.md) · [ldapx](tcllib/files/modules/ldap/ldapx.md)|
|<a name='rfc_2255'></a>rfc 2255|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='rfc_2289'></a>rfc 2289|[otp](tcllib/files/modules/otp/otp.md)|
|<a name='rfc_2396'></a>rfc 2396|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='rfc_2554'></a>rfc 2554|[smtp](tcllib/files/modules/mime/smtp.md)|
|<a name='rfc_2718'></a>RFC 2718|[oauth](tcllib/files/modules/oauth/oauth.md)|
|<a name='rfc_2821'></a>rfc 2821|[smtp](tcllib/files/modules/mime/smtp.md) · [smtpd](tcllib/files/modules/smtpd/smtpd.md)|
|<a name='rfc_2849'></a>rfc 2849|[ldapx](tcllib/files/modules/ldap/ldapx.md)|
|<a name='rfc_3207'></a>rfc 3207|[smtp](tcllib/files/modules/mime/smtp.md)|
|<a name='rfc_3513'></a>rfc 3513|[tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md)|
|<a name='rfc_3986'></a>rfc 3986|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='rfc_4511'></a>rfc 4511|[ldap](tcllib/files/modules/ldap/ldap.md)|
|<a name='rfc_5849'></a>RFC 5849|[oauth](tcllib/files/modules/oauth/oauth.md)|
|<a name='rfc_6455'></a>rfc 6455|[websocket](tcllib/files/modules/websocket/websocket.md)|
|<a name='rfc_7858'></a>rfc 7858|[dns](tcllib/files/modules/dns/tcllib_dns.md)|
|<a name='rfc3501'></a>rfc3501|[imap4](tcllib/files/modules/imap4/imap4.md)|
|<a name='rfc3548'></a>rfc3548|[base32](tcllib/files/modules/base32/base32.md) · [base32::hex](tcllib/files/modules/base32/base32hex.md)|
|<a name='right_outer_join'></a>right outer join|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='ripemd'></a>RIPEMD|[ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md)|
|<a name='roman_numeral'></a>roman numeral|[math::roman](tcllib/files/modules/math/roman.md)|
|<a name='roots'></a>roots|[math::calculus](tcllib/files/modules/math/calculus.md)|
|<a name='rot'></a>rot|[tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md)|
|<a name='rot13'></a>rot13|[tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md)|
|<a name='rounding'></a>rounding|[math::fuzzy](tcllib/files/modules/math/fuzzy.md)|
|<a name='rows'></a>rows|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md)|
|<a name='rpc'></a>rpc|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md)|
|<a name='rsa'></a>rsa|[pki](tcllib/files/modules/pki/pki.md)|
|<a name='running'></a>running|[grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md)|
#### <a name='cS'></a>Keywords: S
|||
|---|---|
|<a name='s3'></a>s3|[S3](tcllib/files/modules/amazon-s3/S3.md)|
|<a name='sasl'></a>SASL|[SASL](tcllib/files/modules/sasl/sasl.md) · [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) · [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) · [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md)|
|<a name='scanl'></a>scanl|[generator](tcllib/files/modules/generator/generator.md)|
|<a name='sccs'></a>SCCS|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='scram'></a>SCRAM|[SASL::SCRAM](tcllib/files/modules/sasl/scram.md)|
|<a name='secure'></a>secure|[comm](tcllib/files/modules/comm/comm.md) · [pop3](tcllib/files/modules/pop3/pop3.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md) · [transfer::connect](tcllib/files/modules/transfer/connect.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='security'></a>security|[aes](tcllib/files/modules/aes/aes.md) · [blowfish](tcllib/files/modules/blowfish/blowfish.md) · [cksum](tcllib/files/modules/crc/cksum.md) · [crc16](tcllib/files/modules/crc/crc16.md) · [crc32](tcllib/files/modules/crc/crc32.md) · [des](tcllib/files/modules/des/des.md) · [md4](tcllib/files/modules/md4/md4.md) · [md5](tcllib/files/modules/md5/md5.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) · [otp](tcllib/files/modules/otp/otp.md) · [pki](tcllib/files/modules/pki/pki.md) · [rc4](tcllib/files/modules/rc4/rc4.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) · [sha1](tcllib/files/modules/sha1/sha1.md) · [sha256](tcllib/files/modules/sha1/sha256.md) · [sum](tcllib/files/modules/crc/sum.md) · [tclDES](tcllib/files/modules/des/tcldes.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr.md)|
|<a name='seed'></a>seed|[tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md)|
|<a name='selectionbox'></a>selectionbox|[javascript](tcllib/files/modules/javascript/javascript.md)|
|<a name='semantic_markup'></a>semantic markup|[docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) · [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) · [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) · [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) · [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) · [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) · [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) · [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) · [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) · [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) · [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) · [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) · [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) · [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) · [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) · [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) · [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) · [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md)|
|<a name='send'></a>send|[comm](tcllib/files/modules/comm/comm.md)|
|<a name='serialization'></a>serialization|[bee](tcllib/files/modules/bee/bee.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [struct::graph](tcllib/files/modules/struct/graph.md) · [struct::tree](tcllib/files/modules/struct/struct_tree.md)|
|<a name='server'></a>server|[map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) · [nameserv::common](tcllib/files/modules/nns/nns_common.md) · [nameserv::server](tcllib/files/modules/nns/nns_server.md) · [nns_intro](tcllib/files/modules/nns/nns_intro.md) · [nnsd](tcllib/files/apps/nnsd.md) · [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md)|
|<a name='service'></a>service|[logger](tcllib/files/modules/log/logger.md)|
|<a name='services'></a>services|[ftpd](tcllib/files/modules/ftpd/ftpd.md) · [smtpd](tcllib/files/modules/smtpd/smtpd.md) · [tool](tcllib/files/modules/httpd/httpd.md)|
|<a name='set'></a>set|[struct::queue](tcllib/files/modules/struct/queue.md) · [struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='sha1'></a>sha1|[sha1](tcllib/files/modules/sha1/sha1.md)|
|<a name='sha256'></a>sha256|[sha256](tcllib/files/modules/sha1/sha256.md)|
|<a name='shell'></a>shell|[string::token::shell](tcllib/files/modules/string/token_shell.md)|
|<a name='shortest_path'></a>shortest path|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='shuffle'></a>shuffle|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='simulated_annealing'></a>simulated annealing|[simulation::annealing](tcllib/files/modules/simulation/annealing.md)|
|<a name='simulation'></a>simulation|[simulation::random](tcllib/files/modules/simulation/simulation_random.md)|
|<a name='singleton'></a>singleton|[oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md)|
|<a name='size_limit'></a>size limit|[tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md)|
|<a name='skiplist'></a>skiplist|[struct::queue](tcllib/files/modules/struct/queue.md) · [struct::skiplist](tcllib/files/modules/struct/skiplist.md)|
|<a name='slippy'></a>slippy|[map::slippy](tcllib/files/modules/map/map_slippy.md) · [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md)|
|<a name='smtp'></a>smtp|[mime](tcllib/files/modules/mime/mime.md) · [smtp](tcllib/files/modules/mime/smtp.md) · [smtpd](tcllib/files/modules/smtpd/smtpd.md)|
|<a name='smtpd'></a>smtpd|[smtpd](tcllib/files/modules/smtpd/smtpd.md)|
|<a name='snit'></a>Snit|[snit](tcllib/files/modules/snit/snit.md)|
|<a name='snit'></a>snit|[deleg_method](tcllib/files/modules/interp/deleg_method.md) · [interp](tcllib/files/modules/interp/tcllib_interp.md)|
|<a name='sntp'></a>SNTP|[ntp_time](tcllib/files/modules/ntp/ntp_time.md)|
|<a name='socket'></a>socket|[comm](tcllib/files/modules/comm/comm.md) · [comm_wire](tcllib/files/modules/comm/comm_wire.md) · [smtpd](tcllib/files/modules/smtpd/smtpd.md)|
|<a name='soundex'></a>soundex|[soundex](tcllib/files/modules/soundex/soundex.md)|
|<a name='source'></a>source|[docstrip](tcllib/files/modules/docstrip/docstrip.md) · [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip.md)|
|<a name='spacing'></a>spacing|[tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md)|
|<a name='spatial_interpolation'></a>spatial interpolation|[math::interpolate](tcllib/files/modules/math/interpolate.md)|
|<a name='special_functions'></a>special functions|[math::special](tcllib/files/modules/math/special.md)|
|<a name='specification'></a>specification|[bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md)|
|<a name='speed'></a>speed|[profiler](tcllib/files/modules/profiler/profiler.md)|
|<a name='split'></a>split|[textutil::split](tcllib/files/modules/textutil/textutil_split.md)|
|<a name='squared_graph'></a>squared graph|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='ssl'></a>ssl|[comm](tcllib/files/modules/comm/comm.md) · [imap4](tcllib/files/modules/imap4/imap4.md) · [pop3](tcllib/files/modules/pop3/pop3.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md) · [transfer::connect](tcllib/files/modules/transfer/connect.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='stack'></a>stack|[struct::queue](tcllib/files/modules/struct/queue.md)|
|<a name='standard_io'></a>standard io|[tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md)|
|<a name='state'></a>state|[grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='state_de_serialization'></a>state (de)serialization|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
|<a name='statistical_distribution'></a>statistical distribution|[simulation::random](tcllib/files/modules/simulation/simulation_random.md)|
|<a name='statistics'></a>statistics|[counter](tcllib/files/modules/counter/counter.md) · [math](tcllib/files/modules/math/math.md) · [math::PCA](tcllib/files/modules/math/pca.md) · [math::statistics](tcllib/files/modules/math/statistics.md)|
|<a name='stdin'></a>stdin|[tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md)|
|<a name='stdout'></a>stdout|[tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md)|
|<a name='stochastic_modelling'></a>stochastic modelling|[simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md)|
|<a name='stream_cipher'></a>stream cipher|[rc4](tcllib/files/modules/rc4/rc4.md)|
|<a name='stream_copy'></a>stream copy|[tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md)|
|<a name='string'></a>string|[string::token](tcllib/files/modules/string/token.md) · [string::token::shell](tcllib/files/modules/string/token_shell.md) · [textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust.md) · [textutil::expander](tcllib/files/modules/textutil/expander.md) · [textutil::repeat](tcllib/files/modules/textutil/repeat.md) · [textutil::split](tcllib/files/modules/textutil/textutil_split.md) · [textutil::string](tcllib/files/modules/textutil/textutil_string.md) · [textutil::tabify](tcllib/files/modules/textutil/tabify.md) · [textutil::trim](tcllib/files/modules/textutil/trim.md)|
|<a name='stringprep'></a>stringprep|[stringprep](tcllib/files/modules/stringprep/stringprep.md) · [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) · [unicode::data](tcllib/files/modules/stringprep/unicode_data.md)|
|<a name='strongly_connected_component'></a>strongly connected component|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='struct'></a>struct|[struct::pool](tcllib/files/modules/struct/pool.md) · [struct::record](tcllib/files/modules/struct/record.md)|
|<a name='structure'></a>structure|[control](tcllib/files/modules/control/control.md)|
|<a name='structured_queries'></a>structured queries|[treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='style'></a>style|[doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md)|
|<a name='subcommand'></a>subcommand|[tepam](tcllib/files/modules/tepam/tepam_introduction.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md)|
|<a name='subgraph'></a>subgraph|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='subject'></a>subject|[hook](tcllib/files/modules/hook/hook.md)|
|<a name='submitbutton'></a>submitbutton|[javascript](tcllib/files/modules/javascript/javascript.md)|
|<a name='subscriber'></a>subscriber|[hook](tcllib/files/modules/hook/hook.md)|
|<a name='subsequence'></a>subsequence|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='subst'></a>subst|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md)|
|<a name='sum'></a>sum|[sum](tcllib/files/modules/crc/sum.md)|
|<a name='swapping'></a>swapping|[struct::list](tcllib/files/modules/struct/struct_list.md)|
|<a name='symmetric_difference'></a>symmetric difference|[struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='synchronous'></a>synchronous|[cache::async](tcllib/files/modules/cache/async.md)|
|<a name='syntax_tree'></a>syntax tree|[grammar::me::util](tcllib/files/modules/grammar_me/me_util.md)|
#### <a name='cT'></a>Keywords: T
|||
|---|---|
|<a name='table'></a>table|[doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [html](tcllib/files/modules/html/html.md) · [report](tcllib/files/modules/report/report.md)|
|<a name='table_of_contents'></a>table of contents|[doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) · [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) · [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md)|
|<a name='tabstops'></a>tabstops|[textutil::tabify](tcllib/files/modules/textutil/tabify.md)|
|<a name='tallying'></a>tallying|[counter](tcllib/files/modules/counter/counter.md)|
|<a name='tape_archive'></a>tape archive|[tar](tcllib/files/modules/tar/tar.md)|
|<a name='tar'></a>tar|[tar](tcllib/files/modules/tar/tar.md)|
|<a name='tcl'></a>tcl|[math::bigfloat](tcllib/files/modules/math/bigfloat.md) · [math::bignum](tcllib/files/modules/math/bignum.md) · [math::decimal](tcllib/files/modules/math/decimal.md) · [math::PCA](tcllib/files/modules/math/pca.md)|
|<a name='tcl_module'></a>Tcl module|[docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md)|
|<a name='tcl_syntax'></a>Tcl syntax|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md)|
|<a name='tcler_s_wiki'></a>tcler's wiki|[doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md)|
|<a name='tcllib'></a>tcllib|[csv](tcllib/files/modules/csv/csv.md)|
|<a name='tcloo'></a>TclOO|[oo::util](tcllib/files/modules/tool/meta.md) · [oo::util](tcllib/files/modules/ooutil/ooutil.md) · [oometa](tcllib/files/modules/oometa/oometa.md) · [tool](tcllib/files/modules/httpd/httpd.md) · [tool](tcllib/files/modules/tool/tool.md) · [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md)|
|<a name='tclparam'></a>TCLPARAM|[pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md)|
|<a name='tdpl'></a>TDPL|[grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='temp_file'></a>temp file|[fileutil](tcllib/files/modules/fileutil/fileutil.md)|
|<a name='template_processing'></a>template processing|[textutil::expander](tcllib/files/modules/textutil/expander.md)|
|<a name='terminal'></a>terminal|[term](tcllib/files/modules/term/term.md) · [term::ansi::code](tcllib/files/modules/term/ansi_code.md) · [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) · [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) · [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) · [term::ansi::send](tcllib/files/modules/term/ansi_send.md) · [term::interact::menu](tcllib/files/modules/term/imenu.md) · [term::interact::pager](tcllib/files/modules/term/ipager.md) · [term::receive](tcllib/files/modules/term/receive.md) · [term::receive::bind](tcllib/files/modules/term/term_bind.md) · [term::send](tcllib/files/modules/term/term_send.md)|
|<a name='test'></a>test|[fileutil](tcllib/files/modules/fileutil/fileutil.md)|
|<a name='testing'></a>Testing|[valtype::common](tcllib/files/modules/valtype/valtype_common.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md) · [valtype::imei](tcllib/files/modules/valtype/imei.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
|<a name='testing'></a>testing|[bench](tcllib/files/modules/bench/bench.md) · [bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) · [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) · [bench_intro](tcllib/files/modules/bench/bench_intro.md) · [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) · [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md)|
|<a name='tex'></a>TeX|[textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
|<a name='text'></a>text|[bench::in](tcllib/files/modules/bench/bench_read.md) · [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md)|
|<a name='text_comparison'></a>text comparison|[soundex](tcllib/files/modules/soundex/soundex.md)|
|<a name='text_conversion'></a>text conversion|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='text_differences'></a>text differences|[rcs](tcllib/files/modules/rcs/rcs.md)|
|<a name='text_display'></a>text display|[term::interact::menu](tcllib/files/modules/term/imenu.md) · [term::interact::pager](tcllib/files/modules/term/ipager.md)|
|<a name='text_expansion'></a>text expansion|[textutil::expander](tcllib/files/modules/textutil/expander.md)|
|<a name='text_likeness'></a>text likeness|[soundex](tcllib/files/modules/soundex/soundex.md)|
|<a name='text_processing'></a>text processing|[bibtex](tcllib/files/modules/bibtex/bibtex.md) · [huddle](tcllib/files/modules/yaml/huddle.md) · [page](tcllib/files/apps/page.md) · [page_intro](tcllib/files/modules/page/page_intro.md) · [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) · [page_util_flow](tcllib/files/modules/page/page_util_flow.md) · [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) · [page_util_peg](tcllib/files/modules/page/page_util_peg.md) · [page_util_quote](tcllib/files/modules/page/page_util_quote.md) · [yaml](tcllib/files/modules/yaml/yaml.md)|
|<a name='text_widget'></a>text widget|[tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md)|
|<a name='threads'></a>threads|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='throw'></a>throw|[throw](tcllib/files/modules/try/tcllib_throw.md)|
|<a name='thumbnail'></a>thumbnail|[jpeg](tcllib/files/modules/jpeg/jpeg.md)|
|<a name='tie'></a>tie|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md)|
|<a name='tif'></a>tif|[tiff](tcllib/files/modules/tiff/tiff.md)|
|<a name='tiff'></a>tiff|[tiff](tcllib/files/modules/tiff/tiff.md)|
|<a name='tile'></a>tile|[map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md)|
|<a name='time'></a>time|[ntp_time](tcllib/files/modules/ntp/ntp_time.md)|
|<a name='timestamp'></a>timestamp|[png](tcllib/files/modules/png/png.md)|
|<a name='timestamps'></a>timestamps|[debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md)|
|<a name='tip_219'></a>tip 219|[tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) · [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) · [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) · [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) · [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) · [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) · [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) · [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) · [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) · [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) · [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md)|
|<a name='tip_230'></a>tip 230|[tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='tip_234'></a>tip 234|[tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='tip_317'></a>tip 317|[tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md)|
|<a name='tk'></a>Tk|[tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md)|
|<a name='tls'></a>tls|[comm](tcllib/files/modules/comm/comm.md) · [imap4](tcllib/files/modules/imap4/imap4.md) · [pop3](tcllib/files/modules/pop3/pop3.md) · [pop3d](tcllib/files/modules/pop3d/pop3d.md) · [smtp](tcllib/files/modules/mime/smtp.md) · [transfer::connect](tcllib/files/modules/transfer/connect.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='tmml'></a>TMML|[doctools](tcllib/files/modules/doctools/doctools.md) · [doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) · [dtplite](tcllib/files/apps/dtplite.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand.md)|
|<a name='toc'></a>toc|[doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) · [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md)|
|<a name='toc_formatter'></a>toc formatter|[doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md)|
|<a name='tokenization'></a>tokenization|[string::token](tcllib/files/modules/string/token.md) · [string::token::shell](tcllib/files/modules/string/token_shell.md)|
|<a name='tool'></a>TOOL|[oometa](tcllib/files/modules/oometa/oometa.md) · [tool](tcllib/files/modules/tool/tool.md) · [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md)|
|<a name='top_down_parsing_languages'></a>top-down parsing languages|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='torrent'></a>torrent|[bee](tcllib/files/modules/bee/bee.md)|
|<a name='touch'></a>touch|[fileutil](tcllib/files/modules/fileutil/fileutil.md)|
|<a name='tpdl'></a>TPDL|[grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md)|
|<a name='trace'></a>trace|[debug](tcllib/files/modules/debug/debug.md) · [debug::caller](tcllib/files/modules/debug/debug_caller.md) · [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) · [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md)|
|<a name='transducer'></a>transducer|[grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) · [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) · [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) · [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) · [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt](tcllib/files/apps/pt.md) · [pt::ast](tcllib/files/modules/pt/pt_astree.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) · [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) · [pt::param](tcllib/files/modules/pt/pt_param.md) · [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) · [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) · [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) · [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) · [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) · [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) · [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) · [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) · [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) · [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) · [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) · [pt::util](tcllib/files/modules/pt/pt_util.md) · [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) · [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) · [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) · [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) · [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) · [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md)|
|<a name='transfer'></a>transfer|[transfer::connect](tcllib/files/modules/transfer/connect.md) · [transfer::copy](tcllib/files/modules/transfer/copyops.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) · [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) · [transfer::data::source](tcllib/files/modules/transfer/dsource.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='transformation'></a>transformation|[page_util_peg](tcllib/files/modules/page/page_util_peg.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='transmitter'></a>transmitter|[transfer::transmitter](tcllib/files/modules/transfer/transmitter.md)|
|<a name='travelling_salesman'></a>travelling salesman|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='traversal'></a>traversal|[fileutil_traverse](tcllib/files/modules/fileutil/traverse.md)|
|<a name='tree'></a>tree|[grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) · [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) · [struct::queue](tcllib/files/modules/struct/queue.md) · [struct::stack](tcllib/files/modules/struct/stack.md) · [struct::tree](tcllib/files/modules/struct/struct_tree.md) · [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) · [treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='tree_query_language'></a>tree query language|[treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='tree_walking'></a>tree walking|[page_util_flow](tcllib/files/modules/page/page_util_flow.md) · [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) · [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md)|
|<a name='treeql'></a>TreeQL|[treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='trigonometry'></a>trigonometry|[math::trig](tcllib/files/modules/math/trig.md)|
|<a name='trimming'></a>trimming|[textutil](tcllib/files/modules/textutil/textutil.md) · [textutil::trim](tcllib/files/modules/textutil/trim.md)|
|<a name='twitter'></a>twitter|[oauth](tcllib/files/modules/oauth/oauth.md)|
|<a name='type'></a>type|[fileutil](tcllib/files/modules/fileutil/fileutil.md) · [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) · [snit](tcllib/files/modules/snit/snit.md)|
|<a name='type_checking'></a>Type checking|[valtype::common](tcllib/files/modules/valtype/valtype_common.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md) · [valtype::imei](tcllib/files/modules/valtype/imei.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
#### <a name='cU'></a>Keywords: U
|||
|---|---|
|<a name='uevent'></a>uevent|[hook](tcllib/files/modules/hook/hook.md)|
|<a name='unbind'></a>unbind|[uevent](tcllib/files/modules/uev/uevent.md)|
|<a name='uncapitalize'></a>uncapitalize|[textutil::string](tcllib/files/modules/textutil/textutil_string.md)|
|<a name='undenting'></a>undenting|[textutil::adjust](tcllib/files/modules/textutil/adjust.md)|
|<a name='unicode'></a>unicode|[stringprep](tcllib/files/modules/stringprep/stringprep.md) · [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) · [unicode](tcllib/files/modules/stringprep/unicode.md) · [unicode::data](tcllib/files/modules/stringprep/unicode_data.md)|
|<a name='union'></a>union|[struct::disjointset](tcllib/files/modules/struct/disjointset.md) · [struct::set](tcllib/files/modules/struct/struct_set.md)|
|<a name='unit'></a>unit|[units](tcllib/files/modules/units/units.md)|
|<a name='unknown_hooking'></a>unknown hooking|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
|<a name='untie'></a>untie|[tie](tcllib/files/modules/tie/tie_std.md) · [tie](tcllib/files/modules/tie/tie.md)|
|<a name='update'></a>update|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md)|
|<a name='uri'></a>uri|[uri](tcllib/files/modules/uri/uri.md) · [uri_urn](tcllib/files/modules/uri/urn-scheme.md)|
|<a name='url'></a>url|[doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) · [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) · [uri](tcllib/files/modules/uri/uri.md) · [uri_urn](tcllib/files/modules/uri/urn-scheme.md)|
|<a name='urn'></a>urn|[uri_urn](tcllib/files/modules/uri/urn-scheme.md)|
|<a name='us_npi'></a>US-NPI|[valtype::usnpi](tcllib/files/modules/valtype/usnpi.md)|
|<a name='utilities'></a>utilities|[namespacex](tcllib/files/modules/namespacex/namespacex.md)|
|<a name='uuencode'></a>uuencode|[uuencode](tcllib/files/modules/base64/uuencode.md)|
|<a name='uuid'></a>UUID|[uuid](tcllib/files/modules/uuid/uuid.md)|
#### <a name='cV'></a>Keywords: V
|||
|---|---|
|<a name='validation'></a>Validation|[valtype::common](tcllib/files/modules/valtype/valtype_common.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md) · [valtype::imei](tcllib/files/modules/valtype/imei.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
|<a name='value_checking'></a>Value checking|[valtype::common](tcllib/files/modules/valtype/valtype_common.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) · [valtype::iban](tcllib/files/modules/valtype/iban.md) · [valtype::imei](tcllib/files/modules/valtype/imei.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
|<a name='vectors'></a>vectors|[math::linearalgebra](tcllib/files/modules/math/linalg.md)|
|<a name='verhoeff'></a>verhoeff|[valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md)|
|<a name='vertex'></a>vertex|[struct::graph](tcllib/files/modules/struct/graph.md) · [struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='vertex_cover'></a>vertex cover|[struct::graph::op](tcllib/files/modules/struct/graphops.md)|
|<a name='virtual_channel'></a>virtual channel|[tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) · [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) · [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) · [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) · [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) · [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) · [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) · [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) · [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) · [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) · [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='virtual_machine'></a>virtual machine|[grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) · [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) · [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) · [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) · [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) · [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) · [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) · [pt::param](tcllib/files/modules/pt/pt_param.md)|
|<a name='visa'></a>VISA|[valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md)|
|<a name='vwait'></a>vwait|[coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) · [smtpd](tcllib/files/modules/smtpd/smtpd.md)|
#### <a name='cW'></a>Keywords: W
|||
|---|---|
|<a name='wais'></a>wais|[uri](tcllib/files/modules/uri/uri.md)|
|<a name='widget'></a>widget|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md)|
|<a name='widget_adaptors'></a>widget adaptors|[snit](tcllib/files/modules/snit/snit.md) · [snitfaq](tcllib/files/modules/snit/snitfaq.md)|
|<a name='wiki'></a>wiki|[doctools::idx](tcllib/files/modules/doctools/docidx.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md)|
|<a name='word'></a>word|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) · [wip](tcllib/files/modules/wip/wip.md)|
|<a name='www'></a>WWW|[tool](tcllib/files/modules/httpd/httpd.md)|
|<a name='www'></a>www|[uri](tcllib/files/modules/uri/uri.md)|
#### <a name='cX'></a>Keywords: X
|||
|---|---|
|<a name='x_208'></a>x.208|[asn](tcllib/files/modules/asn/asn.md)|
|<a name='x_209'></a>x.209|[asn](tcllib/files/modules/asn/asn.md)|
|<a name='x_500'></a>x.500|[ldap](tcllib/files/modules/ldap/ldap.md)|
|<a name='xgoogletoken'></a>XGoogleToken|[SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md)|
|<a name='xml'></a>xml|[xsxp](tcllib/files/modules/amazon-s3/xsxp.md)|
|<a name='xor'></a>xor|[tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md)|
|<a name='xpath'></a>XPath|[treeql](tcllib/files/modules/treeql/treeql.md)|
|<a name='xslt'></a>XSLT|[treeql](tcllib/files/modules/treeql/treeql.md)|
#### <a name='cY'></a>Keywords: Y
|||
|---|---|
|<a name='yaml'></a>yaml|[huddle](tcllib/files/modules/yaml/huddle.md) · [yaml](tcllib/files/modules/yaml/yaml.md)|
|<a name='ydecode'></a>ydecode|[yencode](tcllib/files/modules/base64/yencode.md)|
|<a name='yenc'></a>yEnc|[yencode](tcllib/files/modules/base64/yencode.md)|
|<a name='yencode'></a>yencode|[yencode](tcllib/files/modules/base64/yencode.md)|
#### <a name='cZ'></a>Keywords: Z
|||
|---|---|
|<a name='zero'></a>zero|[tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md)|
|<a name='zip'></a>zip|[zipfile::decode](tcllib/files/modules/zip/decode.md) · [zipfile::encode](tcllib/files/modules/zip/encode.md) · [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md)|
|<a name='zlib'></a>zlib|[tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md)|
|<a name='zoom'></a>zoom|[map::slippy](tcllib/files/modules/map/map_slippy.md) · [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) · [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md)|
|
Added embedded/md/tcllib/files/apps/dtplite.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
|
[//000000001]: # (dtplite - Documentation toolbox)
[//000000002]: # (Generated from file 'dtplite.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (dtplite(n) 1.0.5 tcllib "Documentation toolbox")
# NAME
dtplite - Lightweight DocTools Markup Processor
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USE CASES](#subsection1)
- [COMMAND LINE](#subsection2)
- [OPTIONS](#subsection3)
- [FORMATS](#subsection4)
- [DIRECTORY STRUCTURES](#subsection5)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__dtplite__ __-o__ *output* ?options? *format* *inputfile*](#1)
[__dtplite__ __validate__ *inputfile*](#2)
[__dtplite__ __-o__ *output* ?options? *format* *inputdirectory*](#3)
[__dtplite__ __-merge__ __-o__ *output* ?options? *format* *inputdirectory*](#4)
# <a name='description'></a>DESCRIPTION
The application described by this document, __dtplite__, is the successor to the
extremely simple __[mpexpand](../modules/doctools/mpexpand.md)__. Influenced in
its functionality by the __dtp__ doctools processor it is much more powerful
than __[mpexpand](../modules/doctools/mpexpand.md)__, yet still as easy to use;
definitely easier than __dtp__ with its myriad of subcommands and options.
__dtplite__ is based upon the package
__[doctools](../modules/doctools/doctools.md)__, like the other two processors.
## <a name='subsection1'></a>USE CASES
__dtplite__ was written with the following three use cases in mind.
1. Validation of a single document, i.e. checking that it was written in valid
doctools format. This mode can also be used to get a preliminary version of
the formatted output for a single document, for display in a browser,
nroff, etc., allowing proofreading of the formatting.
1. Generation of the formatted documentation for a single package, i.e. all
the manpages, plus a table of contents and an index of keywords.
1. An extension of the previous mode of operation, a method for the easy
generation of one documentation tree for several packages, and especially
of a unified table of contents and keyword index.
Beyond the above we also want to make use of the customization features provided
by the HTML formatter. It is not the only format the application should be able
to generate, but we anticipiate it to be the most commonly used, and it is one
of the few which do provide customization hooks.
We allow the caller to specify a header string, footer string, a stylesheet, and
data for a bar of navigation links at the top of the generated document. While
all can be set as long as the formatting engine provides an appropriate engine
parameter (See section [OPTIONS](#subsection3)) the last two have internal
processing which make them specific to HTML.
## <a name='subsection2'></a>COMMAND LINE
- <a name='1'></a>__dtplite__ __-o__ *output* ?options? *format* *inputfile*
This is the form for use case [1]. The *options* will be explained later, in
section [OPTIONS](#subsection3).
* path *output* (in)
This argument specifies where to write the generated document. It can be
the path to a file or directory, or __-__. The last value causes the
application to write the generated documented to __stdout__.
If the *output* does not exist then [file dirname $output] has to exist
and must be a writable directory. The generated document will be written
to a file in that directory, and the name of that file will be derived
from the *inputfile*, the *format*, and the value given to option
__-ext__ (if present).
* (path|handle) *format* (in)
This argument specifies the formatting engine to use when processing the
input, and thus the format of the generated document. See section
[FORMATS](#subsection4) for the possibilities recognized by the
application.
* path *inputfile* (in)
This argument specifies the path to the file to process. It has to
exist, must be readable, and written in
*[doctools](../../../index.md#doctools)* format.
- <a name='2'></a>__dtplite__ __validate__ *inputfile*
This is a simpler form for use case [1]. The "validate" format generates no
output at all, only syntax checks are performed. As such the specification
of an output file or other options is not necessary and left out.
- <a name='3'></a>__dtplite__ __-o__ *output* ?options? *format* *inputdirectory*
This is the form for use case [2]. It differs from the form for use case [1]
by having the input documents specified through a directory instead of a
file. The other arguments are identical, except for *output*, which now has
to be the path to an existing and writable directory.
The input documents are all files in *inputdirectory* or any of its
subdirectories which were recognized by __fileutil::fileType__ as containing
text in *[doctools](../../../index.md#doctools)* format.
- <a name='4'></a>__dtplite__ __-merge__ __-o__ *output* ?options? *format* *inputdirectory*
This is the form for use case [3]. The only difference to the form for use
case [2] is the additional option __-merge__.
Each such call will merge the generated documents coming from processing the
input documents under *inputdirectory* or any of its subdirectories to the
files under *output*. In this manner it is possible to incrementally build
the unified documentation for any number of packages. Note that it is
necessary to run through all the packages twice to get fully correct
cross-references (for formats supporting them).
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application,
with the exception of the options __-o__ and __-merge__. These two were
described already, in section [COMMAND LINE](#subsection2).
- __-exclude__ string
This option specifies an exclude (glob) pattern. Any files identified as
manpages to process which match the exclude pattern are ignored. The option
can be provided multiple times, each usage adding an additional pattern to
the list of exclusions.
- __-ext__ string
If the name of an output file has to be derived from the name of an input
file it will use the name of the *format* as the extension by default. This
option here will override this however, forcing it to use *string* as the
file extension. This option is ignored if the name of the output file is
fully specified through option __-o__.
When used multiple times only the last definition is relevant.
- __-header__ file
This option can be used if and only if the selected *format* provides an
engine parameter named "header". It takes the contents of the specified file
and assign them to that parameter, for whatever use by the engine. The HTML
engine will insert the text just after the tag __<body>__. If navigation
buttons are present (see option __-nav__ below), then the HTML generated for
them is appended to the header data originating here before the final
assignment to the parameter.
When used multiple times only the last definition is relevant.
- __-footer__ file
Like __-header__, except that: Any navigation buttons are ignored, the
corresponding required engine parameter is named "footer", and the data is
inserted just before the tag __</body>__.
When used multiple times only the last definition is relevant.
- __-style__ file
This option can be used if and only if the selected *format* provides an
engine parameter named "meta". When specified it will generate a piece of
HTML code declaring the *file* as the stylesheet for the generated document
and assign that to the parameter. The HTML engine will insert this inot the
document, just after the tag __<head>__.
When processing an input directory the stylesheet file is copied into the
output directory and the generated HTML will refer to the copy, to make the
result more self-contained. When processing an input file we have no
location to copy the stylesheet to and so just reference it as specified.
When used multiple times only the last definition is relevant.
- __-toc__ path
This option specifies a doctoc file to use for the table of contents instead
of generating our own.
When used multiple times only the last definition is relevant.
- __-pre+toc__ label path|text
- __-post+toc__ label path|text
This option specifies additional doctoc files (or texts) to use in the
navigation bar.
Positioning and handling of multiple uses is like for options __-prenav__
and __-postnav__, see below.
- __-nav__ label url
- __-prenav__ label url
Use this option to specify a navigation button with *label* to display and
the *url* to link to. This option can be used if and only if the selected
*format* provides an engine parameter named "header". The HTML generated for
this is appended to whatever data we got from option __-header__ before it
is inserted into the generated documents.
When used multiple times all definitions are collected and a navigation bar
is created, with the first definition shown at the left edge and the last
definition to the right.
The url can be relative. In that case it is assumed to be relative to the
main files (TOC and Keyword index), and will be transformed for all others
to still link properly.
- __-postnav__ label url
Use this option to specify a navigation button with *label* to display and
the *url* to link to. This option can be used if and only if the selected
*format* provides an engine parameter named "header". The HTML generated for
this is appended to whatever data we got from option __-header__ before it
is inserted into the generated documents.
When used multiple times all definitions are collected and a navigation bar
is created, with the last definition shown at the right edge and the first
definition to the left.
The url can be relative. In that case it is assumed to be relative to the
main files (TOC and Keyword index), and will be transformed for all others
to still link properly.
## <a name='subsection4'></a>FORMATS
At first the *format* argument will be treated as a path to a tcl file
containing the code for the requested formatting engine. The argument will be
treated as the name of one of the predefined formats listed below if and only if
the path does not exist.
*Note a limitation*: If treating the format as path to the tcl script
implementing the engine was sucessful, then this script has to implement not
only the engine API for doctools, i.e. *doctools_api*, but for *doctoc_api* and
*docidx_api* as well. Otherwise the generation of a table of contents and of a
keyword index will fail.
List of predefined formats, i.e. as provided by the package
__[doctools](../modules/doctools/doctools.md)__:
- __nroff__
The processor generates *roff output, the standard format for unix manpages.
- __html__
The processor generates HTML output, for usage in and display by web
browsers. This engine is currently the only one providing the various engine
parameters required for the additional customaization of the output.
- __tmml__
The processor generates TMML output, the Tcl Manpage Markup Language, a
derivative of XML.
- __latex__
The processor generates LaTeX output.
- __wiki__
The processor generates Wiki markup as understood by __wikit__.
- __list__
The processor extracts the information provided by __manpage_begin__. This
format is used internally to extract the meta data from which both table of
contents and keyword index are derived from.
- __null__
The processor does not generate any output. This is equivalent to
__validate__.
## <a name='subsection5'></a>DIRECTORY STRUCTURES
In this section we describe the directory structures generated by the
application under *output* when processing all documents in an *inputdirectory*.
In other words, this is only relevant to the use cases [2] and [3].
- [2]
The following directory structure is created when processing a single set of
input documents. The file extension used is for output in HTML, but that is
not relevant to the structure and was just used to have proper file names.
output/
toc.html
index.html
files/
path/to/FOO.html
The last line in the example shows the document generated for a file FOO
located at
inputdirectory/path/to/FOO
- [3]
When merging many packages into a unified set of documents the generated
directory structure is a bit deeper:
output
.toc
.idx
.tocdoc
.idxdoc
.xrf
toc.html
index.html
FOO1/
...
FOO2/
toc.html
files/
path/to/BAR.html
Each of the directories FOO1, ... contains the documents generated for the
package FOO1, ... and follows the structure shown for use case [2]. The only
exception is that there is no per-package index.
The files ".toc", ".idx", and ".xrf" contain the internal status of the
whole output and will be read and updated by the next invokation. Their
contents will not be documented. Remove these files when all packages wanted
for the output have been processed, i.e. when the output is complete.
The files ".tocdoc", and ".idxdoc", are intermediate files in doctoc and
docidx markup, respectively, containing the main table of contents and
keyword index for the set of documents before their conversion to the chosen
output format. They are left in place, i.e. not deleted, to serve as
demonstrations of doctoc and docidx markup.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx introduction](../modules/doctools/docidx_intro.md), [doctoc
introduction](../modules/doctools/doctoc_intro.md), [doctools
introduction](../modules/doctools/doctools_intro.md)
# <a name='keywords'></a>KEYWORDS
[HTML](../../../index.md#html), [TMML](../../../index.md#tmml),
[conversion](../../../index.md#conversion), [docidx](../../../index.md#docidx),
[doctoc](../../../index.md#doctoc), [doctools](../../../index.md#doctools),
[manpage](../../../index.md#manpage), [markup](../../../index.md#markup),
[nroff](../../../index.md#nroff)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2013 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/apps/nns.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
[//000000001]: # (nns - Name service facility)
[//000000002]: # (Generated from file 'nns.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nns(n) 1.1 tcllib "Name service facility")
# NAME
nns - Name service facility, Commandline Client Application
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USE CASES](#subsection1)
- [COMMAND LINE](#subsection2)
- [OPTIONS](#subsection3)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__nns__ __bind__ ?__-host__ *host*? ?__-port__ *port*? *name* *data*](#1)
[__nns__ __search__ ?__-host__ *host*? ?__-port__ *port*? ?__-continuous__? ?*pattern*?](#2)
[__nns__ __ident__ ?__-host__ *host*? ?__-port__ *port*?](#3)
[__nns__ __who__](#4)
# <a name='description'></a>DESCRIPTION
Please read *[Name service facility, introduction](../modules/nns/nns_intro.md)*
first.
The application described by this document, __nns__, is a simple command line
client for the nano name service facility provided by the Tcllib packages
__[nameserv](../modules/nns/nns_client.md)__, and
__[nameserv::server](../modules/nns/nns_server.md)__. Beyond that the
application's sources also serve as an example of how to use the client package
__[nameserv](../modules/nns/nns_client.md)__. All abilities of a client are
covered, from configuration to registration of names to searching.
This name service facility has nothing to do with the Internet's *Domain Name
System*, otherwise known as *[DNS](../../../index.md#dns)*. If the reader is
looking for a package dealing with that please see either of the packages
__[dns](../modules/dns/tcllib_dns.md)__ and __resolv__, both found in Tcllib
too.
## <a name='subsection1'></a>USE CASES
__nns__ was written with the following two main use cases in mind.
1. Registration of a name/data pair in the name service.
1. Searching the name service for entries matching a glob pattern.
Beyond the above we also want to be able to identify the client, and get
information about the name service.
## <a name='subsection2'></a>COMMAND LINE
- <a name='1'></a>__nns__ __bind__ ?__-host__ *host*? ?__-port__ *port*? *name* *data*
This form registers the *name*/*data* pair in the specified name service. In
this form the command will *not* exit to keep the registration alive. The
user has to kill it explicitly, either by sending a signal, or through the
job-control facilities of the shell in use. It will especially survive the
loss of the connection to the name service and reestablish the *name*/*data*
pair when the connection is restored.
The options to specify the name service will be explained later, in section
[OPTIONS](#subsection3).
- <a name='2'></a>__nns__ __search__ ?__-host__ *host*? ?__-port__ *port*? ?__-continuous__? ?*pattern*?
This form searches the specified name service for entries matching the
glob-*pattern* and prints them to stdout, with each entry on its own line.
If no pattern is specified it defaults to __*__, matching everything.
The options to specify the name service will be explained later, in section
[OPTIONS](#subsection3).
If the option __-continuous__ is specified the client will not exit after
performing the search, but start to continuously monitor the service for
changes to the set of matching entries, appropriately updating the display
as changes arrive. In that form it will especially also survive the loss of
the connection to the name service and reestablish the search when the
connection is restored.
- <a name='3'></a>__nns__ __ident__ ?__-host__ *host*? ?__-port__ *port*?
This form asks the specified name service for the version and features of
the name service protocol it supports and prints the results to stdout.
The options to specify the name service will be explained later, in section
[OPTIONS](#subsection3).
- <a name='4'></a>__nns__ __who__
This form prints name, version, and protocol version of the application to
stdout.
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application
- __-host__ name|ipaddress
If this option is not specified it defaults to __localhost__. It specifies
the name or ip-address of the host the name service to talk to is running
on.
- __-port__ number
If this option is not specified it defaults to __38573__. It specifies the
TCP port the name service to talk to is listening on for requests.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[nameserv(n)](../modules/nns/nns_client.md),
[nameserv::common(n)](../modules/nns/nns_common.md)
# <a name='keywords'></a>KEYWORDS
[application](../../../index.md#application),
[client](../../../index.md#client), [name
service](../../../index.md#name_service)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/apps/nnsd.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
[//000000001]: # (nnsd - Name service facility)
[//000000002]: # (Generated from file 'nnsd.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nnsd(n) 1.0.1 tcllib "Name service facility")
# NAME
nnsd - Name service facility, Commandline Server Application
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USE CASES](#subsection1)
- [COMMAND LINE](#subsection2)
- [OPTIONS](#subsection3)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__nnsd__ ?__-localonly__ *flag*? ?__-port__ *port*?](#1)
# <a name='description'></a>DESCRIPTION
Please read *[Name service facility, introduction](../modules/nns/nns_intro.md)*
first.
The application described by this document, __[nns](nns.md)__, is a simple
command line server for the nano name service facility provided by the Tcllib
packages __[nameserv](../modules/nns/nns_client.md)__, and
__[nameserv::server](../modules/nns/nns_server.md)__. Beyond that the
application's sources also serve as an example of how to use the server package
__[nameserv::server](../modules/nns/nns_server.md)__.
This name service facility has nothing to do with the Internet's *Domain Name
System*, otherwise known as *[DNS](../../../index.md#dns)*. If the reader is
looking for a package dealing with that please see either of the packages
__[dns](../modules/dns/tcllib_dns.md)__ and __resolv__, both found in Tcllib
too.
## <a name='subsection1'></a>USE CASES
__nnsd__ was written with the following main use case in mind.
1. Run a nano name service on some host.
## <a name='subsection2'></a>COMMAND LINE
- <a name='1'></a>__nnsd__ ?__-localonly__ *flag*? ?__-port__ *port*?
The command configures a server per the specified options and starts it. The
command will not exit on its own, as it keeps the name service database
wholly in memory. The user has to kill it explicitly, either by sending a a
signal, or through the job-control facilities of the shell in use.
The options to configure the name service are explained in section
[OPTIONS](#subsection3).
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application
- __-localonly__ bool
If this option is not specified it defaults to __true__, i.e. acceptance of
only local connections. The server will accept remote connections, i.e.
connections from other hosts, if and only if this option is configured to
__false__.
- __-port__ number
If this option is not specified it defaults to __38573__. It specifies the
TCP port the server has to listen on for requests.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[nameserv::common(n)](../modules/nns/nns_common.md),
[nameserv::server(n)](../modules/nns/nns_server.md)
# <a name='keywords'></a>KEYWORDS
[application](../../../index.md#application), [name
service](../../../index.md#name_service), [server](../../../index.md#server)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/apps/nnslog.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
[//000000001]: # (nnslog - Name service facility)
[//000000002]: # (Generated from file 'nnslog.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nnslog(n) 1.0 tcllib "Name service facility")
# NAME
nnslog - Name service facility, Commandline Logging Client Application
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USE CASES](#subsection1)
- [COMMAND LINE](#subsection2)
- [OPTIONS](#subsection3)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__nnslog__ ?__-host__ *host*? ?__-port__ *port*?](#1)
# <a name='description'></a>DESCRIPTION
Please read *[Name service facility, introduction](../modules/nns/nns_intro.md)*
first.
The application described by this document, __nnslog__, is a simple command line
client for the nano name service facility provided by the Tcllib packages
__[nameserv](../modules/nns/nns_client.md)__, and
__[nameserv::server](../modules/nns/nns_server.md)__.
It essentially implements "__[nns](nns.md)__ search -continuous *", but uses a
different output formatting. Instead of continuously showing the current
contents of the server in the terminal it simply logs all received add/remove
events to __stdout__.
This name service facility has nothing to do with the Internet's *Domain Name
System*, otherwise known as *[DNS](../../../index.md#dns)*. If the reader is
looking for a package dealing with that please see either of the packages
__[dns](../modules/dns/tcllib_dns.md)__ and __resolv__, both found in Tcllib
too.
## <a name='subsection1'></a>USE CASES
__nnslog__ was written with the following main use case in mind.
1. Monitoring the name service for all changes and logging them in a text
terminal.
## <a name='subsection2'></a>COMMAND LINE
- <a name='1'></a>__nnslog__ ?__-host__ *host*? ?__-port__ *port*?
The command connects to the specified name service, sets up a search for all
changes and then prints all received events to stdout, with each events on
its own line. The command will not exit until it is explicitly terminated by
the user. It will especially survive the loss of the connection to the name
service and reestablish the search and log when the connection is restored.
The options to specify the name service will be explained later, in section
[OPTIONS](#subsection3).
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application
- __-host__ name|ipaddress
If this option is not specified it defaults to __localhost__. It specifies
the name or ip-address of the host the name service to talk to is running
on.
- __-port__ number
If this option is not specified it defaults to __38573__. It specifies the
TCP port the name service to talk to is listening on for requests.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[nameserv(n)](../modules/nns/nns_client.md),
[nameserv::common(n)](../modules/nns/nns_common.md)
# <a name='keywords'></a>KEYWORDS
[application](../../../index.md#application),
[client](../../../index.md#client), [name
service](../../../index.md#name_service)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/apps/page.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
|
[//000000001]: # (page - Development Tools)
[//000000002]: # (Generated from file 'page.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page(n) 1.0 tcllib "Development Tools")
# NAME
page - Parser Generator
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMAND LINE](#subsection1)
- [OPERATION](#subsection2)
- [OPTIONS](#subsection3)
- [PLUGINS](#subsection4)
- [PLUGIN LOCATIONS](#subsection5)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__page__ ?*options*...? ?*input* ?*output*??](#1)
# <a name='description'></a>DESCRIPTION
The application described by this document, __page__, is actually not just a
parser generator, as the name implies, but a generic tool for the execution of
arbitrary transformations on texts.
Its genericity comes through the use of *plugins* for reading, transforming, and
writing data, and the predefined set of plugins provided by Tcllib is for the
generation of memoizing recursive descent parsers (aka *packrat parsers*) from
grammar specifications (*Parsing Expression Grammars*).
__page__ is written on top of the package __page::pluginmgr__, wrapping its
functionality into a command line based application. All the other __page::*__
packages are plugin and/or supporting packages for the generation of parsers.
The parsers themselves are based on the packages
__[grammar::peg](../modules/grammar_peg/peg.md)__,
__[grammar::peg::interp](../modules/grammar_peg/peg_interp.md)__, and
__grammar::mengine__.
## <a name='subsection1'></a>COMMAND LINE
- <a name='1'></a>__page__ ?*options*...? ?*input* ?*output*??
This is general form for calling __page__. The application will read the
contents of the file *input*, process them under the control of the
specified *options*, and then write the result to the file *output*.
If *input* is the string __-__ the data to process will be read from
__stdin__ instead of a file. Analogously the result will be written to
__stdout__ instead of a file if *output* is the string __-__. A missing
output or input specification causes the application to assume __-__.
The detailed specifications of the recognized *options* are provided in
section [OPTIONS](#subsection3).
* path *input* (in)
This argument specifies the path to the file to be processed by the
application, or __-__. The last value causes the application to read the
text from __stdin__. Otherwise it has to exist, and be readable. If the
argument is missing __-__ is assumed.
* path *output* (in)
This argument specifies where to write the generated text. It can be the
path to a file, or __-__. The last value causes the application to write
the generated documented to __stdout__.
If the file *output* does not exist then [file dirname $output] has to
exist and must be a writable directory, as the application will create
the fileto write to.
If the argument is missing __-__ is assumed.
## <a name='subsection2'></a>OPERATION
... reading ... transforming ... writing - plugins - pipeline ...
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application.
Options are always processed in order. I.e. of both __--help__ and __--version__
are specified the option encountered first has precedence.
Unknown options specified before any of the options __-rd__, __-wr__, or __-tr__
will cause processing to abort with an error. Unknown options coming in between
these options, or after the last of them are assumed to always take a single
argument and are associated with the last plugin option coming before them. They
will be checked after all the relevant plugins, and thus the options they
understand, are known. I.e. such unknown options cause error if and only if the
plugin option they are associated with does not understand them, and was not
superceded by a plugin option coming after.
Default options are used if and only if the command line did not contain any
options at all. They will set the application up as a PEG-based parser
generator. The exact list of options is
-c peg
And now the recognized options and their arguments, if they have any:
- __--help__
- __-h__
- __-?__
When one of these options is found on the command line all arguments coming
before or after are ignored. The application will print a short description
of the recognized options and exit.
- __--version__
- __-V__
When one of these options is found on the command line all arguments coming
before or after are ignored. The application will print its own revision and
exit.
- __-P__
This option signals the application to activate visual feedback while
reading the input.
- __-T__
This option signals the application to collect statistics while reading the
input and to print them after reading has completed, before processing
started.
- __-D__
This option signals the application to activate logging in the Safe base,
for the debugging of problems with plugins.
- __-r__ parser
- __-rd__ parser
- __--reader__ parser
These options specify the plugin the application has to use for reading the
*input*. If the options are used multiple times the last one will be used.
- __-w__ generator
- __-wr__ generator
- __--writer__ generator
These options specify the plugin the application has to use for generating
and writing the final *output*. If the options are used multiple times the
last one will be used.
- __-t__ process
- __-tr__ process
- __--transform__ process
These options specify a plugin to run on the input. In contrast to readers
and writers each use will *not* supersede previous uses, but add each chosen
plugin to a list of transformations, either at the front, or the end, per
the last seen use of either option __-p__ or __-a__. The initial default is
to append the new transformations.
- __-a__
- __--append__
These options signal the application that all following transformations
should be added at the end of the list of transformations.
- __-p__
- __--prepend__
These options signal the application that all following transformations
should be added at the beginning of the list of transformations.
- __--reset__
This option signals the application to clear the list of transformations.
This is necessary to wipe out the default transformations used.
- __-c__ file
- __--configuration__ file
This option causes the application to load a configuration file and/or
plugin. This is a plugin which in essence provides a pre-defined set of
commandline options. They are processed exactly as if they have been
specified in place of the option and its arguments. This means that unknown
options found at the beginning of the configuration file are associated with
the last plugin, even if that plugin was specified before the configuration
file itself. Conversely, unknown options coming after the configuration file
can be associated with a plugin specified in the file.
If the argument is a file which cannot be loaded as a plugin the application
will assume that its contents are a list of options and their arguments,
separated by space, tabs, and newlines. Options and argumentes containing
spaces can be quoted via double-quotes (") and quotes ('). The quote
character can be specified within in a quoted string by doubling it.
Newlines in a quoted string are accepted as is.
## <a name='subsection4'></a>PLUGINS
__page__ makes use of four different types of plugins, namely: readers, writers,
transformations, and configurations. Here we provide only a basic introduction
on how to use them from __page__. The exact APIs provided to and expected from
the plugins can be found in the documentation for __page::pluginmgr__, for those
who wish to write their own plugins.
Plugins are specified as arguments to the options __-r__, __-w__, __-t__,
__-c__, and their equivalent longer forms. See the section
[OPTIONS](#subsection3) for reference.
Each such argument will be first treated as the name of a file and this file is
loaded as the plugin. If however there is no file with that name, then it will
be translated into the name of a package, and this package is then loaded. For
each type of plugins the package management searches not only the regular paths,
but a set application- and type-specific paths as well. Please see the section
[PLUGIN LOCATIONS](#subsection5) for a listing of all paths and their sources.
- __-c__ *name*
Configurations. The name of the package for the plugin *name* is
"page::config::*name*".
We have one predefined plugin:
* *peg*
It sets the application up as a parser generator accepting parsing
expression grammars and writing a packrat parser in Tcl. The actual
arguments it specifies are:
--reset
--append
--reader peg
--transform reach
--transform use
--writer me
- __-r__ *name*
Readers. The name of the package for the plugin *name* is
"page::reader::*name*".
We have five predefined plugins:
* *peg*
Interprets the input as a parsing expression grammar
(*[PEG](../../../index.md#peg)*) and generates a tree representation for
it. Both the syntax of PEGs and the structure of the tree representation
are explained in their own manpages.
* *hb*
Interprets the input as Tcl code as generated by the writer plugin *hb*
and generates its tree representation.
* *ser*
Interprets the input as the serialization of a PEG, as generated by the
writer plugin *ser*, using the package
__[grammar::peg](../modules/grammar_peg/peg.md)__.
* *lemon*
Interprets the input as a grammar specification as understood by Richard
Hipp's *[LEMON](../../../index.md#lemon)* parser generator and generates
a tree representation for it. Both the input syntax and the structure of
the tree representation are explained in their own manpages.
* *treeser*
Interprets the input as the serialization of a
__[struct::tree](../modules/struct/struct_tree.md)__. It is validated as
such, but nothing else. It is *not* assumed to be the tree
representation of a grammar.
- __-w__ *name*
Writers. The name of the package for the plugin *name* is
"page::writer::*name*".
We have eight predefined plugins:
* *identity*
Simply writes the incoming data as it is, without making any changes.
This is good for inspecting the raw result of a reader or
transformation.
* *null*
Generates nothing, and ignores the incoming data structure.
* *tree*
Assumes that the incoming data structure is a
__[struct::tree](../modules/struct/struct_tree.md)__ and generates an
indented textual representation of all nodes, their parental
relationships, and their attribute information.
* *peg*
Assumes that the incoming data structure is a tree representation of a
*[PEG](../../../index.md#peg)* or other other grammar and writes it out
as a PEG. The result is nicely formatted and partially simplified
(strings as sequences of characters). A pretty printer in essence, but
can also be used to obtain a canonical representation of the input
grammar.
* *tpc*
Assumes that the incoming data structure is a tree representation of a
*[PEG](../../../index.md#peg)* or other other grammar and writes out Tcl
code defining a package which defines a
__[grammar::peg](../modules/grammar_peg/peg.md)__ object containing the
grammar when it is loaded into an interpreter.
* *hb*
This is like the writer plugin *tpc*, but it writes only the statements
which define stat expression and grammar rules. The code making the
result a package is left out.
* *ser*
Assumes that the incoming data structure is a tree representation of a
*[PEG](../../../index.md#peg)* or other other grammar, transforms it
internally into a __[grammar::peg](../modules/grammar_peg/peg.md)__
object and writes out its serialization.
* *me*
Assumes that the incoming data structure is a tree representation of a
*[PEG](../../../index.md#peg)* or other other grammar and writes out Tcl
code defining a package which implements a memoizing recursive descent
parser based on the match engine (ME) provided by the package
__grammar::mengine__.
- __-t__ *name*
Transformers. The name of the package for the plugin *name* is
"page::transform::*name*".
We have two predefined plugins:
* *reach*
Assumes that the incoming data structure is a tree representation of a
*[PEG](../../../index.md#peg)* or other other grammar. It determines
which nonterminal symbols and rules are reachable from
start-symbol/expression. All nonterminal symbols which were not reached
are removed.
* *use*
Assumes that the incoming data structure is a tree representation of a
*[PEG](../../../index.md#peg)* or other other grammar. It determines
which nonterminal symbols and rules are able to generate a *finite*
sequences of terminal symbols (in the sense for a Context Free Grammar).
All nonterminal symbols which were not deemed useful in this sense are
removed.
## <a name='subsection5'></a>PLUGIN LOCATIONS
The application-specific paths searched by __page__ either are, or come from:
1. The directory "~/.page/plugin"
1. The environment variable *PAGE_PLUGINS*
1. The registry entry *HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\PLUGINS*
1. The registry entry *HKEY_CURRENT_USER\SOFTWARE\PAGE\PLUGINS*
The type-specific paths searched by __page__ either are, or come from:
1. The directory "~/.page/plugin/<TYPE>"
1. The environment variable *PAGE_<TYPE>_PLUGINS*
1. The registry entry *HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\<TYPE>\PLUGINS*
1. The registry entry *HKEY_CURRENT_USER\SOFTWARE\PAGE\<TYPE>\PLUGINS*
Where the placeholder *<TYPE>* is always one of the values below, properly
capitalized.
1. reader
1. writer
1. transform
1. config
The registry entries are specific to the Windows(tm) platform, all other
platforms will ignore them.
The contents of both environment variables and registry entries are interpreted
as a list of paths, with the elements separated by either colon (Unix), or
semicolon (Windows).
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='see-also'></a>SEE ALSO
page::pluginmgr
# <a name='keywords'></a>KEYWORDS
[parser generator](../../../index.md#parser_generator), [text
processing](../../../index.md#text_processing)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/apps/pt.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
|
[//000000001]: # (pt - Parser Tools)
[//000000002]: # (Generated from file 'pt.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt(n) 1 tcllib "Parser Tools")
# NAME
pt - Parser Tools Application
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Command Line](#section2)
- [PEG Specification Language](#section3)
- [JSON Grammar Exchange](#section4)
- [C Parser Embedded In Tcl](#section5)
- [C Parser](#section6)
- [Snit Parser](#section7)
- [TclOO Parser](#section8)
- [Grammar Container](#section9)
- [Example](#section10)
- [Internals](#section11)
- [Bugs, Ideas, Feedback](#section12)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
[__pt__ __generate__ *resultformat* ?*options...*? *resultfile* *inputformat* *inputfile*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](../modules/pt/pt_introduction.md)*. This document is the entrypoint to
the whole system the current package is a part of.
This document describes __pt__, the main application of the module, a *[parser
generator](../../../index.md#parser_generator)*. Its intended audience are
people who wish to create a parser for some language of theirs. Should you wish
to modify the application instead, please see the section about the
application's [Internals](#section11) for the basic references.
It resides in the User Application Layer of Parser Tools.
# <a name='section2'></a>Command Line
- <a name='1'></a>__pt__ __generate__ *resultformat* ?*options...*? *resultfile* *inputformat* *inputfile*
This sub-command of the application reads the parsing expression grammar
stored in the *inputfile* in the format *inputformat*, converts it to the
*resultformat* under the direction of the (format-specific) set of options
specified by the user and stores the result in the *resultfile*.
The *inputfile* has to exist, while the *resultfile* may be created,
overwriting any pre-existing content of the file. Any missing directory in
the path to the *resultfile* will be created as well.
The exact form of the result for, and the set of options supported by the
known result-formats, are explained in the upcoming sections of this
document, with the list below providing an index mapping between format name
and its associated section. In alphabetical order:
* __c__
A *resultformat*. See section [C Parser](#section6).
* __container__
A *resultformat*. See section [Grammar Container](#section9).
* __critcl__
A *resultformat*. See section [C Parser Embedded In Tcl](#section5).
* __json__
A *input*- and *resultformat*. See section [JSON Grammar
Exchange](#section4).
* __oo__
A *resultformat*. See section [TclOO Parser](#section8).
* __peg__
A *input*- and *resultformat*. See section [PEG Specification
Language](#section3).
* __snit__
A *resultformat*. See section [Snit Parser](#section7).
Of the seven possible results four are parsers outright (__c__, __critcl__,
__oo__, and __snit__), one (__container__) provides code which can be used in
conjunction with a generic parser (also known as a grammar interpreter), and the
last two (__json__ and __peg__) are doing double-duty as input formats, allowing
the transformation of grammars for exchange, reformatting, and the like.
The created parsers fall into three categories:
- __Specialized parsers implemented in C__
The fastest parsers are created when using the result formats __c__ and
__critcl__. The first returns the raw C code for the parser, while the
latter wraps it into a Tcl package using *CriTcl*.
This makes the latter much easier to use than the former. On the other hand,
the former can be adapted to the users' requirements through a multitude of
options, allowing for things like usage of the parser outside of a Tcl
environment, something the __critcl__ format doesn't support. As such the
__c__ format is meant for more advanced users, or users with special needs.
A disadvantage of all the parsers in this section is the need to run them
through a C compiler to make them actually executable. This is not something
everyone has the necessary tools for. The parsers in the next section are
for people under such restrictions.
- __Specialized parsers implemented in Tcl__
As the parsers in this section are implemented in Tcl they are quite a bit
slower than anything from the previous section. On the other hand this
allows them to be used in pure-Tcl environments, or in environments which
allow only a limited set of binary packages. In the latter case it will be
advantageous to lobby for the inclusion of the C-based runtime support
(notes below) into the environment to reduce the impact of Tcl's on the
speed of these parsers.
The relevant formats are __snit__ and __oo__. Both place their result into a
Tcl package containing a __snit::type__, or TclOO
__[class](../../../index.md#class)__ respectively.
Of the supporting runtime, which is the package
__[pt::rde](../modules/pt/pt_rdengine.md)__, the user has to know nothing
but that it does exist and that the parsers are dependent on it. Knowledge
of the API exported by the runtime for the parsers' consumption is *not*
required by the parsers' users.
- __Interpreted parsing implemented in Tcl__
The last category, grammar interpretation. This means that an interpreter
for parsing expression grammars takes the description of the grammar to
parse input for, and uses it guide the parsing process. This is the slowest
of the available options, as the interpreter has to continually run through
the configured grammar, whereas the specialized parsers of the previous
sections have the relevant knowledge about the grammar baked into them.
The only places where using interpretation make sense is where the grammar
for some input may be changed interactively by the user, as the
interpretation allows for quick turnaround after each change, whereas the
previous methods require the generation of a whole new parser, which is not
as fast. On the other hand, wherever the grammar to use is fixed, the
previous methods are much more advantageous as the time to generate the
parser is minuscule compared to the time the parser code is in use.
The relevant result format is __container__. It (quickly) generates grammar
descriptions (instead of a full parser) which match the API expected by
ParserTools' grammar interpreter. The latter is provided by the package
__[pt::peg::interp](../modules/pt/pt_peg_interp.md)__.
All the parsers generated by __critcl__, __snit__, and __oo__, and the grammar
interpreter share a common API for access to the actual parsing functionality,
making them all plug-compatible. It is described in the *[Parser
API](../modules/pt/pt_parser_api.md)* specification document.
# <a name='section3'></a>PEG Specification Language
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
For either an introduction to or the formal specification of the language,
please go and read the *[PEG Language
Tutorial](../modules/pt/pt_peg_language.md)*.
When used as a result-format this format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-template__ string
The value of this option is a string into which to put the generated text
and the values of the other options. The various locations for user-data are
expected to be specified with the placeholders listed below. The default
value is "__@code@__".
* __@user@__
To be replaced with the value of the option __-user__.
* __@format@__
To be replaced with the the constant __PEG__.
* __@file@__
To be replaced with the value of the option __-file__.
* __@name@__
To be replaced with the value of the option __-name__.
* __@code@__
To be replaced with the generated text.
# <a name='section4'></a>JSON Grammar Exchange
The __json__ format for parsing expression grammars was written as a data
exchange format not bound to Tcl. It was defined to allow the exchange of
grammars with PackRat/PEG based parser generators for other languages.
For the formal specification of the JSON grammar exchange format, please go and
read *[The JSON Grammar Exchange Format](../modules/pt/pt_json_language.md)*.
When used as a result-format this format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-indented__ boolean
If this option is set the system will break the generated JSON across lines
and indent it according to its inner structure, with each key of a
dictionary on a separate line.
If the option is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.
- __-aligned__ boolean
If this option is set the system will ensure that the values for the keys in
a dictionary are vertically aligned with each other, for a nice table
effect. To make this work this also implies that __-indented__ is set.
If the option is not set (the default), the output is formatted as per the
value of __indented__, without trying to align the values for dictionary
keys.
# <a name='section5'></a>C Parser Embedded In Tcl
The __critcl__ format is executable code, a parser for the grammar. It is a Tcl
package with the actual parser implementation written in C and embedded in Tcl
via the __critcl__ package.
This result-format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-class__ string
The value of this option is the name of the class to generate, without
leading colons. The default value is __CLASS__.
For a simple value __X__ without colons, like CLASS, the parser command will
be __X__::__X__. Whereas for a namespaced value __X::Y__ the parser command
will be __X::Y__.
- __-package__ string
The value of this option is the name of the package to generate. The default
value is __PACKAGE__.
- __-version__ string
The value of this option is the version of the package to generate. The
default value is __1__.
# <a name='section6'></a>C Parser
The __c__ format is executable code, a parser for the grammar. The parser
implementation is written in C and can be tweaked to the users' needs through a
multitude of options.
The __critcl__ format, for example, is implemented as a canned configuration of
these options on top of the generator for __c__.
This result-format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-template__ string
The value of this option is a string into which to put the generated text
and the other configuration settings. The various locations for user-data
are expected to be specified with the placeholders listed below. The default
value is "__@code@__".
* __@user@__
To be replaced with the value of the option __-user__.
* __@format@__
To be replaced with the the constant __C/PARAM__.
* __@file@__
To be replaced with the value of the option __-file__.
* __@name@__
To be replaced with the value of the option __-name__.
* __@code@__
To be replaced with the generated Tcl code.
The following options are special, in that they will occur within the
generated code, and are replaced there as well.
* __@statedecl@__
To be replaced with the value of the option __state-decl__.
* __@stateref@__
To be replaced with the value of the option __state-ref__.
* __@strings@__
To be replaced with the value of the option __string-varname__.
* __@self@__
To be replaced with the value of the option __self-command__.
* __@def@__
To be replaced with the value of the option __fun-qualifier__.
* __@ns@__
To be replaced with the value of the option __namespace__.
* __@main@__
To be replaced with the value of the option __main__.
* __@prelude@__
To be replaced with the value of the option __prelude__.
- __-state-decl__ string
A C string representing the argument declaration to use in the generated
parsing functions to refer to the parsing state. In essence type and
argument name. The default value is the string __RDE_PARAM p__.
- __-state-ref__ string
A C string representing the argument named used in the generated parsing
functions to refer to the parsing state. The default value is the string
__p__.
- __-self-command__ string
A C string representing the reference needed to call the generated parser
function (methods ...) from another parser fonction, per the chosen
framework (template). The default value is the empty string.
- __-fun-qualifier__ string
A C string containing the attributes to give to the generated functions
(methods ...), per the chosen framework (template). The default value is
__static__.
- __-namespace__ string
The name of the C namespace the parser functions (methods, ...) shall reside
in, or a general prefix to add to the function names. The default value is
the empty string.
- __-main__ string
The name of the main function (method, ...) to be called by the chosen
framework (template) to start parsing input. The default value is
____main__.
- __-string-varname__ string
The name of the variable used for the table of strings used by the generated
parser, i.e. error messages, symbol names, etc. The default value is
__p_string__.
- __-prelude__ string
A snippet of code to be inserted at the head of each generated parsing
function. The default value is the empty string.
- __-indent__ integer
The number of characters to indent each line of the generated code by. The
default value is __0__.
- __-comments__ boolean
A flag controlling the generation of code comments containing the original
parsing expression a parsing function is for. The default value is __on__.
# <a name='section7'></a>Snit Parser
The __snit__ format is executable code, a parser for the grammar. It is a Tcl
package holding a __snit::type__, i.e. a class, whose instances are parsers for
the input grammar.
This result-format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-class__ string
The value of this option is the name of the class to generate, without
leading colons. Note, it serves double-duty as the name of the package to
generate too, if option __-package__ is not specified, see below. The
default value is __CLASS__, applying if neither option __-class__ nor
__-package__ were specified.
- __-package__ string
The value of this option is the name of the package to generate, without
leading colons. Note, it serves double-duty as the name of the class to
generate too, if option __-class__ is not specified, see above. The default
value is __PACKAGE__, applying if neither option __-package__ nor __-class__
were specified.
- __-version__ string
The value of this option is the version of the package to generate. The
default value is __1__.
# <a name='section8'></a>TclOO Parser
The __oo__ format is executable code, a parser for the grammar. It is a Tcl
package holding a __[TclOO](../../../index.md#tcloo)__ class, whose instances
are parsers for the input grammar.
This result-format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-class__ string
The value of this option is the name of the class to generate, without
leading colons. Note, it serves double-duty as the name of the package to
generate too, if option __-package__ is not specified, see below. The
default value is __CLASS__, applying if neither option __-class__ nor
__-package__ were specified.
- __-package__ string
The value of this option is the name of the package to generate, without
leading colons. Note, it serves double-duty as the name of the class to
generate too, if option __-class__ is not specified, see above. The default
value is __PACKAGE__, applying if neither option __-package__ nor __-class__
were specified.
- __-version__ string
The value of this option is the version of the package to generate. The
default value is __1__.
# <a name='section9'></a>Grammar Container
The __container__ format is another form of describing parsing expression
grammars. While data in this format is executable it does not constitute a
parser for the grammar. It always has to be used in conjunction with the package
__[pt::peg::interp](../modules/pt/pt_peg_interp.md)__, a grammar interpreter.
The format represents grammars by a __snit::type__, i.e. class, whose instances
are API-compatible to the instances of the
__[pt::peg::container](../modules/pt/pt_peg_container.md)__ package, and which
are preloaded with the grammar in question.
This result-format supports the following options:
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-mode__ __bulk__|__incremental__
The value of this option controls which methods of
__[pt::peg::container](../modules/pt/pt_peg_container.md)__ instances are
used to specify the grammar, i.e. preload it into the container. There are
two legal values, as listed below. The default is __bulk__.
* __bulk__
In this mode the methods __start__, __add__, __modes__, and __rules__
are used to specify the grammar in a bulk manner, i.e. as a set of
nonterminal symbols, and two dictionaries mapping from the symbols to
their semantic modes and parsing expressions.
This mode is the default.
* __incremental__
In this mode the methods __start__, __add__, __mode__, and __rule__ are
used to specify the grammar piecemal, with each nonterminal having its
own block of defining commands.
- __-template__ string
The value of this option is a string into which to put the generated code
and the other configuration settings. The various locations for user-data
are expected to be specified with the placeholders listed below. The default
value is "__@code@__".
* __@user@__
To be replaced with the value of the option __-user__.
* __@format@__
To be replaced with the the constant __CONTAINER__.
* __@file@__
To be replaced with the value of the option __-file__.
* __@name@__
To be replaced with the value of the option __-name__.
* __@mode@__
To be replaced with the value of the option __-mode__.
* __@code@__
To be replaced with the generated code.
# <a name='section10'></a>Example
In this section we are working a complete example, starting with a PEG grammar
and ending with running the parser generated from it over some input, following
the outline shown in the figure below:
 Our grammar, assumed to the stored in the file
"calculator.peg" is
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
From this we create a snit-based parser via
pt generate snit calculator.tcl -class calculator -name calculator peg calculator.peg
which leaves us with the parser package and class written to the file
"calculator.tcl". Assuming that this package is then properly installed in a
place where Tcl can find it we can now use this class via a script like
package require calculator
lassign $argv input
set channel [open $input r]
set parser [calculator]
set ast [$parser parse $channel]
$parser destroy
close $channel
... now process the returned abstract syntax tree ...
where the abstract syntax tree stored in the variable will look like
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
assuming that the input file and channel contained the text
120+5
A more graphical representation of the tree would be
 Regardless, at this point it is the user's
responsibility to work with the tree to reach whatever goal she desires. I.e.
analyze it, transform it, etc. The package
__[pt::ast](../modules/pt/pt_astree.md)__ should be of help here, providing
commands to walk such ASTs structures in various ways.
One important thing to note is that the parsers used here return a data
structure representing the structure of the input per the grammar underlying the
parser. There are *no* callbacks during the parsing process, i.e. no *parsing
actions*, as most other parsers will have.
Going back to the last snippet of code, the execution of the parser for some
input, note how the parser instance follows the specified *[Parser
API](../modules/pt/pt_parser_api.md)*.
# <a name='section11'></a>Internals
This section is intended for users of the application which wish to modify or
extend it. Users only interested in the generation of parsers can ignore it.
The main functionality of the application is encapsulated in the package
__[pt::pgen](../modules/pt/pt_pgen.md)__. Please read it for more information.
# <a name='section12'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../index.md#ebnf), [LL(k)](../../../index.md#ll_k_),
[PEG](../../../index.md#peg), [TDPL](../../../index.md#tdpl), [context-free
languages](../../../index.md#context_free_languages),
[expression](../../../index.md#expression),
[grammar](../../../index.md#grammar), [matching](../../../index.md#matching),
[parser](../../../index.md#parser), [parsing
expression](../../../index.md#parsing_expression), [parsing expression
grammar](../../../index.md#parsing_expression_grammar), [push down
automaton](../../../index.md#push_down_automaton), [recursive
descent](../../../index.md#recursive_descent), [state](../../../index.md#state),
[top-down parsing languages](../../../index.md#top_down_parsing_languages),
[transducer](../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/apps/tcldocstrip.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
[//000000001]: # (tcldocstrip - Textprocessing toolbox)
[//000000002]: # (Generated from file 'tcldocstrip.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox")
# NAME
tcldocstrip - Tcl-based Docstrip Processor
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USE CASES](#subsection1)
- [COMMAND LINE](#subsection2)
- [OPTIONS](#subsection3)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__tcldocstrip__ *output* ?options? *input* ?*guards*?](#1)
[__tcldocstrip__ ?options? *output* (?options? *input* *guards*)...](#2)
[__tcldocstrip__ __-guards__ *input*](#3)
# <a name='description'></a>DESCRIPTION
The application described by this document, __tcldocstrip__, is a relative of
__[docstrip](../modules/docstrip/docstrip.md)__, a simple literate programming
tool for LaTeX.
__tcldocstrip__ is based upon the package
__[docstrip](../modules/docstrip/docstrip.md)__.
## <a name='subsection1'></a>USE CASES
__tcldocstrip__ was written with the following three use cases in mind.
1. Conversion of a single input file according to the listed guards into the
stripped output. This handles the most simple case of a set of guards
specifying a single document found in a single input file.
1. Stitching, or the assembly of an output from several sets of guards, in a
specific order, and possibly from different files. This is the second
common case. One document spread over several inputs, and/or spread over
different guard sets.
1. Extraction and listing of all the unique guard expressions and guards used
within a document to help a person which did not author the document in
question in familiarizing itself with it.
## <a name='subsection2'></a>COMMAND LINE
- <a name='1'></a>__tcldocstrip__ *output* ?options? *input* ?*guards*?
This is the form for use case [1]. It converts the *input* file according to
the specified *guards* and options. The result is written to the named
*output* file. Usage of the string __-__ as the name of the output signals
that the result should be written to __stdout__. The guards are
document-specific and have to be known to the caller. The *options* will be
explained later, in section [OPTIONS](#subsection3).
* path *output* (in)
This argument specifies where to write the generated document. It can be
the path to a file or directory, or __-__. The last value causes the
application to write the generated documented to __stdout__.
If the *output* does not exist then [file dirname $output] has to exist
and must be a writable directory.
* path *inputfile* (in)
This argument specifies the path to the file to process. It has to
exist, must be readable, and written in
*[docstrip](../../../index.md#docstrip)* format.
- <a name='2'></a>__tcldocstrip__ ?options? *output* (?options? *input* *guards*)...
This is the form for use case [2]. It differs from the form for use case [1]
by the possibility of having options before the output file, which apply in
general, and specifying more than one inputfile, each with its own set of
input specific options and guards.
It extracts data from the various *input* files, according to the specified
*options* and *guards*, and writes the result to the given *output*, in the
order of their specification on the command line. Options specified before
the output are global settings, whereas the options specified before each
input are valid only just for this input file. Unspecified values are taken
from the global settings, or defaults. As for form [1] using the string
__-__ as output causes the application to write to stdout. Using the string
__.__ for an input file signals that the last input file should be used
again. This enables the assembly of the output from one input file using
multiple and different sets of guards, without having to specify the full
name of the file every time.
- <a name='3'></a>__tcldocstrip__ __-guards__ *input*
This is the form for use case [3]. It determines the guards, and unique
guard expressions used within the provided *input* document. The found
strings are written to stdout, one string per line.
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application,
with the exception of the option __-guards__. This option was described already,
in section [COMMAND LINE](#subsection2).
- __-metaprefix__ string
This option is inherited from the command __docstrip::extract__ provided by
the package __[docstrip](../modules/docstrip/docstrip.md)__.
It specifies the string by which the '%%' prefix of a metacomment line will
be replaced. Defaults to '%%'. For Tcl code this would typically be '#'.
- __-onerror__ mode
This option is inherited from the command __docstrip::extract__ provided by
the package __[docstrip](../modules/docstrip/docstrip.md)__.
It controls what will be done when a format error in the *text* being
processed is detected. The settings are:
* __ignore__
Just ignore the error; continue as if nothing happened.
* __puts__
Write an error message to __stderr__, then continue processing.
* __throw__
Throw an error. __::errorCode__ is set to a list whose first element is
__DOCSTRIP__, second element is the type of error, and third element is
the line number where the error is detected. This is the default.
- __-trimlines__ bool
This option is inherited from the command __docstrip::extract__ provided by
the package __[docstrip](../modules/docstrip/docstrip.md)__.
Controls whether *spaces* at the end of a line should be trimmed away before
the line is processed. Defaults to __true__.
- __-preamble__ text
- __-postamble__ text
- __-nopreamble__
- __-nopostamble__
The -no*amble options deactivate file pre- and postambles altogether,
whereas the -*amble options specify the *user* part of the file pre- and
postambles. This part can be empty, in that case only the standard parts are
shown. This is the default.
Preambles, when active, are written before the actual content of a generated
file. In the same manner postambles are, when active, written after the
actual content of a generated file.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *docstrip* 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.
# <a name='see-also'></a>SEE ALSO
[docstrip](../modules/docstrip/docstrip.md)
# <a name='keywords'></a>KEYWORDS
[.dtx](../../../index.md#_dtx), [LaTeX](../../../index.md#latex),
[conversion](../../../index.md#conversion),
[docstrip](../../../index.md#docstrip),
[documentation](../../../index.md#documentation), [literate
programming](../../../index.md#literate_programming),
[markup](../../../index.md#markup), [source](../../../index.md#source)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/aes/aes.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
[//000000001]: # (aes - Advanced Encryption Standard (AES))
[//000000002]: # (Generated from file 'aes.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (aes(n) 1.2.1 tcllib "Advanced Encryption Standard (AES)")
# NAME
aes - Implementation of the AES block cipher
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [MODES OF OPERATION](#section4)
- [EXAMPLES](#section5)
- [REFERENCES](#section6)
- [AUTHORS](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require aes ?1.2.1?
[__::aes::aes__ ?*-mode [ecb|cbc]*? ?*-dir [encrypt|decrypt]*? *-key keydata* ?*-iv vector*? ?*-hex*? ?*-out channel*? ?*-chunksize size*? [ *-in channel* | ?__--__? *data* ]](#1)
[__::aes::Init__ *mode* *keydata* *iv*](#2)
[__::aes::Encrypt__ *Key* *data*](#3)
[__::aes::Decrypt__ *Key* *data*](#4)
[__::aes::Reset__ *Key* *iv*](#5)
[__::aes::Final__ *Key*](#6)
# <a name='description'></a>DESCRIPTION
This is an implementation in Tcl of the Advanced Encryption Standard (AES) as
published by the U.S. National Institute of Standards and Technology [1]. AES is
a 128-bit block cipher with a variable key size of 128, 192 or 256 bits. This
implementation supports ECB and CBC modes.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::aes::aes__ ?*-mode [ecb|cbc]*? ?*-dir [encrypt|decrypt]*? *-key keydata* ?*-iv vector*? ?*-hex*? ?*-out channel*? ?*-chunksize size*? [ *-in channel* | ?__--__? *data* ]
Perform the __aes__ algorithm on either the data provided by the argument or
on the data read from the *-in* channel. If an *-out* channel is given then
the result will be written to this channel.
The *-key* option must be given. This parameter takes a binary string of
either 16, 24 or 32 bytes in length and is used to generate the key
schedule.
The *-mode* and *-dir* options are optional and default to cbc mode and
encrypt respectively. The initialization vector *-iv* takes a 16 byte binary
argument which defaults to all zeros. See [MODES OF OPERATION](#section4)
for more about available modes and their uses.
AES is a 128-bit block cipher. This means that the data must be provided in
units that are a multiple of 16 bytes.
# <a name='section3'></a>PROGRAMMING INTERFACE
Internal state is maintained in an opaque structure that is returned from the
__Init__ function. In ECB mode the state is not affected by the input but for
CBC mode some input dependent state is maintained and may be reset by calling
the __Reset__ function with a new initialization vector value.
- <a name='2'></a>__::aes::Init__ *mode* *keydata* *iv*
Construct a new AES key schedule using the specified key data and the given
initialization vector. The initialization vector is not used with ECB mode
but is important for CBC mode. See [MODES OF OPERATION](#section4) for
details about cipher modes.
- <a name='3'></a>__::aes::Encrypt__ *Key* *data*
Use a prepared key acquired by calling __Init__ to encrypt the provided
data. The data argument should be a binary array that is a multiple of the
AES block size of 16 bytes. The result is a binary array the same size as
the input of encrypted data.
- <a name='4'></a>__::aes::Decrypt__ *Key* *data*
Decipher data using the key. Note that the same key may be used to encrypt
and decrypt data provided that the initialization vector is reset
appropriately for CBC mode.
- <a name='5'></a>__::aes::Reset__ *Key* *iv*
Reset the initialization vector. This permits the programmer to re-use a key
and avoid the cost of re-generating the key schedule where the same key data
is being used multiple times.
- <a name='6'></a>__::aes::Final__ *Key*
This should be called to clean up resources associated with *Key*. Once this
function has been called the key may not be used again.
# <a name='section4'></a>MODES OF OPERATION
- Electronic Code Book (ECB)
ECB is the basic mode of all block ciphers. Each block is encrypted
independently and so identical plain text will produce identical output when
encrypted with the same key. Any encryption errors will only affect a single
block however this is vulnerable to known plaintext attacks.
- Cipher Block Chaining (CBC)
CBC mode uses the output of the last block encryption to affect the current
block. An initialization vector of the same size as the cipher block size is
used to handle the first block. The initialization vector should be chosen
randomly and transmitted as the first block of the output. Errors in
encryption affect the current block and the next block after which the
cipher will correct itself. CBC is the most commonly used mode in software
encryption. This is the default mode of operation for this module.
# <a name='section5'></a>EXAMPLES
% set nil_block [string repeat \\0 16]
% aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block
66e94bd4ef8a2c3b884cfa59ca342b2e
set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv]
append ciphertext [aes::Encrypt $Key $plaintext]
append ciphertext [aes::Encrypt $Key $additional_plaintext]
aes::Final $Key
# <a name='section6'></a>REFERENCES
1. "Advanced Encryption Standard", Federal Information Processing Standards
Publication 197, 2001
([http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf](http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf))
# <a name='section7'></a>AUTHORS
Thorsten Schloermann, Pat Thoyts
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *aes* 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.
# <a name='see-also'></a>SEE ALSO
[blowfish(n)](../blowfish/blowfish.md), [des(n)](../des/des.md),
[md5(n)](../md5/md5.md), [sha1(n)](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[aes](../../../../index.md#aes), [block
cipher](../../../../index.md#block_cipher), [data
integrity](../../../../index.md#data_integrity),
[encryption](../../../../index.md#encryption),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005, Pat Thoyts <[email protected]>
Copyright © 2012-2014, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/amazon-s3/S3.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
|
[//000000001]: # (S3 - Amazon S3 Web Service Utilities)
[//000000002]: # (Generated from file 'S3.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (S3(n) 1.0.3 tcllib "Amazon S3 Web Service Utilities")
# NAME
S3 - Amazon S3 Web Service Interface
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [ERROR REPORTING](#section2)
- [COMMANDS](#section3)
- [LOW LEVEL COMMANDS](#section4)
- [HIGH LEVEL COMMANDS](#section5)
- [LIMITATIONS](#section6)
- [USAGE SUGGESTIONS](#section7)
- [FUTURE DEVELOPMENTS](#section8)
- [TLS Security Considerations](#section9)
- [Bugs, Ideas, Feedback](#section10)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require S3 ?1.0.3?
package require sha1 1.0
package require md5 2.0
package require base64 2.3
package require xsxp 1.0
[__S3::Configure__ ?__-reset__ *boolean*? ?__-retries__ *integer*? ?__-accesskeyid__ *idstring*? ?__-secretaccesskey__ *idstring*? ?__-service-access-point__ *FQDN*? ?__-use-tls__ *boolean*? ?__-default-compare__ *always|never|exists|missing|newer|date|checksum|different*? ?__-default-separator__ *string*? ?__-default-acl__ *private|public-read|public-read-write|authenticated-read|keep|calc*? ?__-default-bucket__ *bucketname*?](#1)
[__S3::SuggestBucket__ ?*name*?](#2)
[__S3::REST__ *dict*](#3)
[__S3::ListAllMyBuckets__ ?__-blocking__ *boolean*? ?__-parse-xml__ *xmlstring*? ?__-result-type__ *REST|xml|pxml|dict|names|owner*?](#4)
[__S3::PutBucket__ ?__-bucket__ *bucketname*? ?__-blocking__ *boolean*? ?__-acl__ *{}|private|public-read|public-read-write|authenticated-read*?](#5)
[__S3::DeleteBucket__ ?__-bucket__ *bucketname*? ?__-blocking__ *boolean*?](#6)
[__S3::GetBucket__ ?__-bucket__ *bucketname*? ?__-blocking__ *boolean*? ?__-parse-xml__ *xmlstring*? ?__-max-count__ *integer*? ?__-prefix__ *prefixstring*? ?__-delimiter__ *delimiterstring*? ?__-result-type__ *REST|xml|pxml|names|dict*?](#7)
[__S3::Put__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-file__ *filename*? ?__-content__ *contentstring*? ?__-acl__ *private|public-read|public-read-write|authenticated-read|calc|keep*? ?__-content-type__ *contenttypestring*? ?__-x-amz-meta-*__ *metadatatext*? ?__-compare__ *comparemode*?](#8)
[__S3::Get__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-compare__ *comparemode*? ?__-file__ *filename*? ?__-content__ *contentvarname*? ?__-timestamp__ *aws|now*? ?__-headers__ *headervarname*?](#9)
[__S3::Head__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-dict__ *dictvarname*? ?__-headers__ *headersvarname*? ?__-status__ *statusvarname*?](#10)
[__S3::GetAcl__ ?__-blocking__ *boolean*? ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-result-type__ *REST|xml|pxml*?](#11)
[__S3::PutAcl__ ?__-blocking__ *boolean*? ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-acl__ *new-acl*?](#12)
[__S3::Delete__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-status__ *statusvar*?](#13)
[__S3::Push__ ?__-bucket__ *bucketname*? __-directory__ *directoryname* ?__-prefix__ *prefixstring*? ?__-compare__ *comparemode*? ?__-x-amz-meta-*__ *metastring*? ?__-acl__ *aclcode*? ?__-delete__ *boolean*? ?__-error__ *throw|break|continue*? ?__-progress__ *scriptprefix*?](#14)
[__S3::Pull__ ?__-bucket__ *bucketname*? __-directory__ *directoryname* ?__-prefix__ *prefixstring*? ?__-blocking__ *boolean*? ?__-compare__ *comparemode*? ?__-delete__ *boolean*? ?__-timestamp__ *aws|now*? ?__-error__ *throw|break|continue*? ?__-progress__ *scriptprefix*?](#15)
[__S3::Toss__ ?__-bucket__ *bucketname*? __-prefix__ *prefixstring* ?__-blocking__ *boolean*? ?__-error__ *throw|break|continue*? ?__-progress__ *scriptprefix*?](#16)
# <a name='description'></a>DESCRIPTION
This package provides access to Amazon's Simple Storage Solution web service.
As a quick summary, Amazon Simple Storage Solution provides a for-fee web
service allowing the storage of arbitrary data as "resources" within "buckets"
online. See [http://www.amazonaws.com/](http://www.amazonaws.com/) for details
on that system. Access to the service is via HTTP (SOAP or REST). Much of this
documentation will not make sense if you're not familiar with the terms and
functionality of the Amazon S3 service.
This package provides services for reading and writing the data items via the
REST interface. It also provides some higher-level operations. Other packages in
the same distribution provide for even more functionality.
Copyright 2006 Darren New. All Rights Reserved. NO WARRANTIES OF ANY TYPE ARE
PROVIDED. COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS. This software is
licensed under essentially the same terms as Tcl. See LICENSE.txt for the terms.
# <a name='section2'></a>ERROR REPORTING
The error reporting from this package makes use of $errorCode to provide more
details on what happened than simply throwing an error. Any error caught by the
S3 package (and we try to catch them all) will return with an $errorCode being a
list having at least three elements. In all cases, the first element will be
"S3". The second element will take on one of six values, with that element
defining the value of the third and subsequent elements. S3::REST does not throw
an error, but rather returns a dictionary with the keys "error", "errorInfo",
and "errorCode" set. This allows for reliable background use. The possible
second elements are these:
- usage
The usage of the package is incorrect. For example, a command has been
invoked which requires the library to be configured before the library has
been configured, or an invalid combination of options has been specified.
The third element of $errorCode supplies the name of the parameter that was
wrong. The fourth usually provides the arguments that were actually supplied
to the throwing proc, unless the usage error isn't confined to a single
proc.
- local
Something happened on the local system which threw an error. For example, a
request to upload or download a file was made and the file permissions
denied that sort of access. The third element of $errorCode is the original
$errorCode.
- socket
Something happened with the socket. It closed prematurely, or some other
condition of failure-to-communicate-with-Amazon was detected. The third
element of $errorCode is the original $errorCode, or sometimes the message
from fcopy, or ...?
- remote
The Amazon web service returned an error code outside the 2xx range in the
HTTP header. In other words, everything went as documented, except this
particular case was documented not to work. The third element is the
dictionary returned from __::S3::REST__. Note that S3::REST itself never
throws this error, but just returns the dictionary. Most of the higher-level
commands throw for convenience, unless an argument indicates they should
not. If something is documented as "not throwing an S3 remote error", it
means a status return is set rather than throwing an error if Amazon returns
a non-2XX HTTP result code.
- notyet
The user obeyed the documentation, but the author has not yet gotten around
to implementing this feature. (Right now, only TLS support and sophisticated
permissions fall into this category, as well as the S3::Acl command.)
- xml
The service has returned invalid XML, or XML whose schema is unexpected. For
the high-level commands that accept service XML as input for parsing, this
may also be thrown.
# <a name='section3'></a>COMMANDS
This package provides several separate levels of complexity.
- The lowest level simply takes arguments to be sent to the service, sends
them, retrieves the result, and provides it to the caller. *Note:* This
layer allows both synchronous and event-driven processing. It depends on the
MD5 and SHA1 and base64 packages from Tcllib (available at
[http://core.tcl.tk/tcllib/](http://core.tcl.tk/tcllib/)). Note that
__S3::Configure__ is required for __S3::REST__ to work due to the
authentication portion, so we put that in the "lowest level."
- The next layer parses the results of calls, allowing for functionality such
as uploading only changed files, synchronizing directories, and so on. This
layer depends on the __TclXML__ package as well as the included
__[xsxp](xsxp.md)__ package. These packages are package required when these
more-sophisticated routines are called, so nothing breaks if they are not
correctly installed.
- Also included is a separate program that uses the library. It provides code
to parse $argv0 and $argv from the command line, allowing invocation as a
tclkit, etc. (Not yet implmented.)
- Another separate program provides a GUI interface allowing drag-and-drop and
other such functionality. (Not yet implemented.)
- Also built on this package is the OddJob program. It is a separate program
designed to allow distribution of computational work units over Amazon's
Elastic Compute Cloud web service.
The goal is to have at least the bottom-most layers implemented in pure Tcl
using only that which comes from widely-available sources, such as Tcllib.
# <a name='section4'></a>LOW LEVEL COMMANDS
These commands do not require any packages not listed above. They talk directly
to the service, or they are utility or configuration routines. Note that the
"xsxp" package was written to support this package, so it should be available
wherever you got this package.
- <a name='1'></a>__S3::Configure__ ?__-reset__ *boolean*? ?__-retries__ *integer*? ?__-accesskeyid__ *idstring*? ?__-secretaccesskey__ *idstring*? ?__-service-access-point__ *FQDN*? ?__-use-tls__ *boolean*? ?__-default-compare__ *always|never|exists|missing|newer|date|checksum|different*? ?__-default-separator__ *string*? ?__-default-acl__ *private|public-read|public-read-write|authenticated-read|keep|calc*? ?__-default-bucket__ *bucketname*?
There is one command for configuration, and that is __S3::Configure__. If
called with no arguments, it returns a dictionary of key/value pairs listing
all current settings. If called with one argument, it returns the value of
that single argument. If called with two or more arguments, it must be
called with pairs of arguments, and it applies the changes in order. There
is only one set of configuration information per interpreter.
The following options are accepted:
* __-reset__ *boolean*
By default, false. If true, any previous changes and any changes on the
same call before the reset option will be returned to default values.
* __-retries__ *integer*
Default value is 3. If Amazon returns a 500 error, a retry after an
exponential backoff delay will be tried this many times before finally
throwing the 500 error. This applies to each call to __S3::REST__ from
the higher-level commands, but not to __S3::REST__ itself. That is,
__S3::REST__ will always return httpstatus 500 if that's what it
receives. Functions like __S3::Put__ will retry the PUT call, and will
also retry the GET and HEAD calls used to do content comparison.
Changing this to 0 will prevent retries and their associated delays. In
addition, socket errors (i.e., errors whose errorCode starts with "S3
socket") will be similarly retried after backoffs.
* __-accesskeyid__ *idstring*
* __-secretaccesskey__ *idstring*
Each defaults to an empty string. These must be set before any calls are
made. This is your S3 ID. Once you sign up for an account, go to
[http://www.amazonaws.com/](http://www.amazonaws.com/), sign in, go to
the "Your Web Services Account" button, pick "AWS Access Identifiers",
and your access key ID and secret access keys will be available. All
__S3::REST__ calls are authenticated. Blame Amazon for the poor choice
of names.
* __-service-access-point__ *FQDN*
Defaults to "s3.amazonaws.com". This is the fully-qualified domain name
of the server to contact for __S3::REST__ calls. You should probably
never need to touch this, unless someone else implements a compatible
service, or you wish to test something by pointing the library at your
own service.
* __-slop-seconds__ *integer*
When comparing dates between Amazon and the local machine, two dates
within this many seconds of each other are considered the same. Useful
for clock drift correction, processing overhead time, and so on.
* __-use-tls__ *boolean*
Defaults to false. This is not yet implemented. If true, __S3::REST__
will negotiate a TLS connection to Amazon. If false, unencrypted
connections are used.
* __-bucket-prefix__ *string*
Defaults to "TclS3". This string is used by __S3::SuggestBucketName__ if
that command is passed an empty string as an argument. It is used to
distinguish different applications using the Amazon service. Your
application should always set this to keep from interfering with the
buckets of other users of Amazon S3 or with other buckets of the same
user.
* __-default-compare__ *always|never|exists|missing|newer|date|checksum|different*
Defaults to "always." If no -compare is specified on __S3::Put__,
__S3::Get__, or __S3::Delete__, this comparison is used. See those
commands for a description of the meaning.
* __-default-separator__ *string*
Defaults to "/". This is currently unused. It might make sense to use
this for __S3::Push__ and __S3::Pull__, but allowing resources to have
slashes in their names that aren't marking directories would be
problematic. Hence, this currently does nothing.
* __-default-acl__ *private|public-read|public-read-write|authenticated-read|keep|calc*
Defaults to an empty string. If no -acl argument is provided to
__S3::Put__ or __S3::Push__, this string is used (given as the x-amz-acl
header if not keep or calc). If this is also empty, no x-amz-acl header
is generated. This is *not* used by __S3::REST__.
* __-default-bucket__ *bucketname*
If no bucket is given to __S3::GetBucket__, __S3::PutBucket__,
__S3::Get__, __S3::Put__, __S3::Head__, __S3::Acl__, __S3::Delete__,
__S3::Push__, __S3::Pull__, or __S3::Toss__, and if this configuration
variable is not an empty string (and not simply "/"), then this value
will be used for the bucket. This is useful if one program does a large
amount of resource manipulation within a single bucket.
- <a name='2'></a>__S3::SuggestBucket__ ?*name*?
The __S3::SuggestBucket__ command accepts an optional string as a prefix and
returns a valid bucket containing the *name* argument and the Access Key ID.
This makes the name unique to the owner and to the application (assuming the
application picks a good *name* argument). If no name is provided, the name
from __S3::Configure__ *-bucket-prefix* is used. If that too is empty (which
is not the default), an error is thrown.
- <a name='3'></a>__S3::REST__ *dict*
The __S3::REST__ command takes as an argument a dictionary and returns a
dictionary. The return dictionary has the same keys as the input dictionary,
and includes additional keys as the result. The presence or absence of keys
in the input dictionary can control the behavior of the routine. It never
throws an error directly, but includes keys "error", "errorInfo", and
"errorCode" if necessary. Some keys are required, some optional. The routine
can run either in blocking or non-blocking mode, based on the presense of
__resultvar__ in the input dictionary. This requires the *-accesskeyid* and
*-secretaccesskey* to be configured via __S3::Configure__ before being
called.
The possible input keys are these:
* __verb__ *GET|PUT|DELETE|HEAD*
This required item indicates the verb to be used.
* __resource__ *string*
This required item indicates the resource to be accessed. A leading / is
added if not there already. It will be URL-encoded for you if necessary.
Do not supply a resource name that is already URL-encoded.
* ?__rtype__ *torrent|acl*?
This indicates a torrent or acl resource is being manipulated. Do not
include this in the __resource__ key, or the "?" separator will get
URL-encoded.
* ?__parameters__ *dict*?
This optional dictionary provides parameters added to the URL for the
transaction. The keys must be in the correct case (which is confusing in
the Amazon documentation) and the values must be valid. This can be an
empty dictionary or omitted entirely if no parameters are desired. No
other error checking on parameters is performed.
* ?__headers__ *dict*?
This optional dictionary provides headers to be added to the HTTP
request. The keys must be in *lower case* for the authentication to
work. The values must not contain embedded newlines or carriage returns.
This is primarily useful for adding x-amz-* headers. Since
authentication is calculated by __S3::REST__, do not add that header
here. Since content-type gets its own key, also do not add that header
here.
* ?__inbody__ *contentstring*?
This optional item, if provided, gives the content that will be sent. It
is sent with a tranfer encoding of binary, and only the low bytes are
used, so use [encoding convertto utf-8] if the string is a utf-8 string.
This is written all in one blast, so if you are using non-blocking mode
and the __inbody__ is especially large, you may wind up blocking on the
write socket.
* ?__infile__ *filename*?
This optional item, if provided, and if __inbody__ is not provided,
names the file from which the body of the HTTP message will be
constructed. The file is opened for reading and sent progressively by
[fcopy], so it should not block in non-blocking mode even if the file is
very large. The file is transfered in binary mode, so the bytes on your
disk will match the bytes in your resource. Due to HTTP restrictions, it
must be possible to use [file size] on this file to determine the size
at the start of the transaction.
* ?__S3chan__ *channel*?
This optional item, if provided, indicates the already-open socket over
which the transaction should be conducted. If not provided, a connection
is made to the service access point specified via __S3::Configure__,
which is normally s3.amazonaws.com. If this is provided, the channel is
not closed at the end of the transaction.
* ?__outchan__ *channel*?
This optional item, if provided, indicates the already-open channel to
which the body returned from S3 should be written. That is, to retrieve
a large resource, open a file, set the translation mode, and pass the
channel as the value of the key outchan. Output will be written to the
channel in pieces so memory does not fill up unnecessarily. The channel
is not closed at the end of the transaction.
* ?__resultvar__ *varname*?
This optional item, if provided, indicates that __S3::REST__ should run
in non-blocking mode. The *varname* should be fully qualified with
respect to namespaces and cannot be local to a proc. If provided, the
result of the __S3::REST__ call is assigned to this variable once
everything has completed; use trace or vwait to know when this has
happened. If this key is not provided, the result is simply returned
from the call to __S3::REST__ and no calls to the eventloop are invoked
from within this call.
* ?__throwsocket__ *throw|return*?
This optional item, if provided, indicates that __S3::REST__ should
throw an error if throwmode is throw and a socket error is encountered.
It indicates that __S3::REST__ should return the error code in the
returned dictionary if a socket error is encountered and this is set to
return. If __throwsocket__ is set to *return* or if the call is not
blocking, then a socket error (i.e., an error whose error code starts
with "S3 socket" will be returned in the dictionary as __error__,
__errorInfo__, and __errorCode__. If a foreground call is made (i.e.,
__resultvar__ is not provided), and this option is not provided or is
set to *throw*, then __[error](../../../../index.md#error)__ will be
invoked instead.
Once the call to __S3::REST__ completes, a new dict is returned, either in
the *resultvar* or as the result of execution. This dict is a copy of the
original dict with the results added as new keys. The possible new keys are
these:
* __error__ *errorstring*
* __errorInfo__ *errorstring*
* __errorCode__ *errorstring*
If an error is caught, these three keys will be set in the result. Note
that __S3::REST__ does *not* consider a non-2XX HTTP return code as an
error. The __errorCode__ value will be formatted according to the [ERROR
REPORTING](#section2) description. If these are present, other keys
described here might not be.
* __httpstatus__ *threedigits*
The three-digit code from the HTTP transaction. 2XX for good, 5XX for
server error, etc.
* __httpmessage__ *text*
The textual result after the status code. "OK" or "Forbidden" or etc.
* __outbody__ *contentstring*
If *outchan* was not specified, this key will hold a reference to the
(unencoded) contents of the body returned. If Amazon returned an error
(a la the httpstatus not a 2XX value), the error message will be in
__outbody__ or written to __outchan__ as appropriate.
* __outheaders__ *dict*
This contains a dictionary of headers returned by Amazon. The keys are
always lower case. It's mainly useful for finding the x-amz-meta-*
headers, if any, although things like last-modified and content-type are
also useful. The keys of this dictionary are always lower case. Both
keys and values are trimmed of extraneous whitespace.
# <a name='section5'></a>HIGH LEVEL COMMANDS
The routines in this section all make use of one or more calls to __S3::REST__
to do their work, then parse and manage the data in a convenient way. All these
commands throw errors as described in [ERROR REPORTING](#section2) unless
otherwise noted.
In all these commands, all arguments are presented as name/value pairs, in any
order. All the argument names start with a hyphen.
There are a few options that are common to many of the commands, and those
common options are documented here.
- __-blocking__ *boolean*
If provided and specified as false, then any calls to __S3:REST__ will be
non-blocking, and internally these routines will call [vwait] to get the
results. In other words, these routines will return the same value, but
they'll have event loops running while waiting for Amazon.
- __-parse-xml__ *xmlstring*
If provided, the routine skips actually communicating with Amazon, and
instead behaves as if the XML string provided was returned as the body of
the call. Since several of these routines allow the return of data in
various formats, this argument can be used to parse existing XML to extract
the bits of information that are needed. It's also helpful for testing.
- __-bucket__ *bucketname*
Almost every high-level command needs to know what bucket the resources are
in. This option specifies that. (Only the command to list available buckets
does not require this parameter.) This does not need to be URL-encoded, even
if it contains special or non-ASCII characters. May or may not contain
leading or trailing spaces - commands normalize the bucket. If this is not
supplied, the value is taken from __S3::Configure -default-bucket__ if that
string isn't empty. Note that spaces and slashes are always trimmed from
both ends and the rest must leave a valid bucket.
- __-resource__ *resourcename*
This specifies the resource of interest within the bucket. It may or may not
start with a slash - both cases are handled. This does not need to be
URL-encoded, even if it contains special or non-ASCII characters.
- __-compare__ *always|never|exists|missing|newer|date|checksum|different*
When commands copy resources to files or files to resources, the caller may
specify that the copy should be skipped if the contents are the same. This
argument specifies the conditions under which the files should be copied. If
it is not passed, the result of __S3::Configure -default-compare__ is used,
which in turn defaults to "always." The meanings of the various values are
these:
* *always*
Always copy the data. This is the default.
* *never*
Never copy the data. This is essentially a no-op, except in __S3::Push__
and __S3::Pull__ where the -delete flag might make a difference.
* *exists*
Copy the data only if the destination already exists.
* *missing*
Copy the data only if the destination does not already exist.
* *newer*
Copy the data if the destination is missing, or if the date on the
source is newer than the date on the destination by at least
__S3::Configure -slop-seconds__ seconds. If the source is Amazon, the
date is taken from the Last-Modified header. If the source is local, it
is taken as the mtime of the file. If the source data is specified in a
string rather than a file, it is taken as right now, via [clock
seconds].
* *date*
Like *newer*, except copy if the date is newer *or* older.
* *checksum*
Calculate the MD5 checksum on the local file or string, ask Amazon for
the eTag of the resource, and copy the data if they're different. Copy
the data also if the destination is missing. Note that this can be slow
with large local files unless the C version of the MD5 support is
available.
* *different*
Copy the data if the destination does not exist. If the destination
exists and an actual file name was specified (rather than a content
string), and the date on the file differs from the date on the resource,
copy the data. If the data is provided as a content string, the "date"
is treated as "right now", so it will likely always differ unless
slop-seconds is large. If the dates are the same, the MD5 checksums are
compared, and the data is copied if the checksums differ.
Note that "newer" and "date" don't care about the contents, and "checksum"
doesn't care about the dates, but "different" checks both.
- <a name='4'></a>__S3::ListAllMyBuckets__ ?__-blocking__ *boolean*? ?__-parse-xml__ *xmlstring*? ?__-result-type__ *REST|xml|pxml|dict|names|owner*?
This routine performs a GET on the Amazon S3 service, which is defined to
return a list of buckets owned by the account identified by the
authorization header. (Blame Amazon for the dumb names.)
* __-blocking__ *boolean*
See above for standard definition.
* __-parse-xml__ *xmlstring*
See above for standard definition.
* __-result-type__ *REST*
The dictionary returned by __S3::REST__ is the return value of
__S3::ListAllMyBuckets__. In this case, a non-2XX httpstatus will not
throw an error. You may not combine this with *-parse-xml*.
* __-result-type__ *xml*
The raw XML of the body is returned as the result (with no encoding
applied).
* __-result-type__ *pxml*
The XML of the body as parsed by __xsxp::parse__ is returned.
* __-result-type__ *dict*
A dictionary of interesting portions of the XML is returned. The
dictionary contains the following keys:
+ Owner/ID
The Amazon AWS ID (in hex) of the owner of the bucket.
+ Owner/DisplayName
The Amazon AWS ID's Display Name.
+ Bucket/Name
A list of names, one for each bucket.
+ Bucket/CreationDate
A list of dates, one for each bucket, in the same order as
Bucket/Name, in ISO format (as returned by Amazon).
* __-result-type__ *names*
A list of bucket names is returned with all other information stripped
out. This is the default result type for this command.
* __-result-type__ *owner*
A list containing two elements is returned. The first element is the
owner's ID, and the second is the owner's display name.
- <a name='5'></a>__S3::PutBucket__ ?__-bucket__ *bucketname*? ?__-blocking__ *boolean*? ?__-acl__ *{}|private|public-read|public-read-write|authenticated-read*?
This command creates a bucket if it does not already exist. Bucket names are
globally unique, so you may get a "Forbidden" error from Amazon even if you
cannot see the bucket in __S3::ListAllMyBuckets__. See __S3::SuggestBucket__
for ways to minimize this risk. The x-amz-acl header comes from the __-acl__
option, or from __S3::Configure -default-acl__ if not specified.
- <a name='6'></a>__S3::DeleteBucket__ ?__-bucket__ *bucketname*? ?__-blocking__ *boolean*?
This command deletes a bucket if it is empty and you have such permission.
Note that Amazon's list of buckets is a global resource, requiring far-flung
synchronization. If you delete a bucket, it may be quite a few minutes (or
hours) before you can recreate it, yielding "Conflict" errors until then.
- <a name='7'></a>__S3::GetBucket__ ?__-bucket__ *bucketname*? ?__-blocking__ *boolean*? ?__-parse-xml__ *xmlstring*? ?__-max-count__ *integer*? ?__-prefix__ *prefixstring*? ?__-delimiter__ *delimiterstring*? ?__-result-type__ *REST|xml|pxml|names|dict*?
This lists the contents of a bucket. That is, it returns a directory listing
of resources within a bucket, rather than transfering any user data.
* __-bucket__ *bucketname*
The standard bucket argument.
* __-blocking__ *boolean*
The standard blocking argument.
* __-parse-xml__ *xmlstring*
The standard parse-xml argument.
* __-max-count__ *integer*
If supplied, this is the most number of records to be returned. If not
supplied, the code will iterate until all records have been found. Not
compatible with -parse-xml. Note that if this is supplied, only one call
to __S3::REST__ will be made. Otherwise, enough calls will be made to
exhaust the listing, buffering results in memory, so take care if you
may have huge buckets.
* __-prefix__ *prefixstring*
If present, restricts listing to resources with a particular prefix. One
leading / is stripped if present.
* __-delimiter__ *delimiterstring*
If present, specifies a delimiter for the listing. The presence of this
will summarize multiple resources into one entry, as if S3 supported
directories. See the Amazon documentation for details.
* __-result-type__ *REST|xml|pxml|names|dict*
This indicates the format of the return result of the command.
+ REST
If *-max-count* is specified, the dictionary returned from
__S3::REST__ is returned. If *-max-count* is not specified, a list
of all the dictionaries returned from the one or more calls to
__S3::REST__ is returned.
+ xml
If *-max-count* is specified, the body returned from __S3::REST__ is
returned. If *-max-count* is not specified, a list of all the bodies
returned from the one or more calls to __S3::REST__ is returned.
+ pxml
If *-max-count* is specified, the body returned from __S3::REST__ is
passed throught __xsxp::parse__ and then returned. If *-max-count*
is not specified, a list of all the bodies returned from the one or
more calls to __S3::REST__ are each passed through __xsxp::parse__
and then returned.
+ names
Returns a list of all names found in either the Contents/Key fields
or the CommonPrefixes/Prefix fields. If no *-delimiter* is specified
and no *-max-count* is specified, this returns a list of all
resources with the specified *-prefix*.
+ dict
Returns a dictionary. (Returns only one dictionary even if
*-max-count* wasn't specified.) The keys of the dictionary are as
follows:
- Name
The name of the bucket (from the final call to __S3::REST__).
- Prefix
From the final call to __S3::REST__.
- Marker
From the final call to __S3::REST__.
- MaxKeys
From the final call to __S3::REST__.
- IsTruncated
From the final call to __S3::REST__, so always false if
*-max-count* is not specified.
- NextMarker
Always provided if IsTruncated is true, and calculated of Amazon
does not provide it. May be empty if IsTruncated is false.
- Key
A list of names of resources in the bucket matching the
*-prefix* and *-delimiter* restrictions.
- LastModified
A list of times of resources in the bucket, in the same order as
Key, in the format returned by Amazon. (I.e., it is not parsed
into a seconds-from-epoch.)
- ETag
A list of entity tags (a.k.a. MD5 checksums) in the same order
as Key.
- Size
A list of sizes in bytes of the resources, in the same order as
Key.
- Owner/ID
A list of owners of the resources in the bucket, in the same
order as Key.
- Owner/DisplayName
A list of owners of the resources in the bucket, in the same
order as Key. These are the display names.
- CommonPrefixes/Prefix
A list of prefixes common to multiple entities. This is present
only if *-delimiter* was supplied.
- <a name='8'></a>__S3::Put__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-file__ *filename*? ?__-content__ *contentstring*? ?__-acl__ *private|public-read|public-read-write|authenticated-read|calc|keep*? ?__-content-type__ *contenttypestring*? ?__-x-amz-meta-*__ *metadatatext*? ?__-compare__ *comparemode*?
This command sends data to a resource on Amazon's servers for storage, using
the HTTP PUT command. It returns 0 if the __-compare__ mode prevented the
transfer, 1 if the transfer worked, or throws an error if the transfer was
attempted but failed. Server 5XX errors and S3 socket errors are retried
according to __S3:Configure -retries__ settings before throwing an error;
other errors throw immediately.
* __-bucket__
This specifies the bucket into which the resource will be written.
Leading and/or trailing slashes are removed for you, as are spaces.
* __-resource__
This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash. Spaces are not
trimmed.
* __-blocking__
The standard blocking flag.
* __-file__
If this is specified, the *filename* must exist, must be readable, and
must not be a special or directory file. [file size] must apply to it
and must not change for the lifetime of the call. The default
content-type is calculated based on the name and/or contents of the
file. Specifying this is an error if __-content__ is also specified, but
at least one of __-file__ or __-content__ must be specified. (The file
is allowed to not exist or not be readable if __-compare__ *never* is
specified.)
* __-content__
If this is specified, the *contentstring* is sent as the body of the
resource. The content-type defaults to "application/octet-string". Only
the low bytes are sent, so non-ASCII should use the appropriate encoding
(such as [encoding convertto utf-8]) before passing it to this routine,
if necessary. Specifying this is an error if __-file__ is also
specified, but at least one of __-file__ or __-content__ must be
specified.
* __-acl__
This defaults to __S3::Configure -default-acl__ if not specified. It
sets the x-amz-acl header on the PUT operation. If the value provided is
*calc*, the x-amz-acl header is calculated based on the I/O permissions
of the file to be uploaded; it is an error to specify *calc* and
__-content__. If the value provided is *keep*, the acl of the resource
is read before the PUT (or the default is used if the resource does not
exist), then set back to what it was after the PUT (if it existed). An
error will occur if the resource is successfully written but the kept
ACL cannot be then applied. This should never happen. *Note:* *calc* is
not currently fully implemented.
* __-x-amz-meta-*__
If any header starts with "-x-amz-meta-", its contents are added to the
PUT command to be stored as metadata with the resource. Again, no
encoding is performed, and the metadata should not contain characters
like newlines, carriage returns, and so on. It is best to stick with
simple ASCII strings, or to fix the library in several places.
* __-content-type__
This overrides the content-type calculated by __-file__ or sets the
content-type for __-content__.
* __-compare__
This is the standard compare mode argument. __S3::Put__ returns 1 if the
data was copied or 0 if the data was skipped due to the comparison mode
so indicating it should be skipped.
- <a name='9'></a>__S3::Get__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-compare__ *comparemode*? ?__-file__ *filename*? ?__-content__ *contentvarname*? ?__-timestamp__ *aws|now*? ?__-headers__ *headervarname*?
This command retrieves data from a resource on Amazon's S3 servers, using
the HTTP GET command. It returns 0 if the __-compare__ mode prevented the
transfer, 1 if the transfer worked, or throws an error if the transfer was
attempted but failed. Server 5XX errors and S3 socket errors are are retried
according to __S3:Configure__ settings before throwing an error; other
errors throw immediately. Note that this is always authenticated as the user
configured in via __S3::Configure -accesskeyid__. Use the Tcllib http for
unauthenticated GETs.
* __-bucket__
This specifies the bucket from which the resource will be read. Leading
and/or trailing slashes are removed for you, as are spaces.
* __-resource__
This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash. Spaces are not
trimmed.
* __-blocking__
The standard blocking flag.
* __-file__
If this is specified, the body of the resource will be read into this
file, incrementally without pulling it entirely into memory first. The
parent directory must already exist. If the file already exists, it must
be writable. If an error is thrown part-way through the process and the
file already existed, it may be clobbered. If an error is thrown
part-way through the process and the file did not already exist, any
partial bits will be deleted. Specifying this is an error if
__-content__ is also specified, but at least one of __-file__ or
__-content__ must be specified.
* __-timestamp__
This is only valid in conjunction with __-file__. It may be specified as
*now* or *aws*. The default is *now*. If *now*, the file's modification
date is left up to the system. If *aws*, the file's mtime is set to
match the Last-Modified header on the resource, synchronizing the two
appropriately for __-compare__ *date* or __-compare__ *newer*.
* __-content__
If this is specified, the *contentvarname* is a variable in the caller's
scope (not necessarily global) that receives the value of the body of
the resource. No encoding is done, so if the resource (for example)
represents a UTF-8 byte sequence, use [encoding convertfrom utf-8] to
get a valid UTF-8 string. If this is specified, the __-compare__ is
ignored unless it is *never*, in which case no assignment to
*contentvarname* is performed. Specifying this is an error if __-file__
is also specified, but at least one of __-file__ or __-content__ must be
specified.
* __-compare__
This is the standard compare mode argument. __S3::Get__ returns 1 if the
data was copied or 0 if the data was skipped due to the comparison mode
so indicating it should be skipped.
* __-headers__
If this is specified, the headers resulting from the fetch are stored in
the provided variable, as a dictionary. This will include content-type
and x-amz-meta-* headers, as well as the usual HTTP headers, the
x-amz-id debugging headers, and so on. If no file is fetched (due to
__-compare__ or other errors), no assignment to this variable is
performed.
- <a name='10'></a>__S3::Head__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-dict__ *dictvarname*? ?__-headers__ *headersvarname*? ?__-status__ *statusvarname*?
This command requests HEAD from the resource. It returns whether a 2XX code
was returned as a result of the request, never throwing an S3 remote error.
That is, if this returns 1, the resource exists and is accessible. If this
returns 0, something went wrong, and the __-status__ result can be consulted
for details.
* __-bucket__
This specifies the bucket from which the resource will be read. Leading
and/or trailing slashes are removed for you, as are spaces.
* __-resource__
This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash. Spaces are not
trimmed.
* __-blocking__
The standard blocking flag.
* __-dict__
If specified, the resulting dictionary from the __S3::REST__ call is
assigned to the indicated (not necessarily global) variable in the
caller's scope.
* __-headers__
If specified, the dictionary of headers from the result are assigned to
the indicated (not necessarily global) variable in the caller's scope.
* __-status__
If specified, the indicated (not necessarily global) variable in the
caller's scope is assigned a 2-element list. The first element is the
3-digit HTTP status code, while the second element is the HTTP message
(such as "OK" or "Forbidden").
- <a name='11'></a>__S3::GetAcl__ ?__-blocking__ *boolean*? ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-result-type__ *REST|xml|pxml*?
This command gets the ACL of the indicated resource or throws an error if it
is unavailable.
* __-blocking__ *boolean*
See above for standard definition.
* __-bucket__
This specifies the bucket from which the resource will be read. Leading
and/or trailing slashes are removed for you, as are spaces.
* __-resource__
This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash. Spaces are not
trimmed.
* __-parse-xml__ *xml*
The XML from a previous GetACL can be passed in to be parsed into
dictionary form. In this case, -result-type must be pxml or dict.
* __-result-type__ *REST*
The dictionary returned by __S3::REST__ is the return value of
__S3::GetAcl__. In this case, a non-2XX httpstatus will not throw an
error.
* __-result-type__ *xml*
The raw XML of the body is returned as the result (with no encoding
applied).
* __-result-type__ *pxml*
The XML of the body as parsed by __xsxp::parse__ is returned.
* __-result-type__ *dict*
This fetches the ACL, parses it, and returns a dictionary of two
elements.
The first element has the key "owner" whose value is the canonical ID of
the owner of the resource.
The second element has the key "acl" whose value is a dictionary. Each
key in the dictionary is one of Amazon's permissions, namely "READ",
"WRITE", "READ_ACP", "WRITE_ACP", or "FULL_CONTROL". Each value of each
key is a list of canonical IDs or group URLs that have that permission.
Elements are not in the list in any particular order, and not all keys
are necessarily present. Display names are not returned, as they are not
especially useful; use pxml to obtain them if necessary.
- <a name='12'></a>__S3::PutAcl__ ?__-blocking__ *boolean*? ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-acl__ *new-acl*?
This sets the ACL on the indicated resource. It returns the XML written to
the ACL, or throws an error if anything went wrong.
* __-blocking__ *boolean*
See above for standard definition.
* __-bucket__
This specifies the bucket from which the resource will be read. Leading
and/or trailing slashes are removed for you, as are spaces.
* __-resource__
This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash. Spaces are not
trimmed.
* __-owner__
If this is provided, it is assumed to match the owner of the resource.
Otherwise, a GET may need to be issued against the resource to find the
owner. If you already have the owner (such as from a call to
__S3::GetAcl__, you can pass the value of the "owner" key as the value
of this option, and it will be used in the construction of the XML.
* __-acl__
If this option is specified, it provides the ACL the caller wishes to
write to the resource. If this is not supplied or is empty, the value is
taken from __S3::Configure -default-acl__. The ACL is written with a PUT
to the ?acl resource.
If the value passed to this option starts with "<", it is taken to be a
body to be PUT to the ACL resource.
If the value matches one of the standard Amazon x-amz-acl headers (i.e.,
a canned access policy), that header is translated to XML and then
applied. The canned access policies are private, public-read,
public-read-write, and authenticated-read (in lower case).
Otherwise, the value is assumed to be a dictionary formatted as the
"acl" sub-entry within the dict returns by __S3::GetAcl -result-type
dict__. The proper XML is generated and applied to the resource. Note
that a value containing "//" is assumed to be a group, a value
containing "@" is assumed to be an AmazonCustomerByEmail, and otherwise
the value is assumed to be a canonical Amazon ID.
Note that you cannot change the owner, so calling GetAcl on a resource
owned by one user and applying it via PutAcl on a resource owned by
another user may not do exactly what you expect.
- <a name='13'></a>__S3::Delete__ ?__-bucket__ *bucketname*? __-resource__ *resourcename* ?__-blocking__ *boolean*? ?__-status__ *statusvar*?
This command deletes the specified resource from the specified bucket. It
returns 1 if the resource was deleted successfully, 0 otherwise. It returns
0 rather than throwing an S3 remote error.
* __-bucket__
This specifies the bucket from which the resource will be deleted.
Leading and/or trailing slashes are removed for you, as are spaces.
* __-resource__
This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash. Spaces are not
trimmed.
* __-blocking__
The standard blocking flag.
* __-status__
If specified, the indicated (not necessarily global) variable in the
caller's scope is set to a two-element list. The first element is the
3-digit HTTP status code. The second element is the HTTP message (such
as "OK" or "Forbidden"). Note that Amazon's DELETE result is 204 on
success, that being the code indicating no content in the returned body.
- <a name='14'></a>__S3::Push__ ?__-bucket__ *bucketname*? __-directory__ *directoryname* ?__-prefix__ *prefixstring*? ?__-compare__ *comparemode*? ?__-x-amz-meta-*__ *metastring*? ?__-acl__ *aclcode*? ?__-delete__ *boolean*? ?__-error__ *throw|break|continue*? ?__-progress__ *scriptprefix*?
This synchronises a local directory with a remote bucket by pushing the
differences using __S3::Put__. Note that if something has changed in the
bucket but not locally, those changes could be lost. Thus, this is not a
general two-way synchronization primitive. (See __S3::Sync__ for that.) Note
too that resource names are case sensitive, so changing the case of a file
on a Windows machine may lead to otherwise-unnecessary transfers. Note that
only regular files are considered, so devices, pipes, symlinks, and
directories are not copied.
* __-bucket__
This names the bucket into which data will be pushed.
* __-directory__
This names the local directory from which files will be taken. It must
exist, be readable via [glob] and so on. If only some of the files
therein are readable, __S3::Push__ will PUT those files that are
readable and return in its results the list of files that could not be
opened.
* __-prefix__
This names the prefix that will be added to all resources. That is, it
is the remote equivalent of __-directory__. If it is not specified, the
root of the bucket will be treated as the remote directory. An example
may clarify.
S3::Push -bucket test -directory /tmp/xyz -prefix hello/world
In this example, /tmp/xyz/pdq.html will be stored as
http://s3.amazonaws.com/test/hello/world/pdq.html in Amazon's servers.
Also, /tmp/xyz/abc/def/Hello will be stored as
http://s3.amazonaws.com/test/hello/world/abc/def/Hello in Amazon's
servers. Without the __-prefix__ option, /tmp/xyz/pdq.html would be
stored as http://s3.amazonaws.com/test/pdq.html.
* __-blocking__
This is the standard blocking option.
* __-compare__
If present, this is passed to each invocation of __S3::Put__. Naturally,
__S3::Configure -default-compare__ is used if this is not specified.
* __-x-amz-meta-*__
If present, this is passed to each invocation of __S3::Put__. All copied
files will have the same metadata.
* __-acl__
If present, this is passed to each invocation of __S3::Put__.
* __-delete__
This defaults to false. If true, resources in the destination that are
not in the source directory are deleted with __S3::Delete__. Since only
regular files are considered, the existance of a symlink, pipe, device,
or directory in the local source will *not* prevent the deletion of a
remote resource with a corresponding name.
* __-error__
This controls the behavior of __S3::Push__ in the event that __S3::Put__
throws an error. Note that errors encountered on the local file system
or in reading the list of resources in the remote bucket always throw
errors. This option allows control over "partial" errors, when some
files were copied and some were not. __S3::Delete__ is always finished
up, with errors simply recorded in the return result.
+ throw
The error is rethrown with the same errorCode.
+ break
Processing stops without throwing an error, the error is recorded in
the return value, and the command returns with a normal return. The
calls to __S3::Delete__ are not started.
+ continue
This is the default. Processing continues without throwing,
recording the error in the return result, and resuming with the next
file in the local directory to be copied.
* __-progress__
If this is specified and the indicated script prefix is not empty, the
indicated script prefix will be invoked several times in the caller's
context with additional arguments at various points in the processing.
This allows progress reporting without backgrounding. The provided
prefix will be invoked with additional arguments, with the first
additional argument indicating what part of the process is being
reported on. The prefix is initially invoked with *args* as the first
additional argument and a dictionary representing the normalized
arguments to the __S3::Push__ call as the second additional argument.
Then the prefix is invoked with *local* as the first additional argument
and a list of suffixes of the files to be considered as the second
argument. Then the prefix is invoked with *remote* as the first
additional argument and a list of suffixes existing in the remote bucket
as the second additional argument. Then, for each file in the local
list, the prefix will be invoked with *start* as the first additional
argument and the common suffix as the second additional argument. When
__S3::Put__ returns for that file, the prefix will be invoked with
*copy* as the first additional argument, the common suffix as the second
additional argument, and a third argument that will be "copied" (if
__S3::Put__ sent the resource), "skipped" (if __S3::Put__ decided not to
based on __-compare__), or the errorCode that __S3::Put__ threw due to
unexpected errors (in which case the third argument is a list that
starts with "S3"). When all files have been transfered, the prefix may
be invoked zero or more times with *delete* as the first additional
argument and the suffix of the resource being deleted as the second
additional argument, with a third argument being either an empty string
(if the delete worked) or the errorCode from __S3::Delete__ if it
failed. Finally, the prefix will be invoked with *finished* as the first
additional argument and the return value as the second additional
argument.
The return result from this command is a dictionary. They keys are the
suffixes (i.e., the common portion of the path after the __-directory__ and
__-prefix__), while the values are either "copied", "skipped" (if
__-compare__ indicated not to copy the file), or the errorCode thrown by
__S3::Put__, as appropriate. If __-delete__ was true, there may also be
entries for suffixes with the value "deleted" or "notdeleted", indicating
whether the attempted __S3::Delete__ worked or not, respectively. There is
one additional pair in the return result, whose key is the empty string and
whose value is a nested dictionary. The keys of this nested dictionary
include "filescopied" (the number of files successfully copied),
"bytescopied" (the number of data bytes in the files copied, excluding
headers, metadata, etc), "compareskipped" (the number of files not copied
due to __-compare__ mode), "errorskipped" (the number of files not copied
due to thrown errors), "filesdeleted" (the number of resources deleted due
to not having corresponding files locally, or 0 if __-delete__ is false),
and "filesnotdeleted" (the number of resources whose deletion was attempted
but failed).
Note that this is currently implemented somewhat inefficiently. It fetches
the bucket listing (including timestamps and eTags), then calls __S3::Put__,
which uses HEAD to find the timestamps and eTags again. Correcting this with
no API change is planned for a future upgrade.
- <a name='15'></a>__S3::Pull__ ?__-bucket__ *bucketname*? __-directory__ *directoryname* ?__-prefix__ *prefixstring*? ?__-blocking__ *boolean*? ?__-compare__ *comparemode*? ?__-delete__ *boolean*? ?__-timestamp__ *aws|now*? ?__-error__ *throw|break|continue*? ?__-progress__ *scriptprefix*?
This synchronises a remote bucket with a local directory by pulling the
differences using __S3::Get__ If something has been changed locally but not
in the bucket, those difference may be lost. This is not a general two-way
synchronization mechanism. (See __S3::Sync__ for that.) This creates
directories if needed; new directories are created with default permissions.
Note that resource names are case sensitive, so changing the case of a file
on a Windows machine may lead to otherwise-unnecessary transfers. Also, try
not to store data in resources that end with a slash, or which are prefixes
of resources that otherwise would start with a slash; i.e., don't use this
if you store data in resources whose names have to be directories locally.
Note that this is currently implemented somewhat inefficiently. It fetches
the bucket listing (including timestamps and eTags), then calls __S3::Get__,
which uses HEAD to find the timestamps and eTags again. Correcting this with
no API change is planned for a future upgrade.
* __-bucket__
This names the bucket from which data will be pulled.
* __-directory__
This names the local directory into which files will be written It must
exist, be readable via [glob], writable for file creation, and so on. If
only some of the files therein are writable, __S3::Pull__ will GET those
files that are writable and return in its results the list of files that
could not be opened.
* __-prefix__
The prefix of resources that will be considered for retrieval. See
__S3::Push__ for more details, examples, etc. (Of course, __S3::Pull__
reads rather than writes, but the prefix is treated similarly.)
* __-blocking__
This is the standard blocking option.
* __-compare__
This is passed to each invocation of __S3::Get__ if provided. Naturally,
__S3::Configure -default-compare__ is used if this is not provided.
* __-timestamp__
This is passed to each invocation of __S3::Get__ if provided.
* __-delete__
If this is specified and true, files that exist in the __-directory__
that are not in the __-prefix__ will be deleted after all resources have
been copied. In addition, empty directories (other than the top-level
__-directory__) will be deleted, as Amazon S3 has no concept of an empty
directory.
* __-error__
See __S3::Push__ for a description of this option.
* __-progress__
See __S3::Push__ for a description of this option. It differs slightly
in that local directories may be included with a trailing slash to
indicate they are directories.
The return value from this command is a dictionary. It is identical in form
and meaning to the description of the return result of __S3::Push__. It
differs only in that directories may be included, with a trailing slash in
their name, if they are empty and get deleted.
- <a name='16'></a>__S3::Toss__ ?__-bucket__ *bucketname*? __-prefix__ *prefixstring* ?__-blocking__ *boolean*? ?__-error__ *throw|break|continue*? ?__-progress__ *scriptprefix*?
This deletes some or all resources within a bucket. It would be considered a
"recursive delete" had Amazon implemented actual directories.
* __-bucket__
The bucket from which resources will be deleted.
* ____-blocking____
The standard blocking option.
* ____-prefix____
The prefix for resources to be deleted. Any resource that starts with
this string will be deleted. This is required. To delete everything in
the bucket, pass an empty string for the prefix.
* ____-error____
If this is "throw", __S3::Toss__ rethrows any errors it encounters. If
this is "break", __S3::Toss__ returns with a normal return after the
first error, recording that error in the return result. If this is
"continue", which is the default, __S3::Toss__ continues on and lists
all errors in the return result.
* ____-progress____
If this is specified and not an empty string, the script prefix will be
invoked several times in the context of the caller with additional
arguments appended. Initially, it will be invoked with the first
additional argument being *args* and the second being the processed list
of arguments to __S3::Toss__. Then it is invoked with *remote* as the
first additional argument and the list of suffixes in the bucket to be
deleted as the second additional argument. Then it is invoked with the
first additional argument being *delete* and the second additional
argument being the suffix deleted and the third additional argument
being "deleted" or "notdeleted" depending on whether __S3::Delete__
threw an error. Finally, the script prefix is invoked with a first
additional argument of "finished" and a second additional argument of
the return value.
The return value is a dictionary. The keys are the suffixes of files that
__S3::Toss__ attempted to delete, and whose values are either the string
"deleted" or "notdeleted". There is also one additional pair, whose key is
the empty string and whose value is an embedded dictionary. The keys of this
embedded dictionary include "filesdeleted" and "filesnotdeleted", each of
which has integer values.
# <a name='section6'></a>LIMITATIONS
- The pure-Tcl MD5 checking is slow. If you are processing files in the
megabyte range, consider ensuring binary support is available.
- The commands __S3::Pull__ and __S3::Push__ fetch a directory listing which
includes timestamps and MD5 hashes, then invoke __S3::Get__ and __S3::Put__.
If a complex __-compare__ mode is specified, __S3::Get__ and __S3::Put__
will invoke a HEAD operation for each file to fetch timestamps and MD5
hashes of each resource again. It is expected that a future release of this
package will solve this without any API changes.
- The commands __S3::Pull__ and __S3::Push__ fetch a directory listing without
using __-max-count__. The entire directory is pulled into memory at once.
For very large buckets, this could be a performance problem. The author, at
this time, does not plan to change this behavior. Welcome to Open Source.
- __S3::Sync__ is neither designed nor implemented yet. The intention would be
to keep changes synchronised, so changes could be made to both the bucket
and the local directory and be merged by __S3::Sync__.
- Nor is __-compare__ *calc* fully implemented. This is primarily due to
Windows not providing a convenient method for distinguishing between local
files that are "public-read" or "public-read-write". Assistance figuring out
TWAPI for this would be appreciated. The U**X semantics are difficult to map
directly as well. See the source for details. Note that there are not tests
for calc, since it isn't done yet.
- The HTTP processing is implemented within the library, rather than using a
"real" HTTP package. Hence, multi-line headers are not (yet) handled
correctly. Do not include carriage returns or linefeeds in x-amz-meta-*
headers, content-type values, and so on. The author does not at this time
expect to improve this.
- Internally, __S3::Push__ and __S3::Pull__ and __S3::Toss__ are all very
similar and should be refactored.
- The idea of using __-compare__ *never* __-delete__ *true* to delete files
that have been deleted from one place but not the other yet not copying
changed files is untested.
# <a name='section7'></a>USAGE SUGGESTIONS
To fetch a "directory" out of a bucket, make changes, and store it back:
file mkdir ./tempfiles
S3::Pull -bucket sample -prefix of/interest -directory ./tempfiles \
-timestamp aws
do_my_process ./tempfiles other arguments
S3::Push -bucket sample -prefix of/interest -directory ./tempfiles \
-compare newer -delete true
To delete files locally that were deleted off of S3 but not otherwise update
files:
S3::Pull -bucket sample -prefix of/interest -directory ./myfiles \
-compare never -delete true
# <a name='section8'></a>FUTURE DEVELOPMENTS
The author intends to work on several additional projects related to this
package, in addition to finishing the unfinished features.
First, a command-line program allowing browsing of buckets and transfer of files
from shell scripts and command prompts is useful.
Second, a GUI-based program allowing visual manipulation of bucket and resource
trees not unlike Windows Explorer would be useful.
Third, a command-line (and perhaps a GUI-based) program called "OddJob" that
will use S3 to synchronize computation amongst multiple servers running OddJob.
An S3 bucket will be set up with a number of scripts to run, and the OddJob
program can be invoked on multiple machines to run scripts on all the machines,
each moving on to the next unstarted task as it finishes each. This is still
being designed, and it is intended primarily to be run on Amazon's Elastic
Compute Cloud.
# <a name='section9'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section10'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *amazon-s3* 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.
# <a name='keywords'></a>KEYWORDS
[amazon](../../../../index.md#amazon), [cloud](../../../../index.md#cloud),
[s3](../../../../index.md#s3)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms.
|
Added embedded/md/tcllib/files/modules/amazon-s3/xsxp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
[//000000001]: # (xsxp - Amazon S3 Web Service Utilities)
[//000000002]: # (Generated from file 'xsxp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (xsxp(n) 1.0 tcllib "Amazon S3 Web Service Utilities")
# NAME
xsxp - eXtremely Simple Xml Parser
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require xsxp 1
package require xml
[__xsxp::parse__ *xml*](#1)
[__xsxp::fetch__ *pxml* *path* ?*part*?](#2)
[__xsxp::fetchall__ *pxml_list* *path* ?*part*?](#3)
[__xsxp::only__ *pxml* *tagname*](#4)
[__xsxp::prettyprint__ *pxml* ?*chan*?](#5)
# <a name='description'></a>DESCRIPTION
This package provides a simple interface to parse XML into a pure-value list. It
also provides accessor routines to pull out specific subtags, not unlike DOM
access. This package was written for and is used by Darren New's Amazon S3
access package.
This is pretty lame, but I needed something like this for S3, and at the time,
TclDOM would not work with the new 8.5 Tcl due to version number problems.
In addition, this is a pure-value implementation. There is no garbage to clean
up in the event of a thrown error, for example. This simplifies the code for
sufficiently small XML documents, which is what Amazon's S3 guarantees.
Copyright 2006 Darren New. All Rights Reserved. NO WARRANTIES OF ANY TYPE ARE
PROVIDED. COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS. This software is
licensed under essentially the same terms as Tcl. See LICENSE.txt for the terms.
# <a name='section2'></a>COMMANDS
The package implements five rather simple procedures. One parses, one is for
debugging, and the rest pull various parts of the parsed document out for
processing.
- <a name='1'></a>__xsxp::parse__ *xml*
This parses an XML document (using the standard xml tcllib module in a SAX
sort of way) and builds a data structure which it returns if the parsing
succeeded. The return value is referred to herein as a "pxml", or "parsed
xml". The list consists of two or more elements:
The first element is the name of the tag.
The second element is an array-get formatted list of key/value pairs. The
keys are attribute names and the values are attribute values. This is an
empty list if there are no attributes on the tag.
The third through end elements are the children of the node, if any. Each
child is, recursively, a pxml.
Note that if the zero'th element, i.e. the tag name, is "%PCDATA", then the
attributes will be empty and the third element will be the text of the
element. In addition, if an element's contents consists only of PCDATA, it
will have only one child, and all the PCDATA will be concatenated. In other
words, this parser works poorly for XML with elements that contain both
child tags and PCDATA. Since Amazon S3 does not do this (and for that matter
most uses of XML where XML is a poor choice don't do this), this is probably
not a serious limitation.
- <a name='2'></a>__xsxp::fetch__ *pxml* *path* ?*part*?
*pxml* is a parsed XML, as returned from xsxp::parse. *path* is a list of
element tag names. Each element is the name of a child to look up,
optionally followed by a hash ("#") and a string of digits. An empty list or
an initial empty element selects *pxml*. If no hash sign is present, the
behavior is as if "#0" had been appended to that element. (In addition to a
list, slashes can separate subparts where convenient.)
An element of *path* scans the children at the indicated level for the n'th
instance of a child whose tag matches the part of the element before the
hash sign. If an element is simply "#" followed by digits, that indexed
child is selected, regardless of the tags in the children. Hence, an element
of "#3" will always select the fourth child of the node under consideration.
*part* defaults to "%ALL". It can be one of the following case-sensitive
terms:
* %ALL
returns the entire selected element.
* %TAGNAME
returns lindex 0 of the selected element.
* %ATTRIBUTES
returns index 1 of the selected element.
* %CHILDREN
returns lrange 2 through end of the selected element, resulting in a
list of elements being returned.
* %PCDATA
returns a concatenation of all the bodies of direct children of this
node whose tag is %PCDATA. It throws an error if no such children are
found. That is, part=%PCDATA means return the textual content found in
that node but not its children nodes.
* %PCDATA?
is like %PCDATA, but returns an empty string if no PCDATA is found.
For example, to fetch the first bold text from the fifth paragraph of the
body of your HTML file,
xsxp::fetch $pxml {body p#4 b} %PCDATA
- <a name='3'></a>__xsxp::fetchall__ *pxml_list* *path* ?*part*?
This iterates over each PXML in *pxml_list* (which must be a list of pxmls)
selecting the indicated path from it, building a new list with the selected
data, and returning that new list.
For example, *pxml_list* might be the %CHILDREN of a particular element, and
the *path* and *part* might select from each child a sub-element in which
we're interested.
- <a name='4'></a>__xsxp::only__ *pxml* *tagname*
This iterates over the direct children of *pxml* and selects only those with
*tagname* as their tag. Returns a list of matching elements.
- <a name='5'></a>__xsxp::prettyprint__ *pxml* ?*chan*?
This outputs to *chan* (default stdout) a pretty-printed version of *pxml*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *amazon-s3* 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.
# <a name='keywords'></a>KEYWORDS
[dom](../../../../index.md#dom), [parser](../../../../index.md#parser),
[xml](../../../../index.md#xml)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
2006 Darren New. All Rights Reserved.
|
Added embedded/md/tcllib/files/modules/asn/asn.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
|
[//000000001]: # (asn - ASN.1 processing)
[//000000002]: # (Generated from file 'asn.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (asn(n) 0.8 tcllib "ASN.1 processing")
# NAME
asn - ASN.1 BER encoder/decoder
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [ENCODER](#subsection1)
- [DECODER](#subsection2)
- [HANDLING TAGS](#subsection3)
- [EXAMPLES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require asn ?0.8.4?
[__::asn::asnSequence__ *evalue*...](#1)
[__::asn::asnSequenceFromList__ *elist*](#2)
[__::asn::asnSet__ *evalue*...](#3)
[__::asn::asnSetFromList__ *elist*](#4)
[__::asn::asnApplicationConstr__ *appNumber* *evalue*...](#5)
[__::asn::asnApplication__ *appNumber* *data*](#6)
[__::asn::asnChoice__ *appNumber* *evalue*...](#7)
[__::asn::asnChoiceConstr__ *appNumber* *evalue*...](#8)
[__::asn::asnInteger__ *number*](#9)
[__::asn::asnEnumeration__ *number*](#10)
[__::asn::asnBoolean__ *bool*](#11)
[__::asn::asnContext__ *context* *data*](#12)
[__::asn::asnContextConstr__ *context* *evalue*...](#13)
[__::asn::asnObjectIdentifier__ *idlist*](#14)
[__::asn::asnUTCTime__ *utcstring*](#15)
[__::asn::asnNull__](#16)
[__::asn::asnBitString__ *string*](#17)
[__::asn::asnOctetString__ *string*](#18)
[__::asn::asnNumericString__ *string*](#19)
[__::asn::asnPrintableString__ *string*](#20)
[__::asn::asnIA5String__ *string*](#21)
[__::asn::asnBMPString__ *string*](#22)
[__::asn::asnUTF8String__ *string*](#23)
[__::asn::asnString__ *string*](#24)
[__::asn::defaultStringType__ ?*type*?](#25)
[__::asn::asnPeekByte__ *data_var* *byte_var*](#26)
[__::asn::asnGetLength__ *data_var* *length_var*](#27)
[__::asn::asnGetResponse__ *chan* *data_var*](#28)
[__::asn::asnGetInteger__ *data_var* *int_var*](#29)
[__::asn::asnGetEnumeration__ *data_var* *enum_var*](#30)
[__::asn::asnGetOctetString__ *data_var* *string_var*](#31)
[__::asn::asnGetString__ *data_var* *string_var* ?*type_var*?](#32)
[__::asn::asnGetNumericString__ *data_var* *string_var*](#33)
[__::asn::asnGetPrintableString__ *data_var* *string_var*](#34)
[__::asn::asnGetIA5String__ *data_var* *string_var*](#35)
[__::asn::asnGetBMPString__ *data_var* *string_var*](#36)
[__::asn::asnGetUTF8String__ *data_var* *string_var*](#37)
[__::asn::asnGetUTCTime__ *data_var* *utc_var*](#38)
[__::asn::asnGetBitString__ *data_var* *bits_var*](#39)
[__::asn::asnGetObjectIdentifier__ *data_var* *oid_var*](#40)
[__::asn::asnGetBoolean__ *data_var* *bool_var*](#41)
[__::asn::asnGetNull__ *data_var*](#42)
[__::asn::asnGetSequence__ *data_var* *sequence_var*](#43)
[__::asn::asnGetSet__ *data_var* *set_var*](#44)
[__::asn::asnGetApplication__ *data_var* *appNumber_var* ?*content_var*? ?*encodingType_var*?](#45)
[__::asn::asnGetContext__ *data_var* *contextNumber_var* ?*content_var*? ?*encodingType_var*?](#46)
[__::asn::asnPeekTag__ *data_var* *tag_var* *tagtype_var* *constr_var*](#47)
[__::asn::asnTag__ *tagnumber* ?*class*? ?*tagstyle*?](#48)
[__::asn::asnRetag__ *data_var* *newTag*](#49)
# <a name='description'></a>DESCRIPTION
The __asn__ package provides *partial* de- and encoder commands for BER encoded
ASN.1 data. It can also be used for decoding DER, which is a restricted subset
of BER.
ASN.1 is a standard *Abstract Syntax Notation*, and BER are its *Basic Encoding
Rules*.
See
[http://asn1.elibel.tm.fr/en/standards/index.htm](http://asn1.elibel.tm.fr/en/standards/index.htm)
for more information about the standard.
Also see
[http://luca.ntop.org/Teaching/Appunti/asn1.html](http://luca.ntop.org/Teaching/Appunti/asn1.html)
for *A Layman's Guide to a Subset of ASN.1, BER, and DER*, an RSA Laboratories
Technical Note by Burton S. Kaliski Jr. (Revised November 1, 1993). A text
version of this note is part of the module sources and should be read by any
implementor.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>ENCODER
- <a name='1'></a>__::asn::asnSequence__ *evalue*...
Takes zero or more encoded values, packs them into an ASN sequence and
returns its encoded binary form.
- <a name='2'></a>__::asn::asnSequenceFromList__ *elist*
Takes a list of encoded values, packs them into an ASN sequence and returns
its encoded binary form.
- <a name='3'></a>__::asn::asnSet__ *evalue*...
Takes zero or more encoded values, packs them into an ASN set and returns
its encoded binary form.
- <a name='4'></a>__::asn::asnSetFromList__ *elist*
Takes a list of encoded values, packs them into an ASN set and returns its
encoded binary form.
- <a name='5'></a>__::asn::asnApplicationConstr__ *appNumber* *evalue*...
Takes zero or more encoded values, packs them into an ASN application
construct and returns its encoded binary form.
- <a name='6'></a>__::asn::asnApplication__ *appNumber* *data*
Takes a single encoded value *data*, packs it into an ASN application
construct and returns its encoded binary form.
- <a name='7'></a>__::asn::asnChoice__ *appNumber* *evalue*...
Takes zero or more encoded values, packs them into an ASN choice construct
and returns its encoded binary form.
- <a name='8'></a>__::asn::asnChoiceConstr__ *appNumber* *evalue*...
Takes zero or more encoded values, packs them into an ASN choice construct
and returns its encoded binary form.
- <a name='9'></a>__::asn::asnInteger__ *number*
Returns the encoded form of the specified integer *number*.
- <a name='10'></a>__::asn::asnEnumeration__ *number*
Returns the encoded form of the specified enumeration id *number*.
- <a name='11'></a>__::asn::asnBoolean__ *bool*
Returns the encoded form of the specified boolean value *bool*.
- <a name='12'></a>__::asn::asnContext__ *context* *data*
Takes an encoded value and packs it into a constructed value with
application tag, the *context* number.
- <a name='13'></a>__::asn::asnContextConstr__ *context* *evalue*...
Takes zero or more encoded values and packs them into a constructed value
with application tag, the *context* number.
- <a name='14'></a>__::asn::asnObjectIdentifier__ *idlist*
Takes a list of at least 2 integers describing an object identifier (OID)
value, and returns the encoded value.
- <a name='15'></a>__::asn::asnUTCTime__ *utcstring*
Returns the encoded form of the specified UTC time string.
- <a name='16'></a>__::asn::asnNull__
Returns the NULL encoding.
- <a name='17'></a>__::asn::asnBitString__ *string*
Returns the encoded form of the specified *string*.
- <a name='18'></a>__::asn::asnOctetString__ *string*
Returns the encoded form of the specified *string*.
- <a name='19'></a>__::asn::asnNumericString__ *string*
Returns the *string* encoded as ASN.1 NumericString. Raises an error if the
*string* contains characters other than decimal numbers and space.
- <a name='20'></a>__::asn::asnPrintableString__ *string*
Returns the *string* encoding as ASN.1 PrintableString. Raises an error if
the *string* contains characters which are not allowed by the Printable
String datatype. The allowed characters are A-Z, a-z, 0-9, space,
apostrophe, colon, parentheses, plus, minus, comma, period, forward slash,
question mark, and the equals sign.
- <a name='21'></a>__::asn::asnIA5String__ *string*
Returns the *string* encoded as ASN.1 IA5String. Raises an error if the
*string* contains any characters outside of the US-ASCII range.
- <a name='22'></a>__::asn::asnBMPString__ *string*
Returns the *string* encoded as ASN.1 Basic Multilingual Plane string (Which
is essentialy big-endian UCS2).
- <a name='23'></a>__::asn::asnUTF8String__ *string*
Returns the *string* encoded as UTF8 String. Note that some legacy
applications such as Windows CryptoAPI do not like UTF8 strings. Use
BMPStrings if you are not sure.
- <a name='24'></a>__::asn::asnString__ *string*
Returns an encoded form of *string*, choosing the most restricted ASN.1
string type possible. If the string contains non-ASCII characters, then
there is more than one string type which can be used. See
__::asn::defaultStringType__.
- <a name='25'></a>__::asn::defaultStringType__ ?*type*?
Selects the string type to use for the encoding of non-ASCII strings.
Returns current default when called without argument. If the argument *type*
is supplied, it should be either __UTF8__ or __BMP__ to choose UTF8String or
BMPString respectively.
## <a name='subsection2'></a>DECODER
General notes:
1. Nearly all decoder commands take two arguments. These arguments are
variable names, except for __::asn::asnGetResponse__. The first variable
contains the encoded ASN value to decode at the beginning, and more, and
the second variable is where the value is stored to. The remainder of the
input after the decoded value is stored back into the datavariable.
1. After extraction the data variable is always modified first, before by
writing the extracted value to its variable. This means that if both
arguments refer to the same variable, it will always contain the extracted
value after the call, and not the remainder of the input.
- <a name='26'></a>__::asn::asnPeekByte__ *data_var* *byte_var*
Retrieve the first byte of the data, without modifing *data_var*. This can
be used to check for implicit tags.
- <a name='27'></a>__::asn::asnGetLength__ *data_var* *length_var*
Decode the length information for a block of BER data. The tag has already
to be removed from the data.
- <a name='28'></a>__::asn::asnGetResponse__ *chan* *data_var*
Reads an encoded ASN *sequence* from the channel *chan* and stores it into
the variable named by *data_var*.
- <a name='29'></a>__::asn::asnGetInteger__ *data_var* *int_var*
Assumes that an encoded integer value is at the front of the data stored in
the variable named *data_var*, extracts and stores it into the variable
named by *int_var*. Additionally removes all bytes associated with the value
from the data for further processing by the following decoder commands.
- <a name='30'></a>__::asn::asnGetEnumeration__ *data_var* *enum_var*
Assumes that an enumeration id is at the front of the data stored in the
variable named *data_var*, and stores it into the variable named by
*enum_var*. Additionally removes all bytes associated with the value from
the data for further processing by the following decoder commands.
- <a name='31'></a>__::asn::asnGetOctetString__ *data_var* *string_var*
Assumes that a string is at the front of the data stored in the variable
named *data_var*, and stores it into the variable named by *string_var*.
Additionally removes all bytes associated with the value from the data for
further processing by the following decoder commands.
- <a name='32'></a>__::asn::asnGetString__ *data_var* *string_var* ?*type_var*?
Decodes a user-readable string. This is a convenience function which is able
to automatically distinguish all supported ASN.1 string types and convert
the input value appropriately. See __::asn::asnGetPrintableString__,
__::asnGetIA5String__, etc. below for the type-specific conversion commands.
If the optional third argument *type_var* is supplied, then the type of the
incoming string is stored in the variable named by it.
The function throws the error "Invalid command name
asnGetSome__UnsupportedString__" if the unsupported string type
__Unsupported__ is encountered. You can create the appropriate function
"asn::asnGetSome__UnsupportedString__" in your application if neccessary.
- <a name='33'></a>__::asn::asnGetNumericString__ *data_var* *string_var*
Assumes that a numeric string value is at the front of the data stored in
the variable named *data_var*, and stores it into the variable named by
*string_var*. Additionally removes all bytes associated with the value from
the data for further processing by the following decoder commands.
- <a name='34'></a>__::asn::asnGetPrintableString__ *data_var* *string_var*
Assumes that a printable string value is at the front of the data stored in
the variable named *data_var*, and stores it into the variable named by
*string_var*. Additionally removes all bytes associated with the value from
the data for further processing by the following decoder commands.
- <a name='35'></a>__::asn::asnGetIA5String__ *data_var* *string_var*
Assumes that a IA5 (ASCII) string value is at the front of the data stored
in the variable named *data_var*, and stores it into the variable named by
*string_var*. Additionally removes all bytes associated with the value from
the data for further processing by the following decoder commands.
- <a name='36'></a>__::asn::asnGetBMPString__ *data_var* *string_var*
Assumes that a BMP (two-byte unicode) string value is at the front of the
data stored in the variable named *data_var*, and stores it into the
variable named by *string_var*, converting it into a proper Tcl string.
Additionally removes all bytes associated with the value from the data for
further processing by the following decoder commands.
- <a name='37'></a>__::asn::asnGetUTF8String__ *data_var* *string_var*
Assumes that a UTF8 string value is at the front of the data stored in the
variable named *data_var*, and stores it into the variable named by
*string_var*, converting it into a proper Tcl string. Additionally removes
all bytes associated with the value from the data for further processing by
the following decoder commands.
- <a name='38'></a>__::asn::asnGetUTCTime__ *data_var* *utc_var*
Assumes that a UTC time value is at the front of the data stored in the
variable named *data_var*, and stores it into the variable named by
*utc_var*. The UTC time value is stored as a string, which has to be decoded
with the usual clock scan commands. Additionally removes all bytes
associated with the value from the data for further processing by the
following decoder commands.
- <a name='39'></a>__::asn::asnGetBitString__ *data_var* *bits_var*
Assumes that a bit string value is at the front of the data stored in the
variable named *data_var*, and stores it into the variable named by
*bits_var* as a string containing only 0 and 1. Additionally removes all
bytes associated with the value from the data for further processing by the
following decoder commands.
- <a name='40'></a>__::asn::asnGetObjectIdentifier__ *data_var* *oid_var*
Assumes that a object identifier (OID) value is at the front of the data
stored in the variable named *data_var*, and stores it into the variable
named by *oid_var* as a list of integers. Additionally removes all bytes
associated with the value from the data for further processing by the
following decoder commands.
- <a name='41'></a>__::asn::asnGetBoolean__ *data_var* *bool_var*
Assumes that a boolean value is at the front of the data stored in the
variable named *data_var*, and stores it into the variable named by
*bool_var*. Additionally removes all bytes associated with the value from
the data for further processing by the following decoder commands.
- <a name='42'></a>__::asn::asnGetNull__ *data_var*
Assumes that a NULL value is at the front of the data stored in the variable
named *data_var* and removes the bytes used to encode it from the data.
- <a name='43'></a>__::asn::asnGetSequence__ *data_var* *sequence_var*
Assumes that an ASN sequence is at the front of the data stored in the
variable named *data_var*, and stores it into the variable named by
*sequence_var*. Additionally removes all bytes associated with the value
from the data for further processing by the following decoder commands.
The data in *sequence_var* is encoded binary and has to be further decoded
according to the definition of the sequence, using the decoder commands
here.
- <a name='44'></a>__::asn::asnGetSet__ *data_var* *set_var*
Assumes that an ASN set is at the front of the data stored in the variable
named *data_var*, and stores it into the variable named by *set_var*.
Additionally removes all bytes associated with the value from the data for
further processing by the following decoder commands.
The data in *set_var* is encoded binary and has to be further decoded
according to the definition of the set, using the decoder commands here.
- <a name='45'></a>__::asn::asnGetApplication__ *data_var* *appNumber_var* ?*content_var*? ?*encodingType_var*?
Assumes that an ASN application construct is at the front of the data stored
in the variable named *data_var*, and stores its id into the variable named
by *appNumber_var*. Additionally removes all bytes associated with the value
from the data for further processing by the following decoder commands. If a
*content_var* is specified, then the command places all data associated with
it into the named variable, in the binary form which can be processed using
the decoder commands of this package. If a *encodingType_var* is specified,
then that var is set to 1 if the encoding is constructed and 0 if it is
primitive.
Otherwise it is the responsibility of the caller to decode the remainder of
the application construct based on the id retrieved by this command, using
the decoder commands of this package.
- <a name='46'></a>__::asn::asnGetContext__ *data_var* *contextNumber_var* ?*content_var*? ?*encodingType_var*?
Assumes that an ASN context tag construct is at the front of the data stored
in the variable named *data_var*, and stores its id into the variable named
by *contextNumber_var*. Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands. If a *content_var* is specified, then the command places all data
associated with it into the named variable, in the binary form which can be
processed using the decoder commands of this package. If a
*encodingType_var* is specified, then that var is set to 1 if the encoding
is constructed and 0 if it is primitive.
Otherwise it is the responsibility of the caller to decode the remainder of
the construct based on the id retrieved by this command, using the decoder
commands of this package.
## <a name='subsection3'></a>HANDLING TAGS
Working with ASN.1 you often need to decode tagged values, which use a tag thats
different from the universal tag for a type. In those cases you have to replace
the tag with the universal tag used for the type, to decode the value. To decode
a tagged value use the __::asn::asnRetag__ to change the tag to the appropriate
type to use one of the decoders for primitive values. To help with this the
module contains three functions:
- <a name='47'></a>__::asn::asnPeekTag__ *data_var* *tag_var* *tagtype_var* *constr_var*
The __::asn::asnPeekTag__ command can be used to take a peek at the data and
decode the tag value, without removing it from the data. The *tag_var* gets
set to the tag number, while the *tagtype_var* gets set to the class of the
tag. (Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE). The *constr_var*
is set to 1 if the tag is for a constructed value, and to 0 for not
constructed. It returns the length of the tag.
- <a name='48'></a>__::asn::asnTag__ *tagnumber* ?*class*? ?*tagstyle*?
The __::asn::asnTag__ can be used to create a tag value. The *tagnumber*
gives the number of the tag, while the *class* gives one of the classes
(UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The class may be abbreviated to
just the first letter (U,C,A,P), default is UNIVERSAL. The *tagstyle* is
either C for Constructed encoding, or P for primitve encoding. It defaults
to P. You can also use 1 instead of C and 0 instead of P for direct use of
the values returned by __::asn::asnPeekTag__.
- <a name='49'></a>__::asn::asnRetag__ *data_var* *newTag*
Replaces the tag in front of the data in *data_var* with *newTag*. The new
Tag can be created using the __::asn::asnTag__ command.
# <a name='section3'></a>EXAMPLES
Examples for the usage of this package can be found in the implementation of
package __[ldap](../ldap/ldap.md)__.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *asn* 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.
# <a name='keywords'></a>KEYWORDS
[asn](../../../../index.md#asn), [ber](../../../../index.md#ber),
[cer](../../../../index.md#cer), [der](../../../../index.md#der),
[internet](../../../../index.md#internet),
[protocol](../../../../index.md#protocol), [x.208](../../../../index.md#x_208),
[x.209](../../../../index.md#x_209)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Andreas Kupries <[email protected]>
Copyright © 2004 Jochen Loewer <[email protected]>
Copyright © 2004-2011 Michael Schlenker <[email protected]>
|
Added embedded/md/tcllib/files/modules/base32/base32.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
[//000000001]: # (base32 - Base32 encoding)
[//000000002]: # (Generated from file 'base32.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (base32(n) 0.1 tcllib "Base32 encoding")
# NAME
base32 - base32 standard encoding
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Code map](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require base32::core ?0.1?
package require base32 ?0.1?
[__::base32::encode__ *string*](#1)
[__::base32::decode__ *estring*](#2)
# <a name='description'></a>DESCRIPTION
This package provides commands for encoding and decoding of strings into and out
of the standard base32 encoding as specified in RFC 3548.
# <a name='section2'></a>API
- <a name='1'></a>__::base32::encode__ *string*
This command encodes the given *string* in base32 and returns the encoded
string as its result. The result may be padded with the character __=__ to
signal a partial encoding at the end of the input string.
- <a name='2'></a>__::base32::decode__ *estring*
This commands takes the *estring* and decodes it under the assumption that
it is a valid base32 encoded string. The result of the decoding is returned
as the result of the command.
Note that while the encoder will generate only uppercase characters this
decoder accepts input in lowercase as well.
The command will always throw an error whenever encountering conditions
which signal some type of bogus input, namely if
the input contains characters which are not valid output of a base32
encoder,
the length of the input is not a multiple of eight,
padding appears not at the end of input, but in the middle,
the padding has not of length six, four, three, or one characters,
# <a name='section3'></a>Code map
The code map used to convert 5-bit sequences is shown below, with the numeric id
of the bit sequences to the left and the character used to encode it to the
right. It should be noted that the characters "0" and "1" are not used by the
encoding. This is done as these characters can be easily confused with "O", "o"
and "l" (L).
0 A 9 J 18 S 27 3
1 B 10 K 19 T 28 4
2 C 11 L 20 U 29 5
3 D 12 M 21 V 30 6
4 E 13 N 22 W 31 7
5 F 14 O 23 X
6 G 15 P 24 Y
7 H 16 Q 25 Z
8 I 17 R 26 2
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base32* 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.
# <a name='keywords'></a>KEYWORDS
[base32](../../../../index.md#base32), [rfc3548](../../../../index.md#rfc3548)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Public domain
|
Added embedded/md/tcllib/files/modules/base32/base32core.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
[//000000001]: # (base32::core - Base32 encoding)
[//000000002]: # (Generated from file 'base32core.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (base32::core(n) 0.1 tcllib "Base32 encoding")
# NAME
base32::core - Expanding basic base32 maps
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require base32::core ?0.1?
[__::base32::core::define__ *map* *forwvar* *backwvar* *ivar*](#1)
[__::base32::core::valid__ *string* *pattern* *mvar*](#2)
# <a name='description'></a>DESCRIPTION
This package provides generic commands for the construction of full base32
mappings from a basic mapping listing just the codes and associated characters.
The full mappings, regular and inverse, created here map to and from bit
sequences, and also handle the partial mappings at the end of a string.
This is in essence an internal package to be used by implementors of a base32
en- and decoder. A regular user has no need of this package at all.
# <a name='section2'></a>API
- <a name='1'></a>__::base32::core::define__ *map* *forwvar* *backwvar* *ivar*
This command computes full forward and backward (inverse) mappings from the
basic *map* and stores them in the variables named by *forwvar* and
*backwvar* resp. It also constructs a regexp pattern for the detection of
invalid characters in supposedly base32 encoded input and stores it in the
variable named by *ivar*.
- <a name='2'></a>__::base32::core::valid__ *string* *pattern* *mvar*
This command checks if the input *string* is a valid base32 encoded string,
based on the *pattern* of invalid characters as generated by
__::base32::core::define__, and some other general rules.
The result of the command is a boolean flag. Its value is __True__ for a
valid *string*, and __False__ otherwise. In the latter case an error message
describing the problem with the input is stored into the variable named by
*mvar*. The variable is not touched if the input was found to be valid.
The rules checked by the command, beyond rejection of bad characters, are:
The length of the input is not a multiple of eight,
The padding appears not at the end of input, but in the middle,
The padding has not of length six, four, three, or one characters,
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base32* 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.
# <a name='keywords'></a>KEYWORDS
[base32](../../../../index.md#base32)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Public domain
|
Added embedded/md/tcllib/files/modules/base32/base32hex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
[//000000001]: # (base32::hex - Base32 encoding)
[//000000002]: # (Generated from file 'base32hex.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (base32::hex(n) 0.1 tcllib "Base32 encoding")
# NAME
base32::hex - base32 extended hex encoding
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Code map](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require base32::core ?0.1?
package require base32::hex ?0.1?
[__::base32::hex::encode__ *string*](#1)
[__::base32::hex::decode__ *estring*](#2)
# <a name='description'></a>DESCRIPTION
This package provides commands for encoding and decoding of strings into and out
of the extended hex base32 encoding as specified in the RFC 3548bis draft.
# <a name='section2'></a>API
- <a name='1'></a>__::base32::hex::encode__ *string*
This command encodes the given *string* in extended hex base32 and returns
the encoded string as its result. The result may be padded with the
character __=__ to signal a partial encoding at the end of the input string.
- <a name='2'></a>__::base32::hex::decode__ *estring*
This commands takes the *estring* and decodes it under the assumption that
it is a valid extended hex base32 encoded string. The result of the decoding
is returned as the result of the command.
Note that while the encoder will generate only uppercase characters this
decoder accepts input in lowercase as well.
The command will always throw an error whenever encountering conditions
which signal some type of bogus input, namely if
the input contains characters which are not valid output of a extended hex
base32 encoder,
the length of the input is not a multiple of eight,
padding appears not at the end of input, but in the middle,
the padding has not of length six, four, three, or one characters,
# <a name='section3'></a>Code map
The code map used to convert 5-bit sequences is shown below, with the numeric id
of the bit sequences to the left and the character used to encode it to the
right. The important feature of the extended hex mapping is that the first 16
codes map to the digits and hex characters.
0 0 9 9 18 I 27 R
1 1 10 A 19 J 28 S
2 2 11 B 20 K 29 T
3 3 12 C 21 L 30 U
4 4 13 D 22 M 31 V
5 5 14 E 23 N
6 6 15 F 24 O
7 7 16 G 25 P
8 8 17 H 26 Q
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base32* 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.
# <a name='keywords'></a>KEYWORDS
[base32](../../../../index.md#base32), [hex](../../../../index.md#hex),
[rfc3548](../../../../index.md#rfc3548)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Public domain
|
Added embedded/md/tcllib/files/modules/base64/ascii85.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
[//000000001]: # (ascii85 - Text encoding & decoding binary data)
[//000000002]: # (Generated from file 'ascii85.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ascii85(n) 1.0 tcllib "Text encoding & decoding binary data")
# NAME
ascii85 - ascii85-encode/decode binary data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [References](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require ascii85 ?1.0?
[__::ascii85::encode__ ?__-maxlen__ *maxlen*? ?__-wrapchar__ *wrapchar*? *string*](#1)
[__::ascii85::decode__ *string*](#2)
# <a name='description'></a>DESCRIPTION
This package provides procedures to encode binary data into ascii85 and back.
- <a name='1'></a>__::ascii85::encode__ ?__-maxlen__ *maxlen*? ?__-wrapchar__ *wrapchar*? *string*
Ascii85 encodes the given binary *string* and returns the encoded result.
Inserts the character *wrapchar* every *maxlen* characters of output.
*wrapchar* defaults to newline. *maxlen* defaults to __76__.
*Note well*: If your string is not simple ascii you should fix the string
encoding before doing ascii85 encoding. See the examples.
The command will throw an error for negative values of *maxlen*, or if
*maxlen* is not an integer number.
- <a name='2'></a>__::ascii85::decode__ *string*
Ascii85 decodes the given *string* and returns the binary data. The decoder
ignores whitespace in the string, as well as tabs and newlines.
# <a name='section2'></a>EXAMPLES
% ascii85::encode "Hello, world"
87cURD_*#TDfTZ)
% ascii85::encode [string repeat xyz 24]
G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G
^4U[H$X^\H?a^]
% ascii85::encode -wrapchar "" [string repeat xyz 24]
G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]
# NOTE: ascii85 encodes BINARY strings.
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [ascii85::encode $chemical]
6fN]R8E,5Pidu\UiduhZidua
% set caffeine [encoding convertfrom utf-8 [ascii85::decode $encoded]]
# <a name='section3'></a>References
1. [http://en.wikipedia.org/wiki/Ascii85](http://en.wikipedia.org/wiki/Ascii85)
1. Postscript Language Reference Manual, 3rd Edition, page 131.
[http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf](http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf)
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base64* 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.
# <a name='keywords'></a>KEYWORDS
[ascii85](../../../../index.md#ascii85),
[encoding](../../../../index.md#encoding)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010, Emiliano Gavilán
|
Added embedded/md/tcllib/files/modules/base64/base64.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
[//000000001]: # (base64 - Text encoding & decoding binary data)
[//000000002]: # (Generated from file 'base64.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (base64(n) 2.4.2 tcllib "Text encoding & decoding binary data")
# NAME
base64 - base64-encode/decode binary data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require base64 ?2.4.2?
[__::base64::encode__ ?__-maxlen__ *maxlen*? ?__-wrapchar__ *wrapchar*? *string*](#1)
[__::base64::decode__ *string*](#2)
# <a name='description'></a>DESCRIPTION
This package provides procedures to encode binary data into base64 and back.
- <a name='1'></a>__::base64::encode__ ?__-maxlen__ *maxlen*? ?__-wrapchar__ *wrapchar*? *string*
Base64 encodes the given binary *string* and returns the encoded result.
Inserts the character *wrapchar* every *maxlen* characters of output.
*wrapchar* defaults to newline. *maxlen* defaults to __76__.
*Note* that if *maxlen* is set to __0__, the output will not be wrapped at
all.
*Note well*: If your string is not simple ascii you should fix the string
encoding before doing base64 encoding. See the examples.
The command will throw an error for negative values of *maxlen*, or if
*maxlen* is not an integer number.
- <a name='2'></a>__::base64::decode__ *string*
Base64 decodes the given *string* and returns the binary data. The decoder
ignores whitespace in the string.
# <a name='section2'></a>EXAMPLES
% base64::encode "Hello, world"
SGVsbG8sIHdvcmxk
% base64::encode [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
eHl6eHl6eHl6
% base64::encode -wrapchar "" [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
# NOTE: base64 encodes BINARY strings.
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [base64::encode $chemical]
Q+KCiEjigoHigoBO4oKET+KCgg==
% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base64* 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.
# <a name='keywords'></a>KEYWORDS
[base64](../../../../index.md#base64), [encoding](../../../../index.md#encoding)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2000, Eric Melski
Copyright © 2001, Miguel Sofer
|
Added embedded/md/tcllib/files/modules/base64/uuencode.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
[//000000001]: # (uuencode - Text encoding & decoding binary data)
[//000000002]: # (Generated from file 'uuencode.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (uuencode(n) 1.1.4 tcllib "Text encoding & decoding binary data")
# NAME
uuencode - UU-encode/decode binary data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OPTIONS](#section2)
- [EXAMPLES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require uuencode ?1.1.4?
[__::uuencode::encode__ *string*](#1)
[__::uuencode::decode__ *string*](#2)
[__::uuencode::uuencode__ ?__-name__ *string*? ?__-mode__ *octal*? (__-file__ *filename* | ?__--__? *string*)](#3)
[__::uuencode::uudecode__ (__-file__ *filename* | ?__--__? *string*)](#4)
# <a name='description'></a>DESCRIPTION
This package provides a Tcl-only implementation of the __uuencode(1)__ and
__uudecode(1)__ commands. This encoding packs binary data into printable ASCII
characters.
- <a name='1'></a>__::uuencode::encode__ *string*
returns the uuencoded data. This will encode all the data passed in even if
this is longer than the uuencode maximum line length. If the number of input
bytes is not a multiple of 3 then additional 0 bytes are added to pad the
string.
- <a name='2'></a>__::uuencode::decode__ *string*
Decodes the given encoded data. This will return any padding characters as
well and it is the callers responsibility to deal with handling the actual
length of the encoded data. (see uuencode).
- <a name='3'></a>__::uuencode::uuencode__ ?__-name__ *string*? ?__-mode__ *octal*? (__-file__ *filename* | ?__--__? *string*)
- <a name='4'></a>__::uuencode::uudecode__ (__-file__ *filename* | ?__--__? *string*)
UUDecode a file or block of data. A file may contain more than one embedded
file so the result is a list where each element is a three element list of
filename, mode value and data.
# <a name='section2'></a>OPTIONS
- -filename name
Cause the uuencode or uudecode commands to read their data from the named
file rather that taking a string parameter.
- -name string
The uuencoded data header line contains the suggested file name to be used
when unpacking the data. Use this option to change this from the default of
"data.dat".
- -mode octal
The uuencoded data header line contains a suggested permissions bit pattern
expressed as an octal string. To change the default of 0644 you can set this
option. For instance, 0755 would be suitable for an executable. See
__chmod(1)__.
# <a name='section3'></a>EXAMPLES
% set d [uuencode::encode "Hello World!"]
2&5L;&\\@5V]R;&0A
% uuencode::uudecode $d
Hello World!
% set d [uuencode::uuencode -name hello.txt "Hello World"]
begin 644 hello.txt
+2&5L;&\@5V]R;&0`
`
end
% uuencode::uudecode $d
{hello.txt 644 {Hello World}}
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base64* 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.
# <a name='keywords'></a>KEYWORDS
[encoding](../../../../index.md#encoding),
[uuencode](../../../../index.md#uuencode)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts
|
Added embedded/md/tcllib/files/modules/base64/yencode.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
[//000000001]: # (yencode - Text encoding & decoding binary data)
[//000000002]: # (Generated from file 'yencode.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (yencode(n) 1.1.2 tcllib "Text encoding & decoding binary data")
# NAME
yencode - Y-encode/decode binary data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OPTIONS](#section2)
- [References](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require yencode ?1.1.2?
[__::yencode::encode__ *string*](#1)
[__::yencode::decode__ *string*](#2)
[__::yencode::yencode__ ?__-name__ *string*? ?__-line__ *integer*? ?__-crc32__ *boolean*? (__-file__ *filename* | ?__--__? *string*)](#3)
[__::yencode::ydecode__ (__-file__ *filename* | ?__--__? *string*)](#4)
# <a name='description'></a>DESCRIPTION
This package provides a Tcl-only implementation of the yEnc file encoding. This
is a recently introduced method of encoding binary files for transmission
through Usenet. This encoding packs binary data into a format that requires an
8-bit clean transmission layer but that escapes characters special to the
*[NNTP](../../../../index.md#nntp)* posting protocols. See
[http://www.yenc.org/](http://www.yenc.org/) for details concerning the
algorithm.
- <a name='1'></a>__::yencode::encode__ *string*
returns the yEnc encoded data.
- <a name='2'></a>__::yencode::decode__ *string*
Decodes the given yEnc encoded data.
- <a name='3'></a>__::yencode::yencode__ ?__-name__ *string*? ?__-line__ *integer*? ?__-crc32__ *boolean*? (__-file__ *filename* | ?__--__? *string*)
Encode a file or block of data.
- <a name='4'></a>__::yencode::ydecode__ (__-file__ *filename* | ?__--__? *string*)
Decode a file or block of data. A file may contain more than one embedded
file so the result is a list where each element is a three element list of
filename, file size and data.
# <a name='section2'></a>OPTIONS
- -filename name
Cause the yencode or ydecode commands to read their data from the named file
rather that taking a string parameter.
- -name string
The encoded data header line contains the suggested file name to be used
when unpacking the data. Use this option to change this from the default of
"data.dat".
- -line integer
The yencoded data header line contains records the line length used during
the encoding. Use this option to select a line length other that the default
of 128. Note that NNTP imposes a 1000 character line length limit and some
gateways may have trouble with more than 255 characters per line.
- -crc32 boolean
The yEnc specification recommends the inclusion of a cyclic redundancy check
value in the footer. Use this option to change the default from *true* to
*false*.
% set d [yencode::yencode -file testfile.txt]
=ybegin line=128 size=584 name=testfile.txt
-o- data not shown -o-
=yend size=584 crc32=ded29f4f
# <a name='section3'></a>References
1. [http://www.yenc.org/yenc-draft.1.3.txt](http://www.yenc.org/yenc-draft.1.3.txt)
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *base64* 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.
# <a name='keywords'></a>KEYWORDS
[encoding](../../../../index.md#encoding), [yEnc](../../../../index.md#yenc),
[ydecode](../../../../index.md#ydecode), [yencode](../../../../index.md#yencode)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts
|
Added embedded/md/tcllib/files/modules/bee/bee.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
[//000000001]: # (bee - BitTorrent)
[//000000002]: # (Generated from file 'bee.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bee(n) 0.1 tcllib "BitTorrent")
# NAME
bee - BitTorrent Serialization Format Encoder/Decoder
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [ENCODER](#subsection1)
- [DECODER](#subsection2)
- [FORMAT DEFINITION](#section3)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require bee ?0.1?
[__::bee::encodeString__ *string*](#1)
[__::bee::encodeNumber__ *integer*](#2)
[__::bee::encodeListArgs__ *value*...](#3)
[__::bee::encodeList__ *list*](#4)
[__::bee::encodeDictArgs__ *key* *value*...](#5)
[__::bee::encodeDict__ *dict*](#6)
[__::bee::decode__ *string* ?*endvar*? ?*start*?](#7)
[__::bee::decodeIndices__ *string* ?*endvar*? ?*start*?](#8)
[__::bee::decodeChannel__ *chan* __-command__ *cmdprefix* ?__-exact__? ?__-prefix__ *data*?](#9)
[__cmdprefix__ __eof__ *token*](#10)
[__cmdprefix__ __error__ *token* *message*](#11)
[__cmdprefix__ __value__ *token* *value*](#12)
[__::bee::decodeCancel__ *token*](#13)
[__::bee::decodePush__ *token* *string*](#14)
# <a name='description'></a>DESCRIPTION
The __bee__ package provides de- and encoder commands for data in bencoding
(speak 'bee'), the serialization format for data and messages used by the
BitTorrent protocol.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>ENCODER
The package provides one encoder command for each of the basic forms, and two
commands per container, one taking a proper tcl data structure to encode in the
container, the other taking the same information as several arguments.
- <a name='1'></a>__::bee::encodeString__ *string*
Returns the bee-encoding of the *string*.
- <a name='2'></a>__::bee::encodeNumber__ *integer*
Returns the bee-encoding of the *integer* number.
- <a name='3'></a>__::bee::encodeListArgs__ *value*...
Takes zero or more bee-encoded values and returns the bee-encoding of their
list.
- <a name='4'></a>__::bee::encodeList__ *list*
Takes a list of bee-encoded values and returns the bee-encoding of the list.
- <a name='5'></a>__::bee::encodeDictArgs__ *key* *value*...
Takes zero or more pairs of keys and values and returns the bee-encoding of
the dictionary they form. The values are expected to be already bee-encoded,
but the keys must not be. Their encoding will be done by the command itself.
- <a name='6'></a>__::bee::encodeDict__ *dict*
Takes a dictionary list of string keys and bee-encoded values and returns
the bee-encoding of the list. Note that the keys in the input must not be
bee-encoded already. This will be done by the command itself.
## <a name='subsection2'></a>DECODER
The package provides two main decoder commands, one for decoding a string
expected to contain a complete data structure, the other for the incremental
decoding of bee-values arriving on a channel. The latter command is asynchronous
and provides the completed decoded values to the user through a command
callback.
- <a name='7'></a>__::bee::decode__ *string* ?*endvar*? ?*start*?
Takes the bee-encoding in the string and returns one decoded value. In the
case of this being a container all contained values are decoded recursively
as well and the result is a properly nested tcl list and/or dictionary.
If the optional *endvar* is set then it is the name of a variable to store
the index of the first character *after* the decoded value into. In other
words, if the string contains more than one value then *endvar* can be used
to obtain the position of the bee-value after the bee-value currently
decoded. together with *start*, see below, it is possible to iterate over
the string to extract all contained values.
The optional *start* index defaults to __0__, i.e. the beginning of the
string. It is the index of the first character of the bee-encoded value to
extract.
- <a name='8'></a>__::bee::decodeIndices__ *string* ?*endvar*? ?*start*?
Takes the same arguments as __::bee::decode__ and returns the same
information in *endvar*. The result however is different. Instead of the tcl
value contained in the *string* it returns a list describing the value with
respect to type and location (indices for the first and last character of
the bee-value). In case of a container the structure also contains the same
information for all the embedded values.
Formally the results for the various types of bee-values are:
* string
A list containing three elements:
The constant string __string__, denoting the type of the value.
An integer number greater than or equal to zero. This is the index of
the first character of the bee-value in the input *string*.
An integer number greater than or equal to zero. This is the index of
the last character of the bee-value in the input *string*.
*Note* that this information is present in the results for all four
types of bee-values, with only the first element changing according to
the type of the value.
* integer
The result is like for strings, except that the type element contains
the constant string __integer__.
* list
The result is like before, with two exceptions: One, the type element
contains the constant string __list__. And two, the result actually
contains four elements. The last element is new, and contains the index
data as described here for all elements of the bee-list.
* dictionary
The result is like for strings, except that the type element contains
the constant string __dict__. A fourth element is present as well, with
a slightly different structure than for lists. The element is a
dictionary mapping from the strings keys of the bee-dictionary to a list
containing two elements. The first of them is the index information for
the key, and the second element is the index information for the value
the key maps to. This structure is the only which contains not only
index data, but actual values from the bee-string. While the index
information of the keys is unique enough, i.e. serviceable as keys, they
are not easy to navigate when trying to find particular element. Using
the actual keys makes this much easier.
- <a name='9'></a>__::bee::decodeChannel__ *chan* __-command__ *cmdprefix* ?__-exact__? ?__-prefix__ *data*?
The command creates a decoder for a series of bee-values arriving on the
channel *chan* and returns its handle. This handle can be used to remove the
decoder again. Setting up another bee decoder on *chan* while a bee decoder
is still active will fail with an error message.
* __-command__
The command prefix *cmdprefix* specified by the *required* option
__-command__ is used to report extracted values and exceptional
situations (error, and EOF on the channel). The callback will be
executed at the global level of the interpreter, with two or three
arguments. The exact call signatures are
+ <a name='10'></a>__cmdprefix__ __eof__ *token*
The decoder has reached eof on the channel *chan*. No further
invocations of the callback will be made after this. The channel has
already been closed at the time of the call, and the *token* is not
valid anymore as well.
+ <a name='11'></a>__cmdprefix__ __error__ *token* *message*
The decoder encountered an error, which is not eof. For example a
malformed bee-value. The *message* provides details about the error.
The decoder token is in the same state as for eof, i.e. invalid. The
channel however is kept open.
+ <a name='12'></a>__cmdprefix__ __value__ *token* *value*
The decoder received and successfully decoded a bee-value. The
format of the equivalent tcl *value* is the same as returned by
__::bee::decode__. The channel is still open and the decoder token
is valid. This means that the callback is able to remove the
decoder.
* __-exact__
By default the decoder assumes that the remainder of the data in the
channel consists only of bee-values, and reads as much as possible per
event, without regard for boundaries between bee-values. This means that
if the the input contains non-bee data after a series of bee-value the
beginning of that data may be lost because it was already read by the
decoder, but not processed.
The __-exact__ was made for this situation. When specified the decoder
will take care to not read any characters behind the currently processed
bee-value, so that any non-bee data is kept in the channel for further
processing after removal of the decoder.
* __-prefix__
If this option is specified its value is assumed to be the beginning of
the bee-value and used to initialize the internal decoder buffer. This
feature is required if the creator of the decoder used data from the
channel to determine if it should create the decoder or not. Without the
option this data would be lost to the decoding.
- <a name='13'></a>__::bee::decodeCancel__ *token*
This command cancels the decoder set up by __::bee::decodeChannel__ and
represented by the handle *token*.
- <a name='14'></a>__::bee::decodePush__ *token* *string*
This command appends the *string* to the internal decoder buffer. It is the
runtime equivalent of the option __-prefix__ of __::bee::decodeChannel__.
Use it to push data back into the decoder when the __value__ callback used
data from the channel to determine if it should decode another bee-value or
not.
# <a name='section3'></a>FORMAT DEFINITION
Data in the bee serialization format is constructed from two basic forms, and
two container forms. The basic forms are strings and integer numbers, and the
containers are lists and dictionaries.
- String *S*
A string *S* of length *L* is encoded by the string "*L*__:__*S*", where the
length is written out in textual form.
- Integer *N*
An integer number *N* is encoded by the string "__i__*N*__e__".
- List *v1* ... *vn*
A list of the values *v1* to *vn* is encoded by the string
"__l__*BV1*...*BVn*__e__" where "BV__i__" is the bee-encoding of the value
"v__i__".
- Dict *k1* -> *v1* ...
A dictionary mapping the string key *k*__i__ to the value *v*__i__, for
__i__ in __1__ ... __n__ is encoded by the string
"__d__*BK*__i__*BV*__i__...__e__" for i in __1__ ... __n__, where "BK__i__"
is the bee-encoding of the key string "k__i__". and "BV__i__" is the
bee-encoding of the value "v__i__".
*Note*: The bee-encoding does not retain the order of the keys in the input,
but stores in a sorted order. The sorting is done for the "raw strings".
Note that the type of each encoded item can be determined immediately from the
first character of its representation:
- i
Integer.
- l
List.
- d
Dictionary.
- [0-9]
String.
By wrapping an integer number into __i__...__e__ the format makes sure that they
are different from strings, which all begin with a digit.
# <a name='section4'></a>EXAMPLES
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bee* 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.
# <a name='keywords'></a>KEYWORDS
[BitTorrent](../../../../index.md#bittorrent), [bee](../../../../index.md#bee),
[bittorrent](../../../../index.md#bittorrent),
[serialization](../../../../index.md#serialization),
[torrent](../../../../index.md#torrent)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
[//000000001]: # (bench - Benchmarking/Performance tools)
[//000000002]: # (Generated from file 'bench.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench(n) 0.4 tcllib "Benchmarking/Performance tools")
# NAME
bench - bench - Processing benchmark suites
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [Benchmark execution](#subsection1)
- [Result manipulation](#subsection2)
- [Result format](#subsection3)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require bench ?0.4?
[__::bench::locate__ *pattern* *paths*](#1)
[__::bench::run__ ?*option value*...? *interp_list* *file*...](#2)
[__::bench::versions__ *interp_list*](#3)
[__::bench::del__ *bench_result* *column*](#4)
[__::bench::edit__ *bench_result* *column* *newvalue*](#5)
[__::bench::merge__ *bench_result*...](#6)
[__::bench::norm__ *bench_result* *column*](#7)
[__::bench::out::raw__ *bench_result*](#8)
# <a name='description'></a>DESCRIPTION
This package provides commands for the execution of benchmarks written in the
bench language, and for the processing of results generated by such execution.
A reader interested in the bench language itself should start with the *[bench
language introduction](bench_lang_intro.md)* and proceed from there to the
formal *[bench language specification](bench_lang_spec.md)*.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>Benchmark execution
- <a name='1'></a>__::bench::locate__ *pattern* *paths*
This command locates Tcl interpreters and returns a list containing their
paths. It searches them in the list of *paths* specified by the caller,
using the glob *pattern*.
The command resolves soft links to find the actual executables matching the
pattern. Note that only interpreters which are marked as executable and are
actually executable on the current platform are put into the result.
- <a name='2'></a>__::bench::run__ ?*option value*...? *interp_list* *file*...
This command executes the benchmarks declared in the set of files, once per
Tcl interpreter specified via the *interp_list*, and per the configuration
specified by the options, and then returns the accumulated timing results.
The format of this result is described in section [Result
format](#subsection3).
It is assumed that the contents of the files are written in the bench
language.
The available options are
* __-errors__ *flag*
The argument is a boolean value. If set errors in benchmarks are
propagated to the command, aborting benchmark execution. Otherwise they
are recorded in the timing result via a special result code. The default
is to propagate and abort.
* __-threads__ *n*
The argument is a non-negative integer value declaring the number of
threads to use while executing the benchmarks. The default value is
__0__, to not use threads.
* __-match__ *pattern*
The argument is a glob pattern. Only benchmarks whose description
matches the pattern are executed. The default is the empty string, to
execute all patterns.
* __-rmatch__ *pattern*
The argument is a regular expression pattern. Only benchmarks whose
description matches the pattern are executed. The default is the empty
string, to execute all patterns.
* __-iters__ *n*
The argument is positive integer number, the maximal number of
iterations for any benchmark. The default is __1000__. Individual
benchmarks can override this.
* __-pkgdir__ *path*
The argument is a path to an existing, readable directory. Multiple
paths can be specified, simply use the option multiple times, each time
with one of the paths to use.
If no paths were specified the system will behave as before. If one or
more paths are specified, say __N__, each of the specified interpreters
will be invoked __N__ times, with one of the specified paths. The chosen
path is put into the interpreters' __auto_path__, thus allowing it to
find specific versions of a package.
In this way the use of __-pkgdir__ allows the user to benchmark several
different versions of a package, against one or more interpreters.
*Note:* The empty string is allowed as a path and causes the system to
run the specified interpreters with an unmodified __auto_path__. In case
the package in question is available there as well.
- <a name='3'></a>__::bench::versions__ *interp_list*
This command takes a list of Tcl interpreters, identified by their path, and
returns a dictionary mapping from the interpreters to their versions.
Interpreters which are not actually executable, or fail when interrogated,
are not put into the result. I.e the result may contain less interpreters
than there in the input list.
The command uses builtin command __info patchlevel__ to determine the
version of each interpreter.
## <a name='subsection2'></a>Result manipulation
- <a name='4'></a>__::bench::del__ *bench_result* *column*
This command removes a column, i.e. all benchmark results for a specific Tcl
interpreter, from the specified benchmark result and returns the modified
result.
The benchmark results are in the format described in section [Result
format](#subsection3).
The column is identified by an integer number.
- <a name='5'></a>__::bench::edit__ *bench_result* *column* *newvalue*
This command renames a column in the specified benchmark result and returns
the modified result. This means that the path of the Tcl interpreter in the
identified column is changed to an arbitrary string.
The benchmark results are in the format described in section [Result
format](#subsection3).
The column is identified by an integer number.
- <a name='6'></a>__::bench::merge__ *bench_result*...
This commands takes one or more benchmark results, merges them into one big
result, and returns that as its result.
All benchmark results are in the format described in section [Result
format](#subsection3).
- <a name='7'></a>__::bench::norm__ *bench_result* *column*
This command normalizes the timing results in the specified benchmark result
and returns the modified result. This means that the cell values are not
times anymore, but factors showing how much faster or slower the execution
was relative to the baseline.
The baseline against which the command normalizes are the timing results in
the chosen column. This means that after the normalization the values in
this column are all __1__, as these benchmarks are neither faster nor slower
than the baseline.
A factor less than __1__ indicates a benchmark which was faster than the
baseline, whereas a factor greater than __1__ indicates a slower execution.
The benchmark results are in the format described in section [Result
format](#subsection3).
The column is identified by an integer number.
- <a name='8'></a>__::bench::out::raw__ *bench_result*
This command formats the specified benchmark result for output to a file,
socket, etc. This specific command does no formatting at all, it passes the
input through unchanged.
For other formatting styles see the packages
__[bench::out::text](bench_wtext.md)__ and
__[bench::out::csv](bench_wcsv.md)__ which provide commands to format
benchmark results for human consumption, or as CSV data importable by spread
sheets, respectively.
Complementary, to read benchmark results from files, sockets etc. look for
the package __[bench::in](bench_read.md)__ and the commands provided by it.
## <a name='subsection3'></a>Result format
After the execution of a set of benchmarks the raw result returned by this
package is a Tcl dictionary containing all the relevant information. The
dictionary is a compact representation, i.e. serialization, of a 2-dimensional
table which has Tcl interpreters as columns and benchmarks as rows. The cells of
the table contain the timing results. The Tcl interpreters / columns are
identified by their paths. The benchmarks / rows are identified by their
description.
The possible keys are all valid Tcl lists of two or three elements and have one
of the following forms:
- {interp *}
The set of keys matching this glob pattern capture the information about all
the Tcl interpreters used to run the benchmarks. The second element of the
key is the path to the interpreter.
The associated value is the version of the Tcl interpreter.
- {desc *}
The set of keys matching this glob pattern capture the information about all
the benchmarks found in the executed benchmark suite. The second element of
the key is the description of the benchmark, which has to be unique.
The associated value is irrelevant, and set to the empty string.
- {usec * *}
The set of keys matching this glob pattern capture the performance
information, i.e. timing results. The second element of the key is the
description of the benchmark, the third element the path of the Tcl
interpreter which was used to run it.
The associated value is either one of several special result codes, or the
time it took to execute the benchmark, in microseconds. The possible special
result codes are
* ERR
Benchmark could not be executed, failed with a Tcl error.
* BAD_RES
The benchmark could be executed, however the result from its body did
not match the declared expectations.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench_intro](bench_intro.md), [bench_lang_intro](bench_lang_intro.md),
[bench_lang_spec](bench_lang_spec.md), bench_read, bench_wcsv, bench_wtext
# <a name='keywords'></a>KEYWORDS
[benchmark](../../../../index.md#benchmark),
[merging](../../../../index.md#merging),
[normalization](../../../../index.md#normalization),
[performance](../../../../index.md#performance),
[testing](../../../../index.md#testing)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
[//000000001]: # (bench_intro - Benchmarking/Performance tools)
[//000000002]: # (Generated from file 'bench_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench_intro(n) 1.0 tcllib "Benchmarking/Performance tools")
# NAME
bench_intro - bench introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [HISTORICAL NOTES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
The *[bench](bench.md)* (short for *benchmark tools*), is a set of related, yet
different, entities which are working together for the easy creation and
execution of performance test suites, also known as benchmarks. These are
1. A tcl based language for the declaration of test cases. A test case is
represented by a tcl command declaring the various parts needed to execute
it, like setup, cleanup, the commands to test, etc.
1. A package providing the ability to execute test cases written in that
language.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the benchmarking process.
1. A *writer* of benchmarks has to understand the bench language itself. A
beginner to bench should read the more informally written *[bench language
introduction](bench_lang_intro.md)* first. Having digested this the formal
*[bench language specification](bench_lang_spec.md)* should become
understandable. A writer experienced with bench may only need this last
document from time to time, to refresh her memory.
1. A *user* of benchmark suites written in the *[bench](bench.md)* language
has to know which tools are available for use. At the bottom level sits the
package __[bench](bench.md)__, providing the basic facilities to read and
execute files containing benchmarks written in the bench language, and to
manipulate benchmark results.
# <a name='section2'></a>HISTORICAL NOTES
This module and package have been derived from Jeff Hobbs' __tclbench__
application for the benchmarking of the Tcl core and its ancestor
"runbench.tcl".
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench](bench.md), bench_lang_faq, [bench_lang_intro](bench_lang_intro.md),
[bench_lang_spec](bench_lang_spec.md)
# <a name='keywords'></a>KEYWORDS
[bench language](../../../../index.md#bench_language),
[benchmark](../../../../index.md#benchmark),
[performance](../../../../index.md#performance),
[testing](../../../../index.md#testing)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench_lang_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
[//000000001]: # (bench_lang_intro - Benchmarking/Performance tools)
[//000000002]: # (Generated from file 'bench_lang_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench_lang_intro(n) 1.0 tcllib "Benchmarking/Performance tools")
# NAME
bench_lang_intro - bench language introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#subsection1)
- [Basics](#subsection2)
- [Pre- and postprocessing](#subsection3)
- [Advanced pre- and postprocessing](#subsection4)
- [FURTHER READING](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document is an informal introduction to version 1 of the bench language
based on a multitude of examples. After reading this a benchmark writer should
be ready to understand the formal *[bench language
specification](bench_lang_spec.md)*.
## <a name='subsection1'></a>Fundamentals
In the broadest terms possible the *[bench
language](../../../../index.md#bench_language)* is essentially Tcl, plus a
number of commands to support the declaration of benchmarks. A document written
in this language is a Tcl script and has the same syntax.
## <a name='subsection2'></a>Basics
One of the most simplest benchmarks which can be written in bench is
bench -desc LABEL -body {
set a b
}
This code declares a benchmark named __LABEL__ which measures the time it takes
to assign a value to a variable. The Tcl code doing this assignment is the
__-body__ of the benchmark.
## <a name='subsection3'></a>Pre- and postprocessing
Our next example demonstrates how to declare *initialization* and
*[cleanup](../../../../index.md#cleanup)* code, i.e. code computing information
for the use of the __-body__, and for releasing such resources after the
measurement is done. They are the __-pre__- and the __-post__-body,
respectively.
In our example, directly drawn from the benchmark suite of Tcllib's
__[aes](../aes/aes.md)__ package, the concrete initialization code constructs
the key schedule used by the encryption command whose speed we measure, and the
cleanup code releases any resources bound to that schedule.
bench -desc "AES-${len} ECB encryption core" __-pre__ {
set key [aes::Init ecb $k $i]
} -body {
aes::Encrypt $key $p
} __-post__ {
aes::Final $key
}
## <a name='subsection4'></a>Advanced pre- and postprocessing
Our last example again deals with initialization and cleanup code. To see the
difference to the regular initialization and cleanup discussed in the last
section it is necessary to know a bit more about how bench actually measures the
speed of the the __-body__.
Instead of running the __-body__ just once the system actually executes the
__-body__ several hundred times and then returns the average of the found
execution times. This is done to remove environmental effects like machine load
from the result as much as possible, with outliers canceling each other out in
the average.
The drawback of doing things this way is that when we measure operations which
are not idempotent we will most likely not measure the time for the operation we
want, but of the state(s) the system is in after the first iteration, a mixture
of things we have no interest in.
Should we wish, for example, to measure the time it takes to include an element
into a set, with the element not yet in the set, and the set having specific
properties like being a shared Tcl_Obj, then the first iteration will measure
the time for this. *However* all subsequent iterations will measure the time to
include an element which is already in the set, and the Tcl_Obj holding the set
will not be shared anymore either. In the end the timings taken for the several
hundred iterations of this state will overwhelm the time taken from the first
iteration, the only one which actually measured what we wanted.
The advanced initialization and cleanup codes, __-ipre__- and the
__-ipost__-body respectively, are present to solve this very problem. While the
regular initialization and cleanup codes are executed before and after the whole
series of iterations the advanced codes are executed before and after each
iteration of the body, without being measured themselves. This allows them to
bring the system into the exact state the body wishes to measure.
Our example, directly drawn from the benchmark suite of Tcllib's
__[struct::set](../struct/struct_set.md)__ package, is for exactly the example
we used above to demonstrate the necessity for the advanced initialization and
cleanup. Its concrete initialization code constructs a variable refering to a
set with specific properties (The set has a string representation, which is
shared) affecting the speed of the inclusion command, and the cleanup code
releases the temporary variables created by this initialization.
bench -desc "set include, missing <SC> x$times $n" __-ipre__ {
set A $sx($times,$n)
set B $A
} -body {
struct::set include A x
} __-ipost__ {
unset A B
}
# <a name='section2'></a>FURTHER READING
Now that this document has been digested the reader, assumed to be a *writer* of
benchmarks, he should be fortified enough to be able to understand the formal
*bench language specfication*. It will also serve as the detailed specification
and cheat sheet for all available commands and their syntax.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench_intro](bench_intro.md), [bench_lang_spec](bench_lang_spec.md)
# <a name='keywords'></a>KEYWORDS
[bench language](../../../../index.md#bench_language),
[benchmark](../../../../index.md#benchmark),
[examples](../../../../index.md#examples),
[performance](../../../../index.md#performance),
[testing](../../../../index.md#testing)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench_lang_spec.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
[//000000001]: # (bench_lang_spec - Documentation tools)
[//000000002]: # (Generated from file 'bench_lang_spec.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench_lang_spec(n) 1.0 tcllib "Documentation tools")
# NAME
bench_lang_spec - bench language specification
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__bench_rm__ *path*...](#1)
[__bench_tmpfile__](#2)
[__[bench](bench.md)__ *options*...](#3)
# <a name='description'></a>DESCRIPTION
This document specifies both names and syntax of all the commands which together
are the bench language, version 1. As this document is intended to be a
reference the commands are listed in alphabetical order, and the descriptions
are relatively short. A beginner should read the more informally written *[bench
language introduction](bench_lang_intro.md)* first.
# <a name='section2'></a>Commands
- <a name='1'></a>__bench_rm__ *path*...
This command silently removes the files specified as its arguments and then
returns the empty string as its result. The command is *trusted*, there is
no checking if the specified files are outside of whatever restricted area
the benchmarks are run in.
- <a name='2'></a>__bench_tmpfile__
This command returns the path to a bench specific unique temporary file. The
uniqueness means that multiple calls will return different paths. While the
path may exist from previous runs, the command itself does *not* create
aynthing.
The base location of the temporary files is platform dependent:
* Unix, and indeterminate platform
"/tmp"
* Windows
__$TEMP__
* Anything else
The current working directory.
- <a name='3'></a>__[bench](bench.md)__ *options*...
This command declares a single benchmark. Its result is the empty string.
All parts of the benchmark are declared via options, and their values. The
options can occur in any order. The accepted options are:
* __-body__ script
The argument of this option declares the body of the benchmark, the Tcl
script whose performance we wish to measure. This option, and __-desc__,
are the two required parts of each benchmark.
* __-desc__ msg
The argument of this option declares the name of the benchmark. It has
to be unique, or timing data from different benchmarks will be mixed
together.
*Beware!* This requirement is not checked when benchmarks are executed,
and the system will silently produce bogus data. This option, and
__-body__, are the two required parts of each benchmark.
* __-ipost__ script
The argument of this option declares a script which is run immediately
*after* each iteration of the body. Its responsibility is to release
resources created by the body, or __-ipre__-bodym which we do not wish
to live into the next iteration.
* __-ipre__ script
The argument of this option declares a script which is run immediately
*before* each iteration of the body. Its responsibility is to create the
state of the system expected by the body so that we measure the right
thing.
* __-iterations__ num
The argument of this option declares the maximum number of times to run
the __-body__ of the benchmark. During execution this and the global
maximum number of iterations are compared and the smaller of the two
values is used.
This option should be used only for benchmarks which are expected or
known to take a long time per run. I.e. reduce the number of times they
are run to keep the overall time for the execution of the whole
benchmark within manageable limits.
* __-post__ script
The argument of this option declares a script which is run *after* all
iterations of the body have been run. Its responsibility is to release
resources created by the body, or __-pre__-body.
* __-pre__ script
The argument of this option declares a script which is run *before* any
of the iterations of the body are run. Its responsibility is to create
whatever resources are needed by the body to run without failing.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench_intro](bench_intro.md), [bench_lang_intro](bench_lang_intro.md)
# <a name='keywords'></a>KEYWORDS
[bench language](../../../../index.md#bench_language),
[benchmark](../../../../index.md#benchmark),
[performance](../../../../index.md#performance),
[specification](../../../../index.md#specification),
[testing](../../../../index.md#testing)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench_read.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
[//000000001]: # (bench::in - Benchmarking/Performance tools)
[//000000002]: # (Generated from file 'bench_read.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench::in(n) 0.1 tcllib "Benchmarking/Performance tools")
# NAME
bench::in - bench::in - Reading benchmark results
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require csv
package require bench::in ?0.1?
[__::bench::in::read__ *file*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a command for reading benchmark results from files,
sockets, etc.
A reader interested in the creation, processing or writing of such results
should go and read *[bench - Processing benchmark suites](bench.md)* instead.
If the bench language itself is the actual interest please start with the
*[bench language introduction](bench_lang_intro.md)* and then proceed from there
to the formal *[bench language specification](bench_lang_spec.md)*.
# <a name='section2'></a>PUBLIC API
- <a name='1'></a>__::bench::in::read__ *file*
This command reads a benchmark result from the specified *file* and returns
it as its result. The command understands the three formats created by the
commands
* __bench::out::raw__
Provided by package __[bench](bench.md)__.
* __[bench::out::csv](bench_wcsv.md)__
Provided by package __[bench::out::csv](bench_wcsv.md)__.
* __[bench::out::text](bench_wtext.md)__
Provided by package __[bench::out::text](bench_wtext.md)__.
and automatically detects which format is used by the input file.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench](bench.md), [bench::out::csv](bench_wcsv.md),
[bench::out::text](bench_wtext.md), [bench_intro](bench_intro.md)
# <a name='keywords'></a>KEYWORDS
[benchmark](../../../../index.md#benchmark), [csv](../../../../index.md#csv),
[formatting](../../../../index.md#formatting), [human
readable](../../../../index.md#human_readable),
[parsing](../../../../index.md#parsing),
[performance](../../../../index.md#performance),
[reading](../../../../index.md#reading),
[testing](../../../../index.md#testing), [text](../../../../index.md#text)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench_wcsv.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
[//000000001]: # (bench::out::csv - Benchmarking/Performance tools)
[//000000002]: # (Generated from file 'bench_wcsv.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench::out::csv(n) 0.1.2 tcllib "Benchmarking/Performance tools")
# NAME
bench::out::csv - bench::out::csv - Formatting benchmark results as CSV
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require bench::out::csv ?0.1.2?
[__::bench::out::csv__ *bench_result*](#1)
# <a name='description'></a>DESCRIPTION
This package provides commands for fomatting of benchmark results into a CSV
table importable by spread sheets.
A reader interested in the generation or processing of such results should go
and read *[bench - Processing benchmark suites](bench.md)* instead.
If the bench language itself is the actual interest please start with the
*[bench language introduction](bench_lang_intro.md)* and then proceed from there
to the formal *[bench language specification](bench_lang_spec.md)*.
# <a name='section2'></a>PUBLIC API
- <a name='1'></a>__::bench::out::csv__ *bench_result*
This command formats the specified benchmark result for output to a file,
socket, etc. This specific command generates CSV data importable by spread
sheets.
For other formatting styles see the packages __[bench](bench.md)__ and
__[bench::out::text](bench_wtext.md)__ which provide commands to format
benchmark results in raw form, or for human consumption, respectively.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench](bench.md), [bench::out::text](bench_wtext.md)
# <a name='keywords'></a>KEYWORDS
[benchmark](../../../../index.md#benchmark), [csv](../../../../index.md#csv),
[formatting](../../../../index.md#formatting),
[performance](../../../../index.md#performance),
[testing](../../../../index.md#testing)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bench/bench_wtext.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
[//000000001]: # (bench::out::text - Benchmarking/Performance tools)
[//000000002]: # (Generated from file 'bench_wtext.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bench::out::text(n) 0.1.2 tcllib "Benchmarking/Performance tools")
# NAME
bench::out::text - bench::out::text - Formatting benchmark results as human
readable text
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require bench::out::text ?0.1.2?
[__::bench::out::text__ *bench_result*](#1)
# <a name='description'></a>DESCRIPTION
This package provides commands for fomatting of benchmark results into human
readable text.
A reader interested in the generation or processing of such results should go
and read *[bench - Processing benchmark suites](bench.md)* instead.
If the bench language itself is the actual interest please start with the
*[bench language introduction](bench_lang_intro.md)* and then proceed from there
to the formal *[bench language specification](bench_lang_spec.md)*.
# <a name='section2'></a>PUBLIC API
- <a name='1'></a>__::bench::out::text__ *bench_result*
This command formats the specified benchmark result for output to a file,
socket, etc. This specific command generates human readable text.
For other formatting styles see the packages __[bench](bench.md)__ and
__[bench::out::csv](bench_wcsv.md)__ which provide commands to format
benchmark results in raw form, or as importable CSV data, respectively.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bench* 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.
# <a name='see-also'></a>SEE ALSO
[bench](bench.md), [bench::out::csv](bench_wcsv.md)
# <a name='keywords'></a>KEYWORDS
[benchmark](../../../../index.md#benchmark),
[formatting](../../../../index.md#formatting), [human
readable](../../../../index.md#human_readable),
[performance](../../../../index.md#performance),
[testing](../../../../index.md#testing), [text](../../../../index.md#text)
# <a name='category'></a>CATEGORY
Benchmark tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/bibtex/bibtex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
[//000000001]: # (bibtex - bibtex)
[//000000002]: # (Generated from file 'bibtex.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (bibtex(n) 0.6 tcllib "bibtex")
# NAME
bibtex - Parse bibtex files
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require bibtex ?0.6?
[__::bibtex::parse__ ?*options*? ?*text*?](#1)
[__::bibtex::parse__ *text*](#2)
[__::bibtex::parse__ ?__-command__ *cmd*? __-channel__ *chan*](#3)
[__::bibtex::parse__ ?__-recordcommand__ *recordcmd*? ?__-preamblecommand__ *preamblecmd*? ?__-stringcommand__ *stringcmd*? ?__-commentcommand__ *commentcmd*? ?__-progresscommand__ *progresscmd*? ?__-casesensitivestrings__ *bool*? (*text* | __-channel__ *chan*)](#4)
[__::bibtex::wait__ *token*](#5)
[__::bibtex::destroy__ *token*](#6)
[__::bibtex::addStrings__ *token* *stringdict*](#7)
# <a name='description'></a>DESCRIPTION
This package provides commands for the parsing of bibliographies in BibTeX
format.
- <a name='1'></a>__::bibtex::parse__ ?*options*? ?*text*?
This is the general form of the command for parsing a bibliography.
Depending on the options used to invoke it it will either return a token for
the parser, or the parsed entries of the input bibliography. Instead of
performing an immediate parse returning a predefined format the command can
also enter an event-based parsing style where all relevant entries in the
input are reported through callback commands, in the style of SAX.
- <a name='2'></a>__::bibtex::parse__ *text*
In this form the command will assume that the specified *text* is a
bibliography in BibTeX format, parse it, and then return a list containing
one element per record found in the bibliography. Note that comments, string
definitions, preambles, etc. will not show up in the result. Each element
will be a list containing record type, bibliography key and record data, in
this order. The record data will be a dictionary, its keys the keys of the
record, with the associated values.
- <a name='3'></a>__::bibtex::parse__ ?__-command__ *cmd*? __-channel__ *chan*
In this form the command will reads the bibliography from the specified Tcl
channel *chan* and then returns the same data structure as described above.
If however the option __-command__ is specified the result will be a handle
for the parser instead and all processing will be incremental and happen in
the background. When the input has been exhausted the callback *cmd* will be
invoked with the result of the parse. The exact definition for the callback
is
* __cmd__ *token* *parseresult*
The parse result will have the structure explained above, for the
simpler forms of the parser.
*Note* that the parser will *not* close the channel after it has exhausted
it. This is still the responsibility of the user of the parser.
- <a name='4'></a>__::bibtex::parse__ ?__-recordcommand__ *recordcmd*? ?__-preamblecommand__ *preamblecmd*? ?__-stringcommand__ *stringcmd*? ?__-commentcommand__ *commentcmd*? ?__-progresscommand__ *progresscmd*? ?__-casesensitivestrings__ *bool*? (*text* | __-channel__ *chan*)
This is the most low-level form for the parser. The returned result will be
a handle for the parser. During processing it will invoke the invoke the
specified callback commands for each type of data found in the bibliography.
The processing will be incremental and happen in the background if, and only
if a Tcl channel *chan* is specified. For a *text* the processing will
happen immediately and all callbacks will be invoked before the command
itself returns.
The callbacks, i.e. **cmd*, are all command prefixes and will be invoked
with additional arguments appended to them. The meaning of the arguments
depends on the callback and is explained below. The first argument will
however always be the handle of the parser invoking the callback.
* __-casesensitivestrings__
This option takes a boolean value. When set string macro processing
becomes case-sensitive. The default is case-insensitive string macro
processing.
* __recordcmd__ *token* *type* *key* *recorddict*
This callback is invoked whenever the parser detects a bibliography
record in the input. Its arguments are the record type, the bibliography
key for the record, and a dictionary containing the keys and values
describing the record. Any string macros known to the parser have
already been expanded.
* __preamblecmd__ *token* *preambletext*
This callback is invoked whenever the parser detects an @preamble block
in the input. The only additional argument is the text found in the
preamble block. By default such entries are ignored.
* __stringcmd__ *token* *stringdict*
This callback is invoked whenever the parser detects an @string-based
macro definition in the input. The argument is a dictionary with the
macro names as keys and their replacement strings as values. By default
such definitions are added to the parser state for use in future
bibliography records.
* __commentcmd__ *token* *commenttext*
This callback is invoked whenever the parser detects a comment in the
input. The only additional argument is the comment text. By default such
entries are ignored.
* __progresscmd__ *token* *percent*
This callback is invoked during processing to tell the user about the
progress which has been made. Its argument is the percentage of data
processed, as integer number between __0__ and __100__. In the case of
incremental processing the perecentage will always be __-1__ as the
total number of entries is not known beforehand.
- <a name='5'></a>__::bibtex::wait__ *token*
This command waits for the parser represented by the *token* to complete and
then returns. The returned result is the empty string.
- <a name='6'></a>__::bibtex::destroy__ *token*
This command cleans up all internal state associated with the parser
represented by the handle *token*, effectively destroying it. This command
can be called from within the parser callbacks to terminate processing.
- <a name='7'></a>__::bibtex::addStrings__ *token* *stringdict*
This command adds the macro definitions stored in the dictionary
*stringdict* to the parser represented by the handle *token*.
The dictionary keys are the macro names and the values their replacement
strings. This command has the correct signature for use as a
__-stringcommand__ callback in an invokation of the command
__::bibtex::parse__.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *bibtex* 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.
# <a name='keywords'></a>KEYWORDS
[bibliography](../../../../index.md#bibliography),
[bibtex](../../../../index.md#bibtex), [parsing](../../../../index.md#parsing),
[text processing](../../../../index.md#text_processing)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 for documentation, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/blowfish/blowfish.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
[//000000001]: # (blowfish - Blowfish Block Cipher)
[//000000002]: # (Generated from file 'blowfish.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (blowfish(n) 1.0.3 tcllib "Blowfish Block Cipher")
# NAME
blowfish - Implementation of the Blowfish block cipher
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [MODES OF OPERATION](#section4)
- [EXAMPLES](#section5)
- [REFERENCES](#section6)
- [AUTHORS](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require blowfish ?1.0.4?
[__::blowfish::blowfish__ ?*-mode [ecb|cbc]*? ?*-dir [encrypt|decrypt]*? *-key keydata* ?*-iv vector*? ?*-out channel*? ?*-chunksize size*? ?*-pad padchar*? [ *-in channel* | ?*--*? *data* ]](#1)
[__::blowfish::Init__ *mode* *keydata* *iv*](#2)
[__::blowfish::Encrypt__ *Key* *data*](#3)
[__::blowfish::Decrypt__ *Key* *data*](#4)
[__::blowfish::Reset__ *Key* *iv*](#5)
[__::blowfish::Final__ *Key*](#6)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the Blowfish algorithm developed by
Bruce Schneier [1]. Blowfish is a 64-bit block cipher designed to operate
quickly on 32 bit architectures and accepting a variable key length. This
implementation supports ECB and CBC mode blowfish encryption.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::blowfish::blowfish__ ?*-mode [ecb|cbc]*? ?*-dir [encrypt|decrypt]*? *-key keydata* ?*-iv vector*? ?*-out channel*? ?*-chunksize size*? ?*-pad padchar*? [ *-in channel* | ?*--*? *data* ]
Perform the __blowfish__ algorithm on either the data provided by the
argument or on the data read from the *-in* channel. If an *-out* channel is
given then the result will be written to this channel.
The *-key* option must be given. This parameter takes a binary string of
variable length and is used to generate the __blowfish__ key schedule. You
should be aware that creating a key schedule is quite an expensive operation
in blowfish so it is worth reusing the key where possible. See __Reset__.
The *-mode* and *-dir* options are optional and default to cbc mode and
encrypt respectively. The initialization vector *-iv* takes an 8 byte binary
argument which defaults to 8 zeros. See [MODES OF OPERATION](#section4) for
more about available modes and their uses.
Blowfish is a 64-bit block cipher. This means that the data must be provided
in units that are a multiple of 8 bytes. The __blowfish__ command will by
default add nul characters to pad the input data to a multiple of 8 bytes if
necessary. The programming api commands will never add padding and instead
will raise an error if the input is not a multiple of the block size. The
*-pad* option can be used to change the padding character or to disable
padding if the empty string is provided as the argument.
# <a name='section3'></a>PROGRAMMING INTERFACE
- <a name='2'></a>__::blowfish::Init__ *mode* *keydata* *iv*
Construct a new blowfish key schedule using the specified key data and the
given initialization vector. The initialization vector is not used with ECB
mode but is important for CBC mode. See [MODES OF OPERATION](#section4) for
details about cipher modes.
- <a name='3'></a>__::blowfish::Encrypt__ *Key* *data*
Use a prepared key acquired by calling __Init__ to encrypt the provided
data. The data argument should be a binary array that is a multiple of the
block size of 8 bytes. The result is a binary array the same size as the
input of encrypted data.
- <a name='4'></a>__::blowfish::Decrypt__ *Key* *data*
Decipher data using the key. Note that the same key may be used to encrypt
and decrypt data provided that the initialization vector is reset
appropriately for CBC mode.
- <a name='5'></a>__::blowfish::Reset__ *Key* *iv*
Reset the initialization vector. This permits the programmer to re-use a key
and avoid the cost of re-generating the key schedule where the same key data
is being used multiple times.
- <a name='6'></a>__::blowfish::Final__ *Key*
This should be called to clean up resources associated with *Key*. Once this
function has been called the key may not be used again.
# <a name='section4'></a>MODES OF OPERATION
- Electronic Code Book (ECB)
ECB is the basic mode of all block ciphers. Each block is encrypted
independently and so identical plain text will produce identical output when
encrypted with the same key. Any encryption errors will only affect a single
block however this is vulnerable to known plaintext attacks.
- Cipher Block Chaining (CBC)
CBC mode uses the output of the last block encryption to affect the current
block. An initialization vector of the same size as the cipher block size is
used to handle the first block. The initialization vector should be chosen
randomly and transmitted as the first block of the output. Errors in
encryption affect the current block and the next block after which the
cipher will correct itself. CBC is the most commonly used mode in software
encryption.
# <a name='section5'></a>EXAMPLES
% blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!"
d0d8f27e7a374b9e2dbd9938dd04195a
set Key [blowfish::Init cbc $eight_bytes_key_data $eight_byte_iv]
append ciphertext [blowfish::Encrypt $Key $plaintext]
append ciphertext [blowfish::Encrypt $Key $additional_plaintext]
blowfish::Final $Key
# <a name='section6'></a>REFERENCES
1. Schneier, B. "Applied Cryptography, 2nd edition", 1996, ISBN 0-471-11709-9,
pub. John Wiley & Sons.
# <a name='section7'></a>AUTHORS
Frank Pilhofer, Pat Thoyts
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *blowfish* 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.
# <a name='see-also'></a>SEE ALSO
3des, [des](../des/des.md), [rc4](../rc4/rc4.md)
# <a name='keywords'></a>KEYWORDS
[block cipher](../../../../index.md#block_cipher),
[blowfish](../../../../index.md#blowfish),
[cryptography](../../../../index.md#cryptography),
[encryption](../../../../index.md#encryption),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/cache/async.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
[//000000001]: # (cache::async - In-memory caches)
[//000000002]: # (Generated from file 'async.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (cache::async(n) 0.3.1 tcllib "In-memory caches")
# NAME
cache::async - Asynchronous in-memory cache
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require cache::async ?0.3.1?
[__::cache::async__ *objectName* *commandprefix* ?*options*...?](#1)
[*objectName* __get__ *key* *donecmdprefix*](#2)
[*objectName* __set__ *key* *value*](#3)
[*objectName* __unset__ *key*](#4)
[*objectName* __exists__ *key*](#5)
[*objectName* __clear__ ?*key*?](#6)
# <a name='description'></a>DESCRIPTION
This package provides objects which cache data in memory, and operate
asynchronously with regard to request and responses. The objects are agnostic
with regard to cache keys and values, and unknown methods are delegated to the
provider of cached data. These two properties make it easy to use caches as a
facade for any data provider.
# <a name='section2'></a>API
The package exports a class, __cache::async__, as specified below.
- <a name='1'></a>__::cache::async__ *objectName* *commandprefix* ?*options*...?
The command creates a new *[cache](../../../../index.md#cache)* object with
an associated global Tcl command whose name is *objectName*. This command
may be used to invoke various operations on the object.
The *commandprefix* is the action to perform when an user asks for data in
the cache and the cache doesn't yet know about the key. When run the
commandprefix is given three additional arguments, the string __get__, the
key requested, and the cache object itself, in the form of its object
command, in this order. The execution of the action is done in an
idle-handler, decoupling it from the original request.
The only supported option is
* __-full-async-results__
This option defines the behaviour of the cache for when requested keys
are known to the cache at the time of __get__ request. By default such
requeste are responded to asynchronously as well. Setting this option to
__false__ forces the cache to respond to them synchronuously, although
still through the specified callback.
The object commands created by the class commands above have the form:
- <a name='2'></a>*objectName* __get__ *key* *donecmdprefix*
This method requests the data for the *key* from the cache. If the data is
not yet known the command prefix specified during construction of the cache
object is used to ask for this information.
Whenever the information is/becomes available the *donecmdprefix* will be
run to transfer the result to the caller. This command prefix is invoked
with either 2 or 3 arguments, i.e.
The string __set__, the *key*, and the value.
The string __unset__, and the *key*.
These two possibilities are used to either signal the value for the *key*,
or that the *key* has no value defined for it. The latter is distinct from
the cache not knowing about the *key*.
For a cache object configured to be fully asynchronous (default) the
*donecmdprefix* is always run in an idle-handler, decoupling it from the
request. Otherwise the callback will be invoked synchronously when the *key*
is known to the cache at the time of the invokation.
Another important part of the cache's behaviour, as it is asynchronous it is
possible that multiple __get__ requests are issued for the same *key* before
it can respond. In that case the cache will issue only one data request to
the provider, for the first of these, and suspend the others, and then
notify all of them when the data becomes available.
- <a name='3'></a>*objectName* __set__ *key* *value*
- <a name='4'></a>*objectName* __unset__ *key*
These two methods are provided to allow users of the cache to make keys
known to the cache, as either having a *value*, or as undefined.
It is expected that the data provider (see *commandprefix* of the
constructor) uses them in response to data requests for unknown keys.
Note how this matches the cache's own API towards its caller, calling the
*donecmd* of __get__-requests issued to itself with either "set key value"
or "unset key", versus issuing __get__-requests to its own provider with
itself in the place of the *donecmd*, expecting to be called with either
"set key value" or "unset key".
This also means that these methods invoke the *donecmd* of all
__get__-requests waiting for information about the modified *key*.
- <a name='5'></a>*objectName* __exists__ *key*
This method queries the cache for knowledge about the *key* and returns a
boolean value. The result is __true__ if the key is known, and __false__
otherwise.
- <a name='6'></a>*objectName* __clear__ ?*key*?
This method resets the state of either the specified *key* or of all keys
known to the cache, making it unkown. This forces future __get__-requests to
reload the information from the provider.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *cache* 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.
# <a name='keywords'></a>KEYWORDS
[asynchronous](../../../../index.md#asynchronous),
[cache](../../../../index.md#cache), [callback](../../../../index.md#callback),
[synchronous](../../../../index.md#synchronous)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/clock/iso8601.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
|
[//000000001]: # (clock_iso8601 - Date/Time Utilities)
[//000000002]: # (Generated from file 'iso8601.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (clock_iso8601(n) 0.1 tcllib "Date/Time Utilities")
# NAME
clock_iso8601 - Parsing ISO 8601 dates/times
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require clock::iso8601 ?0.1?
[__::clock::iso8601 parse_date__ *date* *options...*](#1)
[__::clock::iso8601 parse_time__ *time* *options...*](#2)
# <a name='description'></a>DESCRIPTION
This package provides functionality to parse dates and times in ISO 8601 format.
- <a name='1'></a>__::clock::iso8601 parse_date__ *date* *options...*
This command parses an ISO8601 date string in an unknown variant and returns
the given date/time in seconds since epoch.
The acceptable options are __-base__, __-gmt__, __-locale__, and
__-timezone__ of the builtin command __clock scan__.
- <a name='2'></a>__::clock::iso8601 parse_time__ *time* *options...*
This command parses a full ISO8601 timestamp string (date and time) in an
unknown variant and returns the given time in seconds since epoch.
The acceptable options are __-base__, __-gmt__, __-locale__, and
__-timezone__ of the builtin command __clock scan__.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *clock::iso8601* 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.
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/clock/rfc2822.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
[//000000001]: # (clock_rfc2822 - Date/Time Utilities)
[//000000002]: # (Generated from file 'rfc2822.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (clock_rfc2822(n) 0.1 tcllib "Date/Time Utilities")
# NAME
clock_rfc2822 - Parsing ISO 8601 dates/times
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require clock::rfc2822 ?0.1?
[__::clock::rfc2822 parse_date__ *date*](#1)
# <a name='description'></a>DESCRIPTION
This package provides functionality to parse dates in RFC 2822 format.
- <a name='1'></a>__::clock::rfc2822 parse_date__ *date*
This command parses an RFC2822 date string and returns the given date in
seconds since epoch. An error is thrown if the command is unable to parse
the date.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *clock::rfc2822* 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.
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/cmdline/cmdline.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
[//000000001]: # (cmdline - Command line and option processing)
[//000000002]: # (Generated from file 'cmdline.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (cmdline(n) 1.5 tcllib "Command line and option processing")
# NAME
cmdline - Procedures to process command lines and options.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [::argv handling](#section2)
- [API](#section3)
- [Error Codes](#subsection1)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require cmdline ?1.3.3?
[__::cmdline::getopt__ *argvVar* *optstring* *optVar* *valVar*](#1)
[__::cmdline::getKnownOpt__ *argvVar* *optstring* *optVar* *valVar*](#2)
[__::cmdline::getoptions__ *arglistVar* *optlist* ?*usage*?](#3)
[__::cmdline::getKnownOptions__ *arglistVar* *optlist* ?*usage*?](#4)
[__::cmdline::usage__ *optlist* ?*usage*?](#5)
[__::cmdline::getfiles__ *patterns* *quiet*](#6)
[__::cmdline::getArgv0__](#7)
# <a name='description'></a>DESCRIPTION
This package provides commands to parse command lines and options.
# <a name='section2'></a>::argv handling
One of the most common variables this package will be used with is __::argv__,
which holds the command line of the current application. This variable has a
companion __::argc__ which is initialized to the number of elements in
__::argv__ at the beginning of the application.
The commands in this package will *not* modify the __::argc__ companion when
called with __::argv__. Keeping the value consistent, if such is desired or
required, is the responsibility of the caller.
# <a name='section3'></a>API
- <a name='1'></a>__::cmdline::getopt__ *argvVar* *optstring* *optVar* *valVar*
This command works in a fashion like the standard C based __getopt__
function. Given an option string and a pointer to an array of args this
command will process the first argument and return info on how to proceed.
The command returns 1 if an option was found, 0 if no more options were
found, and -1 if an error occurred.
*argvVar* contains the name of the list of arguments to process. If options
are found the list is modified and the processed arguments are removed from
the start of the list.
*optstring* contains a list of command options that the application will
accept. If the option ends in ".arg" the command will use the next argument
as an argument to the option, or extract it from the current argument, if it
is of the form "option=value". Otherwise the option is a boolean that is set
to 1 if present.
*optVar* refers to the variable the command will store the found option into
(without the leading '-' and without the .arg extension).
*valVar* refers to the variable to store either the value for the specified
option into upon success or an error message in the case of failure. The
stored value comes from the command line for .arg options, otherwise the
value is 1.
- <a name='2'></a>__::cmdline::getKnownOpt__ *argvVar* *optstring* *optVar* *valVar*
Like __::cmdline::getopt__, but ignores any unknown options in the input.
- <a name='3'></a>__::cmdline::getoptions__ *arglistVar* *optlist* ?*usage*?
Processes the set of command line options found in the list variable named
by *arglistVar* and fills in defaults for those not specified. This also
generates an error message that lists the allowed flags if an incorrect flag
is specified. The optional *usage*-argument contains a string to include in
front of the generated message. If not present it defaults to "options:".
*optlist* contains a list of lists where each element specifies an option in
the form: *flag* *default* *comment*.
If *flag* ends in ".arg" then the value is taken from the command line.
Otherwise it is a boolean and appears in the result if present on the
command line. If *flag* ends in ".secret", it will not be displayed in the
usage.
The options __-?__, __-help__, and __--__ are implicitly understood. The
first two abort option processing by throwing an error and force the
generation of the usage message, whereas the the last aborts option
processing without an error, leaving all arguments coming after for regular
processing, even if starting with a dash.
The result of the command is a dictionary mapping all options to their
values, be they user-specified or defaults.
- <a name='4'></a>__::cmdline::getKnownOptions__ *arglistVar* *optlist* ?*usage*?
Like __::cmdline::getoptions__, but ignores any unknown options in the
input.
- <a name='5'></a>__::cmdline::usage__ *optlist* ?*usage*?
Generates and returns an error message that lists the allowed flags.
*optlist* is defined as for __::cmdline::getoptions__. The optional
*usage*-argument contains a string to include in front of the generated
message. If not present it defaults to "options:".
- <a name='6'></a>__::cmdline::getfiles__ *patterns* *quiet*
Given a list of file *patterns* this command computes the set of valid
files. On windows, file globbing is performed on each argument. On Unix,
only file existence is tested. If a file argument produces no valid files, a
warning is optionally generated (set *quiet* to true).
This code also uses the full path for each file. If not given it prepends
the current working directory to the filename. This ensures that these files
will never conflict with files in a wrapped zip file. The last sentence
refers to the pro-tools.
- <a name='7'></a>__::cmdline::getArgv0__
This command returns the "sanitized" version of *argv0*. It will strip off
the leading path and removes the extension ".bin". The latter is used by the
pro-apps because they must be wrapped by a shell script.
## <a name='subsection1'></a>Error Codes
Starting with version 1.5 all errors thrown by the package have a proper
__::errorCode__ for use with Tcl's __[try](../try/tcllib_try.md)__ command. This
code always has the word __CMDLINE__ as its first element.
# <a name='section4'></a>EXAMPLES
package require Tcl 8.5
package require try ;# Tcllib.
package require cmdline 1.5 ;# First version with proper error-codes.
# Notes:
# - Tcl 8.6+ has 'try' as a builtin command and therefore does not
# need the 'try' package.
# - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
# This then requires a dedicated test (if) on the contents of
# ::errorCode to separate the CMDLINE USAGE signal from actual errors.
set options {
{a "set the atime only"}
{m "set the mtime only"}
{c "do not create non-existent files"}
{r.arg "" "use time from ref_file"}
{t.arg -1 "use specified time"}
}
set usage ": MyCommandName \[options] filename ...\noptions:"
try {
array set params [::cmdline::getoptions argv $options $usage]
} trap {CMDLINE USAGE} {msg o} {
# Trap the usage signal, print the message, and exit the application.
# Note: Other errors are not caught and passed through to higher levels!
puts $msg
exit 1
}
if { $params(a) } { set set_atime "true" }
set has_t [expr {$params(t) != -1}]
set has_r [expr {[string length $params(r)] > 0}]
if {$has_t && $has_r} {
return -code error "Cannot specify both -r and -t"
} elseif {$has_t} {
...
}
This example, taken (and slightly modified) from the package
__[fileutil](../fileutil/fileutil.md)__, shows how to use cmdline. First, a list
of options is created, then the 'args' list is passed to cmdline for processing.
Subsequently, different options are checked to see if they have been passed to
the script, and what their value is.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *cmdline* 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.
# <a name='keywords'></a>KEYWORDS
[argument processing](../../../../index.md#argument_processing),
[argv](../../../../index.md#argv), [argv0](../../../../index.md#argv0), [cmdline
processing](../../../../index.md#cmdline_processing), [command line
processing](../../../../index.md#command_line_processing)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/comm/comm.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
|
[//000000001]: # (comm - Remote communication)
[//000000002]: # (Generated from file 'comm.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (comm(n) 4.6.3 tcllib "Remote communication")
# NAME
comm - A remote communication facility for Tcl (8.3 and later)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#subsection1)
- [Eval Semantics](#subsection2)
- [Multiple Channels](#subsection3)
- [Channel Configuration](#subsection4)
- [Id/port Assignments](#subsection5)
- [Execution Environment](#subsection6)
- [Remote Interpreters](#subsection7)
- [Closing Connections](#subsection8)
- [Callbacks](#subsection9)
- [Unsupported](#subsection10)
- [Security](#subsection11)
- [Blocking Semantics](#subsection12)
- [Asynchronous Result Generation](#subsection13)
- [Compatibility](#subsection14)
- [TLS Security Considerations](#section2)
- [Author](#section3)
- [License](#section4)
- [Bugs](#section5)
- [On Using Old Versions Of Tcl](#section6)
- [Related Work](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require comm ?4.6.3?
[__::comm::comm send__ ?-async? ?-command *callback*? *id* *cmd* ?*arg arg ...*?](#1)
[__::comm::comm self__](#2)
[__::comm::comm interps__](#3)
[__::comm::comm connect__ ?*id*?](#4)
[__::comm::comm new__ *chan* ?*name value ...*?](#5)
[__::comm::comm channels__](#6)
[__::comm::comm config__](#7)
[__::comm::comm config__ *name*](#8)
[__::comm::comm config__ ?*name* *value* *...*?](#9)
[__::comm::comm shutdown__ *id*](#10)
[__::comm::comm abort__](#11)
[__::comm::comm destroy__](#12)
[__::comm::comm hook__ *event* ?__+__? ?*script*?](#13)
[__::comm::comm remoteid__](#14)
[__::comm::comm_send__](#15)
[__::comm::comm return_async__](#16)
[__$future__ __return__ ?__-code__ *code*? ?*value*?](#17)
[__$future__ __configure__ ?__-command__ ?*cmdprefix*??](#18)
[__$future__ __cget__ __-command__](#19)
# <a name='description'></a>DESCRIPTION
The __comm__ command provides an inter-interpreter remote execution facility
much like Tk's __send(n)__, except that it uses sockets rather than the X server
for the communication path. As a result, __comm__ works with multiple
interpreters, works on Windows and Macintosh systems, and provides control over
the remote execution path.
These commands work just like __[send](../../../../index.md#send)__ and __winfo
interps__ :
::comm::comm send ?-async? id cmd ?arg arg ...?
::comm::comm interps
This is all that is really needed to know in order to use __comm__
## <a name='subsection1'></a>Commands
The package initializes __::comm::comm__ as the default *chan*.
__comm__ names communication endpoints with an *id* unique to each machine.
Before sending commands, the *id* of another interpreter is needed. Unlike Tk's
send, __comm__ doesn't implicitly know the *id*'s of all the interpreters on the
system. The following four methods make up the basic __comm__ interface.
- <a name='1'></a>__::comm::comm send__ ?-async? ?-command *callback*? *id* *cmd* ?*arg arg ...*?
This invokes the given command in the interpreter named by *id*. The command
waits for the result and remote errors are returned unless the __-async__ or
__-command__ option is given. If __-async__ is given, send returns
immediately and there is no further notification of result. If __-command__
is used, *callback* specifies a command to invoke when the result is
received. These options are mutually exclusive. The callback will receive
arguments in the form *-option value*, suitable for __array set__. The
options are: *-id*, the comm id of the interpreter that received the
command; *-serial*, a unique serial for each command sent to a particular
comm interpreter; *-chan*, the comm channel name; *-code*, the result code
of the command; *-errorcode*, the errorcode, if any, of the command;
*-errorinfo*, the errorinfo, if any, of the command; and *-result*, the
return value of the command. If connection is lost before a reply is
received, the callback will be invoked with a connection lost message with
-code equal to -1. When __-command__ is used, the command returns the unique
serial for the command.
- <a name='2'></a>__::comm::comm self__
Returns the *id* for this channel.
- <a name='3'></a>__::comm::comm interps__
Returns a list of all the remote *id*'s to which this channel is connected.
__comm__ learns a new remote *id* when a command is first issued it, or when
a remote *id* first issues a command to this comm channel. __::comm::comm
ids__ is an alias for this method.
- <a name='4'></a>__::comm::comm connect__ ?*id*?
Whereas __::comm::comm send__ will automatically connect to the given *id*,
this forces a connection to a remote *id* without sending a command. After
this, the remote *id* will appear in __::comm::comm interps__.
## <a name='subsection2'></a>Eval Semantics
The evaluation semantics of __::comm::comm send__ are intended to match Tk's
__[send](../../../../index.md#send)__ *exactly*. This means that __comm__
evaluates arguments on the remote side.
If you find that __::comm::comm send__ doesn't work for a particular command,
try the same thing with Tk's send and see if the result is different. If there
is a problem, please report it. For instance, there was had one report that this
command produced an error. Note that the equivalent
__[send](../../../../index.md#send)__ command also produces the same error.
% ::comm::comm send id llength {a b c}
wrong # args: should be "llength list"
% send name llength {a b c}
wrong # args: should be "llength list"
The __eval__ hook (described below) can be used to change from
__[send](../../../../index.md#send)__'s double eval semantics to single eval
semantics.
## <a name='subsection3'></a>Multiple Channels
More than one __comm__ channel (or *listener*) can be created in each Tcl
interpreter. This allows flexibility to create full and restricted channels. For
instance, *[hook](../../../../index.md#hook)* scripts are specific to the
channel they are defined against.
- <a name='5'></a>__::comm::comm new__ *chan* ?*name value ...*?
This creates a new channel and Tcl command with the given channel name. This
new command controls the new channel and takes all the same arguments as
__::comm::comm__. Any remaining arguments are passed to the __config__
method. The fully qualified channel name is returned.
- <a name='6'></a>__::comm::comm channels__
This lists all the channels allocated in this Tcl interpreter.
The default configuration parameters for a new channel are:
"-port 0 -local 1 -listen 0 -silent 0"
The default channel __::comm::comm__ is created with:
"::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
## <a name='subsection4'></a>Channel Configuration
The __config__ method acts similar to __fconfigure__ in that it sets or queries
configuration variables associated with a channel.
- <a name='7'></a>__::comm::comm config__
- <a name='8'></a>__::comm::comm config__ *name*
- <a name='9'></a>__::comm::comm config__ ?*name* *value* *...*?
When given no arguments, __config__ returns a list of all variables and
their value With one argument, __config__ returns the value of just that
argument. With an even number of arguments, the given variables are set to
the given values.
These configuration variables can be changed (descriptions of them are elsewhere
in this manual page):
- __-listen__ ?*0|1*?
- __-local__ ?*0|1*?
- __-port__ ?*port*?
- __-silent__ ?*0|1*?
- __-socketcmd__ ?*commandname*?
- __-interp__ ?*interpreter*?
- __-events__ ?*eventlist*?
These configuration variables are read only:
- __-chan__ *chan*
- __-serial__ *n*
- __-socket__ sock*In*
When __config__ changes the parameters of an existing channel (with the
exception of __-interp__ and __-events__), it closes and reopens the listening
socket. An automatically assigned channel *id* will change when this happens.
Recycling the socket is done by invoking __::comm::comm abort__, which causes
all active sends to terminate.
## <a name='subsection5'></a>Id/port Assignments
__comm__ uses a TCP port for endpoint *id*. The __interps__ (or __ids__) method
merely lists all the TCP ports to which the channel is connected. By default,
each channel's *id* is randomly assigned by the operating system (but usually
starts at a low value around 1024 and increases each time a new socket is
opened). This behavior is accomplished by giving the __-port__ config option a
value of 0. Alternately, a specific TCP port number may be provided for a given
channel. As a special case, comm contains code to allocate a a high-numbered TCP
port (>10000) by using __-port {}__. Note that a channel won't be created and
initialized unless the specific port can be allocated.
As a special case, if the channel is configured with __-listen 0__, then it will
not create a listening socket and will use an id of __0__ for itself. Such a
channel is only good for outgoing connections (although once a connection is
established, it can carry send traffic in both directions). As another special
case, if the channel is configured with __-silent 0__, then the listening side
will ignore connection attempts where the protocol negotiation phase failed,
instead of throwing an error.
## <a name='subsection6'></a>Execution Environment
A communication channel in its default configuration will use the current
interpreter for the execution of all received scripts, and of the event scripts
associated with the various hooks.
This insecure setup can be changed by the user via the two options __-interp__,
and __-events__.
When __-interp__ is set all received scripts are executed in the slave
interpreter specified as the value of the option. This interpreter is expected
to exist before configuration. I.e. it is the responsibility of the user to
create it. However afterward the communication channel takes ownership of this
interpreter, and will destroy it when the communication channel is destroyed.
Note that reconfiguration of the communication channel to either a different
interpreter or the empty string will release the ownership *without* destroying
the previously configured interpreter. The empty string has a special meaning,
it restores the default behaviour of executing received scripts in the current
interpreter.
*Also of note* is that replies and callbacks (a special form of reply) are *not*
considered as received scripts. They are trusted, part of the internal machinery
of comm, and therefore always executed in the current interpreter.
Even if an interpreter has been configured as the execution environment for
received scripts the event scripts associated with the various hooks will by
default still be executed in the current interpreter. To change this use the
option __-events__ to declare a list of the events whose scripts should be
executed in the declared interpreter as well. The contents of this option are
ignored if the communication channel is configured to execute received scripts
in the current interpreter.
## <a name='subsection7'></a>Remote Interpreters
By default, each channel is restricted to accepting connections from the local
system. This can be overridden by using the __-local 0__ configuration option
For such channels, the *id* parameter takes the form *{ id host }*.
*WARNING*: The *host* must always be specified in the same form (e.g., as either
a fully qualified domain name, plain hostname or an IP address).
## <a name='subsection8'></a>Closing Connections
These methods give control over closing connections:
- <a name='10'></a>__::comm::comm shutdown__ *id*
This closes the connection to *id*, aborting all outstanding commands in
progress. Note that nothing prevents the connection from being immediately
reopened by another incoming or outgoing command.
- <a name='11'></a>__::comm::comm abort__
This invokes shutdown on all open connections in this comm channel.
- <a name='12'></a>__::comm::comm destroy__
This aborts all connections and then destroys the this comm channel itself,
including closing the listening socket. Special code allows the default
__::comm::comm__ channel to be closed such that the __::comm::comm__ command
it is not destroyed. Doing so closes the listening socket, preventing both
incoming and outgoing commands on the channel. This sequence reinitializes
the default channel:
"::comm::comm destroy; ::comm::comm new ::comm::comm"
When a remote connection is lost (because the remote exited or called
__shutdown__), __comm__ can invoke an application callback. This can be used to
cleanup or restart an ancillary process, for instance. See the *lost* callback
below.
## <a name='subsection9'></a>Callbacks
This is a mechanism for setting hooks for particular events:
- <a name='13'></a>__::comm::comm hook__ *event* ?__+__? ?*script*?
This uses a syntax similar to Tk's __[bind](../../../../index.md#bind)__
command. Prefixing *script* with a __+__ causes the new script to be
appended. Without this, a new *script* replaces any existing script. When
invoked without a script, no change is made. In all cases, the new hook
script is returned by the command.
When an *event* occurs, the *script* associated with it is evaluated with
the listed variables in scope and available. The return code (*not* the
return value) of the script is commonly used decide how to further process
after the hook.
Common variables include:
* __chan__
the name of the comm channel (and command)
* __id__
the id of the remote in question
* __fid__
the file id for the socket of the connection
These are the defined *events*:
- __connecting__
Variables: __chan__, __id__
This hook is invoked before making a connection to the remote named in *id*.
An error return (via __[error](../../../../index.md#error)__) will abort the
connection attempt with the error. Example:
% ::comm::comm hook connecting {
if {[string match {*[02468]} $id]} {
error "Can't connect to even ids"
}
}
% ::comm::comm send 10000 puts ok
Connect to remote failed: Can't connect to even ids
%
- __connected__
Variables: __chan__, __fid__, __id__, __host__, and __port__.
This hook is invoked immediately after making a remote connection to *id*,
allowing arbitrary authentication over the socket named by *fid*. An error
return (via __[error](../../../../index.md#error)__ ) will close the
connection with the error. *host* and *port* are merely extracted from the
*id*; changing any of these will have no effect on the connection, however.
It is also possible to substitute and replace *fid*.
- __incoming__
Variables: __chan__, __fid__, __addr__, and __remport__.
Hook invoked when receiving an incoming connection, allowing arbitrary
authentication over socket named by *fid*. An error return (via
__[error](../../../../index.md#error)__) will close the connection with the
error. Note that the peer is named by *remport* and *addr* but that the
remote *id* is still unknown. Example:
::comm::comm hook incoming {
if {[string match 127.0.0.1 $addr]} {
error "I don't talk to myself"
}
}
- __eval__
Variables: __chan__, __id__, __cmd__, and __buffer__.
This hook is invoked after collecting a complete script from a remote but
*before* evaluating it. This allows complete control over the processing of
incoming commands. *cmd* contains either __send__ or __async__. *buffer*
holds the script to evaluate. At the time the hook is called, *$chan
remoteid* is identical in value to *id*.
By changing *buffer*, the hook can change the script to be evaluated. The
hook can short circuit evaluation and cause a value to be immediately
returned by using __[return](../../../../index.md#return)__ *result* (or,
from within a procedure, __return -code return__ *result*). An error return
(via __[error](../../../../index.md#error)__) will return an error result,
as is if the script caused the error. Any other return will evaluate the
script in *buffer* as normal. For compatibility with 3.2, __break__ and
__return -code break__ *result* is supported, acting similarly to __return
{}__ and __return -code return__ *result*.
Examples:
augmenting a command
% ::comm::comm send [::comm::comm self] pid
5013
% ::comm::comm hook eval {puts "going to execute $buffer"}
% ::comm::comm send [::comm::comm self] pid
going to execute pid
5013
short circuiting a command
% ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
% ::comm::comm send [::comm::comm self] pid
would have executed pid
0
Replacing double eval semantics
% ::comm::comm send [::comm::comm self] llength {a b c}
wrong # args: should be "llength list"
% ::comm::comm hook eval {return [uplevel #0 $buffer]}
return [uplevel #0 $buffer]
% ::comm::comm send [::comm::comm self] llength {a b c}
3
Using a slave interpreter
% interp create foo
% ::comm::comm hook eval {return [foo eval $buffer]}
% ::comm::comm send [::comm::comm self] set myvar 123
123
% set myvar
can't read "myvar": no such variable
% foo eval set myvar
123
Using a slave interpreter (double eval)
% ::comm::comm hook eval {return [eval foo eval $buffer]}
Subverting the script to execute
% ::comm::comm hook eval {
switch -- $buffer {
a {return A-OK}
b {return B-OK}
default {error "$buffer is a no-no"}
}
}
% ::comm::comm send [::comm::comm self] pid
pid is a no-no
% ::comm::comm send [::comm::comm self] a
A-OK
- __reply__
Variables: __chan__, __id__, __buffer__, __ret__, and __return()__.
This hook is invoked after collecting a complete reply script from a remote
but *before* evaluating it. This allows complete control over the processing
of replies to sent commands. The reply *buffer* is in one of the following
forms
return result
return -code code result
return -code code -errorinfo info -errorcode ecode msg
For safety reasons, this is decomposed. The return result is in *ret*, and
the return switches are in the return array:
*return(-code)*
*return(-errorinfo)*
*return(-errorcode)*
Any of these may be the empty string. Modifying these four variables can
change the return value, whereas modifying *buffer* has no effect.
- __callback__
Variables: __chan__, __id__, __buffer__, __ret__, and __return()__.
Similar to *reply*, but used for callbacks.
- __lost__
Variables: __chan__, __id__, and __reason__.
This hook is invoked when the connection to __id__ is lost. Return value (or
thrown error) is ignored. *reason* is an explanatory string indicating why
the connection was lost. Example:
::comm::comm hook lost {
global myvar
if {$myvar(id) == $id} {
myfunc
return
}
}
## <a name='subsection10'></a>Unsupported
These interfaces may change or go away in subsequence releases.
- <a name='14'></a>__::comm::comm remoteid__
Returns the *id* of the sender of the last remote command executed on this
channel. If used by a proc being invoked remotely, it must be called before
any events are processed. Otherwise, another command may get invoked and
change the value.
- <a name='15'></a>__::comm::comm_send__
Invoking this procedure will substitute the Tk
__[send](../../../../index.md#send)__ and __winfo interps__ commands with
these equivalents that use __::comm::comm__.
proc send {args} {
eval ::comm::comm send $args
}
rename winfo tk_winfo
proc winfo {cmd args} {
if {![string match in* $cmd]} {
return [eval [list tk_winfo $cmd] $args]
}
return [::comm::comm interps]
}
## <a name='subsection11'></a>Security
Starting with version 4.6 of the package an option __-socketcmd__ is supported,
allowing the user of a comm channel to specify which command to use when opening
a socket. Anything which is API-compatible with the builtin __::socket__ (the
default) can be used.
The envisioned main use is the specification of the __tls::socket__ command, see
package __[tls](../../../../index.md#tls)__, to secure the communication.
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured comm channel
::comm::comm new SECURE -socketcmd tls::socket -listen 1
...
The sections [Execution Environment](#subsection6) and [Callbacks](#subsection9)
are also relevant to the security of the system, providing means to restrict the
execution to a specific environment, perform additional authentication, and the
like.
## <a name='subsection12'></a>Blocking Semantics
There is one outstanding difference between __comm__ and
__[send](../../../../index.md#send)__. When blocking in a synchronous remote
command, __[send](../../../../index.md#send)__ uses an internal C hook
(Tk_RestrictEvents) to the event loop to look ahead for send-related events and
only process those without processing any other events. In contrast, __comm__
uses the __[vwait](../../../../index.md#vwait)__ command as a semaphore to
indicate the return message has arrived. The difference is that a synchronous
__[send](../../../../index.md#send)__ will block the application and prevent all
events (including window related ones) from being processed, while a synchronous
__::comm::comm send__ will block the application but still allow other events to
get processed. In particular, __after idle__ handlers will fire immediately when
comm blocks.
What can be done about this? First, note that this behavior will come from any
code using __[vwait](../../../../index.md#vwait)__ to block and wait for an
event to occur. At the cost of multiple channel support, __comm__ could be
changed to do blocking I/O on the socket, giving send-like blocking semantics.
However, multiple channel support is a very useful feature of comm that it is
deemed too important to lose. The remaining approaches involve a new loadable
module written in C (which is somewhat against the philosophy of __comm__) One
way would be to create a modified version of the
__[vwait](../../../../index.md#vwait)__ command that allow the event flags
passed to Tcl_DoOneEvent to be specified. For __comm__, just the TCL_FILE_EVENTS
would be processed. Another way would be to implement a mechanism like
Tk_RestrictEvents, but apply it to the Tcl event loop (since __comm__ doesn't
require Tk). One of these approaches will be available in a future __comm__
release as an optional component.
## <a name='subsection13'></a>Asynchronous Result Generation
By default the result returned by a remotely invoked command is the result sent
back to the invoker. This means that the result is generated synchronously, and
the server handling the call is blocked for the duration of the command.
While this is tolerable as long as only short-running commands are invoked on
the server long-running commands, like database queries make this a problem. One
command can prevent the processing requests of all other clients for an
arbitrary period of time.
Before version 4.5 of comm the only solution was to rewrite the server command
to use the Tcl builtin command __[vwait](../../../../index.md#vwait)__, or one
of its relatives like __tkwait__, to open a new event loop which processes
requests while the long-running operation is executed. This however has its own
perils, as this makes it possible to both overflow the Tcl stack with a large
number of event loop, and to have a newer requests block the return of older
ones, as the eventloop have to be unwound in the order of their creation.
The proper solution is to have the invoked command indicate to __comm__ that it
cannot or will not deliver an immediate, synchronous result, but will do so
later. At that point the framework can put sending the actual result on hold and
continue processing requests using the main event loop. No blocking, no nesting
of event loops. At some future date the long running operation delivers the
result to comm, via the future object, which is then forwarded to the invoker as
usual.
The necessary support for this solution has been added to comm since version
4.5, in the form of the new method __return_async__.
- <a name='16'></a>__::comm::comm return_async__
This command is used by a remotely invoked script to notify the comm channel
which invoked it that the result to send back to the invoker is not
generated synchronously. If this command is not called the default/standard
behaviour of comm is to send the synchronously generated result of the
script itself to the invoker.
The result of __return_async__ is an object. This object, called a *future*
is where the result of the script has to be delivered to when it becomes
ready. When that happens it will take all the necessary actions to deliver
the result to the invoker of the script, and then destroy itself. Should
comm have lost the connection to the invoker while the result is being
computed the future will not try to deliver the result it got, but just
destroy itself. The future can be configured with a command to call when the
invoker is lost. This enables the user to implement an early abort of the
long-running operation, should this be supported by it.
An example:
# Procedure invoked by remote clients to run database operations.
proc select {sql} {
# Signal the async generation of the result
set future [::comm::comm return_async]
# Generate an async db operation and tell it where to deliver the result.
set query [db query -command [list $future return] $sql]
# Tell the database system which query to cancel if the connection
# goes away while it is running.
$future configure -command [list db cancel $query]
# Note: The above will work without problem only if the async
# query will nover run its completion callback immediately, but
# only from the eventloop. Because otherwise the future we wish to
# configure may already be gone. If that is possible use 'catch'
# to prevent the error from propagating.
return
}
The API of a future object is:
* <a name='17'></a>__$future__ __return__ ?__-code__ *code*? ?*value*?
Use this method to tell the future that long-running operation has
completed. Arguments are an optional return value (defaults to the empty
string), and the Tcl return code (defaults to OK).
The future will deliver this information to invoker, if the connection
was not lost in the meantime, and then destroy itself. If the connection
was lost it will do nothing but destroy itself.
* <a name='18'></a>__$future__ __configure__ ?__-command__ ?*cmdprefix*??
* <a name='19'></a>__$future__ __cget__ __-command__
These methods allow the user to retrieve and set a command to be called
if the connection the future belongs to has been lost.
## <a name='subsection14'></a>Compatibility
__comm__ exports itself as a package. The package version number is in the form
*major . minor*, where the major version will only change when a non-compatible
change happens to the API or protocol. Minor bug fixes and changes will only
affect the minor version. To load __comm__ this command is usually used:
package require comm 3
Note that requiring no version (or a specific version) can also be done.
The revision history of __comm__ includes these releases:
- 4.6.3
Fixed ticket [ced0d60fc9]. Added proper detection of eof on a socket,
properly closing it.
- 4.6.2
Fixed bugs 2972571 and 3066872, the first a misdetection of quoted brace
after double backslash, the other a blocking gets making for an obvious
(hinsight) DoS attack on comm channels.
- 4.6.1
Changed the implementation of __comm::commCollect__ to emulate lindex's
pre-Tcl 8 behaviour, i.e. it was given the ability to parse out the first
word of a list, even if the whole buffer is not a well-formed list. Without
this change the first word could only be extracted if the whole buffer was a
well-formed list (ever since Tcl 8), and in a ver-high-load situation, i.e.
a server sending lots and/or large commands very fast, this may never
happen, eventually crashing the receiver when it runs out of memory. With
the change the receiver is always able to process the first word when it
becomes well-formed, regardless of the structure of the remainder of the
buffer.
- 4.6
Added the option __-socketcmd__ enabling users to override how a socket is
opened. The envisioned main use is the specification of the __tls::socket__
command, see package __[tls](../../../../index.md#tls)__, to secure the
communication.
- 4.5.7
Changed handling of ports already in use to provide a proper error message.
- 4.5.6
Bugfix in the replacement for __[vwait](../../../../index.md#vwait)__, made
robust against of variable names containing spaces.
- 4.5.5
Bugfix in the handling of hooks, typo in variable name.
- 4.5.4
Bugfix in the handling of the result received by the __send__ method.
Replaced an *after idle unset result* with an immediate __unset__, with the
information saved to a local variable.
The __after idle__ can spill into a forked child process if there is no
event loop between its setup and the fork. This may bork the child if the
next event loop is the __[vwait](../../../../index.md#vwait)__ of __comm__'s
__send__ a few lines above the __after idle__, and the child used the same
serial number for its next request. In that case the parent's __after idle
unset__ will delete the very array element the child is waiting for,
unlocking the __[vwait](../../../../index.md#vwait)__, causing it to access
a now missing array element, instead of the expected result.
- 4.5.3
Bugfixes in the wrappers for the builtin
__[update](../../../../index.md#update)__ and
__[vwait](../../../../index.md#vwait)__ commands.
- 4.5.2
Bugfix in the wrapper for the builtin
__[update](../../../../index.md#update)__ command.
- 4.5.1
Bugfixes in the handling of -interp for regular scripts. The handling of the
buffer was wrong for scripts which are a single statement as list. Fixed
missing argument to new command __commSendReply__, introduced by version
4.5. Affected debugging.
- 4.5
New server-side feature. The command invoked on the server can now switch
comm from the standard synchronous return of its result to an asynchronous
(defered) return. Due to the use of snit to implement the *future* objects
used by this feature from this version on comm requires at least Tcl 8.3 to
run. Please read the section [Asynchronous Result Generation](#subsection13)
for more details.
- 4.4.1
Bugfix in the execution of hooks.
- 4.4
Bugfixes in the handling of -interp for regular and hook scripts. Bugfixes
in channel cleanup.
- 4.3.1
Introduced -interp and -events to enable easy use of a slave interp for
execution of received scripts, and of event scripts.
- 4.3
Bugfixes, and introduces -silent to allow the user to force the
server/listening side to silently ignore connection attempts where the
protocol negotiation failed.
- 4.2
Bugfixes, and most important, switched to utf-8 as default encoding for full
i18n without any problems.
- 4.1
Rewrite of internal code to remove old pseudo-object model. Addition of send
-command asynchronous callback option.
- 4.0
Per request by John LoVerso. Improved handling of error for async invoked
commands.
- 3.7
Moved into tcllib and placed in a proper namespace.
- 3.6
A bug in the looking up of the remoteid for a executed command could be
triggered when the connection was closed while several asynchronous sends
were queued to be executed.
- 3.5
Internal change to how reply messages from a
__[send](../../../../index.md#send)__ are handled. Reply messages are now
decoded into the *value* to pass to
__[return](../../../../index.md#return)__; a new return statement is then
cons'd up to with this value. Previously, the return code was passed in from
the remote as a command to evaluate. Since the wire protocol has not
changed, this is still the case. Instead, the reply handling code decodes
the __reply__ message.
- 3.4
Added more source commentary, as well as documenting config variables in
this man page. Fixed bug were loss of connection would give error about a
variable named __pending__ rather than the message about the lost
connection. __comm ids__ is now an alias for __comm interps__ (previously,
it an alias for __comm chans__). Since the method invocation change of 3.0,
break and other exceptional conditions were not being returned correctly
from __comm send__. This has been fixed by removing the extra level of
indirection into the internal procedure __commSend__. Also added propagation
of the *errorCode* variable. This means that these commands return exactly
as they would with __[send](../../../../index.md#send)__:
comm send id break
catch {comm send id break}
comm send id expr 1 / 0
Added a new hook for reply messages. Reworked method invocation to avoid the
use of comm:* procedures; this also cut the invocation time down by 40%.
Documented __comm config__ (as this manual page still listed the defunct
__comm init__!)
- 3.3
Some minor bugs were corrected and the documentation was cleaned up. Added
some examples for hooks. The return semantics of the __eval__ hook were
changed.
- 3.2
A new wire protocol, version 3, was added. This is backwards compatible with
version 2 but adds an exchange of supported protocol versions to allow
protocol negotiation in the future. Several bugs with the hook
implementation were fixed. A new section of the man page on blocking
semantics was added.
- 3.1
All the documented hooks were implemented. __commLostHook__ was removed. A
bug in __comm new__ was fixed.
- 3.0
This is a new version of __comm__ with several major changes. There is a new
way of creating the methods available under the __comm__ command. The __comm
init__ method has been retired and is replaced by __comm configure__ which
allows access to many of the well-defined internal variables. This also
generalizes the options available to __comm new__. Finally, there is now a
protocol version exchanged when a connection is established. This will allow
for future on-wire protocol changes. Currently, the protocol version is set
to 2.
- 2.3
__comm ids__ was renamed to __comm channels__. General support for __comm
hook__ was fully implemented, but only the *lost* hook exists, and it was
changed to follow the general hook API. __commLostHook__ was unsupported
(replaced by __comm hook lost__) and __commLost__ was removed.
- 2.2
The *died* hook was renamed *lost*, to be accessed by __commLostHook__ and
an early implementation of __comm lost hook__. As such, __commDied__ is now
__commLost__.
- 2.1
Unsupported method __comm remoteid__ was added.
- 2.0
__comm__ has been rewritten from scratch (but is fully compatible with Comm
1.0, without the requirement to use obTcl).
# <a name='section2'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section3'></a>Author
John LoVerso, [email protected]
*http://www.opengroup.org/~loverso/tcl-tk/#comm*
# <a name='section4'></a>License
Please see the file *comm.LICENSE* that accompanied this source, or
[http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html](http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html).
This license for __comm__, new as of version 3.2, allows it to be used for free,
without any licensing fee or royalty.
# <a name='section5'></a>Bugs
- If there is a failure initializing a channel created with __::comm::comm
new__, then the channel should be destroyed. Currently, it is left in an
inconsistent state.
- There should be a way to force a channel to quiesce when changing the
configuration.
The following items can be implemented with the existing hooks and are listed
here as a reminder to provide a sample hook in a future version.
- Allow easier use of a slave interp for actual command execution (especially
when operating in "not local" mode).
- Add host list (xhost-like) or "magic cookie" (xauth-like) authentication to
initial handshake.
The following are outstanding todo items.
- Add an interp discovery and name->port mapping. This is likely to be in a
separate, optional nameserver. (See also the related work, below.)
- Fix the *{id host}* form so as not to be dependent upon canonical hostnames.
This requires fixes to Tcl to resolve hostnames!
This man page is bigger than the source file.
# <a name='section6'></a>On Using Old Versions Of Tcl
Tcl7.5 under Windows contains a bug that causes the interpreter to hang when EOF
is reached on non-blocking sockets. This can be triggered with a command such as
this:
"comm send $other exit"
Always make sure the channel is quiescent before closing/exiting or use at least
Tcl7.6 under Windows.
Tcl7.6 on the Mac contains several bugs. It is recommended you use at least
Tcl7.6p2.
Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended you
use Tcl8.0p1 (or Tcl7.6p2).
# <a name='section7'></a>Related Work
Tcl-DP provides an RPC-based remote execution interface, but is a compiled Tcl
extension. See
[http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html](http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html).
Michael Doyle <[email protected]> has code that implements the Tcl-DP RPC
interface using standard Tcl sockets, much like __comm__. The DpTcl package is
available at
[http://chiselapp.com/user/gwlester/repository/DpTcl](http://chiselapp.com/user/gwlester/repository/DpTcl).
Andreas Kupries <[email protected]> uses __comm__ and has
built a simple nameserver as part of his Pool library. See
[http://www.purl.org/net/akupries/soft/pool/index.htm](http://www.purl.org/net/akupries/soft/pool/index.htm).
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *comm* 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.
# <a name='see-also'></a>SEE ALSO
send(n)
# <a name='keywords'></a>KEYWORDS
[comm](../../../../index.md#comm),
[communication](../../../../index.md#communication),
[ipc](../../../../index.md#ipc), [message](../../../../index.md#message),
[remote communication](../../../../index.md#remote_communication), [remote
execution](../../../../index.md#remote_execution),
[rpc](../../../../index.md#rpc), [secure](../../../../index.md#secure),
[send](../../../../index.md#send), [socket](../../../../index.md#socket),
[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 1995-1998 The Open Group. All Rights Reserved.
Copyright © 2003-2004 ActiveState Corporation.
Copyright © 2006-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/comm/comm_wire.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
[//000000001]: # (comm_wire - Remote communication)
[//000000002]: # (Generated from file 'comm_wire.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (comm_wire(n) 3 tcllib "Remote communication")
# NAME
comm_wire - The comm wire protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Wire Protocol Version 3](#section2)
- [Basic Layer](#subsection1)
- [Basic Message Layer](#subsection2)
- [Negotiation Messages - Initial Handshake](#subsection3)
- [Script/Command Messages](#subsection4)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require comm
# <a name='description'></a>DESCRIPTION
The __[comm](comm.md)__ command provides an inter-interpreter remote execution
facility much like Tk's __send(n)__, except that it uses sockets rather than the
X server for the communication path. As a result, __[comm](comm.md)__ works with
multiple interpreters, works on Windows and Macintosh systems, and provides
control over the remote execution path.
This document contains a specification of the various versions of the wire
protocol used by comm internally for the communication between its endpoints. It
has no relevance to users of __[comm](comm.md)__, only to developers who wish to
modify the package, write a compatible facility in a different language, or some
other facility based on the same protocol.
# <a name='section2'></a>Wire Protocol Version 3
## <a name='subsection1'></a>Basic Layer
The basic encoding for *all* data is UTF-8. Because of this binary data,
including the NULL character, can be sent over the wire as is, without the need
for armoring it.
## <a name='subsection2'></a>Basic Message Layer
On top of the [Basic Layer](#subsection1) we have a *message oriented* exchange
of data. The totality of all characters written to the channel is a Tcl list,
with each element a separate *[message](../../../../index.md#message)*, each
itself a list. The messages in the overall list are separated by EOL. Note that
EOL characters can occur within the list as well. They can be distinguished from
the message-separating EOL by the fact that the data from the beginning up to
their location is not a valid Tcl list.
EOL is signaled through the linefeed character, i.e __LF__, or, hex __0x0a__.
This is following the unix convention for line-endings.
As a list each message is composed of *words*. Their meaning depends on when the
message was sent in the overall exchange. This is described in the upcoming
sections.
## <a name='subsection3'></a>Negotiation Messages - Initial Handshake
The command protocol is defined like this:
- The first message send by a client to a server, when opening the connection,
contains two words. The first word is a list as well, and contains the
versions of the wire protocol the client is willing to accept, with the most
preferred version first. The second word is the TCP port the client is
listening on for connections to itself. The value __0__ is used here to
signal that the client will not listen for connections, i.e. that it is
purely for sending commands, and not receiving them.
- The first message sent by the server to the client, in response to the
message above contains only one word. This word is a list, containing the
string __vers__ as its first element, and the version of the wire protocol
the server has selected from the offered versions as the second.
## <a name='subsection4'></a>Script/Command Messages
All messages coming after the [initial handshake](#subsection3) consist of three
words. These are an instruction, a transaction id, and the payload. The valid
instructions are shown below. The transaction ids are used by the client to
match any incoming replies to the command messages it sent. This means that a
server has to copy the transaction id from a command message to the reply it
sends for that message.
- __send__
- __async__
- __command__
The payload is the Tcl script to execute on the server. It is actually a
list containing the script fragments. These fragment are __concat__enated
together by the server to form the full script to execute on the server
side. This emulates the Tcl "eval" semantics. In most cases it is best to
have only one word in the list, a list containing the exact command.
Examples:
(a) {send 1 {{array get tcl_platform}}}
(b) {send 1 {array get tcl_platform}}
(c) {send 1 {array {get tcl_platform}}}
are all valid representations of the same command. They are
generated via
(a') send {array get tcl_platform}
(b') send array get tcl_platform
(c') send array {get tcl_platform}
respectively
Note that (a), generated by (a'), is the usual form, if only single commands
are sent by the client. For example constructed using
__[list](../../../../index.md#list)__, if the command contains variable
arguments. Like
send [list array get $the_variable]
These three instructions all invoke the script on the server side. Their
difference is in the treatment of result values, and thus determines if a
reply is expected.
* __send__
A reply is expected. The sender is waiting for the result.
* __async__
No reply is expected, the sender has no interest in the result and is
not waiting for any.
* __command__
A reply is expected, but the sender is not waiting for it. It has
arranged to get a process-internal notification when the result arrives.
- __reply__
Like the previous three command, however the tcl script in the payload is
highly restricted. It has to be a syntactically valid Tcl
__[return](../../../../index.md#return)__ command. This contains result
code, value, error code, and error info.
Examples:
{reply 1 {return -code 0 {}}}
{reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *comm* 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.
# <a name='see-also'></a>SEE ALSO
[comm](comm.md)
# <a name='keywords'></a>KEYWORDS
[comm](../../../../index.md#comm),
[communication](../../../../index.md#communication),
[ipc](../../../../index.md#ipc), [message](../../../../index.md#message),
[remote communication](../../../../index.md#remote_communication), [remote
execution](../../../../index.md#remote_execution),
[rpc](../../../../index.md#rpc), [socket](../../../../index.md#socket)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Docs. Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/control/control.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
[//000000001]: # (control - Tcl Control Flow Commands)
[//000000002]: # (Generated from file 'control.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (control(n) 0.1.3 tcllib "Tcl Control Flow Commands")
# NAME
control - Procedures for control flow structures.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [LIMITATIONS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require control ?0.1.3?
[__control::control__ *command* *option* ?*arg arg ...*?](#1)
[__control::assert__ *expr* ?*arg arg ...*?](#2)
[__control::do__ *body* ?*option test*?](#3)
[__control::no-op__ ?*arg arg ...*?](#4)
# <a name='description'></a>DESCRIPTION
The __control__ package provides a variety of commands that provide additional
flow of control structures beyond the built-in ones provided by Tcl. These are
commands that in many programming languages might be considered *keywords*, or a
part of the language itself. In Tcl, control flow structures are just commands
like everything else.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__control::control__ *command* *option* ?*arg arg ...*?
The __control__ command is used as a configuration command for customizing
the other public commands of the control package. The *command* argument
names the command to be customized. The set of valid *option* and subsequent
arguments are determined by the command being customized, and are documented
with the command.
- <a name='2'></a>__control::assert__ *expr* ?*arg arg ...*?
When disabled, the __[assert](../../../../index.md#assert)__ command behaves
exactly like the __[no-op](../../../../index.md#no_op)__ command.
When enabled, the __[assert](../../../../index.md#assert)__ command
evaluates *expr* as an expression (in the same way that __expr__ evaluates
its argument). If evaluation reveals that *expr* is not a valid boolean
expression (according to [__string is boolean -strict__]), an error is
raised. If *expr* evaluates to a true boolean value (as recognized by
__if__), then __[assert](../../../../index.md#assert)__ returns an empty
string. Otherwise, the remaining arguments to
__[assert](../../../../index.md#assert)__ are used to construct a message
string. If there are no arguments, the message string is "assertion failed:
$expr". If there are arguments, they are joined by
__[join](../../../../index.md#join)__ to form the message string. The
message string is then appended as an argument to a callback command, and
the completed callback command is evaluated in the global namespace.
The __[assert](../../../../index.md#assert)__ command can be customized by
the __control__ command in two ways:
[__control::control assert enabled__ ?*boolean*?] queries or sets whether
__control::assert__ is enabled. When called without a *boolean* argument, a
boolean value is returned indicating whether the __control::assert__ command
is enabled. When called with a valid boolean value as the *boolean*
argument, the __control::assert__ command is enabled or disabled to match
the argument, and an empty string is returned.
[__control::control assert callback__ ?*command*?] queries or sets the
callback command that will be called by an enabled
__[assert](../../../../index.md#assert)__ on assertion failure. When called
without a *command* argument, the current callback command is returned. When
called with a *command* argument, that argument becomes the new assertion
failure callback command. Note that an assertion failure callback command is
always defined, even when __[assert](../../../../index.md#assert)__ is
disabled. The default callback command is [__return -code error__].
Note that __control::assert__ has been written so that in combination with
[__namespace import__], it is possible to use enabled
__[assert](../../../../index.md#assert)__ commands in some namespaces and
disabled __[assert](../../../../index.md#assert)__ commands in other
namespaces at the same time. This capability is useful so that debugging
efforts can be independently controlled module by module.
% package require control
% control::control assert enabled 1
% namespace eval one namespace import ::control::assert
% control::control assert enabled 0
% namespace eval two namespace import ::control::assert
% one::assert {1 == 0}
assertion failed: 1 == 0
% two::assert {1 == 0}
- <a name='3'></a>__control::do__ *body* ?*option test*?
The __[do](../../../../index.md#do)__ command evaluates the script *body*
repeatedly *until* the expression *test* becomes true or as long as
(*while*) *test* is true, depending on the value of *option* being __until__
or __while__. If *option* and *test* are omitted the body is evaluated
exactly once. After normal completion, __[do](../../../../index.md#do)__
returns an empty string. Exceptional return codes (__break__, __continue__,
__[error](../../../../index.md#error)__, etc.) during the evaluation of
*body* are handled in the same way the __while__ command handles them,
except as noted in [LIMITATIONS](#section3), below.
- <a name='4'></a>__control::no-op__ ?*arg arg ...*?
The __[no-op](../../../../index.md#no_op)__ command takes any number of
arguments and does nothing. It returns an empty string.
# <a name='section3'></a>LIMITATIONS
Several of the commands provided by the __control__ package accept arguments
that are scripts to be evaluated. Due to fundamental limitations of Tcl's
__catch__ and __[return](../../../../index.md#return)__ commands, it is not
possible for these commands to properly evaluate the command [__return -code
$code__] within one of those script arguments for any value of *$code* other
than *ok*. In this way, the commands of the __control__ package are limited as
compared to Tcl's built-in control flow commands (such as __if__, __while__,
etc.) and those control flow commands that can be provided by packages coded in
C. An example of this difference:
% package require control
% proc a {} {while 1 {return -code error a}}
% proc b {} {control::do {return -code error b} while 1}
% catch a
1
% catch b
0
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *control* 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.
# <a name='see-also'></a>SEE ALSO
break, continue, expr, if, [join](../../../../index.md#join), namespace,
[return](../../../../index.md#return), [string](../../../../index.md#string),
while
# <a name='keywords'></a>KEYWORDS
[assert](../../../../index.md#assert), [control](../../../../index.md#control),
[do](../../../../index.md#do), [flow](../../../../index.md#flow),
[no-op](../../../../index.md#no_op), [structure](../../../../index.md#structure)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/coroutine/coro_auto.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (coroutine::auto - Coroutine utilities)
[//000000002]: # (Generated from file 'coro_auto.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (coroutine::auto(n) 1.1.3 tcllib "Coroutine utilities")
# NAME
coroutine::auto - Automatic event and IO coroutine awareness
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require coroutine::auto 1.1.3
package require coroutine 1.1
# <a name='description'></a>DESCRIPTION
The __coroutine::auto__ package provides no commands or other directly visible
functionality. Built on top of the package __[coroutine](tcllib_coroutine.md)__,
it intercepts various builtin commands of the Tcl core to make any code using
them coroutine-oblivious, i.e. able to run inside and outside of a coroutine
without changes.
The commands so affected by this package are
- __[after](../../../../index.md#after)__
- __[exit](../../../../index.md#exit)__
- __[gets](../../../../index.md#gets)__
- __[global](../../../../index.md#global)__
- __[read](../../../../index.md#read)__
- __[update](../../../../index.md#update)__
- __[vwait](../../../../index.md#vwait)__
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *coroutine* 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.
# <a name='keywords'></a>KEYWORDS
[after](../../../../index.md#after), [channel](../../../../index.md#channel),
[coroutine](../../../../index.md#coroutine),
[events](../../../../index.md#events), [exit](../../../../index.md#exit),
[gets](../../../../index.md#gets), [global](../../../../index.md#global), [green
threads](../../../../index.md#green_threads), [read](../../../../index.md#read),
[threads](../../../../index.md#threads), [update](../../../../index.md#update),
[vwait](../../../../index.md#vwait)
# <a name='category'></a>CATEGORY
Coroutine
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010-2014 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/coroutine/tcllib_coroutine.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
[//000000001]: # (coroutine - Coroutine utilities)
[//000000002]: # (Generated from file 'tcllib_coroutine.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (coroutine(n) 1.2 tcllib "Coroutine utilities")
# NAME
coroutine - Coroutine based event and IO handling
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require coroutine 1.2
[__coroutine::util after__ *delay*](#1)
[__coroutine::util await__ *varname*...](#2)
[__coroutine::util create__ *arg*...](#3)
[__coroutine::util exit__ ?*status*?](#4)
[__coroutine::util gets__ *chan* ?*varname*?](#5)
[__coroutine::util gets_safety__ *chan* *limit* *varname*](#6)
[__coroutine::util global__ *varname*...](#7)
[__coroutine::util read__ __-nonewline__ *chan* ?*n*?](#8)
[__coroutine::util update__ ?__idletasks__?](#9)
[__coroutine::util vwait__ *varname*](#10)
# <a name='description'></a>DESCRIPTION
The __coroutine__ package provides coroutine-aware implementations of various
event- and channel related commands. It can be in multiple modes:
1. Call the commands through their ensemble, in code which is explicitly
written for use within coroutines.
1. Import the commands into a namespace, either directly, or through
__namespace path__. This allows the use from within code which is not
coroutine-aware per se and restricted to specific namespaces.
A more agressive form of making code coroutine-oblivious than point 2 above is
available through the package __[coroutine::auto](coro_auto.md)__, which
intercepts the relevant builtin commands and changes their implementation
dependending on the context they are run in, i.e. inside or outside of a
coroutine.
# <a name='section2'></a>API
All the commands listed below are synchronous with respect to the coroutine
invoking them, i.e. this coroutine blocks until the result is available. The
overall eventloop is not blocked however.
- <a name='1'></a>__coroutine::util after__ *delay*
This command delays the coroutine invoking it by *delay* milliseconds.
- <a name='2'></a>__coroutine::util await__ *varname*...
This command is an extension form of the __coroutine::util vwait__ command
(see below) which waits on a write to one of many named namespace variables.
- <a name='3'></a>__coroutine::util create__ *arg*...
This command creates a new coroutine with an automatically assigned name and
causes it to run the code specified by the arguments.
- <a name='4'></a>__coroutine::util exit__ ?*status*?
This command exits the current coroutine, causing it to return *status*. If
no status was specified the default *0* is returned.
- <a name='5'></a>__coroutine::util gets__ *chan* ?*varname*?
This command reads a line from the channel *chan* and returns it either as
its result, or, if a *varname* was specified, writes it to the named
variable and returns the number of characters read.
- <a name='6'></a>__coroutine::util gets_safety__ *chan* *limit* *varname*
This command reads a line from the channel *chan* up to size *limit* and
stores the result in *varname*. Of *limit* is reached before the set first
newline, an error is thrown. The command returns the number of characters
read.
- <a name='7'></a>__coroutine::util global__ *varname*...
This command imports the named global variables of the coroutine into the
current scope. From the technical point of view these variables reside in
level __#1__ of the Tcl stack. I.e. these are not the regular global
variable in to the global namespace, and each coroutine can have their own
set, independent of all others.
- <a name='8'></a>__coroutine::util read__ __-nonewline__ *chan* ?*n*?
This command reads *n* characters from the channel *chan* and returns them
as its result. If *n* is not specified the command will read the channel
until EOF is reached.
- <a name='9'></a>__coroutine::util update__ ?__idletasks__?
This command causes the coroutine invoking it to run pending events or idle
handlers before proceeding.
- <a name='10'></a>__coroutine::util vwait__ *varname*
This command causes the coroutine calling it to wait for a write to the
named namespace variable *varname*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *coroutine* 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.
# <a name='keywords'></a>KEYWORDS
[after](../../../../index.md#after), [channel](../../../../index.md#channel),
[coroutine](../../../../index.md#coroutine),
[events](../../../../index.md#events), [exit](../../../../index.md#exit),
[gets](../../../../index.md#gets), [global](../../../../index.md#global), [green
threads](../../../../index.md#green_threads), [read](../../../../index.md#read),
[threads](../../../../index.md#threads), [update](../../../../index.md#update),
[vwait](../../../../index.md#vwait)
# <a name='category'></a>CATEGORY
Coroutine
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010-2015 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/counter/counter.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
[//000000001]: # (counter - Counters and Histograms)
[//000000002]: # (Generated from file 'counter.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (counter(n) 2.0.4 tcllib "Counters and Histograms")
# NAME
counter - Procedures for counters and histograms
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require counter ?2.0.4?
[__::counter::init__ *tag args*](#1)
[__::counter::count__ *tag* ?*delta*? ?*instance*?](#2)
[__::counter::start__ *tag instance*](#3)
[__::counter::stop__ *tag instance*](#4)
[__::counter::get__ *tag args*](#5)
[__::counter::exists__ *tag*](#6)
[__::counter::names__](#7)
[__::counter::histHtmlDisplay__ *tag args*](#8)
[__::counter::reset__ *tag args*](#9)
# <a name='description'></a>DESCRIPTION
The __counter__ package provides a counter facility and can compute statistics
and histograms over the collected data.
- <a name='1'></a>__::counter::init__ *tag args*
This defines a counter with the name *tag*. The *args* determines the
characteristics of the counter. The *args* are
* __-group__ *name*
Keep a grouped counter where the name of the histogram bucket is passed
into __::counter::count__.
* __-hist__ *bucketsize*
Accumulate the counter into histogram buckets of size *bucketsize*. For
example, if the samples are millisecond time values and *bucketsize* is
10, then each histogram bucket represents time values of 0 to 10 msec,
10 to 20 msec, 20 to 30 msec, and so on.
* __-hist2x__ *bucketsize*
Accumulate the statistic into histogram buckets. The size of the first
bucket is *bucketsize*, each other bucket holds values 2 times the size
of the previous bucket. For example, if *bucketsize* is 10, then each
histogram bucket represents time values of 0 to 10 msec, 10 to 20 msec,
20 to 40 msec, 40 to 80 msec, and so on.
* __-hist10x__ *bucketsize*
Accumulate the statistic into histogram buckets. The size of the first
bucket is *bucketsize*, each other bucket holds values 10 times the size
of the previous bucket. For example, if *bucketsize* is 10, then each
histogram bucket represents time values of 0 to 10 msec, 10 to 100 msec,
100 to 1000 msec, and so on.
* __-lastn__ *N*
Save the last *N* values of the counter to maintain a "running average"
over the last *N* values.
* __-timehist__ *secsPerMinute*
Keep a time-based histogram. The counter is summed into a histogram
bucket based on the current time. There are 60 per-minute buckets that
have a size determined by *secsPerMinute*, which is normally 60, but for
testing purposes can be less. Every "hour" (i.e., 60 "minutes") the
contents of the per-minute buckets are summed into the next hourly
bucket. Every 24 "hours" the contents of the per-hour buckets are summed
into the next daily bucket. The counter package keeps all time-based
histograms in sync, so the first *secsPerMinute* value seen by the
package is used for all subsequent time-based histograms.
- <a name='2'></a>__::counter::count__ *tag* ?*delta*? ?*instance*?
Increment the counter identified by *tag*. The default increment is 1,
although you can increment by any value, integer or real, by specifying
*delta*. You must declare each counter with __::counter::init__ to define
the characteristics of counter before you start to use it. If the counter
type is __-group__, then the counter identified by *instance* is
incremented.
- <a name='3'></a>__::counter::start__ *tag instance*
Record the starting time of an interval. The *tag* is the name of the
counter defined as a __-hist__ value-based histogram. The *instance* is used
to distinguish this interval from any other intervals that might be
overlapping this one.
- <a name='4'></a>__::counter::stop__ *tag instance*
Record the ending time of an interval. The delta time since the
corresponding __::counter::start__ call for *instance* is recorded in the
histogram identified by *tag*.
- <a name='5'></a>__::counter::get__ *tag args*
Return statistics about a counter identified by *tag*. The *args* determine
what value to return:
* __-total__
Return the total value of the counter. This is the default if *args* is
not specified.
* __-totalVar__
Return the name of the total variable. Useful for specifying with
-textvariable in a Tk widget.
* __-N__
Return the number of samples accumulated into the counter.
* __-avg__
Return the average of samples accumulated into the counter.
* __-avgn__
Return the average over the last *N* samples taken. The *N* value is set
in the __::counter::init__ call.
* __-hist__ *bucket*
If *bucket* is specified, then the value in that bucket of the histogram
is returned. Otherwise the complete histogram is returned in array get
format sorted by bucket.
* __-histVar__
Return the name of the histogram array variable.
* __-histHour__
Return the complete hourly histogram in array get format sorted by
bucket.
* __-histHourVar__
Return the name of the hourly histogram array variable.
* __-histDay__
Return the complete daily histogram in array get format sorted by
bucket.
* __-histDayVar__
Return the name of the daily histogram array variable.
* __-resetDate__
Return the clock seconds value recorded when the counter was last reset.
* __-all__
Return an array get of the array used to store the counter. This
includes the total, the number of samples (N), and any type-specific
information. This does not include the histogram array.
- <a name='6'></a>__::counter::exists__ *tag*
Returns 1 if the counter is defined.
- <a name='7'></a>__::counter::names__
Returns a list of all counters defined.
- <a name='8'></a>__::counter::histHtmlDisplay__ *tag args*
Generate HTML to display a histogram for a counter. The *args* control the
format of the display. They are:
* __-title__ *string*
Label to display above bar chart
* __-unit__ *unit*
Specify __minutes__, __hours__, or __days__ for the time-base
histograms. For value-based histograms, the *unit* is used in the title.
* __-images__ *url*
URL of /images directory.
* __-gif__ *filename*
Image for normal histogram bars. The *filename* is relative to the
__-images__ directory.
* __-ongif__ *filename*
Image for the active histogram bar. The *filename* is relative to the
__-images__ directory.
* __-max__ *N*
Maximum number of value-based buckets to display.
* __-height__ *N*
Pixel height of the highest bar.
* __-width__ *N*
Pixel width of each bar.
* __-skip__ *N*
Buckets to skip when labeling value-based histograms.
* __-format__ *string*
Format used to display labels of buckets.
* __-text__ *boolean*
If 1, a text version of the histogram is dumped, otherwise a graphical
one is generated.
- <a name='9'></a>__::counter::reset__ *tag args*
Resets the counter with the name *tag* to an initial state. The *args*
determine the new characteristics of the counter. They have the same meaning
as described for __::counter::init__.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *counter* 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.
# <a name='keywords'></a>KEYWORDS
[counting](../../../../index.md#counting),
[histogram](../../../../index.md#histogram),
[statistics](../../../../index.md#statistics),
[tallying](../../../../index.md#tallying)
# <a name='category'></a>CATEGORY
Data structures
|
Added embedded/md/tcllib/files/modules/crc/cksum.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
[//000000001]: # (cksum - Cyclic Redundancy Checks)
[//000000002]: # (Generated from file 'cksum.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (cksum(n) 1.1.4 tcllib "Cyclic Redundancy Checks")
# NAME
cksum - Calculate a cksum(1) compatible checksum
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [OPTIONS](#section3)
- [PROGRAMMING INTERFACE](#section4)
- [EXAMPLES](#section5)
- [AUTHORS](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require cksum ?1.1.4?
[__::crc::cksum__ ?*-format format*? ?*-chunksize size*? [ *-channel chan* | *-filename file* | *string* ]](#1)
[__::crc::CksumInit__](#2)
[__::crc::CksumUpdate__ *token* *data*](#3)
[__::crc::CksumFinal__ *token*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a Tcl implementation of the cksum(1) algorithm based upon
information provided at in the GNU implementation of this program as part of the
GNU Textutils 2.0 package.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::crc::cksum__ ?*-format format*? ?*-chunksize size*? [ *-channel chan* | *-filename file* | *string* ]
The command takes string data or a channel or file name and returns a
checksum value calculated using the __cksum(1)__ algorithm. The result is
formatted using the *format*(n) specifier provided or as an unsigned integer
(%u) by default.
# <a name='section3'></a>OPTIONS
- -channel *name*
Return a checksum for the data read from a channel. The command will read
data from the channel until the __eof__ is true. If you need to be able to
process events during this calculation see the [PROGRAMMING
INTERFACE](#section4) section
- -filename *name*
This is a convenience option that opens the specified file, sets the
encoding to binary and then acts as if the *-channel* option had been used.
The file is closed on completion.
- -format *string*
Return the checksum using an alternative format template.
# <a name='section4'></a>PROGRAMMING INTERFACE
The cksum package implements the checksum using a context variable to which
additional data can be added at any time. This is expecially useful in an event
based environment such as a Tk application or a web server package. Data to be
checksummed may be handled incrementally during a __fileevent__ handler in
discrete chunks. This can improve the interactive nature of a GUI application
and can help to avoid excessive memory consumption.
- <a name='2'></a>__::crc::CksumInit__
Begins a new cksum context. Returns a token ID that must be used for the
remaining functions. An optional seed may be specified if required.
- <a name='3'></a>__::crc::CksumUpdate__ *token* *data*
Add data to the checksum identified by token. Calling *CksumUpdate $token
"abcd"* is equivalent to calling *CksumUpdate $token "ab"* followed by
*CksumUpdate $token "cb"*. See [EXAMPLES](#section5).
- <a name='4'></a>__::crc::CksumFinal__ *token*
Returns the checksum value and releases any resources held by this token.
Once this command completes the token will be invalid. The result is a 32
bit integer value.
# <a name='section5'></a>EXAMPLES
% crc::cksum "Hello, World!"
2609532967
% crc::cksum -format 0x%X "Hello, World!"
0x9B8A5027
% crc::cksum -file cksum.tcl
1828321145
% set tok [crc::CksumInit]
% crc::CksumUpdate $tok "Hello, "
% crc::CksumUpdate $tok "World!"
% crc::CksumFinal $tok
2609532967
# <a name='section6'></a>AUTHORS
Pat Thoyts
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *crc* 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.
# <a name='see-also'></a>SEE ALSO
[crc32(n)](crc32.md), [sum(n)](sum.md)
# <a name='keywords'></a>KEYWORDS
[checksum](../../../../index.md#checksum), [cksum](../../../../index.md#cksum),
[crc](../../../../index.md#crc), [crc32](../../../../index.md#crc32), [cyclic
redundancy check](../../../../index.md#cyclic_redundancy_check), [data
integrity](../../../../index.md#data_integrity),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts
|
Added embedded/md/tcllib/files/modules/crc/crc16.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
[//000000001]: # (crc16 - Cyclic Redundancy Checks)
[//000000002]: # (Generated from file 'crc16.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (crc16(n) 1.1.3 tcllib "Cyclic Redundancy Checks")
# NAME
crc16 - Perform a 16bit Cyclic Redundancy Check
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [OPTIONS](#section3)
- [EXAMPLES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require crc16 ?1.1.3?
[__::crc::crc16__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? __--__ *message*](#1)
[__::crc::crc16__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? -filename *file*](#2)
[__::crc::crc-ccitt__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? __--__ *message*](#3)
[__::crc::crc-ccitt__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? -filename *file*](#4)
[__::crc::xmodem__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? __--__ *message*](#5)
[__::crc::xmodem__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? -filename *file*](#6)
# <a name='description'></a>DESCRIPTION
This package provides a Tcl-only implementation of the CRC algorithms based upon
information provided at http://www.microconsultants.com/tips/crc/crc.txt There
are a number of permutations available for calculating CRC checksums and this
package can handle all of them. Defaults are set up for the most common cases.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::crc::crc16__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? __--__ *message*
- <a name='2'></a>__::crc::crc16__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? -filename *file*
- <a name='3'></a>__::crc::crc-ccitt__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? __--__ *message*
- <a name='4'></a>__::crc::crc-ccitt__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? -filename *file*
- <a name='5'></a>__::crc::xmodem__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? __--__ *message*
- <a name='6'></a>__::crc::xmodem__ ?-format *format*? ?-seed *value*? ?-implementation *procname*? -filename *file*
The command takes either string data or a file name and returns a checksum
value calculated using the CRC algorithm. The command used sets up the CRC
polynomial, initial value and bit ordering for the desired standard checksum
calculation. The result is formatted using the *format*(n) specifier
provided or as an unsigned integer (%u) by default.
A number of common polynomials are in use with the CRC algorithm and the
most commonly used of these are included in this package. For convenience
each of these has a command alias in the crc namespace.
It is possible to implement the CRC-32 checksum using this crc16 package as
the implementation is sufficiently generic to extend to 32 bit checksums. As
an example this has been done already - however this is not the fastest
method to implement this algorithm in Tcl and a separate
__[crc32](crc32.md)__ package is available.
# <a name='section3'></a>OPTIONS
- -filename *name*
Return a checksum for the file contents instead of for parameter data.
- -format *string*
Return the checksum using an alternative format template.
- -seed *value*
Select an alternative seed value for the CRC calculation. The default is 0
for the CRC16 calculation and 0xFFFF for the CCITT version. This can be
useful for calculating the CRC for data structures without first converting
the whole structure into a string. The CRC of the previous member can be
used as the seed for calculating the CRC of the next member. It is also used
for accumulating a checksum from fragments of a large message (or file)
- -implementation *procname*
This hook is provided to allow users to provide their own implementation
(perhaps a C compiled extension). The procedure specfied is called with two
parameters. The first is the data to be checksummed and the second is the
seed value. An integer is expected as the result.
The package provides some implementations of standard CRC polynomials for
the XMODEM, CCITT and the usual CRC-16 checksum. For convenience, additional
commands have been provided that make use of these implementations.
- --
Terminate option processing. Please note that using the option termination
flag is important when processing data from parameters. If the binary data
looks like one of the options given above then the data will be read as an
option if this marker is not included. Always use the *--* option
termination flag before giving the data argument.
# <a name='section4'></a>EXAMPLES
% crc::crc16 -- "Hello, World!"
64077
% crc::crc-ccitt -- "Hello, World!"
26586
% crc::crc16 -format 0x%X -- "Hello, World!"
0xFA4D
% crc::crc16 -file crc16.tcl
51675
# <a name='section5'></a>AUTHORS
Pat Thoyts
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *crc* 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.
# <a name='see-also'></a>SEE ALSO
[cksum(n)](cksum.md), [crc32(n)](crc32.md), [sum(n)](sum.md)
# <a name='keywords'></a>KEYWORDS
[checksum](../../../../index.md#checksum), [cksum](../../../../index.md#cksum),
[crc](../../../../index.md#crc), [crc16](../../../../index.md#crc16),
[crc32](../../../../index.md#crc32), [cyclic redundancy
check](../../../../index.md#cyclic_redundancy_check), [data
integrity](../../../../index.md#data_integrity),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, 2017, Pat Thoyts
|
Added embedded/md/tcllib/files/modules/crc/crc32.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
[//000000001]: # (crc32 - Cyclic Redundancy Checks)
[//000000002]: # (Generated from file 'crc32.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (crc32(n) 1.3.2 tcllib "Cyclic Redundancy Checks")
# NAME
crc32 - Perform a 32bit Cyclic Redundancy Check
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [OPTIONS](#section3)
- [PROGRAMMING INTERFACE](#section4)
- [EXAMPLES](#section5)
- [AUTHORS](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require crc32 ?1.3.2?
[__::crc::crc32__ ?-format *format*? ?-seed *value*? [ *-channel chan* | *-filename file* | *message* ]](#1)
[__::crc::Crc32Init__ ?*seed*?](#2)
[__::crc::Crc32Update__ *token* *data*](#3)
[__::crc::Crc32Final__ *token*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a Tcl implementation of the CRC-32 algorithm based upon
information provided at http://www.naaccr.org/standard/crc32/document.html If
either the __critcl__ package or the __Trf__ package are available then a
compiled version may be used internally to accelerate the checksum calculation.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::crc::crc32__ ?-format *format*? ?-seed *value*? [ *-channel chan* | *-filename file* | *message* ]
The command takes either string data or a channel or file name and returns a
checksum value calculated using the CRC-32 algorithm. The result is
formatted using the *format*(n) specifier provided. The default is to return
the value as an unsigned integer (format %u).
# <a name='section3'></a>OPTIONS
- -channel *name*
Return a checksum for the data read from a channel. The command will read
data from the channel until the __eof__ is true. If you need to be able to
process events during this calculation see the [PROGRAMMING
INTERFACE](#section4) section
- -filename *name*
This is a convenience option that opens the specified file, sets the
encoding to binary and then acts as if the *-channel* option had been used.
The file is closed on completion.
- -format *string*
Return the checksum using an alternative format template.
- -seed *value*
Select an alternative seed value for the CRC calculation. The default is
0xffffffff. This can be useful for calculating the CRC for data structures
without first converting the whole structure into a string. The CRC of the
previous member can be used as the seed for calculating the CRC of the next
member. Note that the crc32 algorithm includes a final XOR step. If
incremental processing is desired then this must be undone before using the
output of the algorithm as the seed for further processing. A simpler
alternative is to use the [PROGRAMMING INTERFACE](#section4) which is
intended for this mode of operation.
# <a name='section4'></a>PROGRAMMING INTERFACE
The CRC-32 package implements the checksum using a context variable to which
additional data can be added at any time. This is expecially useful in an event
based environment such as a Tk application or a web server package. Data to be
checksummed may be handled incrementally during a __fileevent__ handler in
discrete chunks. This can improve the interactive nature of a GUI application
and can help to avoid excessive memory consumption.
- <a name='2'></a>__::crc::Crc32Init__ ?*seed*?
Begins a new CRC32 context. Returns a token ID that must be used for the
remaining functions. An optional seed may be specified if required.
- <a name='3'></a>__::crc::Crc32Update__ *token* *data*
Add data to the checksum identified by token. Calling *Crc32Update $token
"abcd"* is equivalent to calling *Crc32Update $token "ab"* followed by
*Crc32Update $token "cb"*. See [EXAMPLES](#section5).
- <a name='4'></a>__::crc::Crc32Final__ *token*
Returns the checksum value and releases any resources held by this token.
Once this command completes the token will be invalid. The result is a 32
bit integer value.
# <a name='section5'></a>EXAMPLES
% crc::crc32 "Hello, World!"
3964322768
% crc::crc32 -format 0x%X "Hello, World!"
0xEC4AC3D0
% crc::crc32 -file crc32.tcl
483919716
% set tok [crc::Crc32Init]
% crc::Crc32Update $tok "Hello, "
% crc::Crc32Update $tok "World!"
% crc::Crc32Final $tok
3964322768
# <a name='section6'></a>AUTHORS
Pat Thoyts
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *crc* 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.
# <a name='see-also'></a>SEE ALSO
[cksum(n)](cksum.md), [crc16(n)](crc16.md), [sum(n)](sum.md)
# <a name='keywords'></a>KEYWORDS
[checksum](../../../../index.md#checksum), [cksum](../../../../index.md#cksum),
[crc](../../../../index.md#crc), [crc32](../../../../index.md#crc32), [cyclic
redundancy check](../../../../index.md#cyclic_redundancy_check), [data
integrity](../../../../index.md#data_integrity),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts
|
Added embedded/md/tcllib/files/modules/crc/sum.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
[//000000001]: # (sum - Cyclic Redundancy Checks)
[//000000002]: # (Generated from file 'sum.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (sum(n) 1.1.2 tcllib "Cyclic Redundancy Checks")
# NAME
sum - Calculate a sum(1) compatible checksum
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [OPTIONS](#section3)
- [EXAMPLES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require sum ?1.1.2?
[__::crc::sum__ ?*-bsd* | *-sysv*? ?*-format fmt*? ?*-chunksize size*? [ *-filename file* | *-channel chan* | *string* ]](#1)
# <a name='description'></a>DESCRIPTION
This package provides a Tcl-only implementation of the sum(1) command which
calculates a 16 bit checksum value from the input data. The BSD sum algorithm is
used by default but the SysV algorithm is also available.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::crc::sum__ ?*-bsd* | *-sysv*? ?*-format fmt*? ?*-chunksize size*? [ *-filename file* | *-channel chan* | *string* ]
The command takes string data or a file name or a channel and returns a
checksum value calculated using the __sum(1)__ algorithm. The result is
formatted using the *format*(n) specifier provided or as an unsigned integer
(%u) by default.
# <a name='section3'></a>OPTIONS
- -sysv
The SysV algorithm is fairly naive. The byte values are summed and any
overflow is discarded. The lowest 16 bits are returned as the checksum.
Input with the same content but different ordering will give the same
result.
- -bsd
This algorithm is similar to the SysV version but includes a bit rotation
step which provides a dependency on the order of the data values.
- -filename *name*
Return a checksum for the file contents instead of for parameter data.
- -channel *chan*
Return a checksum for the contents of the specified channel. The channel
must be open for reading and should be configured for binary translation.
The channel will no be closed on completion.
- -chunksize *size*
Set the block size used when reading data from either files or channels.
This value defaults to 4096.
- -format *string*
Return the checksum using an alternative format template.
# <a name='section4'></a>EXAMPLES
% crc::sum "Hello, World!"
37287
% crc::sum -format 0x%X "Hello, World!"
0x91A7
% crc::sum -file sum.tcl
13392
# <a name='section5'></a>AUTHORS
Pat Thoyts
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *crc* 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.
# <a name='see-also'></a>SEE ALSO
[cksum(n)](cksum.md), [crc32(n)](crc32.md), sum(1)
# <a name='keywords'></a>KEYWORDS
[checksum](../../../../index.md#checksum), [cksum](../../../../index.md#cksum),
[crc](../../../../index.md#crc), [crc32](../../../../index.md#crc32), [cyclic
redundancy check](../../../../index.md#cyclic_redundancy_check), [data
integrity](../../../../index.md#data_integrity),
[security](../../../../index.md#security), [sum](../../../../index.md#sum)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/cron/cron.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
[//000000001]: # (cron - cron)
[//000000002]: # (Generated from file 'cron.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (cron(n) 2.1 tcllib "cron")
# NAME
cron - Tool for automating the period callback of commands
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require cron ?2.1?
[__::cron::at__ *?processname?* *timecode* *command*](#1)
[__::cron::cancel__ *processname*](#2)
[__::cron::every__ *processname* *frequency* *command*](#3)
[__::cron::in__ *?processname?* *timecode* *command*](#4)
[__::cron::object_coroutine__ *object* *coroutine* *?info?*](#5)
[__::cron::sleep__ *milliseconds*](#6)
[__::cron::task delete__ *process*](#7)
[__::cron::task exists__ *process*](#8)
[__::cron::task info__ *process*](#9)
[__::cron::task set__ *process* *field* *value* *?field...?* *?value...?*](#10)
[__::cron::wake__ *?who?*](#11)
[__::cron::clock_step__ *milliseconds*](#12)
[__::cron::clock_delay__ *milliseconds*](#13)
[__::cron::clock_sleep__ *seconds* *?offset?*](#14)
[__::cron::clock_set__ *newtime*](#15)
# <a name='description'></a>DESCRIPTION
The __cron__ package provides a Pure-tcl set of tools to allow programs to
schedule tasks to occur at regular intervals. Rather than force each task to
issue it's own call to the event loop, the cron system mimics the cron utility
in Unix: on task periodically checks to see if something is to be done, and
issues all commands for a given time step at once.
Changes in version 2.0
While cron was originally designed to handle time scales > 1 second, the latest
version's internal understand time granularity down to the millisecond, making
it easier to integrate with other timed events. Version 2.0 also understands how
to properly integrate coroutines and objects. It also adds a facility for an
external (or script driven) clock. Note that vwait style events won't work very
well with an external clock.
# <a name='section2'></a>Commands
- <a name='1'></a>__::cron::at__ *?processname?* *timecode* *command*
This command registers a *command* to be called at the time specified by
*timecode*. If *timecode* is expressed as an integer, the timecode is
assumed to be in unixtime. All other inputs will be interpreted by __clock
scan__ and converted to unix time. This task can be modified by subsequent
calls to this package's commands by referencing *processname*. If
*processname* exists, it will be replaced. If *processname* is not given,
one is generated and returned by the command.
::cron::at start_coffee {Tomorrow at 9:00am} {remote::exec::coffeepot power on}
::cron::at shutdown_coffee {Tomorrow at 12:00pm} {remote::exec::coffeepot power off}
- <a name='2'></a>__::cron::cancel__ *processname*
This command unregisters the process *processname* and cancels any pending
commands. Note: processname can be a process created by either
__::cron::at__ or __::cron::every__.
::cron::cancel check_mail
- <a name='3'></a>__::cron::every__ *processname* *frequency* *command*
This command registers a *command* to be called at the interval of
*frequency*. *frequency* is given in seconds. This task can be modified by
subsequent calls to this package's commands by referencing *processname*. If
*processname* exists, it will be replaced.
::cron::every check_mail 900 ::imap_client::check_mail
::cron::every backup_db 3600 {::backup_procedure ::mydb}
- <a name='4'></a>__::cron::in__ *?processname?* *timecode* *command*
This command registers a *command* to be called after a delay of time
specified by *timecode*. *timecode* is expressed as an seconds. This task
can be modified by subsequent calls to this package's commands by
referencing *processname*. If *processname* exists, it will be replaced. If
*processname* is not given, one is generated and returned by the command.
- <a name='5'></a>__::cron::object_coroutine__ *object* *coroutine* *?info?*
This command registers a *coroutine*, associated with *object* to be called
given the parameters of *info*. If now parameters are given, the coroutine
is assumed to be an idle task which will self-terminate. *info* can be given
in any form compadible with __::cron::task set__
- <a name='6'></a>__::cron::sleep__ *milliseconds*
When run within a coroutine, this command will register the coroutine for a
callback at the appointed time, and immediately yield.
If the ::cron::time variable is > 0 this command will advance the internal
time, 100ms at a time.
In all other cases this command will generate a fictious variable, generate
an after call, and vwait the variable:
set eventid [incr ::cron::eventcount]
set var ::cron::event_#$eventid
set $var 0
::after $ms "set $var 1"
::vwait $var
::unset $var
Usage:
::cron::sleep 250
- <a name='7'></a>__::cron::task delete__ *process*
Delete the process specified the *process*
- <a name='8'></a>__::cron::task exists__ *process*
Returns true if *process* is registered with cron.
- <a name='9'></a>__::cron::task info__ *process*
Returns a dict describing *process*. See __::cron::task set__ for a
description of the options.
- <a name='10'></a>__::cron::task set__ *process* *field* *value* *?field...?* *?value...?*
If *process* does not exist, it is created. Options Include:
* __[command](../../../../index.md#command)__
If __[coroutine](../coroutine/tcllib_coroutine.md)__ is black, a global
command which implements this process. If
__[coroutine](../coroutine/tcllib_coroutine.md)__ is not black, the
command to invoke to create or recreate the coroutine.
* __[coroutine](../coroutine/tcllib_coroutine.md)__
The name of the coroutine (if any) which implements this process.
* __frequency__
If -1, this process is terminated after the next event. If 0 this
process should be called during every idle event. If positive, this
process should generate events periodically. The frequency is an integer
number of milliseconds between events.
* __[object](../../../../index.md#object)__
The object associated with this process or coroutine.
* __scheduled__
If non-zero, the absolute time from the epoch (in milliseconds) that
this process will trigger an event. If zero, and the __frequency__ is
also zero, this process is called every idle loop.
* __[running](../../../../index.md#running)__
A boolean flag. If true it indicates the process never returned or
yielded during the event loop, and will not be called again until it
does so.
- <a name='11'></a>__::cron::wake__ *?who?*
Wake up cron, and arrange for its event loop to be run during the next Idle
cycle.
::cron::wake {I just did something important}
Several utility commands are provided that are used internally within cron and
for testing cron, but may or may not be useful in the general cases.
- <a name='12'></a>__::cron::clock_step__ *milliseconds*
Return a clock time absolute to the epoch which falls on the next border
between one second and the next for the value of *milliseconds*
- <a name='13'></a>__::cron::clock_delay__ *milliseconds*
Return a clock time absolute to the epoch which falls on the next border
between one second and the next *milliseconds* in the future.
- <a name='14'></a>__::cron::clock_sleep__ *seconds* *?offset?*
Return a clock time absolute to the epoch which falls exactly *seconds* in
the future. If offset is given it may be positive or negative, and will
shift the final time to before or after the second would flip.
- <a name='15'></a>__::cron::clock_set__ *newtime*
Sets the internal clock for cron. This command will advance the time in
100ms increment, triggering events, until the internal time catches up with
*newtime*.
*newtime* is expressed in absolute milliseconds since the beginning of the
epoch.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *odie* 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.
# <a name='keywords'></a>KEYWORDS
[cron](../../../../index.md#cron), [odie](../../../../index.md#odie)
# <a name='category'></a>CATEGORY
System
# <a name='copyright'></a>COPYRIGHT
Copyright © 2016-2018 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/csv/csv.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
[//000000001]: # (csv - CSV processing)
[//000000002]: # (Generated from file 'csv.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (csv(n) 0.8.1 tcllib "CSV processing")
# NAME
csv - Procedures to handle CSV data.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [FORMAT](#section3)
- [EXAMPLE](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require csv ?0.8.1?
[__::csv::iscomplete__ *data*](#1)
[__::csv::join__ *values* ?*sepChar*? ?*delChar*? ?*delMode*?](#2)
[__::csv::joinlist__ *values* ?*sepChar*? ?*delChar*? ?*delMode*?](#3)
[__::csv::joinmatrix__ *matrix* ?*sepChar*? ?*delChar*? ?*delMode*?](#4)
[__::csv::read2matrix__ ?__-alternate__? *chan m* {*sepChar* ,} {*expand* none}](#5)
[__::csv::read2queue__ ?__-alternate__? *chan q* {*sepChar* ,}](#6)
[__::csv::report__ *cmd matrix* ?*chan*?](#7)
[__::csv::split__ ?__-alternate__? *line* ?*sepChar*? ?*delChar*?](#8)
[__::csv::split2matrix__ ?__-alternate__? *m line* {*sepChar* ,} {*expand* none}](#9)
[__::csv::split2queue__ ?__-alternate__? *q line* {*sepChar* ,}](#10)
[__::csv::writematrix__ *m chan* ?*sepChar*? ?*delChar*?](#11)
[__::csv::writequeue__ *q chan* ?*sepChar*? ?*delChar*?](#12)
# <a name='description'></a>DESCRIPTION
The __csv__ package provides commands to manipulate information in CSV
[FORMAT](#section3) (CSV = Comma Separated Values).
# <a name='section2'></a>COMMANDS
The following commands are available:
- <a name='1'></a>__::csv::iscomplete__ *data*
A predicate checking if the argument *data* is a complete csv record. The
result is a boolean flag indicating the completeness of the data. The result
is true if the data is complete.
- <a name='2'></a>__::csv::join__ *values* ?*sepChar*? ?*delChar*? ?*delMode*?
Takes a list of values and returns a string in CSV format containing these
values. The separator character can be defined by the caller, but this is
optional. The default is ",". The quoting aka delimiting character can be
defined by the caller, but this is optional. The default is '"'. By default
the quoting mode *delMode* is "auto", surrounding values with *delChar* only
when needed. When set to "always" however, values are always surrounded by
the *delChar* instead.
- <a name='3'></a>__::csv::joinlist__ *values* ?*sepChar*? ?*delChar*? ?*delMode*?
Takes a list of lists of values and returns a string in CSV format
containing these values. The separator character can be defined by the
caller, but this is optional. The default is ",". The quoting character can
be defined by the caller, but this is optional. The default is '"'. By
default the quoting mode *delMode* is "auto", surrounding values with
*delChar* only when needed. When set to "always" however, values are always
surrounded by the *delChar* instead. Each element of the outer list is
considered a record, these are separated by newlines in the result. The
elements of each record are formatted as usual (via __::csv::join__).
- <a name='4'></a>__::csv::joinmatrix__ *matrix* ?*sepChar*? ?*delChar*? ?*delMode*?
Takes a *matrix* object following the API specified for the struct::matrix
package and returns a string in CSV format containing these values. The
separator character can be defined by the caller, but this is optional. The
default is ",". The quoting character can be defined by the caller, but this
is optional. The default is '"'. By default the quoting mode *delMode* is
"auto", surrounding values with *delChar* only when needed. When set to
"always" however, values are always surrounded by the *delChar* instead.
Each row of the matrix is considered a record, these are separated by
newlines in the result. The elements of each record are formatted as usual
(via __::csv::join__).
- <a name='5'></a>__::csv::read2matrix__ ?__-alternate__? *chan m* {*sepChar* ,} {*expand* none}
A wrapper around __::csv::split2matrix__ (see below) reading CSV-formatted
lines from the specified channel (until EOF) and adding them to the given
matrix. For an explanation of the *expand* argument see
__::csv::split2matrix__.
- <a name='6'></a>__::csv::read2queue__ ?__-alternate__? *chan q* {*sepChar* ,}
A wrapper around __::csv::split2queue__ (see below) reading CSV-formatted
lines from the specified channel (until EOF) and adding them to the given
queue.
- <a name='7'></a>__::csv::report__ *cmd matrix* ?*chan*?
A report command which can be used by the matrix methods __format 2string__
and __format 2chan__. For the latter this command delegates the work to
__::csv::writematrix__. *cmd* is expected to be either __printmatrix__ or
__printmatrix2channel__. The channel argument, *chan*, has to be present for
the latter and must not be present for the first.
- <a name='8'></a>__::csv::split__ ?__-alternate__? *line* ?*sepChar*? ?*delChar*?
converts a *line* in CSV format into a list of the values contained in the
line. The character used to separate the values from each other can be
defined by the caller, via *sepChar*, but this is optional. The default is
",". The quoting character can be defined by the caller, but this is
optional. The default is '"'.
If the option __-alternate__ is specified a slightly different syntax is
used to parse the input. This syntax is explained below, in the section
[FORMAT](#section3).
- <a name='9'></a>__::csv::split2matrix__ ?__-alternate__? *m line* {*sepChar* ,} {*expand* none}
The same as __::csv::split__, but appends the resulting list as a new row to
the matrix *m*, using the method __add row__. The expansion mode specified
via *expand* determines how the command handles a matrix with less columns
than contained in *line*. The allowed modes are:
* __none__
This is the default mode. In this mode it is the responsibility of the
caller to ensure that the matrix has enough columns to contain the full
line. If there are not enough columns the list of values is silently
truncated at the end to fit.
* __empty__
In this mode the command expands an empty matrix to hold all columns of
the specified line, but goes no further. The overall effect is that the
first of a series of lines determines the number of columns in the
matrix and all following lines are truncated to that size, as if mode
__none__ was set.
* __auto__
In this mode the command expands the matrix as needed to hold all
columns contained in *line*. The overall effect is that after adding a
series of lines the matrix will have enough columns to hold all columns
of the longest line encountered so far.
- <a name='10'></a>__::csv::split2queue__ ?__-alternate__? *q line* {*sepChar* ,}
The same as __::csv::split__, but appending the resulting list as a single
item to the queue *q*, using the method __put__.
- <a name='11'></a>__::csv::writematrix__ *m chan* ?*sepChar*? ?*delChar*?
A wrapper around __::csv::join__ taking all rows in the matrix *m* and
writing them CSV formatted into the channel *chan*.
- <a name='12'></a>__::csv::writequeue__ *q chan* ?*sepChar*? ?*delChar*?
A wrapper around __::csv::join__ taking all items in the queue *q* (assumes
that they are lists) and writing them CSV formatted into the channel *chan*.
# <a name='section3'></a>FORMAT
The format of regular CSV files is specified as
1. Each record of a csv file (comma-separated values, as exported e.g. by
Excel) is a set of ASCII values separated by ",". For other languages it
may be ";" however, although this is not important for this case as the
functions provided here allow any separator character.
1. If and only if a value contains itself the separator ",", then it (the
value) has to be put between "". If the value does not contain the
separator character then quoting is optional.
1. If a value contains the character ", that character is represented by "".
1. The output string "" represents the value ". In other words, it is assumed
that it was created through rule 3, and only this rule, i.e. that the value
was not quoted.
An alternate format definition mainly used by MS products specifies that the
output string "" is a representation of the empty string. In other words, it is
assumed that the output was generated out of the empty string by quoting it
(i.e. rule 2), and not through rule 3. This is the only difference between the
regular and the alternate format.
The alternate format is activated through specification of the option
__-alternate__ to the various split commands.
# <a name='section4'></a>EXAMPLE
Using the regular format the record
123,"123,521.2","Mary says ""Hello, I am Mary""",""
is parsed into the items
a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
d) "
Using the alternate format the result is
a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
d) (the empty string)
instead. As can be seen only item (d) is different, now the empty string instead
of a ".
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *csv* 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.
# <a name='see-also'></a>SEE ALSO
[matrix](../../../../index.md#matrix), [queue](../../../../index.md#queue)
# <a name='keywords'></a>KEYWORDS
[csv](../../../../index.md#csv), [matrix](../../../../index.md#matrix),
[package](../../../../index.md#package), [queue](../../../../index.md#queue),
[tcllib](../../../../index.md#tcllib)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002-2015 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/debug/debug.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
[//000000001]: # (debug - debug narrative)
[//000000002]: # (Generated from file 'debug.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (debug(n) 1.0.6 tcllib "debug narrative")
# NAME
debug - debug narrative - core
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require debug ?1.0.6?
[__debug.____tag__ *message* ?*level*?](#1)
[__debug__ __2array__](#2)
[__debug__ __define__ *tag*](#3)
[__debug__ __header__ *text*](#4)
[__debug__ __level__ *tag* ?*level*? ?*fd*?](#5)
[__debug__ __names__](#6)
[__debug__ __off__ *tag*](#7)
[__debug__ __on__ *tag*](#8)
[__debug__ __parray__ *arrayvarname*](#9)
[__debug__ __pdict__ *dict*](#10)
[__debug__ __hexl__ *data* ?*prefix*?](#11)
[__debug__ __nl__](#12)
[__debug__ __tab__](#13)
[__debug__ __prefix__ *tag* ?*text*?](#14)
[__debug__ __setting__ (*tag* *level*) ... ?*fd*?](#15)
[__debug__ __suffix__ *tag* ?*text*?](#16)
[__debug__ __trailer__ *text*](#17)
# <a name='description'></a>DESCRIPTION
Debugging areas of interest are represented by 'tags' which have independently
settable levels of interest (an integer, higher is more detailed).
# <a name='section2'></a>API
- <a name='1'></a>__debug.____tag__ *message* ?*level*?
For each known tag the package creates a command with this signature the
user can then use to provide the debug narrative of the tag. The narrative
*message* is provided as a Tcl script whose value is
__[subst](../../../../index.md#subst)__ed in the caller's scope if and only
if the current level of interest for the *tag* matches or exceeds the call's
*level* of detail. This is useful, as one can place arbitrarily complex
narrative in code without unnecessarily evaluating it.
See methods __level__ and __setting__ for querying and manipulating the
current level of detail for tags.
The actually printed text consists of not only the *message*, but also
global and tag-specific prefix and suffix, should they exist, with each line
in the message having the specified headers and trailers.
All these parts are __[subst](../../../../index.md#subst)__ableTcl scripts,
which are substituted once per message before assembly.
- <a name='2'></a>__debug__ __2array__
This method returns a dictionary mapping the names of all debug tags
currently known to the package to their state and log level. The latter are
encoded in a single numeric value, where a negative number indicates an
inactive tag at the level given by the absolute value, and a positive number
is an active tag at that level.
See also method __settings__ below.
- <a name='3'></a>__debug__ __define__ *tag*
This method registers the named *tag* with the package. If the tag was not
known before it is placed in an inactive state. The state of an already
known tag is left untouched.
The result of the method is the empty string.
- <a name='4'></a>__debug__ __header__ *text*
This method defines a global __[subst](../../../../index.md#subst)__able Tcl
script which provides a text printed before each line of output.
Note how this is tag-independent.
Further note that the header substitution happens only once per actual
printed message, i.e. all lines of the same message will have the same
actual heading text.
The result of the method is the specified text.
- <a name='5'></a>__debug__ __level__ *tag* ?*level*? ?*fd*?
This method sets the detail-*level* for the *tag*, and the channel *fd* to
write the tags narration into. The level is an integer value >= 0 defaulting
to __1__. The channel defaults to __stderr__.
The result of the method is the new detail-level for the tag.
- <a name='6'></a>__debug__ __names__
This method returns a list containing the names of all debug tags currently
known to the package.
- <a name='7'></a>__debug__ __off__ *tag*
This method registers the named *tag* with the package and sets it inactive.
The result of the method is the empty string.
- <a name='8'></a>__debug__ __on__ *tag*
This method registers the named *tag* with the package, as active.
The result of the method is the empty string.
- <a name='9'></a>__debug__ __parray__ *arrayvarname*
This is a convenience method formatting the named array like the builtin
command __parray__, except it returns the resulting string instead of
writing it directly to __stdout__.
This makes it suitable for use in debug messages.
- <a name='10'></a>__debug__ __pdict__ *dict*
This is a convenience method formatting the dictionary similarly to how the
builtin command __parray__ does for array, and returns the resulting string.
This makes it suitable for use in debug messages.
- <a name='11'></a>__debug__ __hexl__ *data* ?*prefix*?
This is a convenience method formatting arbitrary data into a hex-dump and
returns the resulting string.
This makes it suitable for use in debug messages.
Each line of the dump is prefixed with *prefix*. This prefix defaults to the
empty string.
- <a name='12'></a>__debug__ __nl__
This is a convenience method to insert a linefeed character (ASCII 0x0a)
into a debug message.
- <a name='13'></a>__debug__ __tab__
This is a convenience method to insert a TAB character (ASCII 0x09) into a
debug message.
- <a name='14'></a>__debug__ __prefix__ *tag* ?*text*?
This method is similar to the method __header__ above, in that it defines
__[subst](../../../../index.md#subst)__able Tcl script which provides more
text for debug messages.
In contrast to __header__ the generated text is added to the user's message
before it is split into lines, making it a per-message extension.
Furthermore the script is tag-dependent.
In exception to that, a script for tag __::__ is applied to all messages.
If both global and tag-dependent prefix exist, both are applied, with the
global prefix coming before the tag-dependent prefix.
Note that the prefix substitution happens only once per actual printed
message.
The result of the method is the empty string.
If the *tag* was not known at the time of the call it is registered, and set
inactive.
- <a name='15'></a>__debug__ __setting__ (*tag* *level*) ... ?*fd*?
This method is a multi-tag variant of method __level__ above, with the
functionality of methods __on__, and __off__ also folded in.
Each named *tag* is set to the detail-*level* following it, with a negative
level deactivating the tag, and a positive level activating it.
If the last argument is not followed by a level it is not treated as tag
name, but as the channel all the named tags should print their messages to.
The result of the method is the empty string.
- <a name='16'></a>__debug__ __suffix__ *tag* ?*text*?
This method is similar to the method __trailer__ below, in that it defines
__[subst](../../../../index.md#subst)__able Tcl script which provides more
text for debug messages.
In contrast to __trailer__ the generated text is added to the user's message
before it is split into lines, making it a per-message extension.
Furthermore the script is tag-dependent.
In exception to that, a script for tag __::__ is applied to all messages.
If both global and tag-dependent suffix exist, both are applied, with the
global suffix coming after the tag-dependent suffix.
Note that the suffix substitution happens only once per actual printed
message.
The result of the method is the empty string.
If the *tag* was not known at the time of the call it is registered, and set
inactive.
- <a name='17'></a>__debug__ __trailer__ *text*
This method defines a global __[subst](../../../../index.md#subst)__able Tcl
script which provides a text printed after each line of output (before the
EOL however).
Note how this is tag-independent.
Further note that the trailer substitution happens only once per actual
printed message, i.e. all lines of the same message will have the same
actual trailing text.
The result of the method is the specified text.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *debug* 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.
# <a name='keywords'></a>KEYWORDS
[debug](../../../../index.md#debug), [log](../../../../index.md#log),
[narrative](../../../../index.md#narrative), [trace](../../../../index.md#trace)
# <a name='category'></a>CATEGORY
debugging, tracing, and logging
# <a name='copyright'></a>COPYRIGHT
Copyright © 200?, Colin McCormack, Wub Server Utilities
Copyright © 2012-2014, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/debug/debug_caller.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
[//000000001]: # (debug::caller - debug narrative)
[//000000002]: # (Generated from file 'debug_caller.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (debug::caller(n) 1.1 tcllib "debug narrative")
# NAME
debug::caller - debug narrative - caller
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require debug::caller ?1.1?
[__[debug](debug.md)__ __caller__ ?*args*...?](#1)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>API
- <a name='1'></a>__[debug](debug.md)__ __caller__ ?*args*...?
This method is useful in a tag-specific prefix to automatically provide
caller information for all uses of the tag. Or in a message, when only
specific places need such detail.
Beyond that it recognizing the various internal forms of method calls
generated by the __[snit](../snit/snit.md)__ OO system and rewrites these to
their original form, for better readability. Similarly for
__[TclOO](../../../../index.md#tcloo)__.
If *args* are specified then they are treated as the integer indices of
command arguments to *not* show in the output. The referenced arguments are
replaced by __*__ instead. The main anticipiated use case for this is the
exclusion of arguments expected to contain large Tcl values, i.e. long
lists, large dictionaries, etc. to prevent them from overwhelming the
narrative.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *debug* 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.
# <a name='keywords'></a>KEYWORDS
[debug](../../../../index.md#debug), [log](../../../../index.md#log),
[narrative](../../../../index.md#narrative), [trace](../../../../index.md#trace)
# <a name='category'></a>CATEGORY
debugging, tracing, and logging
# <a name='copyright'></a>COPYRIGHT
Copyright © 2012-2015, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/debug/debug_heartbeat.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
[//000000001]: # (debug::heartbeat - debug narrative)
[//000000002]: # (Generated from file 'debug_heartbeat.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (debug::heartbeat(n) 1 tcllib "debug narrative")
# NAME
debug::heartbeat - debug narrative - heartbeat
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require debug::heartbeat ?1?
package require debug ?1?
[__[debug](debug.md)__ __heartbeat__ ?*delta*?](#1)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>API
- <a name='1'></a>__[debug](debug.md)__ __heartbeat__ ?*delta*?
This method activates or disables a heartbeat with which to monitor the
event loop of an event-based Tcl application.
It reserves the debug tag __heartbeat__ for its operation and writes a
message every *delta* milliseconds.
A *delta*-value <= 0 disables the heartbeat.
The message produced by the heartbeat contains a sequence counter and the
time in milliseconds since the last beat, thus providing insight into timing
variationsn and deviations from the nominal *delta*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *debug* 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.
# <a name='keywords'></a>KEYWORDS
[debug](../../../../index.md#debug),
[heartbeat](../../../../index.md#heartbeat), [log](../../../../index.md#log),
[narrative](../../../../index.md#narrative), [trace](../../../../index.md#trace)
# <a name='category'></a>CATEGORY
debugging, tracing, and logging
# <a name='copyright'></a>COPYRIGHT
Copyright © 200?, Colin McCormack, Wub Server Utilities
Copyright © 2012, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/debug/debug_timestamp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
[//000000001]: # (debug::timestamp - debug narrative)
[//000000002]: # (Generated from file 'debug_timestamp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (debug::timestamp(n) 1 tcllib "debug narrative")
# NAME
debug::timestamp - debug narrative - timestamping
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require debug::timestamp ?1?
package require debug ?1?
[__[debug](debug.md)__ __timestamp__](#1)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>API
- <a name='1'></a>__[debug](debug.md)__ __timestamp__
This method returns millisecond timing information since a baseline or last
call, making it useful in a tag-specific prefix to automatically provide
caller information for all uses of the tag. Or in a message, when only
specific places need such detail.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *debug* 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.
# <a name='keywords'></a>KEYWORDS
[debug](../../../../index.md#debug), [log](../../../../index.md#log),
[narrative](../../../../index.md#narrative),
[timestamps](../../../../index.md#timestamps),
[trace](../../../../index.md#trace)
# <a name='category'></a>CATEGORY
debugging, tracing, and logging
# <a name='copyright'></a>COPYRIGHT
Copyright © 200?, Colin McCormack, Wub Server Utilities
Copyright © 2012, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/defer/defer.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
[//000000001]: # (defer - Defered execution ala Go)
[//000000002]: # (Generated from file 'defer.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (defer(n) 1 tcllib "Defered execution ala Go")
# NAME
defer - Defered execution
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require defer ?1?
[__::defer::defer__ ?*command*? ?*arg1*? ?*arg2*? ?*argN...*?](#1)
[__::defer::with__ *variableList* *script*](#2)
[__::defer::autowith__ *script*](#3)
[__::defer::cancel__ ?*id...*?](#4)
# <a name='description'></a>DESCRIPTION
The __defer__ commands allow a developer to schedule actions to happen as part
of the current variable scope terminating. This is most useful for dealing with
cleanup activities. Since the defered actions always execute, and always execute
in the reverse order from which the defer statements themselves execute, the
programmer can schedule the cleanup of a resource (for example, a channel) as
soon as that resource is acquired. Then, later if the procedure or lambda ends,
either due to an error, or an explicit return, the cleanup of that resource will
always occur.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::defer::defer__ ?*command*? ?*arg1*? ?*arg2*? ?*argN...*?
Defers execution of some code until the current variable scope ends. Each
argument is concatencated together to form the script to execute at deferal
time. Multiple defer statements may be used, they are executed in the order
of last-in, first-out. The return value is an identifier which can be used
later with __defer::cancel__
- <a name='2'></a>__::defer::with__ *variableList* *script*
Defers execution of a script while copying the current value of some
variables, whose names specified in *variableList*, into the script. The
script acts like a lambda but executes at the same level as the
__defer::with__ call. The return value is the same as __::defer::defer__
- <a name='3'></a>__::defer::autowith__ *script*
The same as __::defer::with__ but uses all local variables in the variable
list.
- <a name='4'></a>__::defer::cancel__ ?*id...*?
Cancels the execution of a defered action. The *id* argument is the
identifier returned by __::defer::defer__, __::defer::with__, or
__::defer::autowith__. Any number of arguments may be supplied, and all of
the IDs supplied will be cancelled.
# <a name='section3'></a>EXAMPLES
package require defer 1
apply {{} {
set fd [open /dev/null]
defer::defer close $fd
}}
# <a name='section4'></a>REFERENCES
# <a name='section5'></a>AUTHORS
Roy Keene
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *defer* 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.
# <a name='keywords'></a>KEYWORDS
[cleanup](../../../../index.md#cleanup), [golang](../../../../index.md#golang)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2017, Roy Keene
|
Added embedded/md/tcllib/files/modules/des/des.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
[//000000001]: # (des - Data Encryption Standard (DES))
[//000000002]: # (Generated from file 'des.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (des(n) 1.1 tcllib "Data Encryption Standard (DES)")
# NAME
des - Implementation of the DES and triple-DES ciphers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [MODES OF OPERATION](#section4)
- [EXAMPLES](#section5)
- [REFERENCES](#section6)
- [AUTHORS](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require des 1.1
[__::DES::des__ ?*-mode [ecb|cbc|cfb|ofb]*? ?*-dir [encrypt|decrypt]*? *-key keydata* ?*-iv vector*? ?*-hex*? ?*-weak*? ?*-out channel*? ?*-chunksize size*? [ *-in channel* | *data* ]](#1)
[__::DES::Init__ *mode* *keydata* *iv* ?*weak*?](#2)
[__::DES::Encrypt__ *Key* *data*](#3)
[__::DES::Decrypt__ *Key* *data*](#4)
[__::DES::Reset__ *Key* *iv*](#5)
[__::DES::Final__ *Key*](#6)
# <a name='description'></a>DESCRIPTION
This is an implementation in Tcl of the Data Encryption Standard (DES) as
published by the U.S. National Institute of Standards and Technology (NIST) [1].
This implementation also supports triple DES (3DES) extension to DES. DES is a
64-bit block cipher that uses a 56-bit key. 3DES uses a 168-bit key. DES has now
officially been superceeded by AES but is in common use in many protocols.
The tcllib implementation of DES and 3DES uses an implementation by Mac Cody and
is available as a separate download from [2]. For anyone concerned about the
details of exporting this code please see the TclDES web pages. The tcllib
specific code is a wrapper to the TclDES API that presents same API for the DES
cipher as for other ciphers in the library.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::DES::des__ ?*-mode [ecb|cbc|cfb|ofb]*? ?*-dir [encrypt|decrypt]*? *-key keydata* ?*-iv vector*? ?*-hex*? ?*-weak*? ?*-out channel*? ?*-chunksize size*? [ *-in channel* | *data* ]
Perform the __[DES](../../../../index.md#des)__ algorithm on either the data
provided by the argument or on the data read from the *-in* channel. If an
*-out* channel is given then the result will be written to this channel.
The *-key* option must be given. This parameter takes a binary string of 8
bytes in length and is used to generate the key schedule. In DES only 56
bits of key data are used. The highest bit from each byte is discarded.
The *-mode* and *-dir* options are optional and default to cbc mode and
encrypt respectively. The initialization vector *-iv* takes an 8 byte binary
argument. This defaults to all zeros. See [MODES OF OPERATION](#section4)
for more about *-mode* and the use of the initialization vector.
DES is a 64-bit block cipher. This means that the data must be provided in
units that are a multiple of 8 bytes.
# <a name='section3'></a>PROGRAMMING INTERFACE
Internal state is maintained in an opaque structure that is returned from the
__Init__ function. In ECB mode the state is not affected by the input but for
other modes some input dependent state is maintained and may be reset by calling
the __Reset__ function with a new initialization vector value.
- <a name='2'></a>__::DES::Init__ *mode* *keydata* *iv* ?*weak*?
Construct a new DES key schedule using the specified key data and the given
initialization vector. The initialization vector is not used with ECB mode
but is important for other usage modes. See [MODES OF OPERATION](#section4).
There are a small number of keys that are known to be weak when used with
DES. By default if such a key is passed in then an error will be raised. If
there is a need to accept such keys then the *weak* parameter can be set
true to avoid the error being thrown.
- <a name='3'></a>__::DES::Encrypt__ *Key* *data*
Use a prepared key acquired by calling __Init__ to encrypt the provided
data. The data argument should be a binary array that is a multiple of the
DES block size of 8 bytes. The result is a binary array the same size as the
input of encrypted data.
- <a name='4'></a>__::DES::Decrypt__ *Key* *data*
Decipher data using the key. Note that the same key may be used to encrypt
and decrypt data provided that the initialization vector is reset
appropriately for CBC mode.
- <a name='5'></a>__::DES::Reset__ *Key* *iv*
Reset the initialization vector. This permits the programmer to re-use a key
and avoid the cost of re-generating the key schedule where the same key data
is being used multiple times.
- <a name='6'></a>__::DES::Final__ *Key*
This should be called to clean up resources associated with *Key*. Once this
function has been called the key may not be used again.
# <a name='section4'></a>MODES OF OPERATION
- Electronic Code Book (ECB)
ECB is the basic mode of all block ciphers. Each block is encrypted
independently and so identical plain text will produce identical output when
encrypted with the same key. Any encryption errors will only affect a single
block however this is vulnerable to known plaintext attacks.
- Cipher Block Chaining (CBC)
CBC mode uses the output of the last block encryption to affect the current
block. An initialization vector of the same size as the cipher block size is
used to handle the first block. The initialization vector should be chosen
randomly and transmitted as the first block of the output. Errors in
encryption affect the current block and the next block after which the
cipher will correct itself. CBC is the most commonly used mode in software
encryption.
- Cipher Feedback (CFB)
CFB mode can be used to convert block ciphers into stream ciphers. In CFB
mode the initialization vector is encrypted and the output is then xor'd
with the plaintext stream. The result is then used as the initialization
vector for the next round. Errors will affect the current block and the next
block.
- Output Feedback (OFB)
OFB is similar to CFB except that the output of the cipher is fed back into
the next round and not the xor'd plain text. This means that errors only
affect a single block but the cipher is more vulnerable to attack.
# <a name='section5'></a>EXAMPLES
% set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext]
% set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext]
set iv [string repeat \\0 8]
set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv]
set ciphertext [DES::Encrypt $Key "somedata"]
append ciphertext [DES::Encrypt $Key "moredata"]
DES::Reset $Key $iv
set plaintext [DES::Decrypt $Key $ciphertext]
DES::Final $Key
# <a name='section6'></a>REFERENCES
1. "Data Encryption Standard", Federal Information Processing Standards
Publication 46-3, 1999,
([http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf](http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf))
1. "TclDES: munitions-grade Tcl scripting"
[http://tcldes.sourceforge.net/](http://tcldes.sourceforge.net/)
# <a name='section7'></a>AUTHORS
Jochen C Loewer, Mac Cody, Pat Thoyts
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *des* 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.
# <a name='see-also'></a>SEE ALSO
[aes(n)](../aes/aes.md), [blowfish(n)](../blowfish/blowfish.md),
[md5(n)](../md5/md5.md), [rc4(n)](../rc4/rc4.md), [sha1(n)](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[3DES](../../../../index.md#3des), [DES](../../../../index.md#des), [block
cipher](../../../../index.md#block_cipher), [data
integrity](../../../../index.md#data_integrity),
[encryption](../../../../index.md#encryption),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/des/tcldes.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
[//000000001]: # (tclDES - Data Encryption Standard (DES))
[//000000002]: # (Generated from file 'tcldes.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tclDES(n) 1.1 tcllib "Data Encryption Standard (DES)")
# NAME
tclDES - Implementation of the DES and triple-DES ciphers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require tclDES 1.1
# <a name='description'></a>DESCRIPTION
The __tclDES__ package is a helper package for __[des](des.md)__.
Please see the documentation of __[des](des.md)__ for details.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *des* 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.
# <a name='see-also'></a>SEE ALSO
[des(n)](des.md)
# <a name='keywords'></a>KEYWORDS
[3DES](../../../../index.md#3des), [DES](../../../../index.md#des), [block
cipher](../../../../index.md#block_cipher), [data
integrity](../../../../index.md#data_integrity),
[encryption](../../../../index.md#encryption),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/des/tcldesjr.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
[//000000001]: # (tclDESjr - Data Encryption Standard (DES))
[//000000002]: # (Generated from file 'tcldesjr.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tclDESjr(n) 1.1 tcllib "Data Encryption Standard (DES)")
# NAME
tclDESjr - Implementation of the DES and triple-DES ciphers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require tclDESjr 1.1
# <a name='description'></a>DESCRIPTION
The __tclDESjr__ package is a helper package for __[des](des.md)__.
Please see the documentation of __[des](des.md)__ for details.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *des* 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.
# <a name='see-also'></a>SEE ALSO
[des(n)](des.md)
# <a name='keywords'></a>KEYWORDS
[3DES](../../../../index.md#3des), [DES](../../../../index.md#des), [block
cipher](../../../../index.md#block_cipher), [data
integrity](../../../../index.md#data_integrity),
[encryption](../../../../index.md#encryption),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/dicttool/dicttool.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
[//000000001]: # (dicttool - Extensions to the standard "dict" command)
[//000000002]: # (Generated from file 'dicttool.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (dicttool(n) 1.0 tcllib "Extensions to the standard "dict" command")
# NAME
dicttool - Dictionary Tools
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
[__ladd__ *varname* *args*](#1)
[__ldelete__ *varname* *args*](#2)
[__dict getnull__ *args*](#3)
[__dict print__ *dict*](#4)
[__dict is_dict__ *value*](#5)
[__rmerge__ *args*](#6)
# <a name='description'></a>DESCRIPTION
The __dicttool__ package enhances the standard *dict* command with several new
commands. In addition, the package also defines several "creature comfort" list
commands as well. Each command checks to see if a command already exists of the
same name before adding itself, just in case any of these slip into the core.
- <a name='1'></a>__ladd__ *varname* *args*
This command will add a new instance of each element in *args* to *varname*,
but only if that element is not already present.
- <a name='2'></a>__ldelete__ *varname* *args*
This command will add a delete all instances of each element in *args* from
*varname*.
- <a name='3'></a>__dict getnull__ *args*
Operates like __dict get__, however if the key *args* does not exist, it
returns an empty list instead of throwing an error.
- <a name='4'></a>__dict print__ *dict*
This command will produce a string representation of *dict*, with each
nested branch on a newline, and indented with two spaces for every level.
- <a name='5'></a>__dict is_dict__ *value*
This command will return true if *value* can be interpreted as a dict. The
command operates in such a way as to not force an existing dict
representation to shimmer into another internal rep.
- <a name='6'></a>__rmerge__ *args*
Return a dict which is the product of a recursive merge of all of the
arguments. Unlike __dict merge__, this command descends into all of the
levels of a dict. Dict keys which end in a : indicate a leaf, which will be
interpreted as a literal value, and not descended into further.
set items [dict merge {
option {color {default: green}}
} {
option {fruit {default: mango}}
} {
option {color {default: blue} fruit {widget: select values: {mango apple cherry grape}}}
}]
puts [dict print $items]
Prints the following result:
option {
color {
default: blue
}
fruit {
widget: select
values: {mango apple cherry grape}
}
}
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *dict* 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.
# <a name='keywords'></a>KEYWORDS
[dict](../../../../index.md#dict)
# <a name='category'></a>CATEGORY
Utilities
# <a name='copyright'></a>COPYRIGHT
Copyright © 2017 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/dns/tcllib_dns.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
|
[//000000001]: # (dns - Domain Name Service)
[//000000002]: # (Generated from file 'tcllib_dns.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (dns(n) 1.4.0 tcllib "Domain Name Service")
# NAME
dns - Tcl Domain Name Service Client
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require dns ?1.4.0?
[__::dns::resolve__ *query* ?*options*?](#1)
[__::dns::configure__ ?*options*?](#2)
[__::dns::name__ *token*](#3)
[__::dns::address__ *token*](#4)
[__::dns::cname__ *token*](#5)
[__::dns::result__ *token*](#6)
[__::dns::status__ *token*](#7)
[__::dns::error__ *token*](#8)
[__::dns::reset__ *token*](#9)
[__::dns::wait__ *token*](#10)
[__::dns::cleanup__ *token*](#11)
[__::dns::nameservers__](#12)
# <a name='description'></a>DESCRIPTION
The dns package provides a Tcl only Domain Name Service client. You should refer
to (1) and (2) for information about the DNS protocol or read resolver(3) to
find out how the C library resolves domain names. The intention of this package
is to insulate Tcl scripts from problems with using the system library resolver
for slow name servers. It may or may not be of practical use. Internet name
resolution is a complex business and DNS is only one part of the resolver. You
may find you are supposed to be using hosts files, NIS or WINS to name a few
other systems. This package is not a substitute for the C library resolver - it
does however implement name resolution over DNS. The package also extends the
package __[uri](../uri/uri.md)__ to support DNS URIs (4) of the form
[dns:what.host.com](dns:what.host.com) or
[dns://my.nameserver/what.host.com](dns://my.nameserver/what.host.com). The
__dns::resolve__ command can handle DNS URIs or simple domain names as a query.
*Note:* The package defaults to using DNS over TCP connections. If you wish to
use UDP you will need to have the __tcludp__ package installed and have a
version that correctly handles binary data (> 1.0.4). This is available at
[http://tcludp.sourceforge.net/](http://tcludp.sourceforge.net/). If the __udp__
package is present then UDP will be used by default.
*Note:* The package supports DNS over TLS (RFC 7858) for enhanced privacy of DNS
queries. Using this feature requires the TLS package.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::dns::resolve__ *query* ?*options*?
Resolve a domain name using the *[DNS](../../../../index.md#dns)* protocol.
*query* is the domain name to be lookup up. This should be either a fully
qualified domain name or a DNS URI.
* __-nameserver__ *hostname* or __-server__ *hostname*
Specify an alternative name server for this request.
* __-protocol__ *tcp|udp*
Specify the network protocol to use for this request. Can be one of
*tcp* or *udp*.
* __-port__ *portnum*
Specify an alternative port.
* __-search__ *domainlist*
* __-timeout__ *milliseconds*
Override the default timeout.
* __-type__ *TYPE*
Specify the type of DNS record you are interested in. Valid values are
A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, MINFO, MX,
TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. See RFC1035 for details
about the return values. See
[http://spf.pobox.com/](http://spf.pobox.com/) about SPF. See (3) about
AAAA records and RFC2782 for details of SRV records.
* __-class__ *CLASS*
Specify the class of domain name. This is usually IN but may be one of
IN for internet domain names, CS, CH, HS or * for any class.
* __-recurse__ *boolean*
Set to *false* if you do not want the name server to recursively act
upon your request. Normally set to *true*.
* __-command__ *procname*
Set a procedure to be called upon request completion. The procedure will
be passed the token as its only argument.
* __-usetls__ *boolean*
Set the *true* to use DNS over TLS. This will force the use of TCP and
change the default port to 853. Certificate validation is required so a
source of trusted certificate authority certificates must be provided
using *-cafile* or *-cadir*.
* __-cafile__ *filepath*
Specify a file containing a collection of trusted certificate authority
certficates. See the __update-ca-certificates__ command manual page for
details or the __-CAfile__ option help from __openssl__.
* __-cadir__ *dirpath*
Specify a directory containing trusted certificate authority
certificates. This must be provided if __-cafile__ is not specified for
certificate validation to work when __-usetls__ is enabled. See the
__openssl__ documentation for the required structure of this directory.
- <a name='2'></a>__::dns::configure__ ?*options*?
The __::dns::configure__ command is used to setup the dns package. The
server to query, the protocol and domain search path are all set via this
command. If no arguments are provided then a list of all the current
settings is returned. If only one argument then it must the the name of an
option and the value for that option is returned.
* __-nameserver__ *hostname*
Set the default name server to be used by all queries. The default is
*localhost*.
* __-protocol__ *tcp|udp*
Set the default network protocol to be used. Default is *tcp*.
* __-port__ *portnum*
Set the default port to use on the name server. The default is 53.
* __-search__ *domainlist*
Set the domain search list. This is currently not used.
* __-timeout__ *milliseconds*
Set the default timeout value for DNS lookups. Default is 30 seconds.
* __-loglevel__ *level*
Set the log level used for emitting diagnostic messages from this
package. The default is *warn*. See the __[log](../log/log.md)__ package
for details of the available levels.
* __-cafile__ *filepath*
Set the default file path to be used for the __-cafile__ option to
__dns::resolve__.
* __-cadir__ *dirpath*
Set the default directory path to be used for the __-cadir__ option to
__dns::resolve__.
- <a name='3'></a>__::dns::name__ *token*
Returns a list of all domain names returned as an answer to your query.
- <a name='4'></a>__::dns::address__ *token*
Returns a list of the address records that match your query.
- <a name='5'></a>__::dns::cname__ *token*
Returns a list of canonical names (usually just one) matching your query.
- <a name='6'></a>__::dns::result__ *token*
Returns a list of all the decoded answer records provided for your query.
This permits you to extract the result for more unusual query types.
- <a name='7'></a>__::dns::status__ *token*
Returns the status flag. For a successfully completed query this will be
*ok*. May be *error* or *timeout* or *eof*. See also __::dns::error__
- <a name='8'></a>__::dns::error__ *token*
Returns the error message provided for requests whose status is *error*. If
there is no error message then an empty string is returned.
- <a name='9'></a>__::dns::reset__ *token*
Reset or cancel a DNS query.
- <a name='10'></a>__::dns::wait__ *token*
Wait for a DNS query to complete and return the status upon completion.
- <a name='11'></a>__::dns::cleanup__ *token*
Remove all state variables associated with the request.
- <a name='12'></a>__::dns::nameservers__
Attempts to return a list of the nameservers currently configured for the
users system. On a unix machine this parses the /etc/resolv.conf file for
nameservers (if it exists) and on Windows systems we examine certain parts
of the registry. If no nameserver can be found then the loopback address
(127.0.0.1) is used as a default.
# <a name='section3'></a>EXAMPLES
% set tok [dns::resolve www.tcl.tk]
::dns::1
% dns::status $tok
ok
% dns::address $tok
199.175.6.239
% dns::name $tok
www.tcl.tk
% dns::cleanup $tok
Using DNS URIs as queries:
% set tok [dns::resolve "dns:tcl.tk;type=MX"]
% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"]
Reverse address lookup:
% set tok [dns::resolve 127.0.0.1]
::dns::1
% dns::name $tok
localhost
% dns::cleanup $tok
Using DNS over TLS (RFC 7858):
% set tok [dns::resolve www.tcl.tk -nameserver dns-tls.bitwiseshift.net -usetls 1 -cafile /etc/ssl/certs/ca-certificates.crt]
::dns::12
% dns::wait $tok
ok
% dns::address $tok
104.25.119.118 104.25.120.118
# <a name='section4'></a>REFERENCES
1. Mockapetris, P., "Domain Names - Concepts and Facilities", RFC 1034,
November 1987.
([http://www.ietf.org/rfc/rfc1034.txt](http://www.ietf.org/rfc/rfc1034.txt))
1. Mockapetris, P., "Domain Names - Implementation and Specification", RFC
1035, November 1087.
([http://www.ietf.org/rfc/rfc1035.txt](http://www.ietf.org/rfc/rfc1035.txt))
1. Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", RFC
1886, December 1995.
([http://www.ietf.org/rfc/rfc1886.txt](http://www.ietf.org/rfc/rfc1886.txt))
1. Josefsson, S., "Domain Name System Uniform Resource Identifiers",
Internet-Draft, October 2003,
([http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt](http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt))
1. Gulbrandsen, A., Vixie, P. and Esibov, L., "A DNS RR for specifying the
location of services (DNS SRV)", RFC 2782, February 2000,
([http://www.ietf.org/rfc/rfc2782.txt](http://www.ietf.org/rfc/rfc2782.txt))
1. Ohta, M. "Incremental Zone Transfer in DNS", RFC 1995, August 1996,
([http://www.ietf.org/rfc/rfc1995.txt](http://www.ietf.org/rfc/rfc1995.txt))
1. Hu, Z., etc al. "Specification for DNS over Transport Layer Security
(TLS)", RFC 7858, May 2016,
([http://www.ietf.org/rfc/rfc7858.txt](http://www.ietf.org/rfc/rfc7858.txt))
# <a name='section5'></a>AUTHORS
Pat Thoyts
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *dns* 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.
# <a name='see-also'></a>SEE ALSO
resolver(5)
# <a name='keywords'></a>KEYWORDS
[DNS](../../../../index.md#dns), [domain name
service](../../../../index.md#domain_name_service),
[resolver](../../../../index.md#resolver), [rfc
1034](../../../../index.md#rfc_1034), [rfc 1035](../../../../index.md#rfc_1035),
[rfc 1886](../../../../index.md#rfc_1886), [rfc
7858](../../../../index.md#rfc_7858)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts
|
Added embedded/md/tcllib/files/modules/dns/tcllib_ip.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
|
[//000000001]: # (tcllib_ip - Domain Name Service)
[//000000002]: # (Generated from file 'tcllib_ip.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib_ip(n) 1.4 tcllib "Domain Name Service")
# NAME
tcllib_ip - IPv4 and IPv6 address manipulation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require ip ?1.4?
[__::ip::version__ *address*](#1)
[__::ip::is__ *class* *address*](#2)
[__::ip::equal__ *address* *address*](#3)
[__::ip::normalize__ *address*](#4)
[__::ip::contract__ *address*](#5)
[__::ip::distance__ *ipaddr1* *ipaddr2*](#6)
[__::ip::nextIp__ *ipaddr* ?*offset*?](#7)
[__::ip::prefix__ *address*](#8)
[__::ip::type__ *address*](#9)
[__::ip::mask__ *address*](#10)
[__::ip::prefixToNative__ *prefix*](#11)
[__::ip::nativeToPrefix__ *nativeList*|*native* ?__-ipv4__?](#12)
[__::ip::intToString__ *number* ?__-ipv4__?](#13)
[__::ip::toInteger__ *ipaddr*](#14)
[__::ip::toHex__ *ipaddr*](#15)
[__::ip::maskToInt__ *ipmask*](#16)
[__::ip::broadcastAddress__ *prefix* ?__-ipv4__?](#17)
[__::ip::maskToLength__ *dottedMask*|*integerMask*|*hexMask* ?__-ipv4__?](#18)
[__::ip::lengthToMask__ *maskLength* ?__-ipv4__?](#19)
[__::ip::nextNet__ *ipaddr* *ipmask* ?*count*? ?__-ipv4__?](#20)
[__::ip::isOverlap__ *prefix* *prefix*...](#21)
[__::ip::isOverlapNative__ ?__-all__? ?__-inline__? ?__-ipv4__? *hexipaddr* *hexipmask* *hexiplist*](#22)
[__::ip::ipToLayer2Multicast__ *ipaddr*](#23)
[__::ip::ipHostFromPrefix__ *prefix* ?__-exclude__ *prefixExcludeList*?](#24)
[__::ip::reduceToAggregates__ *prefixlist*](#25)
[__::ip::longestPrefixMatch__ *ipaddr* *prefixlist* ?__-ipv4__?](#26)
[__::ip::collapse__ *prefixlist*](#27)
[__::ip::subtract__ *prefixlist*](#28)
# <a name='description'></a>DESCRIPTION
This package provides a set of commands to help in parsing, displaying and
comparing internet addresses. The package can handle both IPv4 (1) and IPv6 (2)
address types.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::ip::version__ *address*
Returns the protocol version of the address (__4__ or __6__), or __-1__ if
the address is neither IPv4 or IPv6.
- <a name='2'></a>__::ip::is__ *class* *address*
Returns true if the address is a member of the given protocol class. The
class parameter may be either __ipv4__ or __ipv6__ This is effectively a
boolean equivalent of the __version__ command. The *class* argument may be
shortened to __4__ or __6__.
- <a name='3'></a>__::ip::equal__ *address* *address*
Compare two address specifications for equivalence. The arguments are
normalized and the address prefix determined (if a mask is supplied). The
normalized addresses are then compared bit-by-bit and the procedure returns
true if they match.
- <a name='4'></a>__::ip::normalize__ *address*
Convert an IPv4 or IPv6 address into a fully expanded version. There are
various shorthand ways to write internet addresses, missing out redundant
parts or digits. This procedure is the opposite of __contract__.
- <a name='5'></a>__::ip::contract__ *address*
Convert a __normalize__d internet address into a more compact form suitable
for displaying to users.
- <a name='6'></a>__::ip::distance__ *ipaddr1* *ipaddr2*
This command computes the (integer) distance from IPv4 address *ipaddr1* to
IPv4 address *ipaddr2*, i.e. "ipaddr2 - ipaddr1"
% ::ip::distance 1.1.1.1 1.1.1.5
4
- <a name='7'></a>__::ip::nextIp__ *ipaddr* ?*offset*?
This command adds the integer *offset* to the IPv4 address *ipaddr* and
returns the new IPv4 address.
% ::ip::distance 1.1.1.1 4
1.1.1.5
- <a name='8'></a>__::ip::prefix__ *address*
Returns the address prefix generated by masking the address part with the
mask if provided. If there is no mask then it is equivalent to calling
__normalize__
- <a name='9'></a>__::ip::type__ *address*
- <a name='10'></a>__::ip::mask__ *address*
If the address supplied includes a mask then this is returned otherwise
returns an empty string.
- <a name='11'></a>__::ip::prefixToNative__ *prefix*
This command converts the string *prefix* from dotted form (<ipaddr>/<mask>
format) to native (hex) form. Returns a list containing two elements,
ipaddress and mask, in this order, in hexadecimal notation.
% ip::prefixToNative 1.1.1.0/24
0x01010100 0xffffff00
- <a name='12'></a>__::ip::nativeToPrefix__ *nativeList*|*native* ?__-ipv4__?
This command converts from native (hex) form to dotted form. It is the
complement of __::ip::prefixToNative__.
* list *nativeList* (in)
List of several ip addresses in native form. The native form is a list
as returned by __::ip::prefixToNative__.
* list *native* (in)
A list as returned by __::ip::prefixToNative__.
The command returns a list of addresses in dotted form if it was called with
a list of addresses. Otherwise a single address in dotted form is returned.
% ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
1.1.1.0/24
- <a name='13'></a>__::ip::intToString__ *number* ?__-ipv4__?
This command converts from an ip address specified as integer number to
dotted form.
ip::intToString 4294967295
255.255.255.255
- <a name='14'></a>__::ip::toInteger__ *ipaddr*
This command converts a dotted form ip into an integer number.
% ::ip::toInteger 1.1.1.0
16843008
- <a name='15'></a>__::ip::toHex__ *ipaddr*
This command converts dotted form ip into a hexadecimal number.
% ::ip::toHex 1.1.1.0
0x01010100
- <a name='16'></a>__::ip::maskToInt__ *ipmask*
This command convert an ipmask in either dotted (255.255.255.0) form or mask
length form (24) into an integer number.
::ip::maskToInt 24
4294967040
- <a name='17'></a>__::ip::broadcastAddress__ *prefix* ?__-ipv4__?
This commands returns a broadcast address in dotted form for the given route
*prefix*, either in the form "addr/mask", or in native form. The result is
in dotted form.
::ip::broadcastAddress 1.1.1.0/24
1.1.1.255
::ip::broadcastAddress {0x01010100 0xffffff00}
0x010101ff
- <a name='18'></a>__::ip::maskToLength__ *dottedMask*|*integerMask*|*hexMask* ?__-ipv4__?
This command converts the dotted or integer form of an ipmask to the mask
length form.
::ip::maskToLength 0xffffff00 -ipv4
24
% ::ip::maskToLength 255.255.255.0
24
- <a name='19'></a>__::ip::lengthToMask__ *maskLength* ?__-ipv4__?
This command converts an ipmask in mask length form to its dotted form.
::ip::lengthToMask 24
255.255.255.0
- <a name='20'></a>__::ip::nextNet__ *ipaddr* *ipmask* ?*count*? ?__-ipv4__?
This command returns an ipaddress in the same position in the *count* next
network. The default value for *count* is __1__.
The address can be specified as either integer number or in dotted form. The
mask can be specified as either integer number, dotted form, or mask length
form.
The result is in hex form.
- <a name='21'></a>__::ip::isOverlap__ *prefix* *prefix*...
This command checks if the given ip prefixes overlap. All arguments are in
dotted "addr/mask" form. All arguments after the first prefix are compared
against the first prefix. The result is a boolean value. It is true if an
overlap was found for any of the prefixes.
% ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
0
::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
1
- <a name='22'></a>__::ip::isOverlapNative__ ?__-all__? ?__-inline__? ?__-ipv4__? *hexipaddr* *hexipmask* *hexiplist*
This command is similar to __::ip::isOverlap__, however the arguments are in
the native form, and the form of the result is under greater control of the
caller. If the option __-all__ is specified it checks all addresses for
overlap, not only until the first one is found. If the option __-inline__ is
specified the command returns the overlapping prefix instead of index
values.
The result of the command is, depending on the specified options,
* no options
The index of the first overlap found, or 0 if there is none.
* -all
A list containing the indices of all overlaps found, or an empty list if
there are none.
* -inline
The first overlapping prefix, or an empoty string if there is none.
* -all -inline
A list containing the prefixes of all overlaps found, or an empty list
if there are none.
% ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
0
% ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
2
- <a name='23'></a>__::ip::ipToLayer2Multicast__ *ipaddr*
This command an converts ipv4 address in dotted form into a layer 2
multicast address, also in dotted form.
% ::ip::ipToLayer2Multicast 224.0.0.2
01.00.5e.00.00.02
- <a name='24'></a>__::ip::ipHostFromPrefix__ *prefix* ?__-exclude__ *prefixExcludeList*?
This command returns a host address from a prefix in the form
"ipaddr/masklen", also making sure that the result is not an address found
in the *prefixExcludeList*. The result is an ip address in dotted form.
%::ip::ipHostFromPrefix 1.1.1.5/24
1.1.1.1
%::ip::ipHostFromPrefix 1.1.1.1/32
1.1.1.1
- <a name='25'></a>__::ip::reduceToAggregates__ *prefixlist*
This command finds nets that overlap and filters out the more specific nets.
The prefixes are in either addr/mask form or in native format. The result is
a list containing the non-overlapping ip prefixes from the input.
% ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8 2.1.1.0/24 1.1.1.1/32 }
1.0.0.0/8 2.1.1.0/24
- <a name='26'></a>__::ip::longestPrefixMatch__ *ipaddr* *prefixlist* ?__-ipv4__?
This command finds longest prefix match from set of prefixes, given a
specific host address. The prefixes in the list are in either native or
dotted form, whereas the host address is in either ipprefix format, dotted
form, or integer form. The result is the prefix which is the most specific
match to the host address.
% ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8 2.1.1.0/24 1.1.1.0/28 }
1.1.1.0/28
- <a name='27'></a>__::ip::collapse__ *prefixlist*
This commands takes a list of prefixes and returns a list prefixes with the
largest possible subnet masks covering the input, in this manner collapsing
adjacent prefixes into larger ranges.
This is different from __::ip::reduceToAggregates__ in that the latter only
removes specific nets from a list when they are covered by other elements of
the input whereas this command actively merges nets into larger ranges when
they are adjacent to each other.
% ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
1.2.2.0/23
- <a name='28'></a>__::ip::subtract__ *prefixlist*
This command takes a list of prefixes, some of which are prefixed by a dash.
These latter *negative* prefixes are used to punch holes into the ranges
described by the other, *positive*, prefixes. I.e. the negative prefixes are
subtracted frrom the positive ones, resulting in a larger list of describes
describing the covered ranges only as positives.
# <a name='section3'></a>EXAMPLES
% ip::version ::1
6
% ip::version 127.0.0.1
4
% ip::normalize 127/8
127.0.0.0/8
% ip::contract 192.168.0.0
192.168
%
% ip::normalize fec0::1
fec0:0000:0000:0000:0000:0000:0000:0001
% ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
fec0::1
% ip::equal 192.168.0.4/16 192.168.0.0/16
1
% ip::equal fec0::1/10 fec0::fe01/10
1
# <a name='section4'></a>REFERENCES
1. Postel, J. "Internet Protocol." RFC 791, September 1981,
([http://www.ietf.org/rfc/rfc791.txt](http://www.ietf.org/rfc/rfc791.txt))
1. Hinden, R. and Deering, S., "Internet Protocol Version 6 (IPv6) Addressing
Architecture", RFC 3513, April 2003
([http://www.ietf.org/rfc/rfc3513.txt](http://www.ietf.org/rfc/rfc3513.txt))
# <a name='section5'></a>AUTHORS
Pat Thoyts
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *dns* 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.
# <a name='see-also'></a>SEE ALSO
inet(3), ip(7), ipv6(7)
# <a name='keywords'></a>KEYWORDS
[internet address](../../../../index.md#internet_address),
[ip](../../../../index.md#ip), [ipv4](../../../../index.md#ipv4),
[ipv6](../../../../index.md#ipv6), [rfc 3513](../../../../index.md#rfc_3513)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004, Pat Thoyts
Copyright © 2005 Aamer Akhter <[email protected]>
|
Added embedded/md/tcllib/files/modules/docstrip/docstrip.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
|
[//000000001]: # (docstrip - Literate programming tool)
[//000000002]: # (Generated from file 'docstrip.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docstrip(n) 1.2 tcllib "Literate programming tool")
# NAME
docstrip - Docstrip style source code extraction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [File format](#section2)
- [Commands](#section3)
- [Document structure](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require docstrip ?1.2?
[__docstrip::extract__ *text* *terminals* ?*option* *value* ...?](#1)
[__docstrip::sourcefrom__ *filename* *terminals* ?*option* *value* ...?](#2)
# <a name='description'></a>DESCRIPTION
__Docstrip__ is a tool created to support a brand of Literate Programming. It is
most common in the (La)TeX community, where it is being used for pretty much
everything from the LaTeX core and up, but there is nothing about __docstrip__
which prevents using it for other types of software.
In short, the basic principle of literate programming is that program source
should primarily be written and structured to suit the developers (and advanced
users who want to peek "under the hood"), not to suit the whims of a compiler or
corresponding source code consumer. This means literate sources often need some
kind of "translation" to an illiterate form that dumb software can understand.
The __docstrip__ Tcl package handles this translation.
Even for those who do not whole-hartedly subscribe to the philosophy behind
literate programming, __docstrip__ can bring greater clarity to in particular:
- programs employing non-obvious mathematics
- projects where separate pieces of code, perhaps in different languages, need
to be closely coordinated.
The first is by providing access to much more powerful typographical features
for source code comments than are possible in plain text. The second is because
all the separate pieces of code can be kept next to each other in the same
source file.
The way it works is that the programmer edits directly only one or several
"master" source code files, from which __docstrip__ generates the more
traditional "source" files compilers or the like would expect. The master
sources typically contain a large amount of documentation of the code, sometimes
even in places where the code consumers would not allow any comments. The
etymology of "docstrip" is that this *doc*umentation was *strip*ped away
(although "code extraction" might be a better description, as it has always been
a matter of copying selected pieces of the master source rather than deleting
text from it). The __docstrip__ Tcl package contains a reimplementation of the
basic extraction functionality from the __docstrip__ program, and thus makes it
possible for a Tcl interpreter to read and interpret the master source files
directly.
Readers who are not previously familiar with __docstrip__ but want to know more
about it may consult the following sources.
1. *The tclldoc package and class*,
[http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/](http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/).
1. *The DocStrip utility*,
[http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx](http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx).
1. *The doc and shortvrb Packages*,
[http://ctan.org/tex-archive/macros/latex/base/doc.dtx](http://ctan.org/tex-archive/macros/latex/base/doc.dtx).
1. Chapter 14 of *The LaTeX Companion* (second edition), Addison-Wesley, 2004;
ISBN 0-201-36299-6.
# <a name='section2'></a>File format
The basic unit __docstrip__ operates on are the *lines* of a master source file.
Extraction consists of selecting some of these lines to be copied from input
text to output text. The basic distinction is that between *code lines* (which
are copied and do not begin with a percent character) and *comment lines* (which
begin with a percent character and are not copied).
docstrip::extract [join {
{% comment}
{% more comment !"#$%&/(}
{some command}
{ % blah $blah "Not a comment."}
{% abc; this is comment}
{# def; this is code}
{ghi}
{% jkl}
} \n] {}
returns the same sequence of lines as
join {
{some command}
{ % blah $blah "Not a comment."}
{# def; this is code}
{ghi} ""
} \n
It does not matter to __docstrip__ what format is used for the documentation in
the comment lines, but in order to do better than plain text comments, one
typically uses some markup language. Most commonly LaTeX is used, as that is a
very established standard and also provides the best support for mathematical
formulae, but the __docstrip::util__ package also gives some support for
*[doctools](../../../../index.md#doctools)*-like markup.
Besides the basic code and comment lines, there are also *guard lines*, which
begin with the two characters '%<', and *meta-comment lines*, which begin with
the two characters '%%'. Within guard lines there is furthermore the distinction
between *verbatim guard lines*, which begin with '%<<', and ordinary guard
lines, where the '%<' is not followed by another '<'. The last category is by
far the most common.
Ordinary guard lines conditions extraction of the code line(s) they guard by the
value of a boolean expression; the guarded block of code lines will only be
included if the expression evaluates to true. The syntax of an ordinary guard
line is one of
'%' '<' STARSLASH EXPRESSION '>'
'%' '<' PLUSMINUS EXPRESSION '>' CODE
where
STARSLASH ::= '*' | '/'
PLUSMINUS ::= | '+' | '-'
EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION
| SECONDARY '|' EXPRESSION
SECONDARY ::= PRIMARY | PRIMARY '&' SECONDARY
PRIMARY ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')'
CODE ::= { any character except end-of-line }
Comma and vertical bar both denote 'or'. Ampersand denotes 'and'. Exclamation
mark denotes 'not'. A TERMINAL can be any nonempty string of characters not
containing '>', '&', '|', comma, '(', or ')', although the __docstrip__ manual
is a bit restrictive and only guarantees proper operation for strings of letters
(although even the LaTeX core sources make heavy use also of digits in
TERMINALs). The second argument of __docstrip::extract__ is the list of those
TERMINALs that should count as having the value 'true'; all other TERMINALs
count as being 'false' when guard expressions are evaluated.
In the case of a '%<**EXPRESSION*>' guard, the lines guarded are all lines up to
the next '%</*EXPRESSION*>' guard with the same *EXPRESSION* (compared as
strings). The blocks of code delimited by such '*' and '/' guard lines must be
properly nested.
set text [join {
{begin}
{%<*foo>}
{1}
{%<*bar>}
{2}
{%</bar>}
{%<*!bar>}
{3}
{%</!bar>}
{4}
{%</foo>}
{5}
{%<*bar>}
{6}
{%</bar>}
{end}
} \n]
set res [docstrip::extract $text foo]
append res [docstrip::extract $text {foo bar}]
append res [docstrip::extract $text bar]
sets $res to the result of
join {
{begin}
{1}
{3}
{4}
{5}
{end}
{begin}
{1}
{2}
{4}
{5}
{6}
{end}
{begin}
{5}
{6}
{end} ""
} \n
In guard lines without a '*', '/', '+', or '-' modifier after the '%<', the
guard applies only to the CODE following the '>' on that single line. A '+'
modifier is equivalent to no modifier. A '-' modifier is like the case with no
modifier, but the expression is implicitly negated, i.e., the CODE of a '%<-'
guard line is only included if the expression evaluates to false.
Metacomment lines are "comment lines which should not be stripped away", but be
extracted like code lines; these are sometimes used for copyright notices and
similar material. The '%%' prefix is however not kept, but substituted by the
current __-metaprefix__, which is customarily set to some "comment until end of
line" character (or character sequence) of the language of the code being
extracted.
set text [join {
{begin}
{%<foo> foo}
{%<+foo>plusfoo}
{%<-foo>minusfoo}
{middle}
{%% some metacomment}
{%<*foo>}
{%%another metacomment}
{%</foo>}
{end}
} \n]
set res [docstrip::extract $text foo -metaprefix {# }]
append res [docstrip::extract $text bar -metaprefix {#}]
sets $res to the result of
join {
{begin}
{ foo}
{plusfoo}
{middle}
{# some metacomment}
{# another metacomment}
{end}
{begin}
{minusfoo}
{middle}
{# some metacomment}
{end} ""
} \n
Verbatim guards can be used to force code line interpretation of a block of
lines even if some of them happen to look like any other type of lines to
docstrip. A verbatim guard has the form '%<<*END-TAG*' and the verbatim block is
terminated by the first line that is exactly '%*END-TAG*'.
set text [join {
{begin}
{%<*myblock>}
{some stupid()}
{ #computer<program>}
{%<<QQQ-98765}
{% These three lines are copied verbatim (including percents}
{%% even if -metaprefix is something different than %%).}
{%</myblock>}
{%QQQ-98765}
{ using*strange@programming<language>}
{%</myblock>}
{end}
} \n]
set res [docstrip::extract $text myblock -metaprefix {# }]
append res [docstrip::extract $text {}]
sets $res to the result of
join {
{begin}
{some stupid()}
{ #computer<program>}
{% These three lines are copied verbatim (including percents}
{%% even if -metaprefix is something different than %%).}
{%</myblock>}
{ using*strange@programming<language>}
{end}
{begin}
{end} ""
} \n
The processing of verbatim guards takes place also inside blocks of lines which
due to some outer block guard will not be copied.
The final piece of __docstrip__ syntax is that extraction stops at a line that
is exactly "\endinput"; this is often used to avoid copying random whitespace at
the end of a file. In the unlikely case that one wants such a code line, one can
protect it with a verbatim guard.
# <a name='section3'></a>Commands
The package defines two commands.
- <a name='1'></a>__docstrip::extract__ *text* *terminals* ?*option* *value* ...?
The __extract__ command docstrips the *text* and returns the extracted lines
of code, as a string with each line terminated with a newline. The
*terminals* is the list of those guard expression terminals which should
evaluate to true. The available options are:
* __-annotate__ *lines*
Requests the specified number of lines of annotation to follow each
extracted line in the result. Defaults to 0. Annotation lines are mostly
useful when the extracted lines are to undergo some further
transformation. A first annotation line is a list of three elements:
line type, prefix removed in extraction, and prefix inserted in
extraction. The line type is one of: 'V' (verbatim), 'M' (metacomment),
'+' (+ or no modifier guard line), '-' (- modifier guard line), '.'
(normal line). A second annotation line is the source line number. A
third annotation line is the current stack of block guards. Requesting
more than three lines of annotation is currently not supported.
* __-metaprefix__ *string*
The string by which the '%%' prefix of a metacomment line will be
replaced. Defaults to '%%'. For Tcl code this would typically be '#'.
* __-onerror__ *keyword*
Controls what will be done when a format error in the *text* being
processed is detected. The settings are:
+ __ignore__
Just ignore the error; continue as if nothing happened.
+ __puts__
Write an error message to __stderr__, then continue processing.
+ __throw__
Throw an error. The __-errorcode__ is set to a list whose first
element is __DOCSTRIP__, second element is the type of error, and
third element is the line number where the error is detected. This
is the default.
* __-trimlines__ *boolean*
Controls whether *spaces* at the end of a line should be trimmed away
before the line is processed. Defaults to true.
It should be remarked that the *terminals* are often called "options" in the
context of the __docstrip__ program, since these specify which optional code
fragments should be included.
- <a name='2'></a>__docstrip::sourcefrom__ *filename* *terminals* ?*option* *value* ...?
The __sourcefrom__ command is a docstripping emulation of
__[source](../../../../index.md#source)__. It opens the file *filename*,
reads it, closes it, docstrips the contents as specified by the *terminals*,
and evaluates the result in the local context of the caller, during which
time the __[info](../../../../index.md#info)__ __script__ value will be the
*filename*. The options are passed on to __fconfigure__ to configure the
file before its contents are read. The __-metaprefix__ is set to '#', all
other __extract__ options have their default values.
# <a name='section4'></a>Document structure
The file format (as described above) determines whether a master source code
file can be processed correctly by __docstrip__, but the usefulness of the
format is to no little part also dependent on that the code and comment lines
together constitute a well-formed document.
For a document format that does not require any non-Tcl software, see the
__ddt2man__ command in the __docstrip::util__ package. It is suggested that
files employing that document format are given the suffix ".ddt", to distinguish
them from the more traditional LaTeX-based ".dtx" files.
Master source files with ".dtx" extension are usually set up so that they can be
typeset directly by __[latex](../../../../index.md#latex)__ without any support
from other files. This is achieved by beginning the file with the lines
% \iffalse
%<*driver>
\documentclass{tclldoc}
\begin{document}
\DocInput{*filename.dtx*}
\end{document}
%</driver>
% \fi
or some variation thereof. The trick is that the file gets read twice. With
normal LaTeX reading rules, the first two lines are comments and therefore
ignored. The third line is the document preamble, the fourth line begins the
document body, and the sixth line ends the document, so LaTeX stops there —
non-comments below that point in the file are never subjected to the normal
LaTeX reading rules. Before that, however, the \DocInput command on the fifth
line is processed, and that does two things: it changes the interpretation of
'%' from "comment" to "ignored", and it inputs the file specified in the
argument (which is normally the name of the file the command is in). It is this
second time that the file is being read that the comments and code in it are
typeset.
The function of the \iffalse ... \fi is to skip lines two to seven on this
second time through; this is similar to the "if 0 { ... }" idiom for block
comments in Tcl code, and it is needed here because (amongst other things) the
\documentclass command may only be executed once. The function of the <driver>
guards is to prevent this short piece of LaTeX code from being extracted by
__docstrip__. The total effect is that the file can function both as a LaTeX
document and as a __docstrip__ master source code file.
It is not necessary to use the tclldoc document class, but that does provide a
number of features that are convenient for ".dtx" files containing Tcl code.
More information on this matter can be found in the references above.
# <a name='see-also'></a>SEE ALSO
[docstrip_util](docstrip_util.md)
# <a name='keywords'></a>KEYWORDS
[.dtx](../../../../index.md#_dtx), [LaTeX](../../../../index.md#latex),
[docstrip](../../../../index.md#docstrip),
[documentation](../../../../index.md#documentation), [literate
programming](../../../../index.md#literate_programming),
[source](../../../../index.md#source)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003–2010 Lars Hellström <Lars dot Hellstrom at residenset dot net>
|
Added embedded/md/tcllib/files/modules/docstrip/docstrip_util.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
|
[//000000001]: # (docstrip_util - Literate programming tool)
[//000000002]: # (Generated from file 'docstrip_util.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docstrip_util(n) 1.3.1 tcllib "Literate programming tool")
# NAME
docstrip_util - Docstrip-related utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Package indexing commands](#section2)
- [Source processing commands](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require docstrip ?1.2?
package require docstrip::util ?1.3.1?
[__pkgProvide__ *name* *version* *terminals*](#1)
[__pkgIndex__ ?*terminal* ...?](#2)
[__fileoptions__ ?*option* *value* ...?](#3)
[__docstrip::util::index_from_catalogue__ *dir* *pattern* ?*option* *value* ...?](#4)
[__docstrip::util::modules_from_catalogue__ *target* *source* ?*option* *value* ...?](#5)
[__docstrip::util::classical_preamble__ *metaprefix* *message* *target* ?*source* *terminals* ...?](#6)
[__docstrip::util::classical_postamble__ *metaprefix* *message* *target* ?*source* *terminals* ...?](#7)
[__docstrip::util::packages_provided__ *text* ?*setup-script*?](#8)
[__docstrip::util::ddt2man__ *text*](#9)
[__docstrip::util::guards__ *subcmd* *text*](#10)
[__docstrip::util::patch__ *source-var* *terminals* *fromtext* *diff* ?*option* *value* ...?](#11)
[__docstrip::util::thefile__ *filename* ?*option* *value* ...?](#12)
[__docstrip::util::import_unidiff__ *diff-text* ?*warning-var*?](#13)
# <a name='description'></a>DESCRIPTION
The __docstrip::util__ package is meant for collecting various utility
procedures that are mainly useful at installation or development time. It is
separate from the base package to avoid overhead when the latter is used to
__[source](../../../../index.md#source)__ code.
# <a name='section2'></a>Package indexing commands
Like raw ".tcl" files, code lines in docstrip source files can be searched for
package declarations and corresponding indices constructed. A complication is
however that one cannot tell from the code blocks themselves which will fit
together to make a working package; normally that information would be found in
an accompanying ".ins" file, but parsing one of those is not an easy task.
Therefore __docstrip::util__ introduces an alternative encoding of such
information, in the form of a declarative Tcl script: the
*[catalogue](../../../../index.md#catalogue)* (of the contents in a source
file).
The special commands which are available inside a catalogue are:
- <a name='1'></a>__pkgProvide__ *name* *version* *terminals*
Declares that the code for a package with name *name* and version *version*
is made up from those modules in the source file which are selected by the
*terminals* list of guard expression terminals. This code should preferably
not contain a __[package](../../../../index.md#package)__ __provide__
command for the package, as one will be provided by the package loading
mechanisms.
- <a name='2'></a>__pkgIndex__ ?*terminal* ...?
Declares that the code for a package is made up from those modules in the
source file which are selected by the listed guard expression *terminal*s.
The name and version of this package is determined from
__[package](../../../../index.md#package)__ __provide__ command(s) found in
that code (hence there must be such a command in there).
- <a name='3'></a>__fileoptions__ ?*option* *value* ...?
Declares the __fconfigure__ options that should be in force when reading the
source; this can usually be ignored for pure ASCII files, but if the file
needs to be interpreted according to some other __-encoding__ then this is
how to specify it. The command should normally appear first in the
catalogue, as it takes effect only for commands following it.
Other Tcl commands are supported too — a catalogue is parsed by being evaluated
in a safe interpreter — but they are rarely needed. To allow for future
extensions, unknown commands in the catalogue are silently ignored.
To simplify distribution of catalogues together with their source files, the
catalogue is stored *in the source file itself* as a module selected by the
terminal '__docstrip.tcl::catalogue__'. This supports both the style of
collecting all catalogue lines in one place and the style of putting each
catalogue line in close proximity of the code that it declares.
Putting catalogue entries next to the code they declare may look as follows
% First there's the catalogue entry
% \begin{tcl}
%<docstrip.tcl::catalogue>pkgProvide foo::bar 1.0 {foobar load}
% \end{tcl}
% second a metacomment used to include a copyright message
% \begin{macrocode}
%<*foobar>
%% This file is placed in the public domain.
% \end{macrocode}
% third the package implementation
% \begin{tcl}
namespace eval foo::bar {
# ... some clever piece of Tcl code elided ...
% \end{tcl}
% which at some point may have variant code to make use of a
% |load|able extension
% \begin{tcl}
%<*load>
load [file rootname [info script]][info sharedlibextension]
%</load>
%<*!load>
# ... even more clever scripted counterpart of the extension
# also elided ...
%</!load>
}
%</foobar>
% \end{tcl}
% and that's it!
The corresponding set-up with __pkgIndex__ would be
% First there's the catalogue entry
% \begin{tcl}
%<docstrip.tcl::catalogue>pkgIndex foobar load
% \end{tcl}
% second a metacomment used to include a copyright message
% \begin{tcl}
%<*foobar>
%% This file is placed in the public domain.
% \end{tcl}
% third the package implementation
% \begin{tcl}
package provide foo::bar 1.0
namespace eval foo::bar {
# ... some clever piece of Tcl code elided ...
% \end{tcl}
% which at some point may have variant code to make use of a
% |load|able extension
% \begin{tcl}
%<*load>
load [file rootname [info script]][info sharedlibextension]
%</load>
%<*!load>
# ... even more clever scripted counterpart of the extension
# also elided ...
%</!load>
}
%</foobar>
% \end{tcl}
% and that's it!
- <a name='4'></a>__docstrip::util::index_from_catalogue__ *dir* *pattern* ?*option* *value* ...?
This command is a sibling of the standard __pkg_mkIndex__ command, in that
it adds package entries to "pkgIndex.tcl" files. The difference is that it
indexes __[docstrip](docstrip.md)__-style source files rather than raw
".tcl" or loadable library files. Only packages listed in the catalogue of a
file are considered.
The *dir* argument is the directory in which to look for files (and whose
"pkgIndex.tcl" file should be amended). The *pattern* argument is a __glob__
pattern of files to look into; a typical value would be __*.dtx__ or
__*.{dtx,ddt}__. Remaining arguments are option-value pairs, where the
supported options are:
* __-recursein__ *dirpattern*
If this option is given, then the __index_from_catalogue__ operation
will be repeated in each subdirectory whose name matches the
*dirpattern*. __-recursein__ __*__ will cause the entire subtree rooted
at *dir* to be indexed.
* __-sourceconf__ *dictionary*
Specify __fileoptions__ to use when reading the catalogues of files (and
also for reading the packages if the catalogue does not contain a
__fileoptions__ command). Defaults to being empty. Primarily useful if
your system encoding is very different from that of the source file
(e.g., one is a two-byte encoding and the other is a one-byte encoding).
__ascii__ and __utf-8__ are not very different in that sense.
* __-options__ *terminals*
The *terminals* is a list of terminals in addition to
__docstrip.tcl::catalogue__ that should be held as true when extracting
the catalogue. Defaults to being empty. This makes it possible to make
use of "variant sections" in the catalogue itself, e.g. gaurd some
entries with an extra "experimental" and thus prevent them from
appearing in the index unless that is generated with "experimental"
among the __-options__.
* __-report__ *boolean*
If the *boolean* is true then the return value will be a textual,
probably multiline, report on what was done. Defaults to false, in which
case there is no particular return value.
* __-reportcmd__ *commandPrefix*
Every item in the report is handed as an extra argument to the command
prefix. Since __index_from_catalogue__ would typically be used at a
rather high level in installation scripts and the like, the
*commandPrefix* defaults to "__puts__ __stdout__". Use
__[list](../../../../index.md#list)__ to effectively disable this
feature. The return values from the prefix are ignored.
The __package ifneeded__ scripts that are generated contain one __package
require docstrip__ command and one __docstrip::sourcefrom__ command. If the
catalogue entry was of the __pkgProvide__ kind then the __package ifneeded__
script also contains the __package provide__ command.
Note that __index_from_catalogue__ never removes anything from an existing
"pkgIndex.tcl" file. Hence you may need to delete it (or have
__pkg_mkIndex__ recreate it from scratch) before running
__index_from_catalogue__ to update some piece of information, such as a
package version number.
- <a name='5'></a>__docstrip::util::modules_from_catalogue__ *target* *source* ?*option* *value* ...?
This command is an alternative to __index_from_catalogue__ which creates Tcl
Module (".tm") files rather than "pkgIndex.tcl" entries. Since this action
is more similar to what __[docstrip](docstrip.md)__ classically does, it has
features for putting pre- and postambles on the generated files.
The *source* argument is the name of the source file to generate ".tm" files
from. The *target* argument is the directory which should count as a module
path, i.e., this is what the relative paths derived from package names are
joined to. The supported options are:
* __-preamble__ *message*
A message to put in the preamble (initial block of comments) of
generated files. Defaults to a space. May be several lines, which are
then separated by newlines. Traditionally used for copyright notices or
the like, but metacomment lines provide an alternative to that.
* __-postamble__ *message*
Like __-preamble__, but the message is put at the end of the file
instead of the beginning. Defaults to being empty.
* __-sourceconf__ *dictionary*
Specify __fileoptions__ to use when reading the catalogue of the
*source* (and also for reading the packages if the catalogue does not
contain a __fileoptions__ command). Defaults to being empty. Primarily
useful if your system encoding is very different from that of the source
file (e.g., one is a two-byte encoding and the other is a one-byte
encoding). __ascii__ and __utf-8__ are not very different in that sense.
* __-options__ *terminals*
The *terminals* is a list of terminals in addition to
__docstrip.tcl::catalogue__ that should be held as true when extracting
the catalogue. Defaults to being empty. This makes it possible to make
use of "variant sections" in the catalogue itself, e.g. gaurd some
entries with an extra "experimental" guard and thus prevent them from
contributing packages unless those are generated with "experimental"
among the __-options__.
* __-formatpreamble__ *commandPrefix*
Command prefix used to actually format the preamble. Takes four
additional arguments *message*, *targetFilename*, *sourceFilename*, and
*terminalList* and returns a fully formatted preamble. Defaults to using
__classical_preamble__ with a *metaprefix* of '##'.
* __-formatpostamble__ *commandPrefix*
Command prefix used to actually format the postamble. Takes four
additional arguments *message*, *targetFilename*, *sourceFilename*, and
*terminalList* and returns a fully formatted postamble. Defaults to
using __classical_postamble__ with a *metaprefix* of '##'.
* __-report__ *boolean*
If the *boolean* is true (which is the default) then the return value
will be a textual, probably multiline, report on what was done. If it is
false then there is no particular return value.
* __-reportcmd__ *commandPrefix*
Every item in the report is handed as an extra argument to this command
prefix. Defaults to __[list](../../../../index.md#list)__, which
effectively disables this feature. The return values from the prefix are
ignored. Use for example "__puts__ __stdout__" to get report items
written immediately to the terminal.
An existing file of the same name as one to be created will be overwritten.
- <a name='6'></a>__docstrip::util::classical_preamble__ *metaprefix* *message* *target* ?*source* *terminals* ...?
This command returns a preamble in the classical __[docstrip](docstrip.md)__
style
##
## This is `TARGET',
## generated by the docstrip::util package.
##
## The original source files were:
##
## SOURCE (with options: `foo,bar')
##
## Some message line 1
## line2
## line3
if called as
docstrip::util::classical_preamble {##}\
"\nSome message line 1\nline2\nline3" TARGET SOURCE {foo bar}
The command supports preambles for files generated from multiple sources,
even though __modules_from_catalogue__ at present does not need that.
- <a name='7'></a>__docstrip::util::classical_postamble__ *metaprefix* *message* *target* ?*source* *terminals* ...?
This command returns a postamble in the classical
__[docstrip](docstrip.md)__ style
## Some message line 1
## line2
## line3
##
## End of file `TARGET'.
if called as
docstrip::util::classical_postamble {##}\
"Some message line 1\nline2\nline3" TARGET SOURCE {foo bar}
In other words, the *source* and *terminals* arguments are ignored, but
supported for symmetry with __classical_preamble__.
- <a name='8'></a>__docstrip::util::packages_provided__ *text* ?*setup-script*?
This command returns a list where every even index element is the name of a
package __provide__d by *text* when that is evaluated as a Tcl script, and
the following odd index element is the corresponding version. It is used to
do package indexing of extracted pieces of code, in the manner of
__pkg_mkIndex__.
One difference to __pkg_mkIndex__ is that the *text* gets evaluated in a
safe interpreter. __package require__ commands are silently ignored, as are
unknown commands (which includes __[source](../../../../index.md#source)__
and __load__). Other errors cause processing of the *text* to stop, in which
case only those package declarations that had been encountered before the
error will be included in the return value.
The *setup-script* argument can be used to customise the evaluation
environment, if the code in *text* has some very special needs. The
*setup-script* is evaluated in the local context of the
__packages_provided__ procedure just before the *text* is processed. At that
time, the name of the slave command for the safe interpreter that will do
this processing is kept in the local variable __c__. To for example copy the
contents of the __::env__ array to the safe interpreter, one might use a
*setup-script* of
$c eval [list array set env [array get ::env]]
# <a name='section3'></a>Source processing commands
Unlike the previous group of commands, which would use __docstrip::extract__ to
extract some code lines and then process those further, the following commands
operate on text consisting of all types of lines.
- <a name='9'></a>__docstrip::util::ddt2man__ *text*
The __ddt2man__ command reformats *text* from the general
__[docstrip](docstrip.md)__ format to
__[doctools](../doctools/doctools.md)__ ".man" format (Tcl Markup Language
for Manpages). The different line types are treated as follows:
* comment and metacomment lines
The '%' and '%%' prefixes are removed, the rest of the text is kept as
it is.
* empty lines
These are kept as they are. (Effectively this means that they will count
as comment lines after a comment line and as code lines after a code
line.)
* code lines
__example_begin__ and __example_end__ commands are placed at the
beginning and end of every block of consecutive code lines. Brackets in
a code line are converted to __lb__ and __rb__ commands.
* verbatim guards
These are processed as usual, so they do not show up in the result but
every line in a verbatim block is treated as a code line.
* other guards
These are treated as code lines, except that the actual guard is
__emph__asised.
At the time of writing, no project has employed
__[doctools](../doctools/doctools.md)__ markup in master source files, so
experience of what works well is not available. A source file could however
look as follows
% [manpage_begin gcd n 1.0]
% [keywords divisor]
% [keywords math]
% [moddesc {Greatest Common Divisor}]
% [require gcd [opt 1.0]]
% [description]
%
% [list_begin definitions]
% [call [cmd gcd] [arg a] [arg b]]
% The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which
% must be integers and returns their greatest common divisor.
proc gcd {a b} {
% The first step is to take the absolute values of the arguments.
% This relieves us of having to worry about how signs will be treated
% by the remainder operation.
set a [expr {abs($a)}]
set b [expr {abs($b)}]
% The next line does all of Euclid's algorithm! We can make do
% without a temporary variable, since $a is substituted before the
% [lb]set a $b[rb] and thus continues to hold a reference to the
% "old" value of [var a].
while {$b>0} { set b [expr { $a % [set a $b] }] }
% In Tcl 8.3 we might want to use [cmd set] instead of [cmd return]
% to get the slight advantage of byte-compilation.
%<tcl83> set a
%<!tcl83> return $a
}
% [list_end]
%
% [manpage_end]
If the above text is fed through __docstrip::util::ddt2man__ then the result
will be a syntactically correct __[doctools](../doctools/doctools.md)__
manpage, even though its purpose is a bit different.
It is suggested that master source code files with
__[doctools](../doctools/doctools.md)__ markup are given the suffix ".ddt",
hence the "ddt" in __ddt2man__.
- <a name='10'></a>__docstrip::util::guards__ *subcmd* *text*
The __guards__ command returns information (mostly of a statistical nature)
about the ordinary docstrip guards that occur in the *text*. The *subcmd*
selects what is returned.
* __counts__
List the guard expression terminals with counts. The format of the
return value is a dictionary which maps the terminal name to the number
of occurencies of it in the file.
* __exprcount__
List the guard expressions with counts. The format of the return value
is a dictionary which maps the expression to the number of occurencies
of it in the file.
* __exprerr__
List the syntactically incorrect guard expressions (e.g. parentheses do
not match, or a terminal is missing). The return value is a list, with
the elements in no particular order.
* __expressions__
List the guard expressions. The return value is a list, with the
elements in no particular order.
* __exprmods__
List the guard expressions with modifiers. The format of the return
value is a dictionary where each index is a guard expression and each
entry is a string with one character for every guard line that has this
expression. The characters in the entry specify what modifier was used
in that line: +, -, *, /, or (for guard without modifier:) space. This
is the most primitive form of the information gathered by __guards__.
* __names__
List the guard expression terminals. The return value is a list, with
the elements in no particular order.
* __rotten__
List the malformed guard lines (this does not include lines where only
the expression is malformed, though). The format of the return value is
a dictionary which maps line numbers to their contents.
- <a name='11'></a>__docstrip::util::patch__ *source-var* *terminals* *fromtext* *diff* ?*option* *value* ...?
This command tries to apply a __[diff](../../../../index.md#diff)__ file
(for example a contributed patch) that was computed for a generated file to
the __[docstrip](docstrip.md)__ source. This can be useful if someone has
edited a generated file, thus mistaking it for being the source. This
command makes no presumptions which are specific for the case that the
generated file is a Tcl script.
__[patch](../../../../index.md#patch)__ requires that the source file to
patch is kept as a list of lines in a variable, and the name of that
variable in the calling context is what goes into the *source-var* argument.
The *terminals* is the list of terminals used to extract the file that has
been patched. The *diff* is the actual diff to apply (in a format as
explained below) and the *fromtext* is the contents of the file which served
as "from" when the diff was computed. Options can be used to further control
the process.
The process works by "lifting" the hunks in the *diff* from generated to
source file, and then applying them to the elements of the *source-var*. In
order to do this lifting, it is necessary to determine how lines in the
*fromtext* correspond to elements of the *source-var*, and that is where the
*terminals* come in; the source is first __extract__ed under the given
*terminals*, and the result of that is then matched against the *fromtext*.
This produces a map which translates line numbers stated in the *diff* to
element numbers in *source-var*, which is what is needed to lift the hunks.
The reason that both the *terminals* and the *fromtext* must be given is
twofold. First, it is very difficult to keep track of how many lines of
preamble are supplied some other way than by copying lines from source
files. Second, a generated file might contain material from several source
files. Both make it impossible to predict what line number an extracted file
would have in the generated file, so instead the algorithm for computing the
line number map looks for a block of lines in the *fromtext* which matches
what can be extracted from the source. This matching is affected by the
following options:
* __-matching__ *mode*
How equal must two lines be in order to match? The supported *mode*s
are:
+ __exact__
Lines must be equal as strings. This is the default.
+ __anyspace__
All sequences of whitespace characters are converted to single
spaces before comparing.
+ __nonspace__
Only non-whitespace characters are considered when comparing.
+ __none__
Any two lines are considered to be equal.
* __-metaprefix__ *string*
The __-metaprefix__ value to use when extracting. Defaults to "%%", but
for Tcl code it is more likely that "#" or "##" had been used for the
generated file.
* __-trimlines__ *boolean*
The __-trimlines__ value to use when extracting. Defaults to true.
The return value is in the form of a unified diff, containing only those
hunks which were not applied or were only partially applied; a comment in
the header of each hunk specifies which case is at hand. It is normally
necessary to manually review both the return value from
__[patch](../../../../index.md#patch)__ and the patched text itself, as this
command cannot adjust comment lines to match new content.
An example use would look like
set sourceL [split [docstrip::util::thefile from.dtx] \n]
set terminals {foo bar baz}
set fromtext [docstrip::util::thefile from.tcl]
set difftext [exec diff --unified from.tcl to.tcl]
set leftover [docstrip::util::patch sourceL $terminals $fromtext\
[docstrip::util::import_unidiff $difftext] -metaprefix {#}]
set F [open to.dtx w]; puts $F [join $sourceL \n]; close $F
return $leftover
Here, "from.dtx" was used as source for "from.tcl", which someone modified
into "to.tcl". We're trying to construct a "to.dtx" which can be used as
source for "to.tcl".
- <a name='12'></a>__docstrip::util::thefile__ *filename* ?*option* *value* ...?
The __thefile__ command opens the file *filename*, reads it to end, closes
it, and returns the contents (dropping a final newline if there is one). The
option-value pairs are passed on to __fconfigure__ to configure the open
file channel before anything is read from it.
- <a name='13'></a>__docstrip::util::import_unidiff__ *diff-text* ?*warning-var*?
This command parses a unified (__[diff](../../../../index.md#diff)__ flags
__-U__ and __--unified__) format diff into the list-of-hunks format expected
by __docstrip::util::patch__. The *diff-text* argument is the text to parse
and the *warning-var* is, if specified, the name in the calling context of a
variable to which any warnings about parsing problems will be __append__ed.
The return value is a list of *hunks*. Each hunk is a list of five elements
"*start1* *end1* *start2* *end2* *lines*". *start1* and *end1* are line
numbers in the "from" file of the first and last respectively lines of the
hunk. *start2* and *end2* are the corresponding line numbers in the "to"
file. Line numbers start at 1. The *lines* is a list with two elements for
each line in the hunk; the first specifies the type of a line and the second
is the actual line contents. The type is __-__ for lines only in the "from"
file, __+__ for lines that are only in the "to" file, and __0__ for lines
that are in both.
# <a name='see-also'></a>SEE ALSO
[docstrip](docstrip.md), [doctools](../doctools/doctools.md), doctools_fmt
# <a name='keywords'></a>KEYWORDS
[.ddt](../../../../index.md#_ddt), [.dtx](../../../../index.md#_dtx),
[LaTeX](../../../../index.md#latex), [Tcl
module](../../../../index.md#tcl_module),
[catalogue](../../../../index.md#catalogue), [diff](../../../../index.md#diff),
[docstrip](../../../../index.md#docstrip),
[doctools](../../../../index.md#doctools),
[documentation](../../../../index.md#documentation), [literate
programming](../../../../index.md#literate_programming),
[module](../../../../index.md#module), [package
indexing](../../../../index.md#package_indexing),
[patch](../../../../index.md#patch), [source](../../../../index.md#source)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003–2010 Lars Hellström <Lars dot Hellstrom at residenset dot net>
|
Added embedded/md/tcllib/files/modules/doctools/changelog.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
[//000000001]: # (doctools::changelog - Documentation tools)
[//000000002]: # (Generated from file 'changelog.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::changelog(n) 1.1 tcllib "Documentation tools")
# NAME
doctools::changelog - Processing text in Emacs ChangeLog format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil
package require doctools::changelog ?1.1?
[__::doctools::changelog::scan__ *text*](#1)
[__::doctools::changelog::flatten__ *entries*](#2)
[__::doctools::changelog::toDoctools__ *title* *module* *version* *entries*](#3)
[__::doctools::changelog::merge__ *entries*...](#4)
# <a name='description'></a>DESCRIPTION
This package provides Tcl commands for the processing and reformatting of text
in the "ChangeLog" format generated by __[emacs](../../../../index.md#emacs)__.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::changelog::scan__ *text*
The command takes the *text* and parses it under the assumption that it
contains a ChangeLog as generated by
__[emacs](../../../../index.md#emacs)__. It returns a data structure
describing the contents of this ChangeLog.
This data structure is a list where each element describes one entry in the
ChangeLog. Each element/entry is then a list of three elements describing
the date of the entry, its author, and the comments made, in this order. The
last item in each element/entry, the comments, is a list of sections. Each
section is described by a list containing two elements, a list of file
names, and a string containing the true comment associated with the files of
the section.
{
{
date
author
{
{
{file ...}
commenttext
}
...
}
}
{...}
}
- <a name='2'></a>__::doctools::changelog::flatten__ *entries*
This command converts a list of entries as generated by __change::scan__
above into a simpler list of plain text blocks each containing all the
information of a single entry.
- <a name='3'></a>__::doctools::changelog::toDoctools__ *title* *module* *version* *entries*
This command converts the pre-parsed ChangeLog *entries* as generated by the
command __::doctools::changelog::scan__ into a document in
*[doctools](../../../../index.md#doctools)* format and returns it as the
result of the command.
The other three arguments supply the information for the header of that
document which is not available from the changelog itself.
- <a name='4'></a>__::doctools::changelog::merge__ *entries*...
Each argument of the command is assumed to be a pre-parsed Changelog as
generated by the command __::doctools::changelog::scan__. This command
merges all of them into a single structure, and collapses multiple entries
for the same date and author into a single entry. The new structure is
returned as the result of the command.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[changelog](../../../../index.md#changelog),
[doctools](../../../../index.md#doctools), [emacs](../../../../index.md#emacs)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2013 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/cvs.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
[//000000001]: # (doctools::cvs - Documentation tools)
[//000000002]: # (Generated from file 'cvs.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::cvs(n) 1 tcllib "Documentation tools")
# NAME
doctools::cvs - Processing text in 'cvs log' format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil
package require doctools::cvs ?1?
[__::doctools::cvs::scanLog__ *text* *evar* *cvar* *fvar*](#1)
[__::doctools::cvs::toChangeLog__ *evar* *cvar* *fvar*](#2)
# <a name='description'></a>DESCRIPTION
This package provides Tcl commands for the processing and reformatting text in
the format generated by the __[cvs log](../../../../index.md#cvs_log)__ command.
The commands __::doctools::cvs::scanLog__ and __::doctools::cvs::toChangeLog__
are derived from code found on the [Tcl'ers Wiki](http://wiki.tcl.tk). See the
references at the end of the page.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::cvs::scanLog__ *text* *evar* *cvar* *fvar*
The command takes the *text* and parses it under the assumption that it
contains a CVS log as generated by __[cvs
log](../../../../index.md#cvs_log)__. The resulting information is stored in
the variables whose names were specified via *evar*, *cvar*, and *fvar*.
Already existing information in the referenced variables is preserved,
allowing the caller to merge data from multiple logs into one database.
* varname *evar* (in)
Has to refer to a scalar variable. After the call this variable will
contain a list of all the entries found in the log file. An entry is
identified through the combination of date and author, and can be split
over multiple physical entries, one per touched file.
It should be noted that the entries are listed in the same order as they
were found in the *text*. This is not necessarily sorted by date or
author.
Each item in the list is a list containing two elements, the date of the
entry, and its author, in this order. The date is formatted as
__year__/__month__/__day__.
* varname *cvar* (in)
Has to refer to an array variable. Keys are strings containing the date
and author of log entries, in this order, separated by a comma.
The values are lists of comments made for the entry.
* varname *fvar* (in)
Has to refer to an array variable. Keys are strings containing date,
author of a log entry, and a comment for that entry, in this order,
separated by commas.
The values are lists of the files the entry is touching.
- <a name='2'></a>__::doctools::cvs::toChangeLog__ *evar* *cvar* *fvar*
The three arguments for this command are the same as the last three
arguments of the command __::doctools::cvs::scanLog__. This command however
expects them to be filled with information about one or more logs. It takes
this information and converts it into a text in the format of a ChangeLog as
accepted and generated by __[emacs](../../../../index.md#emacs)__. The
constructed text is returned as the result of the command.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[uri, http://wiki.tcl.tk/log2changelog
# <a name='keywords'></a>KEYWORDS
[changelog](../../../../index.md#changelog), [cvs](../../../../index.md#cvs),
[cvs log](../../../../index.md#cvs_log), [emacs](../../../../index.md#emacs),
[log](../../../../index.md#log)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
|
[//000000001]: # (doctools::idx - Documentation tools)
[//000000002]: # (Generated from file 'docidx.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx(n) 1.0.8 tcllib "Documentation tools")
# NAME
doctools::idx - docidx - Processing indices
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [PACKAGE COMMANDS](#subsection1)
- [OBJECT COMMAND](#subsection2)
- [OBJECT METHODS](#subsection3)
- [OBJECT CONFIGURATION](#subsection4)
- [FORMAT MAPPING](#subsection5)
- [PREDEFINED ENGINES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require doctools::idx ?1.0.8?
[__::doctools::idx::new__ *objectName* ?__-option__ *value* ...?](#1)
[__::doctools::idx::help__](#2)
[__::doctools::idx::search__ *path*](#3)
[__objectName__ __method__ ?*arg arg ...*?](#4)
[*objectName* __configure__](#5)
[*objectName* __configure__ *option*](#6)
[*objectName* __configure__ __-option__ *value*...](#7)
[*objectName* __cget__ __-option__](#8)
[*objectName* __destroy__](#9)
[*objectName* __format__ *text*](#10)
[*objectName* __map__ *symbolic* *actual*](#11)
[*objectName* __parameters__](#12)
[*objectName* __search__ *path*](#13)
[*objectName* __setparam__ *name* *value*](#14)
[*objectName* __warnings__](#15)
# <a name='description'></a>DESCRIPTION
This package provides a class for the creation of objects able to process and
convert text written in the *[docidx](../../../../index.md#docidx)* markup
language into any output format X for which a *[formatting
engine](../../../../index.md#formatting_engine)* is available.
A reader interested in the markup language itself should start with the *[docidx
language introduction](docidx_lang_intro.md)* and proceed from there to the
formal specifications, i.e. the *[docidx language
syntax](docidx_lang_syntax.md)* and the *[docidx language command
reference](docidx_lang_cmdref.md)*.
If on the other hand the reader wishes to write her own formatting engine for
some format, i.e. is a *plugin writer* then reading and understanding the
*[docidx plugin API reference](docidx_plugin_apiref.md)* is an absolute
necessity, as that document specifies the interaction between this package and
its plugins, i.e. the formatting engines, in detail.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>PACKAGE COMMANDS
- <a name='1'></a>__::doctools::idx::new__ *objectName* ?__-option__ *value* ...?
This command creates a new docidx object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [OBJECT
COMMAND](#subsection2) and [OBJECT METHODS](#subsection3). The object
command will be created under the current namespace if the *objectName* is
not fully qualified, and in the specified namespace otherwise.
The options and their values coming after the name of the object are used to
set the initial configuration of the object.
- <a name='2'></a>__::doctools::idx::help__
This is a convenience command for applications wishing to provide their user
with a short description of the available formatting commands and their
meanings. It returns a string containing a standard help text.
- <a name='3'></a>__::doctools::idx::search__ *path*
Whenever an object created by this the package has to map the name of a
format to the file containing the code for its formatting engine it will
search for the file in a number of directories stored in a list. See section
[FORMAT MAPPING](#subsection5) for more explanations.
This list not only contains three default directories which are declared by
the package itself, but is also extensible user of the package. This command
is the means to do so. When given a *path* to an existing and readable
directory it will prepend that directory to the list of directories to
search. This means that the *path* added last is later searched through
first.
An error will be thrown if the *path* either does not exist, is not a
directory, or is not readable.
## <a name='subsection2'></a>OBJECT COMMAND
All commands created by __::doctools::idx::new__ have the following general form
and may be used to invoke various operations on their docidx converter object.
- <a name='4'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [OBJECT METHODS](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>OBJECT METHODS
- <a name='5'></a>*objectName* __configure__
The method returns a list of all known options and their current values when
called without any arguments.
- <a name='6'></a>*objectName* __configure__ *option*
The method behaves like the method __cget__ when called with a single
argument and returns the value of the option specified by said argument.
- <a name='7'></a>*objectName* __configure__ __-option__ *value*...
The method reconfigures the specified __option__s of the object, setting
them to the associated *value*s, when called with an even number of
arguments, at least two.
The legal options are described in the section [OBJECT
CONFIGURATION](#subsection4).
- <a name='8'></a>*objectName* __cget__ __-option__
This method expects a legal configuration option as argument and will return
the current value of that option for the object the method was invoked for.
The legal configuration options are described in section [OBJECT
CONFIGURATION](#subsection4).
- <a name='9'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='10'></a>*objectName* __format__ *text*
This method runs the *text* through the configured formatting engine and
returns the generated string as its result. An error will be thrown if no
__-format__ was configured for the object.
The method assumes that the *text* is in
*[docidx](../../../../index.md#docidx)* format as specified in the companion
document *docidx_fmt*. Errors will be thrown otherwise.
- <a name='11'></a>*objectName* __map__ *symbolic* *actual*
This methods add one entry to the per-object mapping from *symbolic*
filenames to the *actual* uris. The object just stores this mapping and
makes it available to the configured formatting engine through the command
__dt_fmap__. This command is described in more detail in the *[docidx plugin
API reference](docidx_plugin_apiref.md)* which specifies the interaction
between the objects created by this package and index formatting engines.
- <a name='12'></a>*objectName* __parameters__
This method returns a list containing the names of all engine parameters
provided by the configured formatting engine. It will return an empty list
if the object is not yet configured for a specific format.
- <a name='13'></a>*objectName* __search__ *path*
This method extends the per-object list of paths searched for index
formatting engines. See also the command __::doctools::idx::search__ on how
to extend the per-package list of paths. Note that the path entered last
will be searched first. For more details see section [FORMAT
MAPPING](#subsection5).
- <a name='14'></a>*objectName* __setparam__ *name* *value*
This method sets the *name*d engine parameter to the specified *value*. It
will throw an error if the object is either not yet configured for a
specific format, or if the formatting engine for the configured format does
not provide a parameter with the given *name*. The list of parameters
provided by the configured formatting engine can be retrieved through the
method __parameters__.
- <a name='15'></a>*objectName* __warnings__
This method returns a list containing all the warnings which were generated
by the configured formatting engine during the last invocation of the method
__format__.
## <a name='subsection4'></a>OBJECT CONFIGURATION
All docidx objects understand the following configuration options:
- __-file__ *file*
The argument of this option is stored in the object and made available to
the configured formatting engine through the command __dt_file__. This
command is described in more detail in the companion document *docidx_api*
which specifies the API between the object and formatting engines.
The default value of this option is the empty string.
The configured formatting engine should interpret the value as the name of
the file containing the document which is currently processed.
- __-format__ *text*
The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the method
__format__. Its default value is the empty string. The method __format__
cannot be used if this option is not set to a valid value at least once.
The package will immediately try to map the given name to a file containing
the code for a formatting engine generating that format. An error will be
thrown if this mapping fails. In that case a previously configured format is
left untouched.
The section [FORMAT MAPPING](#subsection5) explains in detail how the
package and object will look for engine implementations.
## <a name='subsection5'></a>FORMAT MAPPING
The package and object will perform the following algorithm when trying to map a
format name *foo* to a file containing an implementation of a formatting engine
for *foo*:
1. If *foo* is the name of an existing file then this file is directly taken
as the implementation.
1. If not, the list of per-object search paths is searched. For each directory
in the list the package checks if that directory contains a file
"idx.*foo*". If yes, then that file is taken as the implementation.
Note that this list of paths is initially empty and can be extended through
the object method __search__.
1. If not, the list of package paths is searched. For each directory in the
list the package checks if that directory contains a file "idx.*foo*". If
yes, then that file is taken as the implementation.
This list of paths can be extended through the command
__::doctools::idx::search__. It contains initially one path, the
subdirectory "mpformats" of the directory the package itself is located in.
In other words, if the package implementation "docidx.tcl" is installed in
the directory "/usr/local/lib/tcllib/doctools" then it will by default
search the directory "/usr/local/lib/tcllib/doctools/mpformats" for format
implementations.
1. The mapping fails.
# <a name='section3'></a>PREDEFINED ENGINES
The package provides predefined formatting engines for the following formats.
Some of the formatting engines support engine parameters. These will be
explicitly highlighted.
- html
This engine generates HTML markup, for processing by web browsers and the
like. This engine supports three parameters:
* footer
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the empty
string. The value is inserted into the generated output just before the
__</body>__ tag, closing the body of the generated HTML.
This can be used to insert boilerplate footer markup into the generated
document.
* header
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the empty
string. The value is inserted into the generated output just after the
__<body>__ tag, starting the body of the generated HTML.
This can be used to insert boilerplate header markup into the generated
document.
* meta
The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just after
the __<head>__ tag, starting the header section of the generated HTML.
This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.
- latex
This engine generates output suitable for the
__[latex](../../../../index.md#latex)__ text processor coming out of the TeX
world.
- list
This engine retrieves version, section and title of the manpage from the
document. As such it can be used to generate a directory listing for a set
of manpages.
- nroff
This engine generates nroff output, for processing by
__[nroff](../../../../index.md#nroff)__, or __groff__. The result will be
standard man pages as they are known in the unix world.
- null
This engine generates no outout at all. This can be used if one just wants
to validate some input.
- tmml
This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.
- wiki
This engine generates Wiki markup as understood by Jean Claude Wippler's
__wikit__ application.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [docidx_lang_cmdref](docidx_lang_cmdref.md),
[docidx_lang_intro](docidx_lang_intro.md),
[docidx_lang_syntax](docidx_lang_syntax.md),
[docidx_plugin_apiref](docidx_plugin_apiref.md)
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion),
[docidx](../../../../index.md#docidx),
[documentation](../../../../index.md#documentation),
[index](../../../../index.md#index), [keyword
index](../../../../index.md#keyword_index), [latex](../../../../index.md#latex),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[nroff](../../../../index.md#nroff), [wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2017 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
[//000000001]: # (docidx_intro - Documentation tools)
[//000000002]: # (Generated from file 'docidx_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docidx_intro(n) 1.0 tcllib "Documentation tools")
# NAME
docidx_intro - docidx introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [RELATED FORMATS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[docidx](../../../../index.md#docidx)* (short for *documentation tables of
contents*) stands for a set of related, yet different, entities which are
working together for the easy creation and transformation of keyword-based
indices for documentation. These are
1. A tcl based language for the semantic markup of a keyword index. Markup is
represented by Tcl commands.
1. A package providing the ability to read and transform texts written in that
markup language. It is important to note that the actual transformation of
the input text is delegated to plugins.
1. An API describing the interface between the package above and a plugin.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the documentation process.
1. A *writer* of documentation has to understand the markup language itself. A
beginner to docidx should read the more informally written *[docidx
language introduction](docidx_lang_intro.md)* first. Having digested this
the formal *[docidx language syntax](docidx_lang_syntax.md)* specification
should become understandable. A writer experienced with docidx may only
need the *[docidx language command reference](docidx_lang_cmdref.md)* from
time to time to refresh her memory.
While a document is written the __dtp__ application can be used to validate
it, and after completion it also performs the conversion into the chosen
system of visual markup, be it *roff, HTML, plain text, wiki, etc. The
simpler __[dtplite](../../apps/dtplite.md)__ application makes internal use
of docidx when handling directories of documentation, automatically
generating a proper keyword index for them.
1. A *processor* of documentation written in the
*[docidx](../../../../index.md#docidx)* markup language has to know which
tools are available for use.
The main tool is the aforementioned __dtp__ application provided by Tcllib.
The simpler __[dtplite](../../apps/dtplite.md)__ does not expose docidx to
the user. At the bottom level, common to both applications, however sits
the package __doctoools::idx__, providing the basic facilities to read and
process files containing text in the docidx format.
1. At last, but not least, *plugin writers* have to understand the interaction
between the __[doctools::idx](../doctools2idx/idx_container.md)__ package
and its plugins, as described in the *[docidx plugin API
reference](docidx_plugin_apiref.md)*.
# <a name='section2'></a>RELATED FORMATS
docidx does not stand alone, it has two companion formats. These are called
*[doctoc](../../../../index.md#doctoc)* and
*[doctools](../../../../index.md#doctools)*, and they are for the markup of
*tables of contents*, and general documentation, respectively. They are
described in their own sets of documents, starting at the *[doctoc
introduction](doctoc_intro.md)* and the *[doctools
introduction](doctools_intro.md)*, respectively.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_lang_cmdref](docidx_lang_cmdref.md),
[docidx_lang_faq](docidx_lang_faq.md),
[docidx_lang_intro](docidx_lang_intro.md),
[docidx_lang_syntax](docidx_lang_syntax.md),
[docidx_plugin_apiref](docidx_plugin_apiref.md),
[doctoc_intro](doctoc_intro.md),
[doctools::idx](../doctools2idx/idx_container.md),
[doctools_intro](doctools_intro.md)
# <a name='keywords'></a>KEYWORDS
[index](../../../../index.md#index), [keyword
index](../../../../index.md#keyword_index),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx_lang_cmdref.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
[//000000001]: # (docidx_lang_cmdref - Documentation tools)
[//000000002]: # (Generated from file 'docidx_lang_cmdref.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docidx_lang_cmdref(n) 1.0 tcllib "Documentation tools")
# NAME
docidx_lang_cmdref - docidx language command reference
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__[comment](../../../../index.md#comment)__ *plaintext*](#1)
[__include__ *filename*](#2)
[__index_begin__ *text* *title*](#3)
[__index_end__](#4)
[__key__ *text*](#5)
[__lb__](#6)
[__[manpage](../../../../index.md#manpage)__ *file* *text*](#7)
[__rb__](#8)
[__[url](../../../../index.md#url)__ *url* *label*](#9)
[__vset__ *varname* *value*](#10)
[__vset__ *varname*](#11)
# <a name='description'></a>DESCRIPTION
This document specifies both names and syntax of all the commands which together
are the docidx markup language, version 1. As this document is intended to be a
reference the commands are listed in alphabetical order, and the descriptions
are relatively short. A beginner should read the much more informally written
*[docidx language introduction](docidx_lang_intro.md)* first.
# <a name='section2'></a>Commands
- <a name='1'></a>__[comment](../../../../index.md#comment)__ *plaintext*
Index markup. The argument text is marked up as a comment standing outside
of the actual text of the document. Main use is in free-form text.
- <a name='2'></a>__include__ *filename*
Templating. The contents of the named file are interpreted as text written
in the docidx markup and processed in the place of the include command. The
markup in the file has to be self-contained. It is not possible for a markup
command to cross the file boundaries.
- <a name='3'></a>__index_begin__ *text* *title*
Document structure. The command to start an index. The arguments are a label
for the whole group of documents the index refers to (*text*) and the
overall title text for the index (*title*), without markup.
The label often is the name of the package (or extension) the documents
belong to.
- <a name='4'></a>__index_end__
Document structure. Command to end an index. Anything in the document coming
after this command is in error.
- <a name='5'></a>__key__ *text*
Index structure. This command adds the keyword *text* to the index.
- <a name='6'></a>__lb__
Text. The command is replaced with a left bracket. Use in free-form text.
Required to avoid interpretation of a left bracket as the start of a markup
command. Its usage is restricted to the arguments of other markup commands.
- <a name='7'></a>__[manpage](../../../../index.md#manpage)__ *file* *text*
Index structure. This command adds an element to the index which refers to a
document. The document is specified through the symbolic name *file*. The
*text* argument is used to label the reference.
Symbolic names are used to preserve the convertibility of this format to any
output format. The actual name of the file will be inserted by the chosen
formatting engine when converting the input. This will be based on a mapping
from symbolic to actual names given to the engine.
- <a name='8'></a>__rb__
Text. The command is replaced with a right bracket. Use in free-form text.
Required to avoid interpretation of a right bracket as the end of a markup
command. Its usage is restricted to the arguments of other commands.
- <a name='9'></a>__[url](../../../../index.md#url)__ *url* *label*
Index structure. This is the second command to add an element to the index.
To refer to a document it is not using a symbolic name however, but a
(possibly format-specific) url describing the exact location of the document
indexed here.
- <a name='10'></a>__vset__ *varname* *value*
Templating. In this form the command sets the named document variable to the
specified *value*. It does not generate output. I.e. the command is replaced
by the empty string.
- <a name='11'></a>__vset__ *varname*
Templating. In this form the command is replaced by the value of the named
document variable
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [docidx_lang_faq](docidx_lang_faq.md),
[docidx_lang_intro](docidx_lang_intro.md),
[docidx_lang_syntax](docidx_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[docidx commands](../../../../index.md#docidx_commands), [docidx
language](../../../../index.md#docidx_language), [docidx
markup](../../../../index.md#docidx_markup),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx_lang_faq.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
[//000000001]: # (docidx_lang_faq - Documentation tools)
[//000000002]: # (Generated from file 'docidx_lang_faq.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docidx_lang_faq(n) 1.0 tcllib "Documentation tools")
# NAME
docidx_lang_faq - docidx language faq
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [OVERVIEW](#section2)
- [What is this document?](#subsection1)
- [EXAMPLES](#section3)
- [Where do I find docidx examples?](#subsection2)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>OVERVIEW
## <a name='subsection1'></a>What is this document?
This document is currently mainly a placeholder, to be filled with commonly
asked questions about the docidx markup language and companions, and their
answers.
Please report any questions (and, if possible, answers) we should consider for
this document as explained in the section [Bugs, Ideas, Feedback](#section4)
below.
# <a name='section3'></a>EXAMPLES
## <a name='subsection2'></a>Where do I find docidx examples?
We have no direct examples of documents written using docidx markup. However the
doctools processor __[dtplite](../../apps/dtplite.md)__ does generate a table of
contents when processing a set of documents written in doctools markup. The
intermediate file for it uses docidx markup and is not deleted when generation
completes. Such files can therefore serve as examples.
__[dtplite](../../apps/dtplite.md)__ is distributed as part of Tcllib, so to get
it you need one of
1. A snapshot of Tcllib. How to retrieve such a snapshot and the tools
required for this are described at [Development
Snapshots](/wiki?name=Development+Snapshots)
1. A Tcllib release archive. They are available at the [home](/home) page.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_lang_cmdref](docidx_lang_cmdref.md),
[docidx_lang_intro](docidx_lang_intro.md),
[docidx_lang_syntax](docidx_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[docidx commands](../../../../index.md#docidx_commands), [docidx
language](../../../../index.md#docidx_language), [docidx
markup](../../../../index.md#docidx_markup), [docidx
syntax](../../../../index.md#docidx_syntax),
[examples](../../../../index.md#examples), [faq](../../../../index.md#faq),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
[//000000001]: # (docidx_lang_intro - Documentation tools)
[//000000002]: # (Generated from file 'docidx_lang_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docidx_lang_intro(n) 1.0 tcllib "Documentation tools")
# NAME
docidx_lang_intro - docidx language introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#subsection1)
- [Basic structure](#subsection2)
- [Advanced structure](#subsection3)
- [Escapes](#subsection4)
- [FURTHER READING](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document is an informal introduction to version 1 of the docidx markup
language based on a multitude of examples. After reading this a writer should be
ready to understand the two parts of the formal specification, i.e. the *[docidx
language syntax](docidx_lang_syntax.md)* specification and the *[docidx language
command reference](docidx_lang_cmdref.md)*.
## <a name='subsection1'></a>Fundamentals
While the *docidx markup language* is quite similar to the *doctools markup
language*, in the broadest terms possible, there is one key difference. An index
consists essentially only of markup commands, with no plain text interspersed
between them, except for whitespace.
Each markup command is a Tcl command surrounded by a matching pair of __[__ and
__]__. Inside of these delimiters the usual rules for a Tcl command apply with
regard to word quotation, nested commands, continuation lines, etc. I.e.
... [key {markup language}] ...
... [manpage thefile \\
{file description}] ...
## <a name='subsection2'></a>Basic structure
The most simple document which can be written in docidx is
[index_begin GROUPTITLE TITLE]
[index_end]
Not very useful, but valid. This also shows us that all docidx documents consist
of only one part where we will list all keys and their references.
A more useful index will contain at least keywords, or short 'keys', i.e. the
phrases which were indexed. So:
[index_begin GROUPTITLE TITLE]
[__key markup__]
[__key {semantic markup}]__]
[__key {docidx markup}__]
[__key {docidx language}__]
[__key {docidx commands}__]
[index_end]
In the above example the command __key__ is used to declare the keyword phrases
we wish to be part of the index.
However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords. Here is a
made-up index for all the manpages in the module
*[base64](../../../../index.md#base64)*:
[index_begin tcllib/base64 {De- & Encoding}]
[key base64]
[__manpage base64__]
[key encoding]
[__manpage base64__]
[__manpage uuencode__]
[__manpage yencode__]
[key uuencode]
[__manpage uuencode__]
[key yEnc]
[__manpage yencode__]
[key ydecode]
[__manpage yencode__]
[key yencode]
[__manpage yencode__]
[index_end]
In the above example the command __[manpage](../../../../index.md#manpage)__ is
used to insert references to documents, using symbolic file names, with each
command belonging to the last __key__ command coming before it.
The other command to insert references is __[url](../../../../index.md#url)__.
In contrast to __[manpage](../../../../index.md#manpage)__ it uses explicit
(possibly format-specific) urls to describe the location of the referenced
document. As such this command is intended for the creation of references to
external documents which could not be handled in any other way.
## <a name='subsection3'></a>Advanced structure
In all previous examples we fudged a bit regarding the markup actually allowed
to be used before the __index_begin__ command opening the document.
Instead of only whitespace the two templating commands __include__ and __vset__
are also allowed, to enable the writer to either set and/or import configuration
settings relevant to the table of contents. I.e. it is possible to write
[__include FILE__]
[__vset VAR VALUE__]
[index_begin GROUPTITLE TITLE]
...
[index_end]
Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure.
[index_begin GROUPTITLE TITLE]
[__include FILE__]
[__vset VAR VALUE__]
...
[index_end]
The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion. I.e. a file included
before __index_begin__ may contain only the templating commands __vset__ and
__include__, a file included after a key may contain only manape or url
references, and other keys, etc.
## <a name='subsection4'></a>Escapes
Beyond the 6 commands shown so far we have two more available. However their
function is not the marking up of index structure, but the insertion of
characters, namely __[__ and __]__. These commands, __lb__ and __rb__
respectively, are required because our use of [ and ] to bracket markup commands
makes it impossible to directly use [ and ] within the text.
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added.
...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [__lb__] and [__rb__] to bracket markup commands makes it
impossible to directly use [__lb__] and [__rb__] within the text.
...
# <a name='section2'></a>FURTHER READING
Now that this document has been digested the reader, assumed to be a *writer* of
documentation should be fortified enough to be able to understand the formal
*[docidx language syntax](docidx_lang_syntax.md)* specification as well. From
here on out the *[docidx language command reference](docidx_lang_cmdref.md)*
will also serve as the detailed specification and cheat sheet for all available
commands and their syntax.
To be able to validate a document while writing it, it is also recommended to
familiarize oneself with Tclapps' ultra-configurable __dtp__.
On the other hand, docidx is perfectly suited for the automatic generation from
doctools documents, and this is the route Tcllib's easy and simple
__[dtplite](../../apps/dtplite.md)__ goes, creating an index for a set of
documents behind the scenes, without the writer having to do so on their own.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [docidx_lang_cmdref](docidx_lang_cmdref.md),
[docidx_lang_syntax](docidx_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[docidx commands](../../../../index.md#docidx_commands), [docidx
language](../../../../index.md#docidx_language), [docidx
markup](../../../../index.md#docidx_markup), [docidx
syntax](../../../../index.md#docidx_syntax),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx_lang_syntax.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
[//000000001]: # (docidx_lang_syntax - Documentation tools)
[//000000002]: # (Generated from file 'docidx_lang_syntax.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docidx_lang_syntax(n) 1.0 tcllib "Documentation tools")
# NAME
docidx_lang_syntax - docidx language syntax
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#section2)
- [Lexical definitions](#section3)
- [Syntax](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document contains the formal specification of the syntax of the docidx
markup language, version 1 in Backus-Naur-Form. This document is intended to be
a reference, complementing the *[docidx language command
reference](docidx_lang_cmdref.md)*. A beginner should read the much more
informally written *[docidx language introduction](docidx_lang_intro.md)* first
before trying to understand either this document or the command reference.
# <a name='section2'></a>Fundamentals
In the broadest terms possible the *docidx markup language* is like SGML and
similar languages. A document written in this language consists primarily of
markup commands, with text embedded into it at some places.
Each markup command is a just Tcl command surrounded by a matching pair of __[__
and __]__. Which commands are available, and their arguments, i.e. syntax is
specified in the *[docidx language command reference](docidx_lang_cmdref.md)*.
In this document we specify first the lexeme, and then the syntax, i.e. how we
can mix text and markup commands with each other.
# <a name='section3'></a>Lexical definitions
In the syntax rules listed in the next section
1. <TEXT> stands for all text except markup commands.
1. Any XXX stands for the markup command [xxx] including its arguments. Each
markup command is a Tcl command surrounded by a matching pair of __[__ and
__]__. Inside of these delimiters the usual rules for a Tcl command apply
with regard to word quotation, nested commands, continuation lines, etc.
1. <WHITE> stands for all text consisting only of spaces, newlines, tabulators
and the __[comment](../../../../index.md#comment)__ markup command.
# <a name='section4'></a>Syntax
The rules listed here specify only the syntax of docidx documents. The lexical
level of the language was covered in the previous section.
Regarding the syntax of the (E)BNF itself
1. The construct { X } stands for zero or more occurrences of X.
1. The construct [ X ] stands for zero or one occurrence of X.
The syntax:
index = defs
INDEX_BEGIN
[ contents ]
INDEX_END
{ <WHITE> }
defs = { INCLUDE | VSET | <WHITE> }
contents = keyword { keyword }
keyword = defs KEY ref { ref }
ref = MANPAGE | URL | defs
At last a rule we were unable to capture in the EBNF syntax, as it is about the
arguments of the markup commands, something which is not modeled here.
1. The arguments of all markup commands have to be plain text, and/or text
markup commands, i.e. one of
1) __lb__,
1) __rb__, or
1) __vset__ (1-argument form).
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [docidx_lang_cmdref](docidx_lang_cmdref.md),
[docidx_lang_faq](docidx_lang_faq.md), [docidx_lang_intro](docidx_lang_intro.md)
# <a name='keywords'></a>KEYWORDS
[docidx commands](../../../../index.md#docidx_commands), [docidx
language](../../../../index.md#docidx_language), [docidx
markup](../../../../index.md#docidx_markup), [docidx
syntax](../../../../index.md#docidx_syntax),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/docidx_plugin_apiref.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
|
[//000000001]: # (docidx_plugin_apiref - Documentation tools)
[//000000002]: # (Generated from file 'docidx_plugin_apiref.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (docidx_plugin_apiref(n) 1.0 tcllib "Documentation tools")
# NAME
docidx_plugin_apiref - docidx plugin API reference
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OVERVIEW](#section2)
- [FRONTEND COMMANDS](#section3)
- [PLUGIN COMMANDS](#section4)
- [Management commands](#subsection1)
- [Formatting commands](#subsection2)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__dt_fmap__ *symfname*](#1)
[__dt_format__](#2)
[__dt_read__ *file*](#3)
[__dt_source__ *file*](#4)
[__ex_cappend__ *text*](#5)
[__ex_cget__ *varname*](#6)
[__ex_cis__ *cname*](#7)
[__ex_cname__](#8)
[__ex_cpop__ *cname*](#9)
[__ex_cpush__ *cname*](#10)
[__ex_cset__ *varname* *value*](#11)
[__ex_lb__ ?*newbracket*?](#12)
[__ex_rb__ ?*newbracket*?](#13)
[__idx_initialize__](#14)
[__idx_listvariables__](#15)
[__idx_numpasses__](#16)
[__idx_postprocess__ *text*](#17)
[__idx_setup__ *n*](#18)
[__idx_shutdown__](#19)
[__idx_varset__ *varname* *text*](#20)
[__fmt_plain_text__ *text*](#21)
# <a name='description'></a>DESCRIPTION
This document is intended for *plugin writers*, i.e. developers wishing to write
an index *[formatting engine](../../../../index.md#formatting_engine)* for some
output format X.
It specifies the interaction between the
__[doctools::idx](../doctools2idx/idx_container.md)__ package and its plugins,
i.e. the interface any index formatting engine has to comply with.
This document deals with version 1 of the interface.
A reader who is on the other hand more interested in the markup language itself
should start with the *[docidx language introduction](docidx_lang_intro.md)* and
proceed from there to the formal specifications, i.e. the *[docidx language
syntax](docidx_lang_syntax.md)* and the *[docidx language command
reference](docidx_lang_cmdref.md)*.
# <a name='section2'></a>OVERVIEW
The API for an index formatting engine consists of two major sections.
On the one side we have a set of commands through which the plugin is able to
query the frontend. These commands are provided by the frontend and linked into
the plugin interpreter. Please see section [FRONTEND COMMANDS](#section3) for
their detailed specification.
And on the other side the plugin has to provide its own set of commands which
will then be called by the frontend in a specific sequence while processing
input. They, again, fall into two categories, management and formatting. Please
see section [PLUGIN COMMANDS](#section4) and its subsections for their detailed
specification.
# <a name='section3'></a>FRONTEND COMMANDS
This section specifies the set of commands through which a plugin, also known as
an index formatting engine, is able to query the frontend. These commands are
provided by the frontend and linked into the plugin interpreter.
I.e. an index formatting engine can assume that all of the following commands
are present when any of its own commands (as specified in section [PLUGIN
COMMANDS](#section4)) are executed.
Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the processor, nor
can it damage the filesystem. It is however able to either kill or hang the
whole process, by exiting, or running an infinite loop.
Coming back to the imported commands, all the commands with prefix *dt_* provide
limited access to specific parts of the frontend, whereas the commands with
prefix *ex_* provide access to the state of the
__[textutil::expander](../textutil/expander.md)__ object which does the main
parsing of the input within the frontend. These commands should not be except
under very special circumstances.
- <a name='1'></a>__dt_fmap__ *symfname*
Query command. It returns the actual pathname to use in the output in place
of the symbolic filename *symfname*. It will return the unchanged input if
no mapping was established for *symfname*.
The required mappings are established with the method __map__ of a frontend,
as explained in section __OBJECT METHODS__ of the documentation for the
package __[doctools::idx](../doctools2idx/idx_container.md)__.
- <a name='2'></a>__dt_format__
Query command. It returns the name of the format associated with the index
formatting engine.
- <a name='3'></a>__dt_read__ *file*
Controlled filesystem access. Returns contents of *file* for whatever use
desired by the plugin. Only files which are either in the same directory as
the file containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.
- <a name='4'></a>__dt_source__ *file*
Controlled filesystem access. This command allows the index formatting
engine to load additional Tcl code it may need. Only files which are either
in the same directory as the file containing the engine, or below it, can be
loaded. Trying to load a file outside of this directory causes an error.
- <a name='5'></a>__ex_cappend__ *text*
Appends a string to the output in the current context. This command should
rarely be used by macros or application code.
- <a name='6'></a>__ex_cget__ *varname*
Retrieves the value of variable *varname*, defined in the current context.
- <a name='7'></a>__ex_cis__ *cname*
Determines whether or not the name of the current context is *cname*.
- <a name='8'></a>__ex_cname__
Returns the name of the current context.
- <a name='9'></a>__ex_cpop__ *cname*
Pops a context from the context stack, returning all accumulated output in
that context. The context must be named *cname*, or an error results.
- <a name='10'></a>__ex_cpush__ *cname*
Pushes a context named *cname* onto the context stack. The context must be
popped by __cpop__ before expansion ends or an error results.
- <a name='11'></a>__ex_cset__ *varname* *value*
Sets variable *varname* to *value* in the current context.
- <a name='12'></a>__ex_lb__ ?*newbracket*?
Returns the current value of the left macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
- <a name='13'></a>__ex_rb__ ?*newbracket*?
Returns the current value of the right macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
# <a name='section4'></a>PLUGIN COMMANDS
The plugin has to provide its own set of commands which will then be called by
the frontend in a specific sequence while processing input. They fall into two
categories, management and formatting. Their expected names, signatures, and
responsibilities are specified in the following two subsections.
## <a name='subsection1'></a>Management commands
The management commands a plugin has to provide are used by the frontend to
1. initialize and shutdown the plugin
1. determine the number of passes it has to make over the input
1. initialize and shutdown each pass
1. query and initialize engine parameters
After the plugin has been loaded and the frontend commands are established the
commands will be called in the following sequence:
idx_numpasses -> n
idx_listvariables -> vars
idx_varset var1 value1
idx_varset var2 value2
...
idx_varset varK valueK
idx_initialize
idx_setup 1
...
idx_setup 2
...
...
idx_setup n
...
idx_postprocess
idx_shutdown
...
I.e. first the number of passes and the set of available engine parameters is
established, followed by calls setting the parameters. That second part is
optional.
After that the plugin is initialized, the specified number of passes executed,
the final result run through a global post processing step and at last the
plugin is shutdown again. This can be followed by more conversions, restarting
the sequence at __idx_varset__.
In each of the passes, i.e. after the calls of __idx_setup__ the frontend will
process the input and call the formatting commands as markup is encountered.
This means that the sequence of formatting commands is determined by the grammar
of the docidx markup language, as specified in the *[docidx language
syntax](docidx_lang_syntax.md)* specification.
A different way of looking at the sequence is:
- First some basic parameters are determined.
- Then everything starting at the first __idx_varset__ to __idx_shutdown__
forms a *run*, the formatting of a single input. Each run can be followed by
more.
- Embedded within each run we have one or more *passes*, each starting with
__idx_setup__ and going until either the next __idx_setup__ or
__idx_postprocess__ is reached.
If more than one pass is required to perform the formatting only the output
of the last pass is relevant. The output of all the previous, preparatory
passes is ignored.
The commands, their names, signatures, and responsibilities are, in detail:
- <a name='14'></a>__idx_initialize__
*Initialization/Shutdown*. This command is called at the beginning of every
conversion run, as the first command of that run. Note that a run is not a
pass, but may consist of multiple passes. It has to initialize the general
state of the plugin, beyond the initialization done during the load. No
return value is expected, and any returned value is ignored.
- <a name='15'></a>__idx_listvariables__
*Initialization/Shutdown* and *Engine parameters*. Second command is called
after the plugin code has been loaded, i.e. immediately after
__idx_numpasses__. It has to return a list containing the names of the
parameters the frontend can set to configure the engine. This list can be
empty.
- <a name='16'></a>__idx_numpasses__
*Initialization/Shutdown* and *Pass management*. First command called after
the plugin code has been loaded. No other command of the engine will be
called before it. It has to return the number of passes this engine requires
to fully process the input document. This value has to be an integer number
greater or equal to one.
- <a name='17'></a>__idx_postprocess__ *text*
*Initialization/Shutdown*. This command is called immediately after the last
pass in a run. Its argument is the result of the conversion generated by
that pass. It is provided to allow the engine to perform any global
modifications of the generated document. If no post-processing is required
for a specific format the command has to just return the argument.
Expected to return a value, the final result of formatting the input.
- <a name='18'></a>__idx_setup__ *n*
*Initialization/Shutdown* and *Pass management*. This command is called at
the beginning of each pass over the input in a run. Its argument is the
number of the pass which has begun. Passes are counted from __1__ upward.
The command has to set up the internal state of the plugin for this
particular pass. No return value is expected, and any returned value is
ignored.
- <a name='19'></a>__idx_shutdown__
*Initialization/Shutdown*. This command is called at the end of every
conversion run. It is the last command called in a run. It has to clean up
of all the run-specific state in the plugin. After the call the engine has
to be in a state which allows the initiation of another run without fear
that information from the last run is leaked into this new run. No return
value is expected, and any returned value is ignored.
- <a name='20'></a>__idx_varset__ *varname* *text*
*Engine parameters*. This command is called by the frontend to set an engine
parameter to a particular value. The parameter to change is specified by
*varname*, the value to set in *text*.
The command has to throw an error if an unknown *varname* is used. Only the
names returned by __idx_listvariables__ have to be considered as known.
The values of all engine parameters have to persist between passes and runs.
## <a name='subsection2'></a>Formatting commands
The formatting commands have to implement the formatting for the output format,
for all the markup commands of the docidx markup language, except __lb__,
__rb__, __vset__, __include__, and __[comment](../../../../index.md#comment)__.
These exceptions are processed by the frontend and are never seen by the plugin.
In return a command for the formatting of plain text has to be provided,
something which has no markup in the input at all.
This means, that each of the five markup commands specified in the *[docidx
language command reference](docidx_lang_cmdref.md)* and outside of the set of
exceptions listed above has an equivalent formatting command which takes the
same arguments as the markup command and whose name is the name of markup
command with the prefix *fmt_* added to it.
All commands are expected to format their input in some way per the semantics
specified in the command reference and to return whatever part of this that they
deem necessary as their result, which will be added to the output.
To avoid essentially duplicating the command reference we do not list any of the
command here and simply refer the reader to the *[docidx language command
reference](docidx_lang_cmdref.md)* for their signature and description. The sole
exception is the plain text formatter, which has no equivalent markup command.
The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the docidx markup
language, as specified in the *[docidx language syntax](docidx_lang_syntax.md)*
specification.
- <a name='21'></a>__fmt_plain_text__ *text*
*No associated markup command*.
Called by the frontend for any plain text encountered in the input. It has
to perform any and all special processing required for plain text.
The formatted text is expected as the result of the command, and added to
the output. If no special processing is required it has to simply return its
argument without change.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [docidx_lang_cmdref](docidx_lang_cmdref.md),
[docidx_lang_faq](docidx_lang_faq.md),
[docidx_lang_intro](docidx_lang_intro.md),
[docidx_lang_syntax](docidx_lang_syntax.md),
[doctools::idx](../doctools2idx/idx_container.md)
# <a name='keywords'></a>KEYWORDS
[formatting engine](../../../../index.md#formatting_engine),
[index](../../../../index.md#index), [index
formatter](../../../../index.md#index_formatter),
[keywords](../../../../index.md#keywords),
[markup](../../../../index.md#markup), [plugin](../../../../index.md#plugin),
[semantic markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
|
[//000000001]: # (doctools::toc - Documentation tools)
[//000000002]: # (Generated from file 'doctoc.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc(n) 1.1.7 tcllib "Documentation tools")
# NAME
doctools::toc - doctoc - Processing tables of contents
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [PACKAGE COMMANDS](#subsection1)
- [OBJECT COMMAND](#subsection2)
- [OBJECT METHODS](#subsection3)
- [OBJECT CONFIGURATION](#subsection4)
- [FORMAT MAPPING](#subsection5)
- [PREDEFINED ENGINES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require doctools::toc ?1.1.7?
[__::doctools::toc::new__ *objectName* ?__-option__ *value* ...?](#1)
[__::doctools::toc::help__](#2)
[__::doctools::toc::search__ *path*](#3)
[__objectName__ __method__ ?*arg arg ...*?](#4)
[*objectName* __configure__](#5)
[*objectName* __configure__ *option*](#6)
[*objectName* __configure__ __-option__ *value*...](#7)
[*objectName* __cget__ __-option__](#8)
[*objectName* __destroy__](#9)
[*objectName* __format__ *text*](#10)
[*objectName* __map__ *symbolic* *actual*](#11)
[*objectName* __parameters__](#12)
[*objectName* __search__ *path*](#13)
[*objectName* __setparam__ *name* *value*](#14)
[*objectName* __warnings__](#15)
# <a name='description'></a>DESCRIPTION
This package provides a class for the creation of objects able to process and
convert text written in the *[doctoc](../../../../index.md#doctoc)* markup
language into any output format X for which a *[formatting
engine](../../../../index.md#formatting_engine)* is available.
A reader interested in the markup language itself should start with the *[doctoc
language introduction](doctoc_lang_intro.md)* and proceed from there to the
formal specifications, i.e. the *[doctoc language
syntax](doctoc_lang_syntax.md)* and the *[doctoc language command
reference](doctoc_lang_cmdref.md)*.
If on the other hand the reader wishes to write her own formatting engine for
some format, i.e. is a *plugin writer* then reading and understanding the
*[doctoc plugin API reference](doctoc_plugin_apiref.md)* is an absolute
necessity, as that document specifies the interaction between this package and
its plugins, i.e. the formatting engines, in detail.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>PACKAGE COMMANDS
- <a name='1'></a>__::doctools::toc::new__ *objectName* ?__-option__ *value* ...?
This command creates a new doctoc object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [OBJECT
COMMAND](#subsection2) and [OBJECT METHODS](#subsection3). The object
command will be created under the current namespace if the *objectName* is
not fully qualified, and in the specified namespace otherwise.
The options and their values coming after the name of the object are used to
set the initial configuration of the object.
- <a name='2'></a>__::doctools::toc::help__
This is a convenience command for applications wishing to provide their user
with a short description of the available formatting commands and their
meanings. It returns a string containing a standard help text.
- <a name='3'></a>__::doctools::toc::search__ *path*
Whenever an object created by this the package has to map the name of a
format to the file containing the code for its formatting engine it will
search for the file in a number of directories stored in a list. See section
[FORMAT MAPPING](#subsection5) for more explanations.
This list not only contains three default directories which are declared by
the package itself, but is also extensible user of the package. This command
is the means to do so. When given a *path* to an existing and readable
directory it will prepend that directory to the list of directories to
search. This means that the *path* added last is later searched through
first.
An error will be thrown if the *path* either does not exist, is not a
directory, or is not readable.
## <a name='subsection2'></a>OBJECT COMMAND
All commands created by __::doctools::toc::new__ have the following general form
and may be used to invoke various operations on their doctoc converter object.
- <a name='4'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [OBJECT METHODS](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>OBJECT METHODS
- <a name='5'></a>*objectName* __configure__
The method returns a list of all known options and their current values when
called without any arguments.
- <a name='6'></a>*objectName* __configure__ *option*
The method behaves like the method __cget__ when called with a single
argument and returns the value of the option specified by said argument.
- <a name='7'></a>*objectName* __configure__ __-option__ *value*...
The method reconfigures the specified __option__s of the object, setting
them to the associated *value*s, when called with an even number of
arguments, at least two.
The legal options are described in the section [OBJECT
CONFIGURATION](#subsection4).
- <a name='8'></a>*objectName* __cget__ __-option__
This method expects a legal configuration option as argument and will return
the current value of that option for the object the method was invoked for.
The legal configuration options are described in section [OBJECT
CONFIGURATION](#subsection4).
- <a name='9'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='10'></a>*objectName* __format__ *text*
This method runs the *text* through the configured formatting engine and
returns the generated string as its result. An error will be thrown if no
__-format__ was configured for the object.
The method assumes that the *text* is in
*[doctoc](../../../../index.md#doctoc)* format as specified in the companion
document *doctoc_fmt*. Errors will be thrown otherwise.
- <a name='11'></a>*objectName* __map__ *symbolic* *actual*
This methods add one entry to the per-object mapping from *symbolic*
filenames to the *actual* uris. The object just stores this mapping and
makes it available to the configured formatting engine through the command
__dt_fmap__. This command is described in more detail in the *[doctoc plugin
API reference](doctoc_plugin_apiref.md)* which specifies the interaction
between the objects created by this package and toc formatting engines.
- <a name='12'></a>*objectName* __parameters__
This method returns a list containing the names of all engine parameters
provided by the configured formatting engine. It will return an empty list
if the object is not yet configured for a specific format.
- <a name='13'></a>*objectName* __search__ *path*
This method extends the per-object list of paths searched for toc formatting
engines. See also the command __::doctools::toc::search__ on how to extend
the per-package list of paths. Note that the path entered last will be
searched first. For more details see section [FORMAT MAPPING](#subsection5).
- <a name='14'></a>*objectName* __setparam__ *name* *value*
This method sets the *name*d engine parameter to the specified *value*. It
will throw an error if the object is either not yet configured for a
specific format, or if the formatting engine for the configured format does
not provide a parameter with the given *name*. The list of parameters
provided by the configured formatting engine can be retrieved through the
method __parameters__.
- <a name='15'></a>*objectName* __warnings__
This method returns a list containing all the warnings which were generated
by the configured formatting engine during the last invocation of the method
__format__.
## <a name='subsection4'></a>OBJECT CONFIGURATION
All doctoc objects understand the following configuration options:
- __-file__ *file*
The argument of this option is stored in the object and made available to
the configured formatting engine through the command __dt_file__. This
command is described in more detail in the companion document *doctoc_api*
which specifies the API between the object and formatting engines.
The default value of this option is the empty string.
The configured formatting engine should interpret the value as the name of
the file containing the document which is currently processed.
- __-format__ *text*
The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the method
__format__. Its default value is the empty string. The method __format__
cannot be used if this option is not set to a valid value at least once.
The package will immediately try to map the given name to a file containing
the code for a formatting engine generating that format. An error will be
thrown if this mapping fails. In that case a previously configured format is
left untouched.
The section [FORMAT MAPPING](#subsection5) explains in detail how the
package and object will look for engine implementations.
## <a name='subsection5'></a>FORMAT MAPPING
The package and object will perform the following algorithm when trying to map a
format name *foo* to a file containing an implementation of a formatting engine
for *foo*:
1. If *foo* is the name of an existing file then this file is directly taken
as the implementation.
1. If not, the list of per-object search paths is searched. For each directory
in the list the package checks if that directory contains a file
"toc.*foo*". If yes, then that file is taken as the implementation.
Note that this list of paths is initially empty and can be extended through
the object method __search__.
1. If not, the list of package paths is searched. For each directory in the
list the package checks if that directory contains a file "toc.*foo*". If
yes, then that file is taken as the implementation.
This list of paths can be extended through the command
__::doctools::toc::search__. It contains initially one path, the
subdirectory "mpformats" of the directory the package itself is located in.
In other words, if the package implementation "doctoc.tcl" is installed in
the directory "/usr/local/lib/tcllib/doctools" then it will by default
search the directory "/usr/local/lib/tcllib/doctools/mpformats" for format
implementations.
1. The mapping fails.
# <a name='section3'></a>PREDEFINED ENGINES
The package provides predefined formatting engines for the following formats.
Some of the formatting engines support engine parameters. These will be
explicitly highlighted.
- html
This engine generates HTML markup, for processing by web browsers and the
like. This engine supports three parameters:
* footer
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the empty
string. The value is inserted into the generated output just before the
__</body>__ tag, closing the body of the generated HTML.
This can be used to insert boilerplate footer markup into the generated
document.
* header
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the empty
string. The value is inserted into the generated output just after the
__<body>__ tag, starting the body of the generated HTML.
This can be used to insert boilerplate header markup into the generated
document.
* meta
The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just after
the __<head>__ tag, starting the header section of the generated HTML.
This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.
- latex
This engine generates output suitable for the
__[latex](../../../../index.md#latex)__ text processor coming out of the TeX
world.
- list
This engine retrieves version, section and title of the manpage from the
document. As such it can be used to generate a directory listing for a set
of manpages.
- nroff
This engine generates nroff output, for processing by
__[nroff](../../../../index.md#nroff)__, or __groff__. The result will be
standard man pages as they are known in the unix world.
- null
This engine generates no outout at all. This can be used if one just wants
to validate some input.
- tmml
This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.
- wiki
This engine generates Wiki markup as understood by Jean Claude Wippler's
__wikit__ application.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_intro](doctoc_intro.md), [doctoc_lang_cmdref](doctoc_lang_cmdref.md),
[doctoc_lang_intro](doctoc_lang_intro.md),
[doctoc_lang_syntax](doctoc_lang_syntax.md),
[doctoc_plugin_apiref](doctoc_plugin_apiref.md)
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion),
[doctoc](../../../../index.md#doctoc),
[documentation](../../../../index.md#documentation),
[latex](../../../../index.md#latex), [manpage](../../../../index.md#manpage),
[markup](../../../../index.md#markup), [nroff](../../../../index.md#nroff),
[table of contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc), [wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2017 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
[//000000001]: # (doctoc_intro - Documentation tools)
[//000000002]: # (Generated from file 'doctoc_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctoc_intro(n) 1.0 tcllib "Documentation tools")
# NAME
doctoc_intro - doctoc introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [RELATED FORMATS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[doctoc](../../../../index.md#doctoc)* (short for *documentation tables of
contents*) stands for a set of related, yet different, entities which are
working together for the easy creation and transformation of tables of contents
for documentation. These are
1. A tcl based language for the semantic markup of a table of contents. Markup
is represented by Tcl commands.
1. A package providing the ability to read and transform texts written in that
markup language. It is important to note that the actual transformation of
the input text is delegated to plugins.
1. An API describing the interface between the package above and a plugin.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the documentation process.
1. A *writer* of documentation has to understand the markup language itself. A
beginner to doctoc should read the more informally written *[doctoc
language introduction](doctoc_lang_intro.md)* first. Having digested this
the formal *[doctoc language syntax](doctoc_lang_syntax.md)* specification
should become understandable. A writer experienced with doctoc may only
need the *[doctoc language command reference](doctoc_lang_cmdref.md)* from
time to time to refresh her memory.
While a document is written the __dtp__ application can be used to validate
it, and after completion it also performs the conversion into the chosen
system of visual markup, be it *roff, HTML, plain text, wiki, etc. The
simpler __[dtplite](../../apps/dtplite.md)__ application makes internal use
of doctoc when handling directories of documentation, automatically
generating a proper table of contents for them.
1. A *processor* of documentation written in the
*[doctoc](../../../../index.md#doctoc)* markup language has to know which
tools are available for use.
The main tool is the aforementioned __dtp__ application provided by Tcllib.
The simpler __[dtplite](../../apps/dtplite.md)__ does not expose doctoc to
the user. At the bottom level, common to both applications, however sits
the package __doctoools::toc__, providing the basic facilities to read and
process files containing text in the doctoc format.
1. At last, but not least, *plugin writers* have to understand the interaction
between the __[doctools::toc](doctoc.md)__ package and its plugins, as
described in the *[doctoc plugin API reference](doctoc_plugin_apiref.md)*.
# <a name='section2'></a>RELATED FORMATS
doctoc does not stand alone, it has two companion formats. These are called
*[docidx](../../../../index.md#docidx)* and
*[doctools](../../../../index.md#doctools)*, and they are for the markup of
*keyword indices*, and general documentation, respectively. They are described
in their own sets of documents, starting at the *[docidx
introduction](docidx_intro.md)* and the *[doctools
introduction](doctools_intro.md)*, respectively.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [doctoc_lang_cmdref](doctoc_lang_cmdref.md),
[doctoc_lang_faq](doctoc_lang_faq.md),
[doctoc_lang_intro](doctoc_lang_intro.md),
[doctoc_lang_syntax](doctoc_lang_syntax.md),
[doctoc_plugin_apiref](doctoc_plugin_apiref.md), [doctools::toc](doctoc.md),
[doctools_intro](doctools_intro.md)
# <a name='keywords'></a>KEYWORDS
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc_lang_cmdref.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
[//000000001]: # (doctoc_lang_cmdref - Documentation tools)
[//000000002]: # (Generated from file 'doctoc_lang_cmdref.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctoc_lang_cmdref(n) 1.0 tcllib "Documentation tools")
# NAME
doctoc_lang_cmdref - doctoc language command reference
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__[comment](../../../../index.md#comment)__ *plaintext*](#1)
[__division_end__](#2)
[__division_start__ *text* ?*symfile*?](#3)
[__include__ *filename*](#4)
[__item__ *file* *text* *desc*](#5)
[__lb__](#6)
[__rb__](#7)
[__toc_begin__ *text* *title*](#8)
[__toc_end__](#9)
[__vset__ *varname* *value*](#10)
[__vset__ *varname*](#11)
# <a name='description'></a>DESCRIPTION
This document specifies both names and syntax of all the commands which together
are the doctoc markup language, version 1. As this document is intended to be a
reference the commands are listed in alphabetical order, and the descriptions
are relatively short. A beginner should read the much more informally written
*[doctoc language introduction](doctoc_lang_intro.md)* first.
# <a name='section2'></a>Commands
- <a name='1'></a>__[comment](../../../../index.md#comment)__ *plaintext*
Toc markup. The argument text is marked up as a comment standing outside of
the actual text of the document. Main use is in free-form text.
- <a name='2'></a>__division_end__
Toc structure. This command closes the division opened by the last
__division_begin__ command coming before it, and not yet closed.
- <a name='3'></a>__division_start__ *text* ?*symfile*?
Toc structure. This command opens a division in the table of contents. Its
counterpart is __division_end__. Together they allow a user to give a table
of contents additional structure.
The title of the new division is provided by the argument *text*.
If the symbolic filename *symfile* is present then the section title should
link to the referenced document, if links are supported by the output
format.
- <a name='4'></a>__include__ *filename*
Templating. The contents of the named file are interpreted as text written
in the doctoc markup and processed in the place of the include command. The
markup in the file has to be self-contained. It is not possible for a markup
command to cross the file boundaries.
- <a name='5'></a>__item__ *file* *text* *desc*
Toc structure. This command adds an individual element to the table of
contents. Each such element refers to a document. The document is specified
through the symbolic name *file*. The *text* argument is used to label the
reference, whereas the *desc* provides a short descriptive text of that
document.
The symbolic names are used to preserve the convertibility of this format to
any output format. The actual name of the file will be inserted by the
chosen formatting engine when converting the input. This will be based on a
mapping from symbolic to actual names given to the engine.
- <a name='6'></a>__lb__
Text. The command is replaced with a left bracket. Use in free-form text.
Required to avoid interpretation of a left bracket as the start of a markup
command. Its usage is restricted to the arguments of other markup commands.
- <a name='7'></a>__rb__
Text. The command is replaced with a right bracket. Use in free-form text.
Required to avoid interpretation of a right bracket as the end of a markup
command. Its usage is restricted to the arguments of other commands.
- <a name='8'></a>__toc_begin__ *text* *title*
Document structure. The command to start a table of contents. The arguments
are a label for the whole group of documents the index refers to (*text*)
and the overall title text for the index (*title*), without markup.
The label often is the name of the package (or extension) the documents
belong to.
- <a name='9'></a>__toc_end__
Document structure. Command to end a table of contents. Anything in the
document coming after this command is in error.
- <a name='10'></a>__vset__ *varname* *value*
Templating. In this form the command sets the named document variable to the
specified *value*. It does not generate output. I.e. the command is replaced
by the empty string.
- <a name='11'></a>__vset__ *varname*
Templating. In this form the command is replaced by the value of the named
document variable
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_intro](doctoc_intro.md), [doctoc_lang_faq](doctoc_lang_faq.md),
[doctoc_lang_intro](doctoc_lang_intro.md),
[doctoc_lang_syntax](doctoc_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[doctoc commands](../../../../index.md#doctoc_commands), [doctoc
language](../../../../index.md#doctoc_language), [doctoc
markup](../../../../index.md#doctoc_markup),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc_lang_faq.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
[//000000001]: # (doctoc_lang_faq - Documentation tools)
[//000000002]: # (Generated from file 'doctoc_lang_faq.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctoc_lang_faq(n) 1.0 tcllib "Documentation tools")
# NAME
doctoc_lang_faq - doctoc language faq
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [OVERVIEW](#section2)
- [What is this document?](#subsection1)
- [EXAMPLES](#section3)
- [Where do I find doctoc examples?](#subsection2)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>OVERVIEW
## <a name='subsection1'></a>What is this document?
This document is currently mainly a placeholder, to be filled with commonly
asked questions about the doctoc markup language and companions, and their
answers.
Please report any questions (and, if possible, answers) we should consider for
this document as explained in the section [Bugs, Ideas, Feedback](#section4)
below.
# <a name='section3'></a>EXAMPLES
## <a name='subsection2'></a>Where do I find doctoc examples?
We have no direct examples of documents written using doctoc markup. However the
doctools processor __[dtplite](../../apps/dtplite.md)__ does generate a table of
contents when processing a set of documents written in doctools markup. The
intermediate file for it uses doctoc markup and is not deleted when generation
completes. Such files can therefore serve as examples.
__[dtplite](../../apps/dtplite.md)__ is distributed as part of Tcllib, so to get
it you need one of
1. A snapshot of Tcllib. How to retrieve such a snapshot and the tools
required for this are described at [Development
Snapshots](/wiki?name=Development+Snapshots)
1. A Tcllib release archive. They are available at the [home](/home) page.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_lang_cmdref](doctoc_lang_cmdref.md),
[doctoc_lang_intro](doctoc_lang_intro.md),
[doctoc_lang_syntax](doctoc_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[doctoc commands](../../../../index.md#doctoc_commands), [doctoc
language](../../../../index.md#doctoc_language), [doctoc
markup](../../../../index.md#doctoc_markup), [doctoc
syntax](../../../../index.md#doctoc_syntax),
[examples](../../../../index.md#examples), [faq](../../../../index.md#faq),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
[//000000001]: # (doctoc_lang_intro - Documentation tools)
[//000000002]: # (Generated from file 'doctoc_lang_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctoc_lang_intro(n) 1.0 tcllib "Documentation tools")
# NAME
doctoc_lang_intro - doctoc language introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#subsection1)
- [Basic structure](#subsection2)
- [Items](#subsection3)
- [Divisions](#subsection4)
- [Advanced structure](#subsection5)
- [Escapes](#subsection6)
- [FURTHER READING](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document is an informal introduction to version 1.1 of the doctoc markup
language based on a multitude of examples. After reading this a writer should be
ready to understand the two parts of the formal specification, i.e. the *[doctoc
language syntax](doctoc_lang_syntax.md)* specification and the *[doctoc language
command reference](doctoc_lang_cmdref.md)*.
## <a name='subsection1'></a>Fundamentals
While the *doctoc markup language* is quite similar to the *doctools markup
language*, in the broadest terms possible, there is one key difference. A table
of contents consists essentially only of markup commands, with no plain text
interspersed between them, except for whitespace.
Each markup command is a Tcl command surrounded by a matching pair of __[__ and
__]__. Inside of these delimiters the usual rules for a Tcl command apply with
regard to word quotation, nested commands, continuation lines, etc. I.e.
... [division_start {Appendix 1}] ...
... [item thefile \\
label {file description}] ...
## <a name='subsection2'></a>Basic structure
The most simple document which can be written in doctoc is
[toc_begin GROUPTITLE TITLE]
[toc_end]
This also shows us that all doctoc documents consist of only one part where we
will list *items* and *divisions*.
The user is free to mix these as she sees fit. This is a change from version 1
of the language, which did not allow this mixing, but only the use of either a
series of items or a series of divisions.
We will discuss the commands for each of these two possibilities in the next
sections.
## <a name='subsection3'></a>Items
Use the command __item__ to put an *item* into a table of contents. This is
essentially a reference to a section, subsection, etc. in the document, or set
of documents, the table of contents is for. The command takes three arguments, a
symbolic name for the file the item is for and two text to label the item and
describe the referenced section.
Symbolic names are used to preserve the convertibility of this format to any
output format. The actual name of any file will be inserted by the chosen
formatting engine when converting the input, based on a mapping from symbolic to
actual names given to the engine.
Here a made up example for a table of contents of this document:
[toc_begin Doctoc {Language Introduction}]
[__item 1 DESCRIPTION__]
[__item 1.1 {Basic structure}__]
[__item 1.2 Items__]
[__item 1.3 Divisions__]
[__item 2 {FURTHER READING}__]
[toc_end]
## <a name='subsection4'></a>Divisions
One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1.
This kind of structure can be made more explicit in the doctoc language by using
divisions. Instead of using a series of plain items we use a series of divisions
for the major references, and then place the nested items inside of these.
Of course, instead of the nested items we can again use divisions and thus nest
arbitrarily deep.
A division is marked by two commands instead of one, one to start it, the other
to close the last opened division. They are:
- __division_start__
This command opens a new division. It takes one or two arguments, the title
of the division, and the symbolic name of the file it refers to. The latter
is optional. If the symbolic filename is present then the section title
should link to the referenced document, if links are supported by the output
format.
- __division_end__
This command closes the last opened and not yet closed division.
Using this we can recast the last example like this
[toc_begin Doctoc {Language Introduction}]
[__division_start DESCRIPTION__]
[item 1 {Basic structure}]
[item 2 Items]
[item 3 Divisions]
[__division_end__]
[__division_start {FURTHER READING}__]
[__division_end__]
[toc_end]
Or, to demonstrate deeper nesting
[toc_begin Doctoc {Language Introduction}]
[__division_start DESCRIPTION__]
[__division_start {Basic structure}__]
[item 1 Do]
[item 2 Re]
[__division_end__]
[__division_start Items__]
[item a Fi]
[item b Fo]
[item c Fa]
[__division_end__]
[__division_start Divisions__]
[item 1 Sub]
[item 1 Zero]
[__division_end__]
[__division_end__]
[__division_start {FURTHER READING}__]
[__division_end__]
[toc_end]
And do not forget, it is possible to freely mix items and divisions, and to have
empty divisions.
[toc_begin Doctoc {Language Introduction}]
[item 1 Do]
[__division_start DESCRIPTION__]
[__division_start {Basic structure}__]
[item 2 Re]
[__division_end__]
[item a Fi]
[__division_start Items__]
[item b Fo]
[item c Fa]
[__division_end__]
[__division_start Divisions__]
[__division_end__]
[__division_end__]
[__division_start {FURTHER READING}__]
[__division_end__]
[toc_end]
## <a name='subsection5'></a>Advanced structure
In all previous examples we fudged a bit regarding the markup actually allowed
to be used before the __toc_begin__ command opening the document.
Instead of only whitespace the two templating commands __include__ and __vset__
are also allowed, to enable the writer to either set and/or import configuration
settings relevant to the table of contents. I.e. it is possible to write
[__include FILE__]
[__vset VAR VALUE__]
[toc_begin GROUPTITLE TITLE]
...
[toc_end]
Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure.
[toc_begin GROUPTITLE TITLE]
[__include FILE__]
[__vset VAR VALUE__]
...
[toc_end]
The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion. I.e. a file included
before __toc_begin__ may contain only the templating commands __vset__ and
__include__, a file included in a division may contain only items or divisions
commands, etc.
## <a name='subsection6'></a>Escapes
Beyond the 6 commands shown so far we have two more available. However their
function is not the marking up of toc structure, but the insertion of
characters, namely __[__ and __]__. These commands, __lb__ and __rb__
respectively, are required because our use of [ and ] to bracket markup commands
makes it impossible to directly use [ and ] within the text.
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added.
...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [__lb__] and [__rb__] to bracket markup commands makes it
impossible to directly use [__lb__] and [__rb__] within the text.
...
# <a name='section2'></a>FURTHER READING
Now that this document has been digested the reader, assumed to be a *writer* of
documentation should be fortified enough to be able to understand the formal
*[doctoc language syntax](doctoc_lang_syntax.md)* specification as well. From
here on out the *[doctoc language command reference](doctoc_lang_cmdref.md)*
will also serve as the detailed specification and cheat sheet for all available
commands and their syntax.
To be able to validate a document while writing it, it is also recommended to
familiarize oneself with Tclapps' ultra-configurable __dtp__.
On the other hand, doctoc is perfectly suited for the automatic generation from
doctools documents, and this is the route Tcllib's easy and simple
__[dtplite](../../apps/dtplite.md)__ goes, creating a table of contents for a
set of documents behind the scenes, without the writer having to do so on their
own.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_intro](doctoc_intro.md), [doctoc_lang_cmdref](doctoc_lang_cmdref.md),
[doctoc_lang_syntax](doctoc_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[doctoc commands](../../../../index.md#doctoc_commands), [doctoc
language](../../../../index.md#doctoc_language), [doctoc
markup](../../../../index.md#doctoc_markup), [doctoc
syntax](../../../../index.md#doctoc_syntax),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc_lang_syntax.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
[//000000001]: # (doctoc_lang_syntax - Documentation tools)
[//000000002]: # (Generated from file 'doctoc_lang_syntax.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctoc_lang_syntax(n) 1.0 tcllib "Documentation tools")
# NAME
doctoc_lang_syntax - doctoc language syntax
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#section2)
- [Lexical definitions](#section3)
- [Syntax](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document contains the formal specification of the syntax of the doctoc
markup language, version 1.1 in Backus-Naur-Form. This document is intended to
be a reference, complementing the *[doctoc language command
reference](doctoc_lang_cmdref.md)*. A beginner should read the much more
informally written *[doctoc language introduction](doctoc_lang_intro.md)* first
before trying to understand either this document or the command reference.
# <a name='section2'></a>Fundamentals
In the broadest terms possible the *doctoc markup language* is like SGML and
similar languages. A document written in this language consists primarily of
markup commands, with text embedded into it at some places.
Each markup command is a just Tcl command surrounded by a matching pair of __[__
and __]__. Which commands are available, and their arguments, i.e. syntax is
specified in the *[doctoc language command reference](doctoc_lang_cmdref.md)*.
In this document we specify first the lexeme, and then the syntax, i.e. how we
can mix text and markup commands with each other.
# <a name='section3'></a>Lexical definitions
In the syntax rules listed in the next section
1. <TEXT> stands for all text except markup commands.
1. Any XXX stands for the markup command [xxx] including its arguments. Each
markup command is a Tcl command surrounded by a matching pair of __[__ and
__]__. Inside of these delimiters the usual rules for a Tcl command apply
with regard to word quotation, nested commands, continuation lines, etc.
1. <WHITE> stands for all text consisting only of spaces, newlines, tabulators
and the __[comment](../../../../index.md#comment)__ markup command.
# <a name='section4'></a>Syntax
The rules listed here specify only the syntax of doctoc documents. The lexical
level of the language was covered in the previous section.
Regarding the syntax of the (E)BNF itself
1. The construct { X } stands for zero or more occurrences of X.
1. The construct [ X ] stands for zero or one occurrence of X.
The syntax:
toc = defs
TOC_BEGIN
contents
TOC_END
{ <WHITE> }
defs = { INCLUDE | VSET | <WHITE> }
contents = { defs entry } [ defs ]
entry = ITEM | division
division = DIVISION_START
contents
DIVISION_END
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_intro](doctoc_intro.md), [doctoc_lang_cmdref](doctoc_lang_cmdref.md),
[doctoc_lang_faq](doctoc_lang_faq.md), [doctoc_lang_intro](doctoc_lang_intro.md)
# <a name='keywords'></a>KEYWORDS
[doctoc commands](../../../../index.md#doctoc_commands), [doctoc
language](../../../../index.md#doctoc_language), [doctoc
markup](../../../../index.md#doctoc_markup), [doctoc
syntax](../../../../index.md#doctoc_syntax),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctoc_plugin_apiref.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
[//000000001]: # (doctoc_plugin_apiref - Documentation tools)
[//000000002]: # (Generated from file 'doctoc_plugin_apiref.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctoc_plugin_apiref(n) 1.0 tcllib "Documentation tools")
# NAME
doctoc_plugin_apiref - doctoc plugin API reference
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OVERVIEW](#section2)
- [FRONTEND COMMANDS](#section3)
- [PLUGIN COMMANDS](#section4)
- [Management commands](#subsection1)
- [Formatting commands](#subsection2)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__dt_fmap__ *symfname*](#1)
[__dt_format__](#2)
[__dt_read__ *file*](#3)
[__dt_source__ *file*](#4)
[__ex_cappend__ *text*](#5)
[__ex_cget__ *varname*](#6)
[__ex_cis__ *cname*](#7)
[__ex_cname__](#8)
[__ex_cpop__ *cname*](#9)
[__ex_cpush__ *cname*](#10)
[__ex_cset__ *varname* *value*](#11)
[__ex_lb__ ?*newbracket*?](#12)
[__ex_rb__ ?*newbracket*?](#13)
[__toc_initialize__](#14)
[__toc_listvariables__](#15)
[__toc_numpasses__](#16)
[__toc_postprocess__ *text*](#17)
[__toc_setup__ *n*](#18)
[__toc_shutdown__](#19)
[__toc_varset__ *varname* *text*](#20)
[__fmt_plain_text__ *text*](#21)
# <a name='description'></a>DESCRIPTION
This document is intended for *plugin writers*, i.e. developers wishing to write
a toc *[formatting engine](../../../../index.md#formatting_engine)* for some
output format X.
It specifies the interaction between the __[doctools::toc](doctoc.md)__ package
and its plugins, i.e. the interface any toc formatting engine has to comply
with.
This document deals with version 1 of the interface.
A reader who is on the other hand more interested in the markup language itself
should start with the *[doctoc language introduction](doctoc_lang_intro.md)* and
proceed from there to the formal specifications, i.e. the *[doctoc language
syntax](doctoc_lang_syntax.md)* and the *[doctoc language command
reference](doctoc_lang_cmdref.md)*.
# <a name='section2'></a>OVERVIEW
The API for a toc formatting engine consists of two major sections.
On the one side we have a set of commands through which the plugin is able to
query the frontend. These commands are provided by the frontend and linked into
the plugin interpreter. Please see section [FRONTEND COMMANDS](#section3) for
their detailed specification.
And on the other side the plugin has to provide its own set of commands which
will then be called by the frontend in a specific sequence while processing
input. They, again, fall into two categories, management and formatting. Please
see section [PLUGIN COMMANDS](#section4) and its subsections for their detailed
specification.
# <a name='section3'></a>FRONTEND COMMANDS
This section specifies the set of commands through which a plugin, also known as
a toc formatting engine, is able to query the frontend. These commands are
provided by the frontend and linked into the plugin interpreter.
I.e. a toc formatting engine can assume that all of the following commands are
present when any of its own commands (as specified in section [PLUGIN
COMMANDS](#section4)) are executed.
Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the processor, nor
can it damage the filesystem. It is however able to either kill or hang the
whole process, by exiting, or running an infinite loop.
Coming back to the imported commands, all the commands with prefix *dt_* provide
limited access to specific parts of the frontend, whereas the commands with
prefix *ex_* provide access to the state of the
__[textutil::expander](../textutil/expander.md)__ object which does the main
parsing of the input within the frontend. These commands should not be except
under very special circumstances.
- <a name='1'></a>__dt_fmap__ *symfname*
Query command. It returns the actual pathname to use in the output in place
of the symbolic filename *symfname*. It will return the unchanged input if
no mapping was established for *symfname*.
The required mappings are established with the method __map__ of a frontend,
as explained in section __OBJECT METHODS__ of the documentation for the
package __[doctools::toc](doctoc.md)__.
- <a name='2'></a>__dt_format__
Query command. It returns the name of the format associated with the toc
formatting engine.
- <a name='3'></a>__dt_read__ *file*
Controlled filesystem access. Returns contents of *file* for whatever use
desired by the plugin. Only files which are either in the same directory as
the file containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.
- <a name='4'></a>__dt_source__ *file*
Controlled filesystem access. This command allows the toc formatting engine
to load additional Tcl code it may need. Only files which are either in the
same directory as the file containing the engine, or below it, can be
loaded. Trying to load a file outside of this directory causes an error.
- <a name='5'></a>__ex_cappend__ *text*
Appends a string to the output in the current context. This command should
rarely be used by macros or application code.
- <a name='6'></a>__ex_cget__ *varname*
Retrieves the value of variable *varname*, defined in the current context.
- <a name='7'></a>__ex_cis__ *cname*
Determines whether or not the name of the current context is *cname*.
- <a name='8'></a>__ex_cname__
Returns the name of the current context.
- <a name='9'></a>__ex_cpop__ *cname*
Pops a context from the context stack, returning all accumulated output in
that context. The context must be named *cname*, or an error results.
- <a name='10'></a>__ex_cpush__ *cname*
Pushes a context named *cname* onto the context stack. The context must be
popped by __cpop__ before expansion ends or an error results.
- <a name='11'></a>__ex_cset__ *varname* *value*
Sets variable *varname* to *value* in the current context.
- <a name='12'></a>__ex_lb__ ?*newbracket*?
Returns the current value of the left macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
- <a name='13'></a>__ex_rb__ ?*newbracket*?
Returns the current value of the right macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
# <a name='section4'></a>PLUGIN COMMANDS
The plugin has to provide its own set of commands which will then be called by
the frontend in a specific sequence while processing input. They fall into two
categories, management and formatting. Their expected names, signatures, and
responsibilities are specified in the following two subsections.
## <a name='subsection1'></a>Management commands
The management commands a plugin has to provide are used by the frontend to
1. initialize and shutdown the plugin
1. determine the number of passes it has to make over the input
1. initialize and shutdown each pass
1. query and initialize engine parameters
After the plugin has been loaded and the frontend commands are established the
commands will be called in the following sequence:
toc_numpasses -> n
toc_listvariables -> vars
toc_varset var1 value1
toc_varset var2 value2
...
toc_varset varK valueK
toc_initialize
toc_setup 1
...
toc_setup 2
...
...
toc_setup n
...
toc_postprocess
toc_shutdown
...
I.e. first the number of passes and the set of available engine parameters is
established, followed by calls setting the parameters. That second part is
optional.
After that the plugin is initialized, the specified number of passes executed,
the final result run through a global post processing step and at last the
plugin is shutdown again. This can be followed by more conversions, restarting
the sequence at __toc_varset__.
In each of the passes, i.e. after the calls of __toc_setup__ the frontend will
process the input and call the formatting commands as markup is encountered.
This means that the sequence of formatting commands is determined by the grammar
of the doctoc markup language, as specified in the *[doctoc language
syntax](doctoc_lang_syntax.md)* specification.
A different way of looking at the sequence is:
- First some basic parameters are determined.
- Then everything starting at the first __toc_varset__ to __toc_shutdown__
forms a *run*, the formatting of a single input. Each run can be followed by
more.
- Embedded within each run we have one or more *passes*, each starting with
__toc_setup__ and going until either the next __toc_setup__ or
__toc_postprocess__ is reached.
If more than one pass is required to perform the formatting only the output
of the last pass is relevant. The output of all the previous, preparatory
passes is ignored.
The commands, their names, signatures, and responsibilities are, in detail:
- <a name='14'></a>__toc_initialize__
*Initialization/Shutdown*. This command is called at the beginning of every
conversion run, as the first command of that run. Note that a run is not a
pass, but may consist of multiple passes. It has to initialize the general
state of the plugin, beyond the initialization done during the load. No
return value is expected, and any returned value is ignored.
- <a name='15'></a>__toc_listvariables__
*Initialization/Shutdown* and *Engine parameters*. Second command is called
after the plugin code has been loaded, i.e. immediately after
__toc_numpasses__. It has to return a list containing the names of the
parameters the frontend can set to configure the engine. This list can be
empty.
- <a name='16'></a>__toc_numpasses__
*Initialization/Shutdown* and *Pass management*. First command called after
the plugin code has been loaded. No other command of the engine will be
called before it. It has to return the number of passes this engine requires
to fully process the input document. This value has to be an integer number
greater or equal to one.
- <a name='17'></a>__toc_postprocess__ *text*
*Initialization/Shutdown*. This command is called immediately after the last
pass in a run. Its argument is the result of the conversion generated by
that pass. It is provided to allow the engine to perform any global
modifications of the generated document. If no post-processing is required
for a specific format the command has to just return the argument.
Expected to return a value, the final result of formatting the input.
- <a name='18'></a>__toc_setup__ *n*
*Initialization/Shutdown* and *Pass management*. This command is called at
the beginning of each pass over the input in a run. Its argument is the
number of the pass which has begun. Passes are counted from __1__ upward.
The command has to set up the internal state of the plugin for this
particular pass. No return value is expected, and any returned value is
ignored.
- <a name='19'></a>__toc_shutdown__
*Initialization/Shutdown*. This command is called at the end of every
conversion run. It is the last command called in a run. It has to clean up
of all the run-specific state in the plugin. After the call the engine has
to be in a state which allows the initiation of another run without fear
that information from the last run is leaked into this new run. No return
value is expected, and any returned value is ignored.
- <a name='20'></a>__toc_varset__ *varname* *text*
*Engine parameters*. This command is called by the frontend to set an engine
parameter to a particular value. The parameter to change is specified by
*varname*, the value to set in *text*.
The command has to throw an error if an unknown *varname* is used. Only the
names returned by __toc_listvariables__ have to be considered as known.
The values of all engine parameters have to persist between passes and runs.
## <a name='subsection2'></a>Formatting commands
The formatting commands have to implement the formatting for the output format,
for all the markup commands of the doctoc markup language, except __lb__,
__rb__, __vset__, __include__, and __[comment](../../../../index.md#comment)__.
These exceptions are processed by the frontend and are never seen by the plugin.
In return a command for the formatting of plain text has to be provided,
something which has no markup in the input at all.
This means, that each of the five markup commands specified in the *[doctoc
language command reference](doctoc_lang_cmdref.md)* and outside of the set of
exceptions listed above has an equivalent formatting command which takes the
same arguments as the markup command and whose name is the name of markup
command with the prefix *fmt_* added to it.
All commands are expected to format their input in some way per the semantics
specified in the command reference and to return whatever part of this that they
deem necessary as their result, which will be added to the output.
To avoid essentially duplicating the command reference we do not list any of the
command here and simply refer the reader to the *[doctoc language command
reference](doctoc_lang_cmdref.md)* for their signature and description. The sole
exception is the plain text formatter, which has no equivalent markup command.
The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the doctoc markup
language, as specified in the *[doctoc language syntax](doctoc_lang_syntax.md)*
specification.
- <a name='21'></a>__fmt_plain_text__ *text*
*No associated markup command*.
Called by the frontend for any plain text encountered in the input. It has
to perform any and all special processing required for plain text.
The formatted text is expected as the result of the command, and added to
the output. If no special processing is required it has to simply return its
argument without change.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_intro](doctoc_intro.md), [doctoc_lang_cmdref](doctoc_lang_cmdref.md),
[doctoc_lang_faq](doctoc_lang_faq.md),
[doctoc_lang_intro](doctoc_lang_intro.md),
[doctoc_lang_syntax](doctoc_lang_syntax.md), [doctools::toc](doctoc.md)
# <a name='keywords'></a>KEYWORDS
[formatting engine](../../../../index.md#formatting_engine),
[markup](../../../../index.md#markup), [plugin](../../../../index.md#plugin),
[semantic markup](../../../../index.md#semantic_markup), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc), [toc
formatter](../../../../index.md#toc_formatter)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
|
[//000000001]: # (doctools - Documentation tools)
[//000000002]: # (Generated from file 'doctools.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools(n) 1.4.21 tcllib "Documentation tools")
# NAME
doctools - doctools - Processing documents
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [PACKAGE COMMANDS](#subsection1)
- [OBJECT COMMAND](#subsection2)
- [OBJECT METHODS](#subsection3)
- [OBJECT CONFIGURATION](#subsection4)
- [FORMAT MAPPING](#subsection5)
- [PREDEFINED ENGINES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require doctools ?1.4.21?
[__::doctools::new__ *objectName* ?*option value*...?](#1)
[__::doctools::help__](#2)
[__::doctools::search__ *path*](#3)
[__objectName__ __method__ ?*arg arg ...*?](#4)
[*objectName* __configure__](#5)
[*objectName* __configure__ *option*](#6)
[*objectName* __configure__ __-option__ *value*...](#7)
[*objectName* __cget__ __-option__](#8)
[*objectName* __destroy__](#9)
[*objectName* __format__ *text*](#10)
[*objectName* __map__ *symbolic* *actual*](#11)
[*objectName* __parameters__](#12)
[*objectName* __search__ *path*](#13)
[*objectName* __setparam__ *name* *value*](#14)
[*objectName* __warnings__](#15)
# <a name='description'></a>DESCRIPTION
This package provides a class for the creation of objects able to process and
convert text written in the *[doctools](../../../../index.md#doctools)* markup
language into any output format X for which a *[formatting
engine](../../../../index.md#formatting_engine)* is available.
A reader interested in the markup language itself should start with the
*[doctools language introduction](doctools_lang_intro.md)* and proceed from
there to the formal specifications, i.e. the *[doctools language
syntax](doctools_lang_syntax.md)* and the *[doctools language command
reference](doctools_lang_cmdref.md)*.
If on the other hand the reader wishes to write her own formatting engine for
some format, i.e. is a *plugin writer* then reading and understanding the
*[doctools plugin API reference](doctools_plugin_apiref.md)* is an absolute
necessity, as that document specifies the interaction between this package and
its plugins, i.e. the formatting engines, in detail.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>PACKAGE COMMANDS
- <a name='1'></a>__::doctools::new__ *objectName* ?*option value*...?
This command creates a new doctools object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [OBJECT
COMMAND](#subsection2) and [OBJECT METHODS](#subsection3). The object
command will be created under the current namespace if the *objectName* is
not fully qualified, and in the specified namespace otherwise.
The options and their values coming after the name of the object are used to
set the initial configuration of the object.
- <a name='2'></a>__::doctools::help__
This is a convenience command for applications wishing to provide their user
with a short description of the available formatting commands and their
meanings. It returns a string containing a standard help text.
- <a name='3'></a>__::doctools::search__ *path*
Whenever an object created by this the package has to map the name of a
format to the file containing the code for its formatting engine it will
search for the file in a number of directories stored in a list. See section
[FORMAT MAPPING](#subsection5) for more explanations.
This list not only contains three default directories which are declared by
the package itself, but is also extensible user of the package. This command
is the means to do so. When given a *path* to an existing and readable
directory it will prepend that directory to the list of directories to
search. This means that the *path* added last is later searched through
first.
An error will be thrown if the *path* either does not exist, is not a
directory, or is not readable.
## <a name='subsection2'></a>OBJECT COMMAND
All commands created by __::doctools::new__ have the following general form and
may be used to invoke various operations on their doctools converter object.
- <a name='4'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [OBJECT METHODS](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>OBJECT METHODS
- <a name='5'></a>*objectName* __configure__
The method returns a list of all known options and their current values when
called without any arguments.
- <a name='6'></a>*objectName* __configure__ *option*
The method behaves like the method __cget__ when called with a single
argument and returns the value of the option specified by said argument.
- <a name='7'></a>*objectName* __configure__ __-option__ *value*...
The method reconfigures the specified __option__s of the object, setting
them to the associated *value*s, when called with an even number of
arguments, at least two.
The legal options are described in the section [OBJECT
CONFIGURATION](#subsection4).
- <a name='8'></a>*objectName* __cget__ __-option__
This method expects a legal configuration option as argument and will return
the current value of that option for the object the method was invoked for.
The legal configuration options are described in section [OBJECT
CONFIGURATION](#subsection4).
- <a name='9'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='10'></a>*objectName* __format__ *text*
This method runs the *text* through the configured formatting engine and
returns the generated string as its result. An error will be thrown if no
__-format__ was configured for the object.
The method assumes that the *text* is in
*[doctools](../../../../index.md#doctools)* format as specified in the
companion document *doctools_fmt*. Errors will be thrown otherwise.
- <a name='11'></a>*objectName* __map__ *symbolic* *actual*
This methods add one entry to the per-object mapping from *symbolic*
filenames to the *actual* uris. The object just stores this mapping and
makes it available to the configured formatting engine through the command
__dt_fmap__. This command is described in more detail in the *[doctools
plugin API reference](doctools_plugin_apiref.md)* which specifies the
interaction between the objects created by this package and doctools
formatting engines.
- <a name='12'></a>*objectName* __parameters__
This method returns a list containing the names of all engine parameters
provided by the configured formatting engine. It will return an empty list
if the object is not yet configured for a specific format.
- <a name='13'></a>*objectName* __search__ *path*
This method extends the per-object list of paths searched for doctools
formatting engines. See also the command __::doctools::search__ on how to
extend the per-package list of paths. Note that the path entered last will
be searched first. For more details see section [FORMAT
MAPPING](#subsection5).
- <a name='14'></a>*objectName* __setparam__ *name* *value*
This method sets the *name*d engine parameter to the specified *value*. It
will throw an error if the object is either not yet configured for a
specific format, or if the formatting engine for the configured format does
not provide a parameter with the given *name*. The list of parameters
provided by the configured formatting engine can be retrieved through the
method __parameters__.
- <a name='15'></a>*objectName* __warnings__
This method returns a list containing all the warnings which were generated
by the configured formatting engine during the last invocation of the method
__format__.
## <a name='subsection4'></a>OBJECT CONFIGURATION
All doctools objects understand the following configuration options:
- __-file__ *file*
The argument of this option is stored in the object and made available to
the configured formatting engine through the commands __dt_file__ and
__dt_mainfile__. These commands are described in more detail in the
companion document *doctools_api* which specifies the API between the object
and formatting engines.
The default value of this option is the empty string.
The configured formatting engine should interpret the value as the name of
the file containing the document which is currently processed.
- __-ibase__ *file*
The argument of this option is stored in the object and used as the base
path for resolution of relative include paths. If this option is not set
(empty string) the value of __-file__ is used instead.
Note that __-file__ and __-ibase__, while similar looking, are actually very
different. The value of __-file__ is used by some engines for the generation
of proper relative references between output documents (HTML). As such this
is a *destination* path. The __-ibase__ on the other hand is used to resolve
relative include paths, and as such deals with
*[source](../../../../index.md#source)* paths.
The default value of this option is the empty string.
- __-module__ *text*
The argument of this option is stored in the object and made available to
the configured formatting engine through the command __dt_module__. This
command is described in more detail in the companion document *doctools_api*
which specifies the API between the object and formatting engines.
The default value of this option is the empty string.
The configured formatting engine should interpret the value as the name of
the module the file containing the document which is currently processed
belongs to.
- __-format__ *text*
The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the method
__format__. Its default value is the empty string. The method __format__
cannot be used if this option is not set to a valid value at least once.
The package will immediately try to map the given name to a file containing
the code for a formatting engine generating that format. An error will be
thrown if this mapping fails. In that case a previously configured format is
left untouched.
The section [FORMAT MAPPING](#subsection5) explains in detail how the
package and object will look for engine implementations.
- __-deprecated__ *boolean*
This option is a boolean flag. The object will generate warnings if this
flag is set and the text given to method __format__ contains the deprecated
markup command __strong__. Its default value is __FALSE__. In other words,
no warnings will be generated.
- __-copyright__ *text*
The argument of this option is stored in the object and made available to
the configured formatting engine through the command __dt_copyright__. This
command is described in more detail in the companion document *doctools_api*
which specifies the API between the object and formatting engines.
The default value of this option is the empty string.
The configured formatting engine should interpret the value as a copyright
assignment for the document which is currently processed, or the package
described by it.
This information must be used if and only if the engine is unable to find
any copyright assignments within the document itself. Such are specified by
the formatting command __copyright__. This command is described in more
detail in the companion document *doctools_fmt* which specifies the
*[doctools](../../../../index.md#doctools)* format itself.
## <a name='subsection5'></a>FORMAT MAPPING
The package and object will perform the following algorithm when trying to map a
format name *foo* to a file containing an implementation of a formatting engine
for *foo*:
1. If *foo* is the name of an existing file then this file is directly taken
as the implementation.
1. If not, the list of per-object search paths is searched. For each directory
in the list the package checks if that directory contains a file
"fmt.*foo*". If yes, then that file is taken as the implementation.
Note that this list of paths is initially empty and can be extended through
the object method __search__.
1. If not, the list of package paths is searched. For each directory in the
list the package checks if that directory contains a file "fmt.*foo*". If
yes, then that file is taken as the implementation.
This list of paths can be extended through the command
__::doctools::search__. It contains initially one path, the subdirectory
"mpformats" of the directory the package itself is located in. In other
words, if the package implementation "doctools.tcl" is installed in the
directory "/usr/local/lib/tcllib/doctools" then it will by default search
the directory "/usr/local/lib/tcllib/doctools/mpformats" for format
implementations.
1. The mapping fails.
# <a name='section3'></a>PREDEFINED ENGINES
The package provides predefined engines for the following formats. Some of the
engines support parameters. These will be explained below as well.
- html
This engine generates HTML markup, for processing by web browsers and the
like. This engine supports four parameters:
* footer
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the empty
string. The value is inserted into the generated output just before the
__</body>__ tag, closing the body of the generated HTML.
This can be used to insert boilerplate footer markup into the generated
document.
* header
The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the empty
string. The value is inserted into the generated output just after the
__<body>__ tag, starting the body of the generated HTML.
This can be used to insert boilerplate header markup into the generated
document.
* meta
The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just after
the __<head>__ tag, starting the header section of the generated HTML.
This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.
* xref
The value for this parameter has to be a list of triples specifying
cross-reference information. This information is used by the engine to
create more hyperlinks. Each triple is a list containing a pattern,
symbolic filename and fragment reference, in this order. If a pattern is
specified multiple times the last occurrence of the pattern will be
used.
The engine will consult the xref database when encountering specific
commands and will create a link if the relevant text matches one of the
patterns. No link will be created if no match was found. The link will
go to the uri __file#fragment__ listed in the relevant triple, after
conversion of the symbolic file name to the actual uri via __dt_fmap__
(see the *[doctools plugin API reference](doctools_plugin_apiref.md)*).
This file-to-uri mapping was build by calls to the method __map__ of the
doctools object (See section [OBJECT METHODS](#subsection3)).
The following formatting commands will consult the xref database:
+ __cmd__ *word*
The command will look for the patterns __sa,__*word*, and *word*, in
this order. If this fails if it will convert *word* to all lowercase
and try again.
+ __syscmd__ *word*
The command will look for the patterns __sa,__*word*, and *word*, in
this order. If this fails if it will convert *word* to all lowercase
and try again.
+ __[term](../term/term.md)__ *word*
The command will look for the patterns __kw,__*word*, __sa,__*word*,
and *word*, in this order. If this fails if it will convert *word*
to all lowercase and try again.
+ __[package](../../../../index.md#package)__ *word*
The command will look for the patterns __sa,__*word*, __kw,__*word*,
and *word*, in this order. If this fails if it will convert *word*
to all lowercase and try again.
+ __see_also__ *word*...
The command will look for the patterns __sa,__*word*, and *word*, in
this order, for each *word* given to the command. If this fails if
it will convert *word* to all lowercase and try again.
+ __[keywords](../../../../index.md#keywords)__ *word*...
The command will look for the patterns __kw,__*word*, and *word*, in
this order, for each *word* given to the command. If this fails if
it will convert *word* to all lowercase and try again.
- latex
This engine generates output suitable for the
__[latex](../../../../index.md#latex)__ text processor coming out of the TeX
world.
- list
This engine retrieves version, section and title of the manpage from the
document. As such it can be used to generate a directory listing for a set
of manpages.
- nroff
This engine generates nroff output, for processing by
__[nroff](../../../../index.md#nroff)__, or __groff__. The result will be
standard man pages as they are known in the unix world.
- null
This engine generates no outout at all. This can be used if one just wants
to validate some input.
- tmml
This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.
- wiki
This engine generates Wiki markup as understood by Jean Claude Wippler's
__wikit__ application.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctools_intro](doctools_intro.md),
[doctools_lang_cmdref](doctools_lang_cmdref.md),
[doctools_lang_intro](doctools_lang_intro.md),
[doctools_lang_syntax](doctools_lang_syntax.md),
[doctools_plugin_apiref](doctools_plugin_apiref.md)
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion),
[documentation](../../../../index.md#documentation),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[nroff](../../../../index.md#nroff)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2017 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
[//000000001]: # (doctools_intro - Documentation tools)
[//000000002]: # (Generated from file 'doctools_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools_intro(n) 1.0 tcllib "Documentation tools")
# NAME
doctools_intro - doctools introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [RELATED FORMATS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[doctools](../../../../index.md#doctools)* (short for *documentation tools*)
stands for a set of related, yet different, entities which are working together
for the easy creation and transformation of documentation. These are
1. A tcl based language for the semantic markup of text. Markup is represented
by Tcl commands interspersed with the actual text.
1. A package providing the ability to read and transform texts written in that
markup language. It is important to note that the actual transformation of
the input text is delegated to plugins.
1. An API describing the interface between the package above and a plugin.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the documentation process.
1. A *writer* of documentation has to understand the markup language itself. A
beginner to doctools should read the more informally written *[doctools
language introduction](doctools_lang_intro.md)* first. Having digested this
the formal *[doctools language syntax](doctools_lang_syntax.md)*
specification should become understandable. A writer experienced with
doctools may only need the *[doctools language command
reference](doctools_lang_cmdref.md)* from time to time to refresh her
memory.
While a document is written the __[dtplite](../../apps/dtplite.md)__
application can be used to validate it, and after completion it also
performs the conversion into the chosen system of visual markup, be it
*roff, HTML, plain text, wiki, etc.
1. A *processor* of documentation written in the
*[doctools](../../../../index.md#doctools)* markup language has to know
which tools are available for use.
The main tool is the aforementioned __[dtplite](../../apps/dtplite.md)__
application provided by Tcllib. A more powerful one (in terms of options
and ability to configure it) is the __dtp__ application, provided by
Tclapps. At the bottom level, common to both applications, however sits the
package __[doctools](doctools.md)__, providing the basic facilities to read
and process files containing text in the doctools format.
1. At last, but not least, *plugin writers* have to understand the interaction
between the __[doctools](doctools.md)__ package and its plugins, as
described in the *[doctools plugin API
reference](doctools_plugin_apiref.md)*.
# <a name='section2'></a>RELATED FORMATS
doctools does not stand alone, it has two companion formats. These are called
*[docidx](../../../../index.md#docidx)* and
*[doctoc](../../../../index.md#doctoc)*, and they are for the markup of *keyword
indices*, and *tables of contents*, respectively. They are described in their
own sets of documents, starting at the *[docidx introduction](docidx_intro.md)*
and the *[doctoc introduction](doctoc_intro.md)*, respectively.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](docidx_intro.md), [doctoc_intro](doctoc_intro.md),
[doctools](doctools.md), [doctools_lang_cmdref](doctools_lang_cmdref.md),
[doctools_lang_faq](doctools_lang_faq.md),
[doctools_lang_intro](doctools_lang_intro.md),
[doctools_lang_syntax](doctools_lang_syntax.md),
[doctools_plugin_apiref](doctools_plugin_apiref.md)
# <a name='keywords'></a>KEYWORDS
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
|
[//000000001]: # (doctools_lang_cmdref - Documentation tools)
[//000000002]: # (Generated from file 'doctools_lang_cmdref.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools_lang_cmdref(n) 1.0 tcllib "Documentation tools")
# NAME
doctools_lang_cmdref - doctools language command reference
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__arg__ *text*](#1)
[__arg_def__ *type* *name* ?*mode*?](#2)
[__bullet__](#3)
[__call__ *args*](#4)
[__category__ *text*](#5)
[__[class](../../../../index.md#class)__ *text*](#6)
[__cmd__ *text*](#7)
[__cmd_def__ *command*](#8)
[__[comment](../../../../index.md#comment)__ *plaintext*](#9)
[__const__ *text*](#10)
[__copyright__ *text*](#11)
[__def__ *text*](#12)
[__description__](#13)
[__enum__](#14)
[__emph__ *text*](#15)
[__example__ *text*](#16)
[__example_begin__](#17)
[__example_end__](#18)
[__[file](../../../../index.md#file)__ *text*](#19)
[__fun__ *text*](#20)
[__[image](../../../../index.md#image)__ *name* ?*label*?](#21)
[__include__ *filename*](#22)
[__item__](#23)
[__[keywords](../../../../index.md#keywords)__ *args*](#24)
[__lb__](#25)
[__list_begin__ *what*](#26)
[__list_end__](#27)
[__lst_item__ *text*](#28)
[__manpage_begin__ *command* *section* *version*](#29)
[__manpage_end__](#30)
[__[method](../../../../index.md#method)__ *text*](#31)
[__moddesc__ *text*](#32)
[__namespace__ *text*](#33)
[__nl__](#34)
[__opt__ *text*](#35)
[__opt_def__ *name* ?*arg*?](#36)
[__option__ *text*](#37)
[__[package](../../../../index.md#package)__ *text*](#38)
[__para__](#39)
[__rb__](#40)
[__require__ *package* ?*version*?](#41)
[__section__ *name*](#42)
[__sectref__ *id* ?*text*?](#43)
[__sectref-external__ *text*](#44)
[__see_also__ *args*](#45)
[__strong__ *text*](#46)
[__subsection__ *name*](#47)
[__syscmd__ *text*](#48)
[__[term](../term/term.md)__ *text*](#49)
[__titledesc__ *desc*](#50)
[__tkoption_def__ *name* *dbname* *dbclass*](#51)
[__[type](../../../../index.md#type)__ *text*](#52)
[__[uri](../uri/uri.md)__ *text* ?*text*?](#53)
[__usage__ *args*](#54)
[__var__ *text*](#55)
[__vset__ *varname* *value*](#56)
[__vset__ *varname*](#57)
[__[widget](../../../../index.md#widget)__ *text*](#58)
# <a name='description'></a>DESCRIPTION
This document specifies both names and syntax of all the commands which together
are the doctools markup language, version 1. As this document is intended to be
a reference the commands are listed in alphabetical order, and the descriptions
are relatively short. A beginner should read the much more informally written
*[doctools language introduction](doctools_lang_intro.md)* first.
# <a name='section2'></a>Commands
- <a name='1'></a>__arg__ *text*
Text markup. The argument text is marked up as the *argument* of a command.
Main uses are the highlighting of command arguments in free-form text, and
for the argument parameters of the markup commands __call__ and __usage__.
- <a name='2'></a>__arg_def__ *type* *name* ?*mode*?
Text structure. List element. Argument list. Automatically closes the
previous list element. Specifies the data-*type* of the described argument
of a command, its *name* and its i/o-*mode*. The latter is optional.
- <a name='3'></a>__bullet__
*Deprecated*. Text structure. List element. Itemized list. See __item__ for
the canonical command to open a list item in an itemized list.
- <a name='4'></a>__call__ *args*
Text structure. List element. Definition list. Automatically closes the
previous list element. Defines the term as a command and its arguments. The
first argument is the name of the command described by the following
free-form text, and all arguments coming after that are descriptions of the
command's arguments. It is expected that the arguments are marked up with
__arg__, __[method](../../../../index.md#method)__, __option__ etc., as is
appropriate, and that the command itself is marked up with __cmd__. It is
expected that the formatted term is not only printed in place, but also in
the table of contents of the document, or synopsis, depending on the output
format.
- <a name='5'></a>__category__ *text*
Document information. Anywhere. This command registers its plain text
arguments as the category this document belongs to. If this command is used
multiple times the last value specified is used.
- <a name='6'></a>__[class](../../../../index.md#class)__ *text*
Text markup. The argument is marked up as the name of a
*[class](../../../../index.md#class)*. The text may have other markup
already applied to it. Main use is the highlighting of class names in
free-form text.
- <a name='7'></a>__cmd__ *text*
Text markup. The argument text is marked up as the name of a *Tcl command*.
The text may have other markup already applied to it. Main uses are the
highlighting of commands in free-form text, and for the command parameters
of the markup commands __call__ and __usage__.
- <a name='8'></a>__cmd_def__ *command*
Text structure. List element. Command list. Automatically closes the
previous list element. The argument specifies the name of the *Tcl command*
to be described by the list element. Expected to be marked up in the output
as if it had been formatted with __cmd__.
- <a name='9'></a>__[comment](../../../../index.md#comment)__ *plaintext*
Text markup. The argument text is marked up as a comment standing outside of
the actual text of the document. Main use is in free-form text.
- <a name='10'></a>__const__ *text*
Text markup. The argument is marked up as a *constant* value. The text may
have other markup already applied to it. Main use is the highlighting of
constants in free-form text.
- <a name='11'></a>__copyright__ *text*
Document information. Anywhere. The command registers the plain text
argument as a copyright assignment for the manpage. When invoked more than
once the assignments are accumulated.
- <a name='12'></a>__def__ *text*
Text structure. List element. Definition list. Automatically closes the
previous list element. The argument text is the term defined by the new list
element. Text markup can be applied to it.
- <a name='13'></a>__description__
Document structure. This command separates the header from the document
body. Implicitly starts a section named "DESCRIPTION" (See command
__section__).
- <a name='14'></a>__enum__
Text structure. List element. Enumerated list. Automatically closes the
previous list element.
- <a name='15'></a>__emph__ *text*
Text markup. The argument text is marked up as emphasized. Main use is for
general highlighting of pieces of free-form text without attaching special
meaning to the pieces.
- <a name='16'></a>__example__ *text*
Text structure, Text markup. This command marks its argument up as an
*example*. Main use is the simple embedding of examples in free-form text.
It should be used if the example does *not* need special markup of its own.
Otherwise use a sequence of __example_begin__ ... __example_end__.
- <a name='17'></a>__example_begin__
Text structure. This commands starts an example. All text until the next
__example_end__ belongs to the example. Line breaks, spaces, and tabs have
to be preserved literally. Examples cannot be nested.
- <a name='18'></a>__example_end__
Text structure. This command closes the example started by the last
__example_begin__.
- <a name='19'></a>__[file](../../../../index.md#file)__ *text*
Text markup. The argument is marked up as a
*[file](../../../../index.md#file)* or *directory*, i.e. in general a
*path*. The text may have other markup already applied to it. Main use is
the highlighting of paths in free-form text.
- <a name='20'></a>__fun__ *text*
Text markup. The argument is marked up as the name of a *function*. The text
may have other markup already applied to it. Main use is the highlighting of
function names in free-form text.
- <a name='21'></a>__[image](../../../../index.md#image)__ *name* ?*label*?
Text markup. The argument is the symbolic name of an
*[image](../../../../index.md#image)* and replaced with the image itself, if
a suitable variant is found by the backend. The second argument, should it
be present, will be interpreted the human-readable description of the image,
and put into the output in a suitable position, if such is supported by the
format. The HTML format, for example, can place it into the *alt* attribute
of image references.
- <a name='22'></a>__include__ *filename*
Templating. The contents of the named file are interpreted as text written
in the doctools markup and processed in the place of the include command.
The markup in the file has to be self-contained. It is not possible for a
markup command to cross the file boundaries.
- <a name='23'></a>__item__
Text structure. List element. Itemized list. Automatically closes the
previous list element.
- <a name='24'></a>__[keywords](../../../../index.md#keywords)__ *args*
Document information. Anywhere. This command registers all its plain text
arguments as keywords applying to this document. Each argument is a single
keyword. If this command is used multiple times all the arguments
accumulate.
- <a name='25'></a>__lb__
Text. The command is replaced with a left bracket. Use in free-form text.
Required to avoid interpretation of a left bracket as the start of a markup
command.
- <a name='26'></a>__list_begin__ *what*
Text structure. This command starts a list. The exact nature of the list is
determined by the argument *what* of the command. This further determines
which commands are have to be used to start the list elements. Lists can be
nested, i.e. it is allowed to start a new list within a list element.
The allowed types (and their associated item commands) are:
* __arguments__
__arg_def__.
* __commands__
__cmd_def__.
* __definitions__
__def__ and __call__.
* __enumerated__
__enum__
* __itemized__
__item__
* __options__
__opt_def__
* __tkoptions__
__tkoption_def__
Additionally the following names are recognized as shortcuts for some of the
regular types:
* __args__
Short for __arguments__.
* __cmds__
Short for __commands__.
* __enum__
Short for __enumerated__.
* __item__
Short for __itemized__.
* __opts__
Short for __options__.
At last the following names are still recognized for backward compatibility,
but are otherwise considered to be *deprecated*.
* __arg__
*Deprecated*. See __arguments__.
* __bullet__
*Deprecated*. See __itemized__.
* __cmd__
*Deprecated*. See __commands__.
* __opt__
*Deprecated*. See __options__.
* __tkoption__
*Deprecated*. See __tkoptions__.
- <a name='27'></a>__list_end__
Text structure. This command closes the list opened by the last
__list_begin__ command coming before it.
- <a name='28'></a>__lst_item__ *text*
*Deprecated*. Text structure. List element. Definition list. See __def__ for
the canonical command to open a general list item in a definition list.
- <a name='29'></a>__manpage_begin__ *command* *section* *version*
Document structure. The command to start a manpage. The arguments are the
name of the *command* described by the manpage, the *section* of the
manpages this manpage resides in, and the *version* of the module containing
the command. All arguments have to be plain text, without markup.
- <a name='30'></a>__manpage_end__
Document structure. Command to end a manpage/document. Anything in the
document coming after this command is in error.
- <a name='31'></a>__[method](../../../../index.md#method)__ *text*
Text markup. The argument text is marked up as the name of an
*[object](../../../../index.md#object)*
*[method](../../../../index.md#method)*, i.e. subcommand of a Tcl command.
The text may have other markup already applied to it. Main uses are the
highlighting of method names in free-form text, and for the command
parameters of the markup commands __call__ and __usage__.
- <a name='32'></a>__moddesc__ *text*
Document information. Header. Registers the plain text argument as a short
description of the module the manpage resides in.
- <a name='33'></a>__namespace__ *text*
Text markup. The argument text is marked up as a namespace name. The text
may have other markup already applied to it. Main use is the highlighting of
namespace names in free-form text.
- <a name='34'></a>__nl__
*Deprecated*. Text structure. See __para__ for the canonical command to
insert paragraph breaks into the text.
- <a name='35'></a>__opt__ *text*
Text markup. The argument text is marked up as *optional*. The text may have
other markup already applied to it. Main use is the highlighting of optional
arguments, see the command arg __arg__.
- <a name='36'></a>__opt_def__ *name* ?*arg*?
Text structure. List element. Option list. Automatically closes the previous
list element. Specifies *name* and arguments of the *option* described by
the list element. It is expected that the name is marked up using
__option__.
- <a name='37'></a>__option__ *text*
Text markup. The argument is marked up as *option*. The text may have other
markup already applied to it. Main use is the highlighting of options, also
known as command-switches, in either free-form text, or the arguments of the
__call__ and __usage__ commands.
- <a name='38'></a>__[package](../../../../index.md#package)__ *text*
Text markup. The argument is marked up as the name of a
*[package](../../../../index.md#package)*. The text may have other markup
already applied to it. Main use is the highlighting of package names in
free-form text.
- <a name='39'></a>__para__
Text structure. This command breaks free-form text into paragraphs. Each
command closes the paragraph coming before it and starts a new paragraph for
the text coming after it. Higher-level forms of structure are sections and
subsections.
- <a name='40'></a>__rb__
Text. The command is replaced with a right bracket. Use in free-form text.
Required to avoid interpretation of a right bracket as the end of a markup
command.
- <a name='41'></a>__require__ *package* ?*version*?
Document information. Header. This command registers its argument *package*
as the name of a package or application required by the described package or
application. A minimum version can be provided as well. This argument can be
marked up. The usual markup is __opt__.
- <a name='42'></a>__section__ *name*
Text structure. This command starts a new named document section. The
argument has to be plain text. Implicitly closes the last paragraph coming
before it and also implicitly opens the first paragraph of the new section.
- <a name='43'></a>__sectref__ *id* ?*text*?
Text markup. Formats a reference to the section identified by *id*. If no
*text* is specified the title of the referenced section is used in the
output, otherwise *text* is used.
- <a name='44'></a>__sectref-external__ *text*
Text markup. Like __sectref__, except that the section is assumed to be in a
different document and therefore doesn't need to be identified, nor are any
checks for existence made. Only the text to format is needed.
- <a name='45'></a>__see_also__ *args*
Document information. Anywhere. The command defines direct cross-references
to other documents. Each argument is a plain text label identifying the
referenced document. If this command is used multiple times all the
arguments accumulate.
- <a name='46'></a>__strong__ *text*
*Deprecated*. Text markup. See __emph__ for the canonical command to
emphasize text.
- <a name='47'></a>__subsection__ *name*
Text structure. This command starts a new named subsection of a section. The
argument has to be plain text. Implicitly closes the last paragraph coming
before it and also implicitly opens the first paragraph of the new
subsection.
- <a name='48'></a>__syscmd__ *text*
Text markup. The argument text is marked up as the name of an external
command. The text may have other markup already applied to it. Main use is
the highlighting of external commands in free-form text.
- <a name='49'></a>__[term](../term/term.md)__ *text*
Text markup. The argument is marked up as unspecific terminology. The text
may have other markup already applied to it. Main use is the highlighting of
important terms and concepts in free-form text.
- <a name='50'></a>__titledesc__ *desc*
Document information. Header. Optional. Registers the plain text argument as
the title of the manpage. Defaults to the value registered by __moddesc__.
- <a name='51'></a>__tkoption_def__ *name* *dbname* *dbclass*
Text structure. List element. Widget option list. Automatically closes the
previous list element. Specifies the *name* of the option as used in
scripts, the name used by the option database (*dbname*), and its class
(*dbclass*), i.e. its type. It is expected that the name is marked up using
__option__.
- <a name='52'></a>__[type](../../../../index.md#type)__ *text*
Text markup. The argument is marked up as the name of a *data type*. The
text may have other markup already applied to it. Main use is the
highlighting of data types in free-form text.
- <a name='53'></a>__[uri](../uri/uri.md)__ *text* ?*text*?
Text markup. The argument is marked up as an
*[uri](../../../../index.md#uri)* (i.e. a *uniform resource identifier*. The
text may have other markup already applied to it. Main use is the
highlighting of uris in free-form text. The second argument, should it be
present, will be interpreted the human-readable description of the uri. In
other words, as its label. Without an explicit label the uri will be its own
label.
- <a name='54'></a>__usage__ *args*
Text markup. See __call__ for the full description, this command is
syntactically identical, as it is in its expectations for the markup of its
arguments. In contrast to __call__ it is however not allowed to generate
output where this command occurs in the text. The command is *silent*. The
formatted text may only appear in a different section of the output, for
example a table of contents, or synopsis, depending on the output format.
- <a name='55'></a>__var__ *text*
Text markup. The argument is marked up as the name of a *variable*. The text
may have other markup already applied to it. Main use is the highlighting of
variables in free-form text.
- <a name='56'></a>__vset__ *varname* *value*
Templating. In this form the command sets the named document variable to the
specified *value*. It does not generate output. I.e. the command is replaced
by the empty string.
- <a name='57'></a>__vset__ *varname*
Templating. In this form the command is replaced by the value of the named
document variable
- <a name='58'></a>__[widget](../../../../index.md#widget)__ *text*
Text markup. The argument is marked up as the name of a
*[widget](../../../../index.md#widget)*. The text may have other markup
already applied to it. Main use is the highlighting of widget names in
free-form text.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctools_intro](doctools_intro.md), [doctools_lang_faq](doctools_lang_faq.md),
[doctools_lang_intro](doctools_lang_intro.md),
[doctools_lang_syntax](doctools_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[doctools commands](../../../../index.md#doctools_commands), [doctools
language](../../../../index.md#doctools_language), [doctools
markup](../../../../index.md#doctools_markup),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2010 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools_lang_faq.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
[//000000001]: # (doctools_lang_faq - Documentation tools)
[//000000002]: # (Generated from file 'doctools_lang_faq.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools_lang_faq(n) 1.0 tcllib "Documentation tools")
# NAME
doctools_lang_faq - doctools language faq
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [OVERVIEW](#section2)
- [What is this document?](#subsection1)
- [EXAMPLES](#section3)
- [Where do I find doctools examples?](#subsection2)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>OVERVIEW
## <a name='subsection1'></a>What is this document?
This document is currently mainly a placeholder, to be filled with commonly
asked questions about the doctools markup language and companions, and their
answers.
Please report any questions (and, if possible, answers) we should consider for
this document as explained in the section [Bugs, Ideas, Feedback](#section4)
below.
# <a name='section3'></a>EXAMPLES
## <a name='subsection2'></a>Where do I find doctools examples?
We have no direct examples of documents written using doctools markup. However
the doctools processor __[dtplite](../../apps/dtplite.md)__ does generate a
table of contents when processing a set of documents written in doctools markup.
The intermediate file for it uses doctools markup and is not deleted when
generation completes. Such files can therefore serve as examples.
__[dtplite](../../apps/dtplite.md)__ is distributed as part of Tcllib, so to get
it you need one of
1. A snapshot of Tcllib. How to retrieve such a snapshot and the tools
required for this are described at [Development
Snapshots](/wiki?name=Development+Snapshots)
1. A Tcllib release archive. They are available at the [home](/home) page.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctools_lang_cmdref](doctools_lang_cmdref.md),
[doctools_lang_intro](doctools_lang_intro.md),
[doctools_lang_syntax](doctools_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[doctools commands](../../../../index.md#doctools_commands), [doctools
language](../../../../index.md#doctools_language), [doctools
markup](../../../../index.md#doctools_markup), [doctools
syntax](../../../../index.md#doctools_syntax),
[examples](../../../../index.md#examples), [faq](../../../../index.md#faq),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
|
[//000000001]: # (doctools_lang_intro - Documentation tools)
[//000000002]: # (Generated from file 'doctools_lang_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools_lang_intro(n) 1.0 tcllib "Documentation tools")
# NAME
doctools_lang_intro - doctools language introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#subsection1)
- [Basic structure](#subsection2)
- [Advanced structure](#subsection3)
- [Text structure](#subsection4)
- [Text markup](#subsection5)
- [Escapes](#subsection6)
- [Cross-references](#subsection7)
- [Examples](#subsection8)
- [Lists](#subsection9)
- [FURTHER READING](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document is an informal introduction to version 1 of the doctools markup
language based on a multitude of examples. After reading this a writer should be
ready to understand the two parts of the formal specification, i.e. the
*[doctools language syntax](doctools_lang_syntax.md)* specification and the
*[doctools language command reference](doctools_lang_cmdref.md)*.
## <a name='subsection1'></a>Fundamentals
In the broadest terms possible the *doctools markup language* is LaTeX-like,
instead of like SGML and similar languages. A document written in this language
consists primarily of text, with markup commands embedded into it.
Each markup command is a Tcl command surrounded by a matching pair of __[__ and
__]__. Inside of these delimiters the usual rules for a Tcl command apply with
regard to word quotation, nested commands, continuation lines, etc. I.e.
... [list_begin enumerated] ...
... [call [cmd foo] \\
[arg bar]] ...
... [term {complex concept}] ...
... [opt "[arg key] [arg value]"] ...
## <a name='subsection2'></a>Basic structure
The most simple document which can be written in doctools is
[manpage_begin NAME SECTION VERSION]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_faq]
[see_also doctools_lang_syntax]
[keywords {doctools commands}]
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
[description]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
This also shows us that all doctools documents are split into two parts, the
*header* and the *body*. Everything coming before [__description__] belongs to
the header, and everything coming after belongs to the body, with the whole
document bracketed by the two __manpage_*__ commands. Before and after these
opening and closing commands we have only *whitespace*.
In the remainder of this section we will discuss only the contents of the
header, the structure of the body will be discussed in the section [Text
structure](#subsection4).
The header section can be empty, and otherwise may contain only an arbitrary
sequence of the four so-called *header* commands, plus *whitespace*. These
commands are
- __titledesc__
- __moddesc__
- __require__
- __copyright__
They provide, through their arguments, additional information about the
document, like its title, the title of the larger group the document belongs to
(if applicable), the requirements of the documented packages (if applicable),
and copyright assignments. All of them can occur multiple times, including none,
and they can be used in any order. However for __titledesc__ and __moddesc__
only the last occurrence is taken. For the other two the specified information
is accumulated, in the given order. Regular text is not allowed within the
header.
Given the above a less minimal example of a document is
[manpage_begin NAME SECTION VERSION]
[__copyright {YEAR AUTHOR}__]
[__titledesc TITLE__]
[__moddesc MODULE_TITLE__]
[__require PACKAGE VERSION__]
[__require PACKAGE__]
[description]
[manpage_end]
Remember that the whitespace is optional. The document
[manpage_begin NAME SECTION VERSION]
[copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
[require PACKAGE VERSION][require PACKAGE][description]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
has the same meaning as the example before.
On the other hand, if *whitespace* is present it consists not only of any
sequence of characters containing the space character, horizontal and vertical
tabs, carriage return, and newline, but it may contain comment markup as well,
in the form of the __[comment](../../../../index.md#comment)__ command.
[__comment { ... }__]
[manpage_begin NAME SECTION VERSION]
[copyright {YEAR AUTHOR}]
[titledesc TITLE]
[moddesc MODULE_TITLE][__comment { ... }__]
[require PACKAGE VERSION]
[require PACKAGE]
[description]
[manpage_end]
[__comment { ... }__]
## <a name='subsection3'></a>Advanced structure
In the simple examples of the last section we fudged a bit regarding the markup
actually allowed to be used before the __manpage_begin__ command opening the
document.
Instead of only whitespace the two templating commands __include__ and __vset__
are also allowed, to enable the writer to either set and/or import configuration
settings relevant to the document. I.e. it is possible to write
[__include FILE__]
[__vset VAR VALUE__]
[manpage_begin NAME SECTION VERSION]
[description]
[manpage_end]
Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure. I.e. for example in
the header as well.
[manpage_begin NAME SECTION VERSION]
[__include FILE__]
[__vset VAR VALUE__]
[description]
[manpage_end]
The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion. I.e. a file included
before __manpage_begin__ may contain only the templating commands __vset__ and
__include__, a file included in the header may contain only header commands,
etc.
## <a name='subsection4'></a>Text structure
The body of the document consists mainly of text, possibly split into sections,
subsections, and paragraphs, with parts marked up to highlight various semantic
categories of text, and additional structure through the use of examples and
(nested) lists.
This section explains the high-level structural commands, with everything else
deferred to the following sections.
The simplest way of structuring the body is through the introduction of
paragraphs. The command for doing so is __para__. Each occurrence of this
command closes the previous paragraph and automatically opens the next. The
first paragraph is automatically opened at the beginning of the body, by
__description__. In the same manner the last paragraph automatically ends at
__manpage_end__.
[manpage_begin NAME SECTION VERSION]
[description]
...
[__para__]
...
[__para__]
...
[manpage_end]
Empty paragraphs are ignored.
A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces. The command for doing so is
__section__. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph. The first section
is automatically opened at the beginning of the body, by __description__ (This
section is labeled "DESCRIPTION"). In the same manner the last section
automatically ends at __manpage_end__.
Empty sections are *not* ignored. We are free to (not) use paragraphs within
sections.
[manpage_begin NAME SECTION VERSION]
[description]
...
[__section {Section A}__]
...
[para]
...
[__section {Section B}__]
...
[manpage_end]
Between sections and paragraphs we have subsections, to split sections. The
command for doing so is __subsection__. Each occurrence of this command closes
the previous subsection and automatically opens the next, including its first
paragraph. A subsection is automatically opened at the beginning of the body, by
__description__, and at the beginning of each section. In the same manner the
last subsection automatically ends at __manpage_end__.
Empty subsections are *not* ignored. We are free to (not) use paragraphs within
subsections.
[manpage_begin NAME SECTION VERSION]
[description]
...
[section {Section A}]
...
[__subsection {Sub 1}__]
...
[para]
...
[__subsection {Sub 2}__]
...
[section {Section B}]
...
[manpage_end]
## <a name='subsection5'></a>Text markup
Having handled the overall structure a writer can impose on the document we now
take a closer at the text in a paragraph.
While most often this is just the unadorned content of the document we do have
situations where we wish to highlight parts of it as some type of thing or
other, like command arguments, command names, concepts, uris, etc.
For this we have a series of markup commands which take the text to highlight as
their single argument. It should be noted that while their predominant use is
the highlighting of parts of a paragraph they can also be used to mark up the
arguments of list item commands, and of other markup commands.
The commands available to us are
- __arg__
Its argument is a the name of a command argument.
- __[class](../../../../index.md#class)__
Its argument is a class name.
- __cmd__
Its argument is a command name (Tcl command).
- __const__
Its argument is a constant.
- __emph__
General, non-semantic emphasis.
- __[file](../../../../index.md#file)__
Its argument is a filename / path.
- __fun__
Its argument is a function name.
- __[method](../../../../index.md#method)__
Its argument is a method name
- __namespace__
Its argument is namespace name.
- __opt__
Its argument is some optional syntax element.
- __option__
Its argument is a command line switch / widget option.
- __[package](../../../../index.md#package)__
Its argument is a package name.
- __sectref__
Its argument is the title of a section or subsection, i.e. a section
reference.
- __syscmd__
Its argument is a command name (external, system command).
- __[term](../term/term.md)__
Its argument is a concept, or general terminology.
- __[type](../../../../index.md#type)__
Its argument is a type name.
- __[uri](../uri/uri.md)__
Its argument is a uniform resource identifier, i.e an external reference. A
second argument can be used to specify an explicit label for the reference
in question.
- __usage__
The arguments describe the syntax of a Tcl command.
- __var__
Its argument is a variable.
- __[widget](../../../../index.md#widget)__
Its argument is a widget name.
The example demonstrating the use of text markup is an excerpt from the
*[doctools language command reference](doctools_lang_cmdref.md)*, with some
highlighting added. It shows their use within a block of text, as the arguments
of a list item command (__call__), and our ability to nest them.
...
[call [__cmd arg_def__] [__arg type__] [__arg name__] [__opt__ [__arg mode__]]]
Text structure. List element. Argument list. Automatically closes the
previous list element. Specifies the data-[__arg type__] of the described
argument of a command, its [__arg name__] and its i/o-[__arg mode__]. The
latter is optional.
...
## <a name='subsection6'></a>Escapes
Beyond the 20 commands for simple markup shown in the previous section we have
two more available which are technically simple markup. However their function
is not the marking up of phrases as specific types of things, but the insertion
of characters, namely __[__ and __]__. These commands, __lb__ and __rb__
respectively, are required because our use of [ and ] to bracket markup commands
makes it impossible to directly use [ and ] within the text.
Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added.
...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [__lb__] and [__rb__] to bracket markup commands makes it
impossible to directly use [__lb__] and [__rb__] within the text.
...
## <a name='subsection7'></a>Cross-references
The last two commands we have to discuss are for the declaration of
cross-references between documents, explicit and implicit. They are
__[keywords](../../../../index.md#keywords)__ and __see_also__. Both take an
arbitrary number of arguments, all of which have to be plain unmarked text. I.e.
it is not allowed to use markup on them. Both commands can be used multiple
times in a document. If that is done all arguments of all occurrences of one of
them are put together into a single set.
- __[keywords](../../../../index.md#keywords)__
The arguments of this command are interpreted as keywords describing the
document. A processor can use this information to create an index indirectly
linking the containing document to all documents with the same keywords.
- __see_also__
The arguments of this command are interpreted as references to other
documents. A processor can format them as direct links to these documents.
All the cross-reference commands can occur anywhere in the document between
__manpage_begin__ and __manpage_end__. As such the writer can choose whether she
wants to have them at the beginning of the body, or at its end, maybe near the
place a keyword is actually defined by the main content, or considers them as
meta data which should be in the header, etc.
Our example shows the sources for the cross-references of this document, with
some highlighting added. Incidentally they are found at the end of the body.
...
[__see_also doctools_intro__]
[__see_also doctools_lang_syntax__]
[__see_also doctools_lang_cmdref__]
[__keywords markup {semantic markup}__]
[__keywords {doctools markup} {doctools language}__]
[__keywords {doctools syntax} {doctools commands}__]
[manpage_end]
## <a name='subsection8'></a>Examples
Where ever we can write plain text we can write examples too. For simple
examples we have the command __example__ which takes a single argument, the text
of the argument. The example text must not contain markup. If we wish to have
markup within an example we have to use the 2-command combination
__example_begin__ / __example_end__ instead.
The first opens an example block, the other closes it, and in between we can
write plain text and use all the regular text markup commands. Note that text
structure commands are not allowed. This also means that it is not possible to
embed examples and lists within an example. On the other hand, we *can* use
templating commands within example blocks to read their contents from a file
(Remember section [Advanced structure](#subsection3)).
The source for the very first example in this document (see section
[Fundamentals](#subsection1)), with some highlighting added, is
[__example__ {
... [list_begin enumerated] ...
}]
Using __example_begin__ / __example_end__ this would look like
[__example_begin__]
... [list_begin enumerated] ...
[__example_end__]
## <a name='subsection9'></a>Lists
Where ever we can write plain text we can write lists too. The main commands are
__list_begin__ to start a list, and __list_end__ to close one. The opening
command takes an argument specifying the type of list started it, and this in
turn determines which of the eight existing list item commands are allowed
within the list to start list items.
After the opening command only whitespace is allowed, until the first list item
command opens the first item of the list. Each item is a regular series of
paragraphs and is closed by either the next list item command, or the end of the
list. If closed by a list item command this command automatically opens the next
list item. A consequence of a list item being a series of paragraphs is that all
regular text markup can be used within a list item, including examples and other
lists.
The list types recognized by __list_begin__ and their associated list item
commands are:
- __arguments__
(__arg_def__) This opens an *argument (declaration) list*. It is a
specialized form of a term definition list where the term is an argument
name, with its type and i/o-mode.
- __commands__
(__cmd_def__) This opens a *command (declaration) list*. It is a specialized
form of a term definition list where the term is a command name.
- __definitions__
(__def__ and __call__) This opens a general *term definition list*. The
terms defined by the list items are specified through the argument(s) of the
list item commands, either general terms, possibly with markup (__def__), or
Tcl commands with their syntax (__call__).
- __enumerated__
(__enum__) This opens a general *enumerated list*.
- __itemized__
(__item__) This opens a general *itemized list*.
- __options__
(__opt_def__) This opens an *option (declaration) list*. It is a specialized
form of a term definition list where the term is an option name, possibly
with the option's arguments.
- __tkoptions__
(__tkoption_def__) This opens a *widget option (declaration) list*. It is a
specialized form of a term definition list where the term is the name of a
configuration option for a widget, with its name and class in the option
database.
Our example is the source of the definition list in the previous paragraph, with
most of the content in the middle removed.
...
[__list_begin__ definitions]
[__def__ [const arg]]
([cmd arg_def]) This opens an argument (declaration) list. It is a
specialized form of a definition list where the term is an argument
name, with its type and i/o-mode.
[__def__ [const itemized]]
([cmd item])
This opens a general itemized list.
...
[__def__ [const tkoption]]
([cmd tkoption_def]) This opens a widget option (declaration) list. It
is a specialized form of a definition list where the term is the name
of a configuration option for a widget, with its name and class in the
option database.
[__list_end__]
...
Note that a list cannot begin in one (sub)section and end in another.
Differently said, (sub)section breaks are not allowed within lists and list
items. An example of this *illegal* construct is
...
[list_begin itemized]
[item]
...
[__section {ILLEGAL WITHIN THE LIST}__]
...
[list_end]
...
# <a name='section2'></a>FURTHER READING
Now that this document has been digested the reader, assumed to be a *writer* of
documentation should be fortified enough to be able to understand the formal
*[doctools language syntax](doctools_lang_syntax.md)* specification as well.
From here on out the *[doctools language command
reference](doctools_lang_cmdref.md)* will also serve as the detailed
specification and cheat sheet for all available commands and their syntax.
To be able to validate a document while writing it, it is also recommended to
familiarize oneself with one of the applications for the processing and
conversion of doctools documents, i.e. either Tcllib's easy and simple
__[dtplite](../../apps/dtplite.md)__, or Tclapps' ultra-configurable __dtp__.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctools_intro](doctools_intro.md),
[doctools_lang_cmdref](doctools_lang_cmdref.md),
[doctools_lang_faq](doctools_lang_faq.md),
[doctools_lang_syntax](doctools_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[doctools commands](../../../../index.md#doctools_commands), [doctools
language](../../../../index.md#doctools_language), [doctools
markup](../../../../index.md#doctools_markup), [doctools
syntax](../../../../index.md#doctools_syntax),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools_lang_syntax.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
[//000000001]: # (doctools_lang_syntax - Documentation tools)
[//000000002]: # (Generated from file 'doctools_lang_syntax.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools_lang_syntax(n) 1.0 tcllib "Documentation tools")
# NAME
doctools_lang_syntax - doctools language syntax
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Fundamentals](#section2)
- [Lexical definitions](#section3)
- [Syntax](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document contains the formal specification of the syntax of the doctools
markup language, version 1 in Backus-Naur-Form. This document is intended to be
a reference, complementing the *[doctools language command
reference](doctools_lang_cmdref.md)*. A beginner should read the much more
informally written *[doctools language introduction](doctools_lang_intro.md)*
first before trying to understand either this document or the command reference.
# <a name='section2'></a>Fundamentals
In the broadest terms possible the *doctools markup language* is LaTeX-like,
instead of like SGML and similar languages. A document written in this language
consists primarily of text, with markup commands embedded into it.
Each markup command is a just Tcl command surrounded by a matching pair of __[__
and __]__. Which commands are available, and their arguments, i.e. syntax is
specified in the *[doctools language command
reference](doctools_lang_cmdref.md)*.
In this document we specify first the lexeme, and then the syntax, i.e. how we
can mix text and markup commands with each other.
# <a name='section3'></a>Lexical definitions
In the syntax rules listed in the next section
1. <TEXT> stands for all text except markup commands.
1. Any XXX stands for the markup command [xxx] including its arguments. Each
markup command is a Tcl command surrounded by a matching pair of __[__ and
__]__. Inside of these delimiters the usual rules for a Tcl command apply
with regard to word quotation, nested commands, continuation lines, etc.
1. <WHITE> stands for all text consisting only of spaces, newlines, tabulators
and the __[comment](../../../../index.md#comment)__ markup command.
# <a name='section4'></a>Syntax
The rules listed here specify only the syntax of doctools documents. The lexical
level of the language was covered in the previous section.
Regarding the syntax of the (E)BNF itself
1. The construct { X } stands for zero or more occurrences of X.
1. The construct [ X ] stands for zero or one occurrence of X.
1. The construct LIST_BEGIN<X> stands for the markup command __list_begin__
with __X__ as its type argument.
The syntax:
manpage = defs
MANPAGE_BEGIN
header
DESCRIPTION
body
MANPAGE_END
{ <WHITE> }
defs = { INCLUDE | VSET | <WHITE> }
header = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
xref = KEYWORDS | SEE_ALSO | CATEGORY
body = paras { SECTION sbody }
sbody = paras { SUBSECTION ssbody }
ssbody = paras
paras = tblock { (PARA | NL) tblock }
tblock = { <TEXT> | defs | markup | xref | an_example | a_list }
markup = ARG | CLASS | CMD | CONST | EMPH | FILE
| FUN | LB | METHOD | NAMESPACE | OPT | OPTION
| PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM
| TYPE | URI | USAGE | VAR | WIDGET
example = EXAMPLE
| EXAMPLE_BEGIN extext EXAMPLE_END
extext = { <TEXT> | defs | markup }
a_list = LIST_BEGIN<arguments> argd_list LIST_END
| LIST_BEGIN<commands> cmdd_list LIST_END
| LIST_BEGIN<definitions> def_list LIST_END
| LIST_BEGIN<enumerated> enum_list LIST_END
| LIST_BEGIN<itemized> item_list LIST_END
| LIST_BEGIN<options> optd_list LIST_END
| LIST_BEGIN<tkoptions> tkoptd_list LIST_END
argd_list = [ <WHITE> ] { ARG_DEF paras }
cmdd_list = [ <WHITE> ] { CMD_DEF paras }
def_list = [ <WHITE> ] { (DEF|CALL) paras }
enum_list = [ <WHITE> ] { ENUM paras }
item_list = [ <WHITE> ] { ITEM paras }
optd_list = [ <WHITE> ] { OPT_DEF paras }
tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctools_intro](doctools_intro.md),
[doctools_lang_cmdref](doctools_lang_cmdref.md),
[doctools_lang_faq](doctools_lang_faq.md),
[doctools_lang_intro](doctools_lang_intro.md)
# <a name='keywords'></a>KEYWORDS
[doctools commands](../../../../index.md#doctools_commands), [doctools
language](../../../../index.md#doctools_language), [doctools
markup](../../../../index.md#doctools_markup), [doctools
syntax](../../../../index.md#doctools_syntax),
[markup](../../../../index.md#markup), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/doctools_plugin_apiref.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
|
[//000000001]: # (doctools_plugin_apiref - Documentation tools)
[//000000002]: # (Generated from file 'doctools_plugin_apiref.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools_plugin_apiref(n) 1.1 tcllib "Documentation tools")
# NAME
doctools_plugin_apiref - doctools plugin API reference
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OVERVIEW](#section2)
- [FRONTEND COMMANDS](#section3)
- [PLUGIN COMMANDS](#section4)
- [Management commands](#subsection1)
- [Formatting commands](#subsection2)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__dt_copyright__](#1)
[__dt_file__](#2)
[__dt_mainfile__](#3)
[__dt_fileid__](#4)
[__dt_fmap__ *symfname*](#5)
[__dt_format__](#6)
[__dt_imgdata__ *key* *extensions*](#7)
[__dt_imgdst__ *key* *extensions*](#8)
[__dt_imgsrc__ *key* *extensions*](#9)
[__dt_lnesting__](#10)
[__dt_module__](#11)
[__dt_read__ *file*](#12)
[__dt_source__ *file*](#13)
[__dt_user__](#14)
[__ex_cappend__ *text*](#15)
[__ex_cget__ *varname*](#16)
[__ex_cis__ *cname*](#17)
[__ex_cname__](#18)
[__ex_cpop__ *cname*](#19)
[__ex_cpush__ *cname*](#20)
[__ex_cset__ *varname* *value*](#21)
[__ex_lb__ ?*newbracket*?](#22)
[__ex_rb__ ?*newbracket*?](#23)
[__fmt_initialize__](#24)
[__fmt_listvariables__](#25)
[__fmt_numpasses__](#26)
[__fmt_postprocess__ *text*](#27)
[__fmt_setup__ *n*](#28)
[__fmt_shutdown__](#29)
[__fmt_varset__ *varname* *text*](#30)
[__fmt_plain_text__ *text*](#31)
# <a name='description'></a>DESCRIPTION
This document is intended for *plugin writers*, i.e. developers wishing to write
a doctools *[formatting engine](../../../../index.md#formatting_engine)* for
some output format X.
It specifies the interaction between the __[doctools](doctools.md)__ package and
its plugins, i.e. the interface any doctools formatting engine has to comply
with.
This document deals with version 1 of the interface.
A reader who is on the other hand more interested in the markup language itself
should start with the *[doctools language introduction](doctools_lang_intro.md)*
and proceed from there to the formal specifications, i.e. the *[doctools
language syntax](doctools_lang_syntax.md)* and the *[doctools language command
reference](doctools_lang_cmdref.md)*.
# <a name='section2'></a>OVERVIEW
The API for a doctools formatting engine consists of two major sections.
On the one side we have a set of commands through which the plugin is able to
query the frontend. These commands are provided by the frontend and linked into
the plugin interpreter. Please see section [FRONTEND COMMANDS](#section3) for
their detailed specification.
And on the other side the plugin has to provide its own set of commands which
will then be called by the frontend in a specific sequence while processing
input. They, again, fall into two categories, management and formatting. Please
see section [PLUGIN COMMANDS](#section4) and its subsections for their detailed
specification.
# <a name='section3'></a>FRONTEND COMMANDS
This section specifies the set of commands through which a plugin, also known as
a doctools formatting engine, is able to query the frontend. These commands are
provided by the frontend and linked into the plugin interpreter.
I.e. a doctools formatting engine can assume that all of the following commands
are present when any of its own commands (as specified in section [PLUGIN
COMMANDS](#section4)) are executed.
Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the processor, nor
can it damage the filesystem. It is however able to either kill or hang the
whole process, by exiting, or running an infinite loop.
Coming back to the imported commands, all the commands with prefix *dt_* provide
limited access to specific parts of the frontend, whereas the commands with
prefix *ex_* provide access to the state of the
__[textutil::expander](../textutil/expander.md)__ object which does the main
parsing of the input within the frontend. These commands should not be except
under very special circumstances.
- <a name='1'></a>__dt_copyright__
Query command. It returns a string containing the copyright information the
doctools processor was configured with. The relevant option is
__-copyright__).
- <a name='2'></a>__dt_file__
Query command. It returns the full path of the file containing the input
currently processed by the engine. This may be an included file.
- <a name='3'></a>__dt_mainfile__
Query command. It returns the full path of the toplevel file containing the
input currently processed by the engine.
- <a name='4'></a>__dt_fileid__
Query command. It returns the name of the file containing the input
currently processed by the engine, without path, nor extension.
- <a name='5'></a>__dt_fmap__ *symfname*
Query command. It returns the actual pathname to use in the output in place
of the symbolic filename *symfname*. It will return the unchanged input if
no mapping was established for *symfname*.
The required mappings are established with the method __map__ of a frontend,
as explained in section __OBJECT METHODS__ of the documentation for the
package __[doctools](doctools.md)__.
- <a name='6'></a>__dt_format__
Query command. It returns the name of the format associated with the
doctools formatting engine.
- <a name='7'></a>__dt_imgdata__ *key* *extensions*
Query command. Access to the image map. Looks for an image recorded under
the *key* and having on the specified *extension*. If a matching image is
found its data is returned as the result of the command. Otherwise an empty
string is returned.
- <a name='8'></a>__dt_imgdst__ *key* *extensions*
Query command. Access to the image map. Looks for an image recorded under
the *key* and having on the specified *extension*. If a matching image is
found its destination path in the output is returned as the result of the
command. Otherwise an empty string is returned.
- <a name='9'></a>__dt_imgsrc__ *key* *extensions*
Query command. Access to the image map. Looks for an image recorded under
the *key* and having on the specified *extension*. If a matching image is
found its origin path is returned as the result of the command. Otherwise an
empty string is returned.
- <a name='10'></a>__dt_lnesting__
Query command. It returns the number of lists currently open.
- <a name='11'></a>__dt_module__
Query command. It returns the name of the module the input currently
processed belongs to.
- <a name='12'></a>__dt_read__ *file*
Controlled filesystem access. Returns contents of *file* for whatever use
desired by the plugin. Only files which are either in the same directory as
the file containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.
- <a name='13'></a>__dt_source__ *file*
Controlled filesystem access. This command allows the doctools formatting
engine to load additional Tcl code it may need. Only files which are either
in the same directory as the file containing the engine, or below it, can be
loaded. Trying to load a file outside of this directory causes an error.
- <a name='14'></a>__dt_user__
Query command. It returns the name of the current user as known to the tcl
interpreter the frontend controlling the formatting engine resides in.
- <a name='15'></a>__ex_cappend__ *text*
Appends a string to the output in the current context. This command should
rarely be used by macros or application code.
- <a name='16'></a>__ex_cget__ *varname*
Retrieves the value of variable *varname*, defined in the current context.
- <a name='17'></a>__ex_cis__ *cname*
Determines whether or not the name of the current context is *cname*.
- <a name='18'></a>__ex_cname__
Returns the name of the current context.
- <a name='19'></a>__ex_cpop__ *cname*
Pops a context from the context stack, returning all accumulated output in
that context. The context must be named *cname*, or an error results.
- <a name='20'></a>__ex_cpush__ *cname*
Pushes a context named *cname* onto the context stack. The context must be
popped by __cpop__ before expansion ends or an error results.
- <a name='21'></a>__ex_cset__ *varname* *value*
Sets variable *varname* to *value* in the current context.
- <a name='22'></a>__ex_lb__ ?*newbracket*?
Returns the current value of the left macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
- <a name='23'></a>__ex_rb__ ?*newbracket*?
Returns the current value of the right macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
# <a name='section4'></a>PLUGIN COMMANDS
The plugin has to provide its own set of commands which will then be called by
the frontend in a specific sequence while processing input. They fall into two
categories, management and formatting. Their expected names, signatures, and
responsibilities are specified in the following two subsections.
## <a name='subsection1'></a>Management commands
The management commands a plugin has to provide are used by the frontend to
1. initialize and shutdown the plugin
1. determine the number of passes it has to make over the input
1. initialize and shutdown each pass
1. query and initialize engine parameters
After the plugin has been loaded and the frontend commands are established the
commands will be called in the following sequence:
fmt_numpasses -> n
fmt_listvariables -> vars
fmt_varset var1 value1
fmt_varset var2 value2
...
fmt_varset varK valueK
fmt_initialize
fmt_setup 1
...
fmt_setup 2
...
...
fmt_setup n
...
fmt_postprocess
fmt_shutdown
...
I.e. first the number of passes and the set of available engine parameters is
established, followed by calls setting the parameters. That second part is
optional.
After that the plugin is initialized, the specified number of passes executed,
the final result run through a global post processing step and at last the
plugin is shutdown again. This can be followed by more conversions, restarting
the sequence at __fmt_varset__.
In each of the passes, i.e. after the calls of __fmt_setup__ the frontend will
process the input and call the formatting commands as markup is encountered.
This means that the sequence of formatting commands is determined by the grammar
of the doctools markup language, as specified in the *[doctools language
syntax](doctools_lang_syntax.md)* specification.
A different way of looking at the sequence is:
- First some basic parameters are determined.
- Then everything starting at the first __fmt_varset__ to __fmt_shutdown__
forms a *run*, the formatting of a single input. Each run can be followed by
more.
- Embedded within each run we have one or more *passes*, each starting with
__fmt_setup__ and going until either the next __fmt_setup__ or
__fmt_postprocess__ is reached.
If more than one pass is required to perform the formatting only the output
of the last pass is relevant. The output of all the previous, preparatory
passes is ignored.
The commands, their names, signatures, and responsibilities are, in detail:
- <a name='24'></a>__fmt_initialize__
*Initialization/Shutdown*. This command is called at the beginning of every
conversion run, as the first command of that run. Note that a run is not a
pass, but may consist of multiple passes. It has to initialize the general
state of the plugin, beyond the initialization done during the load. No
return value is expected, and any returned value is ignored.
- <a name='25'></a>__fmt_listvariables__
*Initialization/Shutdown* and *Engine parameters*. Second command is called
after the plugin code has been loaded, i.e. immediately after
__fmt_numpasses__. It has to return a list containing the names of the
parameters the frontend can set to configure the engine. This list can be
empty.
- <a name='26'></a>__fmt_numpasses__
*Initialization/Shutdown* and *Pass management*. First command called after
the plugin code has been loaded. No other command of the engine will be
called before it. It has to return the number of passes this engine requires
to fully process the input document. This value has to be an integer number
greater or equal to one.
- <a name='27'></a>__fmt_postprocess__ *text*
*Initialization/Shutdown*. This command is called immediately after the last
pass in a run. Its argument is the result of the conversion generated by
that pass. It is provided to allow the engine to perform any global
modifications of the generated document. If no post-processing is required
for a specific format the command has to just return the argument.
Expected to return a value, the final result of formatting the input.
- <a name='28'></a>__fmt_setup__ *n*
*Initialization/Shutdown* and *Pass management*. This command is called at
the beginning of each pass over the input in a run. Its argument is the
number of the pass which has begun. Passes are counted from __1__ upward.
The command has to set up the internal state of the plugin for this
particular pass. No return value is expected, and any returned value is
ignored.
- <a name='29'></a>__fmt_shutdown__
*Initialization/Shutdown*. This command is called at the end of every
conversion run. It is the last command called in a run. It has to clean up
of all the run-specific state in the plugin. After the call the engine has
to be in a state which allows the initiation of another run without fear
that information from the last run is leaked into this new run. No return
value is expected, and any returned value is ignored.
- <a name='30'></a>__fmt_varset__ *varname* *text*
*Engine parameters*. This command is called by the frontend to set an engine
parameter to a particular value. The parameter to change is specified by
*varname*, the value to set in *text*.
The command has to throw an error if an unknown *varname* is used. Only the
names returned by __fmt_listvariables__ have to be considered as known.
The values of all engine parameters have to persist between passes and runs.
## <a name='subsection2'></a>Formatting commands
The formatting commands have to implement the formatting for the output format,
for all the markup commands of the doctools markup language, except __lb__,
__rb__, __vset__, __include__, and __[comment](../../../../index.md#comment)__.
These exceptions are processed by the frontend and are never seen by the plugin.
In return a command for the formatting of plain text has to be provided,
something which has no markup in the input at all.
This means, that each of the 49 markup commands specified in the *[doctools
language command reference](doctools_lang_cmdref.md)* and outside of the set of
exceptions listed above has an equivalent formatting command which takes the
same arguments as the markup command and whose name is the name of markup
command with the prefix *fmt_* added to it.
All commands are expected to format their input in some way per the semantics
specified in the command reference and to return whatever part of this that they
deem necessary as their result, which will be added to the output.
To avoid essentially duplicating the command reference we do not list any of the
command here and simply refer the reader to the *[doctools language command
reference](doctools_lang_cmdref.md)* for their signature and description. The
sole exception is the plain text formatter, which has no equivalent markup
command.
The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the doctools markup
language, as specified in the *[doctools language
syntax](doctools_lang_syntax.md)* specification.
- <a name='31'></a>__fmt_plain_text__ *text*
*No associated markup command*.
Called by the frontend for any plain text encountered in the input. It has
to perform any and all special processing required for plain text.
The formatted text is expected as the result of the command, and added to
the output. If no special processing is required it has to simply return its
argument without change.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctools](doctools.md), [doctools_intro](doctools_intro.md),
[doctools_lang_cmdref](doctools_lang_cmdref.md),
[doctools_lang_faq](doctools_lang_faq.md),
[doctools_lang_intro](doctools_lang_intro.md),
[doctools_lang_syntax](doctools_lang_syntax.md)
# <a name='keywords'></a>KEYWORDS
[document](../../../../index.md#document),
[formatter](../../../../index.md#formatter), [formatting
engine](../../../../index.md#formatting_engine),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[semantic markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2010 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools/mpexpand.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
[//000000001]: # (mpexpand - Documentation toolbox)
[//000000002]: # (Generated from file 'mpexpand.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (mpexpand(n) 1.0 tcllib "Documentation toolbox")
# NAME
mpexpand - Markup processor
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [NOTES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__mpexpand__ ?-module *module*? *format* *infile*|- *outfile*|-](#1)
[__mpexpand.all__ ?*-verbose*? ?*module*?](#2)
# <a name='description'></a>DESCRIPTION
This manpage describes a processor / converter for manpages in the doctools
format as specified in __doctools_fmt__. The processor is based upon the package
__[doctools](doctools.md)__.
- <a name='1'></a>__mpexpand__ ?-module *module*? *format* *infile*|- *outfile*|-
The processor takes three arguments, namely the code describing which
formatting to generate as the output, the file to read the markup from, and
the file to write the generated output into. If the *infile* is "__-__" the
processor will read from __stdin__. If *outfile* is "__-__" the processor
will write to __stdout__.
If the option *-module* is present its value overrides the internal
definition of the module name.
The currently known output formats are
* __nroff__
The processor generates *roff output, the standard format for unix
manpages.
* __html__
The processor generates HTML output, for usage in and display by web
browsers.
* __tmml__
The processor generates TMML output, the Tcl Manpage Markup Language, a
derivative of XML.
* __latex__
The processor generates LaTeX output.
* __wiki__
The processor generates Wiki markup as understood by __wikit__.
* __list__
The processor extracts the information provided by __manpage_begin__.
* __null__
The processor does not generate any output.
- <a name='2'></a>__mpexpand.all__ ?*-verbose*? ?*module*?
This command uses __mpexpand__ to generate all possible output formats for
all manpages in the current directory. The manpages are recognized through
the extension ".man". If *-verbose* is specified the command will list its
actions before executing them.
The *module* information is passed to __mpexpand__.
# <a name='section2'></a>NOTES
Possible future formats are plain text, pdf and postscript.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
expander(n), format(n), formatter(n)
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[nroff](../../../../index.md#nroff)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002 Andreas Kupries <[email protected]>
Copyright © 2003 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2base/html_cssdefaults.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
[//000000001]: # (doctools::html::cssdefaults - Documentation tools)
[//000000002]: # (Generated from file 'html_cssdefaults.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::html::cssdefaults(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::html::cssdefaults - Default CSS style for HTML export plugins
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::html::cssdefaults ?0.1?
[__::doctools::html::cssdefaults::contents__](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single command providing access to the text of the
default CSS style to use for HTML markup generated by the various HTML export
plugins.
This is an internal package of doctools, for use by
*[export](../../../../index.md#export)* plugins, i.e. the packages converting
doctools related documented into other formats, most notably
*[HTML](../../../../index.md#html)*.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::html::cssdefaults::contents__
This command returns the text of the default CSS style to use for HTML
markup generated by the various HTML export plugins.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[CSS](../../../../index.md#css), [HTML](../../../../index.md#html),
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [plugin](../../../../index.md#plugin),
[style](../../../../index.md#style)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2base/nroff_manmacros.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
[//000000001]: # (doctools::nroff::man_macros - Documentation tools)
[//000000002]: # (Generated from file 'nroff_manmacros.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::nroff::man_macros(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::nroff::man_macros - Default CSS style for NROFF export plugins
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::nroff::man_macros ?0.1?
[__::doctools::nroff::man_macros::contents__](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single command providing access to the definition of the
nroff *man* macro set to use for NROFF markup generated by the various NROFF
export plugins.
This is an internal package of doctools, for use by
*[export](../../../../index.md#export)* plugins, i.e. the packages converting
doctools related documented into other formats, most notably
*[nroff](../../../../index.md#nroff)*.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::nroff::man_macros::contents__
This command returns the text of the default CSS style to use for NROFF
generated by the various NROFF export plugins.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [macros](../../../../index.md#macros),
[man_macros](../../../../index.md#man_macros),
[nroff](../../../../index.md#nroff), [plugin](../../../../index.md#plugin)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2base/tcl_parse.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
[//000000001]: # (doctools::tcl::parse - Documentation tools)
[//000000002]: # (Generated from file 'tcl_parse.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::tcl::parse(n) 1 tcllib "Documentation tools")
# NAME
doctools::tcl::parse - Processing text in 'subst -novariables' format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error format](#section3)
- [Tree Structure](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit
package require fileutil
package require logger
package require struct::list
package require struct::stack
package require struct::set
package require treeql
package require doctools::tcl::parse
[__::doctools::tcl::parse__ __text__ *tree* *text* ?*root*?](#1)
[__::doctools::tcl::parse__ __file__ *tree* *path* ?*root*?](#2)
# <a name='description'></a>DESCRIPTION
This package provides commands for parsing text with embedded Tcl commands as
accepted by the Tcl builtin command __subst -novariables__. The result of the
parsing is an abstract syntax tree.
This is an internal package of doctools, for use by the higher level parsers
processing the *[docidx](../../../../index.md#docidx)*,
*[doctoc](../../../../index.md#doctoc)*, and
*[doctools](../../../../index.md#doctools)* markup languages.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::tcl::parse__ __text__ *tree* *text* ?*root*?
The command takes the *text* and parses it under the assumption that it
contains a string acceptable to the Tcl builtin command __subst
-novariables__. Errors are thrown otherwise during the parsing. The format
used for these errors in described in section [Error format](#section3).
The command returns the empty string as it result. The actual result of the
parsing is entered into the tree structure *tree*, under the node *root*. If
*root* is not specified the root of *tree* is used. The *tree* has to exist
and be the command of a tree object which supports the same methods as trees
created by the package __[struct::tree](../struct/struct_tree.md)__.
In case of errors *tree* will be left in an undefined state.
- <a name='2'></a>__::doctools::tcl::parse__ __file__ *tree* *path* ?*root*?
The same as __text__, except that the text to parse is read from the file
specified by *path*.
# <a name='section3'></a>Error format
When the parser encounters a problem in the input it will throw an error using
the format described here.
1. The message will contain the reason for the problem (unexpected character
or end of input in input), the character in question, if any, and the line
and column the problem was found at, in a human readable form. This part is
not documented further as its format may change as we see fit. It is
intended for human consumption, not machine.
1. The error code however will contain a machine-readable representation of
the problem, in the form of a 5-element list containing, in the order
listed below
1) the constant string __doctools::tcl::parse__
1) the cause of the problem, one of
- __char__
Unexpected character in input
- __eof__
Unexpected end of the input
1) The location of the problem as offset from the beginning of the input,
counted in characters. Note: Line markers count as one character.
1) The line the problem was found on (counted from 1 (one)),
1) The column the problem was found at (counted from 0 (zero))
# <a name='section4'></a>Tree Structure
After successfully parsing a string the generated tree will have the following
structure:
1. In the following items the word 'root' refers to the node which was
specified as the root of the tree when invoking either __text__ or
__file__. This may be the actual root of the tree.
1. All the following items further ignore the possibility of pre-existing
attributes in the pre-existing nodes. If attributes exists with the same
names as the attributes used by the parser the pre-existing values are
written over. Attributes with names not clashing with the parser's
attributes are not touched.
1. The root node has no attributes.
1. All other nodes have the attributes
- type
The value is a string from the set { Command , Text , Word }
- range
The value is either empty or a 2-element list containing integer
numbers. The numbers are the offsets of the first and last character in
the input text, of the token described by the node,.
- line
The value is an integer, it describes the line in the input the token
described by the node ends on. Lines are counted from 1 (__one__).
- col
The value is an integer, it describes the column in the line in the
input the token described by the node ends on. Columns are counted from
0 (__zero__).
1. The children of the root, if any, are of type Command and Text, in
semi-alternation. This means: After a Text node a Command node has to
follow, and anything can follow a Command node, a Text or other Command
node.
1. The children of a Command node, if any, are of type Command, and Text, and
Word, they describe the arguments of the command.
1. The children of a Word node, if any, are of type Command, Text, in
semi-alternation. This means: After a Text node a Command node has to
follow, and anything can follow a Command node, a Text or other Command
node.
1. A Word node without children represents the empty string.
1. All Text nodes are leaves of the tree.
1. All leaves of the tree are either Text or Command nodes. Word nodes cannot
be leaves.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[Tcl syntax](../../../../index.md#tcl_syntax),
[command](../../../../index.md#command),
[doctools](../../../../index.md#doctools),
[parser](../../../../index.md#parser), [subst](../../../../index.md#subst),
[word](../../../../index.md#word)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2base/tcllib_msgcat.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
[//000000001]: # (doctools::msgcat - Documentation tools)
[//000000002]: # (Generated from file 'tcllib_msgcat.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat - Message catalog management for the various document parsers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat ?0.1?
[__::doctools::msgcat::init__ *prefix*](#1)
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat__ is a support module handling the selection of
message catalogs for the various document processing packages in the doctools
system version 2. As such it is an internal package a regular user (developer)
should not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](../doctools2idx/idx_container.md)__
Within the system architecture this package resides under the various parser
packages, and is shared by them. Underneath it, but not explicit dependencies,
are the packages providing the message catalogs for the various languages.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::msgcat::init__ *prefix*
The command locates and loads the message catalogs for all the languages
returned by __msgcat::mcpreferences__, provided that they could be found. It
returns an integer number describing how many packages were found and
loaded.
The names of the packages the command will look for have the form
"doctools::msgcat::*prefix*::__langcode__", with *prefix* the argument to
the command, and the __langcode__ supplied by the result of
__msgcat::mcpreferences__.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[catalog package](../../../../index.md#catalog_package),
[docidx](../../../../index.md#docidx), [doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/export_docidx.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
[//000000001]: # (doctools::idx::export::docidx - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export::docidx(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::idx::export::docidx - docidx export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [[docidx] notation of keyword indices](#section3)
- [Configuration](#section4)
- [Keyword index serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::export::docidx ?0.1?
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index export plugin for the
generation of docidx markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::export](idx_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::export](idx_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a keyword index, as
specified in section [Keyword index serialization format](#section5), and
contained in *serial*, the *configuration*, a dictionary, and generates
docidx markup encoding the index. The created string is then returned as the
result of the command.
# <a name='section3'></a>[docidx] notation of keyword indices
The docidx format for keyword indices, also called the *docidx markup language*,
is too large to be covered in single section. The interested reader should start
with the document
1. *[docidx language introduction](../doctools/docidx_lang_intro.md)*
and then proceed from there to the formal specifications, i.e. the documents
1. *[docidx language syntax](../doctools/docidx_lang_syntax.md)* and
1. *[docidx language command reference](../doctools/docidx_lang_cmdref.md)*.
to get a thorough understanding of the language.
# <a name='section4'></a>Configuration
The docidx export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *user*
This standard configuration variable contains the name of the user running
the process which invoked the export plugin. The plugin puts this
information into the provenance comment at the beginning of the generated
document.
- string *file*
This standard configuration variable contains the name of the file the index
came from. This variable may not be set or contain the empty string. The
plugin puts this information, if defined, i.e. set and not the empty string,
into the provenance comment at the beginning of the generated document.
- boolean *newlines*
If this flag is set the plugin will break the generated docidx code across
lines, with each markup command on a separate line.
If this flag is not set (the default), the whole document will be written on
a single line, with minimum spacing between all elements.
- boolean *indented*
If this flag is set the plugin will indent the markup commands according to
the structure of indices. To make this work this also implies that
__newlines__ is set. This effect is independent of the value for __aligned__
however.
If this flag is not set (the default), the output is formatted as per the
values of __newlines__ and __aligned__, and no indenting is done.
- boolean *aligned*
If this flag is set the generator ensures that the arguments for the
__[manpage](../../../../index.md#manpage)__ and
__[url](../../../../index.md#url)__ commands in a keyword section are
aligned vertically for a nice table effect. To make this work this also
implies that __newlines__ is set. This effect is independent of the value
for __indented__ however.
If this flag is not set (the default), the output is formatted as per the
values of __newlines__ and __indented__, and no alignment is done.
*Note* that this plugin ignores the standard configuration variables __format__,
and __map__, and their values.
# <a name='section5'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [index](../../../../index.md#index),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
|
[//000000001]: # (doctools::idx - Documentation tools)
[//000000002]: # (Generated from file 'idx_container.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx(n) 2 tcllib "Documentation tools")
# NAME
doctools::idx - Holding keyword indices
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [API](#section3)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Keyword index serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::idx ?2?
package require Tcl 8.4
package require doctools::idx::structure
package require snit
[__::doctools::idx__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __key add__ *name*](#4)
[*objectName* __key remove__ *name*](#5)
[*objectName* __key references__ *name*](#6)
[*objectName* __keys__](#7)
[*objectName* __reference add__ *type* *key* *name* *label*](#8)
[*objectName* __reference remove__ *name*](#9)
[*objectName* __reference label__ *name*](#10)
[*objectName* __reference keys__ *name*](#11)
[*objectName* __reference type__ *name*](#12)
[*objectName* __references__](#13)
[*objectName* __title__](#14)
[*objectName* __title__ *text*](#15)
[*objectName* __label__](#16)
[*objectName* __label__ *text*](#17)
[*objectName* __importer__](#18)
[*objectName* __importer__ *object*](#19)
[*objectName* __exporter__](#20)
[*objectName* __exporter__ *object*](#21)
[*objectName* __deserialize =__ *data* ?*format*?](#22)
[*objectName* __deserialize +=__ *data* ?*format*?](#23)
[*objectName* __serialize__ ?*format*?](#24)
# <a name='description'></a>DESCRIPTION
This package provides a class to contain and programmatically manipulate keyword
indices
This is one of the three public pillars the management of keyword indices
resides on. The other two pillars are
1. *[Exporting keyword indices](idx_export.md)*, and
1. *[Importing keyword indices](idx_import.md)*
For information about the [Concepts](#section2) of keyword indices, and their
parts, see the same-named section. For information about the data structure
which is used to encode keyword indices as values see the section [Keyword index
serialization format](#section4). This is the only format directly known to this
class. Conversions from and to any other format are handled by export and import
manager objects. These may be attached to a container, but do not have to be, it
is merely a convenience.
# <a name='section2'></a>Concepts
1. A *[keyword index](../../../../index.md#keyword_index)* consists of a
(possibly empty) set of *[keywords](../../../../index.md#keywords)*.
1. Each keyword in the set is identified by its name.
1. Each keyword has a (possibly empty) set of *references*.
1. A reference can be associated with more than one keyword.
1. A reference not associated with at least one keyword is not possible
however.
1. Each reference is identified by its target, specified as either an url or
symbolic filename, depending on the type of reference (__url__, or
__manpage__).
1. The type of a reference (url, or manpage) depends only on the reference
itself, and not the keywords it is associated with.
1. In addition to a type each reference has a descriptive label as well. This
label depends only on the reference itself, and not the keywords it is
associated with.
A few notes
1. Manpage references are intended to be used for references to the documents
the index is made for. Their target is a symbolic file name identifying the
document, and export plugins may replace symbolic with actual file names,
if specified.
1. Url references are intended on the othre hand are inteded to be used for
links to anything else, like websites. Their target is an url.
1. While url and manpage references share a namespace for their identifiers,
this should be no problem, given that manpage identifiers are symbolic
filenames and as such they should never look like urls, the identifiers for
url references.
# <a name='section3'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::doctools::idx__ *objectName*
This command creates a new container object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [Object
command](#subsection2) and [Object methods](#subsection3). The object
command will be created under the current namespace if the *objectName* is
not fully qualified, and in the specified namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::doctools::idx__ command have the following
general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __key add__ *name*
This method adds the keyword *name* to the index. If the keyword is already
known nothing is done. The result of the method is the empty string.
- <a name='5'></a>*objectName* __key remove__ *name*
This method removes the keyword *name* from the index. If the keyword is
already gone nothing is done. Any references for whom this keyword was the
last association are removed as well. The result of the method is the empty
string.
- <a name='6'></a>*objectName* __key references__ *name*
This method returns a list containing the names of all references associated
with the keyword *name*. An error is thrown in the keyword is not known to
the index. The order of the references in the list is undefined.
- <a name='7'></a>*objectName* __keys__
This method returns a list containing the names of all keywords known to the
index. The order of the keywords in the list is undefined.
- <a name='8'></a>*objectName* __reference add__ *type* *key* *name* *label*
This method adds the reference *name* to the index and associates it with
the keyword *key*. The other two arguments hold the *type* and *label* of
the reference, respectively. The type has to match the stored information,
should the reference exist already, i.e. this information is immutable after
the reference is known. The only way to change it is delete and recreate the
reference. The label on the other hand is automatically updated to the value
of the argument, overwriting any previously stored information. Should the
reference exists already it is simply associated with the *key*. If that is
true already as well nothing is done, but the *label* updated to the new
value. The result of the method is the empty string.
The *type* argument has be to one of __manpage__ or __url__.
- <a name='9'></a>*objectName* __reference remove__ *name*
The reference *name* is removed from the index. All associations with
keywords are released and the relevant reference labels removed. The result
of the method is the empty string.
- <a name='10'></a>*objectName* __reference label__ *name*
This method returns the label associated with the reference *name*. An error
is thrown if the reference is not known.
- <a name='11'></a>*objectName* __reference keys__ *name*
This method returns a list containing the names of all keywords associated
with the reference *name*. An error is thrown in the reference is not known
to the index. The order of the keywords in the list is undefined.
- <a name='12'></a>*objectName* __reference type__ *name*
This method returns the type of the reference *name*. An error is thrown in
the reference is not known to the index.
- <a name='13'></a>*objectName* __references__
This method returns a list containing the names of all references known to
the index. The order of the references in the list is undefined.
- <a name='14'></a>*objectName* __title__
Returns the currently defined title of the keyword index.
- <a name='15'></a>*objectName* __title__ *text*
Sets the title of the keyword index to *text*, and returns it as the result
of the command.
- <a name='16'></a>*objectName* __label__
Returns the currently defined label of the keyword index.
- <a name='17'></a>*objectName* __label__ *text*
Sets the label of the keyword index to *text*, and returns it as the result
of the command.
- <a name='18'></a>*objectName* __importer__
Returns the import manager object currently attached to the container, if
any.
- <a name='19'></a>*objectName* __importer__ *object*
Attaches the *object* as import manager to the container, and returns it as
the result of the command. Note that the *object* is *not* put into
ownership of the container. I.e., destruction of the container will *not*
destroy the *object*.
It is expected that *object* provides a method named __import text__ which
takes a text and a format name, and returns the canonical serialization of
the keyword index contained in the text, assuming the given format.
- <a name='20'></a>*objectName* __exporter__
Returns the export manager object currently attached to the container, if
any.
- <a name='21'></a>*objectName* __exporter__ *object*
Attaches the *object* as export manager to the container, and returns it as
the result of the command. Note that the *object* is *not* put into
ownership of the container. I.e., destruction of the container will *not*
destroy the *object*.
It is expected that *object* provides a method named __export object__ which
takes the container and a format name, and returns a text encoding keyword
index stored in the container, in the given format. It is further expected
that the *object* will use the container's method __serialize__ to obtain
the serialization of the keyword index from which to generate the text.
- <a name='22'></a>*objectName* __deserialize =__ *data* ?*format*?
This method replaces the contents of the index object with the index
contained in the *data*. If no *format* was specified it is assumed to be
the regular serialization of a keyword index.
Otherwise the object will use the attached import manager to convert the
data from the specified format to a serialization it can handle. In that
case an error will be thrown if the container has no import manager attached
to it.
The result of the method is the empty string.
- <a name='23'></a>*objectName* __deserialize +=__ *data* ?*format*?
This method behaves like __deserialize =__ in its essentials, except that it
merges the keyword index in the *data* to its contents instead of replacing
it. The method will throw an error if merging is not possible, i.e. would
produce an invalid index. The existing content is left unchanged in that
case.
The result of the method is the empty string.
- <a name='24'></a>*objectName* __serialize__ ?*format*?
This method returns the keyword index contained in the object. If no
*format* is not specified the returned result is the canonical serialization
of its contents.
Otherwise the object will use the attached export manager to convert the
data to the specified format. In that case an error will be thrown if the
container has no export manager attached to it.
# <a name='section4'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion), [docidx
markup](../../../../index.md#docidx_markup),
[documentation](../../../../index.md#documentation),
[formatting](../../../../index.md#formatting),
[generation](../../../../index.md#generation),
[index](../../../../index.md#index), [json](../../../../index.md#json), [keyword
index](../../../../index.md#keyword_index), [latex](../../../../index.md#latex),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[nroff](../../../../index.md#nroff), [parsing](../../../../index.md#parsing),
[plugin](../../../../index.md#plugin),
[reference](../../../../index.md#reference), [tcler's
wiki](../../../../index.md#tcler_s_wiki), [text](../../../../index.md#text),
[url](../../../../index.md#url), [wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_export.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
|
[//000000001]: # (doctools::idx::export - Documentation tools)
[//000000002]: # (Generated from file 'idx_export.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::idx::export - Exporting keyword indices
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [API](#section3)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Export plugin API v2 reference](#section4)
- [Keyword index serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::idx::export ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::idx::structure
package require snit
package require pluginmgr
[__::doctools::idx::export__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __export serial__ *serial* ?*format*?](#4)
[*objectName* __export object__ *object* ?*format*?](#5)
[*objectName* __config names__](#6)
[*objectName* __config get__](#7)
[*objectName* __config set__ *name* ?*value*?](#8)
[*objectName* __config unset__ *pattern*...](#9)
[__[export](../../../../index.md#export)__ *serial* *configuration*](#10)
# <a name='description'></a>DESCRIPTION
This package provides a class to manage the plugins for the export of keyword
indices to other formats, i.e. their conversion to, for example
*[docidx](../../../../index.md#docidx)*, *[HTML](../../../../index.md#html)*,
etc.
This is one of the three public pillars the management of keyword indices
resides on. The other two pillars are
1. *[Importing keyword indices](idx_import.md)*, and
1. *[Holding keyword indices](idx_container.md)*
For information about the [Concepts](#section2) of keyword indices, and their
parts, see the same-named section. For information about the data structure
which is the major input to the manager objects provided by this package see the
section [Keyword index serialization format](#section5).
The plugin system of our class is based on the package
__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins
using
1. the environment variable __DOCTOOLS_IDX_EXPORT_PLUGINS__,
1. the environment variable __DOCTOOLS_IDX_PLUGINS__,
1. the environment variable __DOCTOOLS_PLUGINS__,
1. the path "~/.doctools/idx/export/plugin"
1. the path "~/.doctools/idx/plugin"
1. the path "~/.doctools/plugin"
1. the path "~/.doctools/idx/export/plugins"
1. the path "~/.doctools/idx/plugins"
1. the path "~/.doctools/plugins"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\EXPORT\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
The last three are used only when the package is run on a machine using
Windows(tm) operating system.
The whole system is delivered with six predefined export plugins, namely
- docidx
See *[docidx export plugin](export_docidx.md)* for details.
- html
See *html export plugin* for details.
- json
See *json export plugin* for details.
- nroff
See *[nroff export plugin](../doctools2toc/toc_export_nroff.md)* for
details.
- text
See *text export plugin* for details.
- wiki
See *[wiki export plugin](../doctools2toc/toc_export_wiki.md)* for details.
Readers wishing to write their own export plugin for some format, i.e. *plugin
writer*s reading and understanding the section containing the [Export plugin API
v2 reference](#section4) is an absolute necessity, as it specifies the
interaction between this package and its plugins in detail.
# <a name='section2'></a>Concepts
1. A *[keyword index](../../../../index.md#keyword_index)* consists of a
(possibly empty) set of *[keywords](../../../../index.md#keywords)*.
1. Each keyword in the set is identified by its name.
1. Each keyword has a (possibly empty) set of *references*.
1. A reference can be associated with more than one keyword.
1. A reference not associated with at least one keyword is not possible
however.
1. Each reference is identified by its target, specified as either an url or
symbolic filename, depending on the type of reference (__url__, or
__manpage__).
1. The type of a reference (url, or manpage) depends only on the reference
itself, and not the keywords it is associated with.
1. In addition to a type each reference has a descriptive label as well. This
label depends only on the reference itself, and not the keywords it is
associated with.
A few notes
1. Manpage references are intended to be used for references to the documents
the index is made for. Their target is a symbolic file name identifying the
document, and export plugins may replace symbolic with actual file names,
if specified.
1. Url references are intended on the othre hand are inteded to be used for
links to anything else, like websites. Their target is an url.
1. While url and manpage references share a namespace for their identifiers,
this should be no problem, given that manpage identifiers are symbolic
filenames and as such they should never look like urls, the identifiers for
url references.
# <a name='section3'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::doctools::idx::export__ *objectName*
This command creates a new export manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::doctools::idx::export__ command have the
following general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __export serial__ *serial* ?*format*?
This method takes the canonical serialization of a keyword index stored in
*serial* and converts it to the specified *format*, using the export plugin
for the format. An error is thrown if no plugin could be found for the
format. The string generated by the conversion process is returned as the
result of this method.
If no format is specified the method defaults to __docidx__.
The specification of what a *canonical* serialization is can be found in the
section [Keyword index serialization format](#section5).
The plugin has to conform to the interface specified in section [Export
plugin API v2 reference](#section4).
- <a name='5'></a>*objectName* __export object__ *object* ?*format*?
This method is a convenient wrapper around the __export serial__ method
described by the previous item. It expects that *object* is an object
command supporting a __serialize__ method returning the canonical
serialization of a keyword index. It invokes that method, feeds the result
into __export serial__ and returns the resulting string as its own result.
- <a name='6'></a>*objectName* __config names__
This method returns a list containing the names of all configuration
variables currently known to the object.
- <a name='7'></a>*objectName* __config get__
This method returns a dictionary containing the names and values of all
configuration variables currently known to the object.
- <a name='8'></a>*objectName* __config set__ *name* ?*value*?
This method sets the configuration variable *name* to the specified *value*
and returns the new value of the variable.
If no value is specified it simply returns the current value, without
changing it.
Note that while the user can set the predefined configuration variables
__user__ and __format__ doing so will have no effect, these values will be
internally overridden when invoking an import plugin.
- <a name='9'></a>*objectName* __config unset__ *pattern*...
This method unsets all configuration variables matching the specified glob
*pattern*s. If no pattern is specified it will unset all currently defined
configuration variables.
# <a name='section4'></a>Export plugin API v2 reference
Plugins are what this package uses to manage the support for any output format
beyond the [Keyword index serialization format](#section5). Here we specify the
API the objects created by this package use to interact with their plugins.
A plugin for this package has to follow the rules listed below:
1. A plugin is a package.
1. The name of a plugin package has the form doctools::idx::export::__FOO__,
where __FOO__ is the name of the format the plugin will generate output
for. This name is also the argument to provide to the various __export__
methods of export manager objects to get a string encoding a keyword index
in that format.
1. The plugin can expect that the package __doctools::idx::export::plugin__ is
present, as indicator that it was invoked from a genuine plugin manager.
1. A plugin has to provide one command, with the signature shown below.
- <a name='10'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
Whenever an export manager of __[doctools::idx](idx_container.md)__ has
to generate output for an index it will invoke this command.
* string *serial*
This argument will contain the *canonical* serialization of the
index for which to generate the output. The specification of what a
*canonical* serialization is can be found in the section [Keyword
index serialization format](#section5).
* dictionary *configuration*
This argument will contain the current configuration to apply to
the generation, as a dictionary mapping from variable names to
values.
The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables
recognized by a plugin will be described in the manpage for that
plugin.
+ user
This variable is expected to contain the name of the user
owning the process invoking the plugin.
+ format
This variable is expected to contain the name of the format
whose plugin is invoked.
+ file
This variable, if defined by the user of the index object is
expected to contain the name of the input file for which the
plugin is generating its output for.
+ map
This variable, if defined by the user of the index object is
expected to contain a dictionary mapping from symbolic file
names used in the references of type __manpage__ to actual
paths (or urls). A plugin has to be able to handle the
possibility that a symbolic name is without entry in this
mapping.
1. A single usage cycle of a plugin consists of the invokations of the command
__[export](../../../../index.md#export)__. This call has to leave the
plugin in a state where another usage cycle can be run without problems.
# <a name='section5'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html),
[conversion](../../../../index.md#conversion),
[docidx](../../../../index.md#docidx),
[documentation](../../../../index.md#documentation),
[export](../../../../index.md#export),
[formatting](../../../../index.md#formatting),
[generation](../../../../index.md#generation),
[index](../../../../index.md#index), [json](../../../../index.md#json), [keyword
index](../../../../index.md#keyword_index),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[nroff](../../../../index.md#nroff), [plugin](../../../../index.md#plugin),
[reference](../../../../index.md#reference), [tcler's
wiki](../../../../index.md#tcler_s_wiki), [text](../../../../index.md#text),
[url](../../../../index.md#url), [wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2018 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_export_html.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
|
[//000000001]: # (doctools::idx::export::html - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export::html(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::idx::export::html - HTML export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [Keyword index serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::export::html ?0.2?
package require doctools::text
package require doctools::html
package require doctools::html::cssdefaults
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index export plugin for the
generation of HTML markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::export](idx_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::export](idx_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a keyword index, as
specified in section [Keyword index serialization format](#section4), and
contained in *serial*, the *configuration*, a dictionary, and generates HTML
markup encoding the index. The created string is then returned as the result
of the command.
# <a name='section3'></a>Configuration
The html export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *user*
This standard configuration variable contains the name of the user running
the process which invoked the export plugin. The plugin puts this
information into the provenance comment at the beginning of the generated
document.
- string *file*
This standard configuration variable contains the name of the file the index
came from. This variable may not be set or contain the empty string. The
plugin puts this information, if defined, i.e. set and not the empty string,
into the provenance comment at the beginning of the generated document.
- dictionary *map*
This standard configuration variable contains a dictionary mapping from the
symbolic files names in manpage references to the actual filenames and/or
urls to be used in the output.
Url references and symbolic file names without a mapping are used unchanged.
- boolean *newlines*
If this flag is set the plugin will break the generated html code across
lines, with each markup command on a separate line.
If this flag is not set (the default), the whole document will be written on
a single line, with minimum spacing between all elements.
- boolean *indented*
If this flag is set the plugin will indent the markup commands according to
the structure of indices. To make this work this also implies that
__newlines__ is set.
If this flag is not set (the default), the output is formatted as per the
value of __newlines__, and no indenting is done.
- string *meta*
This variable is meant to hold a fragment of HTML (default: empty). The
fragment it contains will be inserted into the generated output in the
<head> section of the document, just after the <title> tag.
- string *header*
This variable is meant to hold a fragment of HTML (default: empty). The
fragment it contains will be inserted into the generated output just after
the <h1> title tag in the body of the document, in the class.header
<div>'ision.
- string *footer*
This variable is meant to hold a fragment of HTML (default: empty). The
fragment it contains will be inserted into the generated output just before
the </body> tag, in the class.footer <div>'ision.
- dictionary *kwid*
The value of this variable (default: empty) maps keywords to the identifiers
to use as their anchor names. Each keyword __FOO__ not found in the
dictionary uses __KW-____FOO__ as anchor, i.e. itself prefixed with the
string __KW-__.
- string *sepline*
The value of this variable is the string to use for the separator comments
inserted into the output when the outpout is broken across lines and/or
indented. The default string consists of 60 dashes.
- integer *kwidth*
This variable holds the size of the keyword column in the main table
generated by the plugin, in percent of the total width of the table. This is
an integer number in the range of 1 to 99. Choosing a value outside of that
range causes the generator to switch back to the defauly setting, 35
percent.
- string *dot*
This variable contains a HTML fragment inserted between the entries of the
navigation bar, and the references associated with each keyword. The default
is the HTML entity · i.e. the bullet character, also known as the
"Greek middle dot", i.e. the unicode character 00B7.
- string *class.main*
This variable contains the class name for the main <div>'ivision of the
generated document. The default is __doctools__.
- string *class.header*
This variable contains the class name for the header <div>'ision of the
generated document. The default is __idx-header__. This division contains
the document title, the user specified __header__, if any, a visible
separator line, and the navigation bar for quick access to each keyword
section.
- string *class.title*
This variable contains the class name for the <h1> tag enclosing the
document title. The default is __idx-title__.
- string *class.navsep*
This variable contains the class name for the <hr> separators in the header
and footer sections of the generated document. The default is
__idx-navsep__.
- string *class.navbar*
This variable contains the class name for the navigation <div>'ision
enclosing the navigation bar of the generated document. The default is
__idx-kwnav__.
- string *class.contents*
This variable contains the class name for the <table> holding the keywords
and their references in the generated document. The default is
__idx-contents__.
- string *class.leader*
This variable contains the class name for the anchor names the plugin
inserts into the keyword table when switching from one section to the next
(Each section holds all keywords with a particular first character). The
default is __idx-leader__.
- string *class.row0*
This variable contains the class name used to label the even rows (<tr>) of
the keyword table. The default is __idx-even__.
- string *class.row1*
This variable contains the class name used to label the odd rows (<tr>) of
the keyword table. The default is __idx-odd__.
- string *class.keyword*
This variable contains the class name used to label the keyword cells/column
(<td>) in the keyword table of the document. The default is __idx-keyword__.
- string *class.refs*
This variable contains the class name used to label the reference
cells/column (<td>) in the keyword table of the document. The default is
__idx-refs__.
- string *class.footer*
This variable contains the class name for the footer <div>'ision of the
generated document. The default is __idx-footer__. This division contains a
browser-visible separator line and the user specified __footer__, if any.
*Note* that this plugin ignores the standard configuration variable __format__,
and its value.
# <a name='section4'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [index](../../../../index.md#index),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_export_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
[//000000001]: # (doctools::idx::export::json - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export::json(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::idx::export::json - JSON export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [JSON notation of keyword indices](#section3)
- [Configuration](#section4)
- [Keyword index serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::export::json ?0.1?
package require textutil::adjust
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index export plugin for the
generation of JSON markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::export](idx_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::export](idx_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a keyword index, as
specified in section [Keyword index serialization format](#section5), and
contained in *serial*, the *configuration*, a dictionary, and generates JSON
markup encoding the index. The created string is then returned as the result
of the command.
# <a name='section3'></a>JSON notation of keyword indices
The JSON format used for keyword indices is a direct translation of the [Keyword
index serialization format](#section5), mapping Tcl dictionaries as JSON objects
and Tcl lists as JSON arrays. For example, the Tcl serialization
doctools::idx {
label {Keyword Index}
keywords {
changelog {changelog.man cvs.man}
conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
cvs cvs.man
}
references {
apps/dtplite.man {manpage dtplite}
changelog.man {manpage doctools::changelog}
cvs.man {manpage doctools::cvs}
docidx.man {manpage doctools::idx}
doctoc.man {manpage doctools::toc}
doctools.man {manpage doctools}
mpexpand.man {manpage mpexpand}
}
title {}
}
is equivalent to the JSON string
{
"doctools::idx" : {
"label" : "Keyword Index",
"keywords" : {
"changelog" : ["changelog.man","cvs.man"],
"conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
"cvs" : ["cvs.man"],
},
"references" : {
"apps\/dtplite.man" : ["manpage","dtplite"],
"changelog.man" : ["manpage","doctools::changelog"],
"cvs.man" : ["manpage","doctools::cvs"],
"docidx.man" : ["manpage","doctools::idx"],
"doctoc.man" : ["manpage","doctools::toc"],
"doctools.man" : ["manpage","doctools"],
"mpexpand.man" : ["manpage","mpexpand"]
},
"title" : ""
}
}
# <a name='section4'></a>Configuration
The JSON export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- boolean *indented*
If this flag is set the plugin will break the generated JSON code across
lines and indent it according to its inner structure, with each key of a
dictionary on a separate line.
If this flag is not set (the default), the whole JSON object will be written
on a single line, with minimum spacing between all elements.
- boolean *aligned*
If this flag is set the generator ensures that the values for the keys in a
dictionary are vertically aligned with each other, for a nice table effect.
To make this work this also implies that __indented__ is set.
If this flag is not set (the default), the output is formatted as per the
value of __indented__, without trying to align the values for dictionary
keys.
*Note* that this plugin ignores the standard configuration variables __user__,
__format__, __file__, and __map__ and their values.
# <a name='section5'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[JSON](../../../../index.md#json), [doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [index](../../../../index.md#index),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_export_nroff.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
[//000000001]: # (doctools::idx::export::nroff - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export::nroff(n) 0.3 tcllib "Documentation tools")
# NAME
doctools::idx::export::nroff - nroff export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [Keyword index serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::export::nroff ?0.3?
package require doctools::text
package require doctools::nroff::man_macros
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index export plugin for the
generation of nroff markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::export](idx_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::export](idx_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a keyword index, as
specified in section [Keyword index serialization format](#section4), and
contained in *serial*, the *configuration*, a dictionary, and generates
nroff markup encoding the index. The created string is then returned as the
result of the command.
# <a name='section3'></a>Configuration
The nroff export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *user*
This standard configuration variable contains the name of the user running
the process which invoked the export plugin. The plugin puts this
information into the provenance comment at the beginning of the generated
document.
- string *file*
This standard configuration variable contains the name of the file the index
came from. This variable may not be set or contain the empty string. The
plugin puts this information, if defined, i.e. set and not the empty string,
into the provenance comment at the beginning of the generated document.
- boolean *inline*
If this flag is set (default) the plugin will place the definitions of the
man macro set directly into the output.
If this flag is not set, the plugin will place a reference to the
definitions of the man macro set into the output, but not the macro
definitions themselves.
*Note* that this plugin ignores the standard configuration variables __format__,
and __map__, and their values.
# <a name='section4'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [index](../../../../index.md#index),
[nroff](../../../../index.md#nroff),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_export_text.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
[//000000001]: # (doctools::idx::export::text - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export::text(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::idx::export::text - plain text export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [Keyword index serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::export::text ?0.2?
package require doctools::text
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index export plugin for the
generation of plain text markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::export](idx_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::export](idx_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a keyword index, as
specified in section [Keyword index serialization format](#section4), and
contained in *serial*, the *configuration*, a dictionary, and generates
plain text markup encoding the index. The created string is then returned as
the result of the command.
# <a name='section3'></a>Configuration
The text export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- dictionary *map*
This standard configuration variable contains a dictionary mapping from the
symbolic files names in manpage references to the actual filenames and/or
urls to be used in the output.
Url references and symbolic file names without a mapping are used unchanged.
*Note* that this plugin ignores the standard configuration variables __user__,
__file__, and __format__, and their values.
# <a name='section4'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [index](../../../../index.md#index),
[plain text](../../../../index.md#plain_text),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_export_wiki.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
[//000000001]: # (doctools::idx::export::wiki - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::export::wiki(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::idx::export::wiki - wiki export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Wiki markup](#section3)
- [Configuration](#section4)
- [Keyword index serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::export::wiki ?0.2?
package require doctools::text
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index export plugin for the
generation of wiki markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::export](idx_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::export](idx_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a keyword index, as
specified in section [Keyword index serialization format](#section5), and
contained in *serial*, the *configuration*, a dictionary, and generates wiki
markup encoding the index. The created string is then returned as the result
of the command.
# <a name='section3'></a>Wiki markup
The basic syntax of the wiki markup generated by this plugin are described at
[http://wiki.tcl.tk/14](http://wiki.tcl.tk/14).
The plugin goes beyond the classic markup to generate proper headers and either
a table or indented list of the keywords and their references.
# <a name='section4'></a>Configuration
The wiki export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- dictionary *map*
This standard configuration variable contains a dictionary mapping from the
symbolic files names in manpage references to the actual filenames and/or
urls to be used in the output.
Url references and symbolic file names without a mapping are used unchanged.
- enum *style*
This variable recognizes two values as legal, __list__ (default), and
__table__. Depending on the value the plugin generates either a list- or
table-based wiki page for the index.
*Note* that this plugin ignores the standard configuration variables __user__,
__file__ and __format__, and their values.
# <a name='section5'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [index](../../../../index.md#index),
[serialization](../../../../index.md#serialization),
[wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_import.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
|
[//000000001]: # (doctools::idx::import - Documentation tools)
[//000000002]: # (Generated from file 'idx_import.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::import(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::idx::import - Importing keyword indices
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [API](#section3)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Import plugin API v2 reference](#section4)
- [Keyword index serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::idx::import ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::idx::structure
package require snit
package require pluginmgr
[__::doctools::idx::import__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __import text__ *text* ?*format*?](#4)
[*objectName* __import file__ *path* ?*format*?](#5)
[*objectName* __import object text__ *object* *text* ?*format*?](#6)
[*objectName* __import object file__ *object* *path* ?*format*?](#7)
[*objectName* __config names__](#8)
[*objectName* __config get__](#9)
[*objectName* __config set__ *name* ?*value*?](#10)
[*objectName* __config unset__ *pattern*...](#11)
[*objectName* __includes__](#12)
[*objectName* __include add__ *path*](#13)
[*objectName* __include remove__ *path*](#14)
[*objectName* __include clear__](#15)
[__IncludeFile__ *currentfile* *path*](#16)
[__[import](../../../../index.md#import)__ *text* *configuration*](#17)
# <a name='description'></a>DESCRIPTION
This package provides a class to manage the plugins for the import of keyword
indices from other formats, i.e. their conversion from, for example
*[docidx](../../../../index.md#docidx)*, *[json](../../../../index.md#json)*,
etc.
This is one of the three public pillars the management of keyword indices
resides on. The other two pillars are
1. *[Exporting keyword indices](idx_export.md)*, and
1. *[Holding keyword indices](idx_container.md)*
For information about the [Concepts](#section2) of keyword indices, and their
parts, see the same-named section. For information about the data structure
which is the major output of the manager objects provided by this package see
the section [Keyword index serialization format](#section5).
The plugin system of our class is based on the package
__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins
using
1. the environment variable __DOCTOOLS_IDX_IMPORT_PLUGINS__,
1. the environment variable __DOCTOOLS_IDX_PLUGINS__,
1. the environment variable __DOCTOOLS_PLUGINS__,
1. the path "~/.doctools/idx/import/plugin"
1. the path "~/.doctools/idx/plugin"
1. the path "~/.doctools/plugin"
1. the path "~/.doctools/idx/import/plugins"
1. the path "~/.doctools/idx/plugins"
1. the path "~/.doctools/plugins"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\IMPORT\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
The last three are used only when the package is run on a machine using
Windows(tm) operating system.
The whole system is delivered with two predefined import plugins, namely
- docidx
See *[docidx import plugin](import_docidx.md)* for details.
- json
See *json import plugin* for details.
Readers wishing to write their own import plugin for some format, i.e. *plugin
writer*s reading and understanding the section containing the [Import plugin API
v2 reference](#section4) is an absolute necessity, as it specifies the
interaction between this package and its plugins in detail.
# <a name='section2'></a>Concepts
1. A *[keyword index](../../../../index.md#keyword_index)* consists of a
(possibly empty) set of *[keywords](../../../../index.md#keywords)*.
1. Each keyword in the set is identified by its name.
1. Each keyword has a (possibly empty) set of *references*.
1. A reference can be associated with more than one keyword.
1. A reference not associated with at least one keyword is not possible
however.
1. Each reference is identified by its target, specified as either an url or
symbolic filename, depending on the type of reference (__url__, or
__manpage__).
1. The type of a reference (url, or manpage) depends only on the reference
itself, and not the keywords it is associated with.
1. In addition to a type each reference has a descriptive label as well. This
label depends only on the reference itself, and not the keywords it is
associated with.
A few notes
1. Manpage references are intended to be used for references to the documents
the index is made for. Their target is a symbolic file name identifying the
document, and export plugins may replace symbolic with actual file names,
if specified.
1. Url references are intended on the othre hand are inteded to be used for
links to anything else, like websites. Their target is an url.
1. While url and manpage references share a namespace for their identifiers,
this should be no problem, given that manpage identifiers are symbolic
filenames and as such they should never look like urls, the identifiers for
url references.
# <a name='section3'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::doctools::idx::import__ *objectName*
This command creates a new import manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::doctools::idx::import__ command have the
following general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __import text__ *text* ?*format*?
This method takes the *text* and converts it from the specified *format* to
the canonical serialization of a keyword index using the import plugin for
the format. An error is thrown if no plugin could be found for the format.
The serialization generated by the conversion process is returned as the
result of this method.
If no format is specified the method defaults to __docidx__.
The specification of what a *canonical* serialization is can be found in the
section [Keyword index serialization format](#section5).
The plugin has to conform to the interface specified in section [Import
plugin API v2 reference](#section4).
- <a name='5'></a>*objectName* __import file__ *path* ?*format*?
This method is a convenient wrapper around the __import text__ method
described by the previous item. It reads the contents of the specified file
into memory, feeds the result into __import text__ and returns the resulting
serialization as its own result.
- <a name='6'></a>*objectName* __import object text__ *object* *text* ?*format*?
This method is a convenient wrapper around the __import text__ method
described by the previous item. It expects that *object* is an object
command supporting a __deserialize__ method expecting the canonical
serialization of a keyword index. It imports the text using __import text__
and then feeds the resulting serialization into the *object* via
__deserialize__. This method returns the empty string as it result.
- <a name='7'></a>*objectName* __import object file__ *object* *path* ?*format*?
This method behaves like __import object text__, except that it reads the
text to convert from the specified file instead of being given it as
argument.
- <a name='8'></a>*objectName* __config names__
This method returns a list containing the names of all configuration
variables currently known to the object.
- <a name='9'></a>*objectName* __config get__
This method returns a dictionary containing the names and values of all
configuration variables currently known to the object.
- <a name='10'></a>*objectName* __config set__ *name* ?*value*?
This method sets the configuration variable *name* to the specified *value*
and returns the new value of the variable.
If no value is specified it simply returns the current value, without
changing it.
Note that while the user can set the predefined configuration variables
__user__ and __format__ doing so will have no effect, these values will be
internally overridden when invoking an import plugin.
- <a name='11'></a>*objectName* __config unset__ *pattern*...
This method unsets all configuration variables matching the specified glob
*pattern*s. If no pattern is specified it will unset all currently defined
configuration variables.
- <a name='12'></a>*objectName* __includes__
This method returns a list containing the currently specified paths to use
to search for include files when processing input. The order of paths in the
list corresponds to the order in which they are used, from first to last,
and also corresponds to the order in which they were added to the object.
- <a name='13'></a>*objectName* __include add__ *path*
This methods adds the specified *path* to the list of paths to use to search
for include files when processing input. The path is added to the end of the
list, causing it to be searched after all previously added paths. The result
of the command is the empty string.
The method does nothing if the path is already known.
- <a name='14'></a>*objectName* __include remove__ *path*
This methods removes the specified *path* from the list of paths to use to
search for include files when processing input. The result of the command is
the empty string.
The method does nothing if the path is not known.
- <a name='15'></a>*objectName* __include clear__
This method clears the list of paths to use to search for include files when
processing input. The result of the command is the empty string.
# <a name='section4'></a>Import plugin API v2 reference
Plugins are what this package uses to manage the support for any input format
beyond the [Keyword index serialization format](#section5). Here we specify the
API the objects created by this package use to interact with their plugins.
A plugin for this package has to follow the rules listed below:
1. A plugin is a package.
1. The name of a plugin package has the form doctools::idx::import::__FOO__,
where __FOO__ is the name of the format the plugin will generate output
for. This name is also the argument to provide to the various __import__
methods of import manager objects to get a string encoding a keyword index
in that format.
1. The plugin can expect that the package __doctools::idx::export::plugin__ is
present, as indicator that it was invoked from a genuine plugin manager.
1. The plugin can expect that a command named __IncludeFile__ is present, with
the signature
- <a name='16'></a>__IncludeFile__ *currentfile* *path*
This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such. An example of
such a format would be *[docidx](../../../../index.md#docidx)*.
The plugin has to supply the following arguments
* string *currentfile*
The path of the file it is currently processing. This may be the
empty string if no such is known.
* string *path*
The path of the include file as specified in the include directive
being processed.
The result of the command will be a 5-element list containing
A boolean flag indicating the success (__True__) or failure (__False__)
of the operation.
In case of success the contents of the included file, and the empty
string otherwise.
The resolved, i.e. absolute path of the included file, if possible, or
the unchanged *path* argument. This is for display in an error message,
or as the *currentfile* argument of another call to __IncludeFile__
should this file contain more files.
In case of success an empty string, and for failure a code indicating
the reason for it, one of
* notfound
The specified file could not be found.
* notread
The specified file was found, but not be read into memory.
An empty string in case of success of a __notfound__ failure, and an
additional error message describing the reason for a __notread__ error
in more detail.
1. A plugin has to provide one command, with the signature shown below.
- <a name='17'></a>__[import](../../../../index.md#import)__ *text* *configuration*
Whenever an import manager of __[doctools::idx](idx_container.md)__ has
to parse input for an index it will invoke this command.
* string *text*
This argument will contain the text encoding the index per the
format the plugin is for.
* dictionary *configuration*
This argument will contain the current configuration to apply to
the parsing, as a dictionary mapping from variable names to values.
The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables
recognized by a plugin will be described in the manpage for that
plugin.
+ user
This variable is expected to contain the name of the user
owning the process invoking the plugin.
+ format
This variable is expected to contain the name of the format
whose plugin is invoked.
1. A single usage cycle of a plugin consists of the invokations of the command
__[import](../../../../index.md#import)__. This call has to leave the
plugin in a state where another usage cycle can be run without problems.
# <a name='section5'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[conversion](../../../../index.md#conversion),
[docidx](../../../../index.md#docidx),
[documentation](../../../../index.md#documentation),
[import](../../../../index.md#import), [index](../../../../index.md#index),
[json](../../../../index.md#json), [keyword
index](../../../../index.md#keyword_index),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[parsing](../../../../index.md#parsing), [plugin](../../../../index.md#plugin),
[reference](../../../../index.md#reference), [url](../../../../index.md#url)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2018 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_import_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
[//000000001]: # (doctools::idx::import::json - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::import::json(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::idx::import::json - JSON import plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [JSON notation of keyword indices](#section3)
- [Keyword index serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::import::json ?0.1?
package require doctools::idx::structure
package require json
[__[import](../../../../index.md#import)__ *string* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index import plugin for the parsing
of JSON markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::import](idx_import.md)__, the import manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::import](idx_import.md)__ and the import manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
import plugin API version 2.
- <a name='1'></a>__[import](../../../../index.md#import)__ *string* *configuration*
This command takes the *string* and parses it as JSON markup encoding a
keyword index, in the context of the specified *configuration* (a
dictionary). The result of the command is the canonical serialization of
that keyword index, in the form specified in section [Keyword index
serialization format](#section4).
# <a name='section3'></a>JSON notation of keyword indices
The JSON format used for keyword indices is a direct translation of the [Keyword
index serialization format](#section4), mapping Tcl dictionaries as JSON objects
and Tcl lists as JSON arrays. For example, the Tcl serialization
doctools::idx {
label {Keyword Index}
keywords {
changelog {changelog.man cvs.man}
conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
cvs cvs.man
}
references {
apps/dtplite.man {manpage dtplite}
changelog.man {manpage doctools::changelog}
cvs.man {manpage doctools::cvs}
docidx.man {manpage doctools::idx}
doctoc.man {manpage doctools::toc}
doctools.man {manpage doctools}
mpexpand.man {manpage mpexpand}
}
title {}
}
is equivalent to the JSON string
{
"doctools::idx" : {
"label" : "Keyword Index",
"keywords" : {
"changelog" : ["changelog.man","cvs.man"],
"conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
"cvs" : ["cvs.man"],
},
"references" : {
"apps\/dtplite.man" : ["manpage","dtplite"],
"changelog.man" : ["manpage","doctools::changelog"],
"cvs.man" : ["manpage","doctools::cvs"],
"docidx.man" : ["manpage","doctools::idx"],
"doctoc.man" : ["manpage","doctools::toc"],
"doctools.man" : ["manpage","doctools"],
"mpexpand.man" : ["manpage","mpexpand"]
},
"title" : ""
}
}
# <a name='section4'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[JSON](../../../../index.md#json),
[deserialization](../../../../index.md#deserialization),
[doctools](../../../../index.md#doctools),
[import](../../../../index.md#import), [index](../../../../index.md#index)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
[//000000001]: # (doctools2idx_introduction - Documentation tools)
[//000000002]: # (Generated from file 'idx_introduction.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools2idx_introduction(n) 2.0 tcllib "Documentation tools")
# NAME
doctools2idx_introduction - DocTools - Keyword indices
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Related formats](#section2)
- [Package Overview](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[docidx](../../../../index.md#docidx)* (short for *documentation indices*)
stands for a set of related, yet different, entities which are working together
for the easy creation and transformation of keyword indices for documentation.
These are
1. A tcl based language for the semantic markup of a keyword index. Markup is
represented by Tcl commands. Beginners should start with the *[docidx
language introduction](../doctools/docidx_lang_intro.md)*. The formal
specification is split over two documents, one dealing with the *[docidx
language syntax](../doctools/docidx_lang_syntax.md)*, the other a *[docidx
language command reference](../doctools/docidx_lang_cmdref.md)*.
1. A set of packages for the programmatic manipulation of keyword indices in
memory, and their conversion between various formats, reading and writing.
The aforementioned markup language is one of the formats which can be both
read from and written to.
1. The system for the conversion of indices is based on a plugin mechanism,
for this we have two APIs describing the interface between the packages
above and the import/export plugins.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the documentation process.
1. A *writer* of documentation has to understand the markup language itself. A
beginner to docidx should read the more informally written *[docidx
language introduction](../doctools/docidx_lang_intro.md)* first. Having
digested this the formal *[docidx language
syntax](../doctools/docidx_lang_syntax.md)* specification should become
understandable. A writer experienced with docidx may only need the *[docidx
language command reference](../doctools/docidx_lang_cmdref.md)* from time
to time to refresh her memory.
While a document is written the __dtp__ application can be used to validate
it, and after completion it also performs the conversion into the chosen
system of visual markup, be it *roff, HTML, plain text, wiki, etc. The
simpler __[dtplite](../../apps/dtplite.md)__ application makes internal use
of docidx when handling directories of documentation, automatically
generating a proper keyword index for them.
1. A *processor* of documentation written in the
*[docidx](../../../../index.md#docidx)* markup language has to know which
tools are available for use.
The main tool is the aforementioned __dtp__ application provided by Tcllib.
The simpler __[dtplite](../../apps/dtplite.md)__ does not expose docidx to
the user. At the bottom level, common to both applications, however we find
the three packages providing the basic facilities to handle keyword
indices, i.e. import from textual formats, programmatic manipulation in
memory, and export to textual formats. These are
- __[doctools::idx](idx_container.md)__
Programmatic manipulation of keyword indices in memory.
- __[doctools::idx::import](idx_import.md)__
Import of keyword indices from various textual formats. The set of
supported formats is extensible through plugin packages.
- __[doctools::idx::export](idx_export.md)__
Export of keyword indices to various textual formats. The set of
supported formats is extensible through plugin packages.
See also section [Package Overview](#section3) for an overview of the
dependencies between these and other, supporting packages.
1. At last, but not least, *plugin writers* have to understand the interaction
between the import and export packages and their plugins. These APIs are
described in the documentation for the two relevant packages, i.e.
- __[doctools::idx::import](idx_import.md)__
- __[doctools::idx::export](idx_export.md)__
# <a name='section2'></a>Related formats
The docidx format does not stand alone, it has two companion formats. These are
called *[doctoc](../../../../index.md#doctoc)* and
*[doctools](../../../../index.md#doctools)*, and they are intended for the
markup of *tables of contents*, and of general documentation, respectively. They
are described in their own sets of documents, starting at the *DocTools - Tables
Of Contents* and the *DocTools - General*, respectively.
# <a name='section3'></a>Package Overview
~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
~~ | ~~
doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
| | |
+---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+
| | | | | | | | |
doctools::config = | | | = doctools::include doctools::config doctools::paths
| | | | |
doctools::idx::export::<*> | | | doctools::idx::import::<*>
docidx | | | docidx, json
json | | | | \\
html | | | doctools::idx::parse \\
nroff | | | | \\
wiki | | | +---------------+ json
text | | | | |
doctools::idx::structure |
|
+-------+---------------+
| |
doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat
| |
doctools::text doctools::nroff::man_macros =
|
doctools::msgcat::idx::<*>
c, en, de, fr
(fr == en for now)
~~ Interoperable objects, without actual package dependencies
-- Package dependency, higher requires lower package
= Dynamic dependency through plugin system
<*> Multiple packages following the given form of naming.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx_intro](../doctools/docidx_intro.md),
[doctoc_intro](../doctools/doctoc_intro.md),
[doctools](../doctools/doctools.md), doctools2doc_introduction,
[doctools2toc_introduction](../doctools2toc/toc_introduction.md),
[doctools_lang_cmdref](../doctools/doctools_lang_cmdref.md),
[doctools_lang_faq](../doctools/doctools_lang_faq.md),
[doctools_lang_intro](../doctools/doctools_lang_intro.md),
[doctools_lang_syntax](../doctools/doctools_lang_syntax.md),
[doctools_plugin_apiref](../doctools/doctools_plugin_apiref.md)
# <a name='keywords'></a>KEYWORDS
[conversion](../../../../index.md#conversion),
[formatting](../../../../index.md#formatting),
[index](../../../../index.md#index), [keyword
index](../../../../index.md#keyword_index),
[markup](../../../../index.md#markup), [parsing](../../../../index.md#parsing),
[plugin](../../../../index.md#plugin), [semantic
markup](../../../../index.md#semantic_markup)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_c.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::idx::c - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::idx::c(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::idx::c - Message catalog for the docidx parser (C)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::c ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::idx::c__ is a support module providing the C
language message catalog for the docidx parser in the doctools system version 2.
As such it is an internal package a regular user (developer) should not be in
direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[C](../../../../index.md#c), [catalog
package](../../../../index.md#catalog_package),
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_de.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::idx::de - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::idx::de(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::idx::de - Message catalog for the docidx parser (DE)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::de ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::idx::de__ is a support module providing the DE
(german) language message catalog for the docidx parser in the doctools system
version 2. As such it is an internal package a regular user (developer) should
not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[DE](../../../../index.md#de), [catalog
package](../../../../index.md#catalog_package),
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_en.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::idx::en - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::idx::en(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::idx::en - Message catalog for the docidx parser (EN)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::en ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::idx::en__ is a support module providing the EN
(english) language message catalog for the docidx parser in the doctools system
version 2. As such it is an internal package a regular user (developer) should
not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[EN](../../../../index.md#en), [catalog
package](../../../../index.md#catalog_package),
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_fr.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::idx::fr - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::idx::fr(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::idx::fr - Message catalog for the docidx parser (FR)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::idx::fr ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::idx::fr__ is a support module providing the FR
(french) language message catalog for the docidx parser in the doctools system
version 2. As such it is an internal package a regular user (developer) should
not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[FR](../../../../index.md#fr), [catalog
package](../../../../index.md#catalog_package),
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_parse.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
[//000000001]: # (doctools::idx::parse - Documentation tools)
[//000000002]: # (Generated from file 'idx_parse.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::parse(n) 1 tcllib "Documentation tools")
# NAME
doctools::idx::parse - Parsing text in docidx format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Parse errors](#section3)
- [[docidx] notation of keyword indices](#section4)
- [Keyword index serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::idx::parse ?0.1?
package require Tcl 8.4
package require doctools::idx::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::stack
[__::doctools::idx::parse__ __text__ *text*](#1)
[__::doctools::idx::parse__ __file__ *path*](#2)
[__::doctools::idx::parse__ __includes__](#3)
[__::doctools::idx::parse__ __include add__ *path*](#4)
[__::doctools::idx::parse__ __include remove__ *path*](#5)
[__::doctools::idx::parse__ __include clear__](#6)
[__::doctools::idx::parse__ __vars__](#7)
[__::doctools::idx::parse__ __var set__ *name* *value*](#8)
[__::doctools::idx::parse__ __var unset__ *name*](#9)
[__::doctools::idx::parse__ __var clear__ ?*pattern*?](#10)
# <a name='description'></a>DESCRIPTION
This package provides commands to parse text written in the
*[docidx](../../../../index.md#docidx)* markup language and convert it into the
canonical serialization of the keyword index encoded in the text. See the
section [Keyword index serialization format](#section5) for specification of
their format.
This is an internal package of doctools, for use by the higher level packages
handling *[docidx](../../../../index.md#docidx)* documents.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::idx::parse__ __text__ *text*
The command takes the string contained in *text* and parses it under the
assumption that it contains a document written using the
*[docidx](../../../../index.md#docidx)* markup language. An error is thrown
if this assumption is found to be false. The format of these errors is
described in section [Parse errors](#section3).
When successful the command returns the canonical serialization of the
keyword index which was encoded in the text. See the section [Keyword index
serialization format](#section5) for specification of that format.
- <a name='2'></a>__::doctools::idx::parse__ __file__ *path*
The same as __text__, except that the text to parse is read from the file
specified by *path*.
- <a name='3'></a>__::doctools::idx::parse__ __includes__
This method returns the current list of search paths used when looking for
include files.
- <a name='4'></a>__::doctools::idx::parse__ __include add__ *path*
This method adds the *path* to the list of paths searched when looking for
an include file. The call is ignored if the path is already in the list of
paths. The method returns the empty string as its result.
- <a name='5'></a>__::doctools::idx::parse__ __include remove__ *path*
This method removes the *path* from the list of paths searched when looking
for an include file. The call is ignored if the path is not contained in the
list of paths. The method returns the empty string as its result.
- <a name='6'></a>__::doctools::idx::parse__ __include clear__
This method clears the list of search paths for include files.
- <a name='7'></a>__::doctools::idx::parse__ __vars__
This method returns a dictionary containing the current set of predefined
variables known to the __vset__ markup command during processing.
- <a name='8'></a>__::doctools::idx::parse__ __var set__ *name* *value*
This method adds the variable *name* to the set of predefined variables
known to the __vset__ markup command during processing, and gives it the
specified *value*. The method returns the empty string as its result.
- <a name='9'></a>__::doctools::idx::parse__ __var unset__ *name*
This method removes the variable *name* from the set of predefined variables
known to the __vset__ markup command during processing. The method returns
the empty string as its result.
- <a name='10'></a>__::doctools::idx::parse__ __var clear__ ?*pattern*?
This method removes all variables matching the *pattern* from the set of
predefined variables known to the __vset__ markup command during processing.
The method returns the empty string as its result.
The pattern matching is done with __string match__, and the default pattern
used when none is specified, is __*__.
# <a name='section3'></a>Parse errors
The format of the parse error messages thrown when encountering violations of
the *[docidx](../../../../index.md#docidx)* markup syntax is human readable and
not intended for processing by machines. As such it is not documented.
*However*, the errorCode attached to the message is machine-readable and has the
following format:
1. The error code will be a list, each element describing a single error found
in the input. The list has at least one element, possibly more.
1. Each error element will be a list containing six strings describing an
error in detail. The strings will be
1) The path of the file the error occurred in. This may be empty.
1) The range of the token the error was found at. This range is a
two-element list containing the offset of the first and last character
in the range, counted from the beginning of the input (file). Offsets
are counted from zero.
1) The line the first character after the error is on. Lines are counted
from one.
1) The column the first character after the error is at. Columns are
counted from zero.
1) The message code of the error. This value can be used as argument to
__msgcat::mc__ to obtain a localized error message, assuming that the
application had a suitable call of __doctools::msgcat::init__ to
initialize the necessary message catalogs (See package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__).
1) A list of details for the error, like the markup command involved. In
the case of message code __docidx/include/syntax__ this value is the
set of errors found in the included file, using the format described
here.
# <a name='section4'></a>[docidx] notation of keyword indices
The docidx format for keyword indices, also called the *docidx markup language*,
is too large to be covered in single section. The interested reader should start
with the document
1. *[docidx language introduction](../doctools/docidx_lang_intro.md)*
and then proceed from there to the formal specifications, i.e. the documents
1. *[docidx language syntax](../doctools/docidx_lang_syntax.md)* and
1. *[docidx language command reference](../doctools/docidx_lang_cmdref.md)*.
to get a thorough understanding of the language.
# <a name='section5'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools), [lexer](../../../../index.md#lexer),
[parser](../../../../index.md#parser)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/idx_structure.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
[//000000001]: # (doctools::idx::structure - Documentation tools)
[//000000002]: # (Generated from file 'idx_structure.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::structure(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::idx::structure - Docidx serialization utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Keyword index serialization format](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::idx::structure ?0.1?
package require Tcl 8.4
package require logger
package require snit
[__::doctools::idx::structure__ __verify__ *serial* ?*canonvar*?](#1)
[__::doctools::idx::structure__ __verify-as-canonical__ *serial*](#2)
[__::doctools::idx::structure__ __canonicalize__ *serial*](#3)
[__::doctools::idx::structure__ __print__ *serial*](#4)
[__::doctools::idx::structure__ __merge__ *seriala* *serialb*](#5)
# <a name='description'></a>DESCRIPTION
This package provides commands to work with the serializations of keyword
indices as managed by the doctools system v2, and specified in section [Keyword
index serialization format](#section3).
This is an internal package of doctools, for use by the higher level packages
handling keyword indices and their conversion into and out of various other
formats, like documents written using *[docidx](../../../../index.md#docidx)*
markup.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::idx::structure__ __verify__ *serial* ?*canonvar*?
This command verifies that the content of *serial* is a valid *regular*
serialization of a keyword index and will throw an error if that is not the
case. The result of the command is the empty string.
If the argument *canonvar* is specified it is interpreted as the name of a
variable in the calling context. This variable will be written to if and
only if *serial* is a valid regular serialization. Its value will be a
boolean, with __True__ indicating that the serialization is not only valid,
but also *canonical*. __False__ will be written for a valid, but
non-canonical serialization.
For the specification of regular and canonical keyword index serializations
see the section [Keyword index serialization format](#section3).
- <a name='2'></a>__::doctools::idx::structure__ __verify-as-canonical__ *serial*
This command verifies that the content of *serial* is a valid *canonical*
serialization of a keyword index and will throw an error if that is not the
case. The result of the command is the empty string.
For the specification of canonical keyword index serializations see the
section [Keyword index serialization format](#section3).
- <a name='3'></a>__::doctools::idx::structure__ __canonicalize__ *serial*
This command assumes that the content of *serial* is a valid *regular*
serialization of a keyword index and will throw an error if that is not the
case.
It will then convert the input into the *canonical* serialization of the
contained keyword index and return it as its result. If the input is already
canonical it will be returned unchanged.
For the specification of regular and canonical keyword index serializations
see the section [Keyword index serialization format](#section3).
- <a name='4'></a>__::doctools::idx::structure__ __print__ *serial*
This command assumes that the argument *serial* contains a valid regular
serialization of a keyword index and returns a string containing that index
in a human readable form.
The exact format of this form is not specified and cannot be relied on for
parsing or other machine-based activities.
For the specification of regular keyword index serializations see the
section [Keyword index serialization format](#section3).
- <a name='5'></a>__::doctools::idx::structure__ __merge__ *seriala* *serialb*
This command accepts the regular serializations of two keyword indices and
uses them to create their union. The result of the command is the canonical
serialization of this unified keyword index.
Title and label of the resulting index are taken from the index contained in
*serialb*. The set of keys, references and their connections is the union of
the set of keys and references of the two inputs.
For the specification of regular and canonical keyword index serializations
see the section [Keyword index serialization format](#section3).
# <a name='section3'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[deserialization](../../../../index.md#deserialization),
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2idx/import_docidx.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
[//000000001]: # (doctools::idx::import::docidx - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::idx::import::docidx(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::idx::import::docidx - docidx import plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [[docidx] notation of keyword indices](#section3)
- [Keyword index serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::idx::import::docidx ?0.1?
package require doctools::idx::parse
package require doctools::idx::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::set
package require struct::stack
package require struct::tree
package require treeql
[__[import](../../../../index.md#import)__ *string* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools keyword index import plugin for the parsing
of docidx markup.
This is an internal package of doctools, for use by the higher level management
packages handling keyword indices, especially
__[doctools::idx::import](idx_import.md)__, the import manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::idx::import](idx_import.md)__ and the import manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the docidx
import plugin API version 2.
- <a name='1'></a>__[import](../../../../index.md#import)__ *string* *configuration*
This command takes the *string* and parses it as docidx markup encoding a
keyword index, in the context of the specified *configuration* (a
dictionary). The result of the command is the canonical serialization of
that keyword index, in the form specified in section [Keyword index
serialization format](#section4).
# <a name='section3'></a>[docidx] notation of keyword indices
The docidx format for keyword indices, also called the *docidx markup language*,
is too large to be covered in single section. The interested reader should start
with the document
1. *[docidx language introduction](../doctools/docidx_lang_intro.md)*
and then proceed from there to the formal specifications, i.e. the documents
1. *[docidx language syntax](../doctools/docidx_lang_syntax.md)* and
1. *[docidx language command reference](../doctools/docidx_lang_cmdref.md)*.
to get a thorough understanding of the language.
# <a name='section4'></a>Keyword index serialization format
Here we specify the format used by the doctools v2 packages to serialize keyword
indices as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a keyword
index may have more than one regular serialization only exactly one of them will
be *canonical*.
- regular serialization
An index serialization is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::idx__, and its value. This
value holds the contents of the index.
The contents of the index are a Tcl dictionary holding the title of the
index, a label, and the keywords and references. The relevant keys and their
values are
* __title__
The value is a string containing the title of the index.
* __label__
The value is a string containing a label for the index.
* __keywords__
The value is a Tcl dictionary, using the keywords known to the
index as keys. The associated values are lists containing the
identifiers of the references associated with that particular
keyword.
Any reference identifier used in these lists has to exist as a key
in the __references__ dictionary, see the next item for its
definition.
* __references__
The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.
Any key here has to be associated with at least one keyword, i.e.
occur in at least one of the reference lists which are the values
in the __keywords__ dictionary, see previous item for its
definition.
The *[type](../../../../index.md#type)* of a reference can be one of two
values,
* __manpage__
The identifier of the reference is interpreted as symbolic file
name, referring to one of the documents the index was made for.
* __url__
The identifier of the reference is interpreted as an url, referring
to some external location, like a website, etc.
- canonical serialization
The canonical serialization of a keyword index has the format as specified
in the previous item, and then additionally satisfies the constraints below,
which make it unique among all the possible serializations of the keyword
index.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The references listed for each keyword of the index, if any, are listed in
ascending dictionary order of their *labels*, as generated by Tcl's builtin
command __lsort -increasing -dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[deserialization](../../../../index.md#deserialization),
[docidx](../../../../index.md#docidx),
[doctools](../../../../index.md#doctools),
[import](../../../../index.md#import), [index](../../../../index.md#index)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/export_doctoc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
|
[//000000001]: # (doctools::toc::export::doctoc - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export::doctoc(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::export::doctoc - doctoc export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [[doctoc] notation of tables of contents](#section3)
- [Configuration](#section4)
- [ToC serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::export::doctoc ?0.1?
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents export plugin for the
generation of doctoc markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::export](toc_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::export](toc_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a table of contents, as
specified in section [ToC serialization format](#section5), and contained in
*serial*, the *configuration*, a dictionary, and generates doctoc markup
encoding the table. The created string is then returned as the result of the
command.
# <a name='section3'></a>[doctoc] notation of tables of contents
The doctoc format for tables of contents, also called the *doctoc markup
language*, is too large to be covered in single section. The interested reader
should start with the document
1. *[doctoc language introduction](../doctools/doctoc_lang_intro.md)*
and then proceed from there to the formal specifications, i.e. the documents
1. *[doctoc language syntax](../doctools/doctoc_lang_syntax.md)* and
1. *[doctoc language command reference](../doctools/doctoc_lang_cmdref.md)*.
to get a thorough understanding of the language.
# <a name='section4'></a>Configuration
The doctoc export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *user*
This standard configuration variable contains the name of the user running
the process which invoked the export plugin. The plugin puts this
information into the provenance comment at the beginning of the generated
document.
- string *file*
This standard configuration variable contains the name of the file the table
of contents came from. This variable may not be set or contain the empty
string. The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the generated
document.
- boolean *newlines*
If this flag is set the plugin will break the generated doctoc code across
lines, with each markup command on a separate line.
If this flag is not set (the default), the whole document will be written on
a single line, with minimum spacing between all elements.
- boolean *indented*
If this flag is set the plugin will indent the markup commands according to
the structure of tables of contents. To make this work this also implies
that __newlines__ is set. This effect is independent of the value for
__aligned__ however.
If this flag is not set (the default), the output is formatted as per the
value of __newlines__, and no indenting is done.
- boolean *aligned*
If this flag is set the generator ensures that the arguments for the
__item__ commands in a division are aligned vertically for a nice table
effect. To make this work this also implies that __newlines__ is set. This
effect is independent of the value for __indented__ however.
If this flag is not set (the default), the output is formatted as per the
values of __newlines__ and __indented__, and no alignment is done.
*Note* that this plugin ignores the standard configuration variables __format__,
and __map__, and their values.
# <a name='section5'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export),
[serialization](../../../../index.md#serialization), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/import_doctoc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
[//000000001]: # (doctools::toc::import::doctoc - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::import::doctoc(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::import::doctoc - doctoc import plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [[doctoc] notation of tables of contents](#section3)
- [ToC serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::import::doctoc ?0.1?
package require doctools::toc::parse
package require doctools::toc::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::set
package require struct::stack
package require struct::tree
package require treeql
[__[import](../../../../index.md#import)__ *string* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents import plugin for the
parsing of doctoc markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::import](toc_import.md)__, the import manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::import](toc_import.md)__ and the import manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
import plugin API version 2.
- <a name='1'></a>__[import](../../../../index.md#import)__ *string* *configuration*
This command takes the *string* and parses it as doctoc markup encoding a
table of contents, in the context of the specified *configuration* (a
dictionary). The result of the command is the canonical serialization of
that table of contents, in the form specified in section [ToC serialization
format](#section4).
# <a name='section3'></a>[doctoc] notation of tables of contents
The doctoc format for tables of contents, also called the *doctoc markup
language*, is too large to be covered in single section. The interested reader
should start with the document
1. *[doctoc language introduction](../doctools/doctoc_lang_intro.md)*
and then proceed from there to the formal specifications, i.e. the documents
1. *[doctoc language syntax](../doctools/doctoc_lang_syntax.md)* and
1. *[doctoc language command reference](../doctools/doctoc_lang_cmdref.md)*.
to get a thorough understanding of the language.
# <a name='section4'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[deserialization](../../../../index.md#deserialization),
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools),
[import](../../../../index.md#import), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
|
[//000000001]: # (doctools::toc - Documentation tools)
[//000000002]: # (Generated from file 'toc_container.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc(n) 2 tcllib "Documentation tools")
# NAME
doctools::toc - Holding tables of contents
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [API](#section3)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [ToC serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::toc ?2?
package require Tcl 8.4
package require doctools::toc::structure
package require struct::tree
package require snit
[__::doctools::toc__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __+ reference__ *id* *label* *docid* *desc*](#4)
[*objectName* __+ division__ *id* *label* ?*docid*?](#5)
[*objectName* __remove__ *id*](#6)
[*objectName* __up__ *id*](#7)
[*objectName* __next__ *id*](#8)
[*objectName* __prev__ *id*](#9)
[*objectName* __child__ *id* *label* ?*...*?](#10)
[*objectName* __element__ ?*...*?](#11)
[*objectName* __children__ *id*](#12)
[*objectName* __type__ *id*](#13)
[*objectName* __full-label__ *id*](#14)
[*objectName* __elabel__ *id* ?*newlabel*?](#15)
[*objectName* __description__ *id* ?*newdesc*?](#16)
[*objectName* __document__ *id* ?*newdocid*?](#17)
[*objectName* __title__](#18)
[*objectName* __title__ *text*](#19)
[*objectName* __label__](#20)
[*objectName* __label__ *text*](#21)
[*objectName* __importer__](#22)
[*objectName* __importer__ *object*](#23)
[*objectName* __exporter__](#24)
[*objectName* __exporter__ *object*](#25)
[*objectName* __deserialize =__ *data* ?*format*?](#26)
[*objectName* __deserialize +=__ *data* ?*format*?](#27)
[*objectName* __serialize__ ?*format*?](#28)
# <a name='description'></a>DESCRIPTION
This package provides a class to contain and programmatically manipulate tables
of contents.
This is one of the three public pillars the management of tables of contents
resides on. The other two pillars are
1. *[Exporting tables of contents](toc_export.md)*, and
1. *Importing tables of contents*
For information about the [Concepts](#section2) of tables of contents, and their
parts, see the same-named section. For information about the data structure
which is used to encode tables of contents as values see the section [ToC
serialization format](#section4). This is the only format directly known to this
class. Conversions from and to any other format are handled by export and import
manager objects. These may be attached to a container, but do not have to be, it
is merely a convenience.
# <a name='section2'></a>Concepts
1. A *[table of contents](../../../../index.md#table_of_contents)* consists of
a (possibly empty) list of *elements*.
1. Each element in the list is identified by its label.
1. Each element is either a *[reference](../../../../index.md#reference)*, or
a *division*.
1. Each reference has an associated document, identified by a symbolic id, and
a textual description.
1. Each division may have an associated document, identified by a symbolic id.
1. Each division consists consists of a (possibly empty) list of *elements*,
with each element following the rules as specified in item 2 and above.
A few notes
1. The above rules span up a tree of elements, with references as the leaf
nodes, and divisions as the inner nodes, and each element representing an
entry in the whole table of contents.
1. The identifying labels of any element E are unique within their division
(or toc), and the full label of any element E is the list of labels for all
nodes on the unique path from the root of the tree to E, including E.
# <a name='section3'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::doctools::toc__ *objectName*
This command creates a new container object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [Object
command](#subsection2) and [Object methods](#subsection3). The object
command will be created under the current namespace if the *objectName* is
not fully qualified, and in the specified namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::doctools::toc__ command have the following
general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __+ reference__ *id* *label* *docid* *desc*
This method adds a new reference element to the table of contents, under the
element specified via its handle *id*. This parent element has to be a
division element, or the root. An error is thrown otherwise. The new element
will be externally identified by its *label*, which has to be be unique
within the parent element. An error is thrown otherwise.
As a reference element it will refer to a document identified by the
symbolic *docid*. This reference must not be the empty string, an error is
thrown otherwise. Beyond the label the element also has a longer descriptive
string, supplied via *desc*.
The result of the method is the handle (id) of the new element.
- <a name='5'></a>*objectName* __+ division__ *id* *label* ?*docid*?
This method adds a new division element to the table of contents, under the
element specified via its handle *id*. This parent element has to be a
division element, or the root. An error is thrown otherwise. The new element
will be externally identified by its *label*, which has to be be unique
within the parent element. An error is thrown otherwise.
As a division element it is can refer to a document, identified by the
symbolic *docid*, but may choose not to.
The result of the method is the handle (id) of the new element.
- <a name='6'></a>*objectName* __remove__ *id*
This method removes the element identified by the handle *id* from the table
of contents. If the element is a division all of its children, if any, are
removed as well. The root element/division of the table of contents cannot
be removed however, only its children.
The result of the method is the empty string.
- <a name='7'></a>*objectName* __up__ *id*
This method returns the handle of the parent for the element identified by
its handle *id*, or the empty string if *id* referred to the root element.
- <a name='8'></a>*objectName* __next__ *id*
This method returns the handle of the right sibling for the element
identified by its handle *id*, or the handle of the parent if the element
has no right sibling, or the empty string if *id* referred to the root
element.
- <a name='9'></a>*objectName* __prev__ *id*
This method returns the handle of the left sibling for the element
identified by its handle *id*, or the handle of the parent if the element
has no left sibling, or the empty string if *id* referred to the root
element.
- <a name='10'></a>*objectName* __child__ *id* *label* ?*...*?
This method returns the handle of a child of the element identified by its
handle *id*. The child itself is identified by a series of labels.
- <a name='11'></a>*objectName* __element__ ?*...*?
This method returns the handle of the element identified by a series of
labels, starting from the root of the table of contents. The series of
labels is allowed to be empty, in which case the handle of the root element
is returned.
- <a name='12'></a>*objectName* __children__ *id*
This method returns a list containing the handles of all children of the
element identified by the handle *id*, from first to last, in that order.
- <a name='13'></a>*objectName* __type__ *id*
This method returns the type of the element, either __reference__, or
__division__.
- <a name='14'></a>*objectName* __full-label__ *id*
This method is the complement of the method __element__, converting the
handle *id* of an element into a list of labels full identifying the element
within the whole table of contents.
- <a name='15'></a>*objectName* __elabel__ *id* ?*newlabel*?
This method queries and/or changes the label of the element identified by
the handle *id*. If the argument *newlabel* is present then the label is
changed to that value. Regardless of this, the result of the method is the
current value of the label.
If the label is changed the new label has to be unique within the containing
division, or an error is thrown.
Further, of the *id* refers to the root element of the table of contents,
then using this method is equivalent to using the method *label*, i.e. it is
accessing the global label for the whole table.
- <a name='16'></a>*objectName* __description__ *id* ?*newdesc*?
This method queries and/or changes the description of the element identified
by the handle *id*. If the argument *newdesc* is present then the
description is changed to that value. Regardless of this, the result of the
method is the current value of the description.
The element this method operates on has to be a reference element, or an
error will be thrown.
- <a name='17'></a>*objectName* __document__ *id* ?*newdocid*?
This method queries and/or changes the document reference of the element
identified by the handle *id*. If the argument *newdocid* is present then
the description is changed to that value. Regardless of this, the result of
the method is the current value of the document reference.
Setting the reference to the empty string means unsetting it, and is allowed
only for division elements. Conversely, if the result is the empty string
then the element has no document reference, and this can happen only for
division elements.
- <a name='18'></a>*objectName* __title__
Returns the currently defined title of the table of contents.
- <a name='19'></a>*objectName* __title__ *text*
Sets the title of the table of contents to *text*, and returns it as the
result of the command.
- <a name='20'></a>*objectName* __label__
Returns the currently defined label of the table of contents.
- <a name='21'></a>*objectName* __label__ *text*
Sets the label of the table of contents to *text*, and returns it as the
result of the command.
- <a name='22'></a>*objectName* __importer__
Returns the import manager object currently attached to the container, if
any.
- <a name='23'></a>*objectName* __importer__ *object*
Attaches the *object* as import manager to the container, and returns it as
the result of the command. Note that the *object* is *not* put into
ownership of the container. I.e., destruction of the container will *not*
destroy the *object*.
It is expected that *object* provides a method named __import text__ which
takes a text and a format name, and returns the canonical serialization of
the table of contents contained in the text, assuming the given format.
- <a name='24'></a>*objectName* __exporter__
Returns the export manager object currently attached to the container, if
any.
- <a name='25'></a>*objectName* __exporter__ *object*
Attaches the *object* as export manager to the container, and returns it as
the result of the command. Note that the *object* is *not* put into
ownership of the container. I.e., destruction of the container will *not*
destroy the *object*.
It is expected that *object* provides a method named __export object__ which
takes the container and a format name, and returns a text encoding table of
contents stored in the container, in the given format. It is further
expected that the *object* will use the container's method __serialize__ to
obtain the serialization of the table of contents from which to generate the
text.
- <a name='26'></a>*objectName* __deserialize =__ *data* ?*format*?
This method replaces the contents of the table object with the table
contained in the *data*. If no *format* was specified it is assumed to be
the regular serialization of a table of contents.
Otherwise the object will use the attached import manager to convert the
data from the specified format to a serialization it can handle. In that
case an error will be thrown if the container has no import manager attached
to it.
The result of the method is the empty string.
- <a name='27'></a>*objectName* __deserialize +=__ *data* ?*format*?
This method behaves like __deserialize =__ in its essentials, except that it
merges the table of contents in the *data* to its contents instead of
replacing it. The method will throw an error if merging is not possible,
i.e. would produce an invalid table. The existing content is left unchanged
in that case.
The result of the method is the empty string.
- <a name='28'></a>*objectName* __serialize__ ?*format*?
This method returns the table of contents contained in the object. If no
*format* is not specified the returned result is the canonical serialization
of its contents.
Otherwise the object will use the attached export manager to convert the
data to the specified format. In that case an error will be thrown if the
container has no export manager attached to it.
# <a name='section4'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion), [doctoc
markup](../../../../index.md#doctoc_markup),
[documentation](../../../../index.md#documentation),
[formatting](../../../../index.md#formatting),
[generation](../../../../index.md#generation),
[json](../../../../index.md#json), [latex](../../../../index.md#latex),
[markup](../../../../index.md#markup), [nroff](../../../../index.md#nroff),
[parsing](../../../../index.md#parsing), [plugin](../../../../index.md#plugin),
[reference](../../../../index.md#reference),
[table](../../../../index.md#table), [table of
contents](../../../../index.md#table_of_contents), [tcler's
wiki](../../../../index.md#tcler_s_wiki), [text](../../../../index.md#text),
[wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_export.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
|
[//000000001]: # (doctools::toc::export - Documentation tools)
[//000000002]: # (Generated from file 'toc_export.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::toc::export - Exporting tables of contents
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [API](#section3)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Export plugin API v2 reference](#section4)
- [ToC serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::toc::export ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::toc::structure
package require snit
package require pluginmgr
[__::doctools::toc::export__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __export serial__ *serial* ?*format*?](#4)
[*objectName* __export object__ *object* ?*format*?](#5)
[*objectName* __config names__](#6)
[*objectName* __config get__](#7)
[*objectName* __config set__ *name* ?*value*?](#8)
[*objectName* __config unset__ *pattern*...](#9)
[__[export](../../../../index.md#export)__ *serial* *configuration*](#10)
# <a name='description'></a>DESCRIPTION
This package provides a class to manage the plugins for the export of tables of
contents to other formats, i.e. their conversion to, for example
*[doctoc](../../../../index.md#doctoc)*, *[HTML](../../../../index.md#html)*,
etc.
This is one of the three public pillars the management of tables of contents
resides on. The other two pillars are
1. *Importing tables of contents*, and
1. *[Holding tables of contents](toc_container.md)*
For information about the [Concepts](#section2) of tables of contents, and their
parts, see the same-named section. For information about the data structure
which is the major input to the manager objects provided by this package see the
section [ToC serialization format](#section5).
The plugin system of our class is based on the package
__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins
using
1. the environment variable __DOCTOOLS_TOC_EXPORT_PLUGINS__,
1. the environment variable __DOCTOOLS_TOC_PLUGINS__,
1. the environment variable __DOCTOOLS_PLUGINS__,
1. the path "~/.doctools/toc/export/plugin"
1. the path "~/.doctools/toc/plugin"
1. the path "~/.doctools/plugin"
1. the path "~/.doctools/toc/export/plugins"
1. the path "~/.doctools/toc/plugins"
1. the path "~/.doctools/plugins"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\EXPORT\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
The last three are used only when the package is run on a machine using
Windows(tm) operating system.
The whole system is delivered with six predefined export plugins, namely
- doctoc
See *[doctoc export plugin](export_doctoc.md)* for details.
- html
See *html export plugin* for details.
- json
See *json export plugin* for details.
- nroff
See *[nroff export plugin](toc_export_nroff.md)* for details.
- text
See *text export plugin* for details.
- wiki
See *[wiki export plugin](toc_export_wiki.md)* for details.
Readers wishing to write their own export plugin for some format, i.e. *plugin
writer*s reading and understanding the section containing the [Export plugin API
v2 reference](#section4) is an absolute necessity, as it specifies the
interaction between this package and its plugins in detail.
# <a name='section2'></a>Concepts
1. A *[table of contents](../../../../index.md#table_of_contents)* consists of
a (possibly empty) list of *elements*.
1. Each element in the list is identified by its label.
1. Each element is either a *[reference](../../../../index.md#reference)*, or
a *division*.
1. Each reference has an associated document, identified by a symbolic id, and
a textual description.
1. Each division may have an associated document, identified by a symbolic id.
1. Each division consists consists of a (possibly empty) list of *elements*,
with each element following the rules as specified in item 2 and above.
A few notes
1. The above rules span up a tree of elements, with references as the leaf
nodes, and divisions as the inner nodes, and each element representing an
entry in the whole table of contents.
1. The identifying labels of any element E are unique within their division
(or toc), and the full label of any element E is the list of labels for all
nodes on the unique path from the root of the tree to E, including E.
# <a name='section3'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::doctools::toc::export__ *objectName*
This command creates a new export manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::doctools::toc::export__ command have the
following general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __export serial__ *serial* ?*format*?
This method takes the canonical serialization of a table of contents stored
in *serial* and converts it to the specified *format*, using the export
plugin for the format. An error is thrown if no plugin could be found for
the format. The string generated by the conversion process is returned as
the result of this method.
If no format is specified the method defaults to __doctoc__.
The specification of what a *canonical* serialization is can be found in the
section [ToC serialization format](#section5).
The plugin has to conform to the interface specified in section [Export
plugin API v2 reference](#section4).
- <a name='5'></a>*objectName* __export object__ *object* ?*format*?
This method is a convenient wrapper around the __export serial__ method
described by the previous item. It expects that *object* is an object
command supporting a __serialize__ method returning the canonical
serialization of a table of contents. It invokes that method, feeds the
result into __export serial__ and returns the resulting string as its own
result.
- <a name='6'></a>*objectName* __config names__
This method returns a list containing the names of all configuration
variables currently known to the object.
- <a name='7'></a>*objectName* __config get__
This method returns a dictionary containing the names and values of all
configuration variables currently known to the object.
- <a name='8'></a>*objectName* __config set__ *name* ?*value*?
This method sets the configuration variable *name* to the specified *value*
and returns the new value of the variable.
If no value is specified it simply returns the current value, without
changing it.
Note that while the user can set the predefined configuration variables
__user__ and __format__ doing so will have no effect, these values will be
internally overridden when invoking an import plugin.
- <a name='9'></a>*objectName* __config unset__ *pattern*...
This method unsets all configuration variables matching the specified glob
*pattern*s. If no pattern is specified it will unset all currently defined
configuration variables.
# <a name='section4'></a>Export plugin API v2 reference
Plugins are what this package uses to manage the support for any output format
beyond the [ToC serialization format](#section5). Here we specify the API the
objects created by this package use to interact with their plugins.
A plugin for this package has to follow the rules listed below:
1. A plugin is a package.
1. The name of a plugin package has the form doctools::toc::export::__FOO__,
where __FOO__ is the name of the format the plugin will generate output
for. This name is also the argument to provide to the various __export__
methods of export manager objects to get a string encoding a table of
contents in that format.
1. The plugin can expect that the package __doctools::toc::export::plugin__ is
present, as indicator that it was invoked from a genuine plugin manager.
1. A plugin has to provide one command, with the signature shown below.
- <a name='10'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
Whenever an export manager of
__[doctools::toc](../doctools/doctoc.md)__ has to generate output for a
table of contents it will invoke this command.
* string *serial*
This argument will contain the *canonical* serialization of the
table of contents for which to generate the output. The
specification of what a *canonical* serialization is can be found
in the section [ToC serialization format](#section5).
* dictionary *configuration*
This argument will contain the current configuration to apply to
the generation, as a dictionary mapping from variable names to
values.
The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables
recognized by a plugin will be described in the manpage for that
plugin.
+ user
This variable is expected to contain the name of the user
owning the process invoking the plugin.
+ format
This variable is expected to contain the name of the format
whose plugin is invoked.
+ file
This variable, if defined by the user of the table object is
expected to contain the name of the input file for which the
plugin is generating its output for.
+ map
This variable, if defined by the user of the table object is
expected to contain a dictionary mapping from symbolic document
ids used in the table entries to actual paths (or urls). A
plugin has to be able to handle the possibility that a document
id is without entry in this mapping.
1. A single usage cycle of a plugin consists of the invokations of the command
__[export](../../../../index.md#export)__. This call has to leave the
plugin in a state where another usage cycle can be run without problems.
# <a name='section5'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html),
[conversion](../../../../index.md#conversion),
[doctoc](../../../../index.md#doctoc),
[documentation](../../../../index.md#documentation),
[export](../../../../index.md#export),
[formatting](../../../../index.md#formatting),
[generation](../../../../index.md#generation),
[json](../../../../index.md#json), [manpage](../../../../index.md#manpage),
[markup](../../../../index.md#markup), [nroff](../../../../index.md#nroff),
[plugin](../../../../index.md#plugin),
[reference](../../../../index.md#reference),
[table](../../../../index.md#table), [table of
contents](../../../../index.md#table_of_contents), [tcler's
wiki](../../../../index.md#tcler_s_wiki), [text](../../../../index.md#text),
[url](../../../../index.md#url), [wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2018 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_export_html.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
[//000000001]: # (doctools::toc::export::html - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export::html(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::export::html - HTML export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [ToC serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::export::html ?0.1?
package require doctools::text
package require doctools::html
package require doctools::html::cssdefaults
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents export plugin for the
generation of HTML markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::export](toc_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::export](toc_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a table of contents, as
specified in section [ToC serialization format](#section4), and contained in
*serial*, the *configuration*, a dictionary, and generates HTML markup
encoding the table. The created string is then returned as the result of the
command.
# <a name='section3'></a>Configuration
The html export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *user*
This standard configuration variable contains the name of the user running
the process which invoked the export plugin. The plugin puts this
information into the provenance comment at the beginning of the generated
document.
- string *file*
This standard configuration variable contains the name of the file the table
of contents came from. This variable may not be set or contain the empty
string. The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the generated
document.
- dictionary *map*
This standard configuration variable contains a dictionary mapping from the
(symbolic) document ids in reference entries to the actual filenames and/or
urls to be used in the output.
Document ids without a mapping are used unchanged.
- boolean *newlines*
If this flag is set the plugin will break the generated html code across
lines, with each markup command on a separate line.
If this flag is not set (the default), the whole document will be written on
a single line, with minimum spacing between all elements.
- boolean *indented*
If this flag is set the plugin will indent the markup commands according to
the structure of indices. To make this work this also implies that
__newlines__ is set.
If this flag is not set (the default), the output is formatted as per the
value of __newlines__, and no indenting is done.
- string *meta*
This variable is meant to hold a fragment of HTML (default: empty). The
fragment it contains will be inserted into the generated output in the
<head> section of the document, just after the <title> tag.
- string *header*
This variable is meant to hold a fragment of HTML (default: empty). The
fragment it contains will be inserted into the generated output just after
the <h1> title tag in the body of the document, in the class.header
<div>'ision.
- string *footer*
This variable is meant to hold a fragment of HTML (default: empty). The
fragment it contains will be inserted into the generated output just before
the </body> tag, in the class.footer <div>'ision.
- dictionary *rid*
The value of this variable (default: empty) maps references to the
identifiers to use as their anchor names. Each reference __FOO__ not found
in the dictionary uses __REF-____FOO__ as anchor, i.e. itself prefixed with
the string __REF-__.
- string *sepline*
The value of this variable is the string to use for the separator comments
inserted into the output when the outpout is broken across lines and/or
indented. The default string consists of 60 dashes.
- string *class.main*
This variable contains the class name for the main <div>'ivision of the
generated document. The default is __doctools__.
- string *class.header*
This variable contains the class name for the header <div>'ision of the
generated document. The default is __toc-header__. This division contains
the document title, the user specified __header__, if any, and a visible
separator line.
- string *class.title*
This variable contains the class name for the <h1> tag enclosing the
document title. The default is __toc-title__.
- string *class.navsep*
This variable contains the class name for the <hr> separators in the header
and footer sections of the generated document. The default is
__toc-navsep__.
- string *class.contents*
This variable contains the class name for the XXXXX holding the keywords and
their references in the generated document. The default is __toc-contents__.
- string *class.ref*
This variable contains the class name for the table elements which are
references to other documents. The default is __toc-ref__.
- string *class.div*
This variable contains the class name for the table elements which are
divisions. The default is __toc-div__.
- string *class.footer*
This variable contains the class name for the footer <div>'ision of the
generated document. The default is __toc-footer__. This division contains a
browser-visible separator line and the user specified __footer__, if any.
*Note* that this plugin ignores the standard configuration variable __format__,
and its value.
# <a name='section4'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [doctools](../../../../index.md#doctools),
[export](../../../../index.md#export),
[serialization](../../../../index.md#serialization), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
[//000000001]: # (doctools::toc::export::json - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export::json(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::export::json - JSON export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [JSON notation of tables of contents](#section3)
- [Configuration](#section4)
- [ToC serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::export::json ?0.1?
package require textutil::adjust
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents export plugin for the
generation of JSON markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::export](toc_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::export](toc_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a table of contents, as
specified in section [ToC serialization format](#section5), and contained in
*serial*, the *configuration*, a dictionary, and generates JSON markup
encoding the table. The created string is then returned as the result of the
command.
# <a name='section3'></a>JSON notation of tables of contents
The JSON format used for tables of contents is a direct translation of the [ToC
serialization format](#section5), mapping Tcl dictionaries as JSON objects and
Tcl lists as JSON arrays. For example, the Tcl serialization
doctools::toc {
items {
{reference {
desc {DocTools - Tables of Contents}
id introduction.man
label doctools::toc::introduction
}}
{division {
id processing.man
items {
{reference {
desc {doctoc serialization utilities}
id structure.man
label doctools::toc::structure
}}
{reference {
desc {Parsing text in doctoc format}
id parse.man
label doctools::toc::parse
}}
}
label Processing
}}
}
label {Table of Contents}
title TOC
}
is equivalent to the JSON string
{
"doctools::toc" : {
"items" : [{
"reference" : {
"desc" : "DocTools - Tables of Contents",
"id" : "introduction.man",
"label" : "doctools::toc::introduction"
}
},{
"division" : {
"id" : "processing.man",
"items" : [{
"reference" : {
"desc" : "doctoc serialization utilities",
"id" : "structure.man",
"label" : "doctools::toc::structure"
}
},{
"reference" : {
"desc" : "Parsing text in doctoc format",
"id" : "parse.man",
"label" : "doctools::toc::parse"
}
}],
"label" : "Processing"
}
}],
"label" : "Table of Contents",
"title" : "TOC"
}
}
# <a name='section4'></a>Configuration
The JSON export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- boolean *indented*
If this flag is set the plugin will break the generated JSON code across
lines and indent it according to its inner structure, with each key of a
dictionary on a separate line.
If this flag is not set (the default), the whole JSON object will be written
on a single line, with minimum spacing between all elements.
- boolean *aligned*
If this flag is set the generator ensures that the values for the keys in a
dictionary are vertically aligned with each other, for a nice table effect.
To make this work this also implies that __indented__ is set.
If this flag is not set (the default), the output is formatted as per the
value of __indented__, without trying to align the values for dictionary
keys.
*Note* that this plugin ignores the standard configuration variables __user__,
__format__, __file__, and __map__ and their values.
# <a name='section5'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[JSON](../../../../index.md#json), [doctools](../../../../index.md#doctools),
[export](../../../../index.md#export),
[serialization](../../../../index.md#serialization), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_export_nroff.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
[//000000001]: # (doctools::toc::export::nroff - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export::nroff(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::toc::export::nroff - nroff export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [ToC serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::export::nroff ?0.2?
package require doctools::text
package require doctools::nroff::man_macros
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents export plugin for the
generation of nroff markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::export](toc_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::export](toc_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a table of contents, as
specified in section [ToC serialization format](#section4), and contained in
*serial*, the *configuration*, a dictionary, and generates nroff markup
encoding the table. The created string is then returned as the result of the
command.
# <a name='section3'></a>Configuration
The nroff export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *user*
This standard configuration variable contains the name of the user running
the process which invoked the export plugin. The plugin puts this
information into the provenance comment at the beginning of the generated
document.
- string *file*
This standard configuration variable contains the name of the file the table
of contents came from. This variable may not be set or contain the empty
string. The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the generated
document.
- boolean *inline*
If this flag is set (default) the plugin will place the definitions of the
man macro set directly into the output.
If this flag is not set, the plugin will place a reference to the
definitions of the man macro set into the output, but not the macro
definitions themselves.
*Note* that this plugin ignores the standard configuration variables __format__,
and __map__, and their values.
# <a name='section4'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [nroff](../../../../index.md#nroff),
[serialization](../../../../index.md#serialization), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_export_text.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
[//000000001]: # (doctools::toc::export::text - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export::text(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::export::text - plain text export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [ToC serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::export::text ?0.1?
package require doctools::text
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents export plugin for the
generation of plain text markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::export](toc_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::export](toc_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a table of contents, as
specified in section [ToC serialization format](#section4), and contained in
*serial*, the *configuration*, a dictionary, and generates plain text markup
encoding the table. The created string is then returned as the result of the
command.
# <a name='section3'></a>Configuration
The text export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- dictionary *map*
This standard configuration variable contains a dictionary mapping from the
(symbolic) document ids in reference entries to the actual filenames and/or
urls to be used in the output.
Document ids without a mapping are used unchanged.
*Note* that this plugin ignores the standard configuration variables __user__,
__file__, and __format__, and their values.
# <a name='section4'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export), [plain
text](../../../../index.md#plain_text),
[serialization](../../../../index.md#serialization), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_export_wiki.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
[//000000001]: # (doctools::toc::export::wiki - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::export::wiki(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::export::wiki - wiki export plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Wiki markup](#section3)
- [Configuration](#section4)
- [ToC serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::export::wiki ?0.1?
package require doctools::text
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents export plugin for the
generation of wiki markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::export](toc_export.md)__, the export manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::export](toc_export.md)__ and the export manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
export plugin API version 2.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a table of contents, as
specified in section [ToC serialization format](#section5), and contained in
*serial*, the *configuration*, a dictionary, and generates wiki markup
encoding the table. The created string is then returned as the result of the
command.
# <a name='section3'></a>Wiki markup
The basic syntax of the wiki markup generated by this plugin are described at
[http://wiki.tcl.tk/14](http://wiki.tcl.tk/14).
The plugin goes beyond the classic markup to generate proper headers and
indenting.
# <a name='section4'></a>Configuration
The wiki export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- dictionary *map*
This standard configuration variable contains a dictionary mapping from the
(symbolic) document ids in reference entries to the actual filenames and/or
urls to be used in the output.
Document ids without a mapping are used unchanged.
*Note* that this plugin ignores the standard configuration variables __user__,
__file__ and __format__, and their values.
# <a name='section5'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctools](../../../../index.md#doctools),
[export](../../../../index.md#export),
[serialization](../../../../index.md#serialization), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc), [wiki](../../../../index.md#wiki)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_import.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
|
[//000000001]: # (doctools::toc::import - Documentation tools)
[//000000002]: # (Generated from file 'toc_import.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::import(n) 0.2 tcllib "Documentation tools")
# NAME
doctools::toc::import - Importing keyword indices
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [API](#section3)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Import plugin API v2 reference](#section4)
- [ToC serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::toc::import ?0.2?
package require Tcl 8.4
package require doctools::config
package require doctools::toc::structure
package require snit
package require pluginmgr
[__::doctools::toc::import__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __import text__ *text* ?*format*?](#4)
[*objectName* __import file__ *path* ?*format*?](#5)
[*objectName* __import object text__ *object* *text* ?*format*?](#6)
[*objectName* __import object file__ *object* *path* ?*format*?](#7)
[*objectName* __config names__](#8)
[*objectName* __config get__](#9)
[*objectName* __config set__ *name* ?*value*?](#10)
[*objectName* __config unset__ *pattern*...](#11)
[*objectName* __includes__](#12)
[*objectName* __include add__ *path*](#13)
[*objectName* __include remove__ *path*](#14)
[*objectName* __include clear__](#15)
[__IncludeFile__ *currentfile* *path*](#16)
[__[import](../../../../index.md#import)__ *text* *configuration*](#17)
# <a name='description'></a>DESCRIPTION
This package provides a class to manage the plugins for the import of tables of
contents from other formats, i.e. their conversion from, for example
*[doctoc](../../../../index.md#doctoc)*, *[json](../../../../index.md#json)*,
etc.
This is one of the three public pillars the management of tables of contents
resides on. The other two pillars are
1. *[Exporting tables of contents](toc_export.md)*, and
1. *[Holding tables of contents](toc_container.md)*
For information about the [Concepts](#section2) of tables of contents, and their
parts, see the same-named section. For information about the data structure
which is the major output of the manager objects provided by this package see
the section [ToC serialization format](#section5).
The plugin system of our class is based on the package
__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins
using
1. the environment variable __DOCTOOLS_TOC_IMPORT_PLUGINS__,
1. the environment variable __DOCTOOLS_TOC_PLUGINS__,
1. the environment variable __DOCTOOLS_PLUGINS__,
1. the path "~/.doctools/toc/import/plugin"
1. the path "~/.doctools/toc/plugin"
1. the path "~/.doctools/plugin"
1. the path "~/.doctools/toc/import/plugins"
1. the path "~/.doctools/toc/plugins"
1. the path "~/.doctools/plugins"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\IMPORT\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
The last three are used only when the package is run on a machine using
Windows(tm) operating system.
The whole system is delivered with two predefined import plugins, namely
- doctoc
See *[doctoc import plugin](import_doctoc.md)* for details.
- json
See *json import plugin* for details.
Readers wishing to write their own import plugin for some format, i.e. *plugin
writer*s reading and understanding the section containing the [Import plugin API
v2 reference](#section4) is an absolute necessity, as it specifies the
interaction between this package and its plugins in detail.
# <a name='section2'></a>Concepts
1. A *[table of contents](../../../../index.md#table_of_contents)* consists of
a (possibly empty) list of *elements*.
1. Each element in the list is identified by its label.
1. Each element is either a *[reference](../../../../index.md#reference)*, or
a *division*.
1. Each reference has an associated document, identified by a symbolic id, and
a textual description.
1. Each division may have an associated document, identified by a symbolic id.
1. Each division consists consists of a (possibly empty) list of *elements*,
with each element following the rules as specified in item 2 and above.
A few notes
1. The above rules span up a tree of elements, with references as the leaf
nodes, and divisions as the inner nodes, and each element representing an
entry in the whole table of contents.
1. The identifying labels of any element E are unique within their division
(or toc), and the full label of any element E is the list of labels for all
nodes on the unique path from the root of the tree to E, including E.
# <a name='section3'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::doctools::toc::import__ *objectName*
This command creates a new import manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::doctools::toc::import__ command have the
following general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __import text__ *text* ?*format*?
This method takes the *text* and converts it from the specified *format* to
the canonical serialization of a table of contents using the import plugin
for the format. An error is thrown if no plugin could be found for the
format. The serialization generated by the conversion process is returned as
the result of this method.
If no format is specified the method defaults to __doctoc__.
The specification of what a *canonical* serialization is can be found in the
section [ToC serialization format](#section5).
The plugin has to conform to the interface specified in section [Import
plugin API v2 reference](#section4).
- <a name='5'></a>*objectName* __import file__ *path* ?*format*?
This method is a convenient wrapper around the __import text__ method
described by the previous item. It reads the contents of the specified file
into memory, feeds the result into __import text__ and returns the resulting
serialization as its own result.
- <a name='6'></a>*objectName* __import object text__ *object* *text* ?*format*?
This method is a convenient wrapper around the __import text__ method
described by the previous item. It expects that *object* is an object
command supporting a __deserialize__ method expecting the canonical
serialization of a table of contents. It imports the text using __import
text__ and then feeds the resulting serialization into the *object* via
__deserialize__. This method returns the empty string as it result.
- <a name='7'></a>*objectName* __import object file__ *object* *path* ?*format*?
This method behaves like __import object text__, except that it reads the
text to convert from the specified file instead of being given it as
argument.
- <a name='8'></a>*objectName* __config names__
This method returns a list containing the names of all configuration
variables currently known to the object.
- <a name='9'></a>*objectName* __config get__
This method returns a dictionary containing the names and values of all
configuration variables currently known to the object.
- <a name='10'></a>*objectName* __config set__ *name* ?*value*?
This method sets the configuration variable *name* to the specified *value*
and returns the new value of the variable.
If no value is specified it simply returns the current value, without
changing it.
Note that while the user can set the predefined configuration variables
__user__ and __format__ doing so will have no effect, these values will be
internally overridden when invoking an import plugin.
- <a name='11'></a>*objectName* __config unset__ *pattern*...
This method unsets all configuration variables matching the specified glob
*pattern*s. If no pattern is specified it will unset all currently defined
configuration variables.
- <a name='12'></a>*objectName* __includes__
This method returns a list containing the currently specified paths to use
to search for include files when processing input. The order of paths in the
list corresponds to the order in which they are used, from first to last,
and also corresponds to the order in which they were added to the object.
- <a name='13'></a>*objectName* __include add__ *path*
This methods adds the specified *path* to the list of paths to use to search
for include files when processing input. The path is added to the end of the
list, causing it to be searched after all previously added paths. The result
of the command is the empty string.
The method does nothing if the path is already known.
- <a name='14'></a>*objectName* __include remove__ *path*
This methods removes the specified *path* from the list of paths to use to
search for include files when processing input. The result of the command is
the empty string.
The method does nothing if the path is not known.
- <a name='15'></a>*objectName* __include clear__
This method clears the list of paths to use to search for include files when
processing input. The result of the command is the empty string.
# <a name='section4'></a>Import plugin API v2 reference
Plugins are what this package uses to manage the support for any input format
beyond the [ToC serialization format](#section5). Here we specify the API the
objects created by this package use to interact with their plugins.
A plugin for this package has to follow the rules listed below:
1. A plugin is a package.
1. The name of a plugin package has the form doctools::toc::import::__FOO__,
where __FOO__ is the name of the format the plugin will generate output
for. This name is also the argument to provide to the various __import__
methods of import manager objects to get a string encoding a table of
contents in that format.
1. The plugin can expect that the package __doctools::toc::export::plugin__ is
present, as indicator that it was invoked from a genuine plugin manager.
1. The plugin can expect that a command named __IncludeFile__ is present, with
the signature
- <a name='16'></a>__IncludeFile__ *currentfile* *path*
This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such. An example of
such a format would be *[doctoc](../../../../index.md#doctoc)*.
The plugin has to supply the following arguments
* string *currentfile*
The path of the file it is currently processing. This may be the
empty string if no such is known.
* string *path*
The path of the include file as specified in the include directive
being processed.
The result of the command will be a 5-element list containing
A boolean flag indicating the success (__True__) or failure (__False__)
of the operation.
In case of success the contents of the included file, and the empty
string otherwise.
The resolved, i.e. absolute path of the included file, if possible, or
the unchanged *path* argument. This is for display in an error message,
or as the *currentfile* argument of another call to __IncludeFile__
should this file contain more files.
In case of success an empty string, and for failure a code indicating
the reason for it, one of
* notfound
The specified file could not be found.
* notread
The specified file was found, but not be read into memory.
An empty string in case of success of a __notfound__ failure, and an
additional error message describing the reason for a __notread__ error
in more detail.
1. A plugin has to provide one command, with the signature shown below.
- <a name='17'></a>__[import](../../../../index.md#import)__ *text* *configuration*
Whenever an import manager of
__[doctools::toc](../doctools/doctoc.md)__ has to parse input for a
table of contents it will invoke this command.
* string *text*
This argument will contain the text encoding the table of contents
per the format the plugin is for.
* dictionary *configuration*
This argument will contain the current configuration to apply to
the parsing, as a dictionary mapping from variable names to values.
The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables
recognized by a plugin will be described in the manpage for that
plugin.
+ user
This variable is expected to contain the name of the user
owning the process invoking the plugin.
+ format
This variable is expected to contain the name of the format
whose plugin is invoked.
1. A single usage cycle of a plugin consists of the invokations of the command
__[import](../../../../index.md#import)__. This call has to leave the
plugin in a state where another usage cycle can be run without problems.
# <a name='section5'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[conversion](../../../../index.md#conversion),
[doctoc](../../../../index.md#doctoc),
[documentation](../../../../index.md#documentation),
[import](../../../../index.md#import), [json](../../../../index.md#json),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[parsing](../../../../index.md#parsing), [plugin](../../../../index.md#plugin),
[reference](../../../../index.md#reference),
[table](../../../../index.md#table), [table of
contents](../../../../index.md#table_of_contents),
[url](../../../../index.md#url)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2018 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_import_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
[//000000001]: # (doctools::toc::import::json - Documentation tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::import::json(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::import::json - JSON import plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [JSON notation of tables of contents](#section3)
- [ToC serialization format](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require doctools::toc::import::json ?0.1?
package require doctools::toc::structure
package require json
[__[import](../../../../index.md#import)__ *string* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
This package implements the doctools table of contents import plugin for the
parsing of JSON markup.
This is an internal package of doctools, for use by the higher level management
packages handling tables of contents, especially
__[doctools::toc::import](toc_import.md)__, the import manager.
Using it from a regular interpreter is possible, however only with contortions,
and is not recommended. The proper way to use this functionality is through the
package __[doctools::toc::import](toc_import.md)__ and the import manager
objects it provides.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the doctoc
import plugin API version 2.
- <a name='1'></a>__[import](../../../../index.md#import)__ *string* *configuration*
This command takes the *string* and parses it as JSON markup encoding a
table of contents, in the context of the specified *configuration* (a
dictionary). The result of the command is the canonical serialization of
that table of contents, in the form specified in section [ToC serialization
format](#section4).
# <a name='section3'></a>JSON notation of tables of contents
The JSON format used for tables of contents is a direct translation of the [ToC
serialization format](#section4), mapping Tcl dictionaries as JSON objects and
Tcl lists as JSON arrays. For example, the Tcl serialization
doctools::toc {
items {
{reference {
desc {DocTools - Tables of Contents}
id introduction.man
label doctools::toc::introduction
}}
{division {
id processing.man
items {
{reference {
desc {doctoc serialization utilities}
id structure.man
label doctools::toc::structure
}}
{reference {
desc {Parsing text in doctoc format}
id parse.man
label doctools::toc::parse
}}
}
label Processing
}}
}
label {Table of Contents}
title TOC
}
is equivalent to the JSON string
{
"doctools::toc" : {
"items" : [{
"reference" : {
"desc" : "DocTools - Tables of Contents",
"id" : "introduction.man",
"label" : "doctools::toc::introduction"
}
},{
"division" : {
"id" : "processing.man",
"items" : [{
"reference" : {
"desc" : "doctoc serialization utilities",
"id" : "structure.man",
"label" : "doctools::toc::structure"
}
},{
"reference" : {
"desc" : "Parsing text in doctoc format",
"id" : "parse.man",
"label" : "doctools::toc::parse"
}
}],
"label" : "Processing"
}
}],
"label" : "Table of Contents",
"title" : "TOC"
}
}
# <a name='section4'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[JSON](../../../../index.md#json),
[deserialization](../../../../index.md#deserialization),
[doctools](../../../../index.md#doctools),
[import](../../../../index.md#import), [table of
contents](../../../../index.md#table_of_contents),
[toc](../../../../index.md#toc)
# <a name='category'></a>CATEGORY
Text formatter plugin
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
[//000000001]: # (doctools2toc_introduction - Documentation tools)
[//000000002]: # (Generated from file 'toc_introduction.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools2toc_introduction(n) 2.0 tcllib "Documentation tools")
# NAME
doctools2toc_introduction - DocTools - Tables of Contents
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Related formats](#section2)
- [Package Overview](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[doctoc](../../../../index.md#doctoc)* (short for *documentation tables of
contents*) stands for a set of related, yet different, entities which are
working together for the easy creation and transformation of tables and contents
for documentation.
These are
1. A tcl based language for the semantic markup of a table of contents. Markup
is represented by Tcl commands. Beginners should start with the *[doctoc
language introduction](../doctools/doctoc_lang_intro.md)*. The formal
specification is split over two documents, one dealing with the *[doctoc
language syntax](../doctools/doctoc_lang_syntax.md)*, the other a *[doctoc
language command reference](../doctools/doctoc_lang_cmdref.md)*.
1. A set of packages for the programmatic manipulation of tables of contents
in memory, and their conversion between various formats, reading and
writing. The aforementioned markup language is one of the formats which can
be both read from and written to.
1. The system for the conversion of tables of contents is based on a plugin
mechanism, for this we have two APIs describing the interface between the
packages above and the import/export plugins.
Which of the more detailed documents are relevant to the reader of this
introduction depends on their role in the documentation process.
1. A *writer* of documentation has to understand the markup language itself. A
beginner to doctoc should read the more informally written *[doctoc
language introduction](../doctools/doctoc_lang_intro.md)* first. Having
digested this the formal *[doctoc language
syntax](../doctools/doctoc_lang_syntax.md)* specification should become
understandable. A writer experienced with doctoc may only need the *[doctoc
language command reference](../doctools/doctoc_lang_cmdref.md)* from time
to time to refresh her memory.
While a document is written the __dtp__ application can be used to validate
it, and after completion it also performs the conversion into the chosen
system of visual markup, be it *roff, HTML, plain text, wiki, etc. The
simpler __[dtplite](../../apps/dtplite.md)__ application makes internal use
of doctoc when handling directories of documentation, automatically
generating a proper table of contents for them.
1. A *processor* of documentation written in the
*[doctoc](../../../../index.md#doctoc)* markup language has to know which
tools are available for use.
The main tool is the aforementioned __dtp__ application provided by Tcllib.
The simpler __[dtplite](../../apps/dtplite.md)__ does not expose doctoc to
the user. At the bottom level, common to both applications, however we find
the three packages providing the basic facilities to handle tables of
contents, i.e. import from textual formats, programmatic manipulation in
memory, and export to textual formats. These are
- __doctoools::toc__
Programmatic manipulation of tables of contents in memory.
- __doctoools::toc::import__
Import of tables of contents from various textual formats. The set of
supported formats is extensible through plugin packages.
- __doctoools::toc::export__
Export of tables of contents to various textual formats. The set of
supported formats is extensible through plugin packages.
See also section [Package Overview](#section3) for an overview of the
dependencies between these and other, supporting packages.
1. At last, but not least, *plugin writers* have to understand the interaction
between the import and export packages and their plugins. These APIs are
described in the documentation for the two relevant packages, i.e.
- __doctoools::toc::import__
- __doctoools::toc::export__
# <a name='section2'></a>Related formats
The doctoc format does not stand alone, it has two companion formats. These are
called *[docidx](../../../../index.md#docidx)* and
*[doctools](../../../../index.md#doctools)*, and they are intended for the
markup of *keyword indices*, and of general documentation, respectively. They
are described in their own sets of documents, starting at the *DocTools -
Keyword Indices* and the *DocTools - General*, respectively.
# <a name='section3'></a>Package Overview
~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
~~ | ~~
doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
| | |
+---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+
| | | | | | | | |
doctools::config = | | | = doctools::include doctools::config doctools::paths
| | | | |
doctools::toc::export::<*> | | | doctools::toc::import::<*>
doctoc | | | doctoc, json
json | | | | \\
html | | | doctools::toc::parse \\
nroff | | | | \\
wiki | | | +---------------+ json
text | | | | |
doctools::toc::structure |
|
+-------+---------------+
| |
doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat
| |
doctools::text doctools::nroff::man_macros =
|
doctools::msgcat::toc::<*>
c, en, de, fr
(fr == en for now)
~~ Interoperable objects, without actual package dependencies
-- Package dependency, higher requires lower package
= Dynamic dependency through plugin system
<*> Multiple packages following the given form of naming.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[doctoc_intro](../doctools/doctoc_intro.md),
[doctools](../doctools/doctools.md), doctools2doc_introduction,
[doctools2idx_introduction](../doctools2idx/idx_introduction.md),
[doctools_lang_cmdref](../doctools/doctools_lang_cmdref.md),
[doctools_lang_faq](../doctools/doctools_lang_faq.md),
[doctools_lang_intro](../doctools/doctools_lang_intro.md),
[doctools_lang_syntax](../doctools/doctools_lang_syntax.md),
[doctools_plugin_apiref](../doctools/doctools_plugin_apiref.md)
# <a name='keywords'></a>KEYWORDS
[contents](../../../../index.md#contents),
[conversion](../../../../index.md#conversion),
[formatting](../../../../index.md#formatting),
[markup](../../../../index.md#markup), [parsing](../../../../index.md#parsing),
[plugin](../../../../index.md#plugin), [semantic
markup](../../../../index.md#semantic_markup), [table of
contents](../../../../index.md#table_of_contents)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_c.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::toc::c - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::toc::c(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::toc::c - Message catalog for the doctoc parser (C)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::c ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::toc::c__ is a support module providing the C
language message catalog for the doctoc parser in the doctools system version 2.
As such it is an internal package a regular user (developer) should not be in
direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](../doctools2idx/idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[C](../../../../index.md#c), [catalog
package](../../../../index.md#catalog_package),
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_de.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::toc::de - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::toc::de(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::toc::de - Message catalog for the doctoc parser (DE)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::de ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::toc::de__ is a support module providing the DE
(german) language message catalog for the doctoc parser in the doctools system
version 2. As such it is an internal package a regular user (developer) should
not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](../doctools2idx/idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[DE](../../../../index.md#de), [catalog
package](../../../../index.md#catalog_package),
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_en.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::toc::en - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::toc::en(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::toc::en - Message catalog for the doctoc parser (EN)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::en ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::toc::en__ is a support module providing the EN
(english) language message catalog for the doctoc parser in the doctools system
version 2. As such it is an internal package a regular user (developer) should
not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](../doctools2idx/idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[EN](../../../../index.md#en), [catalog
package](../../../../index.md#catalog_package),
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_fr.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (doctools::msgcat::toc::fr - Documentation tools)
[//000000002]: # (Generated from file 'msgcat.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::msgcat::toc::fr(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::msgcat::toc::fr - Message catalog for the doctoc parser (FR)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require msgcat
package require doctools::msgcat::toc::fr ?0.1?
# <a name='description'></a>DESCRIPTION
The package __doctools::msgcat::toc::fr__ is a support module providing the FR
(french) language message catalog for the doctoc parser in the doctools system
version 2. As such it is an internal package a regular user (developer) should
not be in direct contact with.
If you are such please go the documentation of either
1. __doctools::doc__,
1. __[doctools::toc](../doctools/doctoc.md)__, or
1. __[doctools::idx](../doctools2idx/idx_container.md)__
Within the system architecture this package resides under the package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__ providing the general
message catalog management within the system. *Note* that there is *no* explicit
dependency between the manager and catalog packages. The catalog is a plugin
which is selected and loaded dynamically.
# <a name='section2'></a>API
This package has no exported API.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[FR](../../../../index.md#fr), [catalog
package](../../../../index.md#catalog_package),
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools), [i18n](../../../../index.md#i18n),
[internationalization](../../../../index.md#internationalization),
[l10n](../../../../index.md#l10n),
[localization](../../../../index.md#localization), [message
catalog](../../../../index.md#message_catalog), [message
package](../../../../index.md#message_package)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_parse.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
|
[//000000001]: # (doctools::toc::parse - Documentation tools)
[//000000002]: # (Generated from file 'toc_parse.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::parse(n) 1 tcllib "Documentation tools")
# NAME
doctools::toc::parse - Parsing text in doctoc format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Parse errors](#section3)
- [[doctoc] notation of tables of contents](#section4)
- [ToC serialization format](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::toc::parse ?0.1?
package require Tcl 8.4
package require doctools::toc::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::stack
[__::doctools::toc::parse__ __text__ *text*](#1)
[__::doctools::toc::parse__ __file__ *path*](#2)
[__::doctools::toc::parse__ __includes__](#3)
[__::doctools::toc::parse__ __include add__ *path*](#4)
[__::doctools::toc::parse__ __include remove__ *path*](#5)
[__::doctools::toc::parse__ __include clear__](#6)
[__::doctools::toc::parse__ __vars__](#7)
[__::doctools::toc::parse__ __var set__ *name* *value*](#8)
[__::doctools::toc::parse__ __var unset__ *name*](#9)
[__::doctools::toc::parse__ __var clear__ ?*pattern*?](#10)
# <a name='description'></a>DESCRIPTION
This package provides commands to parse text written in the
*[doctoc](../../../../index.md#doctoc)* markup language and convert it into the
canonical serialization of the table of contents encoded in the text. See the
section [ToC serialization format](#section5) for specification of their format.
This is an internal package of doctools, for use by the higher level packages
handling *[doctoc](../../../../index.md#doctoc)* documents.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::toc::parse__ __text__ *text*
The command takes the string contained in *text* and parses it under the
assumption that it contains a document written using the
*[doctoc](../../../../index.md#doctoc)* markup language. An error is thrown
if this assumption is found to be false. The format of these errors is
described in section [Parse errors](#section3).
When successful the command returns the canonical serialization of the table
of contents which was encoded in the text. See the section [ToC
serialization format](#section5) for specification of that format.
- <a name='2'></a>__::doctools::toc::parse__ __file__ *path*
The same as __text__, except that the text to parse is read from the file
specified by *path*.
- <a name='3'></a>__::doctools::toc::parse__ __includes__
This method returns the current list of search paths used when looking for
include files.
- <a name='4'></a>__::doctools::toc::parse__ __include add__ *path*
This method adds the *path* to the list of paths searched when looking for
an include file. The call is ignored if the path is already in the list of
paths. The method returns the empty string as its result.
- <a name='5'></a>__::doctools::toc::parse__ __include remove__ *path*
This method removes the *path* from the list of paths searched when looking
for an include file. The call is ignored if the path is not contained in the
list of paths. The method returns the empty string as its result.
- <a name='6'></a>__::doctools::toc::parse__ __include clear__
This method clears the list of search paths for include files.
- <a name='7'></a>__::doctools::toc::parse__ __vars__
This method returns a dictionary containing the current set of predefined
variables known to the __vset__ markup command during processing.
- <a name='8'></a>__::doctools::toc::parse__ __var set__ *name* *value*
This method adds the variable *name* to the set of predefined variables
known to the __vset__ markup command during processing, and gives it the
specified *value*. The method returns the empty string as its result.
- <a name='9'></a>__::doctools::toc::parse__ __var unset__ *name*
This method removes the variable *name* from the set of predefined variables
known to the __vset__ markup command during processing. The method returns
the empty string as its result.
- <a name='10'></a>__::doctools::toc::parse__ __var clear__ ?*pattern*?
This method removes all variables matching the *pattern* from the set of
predefined variables known to the __vset__ markup command during processing.
The method returns the empty string as its result.
The pattern matching is done with __string match__, and the default pattern
used when none is specified, is __*__.
# <a name='section3'></a>Parse errors
The format of the parse error messages thrown when encountering violations of
the *[doctoc](../../../../index.md#doctoc)* markup syntax is human readable and
not intended for processing by machines. As such it is not documented.
*However*, the errorCode attached to the message is machine-readable and has the
following format:
1. The error code will be a list, each element describing a single error found
in the input. The list has at least one element, possibly more.
1. Each error element will be a list containing six strings describing an
error in detail. The strings will be
1) The path of the file the error occurred in. This may be empty.
1) The range of the token the error was found at. This range is a
two-element list containing the offset of the first and last character
in the range, counted from the beginning of the input (file). Offsets
are counted from zero.
1) The line the first character after the error is on. Lines are counted
from one.
1) The column the first character after the error is at. Columns are
counted from zero.
1) The message code of the error. This value can be used as argument to
__msgcat::mc__ to obtain a localized error message, assuming that the
application had a suitable call of __doctools::msgcat::init__ to
initialize the necessary message catalogs (See package
__[doctools::msgcat](../doctools2base/tcllib_msgcat.md)__).
1) A list of details for the error, like the markup command involved. In
the case of message code __doctoc/include/syntax__ this value is the
set of errors found in the included file, using the format described
here.
# <a name='section4'></a>[doctoc] notation of tables of contents
The doctoc format for tables of contents, also called the *doctoc markup
language*, is too large to be covered in single section. The interested reader
should start with the document
1. *[doctoc language introduction](../doctools/doctoc_lang_intro.md)*
and then proceed from there to the formal specifications, i.e. the documents
1. *[doctoc language syntax](../doctools/doctoc_lang_syntax.md)* and
1. *[doctoc language command reference](../doctools/doctoc_lang_cmdref.md)*.
to get a thorough understanding of the language.
# <a name='section5'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools), [lexer](../../../../index.md#lexer),
[parser](../../../../index.md#parser)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/doctools2toc/toc_structure.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
[//000000001]: # (doctools::toc::structure - Documentation tools)
[//000000002]: # (Generated from file 'toc_structure.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (doctools::toc::structure(n) 0.1 tcllib "Documentation tools")
# NAME
doctools::toc::structure - Doctoc serialization utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [ToC serialization format](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require doctools::toc::structure ?0.1?
package require Tcl 8.4
package require logger
package require snit
[__::doctools::toc::structure__ __verify__ *serial* ?*canonvar*?](#1)
[__::doctools::toc::structure__ __verify-as-canonical__ *serial*](#2)
[__::doctools::toc::structure__ __canonicalize__ *serial*](#3)
[__::doctools::toc::structure__ __print__ *serial*](#4)
[__::doctools::toc::structure__ __merge__ *seriala* *serialb*](#5)
# <a name='description'></a>DESCRIPTION
This package provides commands to work with the serializations of tables of
contents as managed by the doctools system v2, and specified in section [ToC
serialization format](#section3).
This is an internal package of doctools, for use by the higher level packages
handling tables of contents and their conversion into and out of various other
formats, like documents written using *[doctoc](../../../../index.md#doctoc)*
markup.
# <a name='section2'></a>API
- <a name='1'></a>__::doctools::toc::structure__ __verify__ *serial* ?*canonvar*?
This command verifies that the content of *serial* is a valid *regular*
serialization of a table of contents and will throw an error if that is not
the case. The result of the command is the empty string.
If the argument *canonvar* is specified it is interpreted as the name of a
variable in the calling context. This variable will be written to if and
only if *serial* is a valid regular serialization. Its value will be a
boolean, with __True__ indicating that the serialization is not only valid,
but also *canonical*. __False__ will be written for a valid, but
non-canonical serialization.
For the specification of regular and canonical serializations see the
section [ToC serialization format](#section3).
- <a name='2'></a>__::doctools::toc::structure__ __verify-as-canonical__ *serial*
This command verifies that the content of *serial* is a valid *canonical*
serialization of a table of contents and will throw an error if that is not
the case. The result of the command is the empty string.
For the specification of canonical serializations see the section [ToC
serialization format](#section3).
- <a name='3'></a>__::doctools::toc::structure__ __canonicalize__ *serial*
This command assumes that the content of *serial* is a valid *regular*
serialization of a table of contents and will throw an error if that is not
the case.
It will then convert the input into the *canonical* serialization of the
contained table of contents and return it as its result. If the input is
already canonical it will be returned unchanged.
For the specification of regular and canonical serializations see the
section [ToC serialization format](#section3).
- <a name='4'></a>__::doctools::toc::structure__ __print__ *serial*
This command assumes that the argument *serial* contains a valid regular
serialization of a table of contents and returns a string containing that
table in a human readable form.
The exact format of this form is not specified and cannot be relied on for
parsing or other machine-based activities.
For the specification of regular serializations see the section [ToC
serialization format](#section3).
- <a name='5'></a>__::doctools::toc::structure__ __merge__ *seriala* *serialb*
This command accepts the regular serializations of two tables of contents
and uses them to create their union. The result of the command is the
canonical serialization of this unified table of contents.
Title and label of the resulting table are taken from the table contained in
*serialb*.
The whole table and its divisions are merged recursively in the same manner:
All reference elements which occur in both divisions (identified by their
label) are unified with document id's and descriptions taken from the second
table.
All division elements which occur in both divisions (identified by their
label) are unified with the optional document id taken from the second
table, if any, or from the first if none is in the second. The elements in
the division are merged recursively using the same algorithm as described in
this list.
Type conflicts between elements, i.e. finding two elements with the same
label but different types result in a merge error.
All elements found in the second division but not in the first are added to
the end of the list of elements in the merge result.
For the specification of regular and canonical serializations see the
section [ToC serialization format](#section3).
# <a name='section3'></a>ToC serialization format
Here we specify the format used by the doctools v2 packages to serialize tables
of contents as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a table
of contents may have more than one regular serialization only exactly one of
them will be *canonical*.
- regular serialization
The serialization of any table of contents is a nested Tcl dictionary.
This dictionary holds a single key, __doctools::toc__, and its value. This
value holds the contents of the table of contents.
The contents of the table of contents are a Tcl dictionary holding the title
of the table of contents, a label, and its elements. The relevant keys and
their values are
* __title__
The value is a string containing the title of the table of
contents.
* __label__
The value is a string containing a label for the table of contents.
* __items__
The value is a Tcl list holding the elements of the table, in the
order they are to be shown.
Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be
that it is a Tcl dictionary holding a single key, the item type,
mapped to the item description.
The two legal item types and their descriptions are
+ __reference__
This item describes a single entry in the table of contents,
referencing a single document. To this end its value is a Tcl
dictionary containing an id for the referenced document, a
label, and a longer textual description which can be associated
with the entry. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the entry.
- __label__
The value is a string containing a label for this entry.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __desc__
The value is a string containing a longer description for
this entry.
+ __division__
This item describes a group of entries in the table of
contents, inducing a hierarchy of entries. To this end its
value is a Tcl dictionary containing a label for the group, an
optional id to a document for the whole group, and the list of
entries in the group. The relevant keys and their values are
- __id__
The value is a string containing the id of the document
associated with the whole group. This key is optional.
- __label__
The value is a string containing a label for the group.
This string also identifies the entry, and no two entries
(references and divisions) in the containing list are
allowed to have the same label.
- __items__
The value is a Tcl list holding the elements of the group,
in the order they are to be shown. This list has the same
structure as the value for the keyword __items__ used to
describe the whole table of contents, see above. This
closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole
table of contents, including other divisions.
- canonical serialization
The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='keywords'></a>KEYWORDS
[deserialization](../../../../index.md#deserialization),
[doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools),
[serialization](../../../../index.md#serialization)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/dtplite/pkg_dtplite.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
|
[//000000001]: # (dtplite - Documentation toolbox)
[//000000002]: # (Generated from file 'pkg_dtplite.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (dtplite(n) 1.3.1 tcllib "Documentation toolbox")
# NAME
dtplite - Lightweight DocTools Markup Processor
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USE CASES](#subsection1)
- [COMMAND LINE](#subsection2)
- [OPTIONS](#subsection3)
- [FORMATS](#subsection4)
- [DIRECTORY STRUCTURES](#subsection5)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require dtplite ?1.3.1?
[__[dtplite](../../apps/dtplite.md)__ __-o__ *output* ?options? *format* *inputfile*](#1)
[__[dtplite](../../apps/dtplite.md)__ __validate__ *inputfile*](#2)
[__[dtplite](../../apps/dtplite.md)__ __-o__ *output* ?options? *format* *inputdirectory*](#3)
[__[dtplite](../../apps/dtplite.md)__ __-merge__ __-o__ *output* ?options? *format* *inputdirectory*](#4)
# <a name='description'></a>DESCRIPTION
The application described by this document,
__[dtplite](../../apps/dtplite.md)__, is the successor to the extremely simple
__[mpexpand](../doctools/mpexpand.md)__. Influenced in its functionality by the
__dtp__ doctools processor it is much more powerful than
__[mpexpand](../doctools/mpexpand.md)__, yet still as easy to use; definitely
easier than __dtp__ with its myriad of subcommands and options.
__[dtplite](../../apps/dtplite.md)__ is based upon the package
__[doctools](../doctools/doctools.md)__, like the other two processors.
## <a name='subsection1'></a>USE CASES
__[dtplite](../../apps/dtplite.md)__ was written with the following three use
cases in mind.
1. Validation of a single document, i.e. checking that it was written in valid
doctools format. This mode can also be used to get a preliminary version of
the formatted output for a single document, for display in a browser,
nroff, etc., allowing proofreading of the formatting.
1. Generation of the formatted documentation for a single package, i.e. all
the manpages, plus a table of contents and an index of keywords.
1. An extension of the previous mode of operation, a method for the easy
generation of one documentation tree for several packages, and especially
of a unified table of contents and keyword index.
Beyond the above we also want to make use of the customization features provided
by the HTML formatter. It is not the only format the application should be able
to generate, but we anticipiate it to be the most commonly used, and it is one
of the few which do provide customization hooks.
We allow the caller to specify a header string, footer string, a stylesheet, and
data for a bar of navigation links at the top of the generated document. While
all can be set as long as the formatting engine provides an appropriate engine
parameter (See section [OPTIONS](#subsection3)) the last two have internal
processing which make them specific to HTML.
## <a name='subsection2'></a>COMMAND LINE
- <a name='1'></a>__[dtplite](../../apps/dtplite.md)__ __-o__ *output* ?options? *format* *inputfile*
This is the form for use case [1]. The *options* will be explained later, in
section [OPTIONS](#subsection3).
* path *output* (in)
This argument specifies where to write the generated document. It can be
the path to a file or directory, or __-__. The last value causes the
application to write the generated documented to __stdout__.
If the *output* does not exist then [file dirname $output] has to exist
and must be a writable directory. The generated document will be written
to a file in that directory, and the name of that file will be derived
from the *inputfile*, the *format*, and the value given to option
__-ext__ (if present).
* (path|handle) *format* (in)
This argument specifies the formatting engine to use when processing the
input, and thus the format of the generated document. See section
[FORMATS](#subsection4) for the possibilities recognized by the
application.
* path *inputfile* (in)
This argument specifies the path to the file to process. It has to
exist, must be readable, and written in
*[doctools](../../../../index.md#doctools)* format.
- <a name='2'></a>__[dtplite](../../apps/dtplite.md)__ __validate__ *inputfile*
This is a simpler form for use case [1]. The "validate" format generates no
output at all, only syntax checks are performed. As such the specification
of an output file or other options is not necessary and left out.
- <a name='3'></a>__[dtplite](../../apps/dtplite.md)__ __-o__ *output* ?options? *format* *inputdirectory*
This is the form for use case [2]. It differs from the form for use case [1]
by having the input documents specified through a directory instead of a
file. The other arguments are identical, except for *output*, which now has
to be the path to an existing and writable directory.
The input documents are all files in *inputdirectory* or any of its
subdirectories which were recognized by __fileutil::fileType__ as containing
text in *[doctools](../../../../index.md#doctools)* format.
- <a name='4'></a>__[dtplite](../../apps/dtplite.md)__ __-merge__ __-o__ *output* ?options? *format* *inputdirectory*
This is the form for use case [3]. The only difference to the form for use
case [2] is the additional option __-merge__.
Each such call will merge the generated documents coming from processing the
input documents under *inputdirectory* or any of its subdirectories to the
files under *output*. In this manner it is possible to incrementally build
the unified documentation for any number of packages. Note that it is
necessary to run through all the packages twice to get fully correct
cross-references (for formats supporting them).
## <a name='subsection3'></a>OPTIONS
This section describes all the options available to the user of the application,
with the exception of the options __-o__ and __-merge__. These two were
described already, in section [COMMAND LINE](#subsection2).
- __-exclude__ string
This option specifies an exclude (glob) pattern. Any files identified as
manpages to process which match the exclude pattern are ignored. The option
can be provided multiple times, each usage adding an additional pattern to
the list of exclusions.
- __-ext__ string
If the name of an output file has to be derived from the name of an input
file it will use the name of the *format* as the extension by default. This
option here will override this however, forcing it to use *string* as the
file extension. This option is ignored if the name of the output file is
fully specified through option __-o__.
When used multiple times only the last definition is relevant.
- __-header__ file
This option can be used if and only if the selected *format* provides an
engine parameter named "header". It takes the contents of the specified file
and assign them to that parameter, for whatever use by the engine. The HTML
engine will insert the text just after the tag __<body>__. If navigation
buttons are present (see option __-nav__ below), then the HTML generated for
them is appended to the header data originating here before the final
assignment to the parameter.
When used multiple times only the last definition is relevant.
- __-footer__ file
Like __-header__, except that: Any navigation buttons are ignored, the
corresponding required engine parameter is named "footer", and the data is
inserted just before the tag __</body>__.
When used multiple times only the last definition is relevant.
- __-style__ file
This option can be used if and only if the selected *format* provides an
engine parameter named "meta". When specified it will generate a piece of
HTML code declaring the *file* as the stylesheet for the generated document
and assign that to the parameter. The HTML engine will insert this inot the
document, just after the tag __<head>__.
When processing an input directory the stylesheet file is copied into the
output directory and the generated HTML will refer to the copy, to make the
result more self-contained. When processing an input file we have no
location to copy the stylesheet to and so just reference it as specified.
When used multiple times only the last definition is relevant.
- __-toc__ path|text
This option specifies a doctoc file (or text) to use for the table of
contents instead of generating our own.
When used multiple times only the last definition is relevant.
- __-pre+toc__ label path|text
- __-post+toc__ label path|text
This option specifies additional doctoc files (or texts) to use in the
navigation bar.
Positioning and handling of multiple uses is like for options __-prenav__
and __-postnav__, see below.
- __-nav__ label url
- __-prenav__ label url
Use this option to specify a navigation button with *label* to display and
the *url* to link to. This option can be used if and only if the selected
*format* provides an engine parameter named "header". The HTML generated for
this is appended to whatever data we got from option __-header__ before it
is inserted into the generated documents.
When used multiple times all definitions are collected and a navigation bar
is created, with the first definition shown at the left edge and the last
definition to the right.
The url can be relative. In that case it is assumed to be relative to the
main files (TOC and Keyword index), and will be transformed for all others
to still link properly.
- __-postnav__ label url
Use this option to specify a navigation button with *label* to display and
the *url* to link to. This option can be used if and only if the selected
*format* provides an engine parameter named "header". The HTML generated for
this is appended to whatever data we got from option __-header__ before it
is inserted into the generated documents.
When used multiple times all definitions are collected and a navigation bar
is created, with the last definition shown at the right edge and the first
definition to the left.
The url can be relative. In that case it is assumed to be relative to the
main files (TOC and Keyword index), and will be transformed for all others
to still link properly.
## <a name='subsection4'></a>FORMATS
At first the *format* argument will be treated as a path to a tcl file
containing the code for the requested formatting engine. The argument will be
treated as the name of one of the predefined formats listed below if and only if
the path does not exist.
*Note a limitation*: If treating the format as path to the tcl script
implementing the engine was sucessful, then this script has to implement not
only the engine API for doctools, i.e. *doctools_api*, but for *doctoc_api* and
*docidx_api* as well. Otherwise the generation of a table of contents and of a
keyword index will fail.
List of predefined formats, i.e. as provided by the package
__[doctools](../doctools/doctools.md)__:
- __nroff__
The processor generates *roff output, the standard format for unix manpages.
- __html__
The processor generates HTML output, for usage in and display by web
browsers. This engine is currently the only one providing the various engine
parameters required for the additional customaization of the output.
- __tmml__
The processor generates TMML output, the Tcl Manpage Markup Language, a
derivative of XML.
- __latex__
The processor generates LaTeX output.
- __wiki__
The processor generates Wiki markup as understood by __wikit__.
- __list__
The processor extracts the information provided by __manpage_begin__. This
format is used internally to extract the meta data from which both table of
contents and keyword index are derived from.
- __null__
The processor does not generate any output. This is equivalent to
__validate__.
## <a name='subsection5'></a>DIRECTORY STRUCTURES
In this section we describe the directory structures generated by the
application under *output* when processing all documents in an *inputdirectory*.
In other words, this is only relevant to the use cases [2] and [3].
- [2]
The following directory structure is created when processing a single set of
input documents. The file extension used is for output in HTML, but that is
not relevant to the structure and was just used to have proper file names.
output/
toc.html
index.html
files/
path/to/FOO.html
The last line in the example shows the document generated for a file FOO
located at
inputdirectory/path/to/FOO
- [3]
When merging many packages into a unified set of documents the generated
directory structure is a bit deeper:
output
.toc
.idx
.tocdoc
.idxdoc
.xrf
toc.html
index.html
FOO1/
...
FOO2/
toc.html
files/
path/to/BAR.html
Each of the directories FOO1, ... contains the documents generated for the
package FOO1, ... and follows the structure shown for use case [2]. The only
exception is that there is no per-package index.
The files ".toc", ".idx", and ".xrf" contain the internal status of the
whole output and will be read and updated by the next invokation. Their
contents will not be documented. Remove these files when all packages wanted
for the output have been processed, i.e. when the output is complete.
The files ".tocdoc", and ".idxdoc", are intermediate files in doctoc and
docidx markup, respectively, containing the main table of contents and
keyword index for the set of documents before their conversion to the chosen
output format. They are left in place, i.e. not deleted, to serve as
demonstrations of doctoc and docidx markup.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *doctools* 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.
# <a name='see-also'></a>SEE ALSO
[docidx introduction](../doctools/docidx_intro.md), [doctoc
introduction](../doctools/doctoc_intro.md), [doctools
introduction](../doctools/doctools_intro.md)
# <a name='keywords'></a>KEYWORDS
[HTML](../../../../index.md#html), [TMML](../../../../index.md#tmml),
[conversion](../../../../index.md#conversion),
[docidx](../../../../index.md#docidx), [doctoc](../../../../index.md#doctoc),
[doctools](../../../../index.md#doctools),
[manpage](../../../../index.md#manpage), [markup](../../../../index.md#markup),
[nroff](../../../../index.md#nroff)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2013 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/fileutil/fileutil.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
|
[//000000001]: # (fileutil - file utilities)
[//000000002]: # (Generated from file 'fileutil.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil(n) 1.16 tcllib "file utilities")
# NAME
fileutil - Procedures implementing some file utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Warnings and Incompatibilities](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require fileutil ?1.16?
[__::fileutil::lexnormalize__ *path*](#1)
[__::fileutil::fullnormalize__ *path*](#2)
[__::fileutil::test__ *path* *codes* ?*msgvar*? ?*label*?](#3)
[__::fileutil::cat__ (?*options*? *file*)...](#4)
[__::fileutil::writeFile__ ?*options*? *file* *data*](#5)
[__::fileutil::appendToFile__ ?*options*? *file* *data*](#6)
[__::fileutil::insertIntoFile__ ?*options*? *file* *at* *data*](#7)
[__::fileutil::removeFromFile__ ?*options*? *file* *at* *n*](#8)
[__::fileutil::replaceInFile__ ?*options*? *file* *at* *n* *data*](#9)
[__::fileutil::updateInPlace__ ?*options*? *file* *cmd*](#10)
[__::fileutil::fileType__ *filename*](#11)
[__::fileutil::find__ ?*basedir* ?*filtercmd*??](#12)
[__::fileutil::findByPattern__ *basedir* ?__-regexp__|__-glob__? ?__--__? *patterns*](#13)
[__::fileutil::foreachLine__ *var filename cmd*](#14)
[__::fileutil::grep__ *pattern* ?*files*?](#15)
[__::fileutil::install__ ?__-m__ *mode*? *source* *destination*](#16)
[__::fileutil::stripN__ *path* *n*](#17)
[__::fileutil::stripPwd__ *path*](#18)
[__::fileutil::stripPath__ *prefix* *path*](#19)
[__::fileutil::jail__ *jail* *path*](#20)
[__::fileutil::touch__ ?__-a__? ?__-c__? ?__-m__? ?__-r__ *ref_file*? ?__-t__ *time*? *filename* ?*...*?](#21)
[__::fileutil::tempdir__](#22)
[__::fileutil::tempdir__ *path*](#23)
[__::fileutil::tempdirReset__](#24)
[__::fileutil::tempfile__ ?*prefix*?](#25)
[__::fileutil::maketempdir__ ?__-prefix__ *str*? ?__-suffix__ *str*? ?__-dir__ *str*?](#26)
[__::fileutil::relative__ *base* *dst*](#27)
[__::fileutil::relativeUrl__ *base* *dst*](#28)
# <a name='description'></a>DESCRIPTION
This package provides implementations of standard unix utilities.
- <a name='1'></a>__::fileutil::lexnormalize__ *path*
This command performs purely lexical normalization on the *path* and returns
the changed path as its result. Symbolic links in the path are *not*
resolved.
Examples:
fileutil::lexnormalize /foo/./bar
=> /foo/bar
fileutil::lexnormalize /foo/../bar
=> /bar
- <a name='2'></a>__::fileutil::fullnormalize__ *path*
This command resolves all symbolic links in the *path* and returns the
changed path as its result. In contrast to the builtin __file normalize__
this command resolves a symbolic link in the last element of the path as
well.
- <a name='3'></a>__::fileutil::test__ *path* *codes* ?*msgvar*? ?*label*?
A command for the testing of several properties of a *path*. The properties
to test for are specified in *codes*, either as a list of keywords
describing the properties, or as a string where each letter is a shorthand
for a property to test. The recognized keywords, shorthands, and associated
properties are shown in the list below. The tests are executed in the order
given to the command.
The result of the command is a boolean value. It will be true if and only if
the *path* passes all the specified tests. In the case of the *path* not
passing one or more test the first failing test will leave a message in the
variable referenced by *msgvar*, if such is specified. The message will be
prefixed with *label*, if it is specified. *Note* that the variabled
referenced by *msgvar* is not touched at all if all the tests pass.
* *r*ead
__file readable__
* *w*rite
__file writable__
* *e*xists
__file exists__
* e*x*ec
__file executable__
* *f*ile
__file isfile__
* *d*ir
__file isdirectory__
- <a name='4'></a>__::fileutil::cat__ (?*options*? *file*)...
A tcl implementation of the UNIX __[cat](../../../../index.md#cat)__
command. Returns the contents of the specified file(s). The arguments are
files to read, with interspersed options configuring the process. If there
are problems reading any of the files, an error will occur, and no data will
be returned.
The options accepted are __-encoding__, __-translation__, __-eofchar__, and
__--__. With the exception of the last all options take a single value as
argument, as specified by the tcl builtin command __fconfigure__. The __--__
has to be used to terminate option processing before a file if that file's
name begins with a dash.
Each file can have its own set of options coming before it, and for anything
not specified directly the defaults are inherited from the options of the
previous file. The first file inherits the system default for unspecified
options.
- <a name='5'></a>__::fileutil::writeFile__ ?*options*? *file* *data*
The command replaces the current contents of the specified *file* with
*data*, with the process configured by the options. The command accepts the
same options as __::fileutil::cat__. The specification of a non-existent
file is legal and causes the command to create the file (and all required
but missing directories).
- <a name='6'></a>__::fileutil::appendToFile__ ?*options*? *file* *data*
This command is like __::fileutil::writeFile__, except that the previous
contents of *file* are not replaced, but appended to. The command accepts
the same options as __::fileutil::cat__
- <a name='7'></a>__::fileutil::insertIntoFile__ ?*options*? *file* *at* *data*
This comment is similar to __::fileutil::appendToFile__, except that the new
data is not appended at the end, but inserted at a specified location within
the file. In further contrast this command has to be given the path to an
existing file. It will not create a missing file, but throw an error
instead.
The specified location *at* has to be an integer number in the range __0__
... [file size *file*]. __0__ will cause insertion of the new data before
the first character of the existing content, whereas [file size *file*]
causes insertion after the last character of the existing content, i.e.
appending.
The command accepts the same options as __::fileutil::cat__.
- <a name='8'></a>__::fileutil::removeFromFile__ ?*options*? *file* *at* *n*
This command is the complement to __::fileutil::insertIntoFile__, removing
*n* characters from the *file*, starting at location *at*. The specified
location *at* has to be an integer number in the range __0__ ... [file size
*file*] - *n*. __0__ will cause the removal of the new data to start with
the first character of the existing content, whereas [file size *file*] -
*n* causes the removal of the tail of the existing content, i.e. the
truncation of the file.
The command accepts the same options as __::fileutil::cat__.
- <a name='9'></a>__::fileutil::replaceInFile__ ?*options*? *file* *at* *n* *data*
This command is a combination of __::fileutil::removeFromFile__ and
__::fileutil::insertIntoFile__. It first removes the part of the contents
specified by the arguments *at* and *n*, and then inserts *data* at the
given location, effectively replacing the removed by content with *data*.
All constraints imposed on *at* and *n* by __::fileutil::removeFromFile__
and __::fileutil::insertIntoFile__ are obeyed.
The command accepts the same options as __::fileutil::cat__.
- <a name='10'></a>__::fileutil::updateInPlace__ ?*options*? *file* *cmd*
This command can be seen as the generic core functionality of
__::fileutil::replaceInFile__. It first reads the contents of the specified
*file*, then runs the command prefix *cmd* with that data appended to it,
and at last writes the result of that invokation back as the new contents of
the file.
If the executed command throws an error the *file* is not changed.
The command accepts the same options as __::fileutil::cat__.
- <a name='11'></a>__::fileutil::fileType__ *filename*
An implementation of the UNIX __[file](../../../../index.md#file)__ command,
which uses various heuristics to guess the type of a file. Returns a list
specifying as much type information as can be determined about the file,
from most general (eg, "binary" or "text") to most specific (eg, "gif"). For
example, the return value for a GIF file would be "binary graphic gif". The
command will detect the following types of files: directory, empty, binary,
text, script (with interpreter), executable elf, executable dos, executable
ne, executable pe, graphic gif, graphic jpeg, graphic png, graphic tiff,
graphic bitmap, html, xml (with doctype if available), message pgp, binary
pdf, text ps, text eps, binary gravity_wave_data_frame, compressed bzip,
compressed gzip, compressed zip, compressed tar, audio wave, audio mpeg, and
link. It further detects doctools, doctoc, and docidx documentation files,
and tklib diagrams.
- <a name='12'></a>__::fileutil::find__ ?*basedir* ?*filtercmd*??
An implementation of the unix command __[find](../../../../index.md#find)__.
Adapted from the Tcler's Wiki. Takes at most two arguments, the path to the
directory to start searching from and a command to use to evaluate interest
in each file. The path defaults to ".", i.e. the current directory. The
command defaults to the empty string, which means that all files are of
interest. The command takes care *not* to lose itself in infinite loops upon
encountering circular link structures. The result of the command is a list
containing the paths to the interesting files.
The *filtercmd*, if specified, is interpreted as a command prefix and one
argument is added to it, the name of the file or directory find is currently
looking at. Note that this name is *not* fully qualified. It has to be
joined it with the result of __pwd__ to get an absolute filename.
The result of *filtercmd* is a boolean value that indicates if the current
file should be included in the list of interesting files.
Example:
# find .tcl files
package require fileutil
proc is_tcl {name} {return [string match *.tcl $name]}
set tcl_files [fileutil::find . is_tcl]
- <a name='13'></a>__::fileutil::findByPattern__ *basedir* ?__-regexp__|__-glob__? ?__--__? *patterns*
This command is based upon the __TclX__ command __recursive_glob__, except
that it doesn't allow recursion over more than one directory at a time. It
uses __::fileutil::find__ internally and is thus able to and does follow
symbolic links, something the __TclX__ command does not do. First argument
is the directory to start the search in, second argument is a list of
*patterns*. The command returns a list of all files reachable through
*basedir* whose names match at least one of the patterns. The options before
the pattern-list determine the style of matching, either regexp or glob.
glob-style matching is the default if no options are given. Usage of the
option __--__ stops option processing. This allows the use of a leading '-'
in the patterns.
- <a name='14'></a>__::fileutil::foreachLine__ *var filename cmd*
The command reads the file *filename* and executes the script *cmd* for
every line in the file. During the execution of the script the variable
*var* is set to the contents of the current line. The return value of this
command is the result of the last invocation of the script *cmd* or the
empty string if the file was empty.
- <a name='15'></a>__::fileutil::grep__ *pattern* ?*files*?
Implementation of __[grep](../../../../index.md#grep)__. Adapted from the
Tcler's Wiki. The first argument defines the *pattern* to search for. This
is followed by a list of *files* to search through. The list is optional and
__stdin__ will be used if it is missing. The result of the procedures is a
list containing the matches. Each match is a single element of the list and
contains filename, number and contents of the matching line, separated by a
colons.
- <a name='16'></a>__::fileutil::install__ ?__-m__ *mode*? *source* *destination*
The __install__ command is similar in functionality to the __install__
command found on many unix systems, or the shell script distributed with
many source distributions (unix/install-sh in the Tcl sources, for example).
It copies *source*, which can be either a file or directory to
*destination*, which should be a directory, unless *source* is also a single
file. The ?-m? option lets the user specify a unix-style mode (either octal
or symbolic - see __file attributes__.
- <a name='17'></a>__::fileutil::stripN__ *path* *n*
Removes the first *n* elements from the specified *path* and returns the
modified path. If *n* is greater than the number of components in *path* an
empty string is returned. The number of components in a given path may be
determined by performing __llength__ on the list returned by __file split__.
- <a name='18'></a>__::fileutil::stripPwd__ *path*
If, and only if the *path* is inside of the directory returned by [__pwd__]
(or the current working directory itself) it is made relative to that
directory. In other words, the current working directory is stripped from
the *path*. The possibly modified path is returned as the result of the
command. If the current working directory itself was specified for *path*
the result is the string "__.__".
- <a name='19'></a>__::fileutil::stripPath__ *prefix* *path*
If, and only of the *path* is inside of the directory "prefix" (or the
prefix directory itself) it is made relative to that directory. In other
words, the prefix directory is stripped from the *path*. The possibly
modified path is returned as the result of the command. If the prefix
directory itself was specified for *path* the result is the string "__.__".
- <a name='20'></a>__::fileutil::jail__ *jail* *path*
This command ensures that the *path* is not escaping the directory *jail*.
It always returns an absolute path derived from *path* which is within
*jail*.
If *path* is an absolute path and already within *jail* it is returned
unmodified.
An absolute path outside of *jail* is stripped of its root element and then
put into the *jail* by prefixing it with it. The same happens if *path* is
relative, except that nothing is stripped of it. Before adding the *jail*
prefix the *path* is lexically normalized to prevent the caller from using
__..__ segments in *path* to escape the jail.
- <a name='21'></a>__::fileutil::touch__ ?__-a__? ?__-c__? ?__-m__? ?__-r__ *ref_file*? ?__-t__ *time*? *filename* ?*...*?
Implementation of __[touch](../../../../index.md#touch)__. Alter the atime
and mtime of the specified files. If __-c__, do not create files if they do
not already exist. If __-r__, use the atime and mtime from *ref_file*. If
__-t__, use the integer clock value *time*. It is illegal to specify both
__-r__ and __-t__. If __-a__, only change the atime. If __-m__, only change
the mtime.
*This command is not available for Tcl versions less than 8.3.*
- <a name='22'></a>__::fileutil::tempdir__
The command returns the path of a directory where the caller can place
temporary files, such as "/tmp" on Unix systems. The algorithm we use to
find the correct directory is as follows:
The directory set by an invokation of __::fileutil::tempdir__ with an
argument. If this is present it is tried exclusively and none of the
following item are tried.
The directory named in the TMPDIR environment variable.
The directory named in the TEMP environment variable.
The directory named in the TMP environment variable.
A platform specific location:
* Windows
"C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried in that order.
* (classic) Macintosh
The TRASH_FOLDER environment variable is used. This is most likely
not correct.
* Unix
The directories "/tmp", "/var/tmp", and "/usr/tmp" are tried in
that order.
The algorithm utilized is mainly that used in the Python standard library.
The exception is the first item, the ability to have the search overridden
by a user-specified directory.
- <a name='23'></a>__::fileutil::tempdir__ *path*
In this mode the command sets the *path* as the first and only directory to
try as a temp. directory. See the previous item for the use of the set
directory. The command returns the empty string.
- <a name='24'></a>__::fileutil::tempdirReset__
Invoking this command clears the information set by the last call of
[__::fileutil::tempdir__ *path*]. See the last item too.
- <a name='25'></a>__::fileutil::tempfile__ ?*prefix*?
The command generates a temporary file name suitable for writing to, and the
associated file. The file name will be unique, and the file will be writable
and contained in the appropriate system specific temp directory. The name of
the file will be returned as the result of the command.
The code was taken from [http://wiki.tcl.tk/772](http://wiki.tcl.tk/772),
attributed to Igor Volobouev and anon.
- <a name='26'></a>__::fileutil::maketempdir__ ?__-prefix__ *str*? ?__-suffix__ *str*? ?__-dir__ *str*?
The command generates a temporary directory suitable for writing to. The
directory name will be unique, and the directory will be writable and
contained in the appropriate system specific temp directory. The name of the
directory will be returned as the result of the command.
The three options can used to tweak the behaviour of the command:
* __-prefix__ str
The initial, fixed part of the directory name. Defaults to __tmp__ if
not specified.
* __-suffix__ str
The fixed tail of the directory. Defaults to the empty string if not
specified.
* __-dir__ str
The directory to place the new directory into. Defaults to the result of
__fileutil::tempdir__ if not specified.
The initial code for this was supplied by [Miguel Martinez
Lopez](mailto:[email protected]).
- <a name='27'></a>__::fileutil::relative__ *base* *dst*
This command takes two directory paths, both either absolute or relative and
computes the path of *dst* relative to *base*. This relative path is
returned as the result of the command. As implied in the previous sentence,
the command is not able to compute this relationship between the arguments
if one of the paths is absolute and the other relative.
*Note:* The processing done by this command is purely lexical. Symbolic
links are *not* taken into account.
- <a name='28'></a>__::fileutil::relativeUrl__ *base* *dst*
This command takes two file paths, both either absolute or relative and
computes the path of *dst* relative to *base*, as seen from inside of the
*base*. This is the algorithm how a browser resolves a relative link found
in the currently shown file.
The computed relative path is returned as the result of the command. As
implied in the previous sentence, the command is not able to compute this
relationship between the arguments if one of the paths is absolute and the
other relative.
*Note:* The processing done by this command is purely lexical. Symbolic
links are *not* taken into account.
# <a name='section2'></a>Warnings and Incompatibilities
- __1.14.9__
In this version __fileutil::find__'s broken system for handling symlinks was
replaced with one working correctly and properly enumerating all the legal
non-cyclic paths under a base directory.
While correct this means that certain pathological directory hierarchies
with cross-linked sym-links will now take about O(n**2) time to enumerate
whereas the original broken code managed O(n) due to its brokenness.
A concrete example and extreme case is the "/sys" hierarchy under Linux
where some hundred devices exist under both "/sys/devices" and "/sys/class"
with the two sub-hierarchies linking to the other, generating millions of
legal paths to enumerate. The structure, reduced to three devices, roughly
looks like
/sys/class/tty/tty0 --> ../../dev/tty0
/sys/class/tty/tty1 --> ../../dev/tty1
/sys/class/tty/tty2 --> ../../dev/tty1
/sys/dev/tty0/bus
/sys/dev/tty0/subsystem --> ../../class/tty
/sys/dev/tty1/bus
/sys/dev/tty1/subsystem --> ../../class/tty
/sys/dev/tty2/bus
/sys/dev/tty2/subsystem --> ../../class/tty
The command __fileutil::find__ currently has no way to escape this. When
having to handle such a pathological hierarchy It is recommended to switch
to package __fileutil::traverse__ and the same-named command it provides,
and then use the __-prefilter__ option to prevent the traverser from
following symbolic links, like so:
package require fileutil::traverse
proc NoLinks {fileName} {
if {[string equal [file type $fileName] link]} {
return 0
}
return 1
}
fileutil::traverse T /sys/devices -prefilter NoLinks
T foreach p {
puts $p
}
T destroy
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil* 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.
# <a name='keywords'></a>KEYWORDS
[cat](../../../../index.md#cat), [file
utilities](../../../../index.md#file_utilities),
[grep](../../../../index.md#grep), [temp file](../../../../index.md#temp_file),
[test](../../../../index.md#test), [touch](../../../../index.md#touch),
[type](../../../../index.md#type)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/fileutil/multi.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (fileutil::multi - file utilities)
[//000000002]: # (Generated from file 'multi.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::multi(n) 0.1 tcllib "file utilities")
# NAME
fileutil::multi - Multi-file operation, scatter/gather, standard object
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require fileutil::multi ?0.1?
package require fileutil::multi::op ?0.1?
package require wip ?1.0?
[__::fileutil::multi__ ?*word*...?](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single command to perform actions on multiple files
selected by glob patterns. It is a thin layer over the package
__[fileutil::multi::op](multiop.md)__ which provides objects for the same. This
package simply creates a single such object and directs all file commands to it.
At the core is a domain specific language allowing the easy specification of
multi-file copy and/or move and/or deletion operations. Alternate names would be
scatter/gather processor, or maybe even assembler. For the detailed
specification of this language, and examples, please see the documention for the
package __[fileutil::multi::op](multiop.md)__.
# <a name='section2'></a>PUBLIC API
The main command of the package is:
- <a name='1'></a>__::fileutil::multi__ ?*word*...?
This command interprets the specified words as file commands to execute. See
the section __FILE API__ of the documentation for the package
__[fileutil::multi::op](multiop.md)__ for the set of acceptable commands,
their syntax, and semantics.
The result of the command is the result generated by the last file command
it executed.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil* 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.
# <a name='keywords'></a>KEYWORDS
[copy](../../../../index.md#copy), [file
utilities](../../../../index.md#file_utilities),
[move](../../../../index.md#move),
[multi-file](../../../../index.md#multi_file),
[remove](../../../../index.md#remove)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/fileutil/multiop.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
|
[//000000001]: # (fileutil::multi::op - file utilities)
[//000000002]: # (Generated from file 'multiop.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::multi::op(n) 0.5.3 tcllib "file utilities")
# NAME
fileutil::multi::op - Multi-file operation, scatter/gather
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [CLASS API](#section2)
- [OBJECT API](#section3)
- [FILE API](#section4)
- [EXAMPLES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require fileutil::multi::op ?0.5.3?
package require wip ?1.0?
[__::fileutil::multi::op__ ?*opName*? ?*word*...?](#1)
[__opName__ *option* ?*arg arg ...*?](#2)
[__$opName__ __do__ ?*word*...?](#3)
[__into__ *directory*](#4)
[__in__ *directory*](#5)
[__to__ *directory*](#6)
[__from__ *directory*](#7)
[__not__ *pattern*](#8)
[__for__ *pattern*](#9)
[__exclude__ *pattern*](#10)
[__but__](#11)
[__except__](#12)
[__as__ *name*](#13)
[__recursive__](#14)
[__recursively__](#15)
[__[copy](../../../../index.md#copy)__](#16)
[__[move](../../../../index.md#move)__](#17)
[__[remove](../../../../index.md#remove)__](#18)
[__expand__](#19)
[__invoke__ *cmdprefix*](#20)
[__reset__](#21)
[__(__](#22)
[__)__](#23)
[__cd__ *directory*](#24)
[__up__](#25)
[__for-windows__](#26)
[__for-win__](#27)
[__for-unix__](#28)
[__the__ *pattern*](#29)
[__the-set__ *varname*](#30)
[__->__ *varname*](#31)
[__strict__](#32)
[__!strict__](#33)
[__files__](#34)
[__links__](#35)
[__directories__](#36)
[__dirs__](#37)
[__all__](#38)
[__state?__](#39)
[__as?__](#40)
[__excluded?__](#41)
[__from?__](#42)
[__into?__](#43)
[__operation?__](#44)
[__recursive?__](#45)
[__strict?__](#46)
[__type?__](#47)
# <a name='description'></a>DESCRIPTION
This package provides objects which are able to perform actions on multiple
files selected by glob patterns.
At the core is a domain specific language allowing the easy specification of
multi-file copy and/or move and/or deletion operations. Alternate names would be
scatter/gather processor, or maybe even assembler.
# <a name='section2'></a>CLASS API
The main command of the package is:
- <a name='1'></a>__::fileutil::multi::op__ ?*opName*? ?*word*...?
The command creates a new multi-file operation object with an associated
global Tcl command whose name is *opName*. This command can be used to
invoke the various possible file operations. It has the following general
form:
* <a name='2'></a>__opName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
If the string __%AUTO%__ is used as the *opName* then the package will
generate a unique name on its own.
If one or more *word*s are specified they are interpreted as an initial set
of file commands to execute. I.e. the method __do__ of the newly constructed
object is implicitly invoked using the words as its arguments.
# <a name='section3'></a>OBJECT API
The following methods are possible for multi-file operation objects:
- <a name='3'></a>__$opName__ __do__ ?*word*...?
This method interprets the specified words as file commands to execute. See
the section [FILE API](#section4) for the set of acceptable commands, their
syntax, and semantics.
The result of the method is the result generated by the last file command it
executed.
# <a name='section4'></a>FILE API
Both object constructor and method __do__ take a list of words and interpret
them as file commands to execute. The names were chosen to allow the
construction of operations as sentences in near-natural language. Most of the
commands influence just the state of the object, i.e. are simply providing the
configuration used by the command triggering the actual action.
- <a name='4'></a>__into__ *directory*
Specifies the destination directory for operations.
- <a name='5'></a>__in__ *directory*
Alias for __into__.
- <a name='6'></a>__to__ *directory*
Alias for __into__.
- <a name='7'></a>__from__ *directory*
Specifies the source directory for operations.
- <a name='8'></a>__not__ *pattern*
Specifies a glob pattern for paths to be excluded from the operation.
- <a name='9'></a>__for__ *pattern*
Alias for __not__.
- <a name='10'></a>__exclude__ *pattern*
Alias for __not__.
- <a name='11'></a>__but__
Has no arguments of its own, but looks ahead in the list of words and
executes all __not__ commands immediately following it. This allows the
construction of "but not" and "but exclude" clauses for a more natural
sounding specification of excluded paths.
- <a name='12'></a>__except__
A semi-alias for __but__. Has no arguments of its own, but looks ahead in
the list of words and executes all __for__ commands immediately following
it. This allows the construction of "except for" clauses for a more natural
sounding specification of excluded paths.
- <a name='13'></a>__as__ *name*
Specifies a new name for the first file handled by the current operation.
I.e. for the renaming of a single file during the operation.
- <a name='14'></a>__recursive__
Signals that file expansion should happen in the whole directory hierarchy
and not just the directory itself.
- <a name='15'></a>__recursively__
An alias for __recursive__.
- <a name='16'></a>__[copy](../../../../index.md#copy)__
Signals that the operation is the copying of files from source to
destination directory per the specified inclusion and exclusion patterns.
- <a name='17'></a>__[move](../../../../index.md#move)__
Signals that the operation is the moving of files from source to destination
directory per the specified inclusion and exclusion patterns.
- <a name='18'></a>__[remove](../../../../index.md#remove)__
Signals that the operation is the removal of files in the destination
directory per the specified inclusion and exclusion patterns.
- <a name='19'></a>__expand__
Signals that there is no operation but the calculation of the set of files
from the include and exclude patterns. This operation is not available if
__the-set__ is used.
- <a name='20'></a>__invoke__ *cmdprefix*
Signals that the user-specified command prefix *cmdprefix* is the operation
to perform. The command prefix is executed at the global level and given the
source directory, destination directory, and set of files (as dictionary
mapping from source to destination files), in this order.
- <a name='21'></a>__reset__
Forces the object into the ground state where all parts of the configuration
have default values.
- <a name='22'></a>__(__
Saves a copy of the current object state on a stack.
- <a name='23'></a>__)__
Takes the state at the top of the state stack and restores it, i.e. makes it
the new current object state.
- <a name='24'></a>__cd__ *directory*
Changes the destination directory to the sub-directory *directory* of the
current destination.
- <a name='25'></a>__up__
Changes the destination directory to the parent directory of the current
destination.
- <a name='26'></a>__for-windows__
Checks that Windows is the current platform. Aborts processing if not.
- <a name='27'></a>__for-win__
An alias for __for-windows__.
- <a name='28'></a>__for-unix__
Checks that Unix is the current platform. Aborts processing if not.
- <a name='29'></a>__the__ *pattern*
This command specifies the files to operate on per a glob pattern, and is
also the active element, i.e. the command which actually performs the
specified operation. All the other commands only modified the object state
to set the operation up, but di nothing else.
To allow for a more natural sounding syntax this command also looks ahead in
the list of words looks and executes several commands immediately following
it before performing its own actions. These commands are __as__, __but__,
__exclude__, __except__, __from__, and __into__ (and aliases). That way
these commands act like qualifiers, and still take effect as if they had
been written before this command.
After the operation has been performed the object state the exclude patterns
and the alias name, if specified, are reset to their default values (i.e.
empty), but nothing else.
- <a name='30'></a>__the-set__ *varname*
Like __the__, however the set of files to use is not specified implicitly
per a glob pattern, but contained and loaded from the specified variable.
The operation __expand__ is not available if this command is used.
- <a name='31'></a>__->__ *varname*
Saves the set of files from the last expansion into the specified variable.
- <a name='32'></a>__strict__
Make file expansion and definition of destination directory (__in__ and
aliases) strict, i.e. report errors for missing directories, and empty
expansion.
- <a name='33'></a>__!strict__
Complement of __strict__. A missing destination directory or empty expansion
are not reported as errors.
- <a name='34'></a>__files__
Limit the search to files. Default is to accept every type of path.
- <a name='35'></a>__links__
Limit the search to symbolic links. Default is to accept every type of path.
- <a name='36'></a>__directories__
Limit the search to directories. Default is to accept every type of path.
- <a name='37'></a>__dirs__
An alias for __directories__.
- <a name='38'></a>__all__
Accept all types of paths (default).
- <a name='39'></a>__state?__
Returns the current state of the object as dictionary. The dictionary keys
and their meanings are:
* __as__
Last setting made by __as__.
* __excluded__
List of currently known exclusion patterns.
* __from__
Current source directory, set by __from__.
* __into__
Current destination directory, set by __into__ (and aliases).
* __operation__
Current operation to perform, set by
__[copy](../../../../index.md#copy)__,
__[move](../../../../index.md#move)__,
__[remove](../../../../index.md#remove)__, __expand__, or __invoke__.
* __recursive__
Current recursion status. Set/unset by __recursive__ and __!recursive__.
* __strict__
Current strictness. Set/unset by __strict__ and __!strict__.
* __type__
Current path type limiter. Set by either __files__, __directories__,
__links__, or __all__.
- <a name='40'></a>__as?__
Returns the current alias name.
- <a name='41'></a>__excluded?__
Returns the current set of exclusion patterns.
- <a name='42'></a>__from?__
Returns the current source directory.
- <a name='43'></a>__into?__
Returns the current destination directory.
- <a name='44'></a>__operation?__
Returns the current operation to perform.
- <a name='45'></a>__recursive?__
Returns the current recursion status.
- <a name='46'></a>__strict?__
Returns the current strictness.
- <a name='47'></a>__type?__
Returns the current path type limiter.
# <a name='section5'></a>EXAMPLES
The following examples assume that the variable __F__ contains a reference to a
multi-file operation object.
$F do copy \\
the *.dll \\
from c:/TDK/PrivateOpenSSL/bin \\
to [installdir_of tls]
$F do move \\
the * \\
from /sources \\
into /scratch \\
but not *.html
# Alternatively use 'except for *.html'.
$F do \\
move \\
the index \\
from /sources \\
into /scratch \\
as pkgIndex.tcl
$F do \\
remove \\
the *.txt \\
in /scratch
Note that the fact that most commands just modify the object state allows us to
use more off forms as specifications instead of just nearly-natural language
sentences. For example the second example in this section can re-arranged into:
$F do \\
from /sources \\
into /scratch \\
but not *.html \\
move \\
the *
and the result is not only still a valid specification, but even stays
relatively readable.
Further note that the information collected by the commands __but__, __except__,
and __as__ is automatically reset after the associated __the__ was executed.
However no other state is reset in that manner, allowing the user to avoid
repetitions of unchanging information. For example the second and third examples
of this section can be merged and rewritten into the equivalent:
$F do \\
move \\
the * \\
from /sources \\
into /scratch \\
but not *.html not index \\
the index \\
as pkgIndex.tcl
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil* 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.
# <a name='keywords'></a>KEYWORDS
[copy](../../../../index.md#copy), [file
utilities](../../../../index.md#file_utilities),
[move](../../../../index.md#move),
[multi-file](../../../../index.md#multi_file),
[remove](../../../../index.md#remove)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/fileutil/traverse.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
[//000000001]: # (fileutil_traverse - file utilities)
[//000000002]: # (Generated from file 'traverse.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil_traverse(n) 0.6 tcllib "file utilities")
# NAME
fileutil_traverse - Iterative directory traversal
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OPTIONS](#section2)
- [Warnings and Incompatibilities](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require fileutil::traverse ?0.6?
package require fileutil
package require control
[__::fileutil::traverse__ ?*objectName*? *path* ?*option* *value*...?](#1)
[__$traverser__ __command__ ?*arg arg ...*?](#2)
[__$traverser__ __files__](#3)
[__$traverser__ __foreach__ *filevar* *script*](#4)
[__$traverser__ __next__ *filevar*](#5)
# <a name='description'></a>DESCRIPTION
This package provides objects for the programmable traversal of directory
hierarchies. The main command exported by the package is:
- <a name='1'></a>__::fileutil::traverse__ ?*objectName*? *path* ?*option* *value*...?
The command creates a new traversal object with an associated global Tcl
command whose name is *objectName*. This command may be used to invoke
various operations on the traverser. If the string __%AUTO%__ is used as the
*objectName* then a unique name will be generated by the package itself.
Regarding the recognized options see section [OPTIONS](#section2). Note that
all these options can be set only during the creation of the traversal
object. Changing them later is not possible and causes errors to be thrown
if attempted.
The object command has the following general form:
* <a name='2'></a>__$traverser__ __command__ ?*arg arg ...*?
*Command* and its *arg*uments determine the exact behavior of the
object.
The following commands are possible for traversal objects:
- <a name='3'></a>__$traverser__ __files__
This method is the most highlevel one provided by traversal objects. When
invoked it returns a list containing the names of all files and directories
matching the current configuration of the traverser.
- <a name='4'></a>__$traverser__ __foreach__ *filevar* *script*
The highlevel __files__ method (see above) is based on this mid-level
method. When invoked it finds all files and directories matching per the
current configuration and executes the *script* for each path. The current
path under consideration is stored in the variable named by *filevar*. Both
variable and script live / are executed in the context of the caller of the
method. In the method __files__ the script simply saves the found paths into
the list to return.
- <a name='5'></a>__$traverser__ __next__ *filevar*
This is the lowest possible interface to the traverser, the core all higher
methods are built on. When invoked it returns a boolean value indicating
whether it found a path matching the current configuration (__True__), or
not (__False__). If a path was found it is stored into the variable named by
*filevar*, in the context of the caller.
The __foreach__ method simply calls this method in a loop until it returned
__False__. This method is exposed so that we are also able to incrementally
traverse a directory hierarchy in an event-based manner.
Note that the traverser does follow symbolic links, except when doing so
would cause it to enter a link-cycle. In other words, the command takes care
to *not* lose itself in infinite loops upon encountering circular link
structures. Note that even links which are not followed will still appear in
the result.
# <a name='section2'></a>OPTIONS
- __-prefilter__ command_prefix
This callback is executed for directories. Its result determines if the
traverser recurses into the directory or not. The default is to always
recurse into all directories. The callback is invoked with a single
argument, the *absolute* path of the directory, and has to return a boolean
value, __True__ when the directory passes the filter, and __False__ if not.
- __-filter__ command_prefix
This callback is executed for all paths. Its result determines if the
current path is a valid result, and returned by __next__. The default is to
accept all paths as valid. The callback is invoked with a single argument,
the *absolute* path to check, and has to return a boolean value, __True__
when the path passes the filter, and __False__ if not.
- __-errorcmd__ command_prefix
This callback is executed for all paths the traverser has trouble with. Like
being unable to change into them, get their status, etc. The default is to
ignore any such problems. The callback is invoked with a two arguments, the
*absolute* path for which the error occured, and the error message. Errors
thrown by the filter callbacks are handled through this callback too. Errors
thrown by the error callback itself are not caught and ignored, but allowed
to pass to the caller, i.e. however invoked the __next__. Any other results
from the callback are ignored.
# <a name='section3'></a>Warnings and Incompatibilities
- __0.4.4__
In this version the traverser's broken system for handling symlinks was
replaced with one working correctly and properly enumerating all the legal
non-cyclic paths under a base directory.
While correct this means that certain pathological directory hierarchies
with cross-linked sym-links will now take about O(n**2) time to enumerate
whereas the original broken code managed O(n) due to its brokenness.
A concrete example and extreme case is the "/sys" hierarchy under Linux
where some hundred devices exist under both "/sys/devices" and "/sys/class"
with the two sub-hierarchies linking to the other, generating millions of
legal paths to enumerate. The structure, reduced to three devices, roughly
looks like
/sys/class/tty/tty0 --> ../../dev/tty0
/sys/class/tty/tty1 --> ../../dev/tty1
/sys/class/tty/tty2 --> ../../dev/tty1
/sys/dev/tty0/bus
/sys/dev/tty0/subsystem --> ../../class/tty
/sys/dev/tty1/bus
/sys/dev/tty1/subsystem --> ../../class/tty
/sys/dev/tty2/bus
/sys/dev/tty2/subsystem --> ../../class/tty
When having to handle such a pathological hierarchy it is recommended to use
the __-prefilter__ option to prevent the traverser from following symbolic
links, like so:
package require fileutil::traverse
proc NoLinks {fileName} {
if {[string equal [file type $fileName] link]} {
return 0
}
return 1
}
fileutil::traverse T /sys/devices -prefilter NoLinks
T foreach p {
puts $p
}
T destroy
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil* 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.
# <a name='keywords'></a>KEYWORDS
[directory traversal](../../../../index.md#directory_traversal),
[traversal](../../../../index.md#traversal)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/ftp/ftp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
[//000000001]: # (ftp - ftp client)
[//000000002]: # (Generated from file 'ftp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ftp(n) 2.4.13 tcllib "ftp client")
# NAME
ftp - Client-side tcl implementation of the ftp protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [BUGS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require ftp ?2.4.13?
[__::ftp::Open__ *server* *user* *passwd* ?*options*?](#1)
[__::ftp::Close__ *handle*](#2)
[__::ftp::Cd__ *handle* *directory*](#3)
[__::ftp::Pwd__ *handle*](#4)
[__::ftp::Type__ *handle* ?__ascii|binary|tenex__?](#5)
[__::ftp::List__ *handle* ?*pattern*?](#6)
[__::ftp::NList__ *handle* ?*directory*?](#7)
[__::ftp::FileSize__ *handle* *file*](#8)
[__::ftp::ModTime__ *handle* *file*](#9)
[__::ftp::Delete__ *handle* *file*](#10)
[__::ftp::Rename__ *handle* *from* *to*](#11)
[__::ftp::Put__ *handle* (*local* | -data *data* | -channel *chan*) ?*remote*?](#12)
[__::ftp::Append__ *handle* (*local* | -data *data* | -channel *chan*) ?*remote*?](#13)
[__::ftp::Get__ *handle* *remote* ?(*local* | -variable *varname* | -channel *chan*)?](#14)
[__::ftp::Reget__ *handle* *remote* ?*local*? ?*from*? ?*to*?](#15)
[__::ftp::Newer__ *handle* *remote* ?*local*?](#16)
[__::ftp::MkDir__ *handle* *directory*](#17)
[__::ftp::RmDir__ *handle* *directory*](#18)
[__::ftp::Quote__ *handle* *arg1* *arg2* *...*](#19)
[__::ftp::DisplayMsg__ *handle* *msg* ?*state*?](#20)
# <a name='description'></a>DESCRIPTION
The ftp package provides the client side of the ftp protocol as specified in RFC
959
([http://www.rfc-editor.org/rfc/rfc959.txt](http://www.rfc-editor.org/rfc/rfc959.txt)).
The package implements both active (default) and passive ftp sessions.
A new ftp session is started with the __::ftp::Open__ command. To shutdown an
existing ftp session use __::ftp::Close__. All other commands are restricted to
usage in an an open ftp session. They will generate errors if they are used out
of context. The ftp package includes file and directory manipulating commands
for remote sites. To perform the same operations on the local site use commands
built into the core, like __cd__ or __[file](../../../../index.md#file)__.
The output of the package is controlled by two state variables,
__::ftp::VERBOSE__ and __::ftp::DEBUG__. Setting __::ftp::VERBOSE__ to "1"
forces the package to show all responses from a remote server. The default value
is "0". Setting __::ftp::DEBUG__ to "1" enables debugging and forces the package
to show all return codes, states, state changes and "real" ftp commands. The
default value is "0".
The command __::ftp::DisplayMsg__ is used to show the different messages from
the ftp session. The setting of __::ftp::VERBOSE__ determines if this command is
called or not. The current implementation of the command uses the
__[log](../log/log.md)__ package of tcllib to write the messages to their final
destination. This means that the behaviour of __::ftp::DisplayMsg__ can be
customized without changing its implementation. For more radical changes
overwriting its implementation by the application is of course still possible.
Note that the default implementation honors the option __-output__ to
__::ftp::Open__ for a session specific log command.
*Caution*: The default implementation logs error messages like all other
messages. If this behaviour is changed to throwing an error instead all commands
in the API will change their behaviour too. In such a case they will not return
a failure code as described below but pass the thrown error to their caller.
# <a name='section2'></a>API
- <a name='1'></a>__::ftp::Open__ *server* *user* *passwd* ?*options*?
This command is used to start a FTP session by establishing a control
connection to the FTP server. The defaults are used for any option not
specified by the caller.
The command takes a host name *server*, a user name *user* and a password
*password* as its parameters and returns a session handle that is an integer
number greater than or equal to "0", if the connection is successfully
established. Otherwise it returns "-1". The *server* parameter must be the
name or internet address (in dotted decimal notation) of the ftp server to
connect to. The *user* and *passwd* parameters must contain a valid user
name and password to complete the login process.
The options overwrite some default values or set special abilities:
* __-blocksize__ *size*
The blocksize is used during data transfer. At most *size* bytes are
transfered at once. The default value for this option is 4096. The
package will evaluate the __-progress callback__ for the session after
the transfer of each block.
* __-timeout__ *seconds*
If *seconds* is non-zero, then __::ftp::Open__ sets up a timeout which
will occur after the specified number of seconds. The default value is
600.
* __-port__ *number*
The port *number* specifies an alternative remote port on the ftp server
on which the ftp service resides. Most ftp services listen for
connection requests on the default port 21. Sometimes, usually for
security reasons, port numbers other than 21 are used for ftp
connections.
* __-mode__ *mode*
The transfer *mode* option determines if a file transfer occurs in
__active__ or __passive__ mode. In passive mode the client will ask the
ftp server to listen on a data port and wait for the connection rather
than to initiate the process by itself when a data transfer request
comes in. Passive mode is normally a requirement when accessing sites
via a firewall. The default mode is __active__.
* __-progress__ *callback*
This *callback* is evaluated whenever a block of data was transfered.
See the option __-blocksize__ for how to specify the size of the
transfered blocks.
When evaluating the *callback* one argument is appended to the callback
script, the current accumulated number of bytes transferred so far.
* __-command__ *callback*
Specifying this option places the connection into asynchronous mode. The
*callback* is evaluated after the completion of any operation. When an
operation is running no further operations must be started until a
callback has been received for the currently executing operation.
When evaluating the *callback* several arguments are appended to the
callback script, namely the keyword of the operation that has completed
and any additional arguments specific to the operation. If an error
occurred during the execution of the operation the callback is given the
keyword __error__.
* __-output__ *callback*
This option has no default. If it is set the default implementation of
__::ftp::DisplayMsg__ will use its value as command prefix to log all
internal messages. The callback will have three arguments appended to it
before evaluation, the id of the session, the message itself, and the
connection state, in this order.
- <a name='2'></a>__::ftp::Close__ *handle*
This command terminates the specified ftp session. If no file transfer is in
progress, the server will close the control connection immediately. If a
file transfer is in progress however, the control connection will remain
open until the transfers completes. When that happens the server will write
the result response for the transfer to it and close the connection
afterward.
- <a name='3'></a>__::ftp::Cd__ *handle* *directory*
This command changes the current working directory on the ftp server to a
specified target *directory*. The command returns 1 if the current working
directory was successfully changed to the specified directory or 0 if it
fails. The target directory can be
a subdirectory of the current directory,
Two dots, __..__ (as an indicator for the parent directory of the current
directory)
or a fully qualified path to a new working directory.
- <a name='4'></a>__::ftp::Pwd__ *handle*
This command returns the complete path of the current working directory on
the ftp server, or an empty string in case of an error.
- <a name='5'></a>__::ftp::Type__ *handle* ?__ascii|binary|tenex__?
This command sets the ftp file transfer type to either __ascii__,
__binary__, or __tenex__. The command always returns the currently set type.
If called without type no change is made.
Currently only __ascii__ and __binary__ types are supported. There is some
early (alpha) support for Tenex mode. The type __ascii__ is normally used to
convert text files into a format suitable for text editors on the platform
of the destination machine. This mainly affects end-of-line markers. The
type __binary__ on the other hand allows the undisturbed transfer of
non-text files, such as compressed files, images and executables.
- <a name='6'></a>__::ftp::List__ *handle* ?*pattern*?
This command returns a human-readable list of files. Wildcard expressions
such as "*.tcl" are allowed. If *pattern* refers to a specific directory,
then the contents of that directory are returned. If the *pattern* is not a
fully-qualified path name, the command lists entries relative to the current
remote directory. If no *pattern* is specified, the contents of the current
remote directory is returned.
The listing includes any system-dependent information that the server
chooses to include. For example most UNIX systems produce output from the
command __ls -l__. The command returns the retrieved information as a tcl
list with one item per entry. Empty lines and UNIX's "total" lines are
ignored and not included in the result as reported by this command.
If the command fails an empty list is returned.
- <a name='7'></a>__::ftp::NList__ *handle* ?*directory*?
This command has the same behavior as the __::ftp::List__ command, except
that it only retrieves an abbreviated listing. This means only file names
are returned in a sorted list.
- <a name='8'></a>__::ftp::FileSize__ *handle* *file*
This command returns the size of the specified *file* on the ftp server. If
the command fails an empty string is returned.
*ATTENTION!* It will not work properly when in ascii mode and is not
supported by all ftp server implementations.
- <a name='9'></a>__::ftp::ModTime__ *handle* *file*
This command retrieves the time of the last modification of the *file* on
the ftp server as a system dependent integer value in seconds or an empty
string if an error occurred. Use the built-in command __clock__ to convert
the retrieves value into other formats.
- <a name='10'></a>__::ftp::Delete__ *handle* *file*
This command deletes the specified *file* on the ftp server. The command
returns 1 if the specified file was successfully deleted or 0 if it failed.
- <a name='11'></a>__::ftp::Rename__ *handle* *from* *to*
This command renames the file *from* in the current directory of the ftp
server to the specified new file name *to*. This new file name must not be
the same as any existing subdirectory or file name. The command returns 1 if
the specified file was successfully renamed or 0 if it failed.
- <a name='12'></a>__::ftp::Put__ *handle* (*local* | -data *data* | -channel *chan*) ?*remote*?
This command transfers a local file *local* to a remote file *remote* on the
ftp server. If the file parameters passed to the command do not fully
qualified path names the command will use the current directory on local and
remote host. If the remote file name is unspecified, the server will use the
name of the local file as the name of the remote file. The command returns 1
to indicate a successful transfer and 0 in the case of a failure.
If __-data__ *data* is specified instead of a local file, the system will
not transfer a file, but the *data* passed into it. In this case the name of
the remote file has to be specified.
If __-channel__ *chan* is specified instead of a local file, the system will
not transfer a file, but read the contents of the channel *chan* and write
this to the remote file. In this case the name of the remote file has to be
specified. After the transfer *chan* will be closed.
- <a name='13'></a>__::ftp::Append__ *handle* (*local* | -data *data* | -channel *chan*) ?*remote*?
This command behaves like __::ftp::Puts__, but appends the transfered
information to the remote file. If the file did not exist on the server it
will be created.
- <a name='14'></a>__::ftp::Get__ *handle* *remote* ?(*local* | -variable *varname* | -channel *chan*)?
This command retrieves a remote file *remote* on the ftp server and stores
its contents into the local file *local*. If the file parameters passed to
the command are not fully qualified path names the command will use the
current directory on local and remote host. If the local file name is
unspecified, the server will use the name of the remote file as the name of
the local file. The command returns 1 to indicate a successful transfer and
0 in the case of a failure. The command will throw an error if the directory
the file *local* is to be placed in does not exist.
If __-variable__ *varname* is specified, the system will store the retrieved
data into the variable *varname* instead of a file.
If __-channel__ *chan* is specified, the system will write the retrieved
data into the channel *chan* instead of a file. The system will *not* close
*chan* after the transfer, this is the responsibility of the caller to
__::ftp::Get__.
- <a name='15'></a>__::ftp::Reget__ *handle* *remote* ?*local*? ?*from*? ?*to*?
This command behaves like __::ftp::Get__, except that if local file *local*
exists and is smaller than remote file *remote*, the local file is presumed
to be a partially transferred copy of the remote file and the transfer is
continued from the apparent point of failure. The command will throw an
error if the directory the file *local* is to be placed in does not exist.
This command is useful when transferring very large files over networks that
tend to drop connections.
Specifying the additional byte offsets *from* and *to* will cause the
command to change its behaviour and to download exactly the specified slice
of the remote file. This mode is possible only if a local destination is
explicitly provided. Omission of *to* leads to downloading till the end of
the file.
- <a name='16'></a>__::ftp::Newer__ *handle* *remote* ?*local*?
This command behaves like __::ftp::Get__, except that it retrieves the
remote file only if the modification time of the remote file is more recent
than the file on the local system. If the file does not exist on the local
system, the remote file is considered newer. The command will throw an error
if the directory the file *local* is to be placed in does not exist.
- <a name='17'></a>__::ftp::MkDir__ *handle* *directory*
This command creates the specified *directory* on the ftp server. If the
specified path is relative the new directory will be created as a
subdirectory of the current working directory. Else the created directory
will have the specified path name. The command returns 1 to indicate a
successful creation of the directory and 0 in the case of a failure.
- <a name='18'></a>__::ftp::RmDir__ *handle* *directory*
This command removes the specified directory on the ftp server. The remote
directory has to be empty or the command will fail. The command returns 1 to
indicate a successful removal of the directory and 0 in the case of a
failure.
- <a name='19'></a>__::ftp::Quote__ *handle* *arg1* *arg2* *...*
This command is used to send an arbitrary ftp command to the server. It
cannot be used to obtain a directory listing or for transferring files. It
is included to allow an application to execute commands on the ftp server
which are not provided by this package. The arguments are sent verbatim,
i.e. as is, with no changes.
In contrast to the other commands in this package this command will not
parse the response it got from the ftp server but return it verbatim to the
caller.
- <a name='20'></a>__::ftp::DisplayMsg__ *handle* *msg* ?*state*?
This command is used by the package itself to show the different messages
from the ftp sessions. The package itself declares this command very simple,
writing the messages to __stdout__ (if __::ftp::VERBOSE__ was set, see
below) and throwing tcl errors for error messages. It is the responsibility
of the application to overwrite it as needed. A state variable for different
states assigned to different colors is recommended by the author. The
package __[log](../log/log.md)__ is useful for this.
- __::ftp::VERBOSE__
A state variable controlling the output of the package. Setting
__::ftp::VERBOSE__ to "1" forces the package to show all responses from a
remote server. The default value is "0".
- __::ftp::DEBUG__
A state variable controlling the output of ftp. Setting __::ftp::DEBUG__ to
"1" enables debugging and forces the package to show all return codes,
states, state changes and "real" ftp commands. The default value is "0".
# <a name='section3'></a>BUGS
The correct execution of many commands depends upon the proper behavior by the
remote server, network and router configuration.
An update command placed in the procedure __::ftp::DisplayMsg__ may run into
persistent errors or infinite loops. The solution to this problem is to use
__update idletasks__ instead of __[update](../../../../index.md#update)__.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ftp* 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.
# <a name='see-also'></a>SEE ALSO
[ftpd](../ftpd/ftpd.md), [mime](../mime/mime.md), [pop3](../pop3/pop3.md),
[smtp](../mime/smtp.md)
# <a name='keywords'></a>KEYWORDS
[ftp](../../../../index.md#ftp), [internet](../../../../index.md#internet),
[net](../../../../index.md#net), [rfc 959](../../../../index.md#rfc_959)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/ftp/ftp_geturl.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
[//000000001]: # (ftp::geturl - ftp client)
[//000000002]: # (Generated from file 'ftp_geturl.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ftp::geturl(n) 0.2.2 tcllib "ftp client")
# NAME
ftp::geturl - Uri handler for ftp urls
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require ftp::geturl ?0.2.2?
[__::ftp::geturl__ *url*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a command which wraps around the client side of the
*[ftp](../../../../index.md#ftp)* protocol provided by package __[ftp](ftp.md)__
to allow the retrieval of urls using the *[ftp](../../../../index.md#ftp)*
schema.
# <a name='section2'></a>API
- <a name='1'></a>__::ftp::geturl__ *url*
This command can be used by the generic command __::uri::geturl__ (See
package __[uri](../uri/uri.md)__) to retrieve the contents of ftp urls.
Internally it uses the commands of the package __[ftp](ftp.md)__ to fulfill
the request.
The contents of a *[ftp](../../../../index.md#ftp)* url are defined as
follows:
* *[file](../../../../index.md#file)*
The contents of the specified file itself.
* *directory*
A listing of the contents of the directory in key value notation where
the file name is the key and its attributes the associated value.
* *link*
The attributes of the link, including the path it refers to.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ftp* 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.
# <a name='see-also'></a>SEE ALSO
[ftpd](../ftpd/ftpd.md), [mime](../mime/mime.md), [pop3](../pop3/pop3.md),
[smtp](../mime/smtp.md)
# <a name='keywords'></a>KEYWORDS
[ftp](../../../../index.md#ftp), [internet](../../../../index.md#internet),
[net](../../../../index.md#net), [rfc 959](../../../../index.md#rfc_959)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/ftpd/ftpd.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
|
[//000000001]: # (ftpd - Tcl FTP Server Package)
[//000000002]: # (Generated from file 'ftpd.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ftpd(n) 1.3 tcllib "Tcl FTP Server Package")
# NAME
ftpd - Tcl FTP server implementation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [CALLBACKS](#section3)
- [VARIABLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require ftpd ?1.3?
[__::ftpd::server__ ?*myaddr*?](#1)
[__::ftpd::config__ ?*option value*? ?*option value ...*?](#2)
[*fsCmd* __append__ *path*](#3)
[*fsCmd* __delete__ *path* *channel*](#4)
[*fsCmd* __dlist__ *path* *style* *channel*](#5)
[*fsCmd* __exists__ *path*](#6)
[*fsCmd* __mkdir__ *path* *channel*](#7)
[*fsCmd* __mtime__ *path* *channel*](#8)
[*fsCmd* __permissions__ *path*](#9)
[*fsCmd* __rename__ *path* *newpath* *channel*](#10)
[*fsCmd* __retr__ *path*](#11)
[*fsCmd* __rmdir__ *path* *channel*](#12)
[*fsCmd* __size__ *path* *channel*](#13)
[*fsCmd* __store__ *path*](#14)
# <a name='description'></a>DESCRIPTION
The __ftpd__ package provides a simple Tcl-only server library for the FTP
protocol as specified in RFC 959
([http://www.rfc-editor.org/rfc/rfc959.txt](http://www.rfc-editor.org/rfc/rfc959.txt)).
It works by listening on the standard FTP socket. Most server errors are
returned as error messages with the appropriate code attached to them. Since the
server code for the ftp daemon is executed in the event loop, it is possible
that a __bgerror__ will be thrown on the server if there are problems with the
code in the module.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::ftpd::server__ ?*myaddr*?
Open a listening socket to listen to and accept ftp connections. myaddr is
an optional argument. *myaddr* is the domain-style name or numerical IP
address of the client-side network interface to use for the connection.
- <a name='2'></a>__::ftpd::config__ ?*option value*? ?*option value ...*?
The value is always the name of the command to call as the callback. The
option specifies which callback should be configured. See section
[CALLBACKS](#section3) for descriptions of the arguments and return values
for each of the callbacks.
* -authIpCmd *proc*
Callback to authenticate new connections based on the ip-address of the
peer.
* -authUsrCmd *proc*
Callback to authenticate new connections based on the user logging in
(and the users password).
* -authFileCmd *proc*
Callback to accept or deny a users access to read and write to a
specific path or file.
* -logCmd *proc*
Callback for log information generated by the FTP engine.
* -fsCmd *proc*
Callback to connect the engine to the filesystem it operates on.
* -closeCmd *proc*
Callback to be called when a connection is closed. This allows the
embedding application to perform its own cleanup operations.
* -xferDoneCmd *proc*
Callback for transfer completion notification. In other words, it is
called whenever a transfer of data to or from the client has completed.
# <a name='section3'></a>CALLBACKS
- __authIpCmd__ callback
The authIpCmd receives the ip-address of the peer attempting to connect to
the ftp server as its argument. It returns a 1 to allow users from the
specified IP to attempt to login and a 0 to reject the login attempt from
the specified IP.
- __authUsrCmd__ callback
The authUsrCmd receives the username and password as its two arguments. It
returns a 1 to accept the attempted login to the ftpd and a 0 to reject the
attempted login.
- __authFileCmd__ callback
The authFileCmd receives the user (that is currently logged in), the path or
filename that is about to be read or written, and __read__ or __write__ as
its three arguments. It returns a 1 to allow the path or filename to be read
or written, and a 0 to reject the attempted read or write with a permissions
error code.
- __logCmd__ callback
The logCmd receives a severity and a message as its two arguments. The
severities used within the ftpd package are __note__, __debug__, and
__error__. The logCmd doesn't return anything.
- __fsCmd__ callback
The fsCmd receives a subcommand, a filename or path, and optional additional
arguments (depending on the subcommand).
The subcommands supported by the fsCmd are:
* <a name='3'></a>*fsCmd* __append__ *path*
The append subcommand receives the filename to append to as its
argument. It returns a writable tcl channel as its return value.
* <a name='4'></a>*fsCmd* __delete__ *path* *channel*
The delete subcommand receives the filename to delete, and a channel to
write to as its two arguments. The file specified is deleted and the
appropriate ftp message is written to the channel that is passed as the
second argument. The delete subcommand returns nothing.
* <a name='5'></a>*fsCmd* __dlist__ *path* *style* *channel*
The dlist subcommand receives the path that it should list the files
that are in, the style in which the files should be listed which is
either __nlst__ or __list__, and a channel to write to as its three
arguments. The files in the specified path are printed to the specified
channel one per line. If the style is __nlst__ only the name of the file
is printed to the channel. If the style is __list__ then the file
permissions, number of links to the file, the name of the user that owns
the file, the name of the group that owns the file, the size (in bytes)
of the file, the modify time of the file, and the filename are printed
out to the channel in a formatted space separated format. The __dlist__
subcommand returns nothing.
* <a name='6'></a>*fsCmd* __exists__ *path*
The exists subcommand receives the name of a file to check the existence
of as its only argument. The exists subcommand returns a 1 if the path
specified exists and the path is not a directory.
* <a name='7'></a>*fsCmd* __mkdir__ *path* *channel*
The mkdir subcommand receives the path of a directory to create and a
channel to write to as its two arguments. The mkdir subcommand creates
the specified directory if necessary and possible. The mkdir subcommand
then prints the appropriate success or failure message to the channel.
The mkdir subcommand returns nothing.
* <a name='8'></a>*fsCmd* __mtime__ *path* *channel*
The mtime subcommand receives the path of a file to check the modify
time on and a channel as its two arguments. If the file exists the mtime
is printed to the channel in the proper FTP format, otherwise an
appropriate error message and code are printed to the channel. The mtime
subcommand returns nothing.
* <a name='9'></a>*fsCmd* __permissions__ *path*
The permissions subcommand receives the path of a file to retrieve the
permissions of. The permissions subcommand returns the octal file
permissions of the specified file. The file is expected to exist.
* <a name='10'></a>*fsCmd* __rename__ *path* *newpath* *channel*
The rename subcommand receives the path of the current file, the new
file path, and a channel to write to as its three arguments. The rename
subcommand renames the current file to the new file path if the path to
the new file exists, and then prints out the appropriate message to the
channel. If the new file path doesn't exist the appropriate error
message is printed to the channel. The rename subcommand returns
nothing.
* <a name='11'></a>*fsCmd* __retr__ *path*
The retr subcommand receives the path of a file to read as its only
argument. The retr subcommand returns a readable channel that the
specified file can be read from.
* <a name='12'></a>*fsCmd* __rmdir__ *path* *channel*
The rmdir subcommand receives the path of a directory to remove and a
channel to write to as its two arguments. The rmdir subcommand removes
the specified directory (if possible) and prints the appropriate message
to the channel (which may be an error if the specified directory does
not exist or is not empty). The rmdir subcommand returns nothing.
* <a name='13'></a>*fsCmd* __size__ *path* *channel*
The size subcommand receives the path of a file to get the size (in
bytes) of and a channel to write to as its two arguments. The size
subcommand prints the appropriate code and the size of the file if the
specified path is a file, otherwise an appropriate error code and
message are printed to the channel. The size subcommand returns nothing.
* <a name='14'></a>*fsCmd* __store__ *path*
The store subcommand receives the path of a file to write as its only
argument. The store subcommand returns a writable channel.
- __closeCmd__
The __closeCmd__ receives no arguments when it is invoked, and any return
value it may generate is discarded.
- __xferDoneCmd__ sock sock2 file bytes filename err
The __xferDoneCmd__ receives six arguments when invoked. These are, in this
order, the channel handle of the control socket for the connection, the
channel handle of the data socket used for the transfer (already closed),
the handle of the channel containing the transfered file, the number of
bytes transfered, the path of the file which was transfered, and a (possibly
empty) error message. Any return value it may generate is discarded.
# <a name='section4'></a>VARIABLES
- __::ftpd::cwd__
The current working directory for a session when someone first connects to
the FTPD or when the __REIN__ ftp command is received.
- __::ftpd::contact__
The e-mail address of the person that is the contact for the ftp server.
This address is printed out as part of the response to the __FTP HELP__
command.
- __::ftpd::port__
The port that the ftp server should listen on. If port is specified as zero,
the operating system will allocate an unused port for use as a server
socket; afterwards, the variable will contain the port number that was
allocated.
- __::ftpd::welcome__
The message that is printed out when the user first connects to the ftp
server.
- __::ftpd::CurrentSocket__
Accessible to all callbacks and all filesystem commands (which are a special
form of callback) and contains the handle of the socket channel which was
active when the callback was invoked.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ftpd* 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.
# <a name='keywords'></a>KEYWORDS
[ftp](../../../../index.md#ftp), [ftpd](../../../../index.md#ftpd),
[ftpserver](../../../../index.md#ftpserver), [rfc
959](../../../../index.md#rfc_959), [services](../../../../index.md#services)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/fumagic/cfront.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
[//000000001]: # (fileutil::magic::cfront - file utilities)
[//000000002]: # (Generated from file 'cfront.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::magic::cfront(n) 1.2.0 tcllib "file utilities")
# NAME
fileutil::magic::cfront - Generator core for compiler of magic(5) files
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require fileutil::magic::cfront ?1.2.0?
package require fileutil::magic::cgen ?1.2.0?
package require fileutil::magic::rt ?1.2.0?
package require struct::list
package require fileutil
[__::fileutil::magic::cfront::compile__ *path*...](#1)
[__::fileutil::magic::cfront::procdef__ *procname* *path*...](#2)
[__::fileutil::magic::cfront::install__ *path*...](#3)
# <a name='description'></a>DESCRIPTION
This package provides the frontend of a compiler of magic(5) files into
recognizers based on the __[fileutil::magic::rt](rtcore.md)__ recognizer runtime
package. For the generator backed used by this compiler see the package
__[fileutil::magic::cgen](cgen.md)__.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::fileutil::magic::cfront::compile__ *path*...
This command takes the paths of one or more files and directories and
compiles all the files, and the files in all the directories into a single
recognizer for all the file types specified in these files.
All the files have to be in the format specified by magic(5).
The result of the command is a Tcl script containing the generated
recognizer.
- <a name='2'></a>__::fileutil::magic::cfront::procdef__ *procname* *path*...
This command behaves like __::fileutil::magic::cfront::compile__ with regard
to the specified path arguments, then wraps the resulting recognizer script
into a procedure named *procname*, puts code setting up the namespace of
*procname* in front, and returns the resulting script.
- <a name='3'></a>__::fileutil::magic::cfront::install__ *path*...
This command uses __::fileutil::magic::cfront::procdef__ to compile each of
the paths into a recognizer procedure and installs the result in the current
interpreter.
The name of each new procedure is derived from the name of the
file/directory used in its creation, with file/directory "FOO" causing the
creation of procedure __::fileutil::magic::/FOO::run__.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil :: magic* 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.
# <a name='see-also'></a>SEE ALSO
file(1), [fileutil](../fileutil/fileutil.md), magic(5)
# <a name='keywords'></a>KEYWORDS
[file recognition](../../../../index.md#file_recognition), [file
type](../../../../index.md#file_type), [file
utilities](../../../../index.md#file_utilities),
[mime](../../../../index.md#mime), [type](../../../../index.md#type)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/fumagic/cgen.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
[//000000001]: # (fileutil::magic::cgen - file utilities)
[//000000002]: # (Generated from file 'cgen.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::magic::cgen(n) 1.2.0 tcllib "file utilities")
# NAME
fileutil::magic::cgen - Generator core for compiler of magic(5) files
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require fileutil::magic::cgen ?1.2.0?
package require fileutil::magic::rt ?1.2.0?
package require struct::tree
package require struct::list
[__::fileutil::magic::cgen::2tree__ *script*](#1)
[__::fileutil::magic::cgen::treedump__ *tree*](#2)
[__::fileutil::magic::cgen::treegen__ *tree* *node*](#3)
# <a name='description'></a>DESCRIPTION
This package provides the generator backend for a compiler of magic(5) files
into recognizers based on the __[fileutil::magic::rt](rtcore.md)__ recognizer
runtime package. For the compiler frontend using this generator see the package
__[fileutil::magic::cfront](cfront.md)__.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::fileutil::magic::cgen::2tree__ *script*
This command converts the recognizer specified by the *script* into a tree
and returns the object command of that tree as its result. It uses the
package __[struct::tree](../struct/struct_tree.md)__ for the tree.
The *script* is in the format specified by magic(5).
- <a name='2'></a>__::fileutil::magic::cgen::treedump__ *tree*
This command takes a *tree* as generated by
__::fileutil::magic::cgen::2tree__ and returns a string encoding the tree
for human consumption, to aid in debugging.
- <a name='3'></a>__::fileutil::magic::cgen::treegen__ *tree* *node*
This command takes a *tree* as generated by
__::fileutil::magic::cgen::2tree__ and returns a Tcl script, the recognizer
for the file types represented by the sub-tree rooted at the *node*. The
generated script makes extensive use of the commands provided by the
recognizer runtime package __[fileutil::magic::rt](rtcore.md)__ to perform
its duties.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil :: magic* 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.
# <a name='see-also'></a>SEE ALSO
file(1), [fileutil](../fileutil/fileutil.md), magic(5)
# <a name='keywords'></a>KEYWORDS
[file recognition](../../../../index.md#file_recognition), [file
type](../../../../index.md#file_type), [file
utilities](../../../../index.md#file_utilities),
[mime](../../../../index.md#mime), [type](../../../../index.md#type)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/fumagic/filetypes.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
[//000000001]: # (fileutil::magic::filetype - file utilities)
[//000000002]: # (Generated from file 'filetypes.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::magic::filetype(n) 2.0 tcllib "file utilities")
# NAME
fileutil::magic::filetype - Procedures implementing file-type recognition
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [REFERENCES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require fileutil::magic::filetype ?2.0?
[__::fileutil::magic::filetype__ *filename*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a command for the recognition of file types in pure Tcl.
The core part of the recognizer was generated from a "magic(5)" file containing
the checks to perform to recognize files, and associated file-types.
*Beware!* This recognizer is large, about 752 Kilobyte of generated Tcl code.
- <a name='1'></a>__::fileutil::magic::filetype__ *filename*
This command is similar to the command __fileutil::fileType__.
Returns a list containing a list of descriptions, a list of mimetype
components, and a list file extensions. Returns an empty string if the file
content is not recognized.
# <a name='section2'></a>REFERENCES
1. [File(1) sources](ftp://ftp.astron.com/pub/file/) This site contains the
current sources for the file command, including the magic definitions used
by it. The latter were used by us to generate this recognizer.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil :: magic* 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.
# <a name='see-also'></a>SEE ALSO
file(1), [fileutil](../fileutil/fileutil.md), magic(5)
# <a name='keywords'></a>KEYWORDS
[file recognition](../../../../index.md#file_recognition), [file
type](../../../../index.md#file_type), [file
utilities](../../../../index.md#file_utilities),
[type](../../../../index.md#type)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/fumagic/rtcore.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
|
[//000000001]: # (fileutil::magic::rt - file utilities)
[//000000002]: # (Generated from file 'rtcore.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::magic::rt(n) 2.0 tcllib "file utilities")
# NAME
fileutil::magic::rt - Runtime core for file type recognition engines written in
pure Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [NUMERIC TYPES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require fileutil::magic::rt ?2.0?
[__::fileutil::magic::rt::>__](#1)
[__::fileutil::magic::rt::<__](#2)
[__::fileutil::magic::rt::open__ *filename*](#3)
[__::fileutil::magic::rt::close__](#4)
[__::fileutil::magic::rt::file_start__ *name*](#5)
[__::fileutil::magic::rt::result__ ?*msg*?](#6)
[__::fileutil::magic::rt::resultv__ ?*msg*?](#7)
[__::fileutil::magic::rt::emit__ *msg*](#8)
[__::fileutil::magic::rt::offset__ *where*](#9)
[__::fileutil::magic::rt::Nv__ *type* *offset* ?*qual*?](#10)
[__::fileutil::magic::rt::N__ *type* *offset* *comp* *val* ?*qual*?](#11)
[__::fileutil::magic::rt::Nvx__ *type* *offset* ?*qual*?](#12)
[__::fileutil::magic::rt::Nx__ *type* *offset* *comp* *val* ?*qual*?](#13)
[__::fileutil::magic::rt::S__ *offset* *comp* *val* ?*qual*?](#14)
[__::fileutil::magic::rt::Sx__ *offset* *comp* *val* ?*qual*?](#15)
[__::fileutil::magic::rt::L__ *newlevel*](#16)
[__::fileutil::magic::rt::I__ *base* *type* *delta*](#17)
[__::fileutil::magic::rt::R__ *offset*](#18)
[__::fileutil::magic::rt::U__ *fileindex* *name*](#19)
# <a name='description'></a>DESCRIPTION
This package provides the runtime core for file type recognition engines written
in pure Tcl and is thus used by all other packages in this module, i.e. the two
frontend packages __fileutil::magic::mimetypes__ and
__fileutil::magic::filetypes__, and the two engine compiler packages
__[fileutil::magic::cgen](cgen.md)__ and
__[fileutil::magic::cfront](cfront.md)__.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::fileutil::magic::rt::>__
Shorthand for __incr level__.
- <a name='2'></a>__::fileutil::magic::rt::<__
Shorthand for __incr level -1__.
- <a name='3'></a>__::fileutil::magic::rt::open__ *filename*
This command initializes the runtime and prepares the file *filename* for
use by the system. This command has to be invoked first, before any other
command of this package.
The command returns the channel handle of the opened file as its result.
- <a name='4'></a>__::fileutil::magic::rt::close__
This command closes the last file opened via __::fileutil::magic::rt::open__
and shuts the runtime down. This command has to be invoked last, after the
file has been dealt with completely. Afterward another invokation of
__::fileutil::magic::rt::open__ is required to process another file.
This command returns the empty string as its result.
- <a name='5'></a>__::fileutil::magic::rt::file_start__ *name*
This command marks the start of a magic file when debugging. It returns the
empty string as its result.
- <a name='6'></a>__::fileutil::magic::rt::result__ ?*msg*?
This command returns the current result and stops processing.
If *msg* is specified its text is added to the result before it is returned.
See __::fileutil::magic::rt::emit__ for the allowed special character
sequences.
- <a name='7'></a>__::fileutil::magic::rt::resultv__ ?*msg*?
This command returns the current result. In contrast to
__::fileutil::magic::rt::result__ processing continues.
If *msg* is specified its text is added to the result before it is returned.
See __::fileutil::magic::rt::emit__ for the allowed special character
sequences.
- <a name='8'></a>__::fileutil::magic::rt::emit__ *msg*
This command adds the text *msg* to the result buffer. The message may
contain the following special character sequences. They will be replaced
with buffered values before the message is added to the result. The command
returns the empty string as its result.
* __\b__
This sequence is removed
* __%s__
Replaced with the last buffered string value.
* __%ld__
Replaced with the last buffered numeric value.
* __%d__
See above.
- <a name='9'></a>__::fileutil::magic::rt::offset__ *where*
- <a name='10'></a>__::fileutil::magic::rt::Nv__ *type* *offset* ?*qual*?
This command fetches the numeric value with *type* from the absolute
location *offset* and returns it as its result. The fetched value is further
stored in the numeric buffer.
If *qual* is specified it is considered to be a mask and applied to the
fetched value before it is stored and returned. It has to have the form of a
partial Tcl bit-wise expression, i.e.
& number
For example:
Nv lelong 0 &0x8080ffff
For the possible types see section [NUMERIC TYPES](#section3).
- <a name='11'></a>__::fileutil::magic::rt::N__ *type* *offset* *comp* *val* ?*qual*?
This command behaves mostly like __::fileutil::magic::rt::Nv__, except that
it compares the fetched and masked value against *val* as specified with
*comp* and returns the result of that comparison.
The argument *comp* has to contain one of Tcl's comparison operators, and
the comparison made will be
<val> <comp> <fetched-and-masked-value>
The special comparison operator __x__ signals that no comparison should be
done, or, in other words, that the fetched value will always match *val*.
- <a name='12'></a>__::fileutil::magic::rt::Nvx__ *type* *offset* ?*qual*?
This command behaves like __::fileutil::magic::rt::Nv__, except that it
additionally remembers the location in the file after the fetch in the
calling context, for the current level, for later use by
__::fileutil::magic::rt::R__.
- <a name='13'></a>__::fileutil::magic::rt::Nx__ *type* *offset* *comp* *val* ?*qual*?
This command behaves like __::fileutil::magic::rt::N__, except that it
additionally remembers the location in the file after the fetch in the
calling context, for the current, for later use by
__::fileutil::magic::rt::R__.
- <a name='14'></a>__::fileutil::magic::rt::S__ *offset* *comp* *val* ?*qual*?
This command behaves like __::fileutil::magic::rt::N__, except that it
fetches and compares strings, not numeric data. The fetched value is also
stored in the internal string buffer instead of the numeric buffer.
- <a name='15'></a>__::fileutil::magic::rt::Sx__ *offset* *comp* *val* ?*qual*?
This command behaves like __::fileutil::magic::rt::S__, except that it
additionally remembers the location in the file after the fetch in the
calling context, for the current level, for later use by
__::fileutil::magic::rt::R__.
- <a name='16'></a>__::fileutil::magic::rt::L__ *newlevel*
This command sets the current level in the calling context to *newlevel*.
The command returns the empty string as its result.
- <a name='17'></a>__::fileutil::magic::rt::I__ *base* *type* *delta*
This command handles base locations specified indirectly through the
contents of the inspected file. It returns the sum of *delta* and the value
of numeric *type* fetched from the absolute location *base*.
For the possible types see section [NUMERIC TYPES](#section3).
- <a name='18'></a>__::fileutil::magic::rt::R__ *offset*
This command handles base locations specified relative to the end of the
last field one level above.
In other words, the command computes an absolute location in the file based
on the relative *offset* and returns it as its result. The base the offset
is added to is the last location remembered for the level in the calling
context.
- <a name='19'></a>__::fileutil::magic::rt::U__ *fileindex* *name*
Use a named test script at the current level.
# <a name='section3'></a>NUMERIC TYPES
- __byte__
8-bit integer
- __short__
16-bit integer, stored in native endianess
- __beshort__
see above, stored in big endian
- __leshort__
see above, stored in small/little endian
- __long__
32-bit integer, stored in native endianess
- __belong__
see above, stored in big endian
- __lelong__
see above, stored in small/little endian
All of the types above exit in an unsigned form as well. The type names are the
same, with the character "u" added as prefix.
- __date__
32-bit integer timestamp, stored in native endianess
- __bedate__
see above, stored in big endian
- __ledate__
see above, stored in small/little endian
- __ldate__
32-bit integer timestamp, stored in native endianess
- __beldate__
see above, stored in big endian
- __leldate__
see above, stored in small/little endian
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *fileutil :: magic* 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.
# <a name='see-also'></a>SEE ALSO
file(1), [fileutil](../fileutil/fileutil.md), magic(5)
# <a name='keywords'></a>KEYWORDS
[file recognition](../../../../index.md#file_recognition), [file
type](../../../../index.md#file_type), [file
utilities](../../../../index.md#file_utilities),
[mime](../../../../index.md#mime), [type](../../../../index.md#type)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/generator/generator.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
|
[//000000001]: # (generator - Tcl Generator Commands)
[//000000002]: # (Generated from file 'generator.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (generator(n) 0.1 tcllib "Tcl Generator Commands")
# NAME
generator - Procedures for creating and using generators.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PRELUDE](#section3)
- [BUGS, IDEAS, FEEDBACK](#section4)
- [Keywords](#keywords)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require generator ?0.1?
[__generator__ __define__ *name* *params* *body*](#1)
[__generator__ __yield__ *arg* ?*args..*?](#2)
[__generator__ __foreach__ *varList* *generator* *varList* *generator* ?...? *body*](#3)
[__generator__ __next__ *generator* ?*varName..*?](#4)
[__generator__ __exists__ *generator*](#5)
[__generator__ __names__](#6)
[__generator__ __destroy__ ?*generator..*?](#7)
[__generator__ __finally__ *cmd* ?*arg..*?](#8)
[__generator__ __from__ *format* *value*](#9)
[__generator__ __to__ *format* *generator*](#10)
[__generator__ __map__ *function* *generator*](#11)
[__generator__ __filter__ *predicate* *generator*](#12)
[__generator__ __reduce__ *function* *zero* *generator*](#13)
[__generator__ __foldl__ *function* *zero* *generator*](#14)
[__generator__ __foldr__ *function* *zero* *generator*](#15)
[__generator__ __all__ *predicate* *generator*](#16)
[__generator__ __and__ *generator*](#17)
[__generator__ __any__ *generator*](#18)
[__generator__ __concat__ *generator* ?*generator..*?](#19)
[__generator__ __concatMap__ *function* *generator*](#20)
[__generator__ __drop__ *n* *generator*](#21)
[__generator__ __dropWhile__ *predicate* *generator*](#22)
[__generator__ __contains__ *element* *generator*](#23)
[__generator__ __foldl1__ *function* *generator*](#24)
[__generator__ __foldli__ *function* *zero* *generator*](#25)
[__generator__ __foldri__ *function* *zero* *generator*](#26)
[__generator__ __head__ *generator*](#27)
[__generator__ __tail__ *generator*](#28)
[__generator__ __init__ *generator*](#29)
[__generator__ __takeList__ *n* *generator*](#30)
[__generator__ __take__ *n* *generator*](#31)
[__generator__ __iterate__ *function* *init*](#32)
[__generator__ __last__ *generator*](#33)
[__generator__ __length__ *generator*](#34)
[__generator__ __or__ *predicate* *generator*](#35)
[__generator__ __product__ *generator*](#36)
[__generator__ __repeat__ *n* *value..*](#37)
[__generator__ __sum__ *generator*](#38)
[__generator__ __takeWhile__ *predicate* *generator*](#39)
[__generator__ __splitWhen__ *predicate* *generator*](#40)
[__generator__ __scanl__ *function* *zero* *generator*](#41)
# <a name='description'></a>DESCRIPTION
The __generator__ package provides commands to define and iterate over generator
expressions. A *generator* is a command that returns a sequence of values.
However, unlike an ordinary command that returns a list, a generator *yields*
each value and then suspends, allowing subsequent values to be fetched
on-demand. As such, generators can be used to efficiently iterate over a set of
values, without having to generate all answers in-memory. Generators can be used
to iterate over elements of a data structure, or rows in the result set of a
database query, or to decouple producer/consumer software designs such as
parsers and tokenizers, or to implement sophisticated custom control strategies
such as backtracking search. Generators reduce the need to implement custom
control structures, as many such structures can be recast as generators, leading
to both a simpler implementation and a more standardised interface. The
generator mechanism is built on top of the Tcl 8.6 coroutine mechanism.
The package exports a single ensemble command, __generator__. All functionality
is provided as subcommands of this command. The core subcommands of the package
are __define__, __yield__, and __foreach__. The __define__ command works like
Tcl's __[proc](../../../../index.md#proc)__ command, but creates a generator
procedure; that is, a procedure that returns a generator when called. The
generator itself is a command that can be called multiple times: each time it
returns the next value in the generated series. When the series has been
exhausted, the generator command returns an empty list and then destroys itself.
Rather than manually call a generator, however, the package also provides a
flexible __foreach__ command that loops through the values of one or more
generators. This loop construct mimicks the functionality of the built-in Tcl
__[foreach](../../../../index.md#foreach)__ command, including handling multiple
return values and looping over multiple generators at once. Writing a generator
is also a simple task, much like writing a normal procedure: simply use the
__define__ command to define the generator, and then call __yield__ instead of
__[return](../../../../index.md#return)__. For example, we can define a
generator for looping through the integers in a particular range:
generator define range {n m} {
for {set i $n} {$i <= $m} {incr i} { generator yield $i }
}
generator foreach x [range 1 10] {
puts "x = $x"
}
The above example will print the numbers from 1 to 10 in sequence, as you would
expect. The difference from a normal loop over a list is that the numbers are
only generated as they are needed. If we insert a break into the loop then any
remaining numbers in the sequence would never be generated. To illustrate, we
can define a generator that produces the sequence of natural numbers: an
infinite series. A normal procedure would never return trying to produce this
series as a list. By using a generator we only have to generate those values
which are actually used:
generator define nats {} {
while 1 { generator yield [incr nat] }
}
generator foreach n [nats] {
if {$n > 100} { break }
}
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__generator__ __define__ *name* *params* *body*
Creates a new generator procedure. The arguments to the command are
identical to those for __[proc](../../../../index.md#proc)__: a *name*, a
list of parameters, and a body. The parameter list format is identical to a
procedure. In particular, default values and the ?args? syntax can be used
as usual. Each time the resulting generator procedure is called it creates a
new generator command (coroutine) that will yield a list of values on each
call. Each result from a generator is guaranteed to be a non-empty list of
values. When a generator is exhausted it returns an empty list and then
destroys itself to free up resources. It is an error to attempt to call an
exhausted generator as the command no longer exists.
- <a name='2'></a>__generator__ __yield__ *arg* ?*args..*?
Used in the definition of a generator, this command returns the next set of
values to the consumer. Once the __yield__ command has been called the
generator will suspend to allow the consumer to process that value. When the
next value is requested, the generator will resume as if the yield command
had just returned, and can continue processing to yield the next result. The
__yield__ command must be called with at least one argument, but can be
called with multiple arguments, in which case this is equivalent to calling
__yield__ once for each argument.
- <a name='3'></a>__generator__ __foreach__ *varList* *generator* *varList* *generator* ?...? *body*
Loops through one or more generators, assigning the next values to variables
and then executing the loop body. Works much like the built-in
__[foreach](../../../../index.md#foreach)__ command, but working with
generators rather than lists. Multiple generators can be iterated over in
parallel, and multiple results can be retrieved from a single generator at
once. Like the built-in __[foreach](../../../../index.md#foreach)__, the
loop will continue until all of the generators have been exhausted:
variables for generators that are exhausted early will be set to the empty
string.
The __foreach__ command will automatically clean-up all of the generators at
the end of the loop, regardless of whether the loop terminated early or not.
This behaviour is provided as a convenience to avoid having to explicitly
clean up a generator in the usual cases. Generators can however be destroyed
before the end of the loop, in which case the loop will continue as normal
until all the other generators have been destroyed or exhausted.
The __foreach__ command does not take a snapshot of the generator. Any
changes in the state of the generator made inside the loop or by other code
will affect the state of the loop. In particular, if the code in the loop
invokes the generator to manually retrieve the next element, this element
will then be excluded from the loop, and the next iteration will continue
from the element after that one. Care should be taken to avoid concurrent
updates to generators unless this behaviour is required (e.g., in argument
processing).
- <a name='4'></a>__generator__ __next__ *generator* ?*varName..*?
Manually retrieves the next values from a generator. One value is retrieved
for each variable supplied and assigned to the corresponding variable. If
the generator becomes exhausted at any time then any remaining variables are
set to the empty string.
- <a name='5'></a>__generator__ __exists__ *generator*
Returns 1 if the generator (still) exists, or 0 otherwise.
- <a name='6'></a>__generator__ __names__
Returns a list of all currently existing generator commands.
- <a name='7'></a>__generator__ __destroy__ ?*generator..*?
Destroys one or more generators, freeing any associated resources.
- <a name='8'></a>__generator__ __finally__ *cmd* ?*arg..*?
Used in the definition of a generator procedure, this command arranges for a
resource to be cleaned up whenever the generator is destroyed, either
explicitly or implicitly when the generator is exhausted. This command can
be used like a __finally__ block in the __[try](../try/tcllib_try.md)__
command, except that it is tied to the life-cycle of the generator rather
than to a particular scope. For example, if we create a generator to iterate
over the lines in a text file, we can use __finally__ to ensure that the
file is closed whenever the generator is destroyed:
generator define lines file {
set in [open $file]
# Ensure file is always closed
generator finally close $in
while {[gets $in line] >= 0} {
generator yield $line
}
}
generator foreach line [lines /etc/passwd] {
puts "[incr count]: $line"
if {$count > 10} { break }
}
# File will be closed even on early exit
If you create a generator that consumes another generator (such as the
standard __map__ and __filter__ generators defined later), then you should
use a __finally__ command to ensure that this generator is destroyed when
its parent is. For example, the __map__ generator is defined as follows:
generator define map {f xs} {
generator finally generator destroy $xs
generator foreach x $xs { generator yield [{*}$f $x] }
}
- <a name='9'></a>__generator__ __from__ *format* *value*
Creates a generator from a data structure. Currently, supported formats are
__list__, __dict__, or __string__. The list format yields each element in
turn. For dictionaries, each key and value are yielded separately. Finally,
strings are yielded a character at a time.
- <a name='10'></a>__generator__ __to__ *format* *generator*
Converts a generator into a data structure. This is the reverse operation of
the __from__ command, and supports the same data structures. The two
operations obey the following identity laws (where __=__ is interpreted
appropriately):
[generator to $fmt [generator from $fmt $value]] = $value
[generator from $fmt [generator to $fmt $gen]] = $gen
# <a name='section3'></a>PRELUDE
The following commands are provided as a standard library of generator
combinators and functions that perform convenience operations on generators. The
functions in this section are loosely modelled on the equivalent functions from
the Haskell Prelude. *Warning:* most of the functions in this prelude destroy
any generator arguments they are passed as a side-effect. If you want to have
persistent generators, see the streams library.
- <a name='11'></a>__generator__ __map__ *function* *generator*
Apply a function to every element of a generator, returning a new generator
of the results. This is the classic map function from functional
programming, applied to generators. For example, we can generate all the
square numbers using the following code (where __nats__ is defined as
earlier):
proc square x { expr {$x * $x} }
generator foreach n [generator map square [nats]] {
puts "n = $n"
if {$n > 1000} { break }
}
- <a name='12'></a>__generator__ __filter__ *predicate* *generator*
Another classic functional programming gem. This command returns a generator
that yields only those items from the argument generator that satisfy the
predicate (boolean function). For example, if we had a generator
__employees__ that returned a stream of dictionaries representing people, we
could filter all those whose salaries are above 100,000 dollars (or
whichever currency you prefer) using a simple filter:
proc salary> {amount person} { expr {[dict get $person salary] > $amount} }
set fat-cats [generator filter {salary> 100000} $employees]
- <a name='13'></a>__generator__ __reduce__ *function* *zero* *generator*
This is the classic left-fold operation. This command takes a function, an
initial value, and a generator of values. For each element in the generator
it applies the function to the current accumulator value (the *zero*
argument initially) and that element, and then uses the result as the new
accumulator value. This process is repeated through the entire generator
(eagerly) and the final accumulator value is then returned. If we consider
the function to be a binary operator, and the zero argument to be the left
identity element of that operation, then we can consider the __reduce__
command as *folding* the operator between each successive pair of values in
the generator in a left-associative fashion. For example, the sum of a
sequence of numbers can be calculated by folding a __+__ operator between
them, with 0 as the identity:
# sum xs = reduce + 0 xs
# sum [range 1 5] = reduce + 0 [range 1 5]
# = reduce + [+ 0 1] [range 2 5]
# = reduce + [+ 1 2] [range 3 5]
# = ...
# = reduce + [+ 10 5] <empty>
# = ((((0+1)+2)+3)+4)+5
# = 15
proc + {a b} { expr {$a + $b} }
proc sum gen { generator reduce + 0 $gen }
puts [sum [range 1 10]]
The __reduce__ operation is an extremely useful one, and a great variety of
different operations can be defined using it. For example, we can define a
factorial function as the product of a range using generators. This
definition is both very clear and also quite efficient (in both memory and
running time):
proc * {x y} { expr {$x * $y} }
proc prod gen { generator reduce * 0 $gen }
proc fac n { prod [range 1 $n] }
However, while the __reduce__ operation is efficient for finite generators,
care should be taken not to apply it to an infinite generator, as this will
result in an infinite loop:
sum [nats]; # Never returns
- <a name='14'></a>__generator__ __foldl__ *function* *zero* *generator*
This is an alias for the __reduce__ command.
- <a name='15'></a>__generator__ __foldr__ *function* *zero* *generator*
This is the right-associative version of __reduce__. This operation is
generally inefficient, as the entire generator needs to be evaluated into
memory (as a list) before the reduction can commence. In an eagerly
evaluated language like Tcl, this operation has limited use, and should be
avoided if possible.
- <a name='16'></a>__generator__ __all__ *predicate* *generator*
Returns true if all elements of the generator satisfy the given predicate.
- <a name='17'></a>__generator__ __and__ *generator*
Returns true if all elements of the generator are true (i.e., takes the
logical conjunction of the elements).
- <a name='18'></a>__generator__ __any__ *generator*
Returns true if any of the elements of the generator are true (i.e., logical
disjunction).
- <a name='19'></a>__generator__ __concat__ *generator* ?*generator..*?
Returns a generator which is the concatenation of each of the argument
generators.
- <a name='20'></a>__generator__ __concatMap__ *function* *generator*
Given a function which maps a value to a series of values, and a generator
of values of that type, returns a generator of all of the results in one
flat series. Equivalent to __concat__ applied to the result of __map__.
- <a name='21'></a>__generator__ __drop__ *n* *generator*
Removes the given number of elements from the front of the generator and
returns the resulting generator with those elements removed.
- <a name='22'></a>__generator__ __dropWhile__ *predicate* *generator*
Removes all elements from the front of the generator that satisfy the
predicate.
- <a name='23'></a>__generator__ __contains__ *element* *generator*
Returns true if the generator contains the given element. Note that this
will destroy the generator!
- <a name='24'></a>__generator__ __foldl1__ *function* *generator*
A version of __foldl__ that takes the *zero* argument from the first element
of the generator. Therefore this function is only valid on non-empty
generators.
- <a name='25'></a>__generator__ __foldli__ *function* *zero* *generator*
A version of __foldl__ that supplies the integer index of each element as
the first argument to the function. The first element in the generator at
this point is given index 0.
- <a name='26'></a>__generator__ __foldri__ *function* *zero* *generator*
Right-associative version of __foldli__.
- <a name='27'></a>__generator__ __head__ *generator*
Returns the first element of the generator.
- <a name='28'></a>__generator__ __tail__ *generator*
Removes the first element of the generator, returning the rest.
- <a name='29'></a>__generator__ __init__ *generator*
Returns a new generator consisting of all elements except the last of the
argument generator.
- <a name='30'></a>__generator__ __takeList__ *n* *generator*
Returns the next *n* elements of the generator as a list. If not enough
elements are left in the generator, then just the remaining elements are
returned.
- <a name='31'></a>__generator__ __take__ *n* *generator*
Returns the next *n* elements of the generator as a new generator. The old
generator is destroyed.
- <a name='32'></a>__generator__ __iterate__ *function* *init*
Returns an infinite generator formed by repeatedly applying the function to
the initial argument. For example, the Fibonacci numbers can be defined as
follows:
proc fst pair { lindex $pair 0 }
proc snd pair { lindex $pair 1 }
proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] }
proc fibs {} { generator map fst [generator iterate nextFib {0 1}] }
- <a name='33'></a>__generator__ __last__ *generator*
Returns the last element of the generator (if it exists).
- <a name='34'></a>__generator__ __length__ *generator*
Returns the length of the generator, destroying it in the process.
- <a name='35'></a>__generator__ __or__ *predicate* *generator*
Returns 1 if any of the elements of the generator satisfy the predicate.
- <a name='36'></a>__generator__ __product__ *generator*
Returns the product of the numbers in a generator.
- <a name='37'></a>__generator__ __repeat__ *n* *value..*
Returns a generator that consists of *n* copies of the given elements. The
special value *Inf* can be used to generate an infinite sequence.
- <a name='38'></a>__generator__ __sum__ *generator*
Returns the sum of the values in the generator.
- <a name='39'></a>__generator__ __takeWhile__ *predicate* *generator*
Returns a generator of the first elements in the argument generator that
satisfy the predicate.
- <a name='40'></a>__generator__ __splitWhen__ *predicate* *generator*
Splits the generator into lists of elements using the predicate to identify
delimiters. The resulting lists are returned as a generator. Elements
matching the delimiter predicate are discarded. For example, to split up a
generator using the string "|" as a delimiter:
set xs [generator from list {a | b | c}]
generator split {string equal "|"} $xs ;# returns a then b then c
- <a name='41'></a>__generator__ __scanl__ *function* *zero* *generator*
Similar to __foldl__, but returns a generator of all of the intermediate
values for the accumulator argument. The final element of this generator is
equivalent to __foldl__ called on the same arguments.
# <a name='section4'></a>BUGS, IDEAS, FEEDBACK
Please report any errors in this document, or in the package it describes, to
[Neil Madden](mailto:[email protected]).
# <a name='keywords'></a>KEYWORDS
[control structure](../../../../index.md#control_structure),
[coroutine](../../../../index.md#coroutine),
[filter](../../../../index.md#filter), [foldl](../../../../index.md#foldl),
[foldr](../../../../index.md#foldr), [foreach](../../../../index.md#foreach),
[generator](../../../../index.md#generator),
[iterator](../../../../index.md#iterator), [map](../../../../index.md#map),
[reduce](../../../../index.md#reduce), [scanl](../../../../index.md#scanl)
|
Added embedded/md/tcllib/files/modules/gpx/gpx.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
[//000000001]: # (gpx - GPS eXchange Format (GPX))
[//000000002]: # (Generated from file 'gpx.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (gpx(n) 0.9 tcllib "GPS eXchange Format (GPX)")
# NAME
gpx - Extracts waypoints, tracks and routes from GPX files
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [DATA STRUCTURES](#section3)
- [EXAMPLE](#section4)
- [REFERENCES](#section5)
- [AUTHOR](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require gpx ?0.9?
[__::gpx::Create__ *gpxFilename* ?*rawXML*?](#1)
[__::gpx::Cleanup__ *token*](#2)
[__::gpx::GetGPXMetadata__ *token*](#3)
[__::gpx::GetWaypointCount__ *token*](#4)
[__::gpx::GetAllWaypoints__ *token*](#5)
[__::gpx::GetTrackCount__ *token*](#6)
[__::gpx::GetTrackMetadata__ *token* *whichTrack*](#7)
[__::gpx::GetTrackPoints__ *token* *whichTrack*](#8)
[__::gpx::GetRouteCount__ *token*](#9)
[__::gpx::GetRouteMetadata__ *token* *whichRoute*](#10)
[__::gpx::GetRoutePoints__ *token* *whichRoute*](#11)
# <a name='description'></a>DESCRIPTION
This module parses and extracts waypoints, tracks, routes and metadata from a
GPX (GPS eXchange) file. Both GPX version 1.0 and 1.1 are supported.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::gpx::Create__ *gpxFilename* ?*rawXML*?
The __::gpx::Create__ is the first command called to process GPX data. It
takes the GPX data from either the *rawXML* parameter if present or from the
contents of *gpxFilename*, and parses it using *tdom*. It returns a token
value that is used by all the other commands.
- <a name='2'></a>__::gpx::Cleanup__ *token*
This procedure cleans up resources associated with *token*. It is *strongly*
recommended that you call this function after you are done with a given GPX
file. Not doing so will result in memory not being freed, and if your app
calls __::gpx::Create__ enough times, the memory leak could cause a
performance hit...or worse.
- <a name='3'></a>__::gpx::GetGPXMetadata__ *token*
This procedure returns a dictionary of the metadata associated with the GPX
data identified by *token*. The format of the metadata dictionary is
described below, but keys *version* and *creator* will always be present.
- <a name='4'></a>__::gpx::GetWaypointCount__ *token*
This procedure returns the number of waypoints defined in the GPX data
identified by *token*.
- <a name='5'></a>__::gpx::GetAllWaypoints__ *token*
This procedure returns the a list of waypoints defined in the GPX data
identified by *token*. The format of each waypoint item is described below.
- <a name='6'></a>__::gpx::GetTrackCount__ *token*
This procedure returns the number of tracks defined in the GPX data
identified by *token*.
- <a name='7'></a>__::gpx::GetTrackMetadata__ *token* *whichTrack*
This procedure returns a dictionary of the metadata associated track number
*whichTrack* (1 based) in the GPX data identified by *token*. The format of
the metadata dictionary is described below.
- <a name='8'></a>__::gpx::GetTrackPoints__ *token* *whichTrack*
The procedure returns a list of track points comprising track number
*whichTrack* (1 based) in the GPX data identified by *token*. The format of
the metadata dictionary is described below.
- <a name='9'></a>__::gpx::GetRouteCount__ *token*
This procedure returns the number of routes defined in the GPX data
identified by *token*.
- <a name='10'></a>__::gpx::GetRouteMetadata__ *token* *whichRoute*
This procedure returns a dictionary of the metadata associated route number
*whichRoute* (1 based) in the GPX data identified by *token*. The format of
the metadata dictionary is described below.
- <a name='11'></a>__::gpx::GetRoutePoints__ *token* *whichRoute*
The procedure returns a list of route points comprising route number
*whichRoute* (1 based) in the GPX data identified by *token*. The format of
the metadata dictionary is described below.
# <a name='section3'></a>DATA STRUCTURES
- metadata dictionary
The metadata associated with either the GPX document, a track, a route, a
waypoint, a track point or route point is returned in a dictionary. The keys
of that dictionary will be whatever optional GPX elements are present. The
value for each key depends on the GPX schema for that element. For example,
the value for a version key will be a string, while for a link key will be a
sub-dictionary with keys *href* and optionally *text* and *type*.
- point item
Each item in a track or route list of points consists of a list of three
elements: *latitude*, *longitude* and *metadata dictionary*. *Latitude* and
*longitude* are decimal numbers. The *metadata dictionary* format is
described above. For points in a track, typically there will always be ele
(elevation) and time metadata keys.
# <a name='section4'></a>EXAMPLE
% set token [::gpx::Create myGpxFile.gpx]
% set version [dict get [::gpx::GetGPXMetadata $token] version]
% set trackCnt [::gpx::GetTrackCount $token]
% set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
% lassign $firstPoint lat lon ptMetadata
% puts "first point in the first track is at $lat, $lon"
% if {[dict exists $ptMetadata ele]} {
puts "at elevation [dict get $ptMetadata ele] meters"
}
% ::gpx::Cleanup $token
# <a name='section5'></a>REFERENCES
1. GPX: the GPS Exchange Format
([http://www.topografix.com/gpx.asp](http://www.topografix.com/gpx.asp))
1. GPX 1.1 Schema Documentation
([http://www.topografix.com/GPX/1/1/](http://www.topografix.com/GPX/1/1/))
1. GPX 1.0 Developer's Manual
([http://www.topografix.com/gpx_manual.asp](http://www.topografix.com/gpx_manual.asp))
# <a name='section6'></a>AUTHOR
Keith Vetter
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *gpx* 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.
# <a name='keywords'></a>KEYWORDS
[gps](../../../../index.md#gps), [gpx](../../../../index.md#gpx)
# <a name='category'></a>CATEGORY
File formats
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010, Keith Vetter <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_aycock/aycock.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
[//000000001]: # (grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl)
[//000000002]: # (Generated from file 'aycock.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::aycock(n) 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl")
# NAME
grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [OBJECT COMMAND](#section3)
- [DESCRIPTION](#section4)
- [EXAMPLE](#section5)
- [KEYWORDS](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require grammar::aycock ?1.0?
[__::aycock::parser__ *grammar* ?__-verbose__?](#1)
[*parserName* __parse__ *symList* *valList* ?*clientData*?](#2)
[*parserName* __destroy__](#3)
[*parserName* __terminals__](#4)
[*parserName* __nonterminals__](#5)
[*parserName* __save__](#6)
# <a name='description'></a>DESCRIPTION
The __grammar::aycock__ package implements a parser generator for the class of
parsers described in John Aycock and R. Nigel Horspool. Practical Earley
Parsing. *The Computer Journal,* *45*(6):620-630, 2002.
[http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254)
# <a name='section2'></a>PROCEDURES
The __grammar::aycock__ package exports the single procedure:
- <a name='1'></a>__::aycock::parser__ *grammar* ?__-verbose__?
Generates a parser for the given *grammar*, and returns its name. If the
optional __-verbose__ flag is given, dumps verbose information relating to
the generated parser to the standard output. The returned parser is an
object that accepts commands as shown in [OBJECT COMMAND](#section3) below.
# <a name='section3'></a>OBJECT COMMAND
- <a name='2'></a>*parserName* __parse__ *symList* *valList* ?*clientData*?
Invokes a parser returned from __::aycock::parser__. *symList* is a list of
grammar symbols representing the terminals in an input string, and *valList*
is a list of their semantic values. The result is the semantic value of the
entire string when parsed.
- <a name='3'></a>*parserName* __destroy__
Destroys a parser constructed by __::aycock::parser__.
- <a name='4'></a>*parserName* __terminals__
Returns a list of terminal symbols that may be presented in the *symList*
argument to the __parse__ object command.
- <a name='5'></a>*parserName* __nonterminals__
Returns a list of nonterminal symbols that were defined in the parser's
grammar.
- <a name='6'></a>*parserName* __save__
Returns a Tcl script that will reconstruct the parser without needing all
the mechanism of the parser generator at run time. The reconstructed parser
depends on a set of commands in the package __grammar::aycock::runtime__,
which is also automatically loaded when the __grammar::aycock__ package is
loaded.
# <a name='section4'></a>DESCRIPTION
The __grammar::aycock::parser__ command accepts a grammar expressed as a Tcl
list. The list must be structured as the concatenation of a set of *rule*s. Each
*rule* comprises a variable number of elements in the list:
- The name of the nonterminal symbol that the rule reduces.
- The literal string, __::=__
- Zero or more names of terminal or nonterminal symbols that comprise the
right-hand-side of the rule.
- Finally, a Tcl script to execute when the rule is reduced. Within the given
script, a variable called _____ contains a list of the semantic values of
the symbols on the right-hand side. The value returned by the script is
expected to be the semantic value of the left-hand side. If the *clientData*
parameter was passed to the __parse__ method, it is available in a variable
called __clientData__. It is permissible for the script to be the empty
string. In this case, the semantic value of the rule will be the same as the
semantic value of the first symbol on the right-hand side. If the right-hand
side is also empty, the semantic value will be the empty string.
Parsing is done with an Earley parser, which is not terribly efficient in speed
or memory consumption, but which deals effectively with ambiguous grammars. For
this reason, the __grammar::aycock__ package is perhaps best adapted to
natural-language processing or the parsing of extraordinarily complex languages
in which ambiguity can be tolerated.
# <a name='section5'></a>EXAMPLE
The following code demonstrates a trivial desk calculator, admitting only __+__,
__*__ and parentheses as its operators. It also shows the format in which the
lexical analyzer is expected to present terminal symbols to the parser.
set p [aycock::parser {
start ::= E {}
E ::= E + T {expr {[lindex $_ 0] + [lindex $_ 2]}}
E ::= T {}
T ::= T * F {expr {[lindex $_ 0] * [lindex $_ 2]}}
T ::= F {}
F ::= NUMBER {}
F ::= ( E ) {lindex $_ 1}
}]
puts [$p parse {( NUMBER + NUMBER ) * ( NUMBER + NUMBER ) } {{} 2 {} 3 {} {} {} 7 {} 1 {}}]
$p destroy
The example, when run, prints __40__.
# <a name='section6'></a>KEYWORDS
Aycock, Earley, Horspool, parser, compiler
# <a name='keywords'></a>KEYWORDS
[ambiguous](../../../../index.md#ambiguous),
[aycock](../../../../index.md#aycock), [earley](../../../../index.md#earley),
[grammar](../../../../index.md#grammar),
[horspool](../../../../index.md#horspool),
[parser](../../../../index.md#parser), [parsing](../../../../index.md#parsing),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 by Kevin B. Kenny <[email protected]>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>
|
Added embedded/md/tcllib/files/modules/grammar_fa/dacceptor.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
[//000000001]: # (grammar::fa::dacceptor - Finite automaton operations and usage)
[//000000002]: # (Generated from file 'dacceptor.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::fa::dacceptor(n) 0.1.1 tcllib "Finite automaton operations and usage")
# NAME
grammar::fa::dacceptor - Create and use deterministic acceptors
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [ACCEPTOR METHODS](#section3)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit
package require struct::set
package require grammar::fa::dacceptor ?0.1.1?
[__::grammar::fa::dacceptor__ *daName* *fa* ?__-any__ *any*?](#1)
[__daName__ *option* ?*arg arg ...*?](#2)
[*daName* __destroy__](#3)
[*daName* __accept?__ *symbols*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a class for acceptors constructed from deterministic
*finite automatons* (DFA). Acceptors are objects which can be given a string of
symbols and tell if the DFA they are constructed from would *accept* that
string. For the actual creation of the DFAs the acceptors are based on we have
the packages __[grammar::fa](fa.md)__ and __[grammar::fa::op](faop.md)__.
# <a name='section2'></a>API
The package exports the API described here.
- <a name='1'></a>__::grammar::fa::dacceptor__ *daName* *fa* ?__-any__ *any*?
Creates a new deterministic acceptor with an associated global Tcl command
whose name is *daName*. This command may be used to invoke various
operations on the acceptor. It has the following general form:
* <a name='2'></a>__daName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. See
section [ACCEPTOR METHODS](#section3) for more explanations.
The acceptor will be based on the deterministic finite automaton stored
in the object *fa*. It will keep a copy of the relevant data of the FA
in its own storage, in a form easy to use for its purposes. This also
means that changes made to the *fa* after the construction of the
acceptor *will not* influence the acceptor.
If *any* has been specified, then the acceptor will convert all symbols
in the input which are unknown to the base FA to that symbol before
proceeding with the processing.
# <a name='section3'></a>ACCEPTOR METHODS
All acceptors provide the following methods for their manipulation:
- <a name='3'></a>*daName* __destroy__
Destroys the automaton, including its storage space and associated command.
- <a name='4'></a>*daName* __accept?__ *symbols*
Takes the list of *symbols* and checks if the FA the acceptor is based on
would accept it. The result is a boolean value. __True__ is returned if the
symbols are accepted, and __False__ otherwise. Note that bogus symbols in
the input are either translated to the *any* symbol (if specified), or cause
the acceptance test to simply fail. No errors will be thrown. The method
will process only just that prefix of the input which is enough to fully
determine (non-)acceptance.
# <a name='section4'></a>EXAMPLES
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_fa* 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.
# <a name='keywords'></a>KEYWORDS
[acceptance](../../../../index.md#acceptance),
[acceptor](../../../../index.md#acceptor),
[automaton](../../../../index.md#automaton), [finite
automaton](../../../../index.md#finite_automaton),
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [regular
expression](../../../../index.md#regular_expression), [regular
grammar](../../../../index.md#regular_grammar), [regular
languages](../../../../index.md#regular_languages),
[state](../../../../index.md#state),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_fa/dexec.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
[//000000001]: # (grammar::fa::dexec - Finite automaton operations and usage)
[//000000002]: # (Generated from file 'dexec.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::fa::dexec(n) 0.2 tcllib "Finite automaton operations and usage")
# NAME
grammar::fa::dexec - Execute deterministic finite automatons
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [EXECUTOR METHODS](#section3)
- [EXECUTOR CALLBACK](#section4)
- [EXAMPLES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit
package require grammar::fa::dexec ?0.2?
[__::grammar::fa::dexec__ *daName* *fa* ?__-any__ *any*? ?__-command__ *cmdprefix*?](#1)
[__daName__ *option* ?*arg arg ...*?](#2)
[*daName* __destroy__](#3)
[*daName* __put__ *symbol*](#4)
[*daName* __reset__](#5)
[*daName* __state__](#6)
[*cmdprefix* __error__ *code* *message*](#7)
[*cmdprefix* __final__ *stateid*](#8)
[*cmdprefix* __reset__](#9)
[*cmdprefix* __state__ *stateid*](#10)
# <a name='description'></a>DESCRIPTION
This package provides a class for executors constructed from deterministic
*finite automatons* (DFA). Executors are objects which are given a string of
symbols in a piecemal fashion, perform state transitions and report back when
they enter a final state, or find an error in the input. For the actual creation
of the DFAs the executors are based on we have the packages
__[grammar::fa](fa.md)__ and __[grammar::fa::op](faop.md)__.
The objects follow a push model. Symbols are pushed into the executor, and when
something important happens, i.e. error occurs, a state transition, or a final
state is entered this will be reported via the callback specified via the option
__-command__. Note that conversion of this into a pull model where the
environment retrieves messages from the object and the object uses a callback to
ask for more symbols is a trivial thing.
*Side note*: The acceptor objects provided by
__[grammar::fa::dacceptor](dacceptor.md)__ could have been implemented on top of
the executors provided here, but were not, to get a bit more performance (we
avoid a number of method calls and the time required for their dispatch).
# <a name='section2'></a>API
The package exports the API described here.
- <a name='1'></a>__::grammar::fa::dexec__ *daName* *fa* ?__-any__ *any*? ?__-command__ *cmdprefix*?
Creates a new deterministic executor with an associated global Tcl command
whose name is *daName*. This command may be used to invoke various
operations on the executor. It has the following general form:
* <a name='2'></a>__daName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. See
section [EXECUTOR METHODS](#section3) for more explanations.
The executor will be based on the deterministic finite automaton stored
in the object *fa*. It will keep a copy of the relevant data of the FA
in its own storage, in a form easy to use for its purposes. This also
means that changes made to the *fa* after the construction of the
executor *will not* influence the executor.
If *any* has been specified, then the executor will convert all symbols
in the input which are unknown to the base FA to that symbol before
proceeding with the processing.
# <a name='section3'></a>EXECUTOR METHODS
All executors provide the following methods for their manipulation:
- <a name='3'></a>*daName* __destroy__
Destroys the automaton, including its storage space and associated command.
- <a name='4'></a>*daName* __put__ *symbol*
Takes the current state of the executor and the *symbol* and performs the
appropriate state transition. Reports any errors encountered via the command
callback, as well as entering a final state of the underlying FA.
When an error is reported all further invokations of __put__ will do
nothing, until the error condition has been cleared via an invokation of
method __reset__.
- <a name='5'></a>*daName* __reset__
Unconditionally sets the executor into the start state of the underlying FA.
This also clears any error condition __put__ may have encountered.
- <a name='6'></a>*daName* __state__
Returns the current state of the underlying FA. This allow for introspection
without the need to pass data from the callback command.
# <a name='section4'></a>EXECUTOR CALLBACK
The callback command *cmdprefix* given to an executor via the option
__-command__ will be executed by the object at the global level, using the
syntax described below. Note that *cmdprefix* is not simply the name of a
command, but a full command prefix. In other words it may contain additional
fixed argument words beyond the command word.
- <a name='7'></a>*cmdprefix* __error__ *code* *message*
The executor has encountered an error, and *message* contains a
human-readable text explaining the nature of the problem. The *code* on the
other hand is a fixed machine-readable text. The following error codes can
be generated by executor objects.
* __BADSYM__
An unknown symbol was found in the input. This can happen if and only if
no __-any__ symbol was specified.
* __BADTRANS__
The underlying FA has no transition for the current combination of input
symbol and state. In other words, the executor was not able to compute a
new state for this combination.
- <a name='8'></a>*cmdprefix* __final__ *stateid*
The executor has entered the final state *stateid*.
- <a name='9'></a>*cmdprefix* __reset__
The executor was reset.
- <a name='10'></a>*cmdprefix* __state__ *stateid*
The FA changed state due to a transition. *stateid* is the new state.
# <a name='section5'></a>EXAMPLES
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_fa* 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.
# <a name='keywords'></a>KEYWORDS
[automaton](../../../../index.md#automaton),
[execution](../../../../index.md#execution), [finite
automaton](../../../../index.md#finite_automaton),
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [regular
expression](../../../../index.md#regular_expression), [regular
grammar](../../../../index.md#regular_grammar), [regular
languages](../../../../index.md#regular_languages),
[running](../../../../index.md#running), [state](../../../../index.md#state),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Andreas Kupries <[email protected]>
Copyright © 2007 Bogdan <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_fa/fa.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
|
[//000000001]: # (grammar::fa - Finite automaton operations and usage)
[//000000002]: # (Generated from file 'fa.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::fa(n) 0.4 tcllib "Finite automaton operations and usage")
# NAME
grammar::fa - Create and manipulate finite automatons
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [FA METHODS](#section3)
- [EXAMPLES](#section4)
- [FINITE AUTOMATONS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit 1.3
package require struct::list
package require struct::set
package require grammar::fa::op ?0.2?
package require grammar::fa ?0.4?
[__::grammar::fa__ *faName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*|__fromRegex__ *re* ?*over*??](#1)
[__faName__ *option* ?*arg arg ...*?](#2)
[*faName* __destroy__](#3)
[*faName* __clear__](#4)
[*faName* __=__ *srcFA*](#5)
[*faName* __-->__ *dstFA*](#6)
[*faName* __serialize__](#7)
[*faName* __deserialize__ *serialization*](#8)
[*faName* __states__](#9)
[*faName* __state__ __add__ *s1* ?*s2* ...?](#10)
[*faName* __state__ __delete__ *s1* ?*s2* ...?](#11)
[*faName* __state__ __exists__ *s*](#12)
[*faName* __state__ __rename__ *s* *snew*](#13)
[*faName* __startstates__](#14)
[*faName* __start__ __add__ *s1* ?*s2* ...?](#15)
[*faName* __start__ __remove__ *s1* ?*s2* ...?](#16)
[*faName* __start?__ *s*](#17)
[*faName* __start?set__ *stateset*](#18)
[*faName* __finalstates__](#19)
[*faName* __final__ __add__ *s1* ?*s2* ...?](#20)
[*faName* __final__ __remove__ *s1* ?*s2* ...?](#21)
[*faName* __final?__ *s*](#22)
[*faName* __final?set__ *stateset*](#23)
[*faName* __symbols__](#24)
[*faName* __symbols@__ *s* ?*d*?](#25)
[*faName* __symbols@set__ *stateset*](#26)
[*faName* __symbol__ __add__ *sym1* ?*sym2* ...?](#27)
[*faName* __symbol__ __delete__ *sym1* ?*sym2* ...?](#28)
[*faName* __symbol__ __rename__ *sym* *newsym*](#29)
[*faName* __symbol__ __exists__ *sym*](#30)
[*faName* __next__ *s* *sym* ?__-->__ *next*?](#31)
[*faName* __!next__ *s* *sym* ?__-->__ *next*?](#32)
[*faName* __nextset__ *stateset* *sym*](#33)
[*faName* __is__ __deterministic__](#34)
[*faName* __is__ __complete__](#35)
[*faName* __is__ __useful__](#36)
[*faName* __is__ __epsilon-free__](#37)
[*faName* __reachable_states__](#38)
[*faName* __unreachable_states__](#39)
[*faName* __reachable__ *s*](#40)
[*faName* __useful_states__](#41)
[*faName* __unuseful_states__](#42)
[*faName* __useful__ *s*](#43)
[*faName* __epsilon_closure__ *s*](#44)
[*faName* __reverse__](#45)
[*faName* __complete__](#46)
[*faName* __remove_eps__](#47)
[*faName* __trim__ ?*what*?](#48)
[*faName* __determinize__ ?*mapvar*?](#49)
[*faName* __minimize__ ?*mapvar*?](#50)
[*faName* __complement__](#51)
[*faName* __kleene__](#52)
[*faName* __optional__](#53)
[*faName* __union__ *fa* ?*mapvar*?](#54)
[*faName* __intersect__ *fa* ?*mapvar*?](#55)
[*faName* __difference__ *fa* ?*mapvar*?](#56)
[*faName* __concatenate__ *fa* ?*mapvar*?](#57)
[*faName* __fromRegex__ *regex* ?*over*?](#58)
# <a name='description'></a>DESCRIPTION
This package provides a container class for *finite automatons* (Short: FA). It
allows the incremental definition of the automaton, its manipulation and
querying of the definition. While the package provides complex operations on the
automaton (via package __[grammar::fa::op](faop.md)__), it does not have the
ability to execute a definition for a stream of symbols. Use the packages
__[grammar::fa::dacceptor](dacceptor.md)__ and
__[grammar::fa::dexec](dexec.md)__ for that. Another package related to this is
__grammar::fa::compiler__. It turns a FA into an executor class which has the
definition of the FA hardwired into it. The output of this package is
configurable to suit a large number of different implementation languages and
paradigms.
For more information about what a finite automaton is see section [FINITE
AUTOMATONS](#section5).
# <a name='section2'></a>API
The package exports the API described here.
- <a name='1'></a>__::grammar::fa__ *faName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*|__fromRegex__ *re* ?*over*??
Creates a new finite automaton with an associated global Tcl command whose
name is *faName*. This command may be used to invoke various operations on
the automaton. It has the following general form:
* <a name='2'></a>__faName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. See
section [FA METHODS](#section3) for more explanations. The new automaton
will be empty if no *src* is specified. Otherwise it will contain a copy
of the definition contained in the *src*. The *src* has to be a FA
object reference for all operators except __deserialize__ and
__fromRegex__. The __deserialize__ operator requires *src* to be the
serialization of a FA instead, and __fromRegex__ takes a regular
expression in the form a of a syntax tree. See
__::grammar::fa::op::fromRegex__ for more detail on that.
# <a name='section3'></a>FA METHODS
All automatons provide the following methods for their manipulation:
- <a name='3'></a>*faName* __destroy__
Destroys the automaton, including its storage space and associated command.
- <a name='4'></a>*faName* __clear__
Clears out the definition of the automaton contained in *faName*, but does
*not* destroy the object.
- <a name='5'></a>*faName* __=__ *srcFA*
Assigns the contents of the automaton contained in *srcFA* to *faName*,
overwriting any existing definition. This is the assignment operator for
automatons. It copies the automaton contained in the FA object *srcFA* over
the automaton definition in *faName*. The old contents of *faName* are
deleted by this operation.
This operation is in effect equivalent to
*faName* __deserialize__ [*srcFA* __serialize__]
- <a name='6'></a>*faName* __-->__ *dstFA*
This is the reverse assignment operator for automatons. It copies the
automation contained in the object *faName* over the automaton definition in
the object *dstFA*. The old contents of *dstFA* are deleted by this
operation.
This operation is in effect equivalent to
*dstFA* __deserialize__ [*faName* __serialize__]
- <a name='7'></a>*faName* __serialize__
This method serializes the automaton stored in *faName*. In other words it
returns a tcl *value* completely describing that automaton. This allows, for
example, the transfer of automatons over arbitrary channels, persistence,
etc. This method is also the basis for both the copy constructor and the
assignment operator.
The result of this method has to be semantically identical over all
implementations of the __grammar::fa__ interface. This is what will enable
us to copy automatons between different implementations of the same
interface.
The result is a list of three elements with the following structure:
The constant string __grammar::fa__.
A list containing the names of all known input symbols. The order of
elements in this list is not relevant.
The last item in the list is a dictionary, however the order of the keys is
important as well. The keys are the states of the serialized FA, and their
order is the order in which to create the states when deserializing. This is
relevant to preserve the order relationship between states.
The value of each dictionary entry is a list of three elements describing
the state in more detail.
A boolean flag. If its value is __true__ then the state is a start state,
otherwise it is not.
A boolean flag. If its value is __true__ then the state is a final state,
otherwise it is not.
The last element is a dictionary describing the transitions for the state.
The keys are symbols (or the empty string), and the values are sets of
successor states.
Assuming the following FA (which describes the life of a truck driver in a
very simple way :)
Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
(...) is the start state.
a possible serialization is
grammar::fa \\
{yellow red green red/yellow} \\
{Drive {0 0 {yellow Brake}} \\
Brake {0 0 {red Stop}} \\
Stop {1 0 {red/yellow Attention}} \\
Attention {0 0 {green Drive}}}
A possible one, because I did not care about creation order here
- <a name='8'></a>*faName* __deserialize__ *serialization*
This is the complement to __serialize__. It replaces the automaton
definition in *faName* with the automaton described by the *serialization*
value. The old contents of *faName* are deleted by this operation.
- <a name='9'></a>*faName* __states__
Returns the set of all states known to *faName*.
- <a name='10'></a>*faName* __state__ __add__ *s1* ?*s2* ...?
Adds the states *s1*, *s2*, et cetera to the FA definition in *faName*. The
operation will fail any of the new states is already declared.
- <a name='11'></a>*faName* __state__ __delete__ *s1* ?*s2* ...?
Deletes the state *s1*, *s2*, et cetera, and all associated information from
the FA definition in *faName*. The latter means that the information about
in- or outbound transitions is deleted as well. If the deleted state was a
start or final state then this information is invalidated as well. The
operation will fail if the state *s* is not known to the FA.
- <a name='12'></a>*faName* __state__ __exists__ *s*
A predicate. It tests whether the state *s* is known to the FA in *faName*.
The result is a boolean value. It will be set to __true__ if the state *s*
is known, and __false__ otherwise.
- <a name='13'></a>*faName* __state__ __rename__ *s* *snew*
Renames the state *s* to *snew*. Fails if *s* is not a known state. Also
fails if *snew* is already known as a state.
- <a name='14'></a>*faName* __startstates__
Returns the set of states which are marked as *start* states, also known as
*initial* states. See [FINITE AUTOMATONS](#section5) for explanations what
this means.
- <a name='15'></a>*faName* __start__ __add__ *s1* ?*s2* ...?
Mark the states *s1*, *s2*, et cetera in the FA *faName* as *start* (aka
*initial*).
- <a name='16'></a>*faName* __start__ __remove__ *s1* ?*s2* ...?
Mark the states *s1*, *s2*, et cetera in the FA *faName* as *not start* (aka
*not accepting*).
- <a name='17'></a>*faName* __start?__ *s*
A predicate. It tests if the state *s* in the FA *faName* is *start* or not.
The result is a boolean value. It will be set to __true__ if the state *s*
is *start*, and __false__ otherwise.
- <a name='18'></a>*faName* __start?set__ *stateset*
A predicate. It tests if the set of states *stateset* contains at least one
start state. They operation will fail if the set contains an element which
is not a known state. The result is a boolean value. It will be set to
__true__ if a start state is present in *stateset*, and __false__ otherwise.
- <a name='19'></a>*faName* __finalstates__
Returns the set of states which are marked as
*[final](../../../../index.md#final)* states, also known as *accepting*
states. See [FINITE AUTOMATONS](#section5) for explanations what this means.
- <a name='20'></a>*faName* __final__ __add__ *s1* ?*s2* ...?
Mark the states *s1*, *s2*, et cetera in the FA *faName* as
*[final](../../../../index.md#final)* (aka *accepting*).
- <a name='21'></a>*faName* __final__ __remove__ *s1* ?*s2* ...?
Mark the states *s1*, *s2*, et cetera in the FA *faName* as *not final* (aka
*not accepting*).
- <a name='22'></a>*faName* __final?__ *s*
A predicate. It tests if the state *s* in the FA *faName* is
*[final](../../../../index.md#final)* or not. The result is a boolean value.
It will be set to __true__ if the state *s* is
*[final](../../../../index.md#final)*, and __false__ otherwise.
- <a name='23'></a>*faName* __final?set__ *stateset*
A predicate. It tests if the set of states *stateset* contains at least one
final state. They operation will fail if the set contains an element which
is not a known state. The result is a boolean value. It will be set to
__true__ if a final state is present in *stateset*, and __false__ otherwise.
- <a name='24'></a>*faName* __symbols__
Returns the set of all symbols known to the FA *faName*.
- <a name='25'></a>*faName* __symbols@__ *s* ?*d*?
Returns the set of all symbols for which the state *s* has transitions. If
the empty symbol is present then *s* has epsilon transitions. If two states
are specified the result is the set of symbols which have transitions from
*s* to *t*. This set may be empty if there are no transitions between the
two specified states.
- <a name='26'></a>*faName* __symbols@set__ *stateset*
Returns the set of all symbols for which at least one state in the set of
states *stateset* has transitions. In other words, the union of [*faName*
__symbols@__ __s__] for all states __s__ in *stateset*. If the empty symbol
is present then at least one state contained in *stateset* has epsilon
transitions.
- <a name='27'></a>*faName* __symbol__ __add__ *sym1* ?*sym2* ...?
Adds the symbols *sym1*, *sym2*, et cetera to the FA definition in *faName*.
The operation will fail any of the symbols is already declared. The empty
string is not allowed as a value for the symbols.
- <a name='28'></a>*faName* __symbol__ __delete__ *sym1* ?*sym2* ...?
Deletes the symbols *sym1*, *sym2* et cetera, and all associated information
from the FA definition in *faName*. The latter means that all transitions
using the symbols are deleted as well. The operation will fail if any of the
symbols is not known to the FA.
- <a name='29'></a>*faName* __symbol__ __rename__ *sym* *newsym*
Renames the symbol *sym* to *newsym*. Fails if *sym* is not a known symbol.
Also fails if *newsym* is already known as a symbol.
- <a name='30'></a>*faName* __symbol__ __exists__ *sym*
A predicate. It tests whether the symbol *sym* is known to the FA in
*faName*. The result is a boolean value. It will be set to __true__ if the
symbol *sym* is known, and __false__ otherwise.
- <a name='31'></a>*faName* __next__ *s* *sym* ?__-->__ *next*?
Define or query transition information.
If *next* is specified, then the method will add a transition from the state
*s* to the *successor* state *next* labeled with the symbol *sym* to the FA
contained in *faName*. The operation will fail if *s*, or *next* are not
known states, or if *sym* is not a known symbol. An exception to the latter
is that *sym* is allowed to be the empty string. In that case the new
transition is an *epsilon transition* which will not consume input when
traversed. The operation will also fail if the combination of (*s*, *sym*,
and *next*) is already present in the FA.
If *next* was not specified, then the method will return the set of states
which can be reached from *s* through a single transition labeled with
symbol *sym*.
- <a name='32'></a>*faName* __!next__ *s* *sym* ?__-->__ *next*?
Remove one or more transitions from the Fa in *faName*.
If *next* was specified then the single transition from the state *s* to the
state *next* labeled with the symbol *sym* is removed from the FA. Otherwise
*all* transitions originating in state *s* and labeled with the symbol *sym*
will be removed.
The operation will fail if *s* and/or *next* are not known as states. It
will also fail if a non-empty *sym* is not known as symbol. The empty string
is acceptable, and allows the removal of epsilon transitions.
- <a name='33'></a>*faName* __nextset__ *stateset* *sym*
Returns the set of states which can be reached by a single transition
originating in a state in the set *stateset* and labeled with the symbol
*sym*.
In other words, this is the union of [*faName* next __s__ *symbol*] for all
states __s__ in *stateset*.
- <a name='34'></a>*faName* __is__ __deterministic__
A predicate. It tests whether the FA in *faName* is a deterministic FA or
not. The result is a boolean value. It will be set to __true__ if the FA is
deterministic, and __false__ otherwise.
- <a name='35'></a>*faName* __is__ __complete__
A predicate. It tests whether the FA in *faName* is a complete FA or not. A
FA is complete if it has at least one transition per state and symbol. This
also means that a FA without symbols, or states is also complete. The result
is a boolean value. It will be set to __true__ if the FA is deterministic,
and __false__ otherwise.
Note: When a FA has epsilon-transitions transitions over a symbol for a
state S can be indirect, i.e. not attached directly to S, but to a state in
the epsilon-closure of S. The symbols for such indirect transitions count
when computing completeness.
- <a name='36'></a>*faName* __is__ __useful__
A predicate. It tests whether the FA in *faName* is an useful FA or not. A
FA is useful if all states are *reachable* and *useful*. The result is a
boolean value. It will be set to __true__ if the FA is deterministic, and
__false__ otherwise.
- <a name='37'></a>*faName* __is__ __epsilon-free__
A predicate. It tests whether the FA in *faName* is an epsilon-free FA or
not. A FA is epsilon-free if it has no epsilon transitions. This definition
means that all deterministic FAs are epsilon-free as well, and
epsilon-freeness is a necessary pre-condition for deterministic'ness. The
result is a boolean value. It will be set to __true__ if the FA is
deterministic, and __false__ otherwise.
- <a name='38'></a>*faName* __reachable_states__
Returns the set of states which are reachable from a start state by one or
more transitions.
- <a name='39'></a>*faName* __unreachable_states__
Returns the set of states which are not reachable from any start state by
any number of transitions. This is
[faName states] - [faName reachable_states]
- <a name='40'></a>*faName* __reachable__ *s*
A predicate. It tests whether the state *s* in the FA *faName* can be
reached from a start state by one or more transitions. The result is a
boolean value. It will be set to __true__ if the state can be reached, and
__false__ otherwise.
- <a name='41'></a>*faName* __useful_states__
Returns the set of states which are able to reach a final state by one or
more transitions.
- <a name='42'></a>*faName* __unuseful_states__
Returns the set of states which are not able to reach a final state by any
number of transitions. This is
[faName states] - [faName useful_states]
- <a name='43'></a>*faName* __useful__ *s*
A predicate. It tests whether the state *s* in the FA *faName* is able to
reach a final state by one or more transitions. The result is a boolean
value. It will be set to __true__ if the state is useful, and __false__
otherwise.
- <a name='44'></a>*faName* __epsilon_closure__ *s*
Returns the set of states which are reachable from the state *s* in the FA
*faName* by one or more epsilon transitions, i.e transitions over the empty
symbol, transitions which do not consume input. This is called the *epsilon
closure* of *s*.
- <a name='45'></a>*faName* __reverse__
- <a name='46'></a>*faName* __complete__
- <a name='47'></a>*faName* __remove_eps__
- <a name='48'></a>*faName* __trim__ ?*what*?
- <a name='49'></a>*faName* __determinize__ ?*mapvar*?
- <a name='50'></a>*faName* __minimize__ ?*mapvar*?
- <a name='51'></a>*faName* __complement__
- <a name='52'></a>*faName* __kleene__
- <a name='53'></a>*faName* __optional__
- <a name='54'></a>*faName* __union__ *fa* ?*mapvar*?
- <a name='55'></a>*faName* __intersect__ *fa* ?*mapvar*?
- <a name='56'></a>*faName* __difference__ *fa* ?*mapvar*?
- <a name='57'></a>*faName* __concatenate__ *fa* ?*mapvar*?
- <a name='58'></a>*faName* __fromRegex__ *regex* ?*over*?
These methods provide more complex operations on the FA. Please see the
same-named commands in the package __[grammar::fa::op](faop.md)__ for
descriptions of what they do.
# <a name='section4'></a>EXAMPLES
# <a name='section5'></a>FINITE AUTOMATONS
For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where
- S is a set of *states*,
- Sy a set of *input symbols*,
- St is a subset of S, the set of *start* states, also known as *initial*
states.
- Fi is a subset of S, the set of *[final](../../../../index.md#final)*
states, also known as *accepting*.
- T is a function from S x (Sy + epsilon) to {S}, the *transition function*.
Here __epsilon__ denotes the empty input symbol and is distinct from all
symbols in Sy; and {S} is the set of subsets of S. In other words, T maps a
combination of State and Input (which can be empty) to a set of *successor
states*.
In computer theory a FA is most often shown as a graph where the nodes represent
the states, and the edges between the nodes encode the transition function: For
all n in S' = T (s, sy) we have one edge between the nodes representing s and n
resp., labeled with sy. The start and accepting states are encoded through
distinct visual markers, i.e. they are attributes of the nodes.
FA's are used to process streams of symbols over Sy.
A specific FA is said to *accept* a finite stream sy_1 sy_2 ... sy_n if there is
a path in the graph of the FA beginning at a state in St and ending at a state
in Fi whose edges have the labels sy_1, sy_2, etc. to sy_n. The set of all
strings accepted by the FA is the *language* of the FA. One important
equivalence is that the set of languages which can be accepted by an FA is the
set of *[regular languages](../../../../index.md#regular_languages)*.
Another important concept is that of deterministic FAs. A FA is said to be
*deterministic* if for each string of input symbols there is exactly one path in
the graph of the FA beginning at the start state and whose edges are labeled
with the symbols in the string. While it might seem that non-deterministic FAs
to have more power of recognition, this is not so. For each non-deterministic FA
we can construct a deterministic FA which accepts the same language (-->
Thompson's subset construction).
While one of the premier applications of FAs is in
*[parsing](../../../../index.md#parsing)*, especially in the
*[lexer](../../../../index.md#lexer)* stage (where symbols == characters), this
is not the only possibility by far.
Quite a lot of processes can be modeled as a FA, albeit with a possibly large
set of states. For these the notion of accepting states is often less or not
relevant at all. What is needed instead is the ability to act to state changes
in the FA, i.e. to generate some output in response to the input. This
transforms a FA into a *finite transducer*, which has an additional set OSy of
*output symbols* and also an additional *output function* O which maps from "S x
(Sy + epsilon)" to "(Osy + epsilon)", i.e a combination of state and input,
possibly empty to an output symbol, or nothing.
For the graph representation this means that edges are additional labeled with
the output symbol to write when this edge is traversed while matching input.
Note that for an application "writing an output symbol" can also be "executing
some code".
Transducers are not handled by this package. They will get their own package in
the future.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_fa* 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.
# <a name='keywords'></a>KEYWORDS
[automaton](../../../../index.md#automaton), [finite
automaton](../../../../index.md#finite_automaton),
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [regular
expression](../../../../index.md#regular_expression), [regular
grammar](../../../../index.md#regular_grammar), [regular
languages](../../../../index.md#regular_languages),
[state](../../../../index.md#state),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_fa/faop.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
|
[//000000001]: # (grammar::fa::op - Finite automaton operations and usage)
[//000000002]: # (Generated from file 'faop.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::fa::op(n) 0.4 tcllib "Finite automaton operations and usage")
# NAME
grammar::fa::op - Operations on finite automatons
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [EXAMPLES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit
package require struct::list
package require struct::set
package require grammar::fa::op ?0.4.1?
[__::grammar::fa::op::constructor__ *cmd*](#1)
[__::grammar::fa::op::reverse__ *fa*](#2)
[__::grammar::fa::op::complete__ *fa* ?*sink*?](#3)
[__::grammar::fa::op::remove_eps__ *fa*](#4)
[__::grammar::fa::op::trim__ *fa* ?*what*?](#5)
[__::grammar::fa::op::determinize__ *fa* ?*mapvar*?](#6)
[__::grammar::fa::op::minimize__ *fa* ?*mapvar*?](#7)
[__::grammar::fa::op::complement__ *fa*](#8)
[__::grammar::fa::op::kleene__ *fa*](#9)
[__::grammar::fa::op::optional__ *fa*](#10)
[__::grammar::fa::op::union__ *fa* *fb* ?*mapvar*?](#11)
[__::grammar::fa::op::intersect__ *fa* *fb* ?*mapvar*?](#12)
[__::grammar::fa::op::difference__ *fa* *fb* ?*mapvar*?](#13)
[__::grammar::fa::op::concatenate__ *fa* *fb* ?*mapvar*?](#14)
[__::grammar::fa::op::fromRegex__ *fa* *regex* ?*over*?](#15)
[__::grammar::fa::op::toRegexp__ *fa*](#16)
[__::grammar::fa::op::toRegexp2__ *fa*](#17)
[__::grammar::fa::op::toTclRegexp__ *regexp* *symdict*](#18)
[__::grammar::fa::op::simplifyRegexp__ *regexp*](#19)
# <a name='description'></a>DESCRIPTION
This package provides a number of complex operations on finite automatons
(Short: FA), as provided by the package __[grammar::fa](fa.md)__. The package
does not provide the ability to create and/or manipulate such FAs, nor the
ability to execute a FA for a stream of symbols. Use the packages
__[grammar::fa](fa.md)__ and __grammar::fa::interpreter__ for that. Another
package related to this is __grammar::fa::compiler__ which turns a FA into an
executor class which has the definition of the FA hardwired into it.
For more information about what a finite automaton is see section *FINITE
AUTOMATONS* in package __[grammar::fa](fa.md)__.
# <a name='section2'></a>API
The package exports the API described here. All commands modify their first
argument. I.e. whatever FA they compute is stored back into it. Some of the
operations will construct an automaton whose states are all new, but related to
the states in the source automaton(s). These operations take variable names as
optional arguments where they will store mappings which describe the
relationship(s). The operations can be loosely partitioned into structural and
language operations. The latter are defined in terms of the language the
automaton(s) accept, whereas the former are defined in terms of the structural
properties of the involved automaton(s). Some operations are both. *Structure
operations*
- <a name='1'></a>__::grammar::fa::op::constructor__ *cmd*
This command has to be called by the user of the package before any other
operations is performed, to establish a command which can be used to
construct a FA container object. If this is not done several operations will
fail as they are unable to construct internal and transient containers to
hold state and/or partial results.
Any container class using this package for complex operations should set its
own class command as the constructor. See package __[grammar::fa](fa.md)__
for an example.
- <a name='2'></a>__::grammar::fa::op::reverse__ *fa*
Reverses the *fa*. This is done by reversing the direction of all
transitions and swapping the sets of *start* and
*[final](../../../../index.md#final)* states. The language of *fa* changes
unpredictably.
- <a name='3'></a>__::grammar::fa::op::complete__ *fa* ?*sink*?
Completes the *fa* *complete*, but nothing is done if the *fa* is already
*complete*. This implies that only the first in a series of multiple
consecutive complete operations on *fa* will perform anything. The remainder
will be null operations.
The language of *fa* is unchanged by this operation.
This is done by adding a single new state, the *sink*, and transitions from
all other states to that sink for all symbols they have no transitions for.
The sink itself is made complete by adding loop transitions for all symbols.
Note: When a FA has epsilon-transitions transitions over a symbol for a
state S can be indirect, i.e. not attached directly to S, but to a state in
the epsilon-closure of S. The symbols for such indirect transitions count
when computing completeness of a state. In other words, these indirectly
reached symbols are *not* missing.
The argument *sink* provides the name for the new state and most not be
present in the *fa* if specified. If the name is not specified the command
will name the state "sink__n__", where __n__ is set so that there are no
collisions with existing states.
Note that the sink state is *not useful* by definition. In other words,
while the FA becomes complete, it is also *not useful* in the strict sense
as it has a state from which no final state can be reached.
- <a name='4'></a>__::grammar::fa::op::remove_eps__ *fa*
Removes all epsilon-transitions from the *fa* in such a manner the the
language of *fa* is unchanged. However nothing is done if the *fa* is
already *epsilon-free*. This implies that only the first in a series of
multiple consecutive complete operations on *fa* will perform anything. The
remainder will be null operations.
*Note:* This operation may cause states to become unreachable or not useful.
These states are not removed by this operation. Use
__::grammar::fa::op::trim__ for that instead.
- <a name='5'></a>__::grammar::fa::op::trim__ *fa* ?*what*?
Removes unwanted baggage from *fa*. The legal values for *what* are listed
below. The command defaults to __!reachable|!useful__ if no specific
argument was given.
* __!reachable__
Removes all states which are not reachable from a start state.
* __!useful__
Removes all states which are unable to reach a final state.
* __!reachable&!useful__
* __!(reachable|useful)__
Removes all states which are not reachable from a start state and are
unable to reach a final state.
* __!reachable|!useful__
* __!(reachable&useful)__
Removes all states which are not reachable from a start state or are
unable to reach a final state.
- <a name='6'></a>__::grammar::fa::op::determinize__ *fa* ?*mapvar*?
Makes the *fa* deterministic without changing the language accepted by the
*fa*. However nothing is done if the *fa* is already *deterministic*. This
implies that only the first in a series of multiple consecutive complete
operations on *fa* will perform anything. The remainder will be null
operations.
The command will store a dictionary describing the relationship between the
new states of the resulting dfa and the states of the input nfa in *mapvar*,
if it has been specified. Keys of the dictionary are the handles for the
states of the resulting dfa, values are sets of states from the input nfa.
*Note*: An empty dictionary signals that the command was able to make the
*fa* deterministic without performing a full subset construction, just by
removing states and shuffling transitions around (As part of making the FA
epsilon-free).
*Note*: The algorithm fails to make the FA deterministic in the technical
sense if the FA has no start state(s), because determinism requires the FA
to have exactly one start states. In that situation we make a best effort;
and the missing start state will be the only condition preventing the
generated result from being *deterministic*. It should also be noted that in
this case the possibilities for trimming states from the FA are also
severely reduced as we cannot declare states unreachable.
- <a name='7'></a>__::grammar::fa::op::minimize__ *fa* ?*mapvar*?
Creates a FA which accepts the same language as *fa*, but has a minimal
number of states. Uses Brzozowski's method to accomplish this.
The command will store a dictionary describing the relationship between the
new states of the resulting minimal fa and the states of the input fa in
*mapvar*, if it has been specified. Keys of the dictionary are the handles
for the states of the resulting minimal fa, values are sets of states from
the input fa.
*Note*: An empty dictionary signals that the command was able to minimize
the *fa* without having to compute new states. This should happen if and
only if the input FA was already minimal.
*Note*: If the algorithm has no start or final states to work with then the
result might be technically minimal, but have a very unexpected structure.
It should also be noted that in this case the possibilities for trimming
states from the FA are also severely reduced as we cannot declare states
unreachable.
*Language operations* All operations in this section require that all input FAs
have at least one start and at least one final state. Otherwise the language of
the FAs will not be defined, making the operation senseless (as it operates on
the languages of the FAs in a defined manner).
- <a name='8'></a>__::grammar::fa::op::complement__ *fa*
Complements *fa*. This is possible if and only if *fa* is *complete* and
*deterministic*. The resulting FA accepts the complementary language of
*fa*. In other words, all inputs not accepted by the input are accepted by
the result, and vice versa.
The result will have all states and transitions of the input, and different
final states.
- <a name='9'></a>__::grammar::fa::op::kleene__ *fa*
Applies Kleene's closure to *fa*. The resulting FA accepts all strings __S__
for which we can find a natural number __n__ (0 inclusive) and strings
__A1__ ... __An__ in the language of *fa* such that __S__ is the
concatenation of __A1__ ... __An__. In other words, the language of the
result is the infinite union over finite length concatenations over the
language of *fa*.
The result will have all states and transitions of the input, and new start
and final states.
- <a name='10'></a>__::grammar::fa::op::optional__ *fa*
Makes the *fa* optional. In other words it computes the FA which accepts the
language of *fa* and the empty the word (epsilon) as well.
The result will have all states and transitions of the input, and new start
and final states.
- <a name='11'></a>__::grammar::fa::op::union__ *fa* *fb* ?*mapvar*?
Combines the FAs *fa* and *fb* such that the resulting FA accepts the union
of the languages of the two FAs.
The result will have all states and transitions of the two input FAs, and
new start and final states. All states of *fb* which exist in *fa* as well
will be renamed, and the *mapvar* will contain a mapping from the old states
of *fb* to the new ones, if present.
It should be noted that the result will be non-deterministic, even if the
inputs are deterministic.
- <a name='12'></a>__::grammar::fa::op::intersect__ *fa* *fb* ?*mapvar*?
Combines the FAs *fa* and *fb* such that the resulting FA accepts the
intersection of the languages of the two FAs. In other words, the result
will accept a word if and only if the word is accepted by both *fa* and
*fb*. The result will be useful, but not necessarily deterministic or
minimal.
The command will store a dictionary describing the relationship between the
new states of the resulting fa and the pairs of states of the input FAs in
*mapvar*, if it has been specified. Keys of the dictionary are the handles
for the states of the resulting fa, values are pairs of states from the
input FAs. Pairs are represented by lists. The first element in each pair
will be a state in *fa*, the second element will be drawn from *fb*.
- <a name='13'></a>__::grammar::fa::op::difference__ *fa* *fb* ?*mapvar*?
Combines the FAs *fa* and *fb* such that the resulting FA accepts the
difference of the languages of the two FAs. In other words, the result will
accept a word if and only if the word is accepted by *fa*, but not by *fb*.
This can also be expressed as the intersection of *fa* with the complement
of *fb*. The result will be useful, but not necessarily deterministic or
minimal.
The command will store a dictionary describing the relationship between the
new states of the resulting fa and the pairs of states of the input FAs in
*mapvar*, if it has been specified. Keys of the dictionary are the handles
for the states of the resulting fa, values are pairs of states from the
input FAs. Pairs are represented by lists. The first element in each pair
will be a state in *fa*, the second element will be drawn from *fb*.
- <a name='14'></a>__::grammar::fa::op::concatenate__ *fa* *fb* ?*mapvar*?
Combines the FAs *fa* and *fb* such that the resulting FA accepts the
cross-product of the languages of the two FAs. I.e. a word W will be
accepted by the result if there are two words A and B accepted by *fa*, and
*fb* resp. and W is the concatenation of A and B.
The result FA will be non-deterministic.
- <a name='15'></a>__::grammar::fa::op::fromRegex__ *fa* *regex* ?*over*?
Generates a non-deterministic FA which accepts the same language as the
regular expression *regex*. If the *over* is specified it is treated as the
set of symbols the regular expression and the automaton are defined over.
The command will compute the set from the "S" constructors in *regex* when
*over* was not specified. This set is important if and only if the
complement operator "!" is used in *regex* as the complementary language of
an FA is quite different for different sets of symbols.
The regular expression is represented by a nested list, which forms a syntax
tree. The following structures are legal:
* {S x}
Atomic regular expression. Everything else is constructed from these.
Accepts the __S__ymbol "x".
* {. A1 A2 ...}
Concatenation operator. Accepts the concatenation of the regular
expressions __A1__, __A2__, etc.
*Note* that this operator accepts zero or more arguments. With zero
arguments the represented language is *epsilon*, the empty word.
* {| A1 A2 ...}
Choice operator, also called "Alternative". Accepts all input accepted
by at least one of the regular expressions __A1__, __A2__, etc. In other
words, the union of __A1__, __A2__.
*Note* that this operator accepts zero or more arguments. With zero
arguments the represented language is the *empty* language, the language
without words.
* {& A1 A2 ...}
Intersection operator, logical and. Accepts all input accepted which is
accepted by all of the regular expressions __A1__, __A2__, etc. In other
words, the intersection of __A1__, __A2__.
* {? A}
Optionality operator. Accepts the empty word and anything from the
regular expression __A__.
* {* A}
Kleene closure. Accepts the empty word and any finite concatenation of
words accepted by the regular expression __A__.
* {+ A}
Positive Kleene closure. Accepts any finite concatenation of words
accepted by the regular expression __A__, but not the empty word.
* {! A}
Complement operator. Accepts any word not accepted by the regular
expression __A__. Note that the complement depends on the set of symbol
the result should run over. See the discussion of the argument *over*
before.
- <a name='16'></a>__::grammar::fa::op::toRegexp__ *fa*
This command generates and returns a regular expression which accepts the
same language as the finite automaton *fa*. The regular expression is in the
format as described above, for __::grammar::fa::op::fromRegex__.
- <a name='17'></a>__::grammar::fa::op::toRegexp2__ *fa*
This command has the same functionality as __::grammar::fa::op::toRegexp__,
but uses a different algorithm to simplify the generated regular
expressions.
- <a name='18'></a>__::grammar::fa::op::toTclRegexp__ *regexp* *symdict*
This command generates and returns a regular expression in Tcl syntax for
the regular expression *regexp*, if that is possible. *regexp* is in the
same format as expected by __::grammar::fa::op::fromRegex__.
The command will fail and throw an error if *regexp* contains
complementation and intersection operations.
The argument *symdict* is a dictionary mapping symbol names to pairs of
*syntactic type* and Tcl-regexp. If a symbol occurring in the *regexp* is
not listed in this dictionary then single-character symbols are considered
to designate themselves whereas multiple-character symbols are considered to
be a character class name.
- <a name='19'></a>__::grammar::fa::op::simplifyRegexp__ *regexp*
This command simplifies a regular expression by applying the following
algorithm first to the main expression and then recursively to all
sub-expressions:
Convert the expression into a finite automaton.
Minimize the automaton.
Convert the automaton back to a regular expression.
Choose the shorter of original expression and expression from the previous
step.
# <a name='section3'></a>EXAMPLES
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_fa* 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.
# <a name='keywords'></a>KEYWORDS
[automaton](../../../../index.md#automaton), [finite
automaton](../../../../index.md#finite_automaton),
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [regular
expression](../../../../index.md#regular_expression), [regular
grammar](../../../../index.md#regular_grammar), [regular
languages](../../../../index.md#regular_languages),
[state](../../../../index.md#state),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/gasm.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
|
[//000000001]: # (grammar::me::cpu::gasm - Grammar operations and usage)
[//000000002]: # (Generated from file 'gasm.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me::cpu::gasm(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::me::cpu::gasm - ME assembler
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [DEFINITIONS](#section2)
- [API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require grammar::me::cpu::gasm ?0.1?
[__::grammar::me::cpu::gasm::begin__ *g* *n* ?*mode*? ?*note*?](#1)
[__::grammar::me::cpu::gasm::done__ __-->__ *t*](#2)
[__::grammar::me::cpu::gasm::state__](#3)
[__::grammar::me::cpu::gasm::state!__ *s*](#4)
[__::grammar::me::cpu::gasm::lift__ *t* *dst* __=__ *src*](#5)
[__::grammar::me::cpu::gasm::Inline__ *t* *node* *label*](#6)
[__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*...?](#7)
[__::grammar::me::cpu::gasm::Bra__](#8)
[__::grammar::me::cpu::gasm::Nop__ *text*](#9)
[__::grammar::me::cpu::gasm::Note__ *text*](#10)
[__::grammar::me::cpu::gasm::Jmp__ *label*](#11)
[__::grammar::me::cpu::gasm::Exit__](#12)
[__::grammar::me::cpu::gasm::Who__ *label*](#13)
[__::grammar::me::cpu::gasm::/Label__ *name*](#14)
[__::grammar::me::cpu::gasm::/Clear__](#15)
[__::grammar::me::cpu::gasm::/Ok__](#16)
[__::grammar::me::cpu::gasm::/Fail__](#17)
[__::grammar::me::cpu::gasm::/At__ *name*](#18)
[__::grammar::me::cpu::gasm::/CloseLoop__](#19)
# <a name='description'></a>DESCRIPTION
This package provides a simple in-memory assembler. Its origin is that of a
support package for use by packages converting PEG and other grammars into a
corresponding matcher based on the ME virtual machine, like
__page::compiler::peg::mecpu__. Despite that it is actually mostly agnostic
regarding the instructions, users can choose any instruction set they like.
The program under construction is held in a graph structure (See package
__[struct::graph](../struct/graph.md)__) during assembly and subsequent
manipulation, with instructions represented by nodes, and the flow of execution
between instructions explicitly encoded in the arcs between them.
In this model jumps are not encoded explicitly, they are implicit in the arcs.
The generation of explicit jumps is left to any code converting the graph
structure into a more conventional representation. The same goes for branches.
They are implicitly encoded by all instructions which have two outgoing arcs,
whereas all other instructions have only one outgoing arc. Their conditonality
is handled by tagging their outgoing arcs with information about the conditions
under which they are taken.
While the graph the assembler operates on is supplied from the outside, i.e.
external, it does manage some internal state, namely:
1. The handle of the graph node most assembler operations will work on, the
*anchor*.
1. A mapping from arbitrary strings to instructions. I.e. it is possible to
*label* an instruction during assembly, and later recall that instruction
by its label.
1. The condition code to use when creating arcs between instructions, which is
one of __always__, __ok__, and __fail__.
1. The current operation mode, one of __halt__, __okfail__, and __!okfail__.
1. The name of a node in a tree. This, and the operation mode above are the
parts most heavily influenced by the needs of a grammar compiler, as they
assume some basic program structures (selected through the operation mode),
and intertwine the graph with a tree, like the AST for the grammar to be
compiled.
# <a name='section2'></a>DEFINITIONS
As the graph the assembler is operating on, and the tree it is intertwined with,
are supplied to the assembler from the outside it is necessary to specify the
API expected from them, and to describe the structures expected and/or generated
by the assembler in either.
1. Any graph object command used by the assembler has to provide the API as
specified in the documentation for the package
__[struct::graph](../struct/graph.md)__.
1. Any tree object command used by the assembler has to provide the API as
specified in the documentation for the package
__[struct::tree](../struct/struct_tree.md)__.
1. Any instruction (node) generated by the assembler in a graph will have at
least two, and at most three attributes:
- __instruction__
The value of this attribute is the name of the instruction. The only
names currently defined by the assembler are the three
pseudo-instructions
* __NOP__
This instruction does nothing. Useful for fixed framework nodes,
unchanging jump destinations, and the like. No arguments.
* __C__
A .NOP to allow the insertion of arbitrary comments into the
instruction stream, i.e. a comment node. One argument, the text of
the comment.
* __BRA__
A .NOP serving as explicitly coded conditional branch. No
arguments.
However we reserve the space of all instructions whose names begin with
a "." (dot) for future use by the assembler.
- __arguments__
The value of this attribute is a list of strings, the arguments of the
instruction. The contents are dependent on the actual instruction and
the assembler doesn't know or care about them. This means for example
that it has no builtin knowledge about what instruction need which
arguments and thus doesn't perform any type of checking.
- __expr__
This attribute is optional. When it is present its value is the name of
a node in the tree intertwined with the graph.
1. Any arc between two instructions will have one attribute:
- __condition__
The value of this attribute determines under which condition execution
will take this arc. It is one of __always__, __ok__, and __fail__. The
first condition is used for all arcs which are the single outgoing arc
of an instruction. The other two are used for the two outgoing arcs of
an instruction which implicitly encode a branch.
1. A tree node given to the assembler for cross-referencing will be written to
and given the following attributes, some fixed, some dependent on the
operation mode. All values will be references to nodes in the instruction
graph. Some of the instruction will expect some or specific sets of these
attributes.
- __gas::entry__
Always written.
- __gas::exit__
Written for all modes but __okfail__.
- __gas::exit::ok__
Written for mode __okfail__.
- __gas::exit::fail__
Written for mode __okfail__.
# <a name='section3'></a>API
- <a name='1'></a>__::grammar::me::cpu::gasm::begin__ *g* *n* ?*mode*? ?*note*?
This command starts the assembly of an instruction sequence, and
(re)initializes the state of the assembler. After completion of the
instruction sequence use __::grammar::me::cpu::gasm::done__ to finalize the
assembler.
It will operate on the graph *g* in the specified *mode* (Default is
__okfail__). As part of the initialization it will always create a standard
.NOP instruction and label it "entry". The creation of the remaining
standard instructions is *mode*-dependent:
* __halt__
An "icf_halt" instruction labeled "exit/return".
* __!okfail__
An "icf_ntreturn" instruction labeled "exit/return".
* __okfail__
Two .NOP instructions labeled "exit/ok" and "exit/fail" respectively.
The *note*, if specified (default is not), is given to the "entry" .NOP
instruction.
The node reference *n* is simply stored for use by
__::grammar::me::cpu::gasm::done__. It has to refer to a node in the tree
*t* argument of that command.
After the initialization is done the "entry" instruction will be the
*anchor*, and the condition code will be set to __always__.
The command returns the empy string as its result.
- <a name='2'></a>__::grammar::me::cpu::gasm::done__ __-->__ *t*
This command finalizes the creation of an instruction sequence and then
clears the state of the assembler. *NOTE* that this *does not* delete any of
the created instructions. They can be made available to future begin/done
cycles. Further assembly will be possible only after reinitialization of the
system via __::grammar::me::cpu::gasm::begin__.
Before the state is cleared selected references to selected instructions
will be written to attributes of the node *n* in the tree *t*. Which
instructions are saved is *mode*-dependent. Both *mode* and the destination
node *n* were specified during invokation of
__::grammar::me::cpu::gasm::begin__.
Independent of the mode a reference to the instruction labeled "entry" will
be saved to the attribute __gas::entry__ of *n*. The reference to the node
*n* will further be saved into the attribute "expr" of the "entry"
instruction. Beyond that
* __halt__
A reference to the instruction labeled "exit/return" will be saved to
the attribute __gas::exit__ of *n*.
* __okfail__
See __halt__.
* __!okfail__
Reference to the two instructions labeled "exit/ok" and "exit/fail" will
be saved to the attributes __gas::exit::ok__ and __gas::exit::fail__ of
*n* respectively.
The command returns the empy string as its result.
- <a name='3'></a>__::grammar::me::cpu::gasm::state__
This command returns the current state of the assembler. Its format is not
documented and considered to be internal to the package.
- <a name='4'></a>__::grammar::me::cpu::gasm::state!__ *s*
This command takes a serialized assembler state *s* as returned by
__::grammar::me::cpu::gasm::state__ and makes it the current state of the
assembler.
*Note* that this may overwrite label definitions, however all
non-conflicting label definitions in the state before are not touched and
merged with *s*.
The command returns the empty string as its result.
- <a name='5'></a>__::grammar::me::cpu::gasm::lift__ *t* *dst* __=__ *src*
This command operates on the tree *t*. It copies the contents of the
attributes __gas::entry__, __gas::exit::ok__ and __gas::exit::fail__ from
the node *src* to the node *dst*. It returns the empty string as its result.
- <a name='6'></a>__::grammar::me::cpu::gasm::Inline__ *t* *node* *label*
This command links an instruction sequence created by an earlier begin/done
pair into the current instruction sequence.
To this end it
reads the instruction references from the attributes __gas::entry__,
__gas::exit::ok__, and __gas::exit::fail__ from the node *n* of the tree *t*
and makes them available to assembler und the labels *label*/entry,
*label*/exit::ok, and *label*/exit::fail respectively.
Creates an arc from the *anchor* to the node labeled *label*/entry, and tags
it with the current condition code.
Makes the node labeled *label*/exit/ok the new *anchor*.
The command returns the empty string as its result.
- <a name='7'></a>__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*...?
This is the basic command to add instructions to the graph. It creates a new
instruction of type *cmd* with the given arguments *arg*... If the *anchor*
was defined it will also create an arc from the *anchor* to the new
instruction using the current condition code. After the call the new
instruction will be the *anchor* and the current condition code will be set
to __always__.
The command returns the empty string as its result.
- <a name='8'></a>__::grammar::me::cpu::gasm::Bra__
This is a convenience command to create a .BRA pseudo-instruction. It uses
__::grammar::me::cpu::gasm::Cmd__ to actually create the instruction and
inherits its behaviour.
- <a name='9'></a>__::grammar::me::cpu::gasm::Nop__ *text*
This is a convenience command to create a .NOP pseudo-instruction. It uses
__::grammar::me::cpu::gasm::Cmd__ to actually create the instruction and
inherits its behaviour. The *text* will be saved as the first and only
argument of the new instruction.
- <a name='10'></a>__::grammar::me::cpu::gasm::Note__ *text*
This is a convenience command to create a .C pseudo-instruction, i.e. a
comment. It uses __::grammar::me::cpu::gasm::Cmd__ to actually create the
instruction and inherits its behaviour. The *text* will be saved as the
first and only argument of the new instruction.
- <a name='11'></a>__::grammar::me::cpu::gasm::Jmp__ *label*
This command creates an arc from the *anchor* to the instruction labeled
with *label*, and tags with the the current condition code.
The command returns the empty string as its result.
- <a name='12'></a>__::grammar::me::cpu::gasm::Exit__
This command creates an arc from the *anchor* to one of the exit
instructions, based on the operation mode (see
__::grammar::me::cpu::gasm::begin__), and tags it with current condition
code.
For mode __okfail__ it links to the instruction labeled either "exit/ok" or
"exit/fail", depending on the current condition code, and tagging it with
the current condition code For the other two modes it links to the
instruction labeled "exit/return", tagging it condition code __always__,
independent the current condition code.
The command returns the empty string as its result.
- <a name='13'></a>__::grammar::me::cpu::gasm::Who__ *label*
This command returns a reference to the instruction labeled with *label*.
- <a name='14'></a>__::grammar::me::cpu::gasm::/Label__ *name*
This command labels the *anchor* with *name*. *Note* that an instruction can
have more than one label.
The command returns the empty string as its result.
- <a name='15'></a>__::grammar::me::cpu::gasm::/Clear__
This command clears the *anchor*, leaving it undefined, and further resets
the current condition code to __always__.
The command returns the empty string as its result.
- <a name='16'></a>__::grammar::me::cpu::gasm::/Ok__
This command sets the current condition code to __ok__.
The command returns the empty string as its result.
- <a name='17'></a>__::grammar::me::cpu::gasm::/Fail__
This command sets the current condition code to __fail__.
The command returns the empty string as its result.
- <a name='18'></a>__::grammar::me::cpu::gasm::/At__ *name*
This command sets the *anchor* to the instruction labeled with *name*, and
further resets the current condition code to __always__.
The command returns the empty string as its result.
- <a name='19'></a>__::grammar::me::cpu::gasm::/CloseLoop__
This command marks the *anchor* as the last instruction in a loop body, by
creating the attribute __LOOP__.
The command returns the empty string as its result.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[assembler](../../../../index.md#assembler),
[grammar](../../../../index.md#grammar), [graph](../../../../index.md#graph),
[parsing](../../../../index.md#parsing), [tree](../../../../index.md#tree),
[virtual machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_ast.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
[//000000001]: # (grammar::me_ast - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_ast.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me_ast(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::me_ast - Various representations of ASTs
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [AST VALUES](#section2)
- [AST OBJECTS](#section3)
- [EXTENDED AST OBJECTS](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document specifies various representations for the *[abstract syntax
tree](../../../../index.md#abstract_syntax_tree)*s (short
*[AST](../../../../index.md#ast)*) generated by instances of ME virtual
machines, independent of variant. Please go and read the document
__[grammar::me_intro](me_intro.md)__ first if you do not know what a ME virtual
machine is.
ASTs and all the representations we specify distinguish between two types of
nodes, namely:
- Terminal
Terminal nodes refer to the terminal symbols found in the token stream. They
are always leaf nodes. I.e. terminal nodes never have children.
- Nonterminal
Nonterminal nodes represent a nonterminal symbol of the grammar used during
parsing. They can occur as leaf and inner nodes of the tree.
Both types of nodes carry basic range information telling a user which parts of
the input are covered by the node by providing the location of the first and
last tokens found within the range. Locations are provided as non-negative
integer offsets from the beginning of the token stream, with the first token
found in the stream located at offset 0 (zero).
The root of an AS tree can be either a terminal or nonterminal node.
# <a name='section2'></a>AST VALUES
This representation of ASTs is a Tcl list. The main list represents the root
node of the tree, with the representations of the children nested within.
Each node is represented by a single Tcl list containing three or more elements.
The first element is either the empty string or the name of a nonterminal symbol
(which is never the empty string). The second and third elements are then the
locations of the first and last tokens. Any additional elements after the third
are then the representations of the children, with the leftmost child first,
i.e. as the fourth element of the list representing the node.
# <a name='section3'></a>AST OBJECTS
In this representation an AST is represented by a Tcl object command whose API
is compatible to the tree objects provided by the package
__[struct::tree](../struct/struct_tree.md)__. I.e it has to support at least all
of the methods described by that package, and may support more.
Because of this the remainder of the specifications is written using the terms
of __[struct::tree](../struct/struct_tree.md)__.
Each node of the AST directly maps to a node in the tree object. All data beyond
the child nodes, i.e. node type and input locations, are stored in attributes of
the node in the tree object. They are:
- type
The type of the AST node. The recognized values are __terminal__ and
__nonterminal__.
- range
The locations of the first and last token of the terminal data in the input
covered by the node. This is a list containing two locations.
- detail
This attribute is present only for nonterminal nodes. It contains the name
of the nonterminal symbol stored in the node.
# <a name='section4'></a>EXTENDED AST OBJECTS
Extended AST objects are like AST objects, with additional information.
- detail
This attribute is now present at all nodes. Its contents are unchanged for
nonterminal nodes. For terminal nodes it contains a list describing all
tokens from the input which are covered by the node.
Each element of the list contains the token name, the associated lexeme
attribute, line number, and column index, in this order.
- range_lc
This new attribute is defined for all nodes, and contains the locations from
attribute *range* translated into line number and column index. Lines are
counted from 1, columns are counted from 0.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[AST](../../../../index.md#ast), [abstract syntax
tree](../../../../index.md#abstract_syntax_tree)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_cpu.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
[//000000001]: # (grammar::me::cpu - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_cpu.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me::cpu(n) 0.2 tcllib "Grammar operations and usage")
# NAME
grammar::me::cpu - Virtual machine implementation II for parsing token streams
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [CLASS API](#subsection1)
- [OBJECT API](#subsection2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require grammar::me::cpu ?0.2?
[__::grammar::me::cpu__ *meName* *matchcode*](#1)
[__meName__ __option__ ?*arg arg ...*?](#2)
[*meName* __lc__ *location*](#3)
[*meName* __tok__ ?*from* ?*to*??](#4)
[*meName* __pc__ *state*](#5)
[*meName* __iseof__ *state*](#6)
[*meName* __at__ *state*](#7)
[*meName* __cc__ *state*](#8)
[*meName* __sv__](#9)
[*meName* __ok__](#10)
[*meName* __error__](#11)
[*meName* __lstk__ *state*](#12)
[*meName* __astk__ *state*](#13)
[*meName* __mstk__ *state*](#14)
[*meName* __estk__ *state*](#15)
[*meName* __rstk__ *state*](#16)
[*meName* __nc__ *state*](#17)
[*meName* __ast__](#18)
[*meName* __halted__](#19)
[*meName* __code__](#20)
[*meName* __eof__](#21)
[*meName* __put__ *tok* *lex* *line* *col*](#22)
[*meName* __putstring__ *string* *lvar* *cvar*](#23)
[*meName* __run__ ?*n*?](#24)
[*meName* __pull__ *nextcmd*](#25)
[*meName* __reset__](#26)
[*meName* __destroy__](#27)
# <a name='description'></a>DESCRIPTION
This package provides an implementation of the ME virtual machine. Please go and
read the document __[grammar::me_intro](me_intro.md)__ first if you do not know
what a ME virtual machine is.
This implementation provides an object-based API and the machines are not truly
tied to Tcl. A C implementation of the same API is quite possible.
Internally the package actually uses the value-based machine manipulation
commands as provided by the package __[grammar::me::cpu::core](me_cpucore.md)__
to perform its duties.
# <a name='section2'></a>API
## <a name='subsection1'></a>CLASS API
The package directly provides only a single command for the construction of ME
virtual machines.
- <a name='1'></a>__::grammar::me::cpu__ *meName* *matchcode*
The command creates a new ME machine object with an associated global Tcl
command whose name is *meName*. This command may be used to invoke various
operations on the machine. It has the following general form:
* <a name='2'></a>__meName__ __option__ ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
The argument *matchcode* contains the match instructions the machine has to
execute while parsing the input stream. Please read section __MATCH CODE
REPRESENTATION__ of the documentation for the package
__[grammar::me::cpu::core](me_cpucore.md)__ for the specification of the
structure of this value.
The *tokmap* argument taken by the implementation provided by the package
__[grammar::me::tcl](me_tcl.md)__ is here hidden inside of the match
instructions and therefore not needed.
## <a name='subsection2'></a>OBJECT API
All ME virtual machine objects created by the class command specified in section
[CLASS API](#subsection1) support the methods listed below.
The machines provided by this package provide methods for operation in both
push- and pull-styles. Push-style means that tokens are pushed into the machine
state when they arrive, triggering further execution until they are consumed. In
other words, this allows the machine to be suspended and resumed at will and an
arbitrary number of times, the quasi-parallel operation of several machines, and
the operation as part of the event loop.
- <a name='3'></a>*meName* __lc__ *location*
This method converts the location of a token given as offset in the input
stream into the associated line number and column index. The result of the
command is a 2-element list containing the two values, in the order
mentioned in the previous sentence. This allows higher levels to convert the
location information found in the error status and the generated AST into
more human readable data.
*Note* that the command is not able to convert locations which have not been
reached by the machine yet. In other words, if the machine has read 7 tokens
the command is able to convert the offsets __0__ to __6__, but nothing
beyond that. This also shows that it is not possible to convert offsets
which refer to locations before the beginning of the stream.
- <a name='4'></a>*meName* __tok__ ?*from* ?*to*??
This method returns a Tcl list containing the part of the input stream
between the locations *from* and *to* (both inclusive). If *to* is not
specified it will default to the value of *from*. If *from* is not specified
either the whole input stream is returned.
Each element of the returned list is a list of four elements, the token, its
associated lexeme, line number, and column index, in this order. This
command places the same restrictions on its location arguments as the method
__lc__.
- <a name='5'></a>*meName* __pc__ *state*
This method takes the state value of a ME virtual machine and returns the
current value of the stored program counter.
- <a name='6'></a>*meName* __iseof__ *state*
This method takes the state value of a ME virtual machine and returns the
current value of the stored eof flag.
- <a name='7'></a>*meName* __at__ *state*
This method takes the state value of a ME virtual machine and returns the
current location in the input stream.
- <a name='8'></a>*meName* __cc__ *state*
This method takes the state value of a ME virtual machine and returns the
current token.
- <a name='9'></a>*meName* __sv__
This command returns the current semantic value *SV* stored in the machine.
This is an abstract syntax tree as specified in the document
__[grammar::me_ast](me_ast.md)__, section __AST VALUES__.
- <a name='10'></a>*meName* __ok__
This method returns the current match status *OK*.
- <a name='11'></a>*meName* __error__
This method returns the current error status *ER*.
- <a name='12'></a>*meName* __lstk__ *state*
This method takes the state value of a ME virtual machine and returns the
location stack.
- <a name='13'></a>*meName* __astk__ *state*
This method takes the state value of a ME virtual machine and returns the
AST stack.
- <a name='14'></a>*meName* __mstk__ *state*
This method takes the state value of a ME virtual machine and returns the
AST marker stack.
- <a name='15'></a>*meName* __estk__ *state*
This method takes the state value of a ME virtual machine and returns the
error stack.
- <a name='16'></a>*meName* __rstk__ *state*
This method takes the state value of a ME virtual machine and returns the
subroutine return stack.
- <a name='17'></a>*meName* __nc__ *state*
This method takes the state value of a ME virtual machine and returns the
nonterminal match cache as a dictionary.
- <a name='18'></a>*meName* __ast__
This method returns the current top entry of the AST stack *AS*. This is an
abstract syntax tree as specified in the document
__[grammar::me_ast](me_ast.md)__, section __AST VALUES__.
- <a name='19'></a>*meName* __halted__
This method returns a boolean value telling the caller whether the engine
has halted execution or not. Halt means that no further matching is
possible, and the information retrieved via the other method is final.
Attempts to __run__ the engine will be ignored, until a __reset__ is made.
- <a name='20'></a>*meName* __code__
This method returns the *code* information used to construct the object. In
other words, the match program executed by the machine.
- <a name='21'></a>*meName* __eof__
This method adds an end of file marker to the end of the input stream. This
signals the machine that the current contents of the input queue are the
final parts of the input and nothing will come after. Attempts to put more
characters into the queue will fail.
- <a name='22'></a>*meName* __put__ *tok* *lex* *line* *col*
This method adds the token *tok* to the end of the input stream, with
associated lexeme data *lex* and *line*/*col*umn information.
- <a name='23'></a>*meName* __putstring__ *string* *lvar* *cvar*
This method adds each individual character in the *string* as a token to the
end of the input stream, from first to last. The lexemes will be empty and
the line/col information is computed based on the characters encountered and
the data in the variables *lvar* and *cvar*.
- <a name='24'></a>*meName* __run__ ?*n*?
This methods causes the engine to execute match instructions until either
*n* instructions have been executed, or
a halt instruction was executed, or
the input queue is empty and the code is asking for more tokens to process.
If no limit *n* was set only the last two conditions are checked for.
- <a name='25'></a>*meName* __pull__ *nextcmd*
This method implements pull-style operation of the machine. It causes it to
execute match instructions until either a halt instruction is reached, or
the command prefix *nextcmd* ceases to deliver more tokens.
The command prefix *nextcmd* represents the input stream of characters and
is invoked by the machine whenever the a new character from the stream is
required. The instruction for handling this is *ict_advance*. The callback
has to return either the empty list, or a list of 4 elements containing the
token, its lexeme attribute, and its location as line number and column
index, in this order. The empty list is the signal that the end of the input
stream has been reached. The lexeme attribute is stored in the terminal
cache, but otherwise not used by the machine.
The end of the input stream for this method does not imply that method
__eof__ is called for the machine as a whole. By avoiding this and still
asking for an explicit call of the method it is possible to mix push- and
pull-style operation during the lifetime of the machine.
- <a name='26'></a>*meName* __reset__
This method resets the machine to its initial state, discarding any state it
may have.
- <a name='27'></a>*meName* __destroy__
This method deletes the object and releases all resurces it claimed.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005-2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_cpucore.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
|
[//000000001]: # (grammar::me::cpu::core - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_cpucore.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me::cpu::core(n) 0.2 tcllib "Grammar operations and usage")
# NAME
grammar::me::cpu::core - ME virtual machine state manipulation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [MATCH PROGRAM REPRESENTATION](#subsection1)
- [CPU STATE](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require grammar::me::cpu::core ?0.2?
[__::grammar::me::cpu::core__ __disasm__ *asm*](#1)
[__::grammar::me::cpu::core__ __asm__ *asm*](#2)
[__::grammar::me::cpu::core__ __new__ *asm*](#3)
[__::grammar::me::cpu::core__ __lc__ *state* *location*](#4)
[__::grammar::me::cpu::core__ __tok__ *state* ?*from* ?*to*??](#5)
[__::grammar::me::cpu::core__ __pc__ *state*](#6)
[__::grammar::me::cpu::core__ __iseof__ *state*](#7)
[__::grammar::me::cpu::core__ __at__ *state*](#8)
[__::grammar::me::cpu::core__ __cc__ *state*](#9)
[__::grammar::me::cpu::core__ __sv__ *state*](#10)
[__::grammar::me::cpu::core__ __ok__ *state*](#11)
[__::grammar::me::cpu::core__ __error__ *state*](#12)
[__::grammar::me::cpu::core__ __lstk__ *state*](#13)
[__::grammar::me::cpu::core__ __astk__ *state*](#14)
[__::grammar::me::cpu::core__ __mstk__ *state*](#15)
[__::grammar::me::cpu::core__ __estk__ *state*](#16)
[__::grammar::me::cpu::core__ __rstk__ *state*](#17)
[__::grammar::me::cpu::core__ __nc__ *state*](#18)
[__::grammar::me::cpu::core__ __ast__ *state*](#19)
[__::grammar::me::cpu::core__ __halted__ *state*](#20)
[__::grammar::me::cpu::core__ __code__ *state*](#21)
[__::grammar::me::cpu::core__ __eof__ *statevar*](#22)
[__::grammar::me::cpu::core__ __put__ *statevar* *tok* *lex* *line* *col*](#23)
[__::grammar::me::cpu::core__ __run__ *statevar* ?*n*?](#24)
# <a name='description'></a>DESCRIPTION
This package provides an implementation of the ME virtual machine. Please go and
read the document __[grammar::me_intro](me_intro.md)__ first if you do not know
what a ME virtual machine is.
This implementation represents each ME virtual machine as a Tcl value and
provides commands to manipulate and query such values to show the effects of
executing instructions, adding tokens, retrieving state, etc.
The values fully follow the paradigm of Tcl that every value is a string and
while also allowing C implementations for a proper Tcl_ObjType to keep all the
important data in native data structures. Because of the latter it is
recommended to access the state values *only* through the commands of this
package to ensure that internal representation is not shimmered away.
The actual structure used by all state values is described in section [CPU
STATE](#section3).
# <a name='section2'></a>API
The package directly provides only a single command, and all the functionality
is made available through its methods.
- <a name='1'></a>__::grammar::me::cpu::core__ __disasm__ *asm*
This method returns a list containing a disassembly of the match
instructions in *asm*. The format of *asm* is specified in the section
[MATCH PROGRAM REPRESENTATION](#subsection1).
Each element of the result contains instruction label, instruction name, and
the instruction arguments, in this order. The label can be the empty string.
Jump destinations are shown as labels, strings and tokens unencoded. Token
names are prefixed with their numeric id, if, and only if a tokmap is
defined. The two components are separated by a colon.
- <a name='2'></a>__::grammar::me::cpu::core__ __asm__ *asm*
This method returns code in the format as specified in section [MATCH
PROGRAM REPRESENTATION](#subsection1) generated from ME assembly code *asm*,
which is in the format as returned by the method __disasm__.
- <a name='3'></a>__::grammar::me::cpu::core__ __new__ *asm*
This method creates state value for a ME virtual machine in its initial
state and returns it as its result.
The argument *matchcode* contains a Tcl representation of the match
instructions the machine has to execute while parsing the input stream. Its
format is specified in the section [MATCH PROGRAM
REPRESENTATION](#subsection1).
The *tokmap* argument taken by the implementation provided by the package
__[grammar::me::tcl](me_tcl.md)__ is here hidden inside of the match
instructions and therefore not needed.
- <a name='4'></a>__::grammar::me::cpu::core__ __lc__ *state* *location*
This method takes the state value of a ME virtual machine and uses it to
convert a location in the input stream (as offset) into a line number and
column index. The result of the method is a 2-element list containing the
two pieces in the order mentioned in the previous sentence.
*Note* that the method cannot convert locations which the machine has not
yet read from the input stream. In other words, if the machine has read 7
characters so far it is possible to convert the offsets __0__ to __6__, but
nothing beyond that. This also shows that it is not possible to convert
offsets which refer to locations before the beginning of the stream.
This utility allows higher levels to convert the location offsets found in
the error status and the AST into more human readable data.
- <a name='5'></a>__::grammar::me::cpu::core__ __tok__ *state* ?*from* ?*to*??
This method takes the state value of a ME virtual machine and returns a Tcl
list containing the part of the input stream between the locations *from*
and *to* (both inclusive). If *to* is not specified it will default to the
value of *from*. If *from* is not specified either the whole input stream is
returned.
This method places the same restrictions on its location arguments as the
method __lc__.
- <a name='6'></a>__::grammar::me::cpu::core__ __pc__ *state*
This method takes the state value of a ME virtual machine and returns the
current value of the stored program counter.
- <a name='7'></a>__::grammar::me::cpu::core__ __iseof__ *state*
This method takes the state value of a ME virtual machine and returns the
current value of the stored eof flag.
- <a name='8'></a>__::grammar::me::cpu::core__ __at__ *state*
This method takes the state value of a ME virtual machine and returns the
current location in the input stream.
- <a name='9'></a>__::grammar::me::cpu::core__ __cc__ *state*
This method takes the state value of a ME virtual machine and returns the
current token.
- <a name='10'></a>__::grammar::me::cpu::core__ __sv__ *state*
This method takes the state value of a ME virtual machine and returns the
current semantic value stored in it. This is an abstract syntax tree as
specified in the document __[grammar::me_ast](me_ast.md)__, section __AST
VALUES__.
- <a name='11'></a>__::grammar::me::cpu::core__ __ok__ *state*
This method takes the state value of a ME virtual machine and returns the
match status stored in it.
- <a name='12'></a>__::grammar::me::cpu::core__ __error__ *state*
This method takes the state value of a ME virtual machine and returns the
current error status stored in it.
- <a name='13'></a>__::grammar::me::cpu::core__ __lstk__ *state*
This method takes the state value of a ME virtual machine and returns the
location stack.
- <a name='14'></a>__::grammar::me::cpu::core__ __astk__ *state*
This method takes the state value of a ME virtual machine and returns the
AST stack.
- <a name='15'></a>__::grammar::me::cpu::core__ __mstk__ *state*
This method takes the state value of a ME virtual machine and returns the
AST marker stack.
- <a name='16'></a>__::grammar::me::cpu::core__ __estk__ *state*
This method takes the state value of a ME virtual machine and returns the
error stack.
- <a name='17'></a>__::grammar::me::cpu::core__ __rstk__ *state*
This method takes the state value of a ME virtual machine and returns the
subroutine return stack.
- <a name='18'></a>__::grammar::me::cpu::core__ __nc__ *state*
This method takes the state value of a ME virtual machine and returns the
nonterminal match cache as a dictionary.
- <a name='19'></a>__::grammar::me::cpu::core__ __ast__ *state*
This method takes the state value of a ME virtual machine and returns the
abstract syntax tree currently at the top of the AST stack stored in it.
This is an abstract syntax tree as specified in the document
__[grammar::me_ast](me_ast.md)__, section __AST VALUES__.
- <a name='20'></a>__::grammar::me::cpu::core__ __halted__ *state*
This method takes the state value of a ME virtual machine and returns the
current halt status stored in it, i.e. if the machine has stopped or not.
- <a name='21'></a>__::grammar::me::cpu::core__ __code__ *state*
This method takes the state value of a ME virtual machine and returns the
code stored in it, i.e. the instructions executed by the machine.
- <a name='22'></a>__::grammar::me::cpu::core__ __eof__ *statevar*
This method takes the state value of a ME virtual machine as stored in the
variable named by *statevar* and modifies it so that the eof flag inside is
set. This signals to the machine that whatever token are in the input queue
are the last to be processed. There will be no more.
- <a name='23'></a>__::grammar::me::cpu::core__ __put__ *statevar* *tok* *lex* *line* *col*
This method takes the state value of a ME virtual machine as stored in the
variable named by *statevar* and modifies it so that the token *tok* is
added to the end of the input queue, with associated lexeme data *lex* and
*line*/*col*umn information.
The operation will fail with an error if the eof flag of the machine has
been set through the method __eof__.
- <a name='24'></a>__::grammar::me::cpu::core__ __run__ *statevar* ?*n*?
This method takes the state value of a ME virtual machine as stored in the
variable named by *statevar*, executes a number of instructions and stores
the state resulting from their modifications back into the variable.
The execution loop will run until either
*n* instructions have been executed, or
a halt instruction was executed, or
the input queue is empty and the code is asking for more tokens to process.
If no limit *n* was set only the last two conditions are checked for.
## <a name='subsection1'></a>MATCH PROGRAM REPRESENTATION
A match program is represented by nested Tcl list. The first element, *asm*, is
a list of integer numbers, the instructions to execute, and their arguments. The
second element, *[pool](../../../../index.md#pool)*, is a list of strings,
referenced by the instructions, for error messages, token names, etc. The third
element, *tokmap*, provides ordering information for the tokens, mapping their
names to their numerical rank. This element can be empty, forcing lexicographic
comparison when matching ranges.
All ME instructions are encoded as integer numbers, with the mapping given
below. A number of the instructions, those which handle error messages, have
been given an additional argument to supply that message explicitly instead of
having it constructed from token names, etc. This allows the machine state to
store only the message ids instead of the full strings.
Jump destination arguments are absolute indices into the *asm* element, refering
to the instruction to jump to. Any string arguments are absolute indices into
the *[pool](../../../../index.md#pool)* element. Tokens, characters, messages,
and token (actually character) classes to match are coded as references into the
*[pool](../../../../index.md#pool)* as well.
1. "__ict_advance__ *message*"
1. "__ict_match_token__ *tok* *message*"
1. "__ict_match_tokrange__ *tokbegin* *tokend* *message*"
1. "__ict_match_tokclass__ *code* *message*"
1. "__inc_restore__ *branchlabel* *nt*"
1. "__inc_save__ *nt*"
1. "__icf_ntcall__ *branchlabel*"
1. "__icf_ntreturn__"
1. "__iok_ok__"
1. "__iok_fail__"
1. "__iok_negate__"
1. "__icf_jalways__ *branchlabel*"
1. "__icf_jok__ *branchlabel*"
1. "__icf_jfail__ *branchlabel*"
1. "__icf_halt__"
1. "__icl_push__"
1. "__icl_rewind__"
1. "__icl_pop__"
1. "__ier_push__"
1. "__ier_clear__"
1. "__ier_nonterminal__ *message*"
1. "__ier_merge__"
1. "__isv_clear__"
1. "__isv_terminal__"
1. "__isv_nonterminal_leaf__ *nt*"
1. "__isv_nonterminal_range__ *nt*"
1. "__isv_nonterminal_reduce__ *nt*"
1. "__ias_push__"
1. "__ias_mark__"
1. "__ias_mrewind__"
1. "__ias_mpop__"
# <a name='section3'></a>CPU STATE
A state value is a list containing the following elements, in the order listed
below:
1. *code*: Match instructions, see [MATCH PROGRAM
REPRESENTATION](#subsection1).
1. *pc*: Program counter, *int*.
1. *halt*: Halt flag, *boolean*.
1. *eof*: Eof flag, *boolean*
1. *tc*: Terminal cache, and input queue. Structure see below.
1. *cl*: Current location, *int*.
1. *ct*: Current token, *[string](../../../../index.md#string)*.
1. *ok*: Match status, *boolean*.
1. *sv*: Semantic value, *[list](../../../../index.md#list)*.
1. *er*: Error status, *[list](../../../../index.md#list)*.
1. *ls*: Location stack, *[list](../../../../index.md#list)*.
1. *as*: AST stack, *[list](../../../../index.md#list)*.
1. *ms*: AST marker stack, *[list](../../../../index.md#list)*.
1. *es*: Error stack, *[list](../../../../index.md#list)*.
1. *rs*: Return stack, *[list](../../../../index.md#list)*.
1. *nc*: Nonterminal cache, *dictionary*.
*tc*, the input queue of tokens waiting for processing and the terminal cache
containing the tokens already processing are one unified data structure simply
holding all tokens and their information, with the current location separating
that which has been processed from that which is waiting. Each element of the
queue/cache is a list containing the token, its lexeme information, line number,
and column index, in this order.
All stacks have their top element aat the end, i.e. pushing an item is
equivalent to appending to the list representing the stack, and popping it
removes the last element.
*er*, the error status is either empty or a list of two elements, a location in
the input, and a list of messages, encoded as references into the
*[pool](../../../../index.md#pool)* element of the *code*.
*nc*, the nonterminal cache is keyed by nonterminal name and location, each
value a four-element list containing current location, match status, semantic
value, and error status, in this order.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005-2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
[//000000001]: # (grammar::me_intro - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me_intro(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::me_intro - Introduction to virtual machines for parsing token streams
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document is an introduction to and overview of the basic facilities for the
parsing and/or matching of *token* streams. One possibility often used for the
token domain are characters.
The packages themselves all provide variants of one *[virtual
machine](../../../../index.md#virtual_machine)*, called a *match engine* (short
*ME*), which has all the facilities needed for the matching and parsing of a
stream, and which are either controlled directly, or are customized with a match
program. The virtual machine is basically a pushdown automaton, with additional
elements for backtracking and/or handling of semantic data and construction of
abstract syntax trees (*[AST](../../../../index.md#ast)*).
Because of the high degree of similarity in the actual implementations of the
aforementioned virtual machine and the data structures they receive and generate
these common parts are specified in a separate document which will be referenced
by the documentation for packages actually implementing it.
The relevant documents are:
- __[grammar::me_vm](me_vm.md)__
Virtual machine specification.
- __[grammar::me_ast](me_ast.md)__
Specification of various representations used for abstract syntax trees.
- __[grammar::me::util](me_util.md)__
Utility commands.
- __[grammar::me::tcl](me_tcl.md)__
Singleton ME virtual machine implementation tied to Tcl for control flow and
stacks. Hardwired for pull operation. Uninteruptible during processing.
- __[grammar::me::cpu](me_cpu.md)__
Object-based ME virtual machine implementation with explicit control flow,
and stacks, using bytecodes. Suspend/Resumable. Push/pull operation.
- __[grammar::me::cpu::core](me_cpucore.md)__
Core functionality for state manipulation and stepping used in the bytecode
based implementation of ME virtual machines.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[CFG](../../../../index.md#cfg), [CFL](../../../../index.md#cfl),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TPDL](../../../../index.md#tpdl), [context-free
grammar](../../../../index.md#context_free_grammar), [context-free
languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parsing](../../../../index.md#parsing), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_tcl.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
|
[//000000001]: # (grammar::me::tcl - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_tcl.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me::tcl(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::me::tcl - Virtual machine implementation I for parsing token streams
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [MACHINE STATE](#section3)
- [MACHINE INSTRUCTIONS](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require grammar::me::tcl ?0.1?
[__::grammar::me::tcl__ __cmd__ *...*](#1)
[__::grammar::me::tcl__ __init__ *nextcmd* ?*tokmap*?](#2)
[__::grammar::me::tcl__ __lc__ *location*](#3)
[__::grammar::me::tcl__ __tok__ *from* ?*to*?](#4)
[__::grammar::me::tcl__ __tokens__](#5)
[__::grammar::me::tcl__ __sv__](#6)
[__::grammar::me::tcl__ __ast__](#7)
[__::grammar::me::tcl__ __astall__](#8)
[__::grammar::me::tcl__ __ctok__](#9)
[__::grammar::me::tcl__ __nc__](#10)
[__::grammar::me::tcl__ __next__](#11)
[__::grammar::me::tcl__ __ord__](#12)
[__::grammar::me::tcl::ict_advance__ *message*](#13)
[__::grammar::me::tcl::ict_match_token__ *tok* *message*](#14)
[__::grammar::me::tcl::ict_match_tokrange__ *tokbegin* *tokend* *message*](#15)
[__::grammar::me::tcl::ict_match_tokclass__ *code* *message*](#16)
[__::grammar::me::tcl::inc_restore__ *nt*](#17)
[__::grammar::me::tcl::inc_save__ *nt* *startlocation*](#18)
[__::grammar::me::tcl::iok_ok__](#19)
[__::grammar::me::tcl::iok_fail__](#20)
[__::grammar::me::tcl::iok_negate__](#21)
[__::grammar::me::tcl::icl_get__](#22)
[__::grammar::me::tcl::icl_rewind__ *oldlocation*](#23)
[__::grammar::me::tcl::ier_get__](#24)
[__::grammar::me::tcl::ier_clear__](#25)
[__::grammar::me::tcl::ier_nonterminal__ *message* *location*](#26)
[__::grammar::me::tcl::ier_merge__ *olderror*](#27)
[__::grammar::me::tcl::isv_clear__](#28)
[__::grammar::me::tcl::isv_terminal__](#29)
[__::grammar::me::tcl::isv_nonterminal_leaf__ *nt* *startlocation*](#30)
[__::grammar::me::tcl::isv_nonterminal_range__ *nt* *startlocation*](#31)
[__::grammar::me::tcl::isv_nonterminal_reduce__ *nt* *startlocation* ?*marker*?](#32)
[__::grammar::me::tcl::ias_push__](#33)
[__::grammar::me::tcl::ias_mark__](#34)
[__::grammar::me::tcl::ias_pop2mark__ *marker*](#35)
# <a name='description'></a>DESCRIPTION
This package provides an implementation of the ME virtual machine. Please go and
read the document __[grammar::me_intro](me_intro.md)__ first if you do not know
what a ME virtual machine is.
This implementation is tied very strongly to Tcl. All the stacks in the machine
state are handled through the Tcl stack, all control flow is handled by Tcl
commands, and the remaining machine instructions are directly mapped to Tcl
commands. Especially the matching of nonterminal symbols is handled by Tcl
procedures as well, essentially extending the machine implementation with custom
instructions.
Further on the implementation handles only a single machine which is
uninteruptible during execution and hardwired for pull operation. I.e. it
explicitly requests each new token through a callback, pulling them into its
state.
A related package is __[grammar::peg::interp](../grammar_peg/peg_interp.md)__
which provides a generic interpreter / parser for parsing expression grammars
(PEGs), implemented on top of this implementation of the ME virtual machine.
# <a name='section2'></a>API
The commands documented in this section do not implement any of the instructions
of the ME virtual machine. They provide the facilities for the initialization of
the machine and the retrieval of important information.
- <a name='1'></a>__::grammar::me::tcl__ __cmd__ *...*
This is an ensemble command providing access to the commands listed in this
section. See the methods themselves for detailed specifications.
- <a name='2'></a>__::grammar::me::tcl__ __init__ *nextcmd* ?*tokmap*?
This command (re)initializes the machine. It returns the empty string. This
command has to be invoked before any other command of this package.
The command prefix *nextcmd* represents the input stream of characters and
is invoked by the machine whenever the a new character from the stream is
required. The instruction for handling this is *ict_advance*. The callback
has to return either the empty list, or a list of 4 elements containing the
token, its lexeme attribute, and its location as line number and column
index, in this order. The empty list is the signal that the end of the input
stream has been reached. The lexeme attribute is stored in the terminal
cache, but otherwise not used by the machine.
The optional dictionary *tokmap* maps from tokens to integer numbers. If
present the numbers impose an order on the tokens, which is subsequently
used by *ict_match_tokrange* to determine if a token is in the specified
range or not. If no token map is specified the lexicographic order of th
token names will be used instead. This choice is especially asensible when
using characters as tokens.
- <a name='3'></a>__::grammar::me::tcl__ __lc__ *location*
This command converts the location of a token given as offset in the input
stream into the associated line number and column index. The result of the
command is a 2-element list containing the two values, in the order
mentioned in the previous sentence. This allows higher levels to convert the
location information found in the error status and the generated AST into
more human readable data.
*Note* that the command is not able to convert locations which have not been
reached by the machine yet. In other words, if the machine has read 7 tokens
the command is able to convert the offsets __0__ to __6__, but nothing
beyond that. This also shows that it is not possible to convert offsets
which refer to locations before the beginning of the stream.
After a call of __init__ the state used for the conversion is cleared,
making further conversions impossible until the machine has read tokens
again.
- <a name='4'></a>__::grammar::me::tcl__ __tok__ *from* ?*to*?
This command returns a Tcl list containing the part of the input stream
between the locations *from* and *to* (both inclusive). If *to* is not
specified it will default to the value of *from*.
Each element of the returned list is a list of four elements, the token, its
associated lexeme, line number, and column index, in this order. In other
words, each element has the same structure as the result of the *nextcmd*
callback given to __::grammar::me::tcl::init__
This command places the same restrictions on its location arguments as
__::grammar::me::tcl::lc__.
- <a name='5'></a>__::grammar::me::tcl__ __tokens__
This command returns the number of tokens currently known to the ME virtual
machine.
- <a name='6'></a>__::grammar::me::tcl__ __sv__
This command returns the current semantic value *SV* stored in the machine.
This is an abstract syntax tree as specified in the document
__[grammar::me_ast](me_ast.md)__, section __AST VALUES__.
- <a name='7'></a>__::grammar::me::tcl__ __ast__
This method returns the abstract syntax tree currently at the top of the AST
stack of the ME virtual machine. This is an abstract syntax tree as
specified in the document __[grammar::me_ast](me_ast.md)__, section __AST
VALUES__.
- <a name='8'></a>__::grammar::me::tcl__ __astall__
This method returns the whole stack of abstract syntax trees currently known
to the ME virtual machine. Each element of the returned list is an abstract
syntax tree as specified in the document __[grammar::me_ast](me_ast.md)__,
section __AST VALUES__. The top of the stack resides at the end of the list.
- <a name='9'></a>__::grammar::me::tcl__ __ctok__
This method returns the current token considered by the ME virtual machine.
- <a name='10'></a>__::grammar::me::tcl__ __nc__
This method returns the contents of the nonterminal cache as a dictionary
mapping from "__symbol__,__location__" to match information.
- <a name='11'></a>__::grammar::me::tcl__ __next__
This method returns the next token callback as specified during
initialization of the ME virtual machine.
- <a name='12'></a>__::grammar::me::tcl__ __ord__
This method returns a dictionary containing the *tokmap* specified during
initialization of the ME virtual machine. ____::grammar::me::tcl::ok____
This variable contains the current match status *OK*. It is provided as
variable instead of a command because that makes access to this information
faster, and the speed of access is considered very important here as this
information is used constantly to determine the control flow.
# <a name='section3'></a>MACHINE STATE
Please go and read the document __[grammar::me_vm](me_vm.md)__ first for a
specification of the basic ME virtual machine and its state.
This implementation manages the state described in that document, except for the
stacks minus the AST stack. In other words, location stack, error stack, return
stack, and ast marker stack are implicitly managed through standard Tcl scoping,
i.e. Tcl variables in procedures, outside of this implementation.
# <a name='section4'></a>MACHINE INSTRUCTIONS
Please go and read the document __[grammar::me_vm](me_vm.md)__ first for a
specification of the basic ME virtual machine and its instruction set.
This implementation maps all instructions to Tcl commands in the namespace
"::grammar::me::tcl", except for the stack related commands, nonterminal symbols
and control flow. Here we simply list the commands and explain the differences
to the specified instructions, if there are any. For their semantics see the
aforementioned specification. The machine commands are *not* reachable through
the ensemble command __::grammar::me::tcl__.
- <a name='13'></a>__::grammar::me::tcl::ict_advance__ *message*
No changes.
- <a name='14'></a>__::grammar::me::tcl::ict_match_token__ *tok* *message*
No changes.
- <a name='15'></a>__::grammar::me::tcl::ict_match_tokrange__ *tokbegin* *tokend* *message*
If, and only if a token map was specified during initialization then the
arguments are the numeric representations of the smallest and largest tokens
in the range. Otherwise they are the relevant tokens themselves and
lexicographic comparison is used.
- <a name='16'></a>__::grammar::me::tcl::ict_match_tokclass__ *code* *message*
No changes.
- <a name='17'></a>__::grammar::me::tcl::inc_restore__ *nt*
Instead of taking a branchlabel the command returns a boolean value. The
result will be __true__ if and only if cached information was found. The
caller has to perform the appropriate branching.
- <a name='18'></a>__::grammar::me::tcl::inc_save__ *nt* *startlocation*
The command takes the start location as additional argument, as it is
managed on the Tcl stack, and not in the machine state.
- __icf_ntcall__ *branchlabel*
- __icf_ntreturn__
These two instructions are not mapped to commands. They are control flow
instructions and handled in Tcl.
- <a name='19'></a>__::grammar::me::tcl::iok_ok__
No changes.
- <a name='20'></a>__::grammar::me::tcl::iok_fail__
No changes.
- <a name='21'></a>__::grammar::me::tcl::iok_negate__
No changes.
- __icf_jalways__ *branchlabel*
- __icf_jok__ *branchlabel*
- __icf_jfail__ *branchlabel*
- __icf_halt__
These four instructions are not mapped to commands. They are control flow
instructions and handled in Tcl.
- <a name='22'></a>__::grammar::me::tcl::icl_get__
This command returns the current location *CL* in the input. It replaces
*icl_push*.
- <a name='23'></a>__::grammar::me::tcl::icl_rewind__ *oldlocation*
The command takes the location as argument as it comes from the Tcl stack,
not the machine state.
- __icl_pop__
Not mapped, the stacks are not managed by the package.
- <a name='24'></a>__::grammar::me::tcl::ier_get__
This command returns the current error state *ER*. It replaces *ier_push*.
- <a name='25'></a>__::grammar::me::tcl::ier_clear__
No changes.
- <a name='26'></a>__::grammar::me::tcl::ier_nonterminal__ *message* *location*
The command takes the location as argument as it comes from the Tcl stack,
not the machine state.
- <a name='27'></a>__::grammar::me::tcl::ier_merge__ *olderror*
The command takes the second error state to merge as argument as it comes
from the Tcl stack, not the machine state.
- <a name='28'></a>__::grammar::me::tcl::isv_clear__
No changes.
- <a name='29'></a>__::grammar::me::tcl::isv_terminal__
No changes.
- <a name='30'></a>__::grammar::me::tcl::isv_nonterminal_leaf__ *nt* *startlocation*
The command takes the start location as argument as it comes from the Tcl
stack, not the machine state.
- <a name='31'></a>__::grammar::me::tcl::isv_nonterminal_range__ *nt* *startlocation*
The command takes the start location as argument as it comes from the Tcl
stack, not the machine state.
- <a name='32'></a>__::grammar::me::tcl::isv_nonterminal_reduce__ *nt* *startlocation* ?*marker*?
The command takes start location and marker as argument as it comes from the
Tcl stack, not the machine state.
- <a name='33'></a>__::grammar::me::tcl::ias_push__
No changes.
- <a name='34'></a>__::grammar::me::tcl::ias_mark__
This command returns a marker for the current state of the AST stack *AS*.
The marker stack is not managed by the machine.
- <a name='35'></a>__::grammar::me::tcl::ias_pop2mark__ *marker*
The command takes the marker as argument as it comes from the Tcl stack, not
the machine state. It replaces *ias_mpop*.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_util.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
[//000000001]: # (grammar::me::util - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_util.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me::util(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::me::util - AST utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require grammar::me::util ?0.1?
[__::grammar::me::util::ast2tree__ *ast* *tree* ?*root*?](#1)
[__::grammar::me::util::ast2etree__ *ast* *mcmd* *tree* ?*root*?](#2)
[__mcmd__ __lc__ *location*](#3)
[__mcmd__ __tok__ *from* ?*to*?](#4)
[__::grammar::me::util::tree2ast__ *tree* ?*root*?](#5)
# <a name='description'></a>DESCRIPTION
This package provides a number of utility command for the conversion between the
various representations of abstract syntax trees as specified in the document
__[grammar::me_ast](me_ast.md)__.
- <a name='1'></a>__::grammar::me::util::ast2tree__ *ast* *tree* ?*root*?
This command converts an *ast* from value to object representation. All
nodes in the *ast* will be converted into nodes of this *tree*, with the
root of the AST a child of the node *root*. If this node is not explicitly
specified the root of the tree is used. Existing content of tree is not
touched, i.e. neither removed nor changed, with the exception of the
specified root node, which will gain a new child.
- <a name='2'></a>__::grammar::me::util::ast2etree__ *ast* *mcmd* *tree* ?*root*?
This command is like __::grammar::me::util::ast2tree__, except that the
result is in the extended object representation of the input AST. The source
of the extended information is the command prefix *mcmd*. It has to
understand two methods, __lc__, and __tok__, with the semantics specified
below.
* <a name='3'></a>__mcmd__ __lc__ *location*
Takes the location of a token given as offset in the input stream and
return a 2-element list containing the associated line number and column
index, in this order.
* <a name='4'></a>__mcmd__ __tok__ *from* ?*to*?
Takes one or two locations *from* and *to* as offset in the input stream
and returns a Tcl list containing the specified part of the input
stream. Both location are inclusive. If *to* is not specified it will
default to the value of *from*.
Each element of the returned list is a list containing the token, its
associated lexeme, the line number, and column index, in this order.
Both the ensemble command __::grammar::me::tcl__ provided by the package
__[grammar::me::tcl](me_tcl.md)__ and the objects command created by the
package __::grammar::me::cpu__ fit the above specification.
- <a name='5'></a>__::grammar::me::util::tree2ast__ *tree* ?*root*?
This command converts an *ast* in (extended) object representation into a
value and returns it. If a *root* node is specified the AST is generated
from that node downward. Otherwise the root of the tree object is used as
the starting point.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[abstract syntax tree](../../../../index.md#abstract_syntax_tree), [syntax
tree](../../../../index.md#syntax_tree), [tree](../../../../index.md#tree)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_me/me_vm.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
|
[//000000001]: # (grammar::me_vm - Grammar operations and usage)
[//000000002]: # (Generated from file 'me_vm.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::me_vm(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::me_vm - Virtual machine for parsing token streams
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [MACHINE STATE](#section2)
- [MACHINE INSTRUCTIONS](#section3)
- [TERMINAL MATCHING](#subsection1)
- [NONTERMINAL MATCHING](#subsection2)
- [UNCONDITIONAL MATCHING](#subsection3)
- [CONTROL FLOW](#subsection4)
- [INPUT LOCATION HANDLING](#subsection5)
- [ERROR HANDLING](#subsection6)
- [SEMANTIC VALUES](#subsection7)
- [AST STACK HANDLING](#subsection8)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
Please go and read the document __[grammar::me_intro](me_intro.md)__ first for
an overview of the various documents and their relations.
This document specifies a virtual machine for the controlled matching and
parsing of token streams, creating an *[abstract syntax
tree](../../../../index.md#abstract_syntax_tree)* (short
*[AST](../../../../index.md#ast)*) reflecting the structure of the input.
Special machine features are the caching and reuse of partial results, caching
of the encountered input, and the ability to backtrack in both input and AST
creation.
These features make the specified virtual machine especially useful to packrat
parsers based on parsing expression grammars. It is however not restricted to
this type of parser. Normal LL and LR parsers can be implemented with it as
well.
The following sections will discuss first the abstract state kept by ME virtual
machines, and then their instruction set.
# <a name='section2'></a>MACHINE STATE
A ME virtual machine manages the following state:
- *Current token* CT
The token from the input under consideration by the machine.
This information is used and modified by the instructions defined in the
section [TERMINAL MATCHING](#subsection1).
- *Current location* CL
The location of the *current token* in the input stream, as offset relative
to the beginning of the stream. The first token is considered to be at
offset __0__.
This information is implicitly used and modified by the instructions defined
in the sections [TERMINAL MATCHING](#subsection1) and [NONTERMINAL
MATCHING](#subsection2), and can be directly queried and modified by the
instructions defined in section [INPUT LOCATION HANDLING](#subsection5).
- *Location stack* LS
In addition to the above a stack of locations, for backtracking. Locations
can put on the stack, removed from it, and removed with setting the current
location.
This information is implicitly used and modified by the instructions defined
in the sections [TERMINAL MATCHING](#subsection1) and [NONTERMINAL
MATCHING](#subsection2), and can be directly queried and modified by the
instructions defined in section [INPUT LOCATION HANDLING](#subsection5).
- *Match status* OK
A boolean value, the result of the last attempt at matching input. It is set
to __true__ if that attempt was successful, and __false__ otherwise.
This information is influenced by the instructions defined in the sections
[TERMINAL MATCHING](#subsection1), [NONTERMINAL MATCHING](#subsection2), and
[UNCONDITIONAL MATCHING](#subsection3). It is queried by the instructions
defined in the section [CONTROL FLOW](#subsection4).
- *Semantic value* SV
The semantic value associated with (generated by) the last attempt at
matching input. Contains either the empty string or a node for the abstract
syntax tree constructed from the input.
This information is influenced by the instructions defined in the sections
[SEMANTIC VALUES](#subsection7), and [AST STACK HANDLING](#subsection8).
- *AST stack* AS
A stack of partial abstract syntax trees constructed by the machine during
matching.
This information is influenced by the instructions defined in the sections
[SEMANTIC VALUES](#subsection7), and [AST STACK HANDLING](#subsection8).
- *AST Marker stack* MS
In addition to the above a stack of stacks, for backtracking. This is
actually a stack of markers into the AST stack, thus implicitly snapshooting
the state of the AST stack at some point in time. Markers can be put on the
stack, dropped from it, and used to roll back the AST stack to an earlier
state.
This information is influenced by the instructions defined in the sections
[SEMANTIC VALUES](#subsection7), and [AST STACK HANDLING](#subsection8).
- *Error status* ER
Error information associated with the last attempt at matching input.
Contains either the empty string or a list of 2 elements, a location in the
input and a list of error messages associated with it, in this order.
*Note* that error information can be set even if the last attempt at
matching input was successful. For example the *-operator (matching a
sub-expression zero or more times) in a parsing expression grammar is always
successful, even if it encounters a problem further in the input and has to
backtrack. Such problems must not be forgotten when continuing to match.
This information is queried and influenced by the instructions defined in
the sections [TERMINAL MATCHING](#subsection1), [NONTERMINAL
MATCHING](#subsection2), and [ERROR HANDLING](#subsection6).
- *Error stack* ES
In addition to the above a stack of error information, to allow the merging
of current and older error information when performing backtracking in
choices after an unsucessful match.
This information is queried and influenced by the instructions defined in
the sections [TERMINAL MATCHING](#subsection1), [NONTERMINAL
MATCHING](#subsection2), and [ERROR HANDLING](#subsection6).
- *Return stack* RS
A stack of program counter values, i.e. locations in the code controlling
the virtual machine, for the management of subroutine calls, i.e. the
matching of nonterminal symbols.
This information is queried and influenced by the instructions defined in
the section [NONTERMINAL MATCHING](#subsection2).
- *Nonterminal cache* NC
A cache of machine states (A 4-tuple containing a location in the input,
match status *OK*, semantic value *SV*, and error status *ER*) keyed by name
of nonterminal symbol and location in the input stream.
The key location is where machine started the attempt to match the named
nonterminal symbol, and the location in the value is where machine ended up
after the attempt completed, independent of the success of the attempt.
This status is queried and influenced by the instructions defined in the
section [NONTERMINAL MATCHING](#subsection2).
# <a name='section3'></a>MACHINE INSTRUCTIONS
With the machine state specified it is now possible to explain the instruction
set of ME virtual machines. They are grouped roughly by the machine state they
influence and/or query.
## <a name='subsection1'></a>TERMINAL MATCHING
First the instructions to match tokens from the input stream, and by extension
all terminal symbols.
These instructions are the only ones which may retrieve a new token from the
input stream. This is a *may* and not a *will* because the instructions will a
retrieve new token if, and only if the current location *CL* is at the head of
the stream. If the machine has backtracked (see __icl_rewind__) the instructions
will retrieve the token to compare against from the internal cache.
- __ict_advance__ *message*
This instruction tries to advance to the next token in the input stream,
i.e. the one after the current location *CL*. The instruction will fail if,
and only if the end of the input stream is reached, i.e. if there is no next
token.
The sucess/failure of the instruction is remembered in the match status
*OK*. In the case of failure the error status *ER* is set to the current
location and the message *message*. In the case of success the error status
*ER* is cleared, the new token is made the current token *CT*, and the new
location is made the current location *CL*.
The argument *message* is a reference to the string to put into the error
status *ER*, if such is needed.
- __ict_match_token__ *tok* *message*
This instruction tests the current token *CT* for equality with the argument
*tok* and records the result in the match status *OK*. The instruction fails
if the current token is not equal to *tok*.
In case of failure the error status *ER* is set to the current location *CL*
and the message *message*, and the current location *CL* is moved one token
backwards. Otherwise, i.e. upon success, the error status *ER* is cleared
and the current location *CL* is not touched.
- __ict_match_tokrange__ *tokbegin* *tokend* *message*
This instruction tests the current token *CT* for being in the range of
tokens from *tokbegin* to *tokend* (inclusive) and records the result in the
match status *OK*. The instruction fails if the current token is not inside
the range.
In case of failure the error status *ER* is set to the current location *CL*
and the message *message*, and the current location *CL* is moved one token
backwards. Otherwise, i.e. upon success, the error status *ER* is cleared
and the current location *CL* is not touched.
- __ict_match_tokclass__ *code* *message*
This instruction tests the current token *CT* for being a member of the
token class *code* and records the result in the match status *OK*. The
instruction fails if the current token is not a member of the specified
class.
In case of failure the error status *ER* is set to the current location *CL*
and the message *message*, and the current location *CL* is moved one token
backwards. Otherwise, i.e. upon success, the error status *ER* is cleared
and the current location *CL* is not touched.
Currently the following classes are legal:
* alnum
A token is accepted if it is a unicode alphabetical character, or a
digit.
* alpha
A token is accepted if it is a unicode alphabetical character.
* digit
A token is accepted if it is a unicode digit character.
* xdigit
A token is accepted if it is a hexadecimal digit character.
* punct
A token is accepted if it is a unicode punctuation character.
* space
A token is accepted if it is a unicode space character.
## <a name='subsection2'></a>NONTERMINAL MATCHING
The instructions in this section handle the matching of nonterminal symbols.
They query the nonterminal cache *NC* for saved information, and put such
information into the cache.
The usage of the cache is a performance aid for backtracking parsers, allowing
them to avoid an expensive rematch of complex nonterminal symbols if they have
been encountered before.
- __inc_restore__ *branchlabel* *nt*
This instruction checks if the nonterminal cache *NC* contains information
about the nonterminal symbol *nt*, at the current location *CL*. If that is
the case the instruction will update the machine state (current location
*CL*, match status *OK*, semantic value *SV*, and error status *ER*) with
the found information and continue execution at the instruction refered to
by the *branchlabel*. The new current location *CL* will be the last token
matched by the nonterminal symbol, i.e. belonging to it.
If no information was found the instruction will continue execution at the
next instruction.
Together with __icf_ntcall__ it is possible to generate code for memoized
and non-memoized matching of nonterminal symbols, either as subroutine
calls, or inlined in the caller.
- __inc_save__ *nt*
This instruction saves the current state of the machine (current location
*CL*, match status *OK*, semantic value *SV*, and error status *ER*), to the
nonterminal cache *NC*. It will also pop an entry from the location stack
*LS* and save it as the start location of the match.
It is expected to be called at the end of matching a nonterminal symbol,
with *nt* the name of the nonterminal symbol the code was working on. This
allows the instruction __inc_restore__ to check for and retrieve the data,
should we have to match this nonterminal symbol at the same location again,
during backtracking.
- __icf_ntcall__ *branchlabel*
This instruction invokes the code for matching the nonterminal symbol *nt*
as a subroutine. To this end it stores the current program counter *PC* on
the return stack *RS*, the current location *CL* on the location stack *LS*,
and then continues execution at the address *branchlabel*.
The next matching __icf_ntreturn__ will cause the execution to continue at
the instruction coming after the call.
- __icf_ntreturn__
This instruction will pop an entry from the return stack *RS*, assign it to
the program counter *PC*, and then continue execution at the new address.
## <a name='subsection3'></a>UNCONDITIONAL MATCHING
The instructions in this section are the remaining match operators. They change
the match status *OK* directly and unconditionally.
- __iok_ok__
This instruction sets the match status *OK* to __true__, indicating a
successful match.
- __iok_fail__
This instruction sets the match status *OK* to __false__, indicating a
failed match.
- __iok_negate__
This instruction negates the match status *OK*, turning a failure into a
success and vice versa.
## <a name='subsection4'></a>CONTROL FLOW
The instructions in this section implement both conditional and unconditional
control flow. The conditional jumps query the match status *OK*.
- __icf_jalways__ *branchlabel*
This instruction sets the program counter *PC* to the address specified by
*branchlabel* and then continues execution from there. This is an
unconditional jump.
- __icf_jok__ *branchlabel*
This instruction sets the program counter *PC* to the address specified by
*branchlabel*. This happens if, and only if the match status *OK* indicates
a success. Otherwise it simply continues execution at the next instruction.
This is a conditional jump.
- __icf_jfail__ *branchlabel*
This instruction sets the program counter *PC* to the address specified by
*branchlabel*. This happens if, and only if the match status *OK* indicates
a failure. Otherwise it simply continues execution at the next instruction.
This is a conditional jump.
- __icf_halt__
This instruction halts the machine and blocks any further execution.
## <a name='subsection5'></a>INPUT LOCATION HANDLING
The instructions in this section are for backtracking, they manipulate the
current location *CL* of the machine state. They allow a user of the machine to
query and save locations in the input, and to rewind the current location *CL*
to saved locations, making them one of the components enabling the
implementation of backtracking parsers.
- __icl_push__
This instruction pushes a copy of the current location *CL* on the location
stack *LS*.
- __icl_rewind__
This instruction pops an entry from the location stack *LS* and then moves
the current location *CL* back to this point in the input.
- __icl_pop__
This instruction pops an entry from the location stack *LS* and discards it.
## <a name='subsection6'></a>ERROR HANDLING
The instructions in this section provide read and write access to the error
status *ER* of the machine.
- __ier_push__
This instruction pushes a copy of the current error status *ER* on the error
stack *ES*.
- __ier_clear__
This instruction clears the error status *ER*.
- __ier_nonterminal__ *message*
This instruction checks if the error status *ER* contains an error whose
location is just past the location found in the top entry of the location
stack *LS*. Nothing happens if no such error is found. Otherwise the found
error is replaced by an error at the location found on the stack, having the
message *message*.
- __ier_merge__
This instruction pops an entry from the error stack *ES*, merges it with the
current error status *ER* and stores the result of the merge as the new
error status *ER*.
The merge is performed as described below:
If one of the two error states is empty the other is chosen. If neither
error state is empty, and refering to different locations, then the error
state with the location further in the input is chosen. If both error states
refer to the same location their messages are merged (with removing
duplicates).
## <a name='subsection7'></a>SEMANTIC VALUES
The instructions in this section manipulate the semantic value *SV*.
- __isv_clear__
This instruction clears the semantic value *SV*.
- __isv_terminal__
This instruction creates a terminal AST node for the current token *CT*,
makes it the semantic value *SV*, and also pushes the node on the AST stack
*AS*.
- __isv_nonterminal_leaf__ *nt*
This instruction creates a nonterminal AST node without any children for the
nonterminal *nt*, and makes it the semantic value *SV*.
This instruction should be executed if, and only if the match status *OK*
indicates a success. In the case of a failure __isv_clear__ should be
called.
- __isv_nonterminal_range__ *nt*
This instruction creates a nonterminal AST node for the nonterminal *nt*,
with a single terminal node as its child, and makes this AST the semantic
value *SV*. The terminal node refers to the input string from the location
found on top of the location stack *LS* to the current location *CL* (both
inclusive).
This instruction should be executed if, and only if the match status *OK*
indicates a success. In the case of a failure __isv_clear__ should be
called.
- __isv_nonterminal_reduce__ *nt*
This instruction creates a nonterminal AST node for the nonterminal *nt* and
makes it the semantic value *SV*.
All entries on the AST stack *AS* above the marker found in the top entry of
the AST Marker stack *MS* become children of the new node, with the entry at
the stack top becoming the rightmost child. If the AST Marker stack *MS* is
empty the whole stack is used. The AST marker stack *MS* is left unchanged.
This instruction should be executed if, and only if the match status *OK*
indicates a success. In the case of a failure __isv_clear__ should be
called.
## <a name='subsection8'></a>AST STACK HANDLING
The instructions in this section manipulate the AST stack *AS*, and the AST
Marker stack *MS*.
- __ias_push__
This instruction pushes the semantic value *SV* on the AST stack *AS*.
- __ias_mark__
This instruction pushes a marker for the current state of the AST stack *AS*
on the AST Marker stack *MS*.
- __ias_mrewind__
This instruction pops an entry from the AST Marker stack *MS* and then
proceeds to pop entries from the AST stack *AS* until the state represented
by the popped marker has been reached again. Nothing is done if the AST
stack *AS* is already smaller than indicated by the popped marker.
- __ias_mpop__
This instruction pops an entry from the AST Marker stack *MS* and discards
it.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_me* 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.
# <a name='keywords'></a>KEYWORDS
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_peg/peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
|
[//000000001]: # (grammar::peg - Grammar operations and usage)
[//000000002]: # (Generated from file 'peg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::peg(n) 0.1 tcllib "Grammar operations and usage")
# NAME
grammar::peg - Create and manipulate parsing expression grammars
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TERMS & CONCEPTS](#subsection1)
- [CONTAINER CLASS API](#subsection2)
- [CONTAINER OBJECT API](#subsection3)
- [PARSING EXPRESSIONS](#subsection4)
- [PARSING EXPRESSION GRAMMARS](#section2)
- [REFERENCES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit
package require grammar::peg ?0.1?
[__::grammar::peg__ *pegName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*?](#1)
[*pegName* __destroy__](#2)
[*pegName* __clear__](#3)
[*pegName* __=__ *srcPEG*](#4)
[*pegName* __-->__ *dstPEG*](#5)
[*pegName* __serialize__](#6)
[*pegName* __deserialize__ *serialization*](#7)
[*pegName* __is valid__](#8)
[*pegName* __start__ ?*pe*?](#9)
[*pegName* __nonterminals__](#10)
[*pegName* __nonterminal add__ *nt* *pe*](#11)
[*pegName* __nonterminal delete__ *nt1* ?*nt2* ...?](#12)
[*pegName* __nonterminal exists__ *nt*](#13)
[*pegName* __nonterminal rename__ *nt* *ntnew*](#14)
[*pegName* __nonterminal mode__ *nt* ?*mode*?](#15)
[*pegName* __nonterminal rule__ *nt*](#16)
[*pegName* __unknown nonterminals__](#17)
# <a name='description'></a>DESCRIPTION
This package provides a container class for *parsing expression grammars*
(Short: PEG). It allows the incremental definition of the grammar, its
manipulation and querying of the definition. The package neither provides
complex operations on the grammar, nor has it the ability to execute a grammar
definition for a stream of symbols. Two packages related to this one are
__grammar::mengine__ and __grammar::peg::interpreter__. The first of them
defines a general virtual machine for the matching of a character stream, and
the second implements an interpreter for parsing expression grammars on top of
that virtual machine.
## <a name='subsection1'></a>TERMS & CONCEPTS
PEGs are similar to context-free grammars, but not equivalent; in some cases
PEGs are strictly more powerful than context-free grammars (there exist PEGs for
some non-context-free languages). The formal mathematical definition of parsing
expressions and parsing expression grammars can be found in section [PARSING
EXPRESSION GRAMMARS](#section2).
In short, we have *terminal symbols*, which are the most basic building blocks
for *sentences*, and *nonterminal symbols* with associated *parsing
expressions*, defining the grammatical structure of the sentences. The two sets
of symbols are distinctive, and do not overlap. When speaking about symbols the
word "symbol" is often left out. The union of the sets of terminal and
nonterminal symbols is called the set of *symbols*.
Here the set of *terminal symbols* is not explicitly managed, but implicitly
defined as the set of all characters. Note that this means that we inherit from
Tcl the ability to handle all of Unicode.
A pair of *nonterminal* and *[parsing
expression](../../../../index.md#parsing_expression)* is also called a
*grammatical rule*, or *rule* for short. In the context of a rule the
nonterminal is often called the left-hand-side (LHS), and the parsing expression
the right-hand-side (RHS).
The *start expression* of a grammar is a parsing expression from which all the
sentences contained in the language specified by the grammar are *derived*. To
make the understanding of this term easier let us assume for a moment that the
RHS of each rule, and the start expression, is either a sequence of symbols, or
a series of alternate parsing expressions. In the latter case the rule can be
seen as a set of rules, each providing one alternative for the nonterminal. A
parsing expression A' is now a derivation of a parsing expression A if we pick
one of the nonterminals N in the expression, and one of the alternative rules R
for N, and then replace the nonterminal in A with the RHS of the chosen rule.
Here we can see why the terminal symbols are called such. They cannot be
expanded any further, thus terminate the process of deriving new expressions. An
example
Rules
(1) A <- a B c
(2a) B <- d B
(2b) B <- e
Some derivations, using starting expression A.
A -/1/-> a B c -/2a/-> a d B c -/2b/-> a d e c
A derived expression containing only terminal symbols is a *sentence*. The set
of all sentences which can be derived from the start expression is the
*language* of the grammar.
Some definitions for nonterminals and expressions:
1. A nonterminal A is called *reachable* if it is possible to derive a parsing
expression from the start expression which contains A.
1. A nonterminal A is called *useful* if it is possible to derive a sentence
from it.
1. A nonterminal A is called *recursive* if it is possible to derive a parsing
expression from it which contains A, again.
1. The *FIRST set* of a nonterminal A contains all the symbols which can occur
of as the leftmost symbol in a parsing expression derived from A. If the
FIRST set contains A itself then that nonterminal is called
*left-recursive*.
1. The *LAST set* of a nonterminal A contains all the symbols which can occur
of as the rightmost symbol in a parsing expression derived from A. If the
LAST set contains A itself then that nonterminal is called
*right-recursive*.
1. The *FOLLOW set* of a nonterminal A contains all the symbols which can
occur after A in a parsing expression derived from the start expression.
1. A nonterminal (or parsing expression) is called *nullable* if the empty
sentence can be derived from it.
And based on the above definitions for grammars:
1. A grammar G is *recursive* if and only if it contains a nonterminal A which
is recursive. The terms *left-* and *right-recursive*, and *useful* are
analogously defined.
1. A grammar is *minimal* if it contains only *reachable* and *useful*
nonterminals.
1. A grammar is *wellformed* if it is not left-recursive. Such grammars are
also *complete*, which means that they always succeed or fail on all input
sentences. For an incomplete grammar on the other hand input sentences
exist for which an attempt to match them against the grammar will not
terminate.
1. As we wish to allow ourselves to build a grammar incrementally in a
container object we will encounter stages where the RHS of one or more
rules reference symbols which are not yet known to the container. Such a
grammar we call *invalid*. We cannot use the term *incomplete* as this term
is already taken, see the last item.
## <a name='subsection2'></a>CONTAINER CLASS API
The package exports the API described here.
- <a name='1'></a>__::grammar::peg__ *pegName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*?
The command creates a new container object for a parsing expression grammar
and returns the fully qualified name of the object command as its result.
The API the returned command is following is described in the section
[CONTAINER OBJECT API](#subsection3). It may be used to invoke various
operations on the container and the grammar within.
The new container, i.e. grammar will be empty if no *src* is specified.
Otherwise it will contain a copy of the grammar contained in the *src*. The
*src* has to be a container object reference for all operators except
__deserialize__. The __deserialize__ operator requires *src* to be the
serialization of a parsing expression grammar instead.
An empty grammar has no nonterminal symbols, and the start expression is the
empty expression, i.e. epsilon. It is *valid*, but not *useful*.
## <a name='subsection3'></a>CONTAINER OBJECT API
All grammar container objects provide the following methods for the manipulation
of their contents:
- <a name='2'></a>*pegName* __destroy__
Destroys the grammar, including its storage space and associated command.
- <a name='3'></a>*pegName* __clear__
Clears out the definition of the grammar contained in *pegName*, but does
*not* destroy the object.
- <a name='4'></a>*pegName* __=__ *srcPEG*
Assigns the contents of the grammar contained in *srcPEG* to *pegName*,
overwriting any existing definition. This is the assignment operator for
grammars. It copies the grammar contained in the grammar object *srcPEG*
over the grammar definition in *pegName*. The old contents of *pegName* are
deleted by this operation.
This operation is in effect equivalent to
*pegName* __deserialize__ [*srcPEG* __serialize__]
- <a name='5'></a>*pegName* __-->__ *dstPEG*
This is the reverse assignment operator for grammars. It copies the
automation contained in the object *pegName* over the grammar definition in
the object *dstPEG*. The old contents of *dstPEG* are deleted by this
operation.
This operation is in effect equivalent to
*dstPEG* __deserialize__ [*pegName* __serialize__]
- <a name='6'></a>*pegName* __serialize__
This method serializes the grammar stored in *pegName*. In other words it
returns a tcl *value* completely describing that grammar. This allows, for
example, the transfer of grammars over arbitrary channels, persistence, etc.
This method is also the basis for both the copy constructor and the
assignment operator.
The result of this method has to be semantically identical over all
implementations of the __grammar::peg__ interface. This is what will enable
us to copy grammars between different implementations of the same interface.
The result is a list of four elements with the following structure:
The constant string __grammar::peg__.
A dictionary. Its keys are the names of all known nonterminal symbols, and
their associated values are the parsing expressions describing their
sentennial structure.
A dictionary. Its keys are the names of all known nonterminal symbols, and
their associated values hints to a matcher regarding the semantic values
produced by the symbol.
The last item is a parsing expression, the *start expression* of the
grammar.
Assuming the following PEG for simple mathematical expressions
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
Sign <- '+' / '-'
Number <- Sign? Digit+
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)
MulOp <- '*' / '/'
Factor <- Term (AddOp Term)*
AddOp <- '+'/'-'
Term <- Number
a possible serialization is
grammar::peg \\
{Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
Factor {x Term {* {x AddOp Term}}} \\
Term Number \\
MulOp {/ * /} \\
AddOp {/ + -} \\
Number {x {? Sign} {+ Digit}} \\
Sign {/ + -} \\
Digit {/ 0 1 2 3 4 5 6 7 8 9} \\
} \\
{Expression value Factor value \\
Term value MulOp value \\
AddOp value Number value \\
Sign value Digit value \\
}
Expression
A possible one, because the order of the nonterminals in the dictionary is
not relevant.
- <a name='7'></a>*pegName* __deserialize__ *serialization*
This is the complement to __serialize__. It replaces the grammar definition
in *pegName* with the grammar described by the *serialization* value. The
old contents of *pegName* are deleted by this operation.
- <a name='8'></a>*pegName* __is valid__
A predicate. It tests whether the PEG in *pegName* is *valid*. See section
[TERMS & CONCEPTS](#subsection1) for the definition of this grammar
property. The result is a boolean value. It will be set to __true__ if the
PEG has the tested property, and __false__ otherwise.
- <a name='9'></a>*pegName* __start__ ?*pe*?
This method defines the *start expression* of the grammar. It replaces the
previously defined start expression with the parsing expression *pe*. The
method fails and throws an error if *pe* does not contain a valid parsing
expression as specified in the section [PARSING EXPRESSIONS](#subsection4).
In that case the existing start expression is not changed. The method
returns the empty string as its result.
If the method is called without an argument it will return the currently
defined start expression.
- <a name='10'></a>*pegName* __nonterminals__
Returns the set of all nonterminal symbols known to the grammar.
- <a name='11'></a>*pegName* __nonterminal add__ *nt* *pe*
This method adds the nonterminal *nt* and its associated parsing expression
*pe* to the set of nonterminal symbols and rules of the PEG contained in the
object *pegName*. The method fails and throws an error if either the string
*nt* is already known as a symbol of the grammar, or if *pe* does not
contain a valid parsing expression as specified in the section [PARSING
EXPRESSIONS](#subsection4). In that case the current set of nonterminal
symbols and rules is not changed. The method returns the empty string as its
result.
- <a name='12'></a>*pegName* __nonterminal delete__ *nt1* ?*nt2* ...?
This method removes the named symbols *nt1*, *nt2* from the set of
nonterminal symbols of the PEG contained in the object *pegName*. The method
fails and throws an error if any of the strings is not known as a
nonterminal symbol. In that case the current set of nonterminal symbols is
not changed. The method returns the empty string as its result.
The stored grammar becomes invalid if the deleted nonterminals are
referenced by the RHS of still-known rules.
- <a name='13'></a>*pegName* __nonterminal exists__ *nt*
A predicate. It tests whether the nonterminal symbol *nt* is known to the
PEG in *pegName*. The result is a boolean value. It will be set to __true__
if the symbol *nt* is known, and __false__ otherwise.
- <a name='14'></a>*pegName* __nonterminal rename__ *nt* *ntnew*
This method renames the nonterminal symbol *nt* to *ntnew*. The method fails
and throws an error if either *nt* is not known as a nonterminal, or if
*ntnew* is a known symbol. The method returns the empty string as its
result.
- <a name='15'></a>*pegName* __nonterminal mode__ *nt* ?*mode*?
This mode returns or sets the semantic mode associated with the nonterminal
symbol *nt*. If no *mode* is specified the current mode of the nonterminal
is returned. Otherwise the current mode is set to *mode*. The method fails
and throws an error if *nt* is not known as a nonterminal. The grammar
interpreter implemented by the package __grammar::peg::interpreter__
recognizes the following modes:
* value
The semantic value of the nonterminal is the abstract syntax tree
created from the AST's of the RHS and a node for the nonterminal itself.
* match
The semantic value of the nonterminal is an the abstract syntax tree
consisting of single a node for the string matched by the RHS. The ASTs
generated by the RHS are discarded.
* leaf
The semantic value of the nonterminal is an the abstract syntax tree
consisting of single a node for the nonterminal itself. The ASTs
generated by the RHS are discarded.
* discard
The nonterminal has no semantic value. The ASTs generated by the RHS are
discarded (as well).
- <a name='16'></a>*pegName* __nonterminal rule__ *nt*
This method returns the parsing expression associated with the nonterminal
*nt*. The method fails and throws an error if *nt* is not known as a
nonterminal.
- <a name='17'></a>*pegName* __unknown nonterminals__
This method returns a list containing the names of all nonterminal symbols
which are referenced on the RHS of a grammatical rule, but have no rule
definining their structure. In other words, a list of the nonterminal
symbols which make the grammar invalid. The grammar is valid if this list is
empty.
## <a name='subsection4'></a>PARSING EXPRESSIONS
Various methods of PEG container objects expect a parsing expression as their
argument, or will return such. This section specifies the format such parsing
expressions are in.
1. The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
1. The string __alnum__ is an atomic parsing expression. It matches any
alphanumeric character.
1. The string __alpha__ is an atomic parsing expression. It matches any
alphabetical character.
1. The string __dot__ is an atomic parsing expression. It matches any
character.
1. The expression [list t __x__] is an atomic parsing expression. It matches
the terminal string __x__.
1. The expression [list n __A__] is an atomic parsing expression. It matches
the nonterminal __A__.
1. For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered choice*,
aka *prioritized choice*.
1. For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
1. For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or more
repetitions.
1. For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing one
or more repetitions.
1. For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
1. For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
1. For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
Examples of parsing expressions where already shown, in the description of the
method __serialize__.
# <a name='section2'></a>PARSING EXPRESSION GRAMMARS
For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where
- VN is a set of *nonterminal symbols*,
- VT is a set of *terminal symbols*,
- R is a finite set of rules, where each rule is a pair (A,e), A in VN, and
*[e](../../../../index.md#e)* a *[parsing
expression](../../../../index.md#parsing_expression)*.
- eS is a parsing expression, the *start expression*.
Further constraints are
- The intersection of VN and VT is empty.
- For all A in VT exists exactly one pair (A,e) in R. In other words, R is a
function from nonterminal symbols to parsing expressions.
Parsing expression are inductively defined via
- The empty string (epsilon) is a parsing expression.
- A terminal symbol *a* is a parsing expression.
- A nonterminal symbol *A* is a parsing expression.
- *e1**e2* is a parsing expression for parsing expressions *e1* and *2*. This
is called *sequence*.
- *e1*/*e2* is a parsing expression for parsing expressions *e1* and *2*. This
is called *ordered choice*.
- *[e](../../../../index.md#e)** is a parsing expression for parsing
expression *[e](../../../../index.md#e)*. This is called *zero-or-more
repetitions*, also known as *kleene closure*.
- *[e](../../../../index.md#e)*+ is a parsing expression for parsing
expression *[e](../../../../index.md#e)*. This is called *one-or-more
repetitions*, also known as *positive kleene closure*.
- !*[e](../../../../index.md#e)* is a parsing expression for parsing
expression *e1*. This is called a *not lookahead predicate*.
- &*[e](../../../../index.md#e)* is a parsing expression for parsing
expression *e1*. This is called an *and lookahead predicate*.
PEGs are used to define a grammatical structure for streams of symbols over VT.
They are a modern phrasing of older formalisms invented by Alexander Birham.
These formalisms were called TS (TMG recognition scheme), and gTS (generalized
TS). Later they were renamed to TPDL (Top-Down Parsing Languages) and gTPDL
(generalized TPDL).
They can be easily implemented by recursive descent parsers with backtracking.
This makes them relatives of LL(k) Context-Free Grammars.
# <a name='section3'></a>REFERENCES
1. [The Packrat Parsing and Parsing Expression Grammars
Page](http://www.pdos.lcs.mit.edu/~baford/packrat/), by Bryan Ford,
Massachusetts Institute of Technology. This is the main entry page to PEGs,
and their realization through Packrat Parsers.
1. [Parsing Techniques - A Practical Guide
](http://www.cs.vu.nl/~dick/PTAPG.html), an online book offering a clear,
accessible, and thorough discussion of many different parsing techniques
with their interrelations and applicabilities, including error recovery
techniques.
1. [Compilers and Compiler Generators](http://scifac.ru.ac.za/compilers/), an
online book using CoCo/R, a generator for recursive descent parsers.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_peg* 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.
# <a name='keywords'></a>KEYWORDS
[LL(k)](../../../../index.md#ll_k_), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[parsing](../../../../index.md#parsing), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/grammar_peg/peg_interp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
[//000000001]: # (grammar::peg::interp - Grammar operations and usage)
[//000000002]: # (Generated from file 'peg_interp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (grammar::peg::interp(n) 0.1.1 tcllib "Grammar operations and usage")
# NAME
grammar::peg::interp - Interpreter for parsing expression grammars
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [THE INTERPRETER API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require grammar::mengine ?0.1?
package require grammar::peg::interp ?0.1.1?
[__::grammar::peg::interp::setup__ *peg*](#1)
[__::grammar::peg::interp::parse__ *nextcmd* *errorvar* *astvar*](#2)
# <a name='description'></a>DESCRIPTION
This package provides commands for the controlled matching of a character stream
via a parsing expression grammar and the creation of an abstract syntax tree for
the stream and partials.
It is built on top of the virtual machine provided by the package
__[grammar::me::tcl](../grammar_me/me_tcl.md)__ and directly interprets the
parsing expression grammar given to it. In other words, the grammar is *not*
pre-compiled but used as is.
The grammar to be interpreted is taken from a container object following the
interface specified by the package __grammar::peg::container__. Only the
relevant parts are copied into the state of this package.
It should be noted that the package provides exactly one instance of the
interpreter, and interpreting a second grammar requires the user to either abort
or complete a running interpretation, or to put them into different Tcl
interpreters.
Also of note is that the implementation assumes a pull-type handling of the
input. In other words, the interpreter pulls characters from the input stream as
it needs them. For usage in a push environment, i.e. where the environment
pushes new characters as they come we have to put the engine into its own
thread.
# <a name='section2'></a>THE INTERPRETER API
The package exports the following API
- <a name='1'></a>__::grammar::peg::interp::setup__ *peg*
This command (re)initializes the interpreter. It returns the empty string.
This command has to be invoked first, before any matching run.
Its argument *peg* is the handle of an object containing the parsing
expression grammar to interpret. This grammar has to be valid, or an error
will be thrown.
- <a name='2'></a>__::grammar::peg::interp::parse__ *nextcmd* *errorvar* *astvar*
This command interprets the loaded grammar and tries to match it against the
stream of characters represented by the command prefix *nextcmd*.
The command prefix *nextcmd* represents the input stream of characters and
is invoked by the interpreter whenever the a new character from the stream
is required. The callback has to return either the empty list, or a list of
4 elements containing the token, its lexeme attribute, and its location as
line number and column index, in this order. The empty list is the signal
that the end of the input stream has been reached. The lexeme attribute is
stored in the terminal cache, but otherwise not used by the machine.
The result of the command is a boolean value indicating whether the matching
process was successful (__true__), or not (__false__). In the case of a
match failure error information will be stored into the variable referenced
by *errorvar*. The variable referenced by *astvar* will always contain the
generated abstract syntax tree, however in the case of an error it will be
only partial and possibly malformed.
The abstract syntax tree is represented by a nested list, as described in
section __AST VALUES__ of document
*[grammar::me_ast](../grammar_me/me_ast.md)*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *grammar_peg* 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.
# <a name='keywords'></a>KEYWORDS
[LL(k)](../../../../index.md#ll_k_), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parsing](../../../../index.md#parsing), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Grammars and finite automata
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005-2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/hook/hook.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
[//000000001]: # (hook - Hooks)
[//000000002]: # (Generated from file 'hook.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (hook(n) 0.1 tcllib "Hooks")
# NAME
hook - Hooks
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Concepts](#section2)
- [Introduction](#subsection1)
- [Bindings](#subsection2)
- [Subjects and observers](#subsection3)
- [Reference](#section3)
- [Example](#section4)
- [Credits](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require hook ?0.1?
[__hook__ __bind__ ?*subject*? ?*hook*? ?*observer*? ?*cmdPrefix*?](#1)
[__hook__ __call__ *subject* *hook* ?*args*...?](#2)
[__hook__ __forget__ *object*](#3)
[__hook__ __cget__ *option*](#4)
[__hook__ __configure__ __option__ *value* ...](#5)
# <a name='description'></a>DESCRIPTION
This package provides the __hook__ ensemble command, which implements the
Subject/Observer pattern. It allows *subjects*, which may be *modules*,
*objects*, *widgets*, and so forth, to synchronously call *hooks* which may be
bound to an arbitrary number of subscribers, called *observers*. A subject may
call any number of distinct hooks, and any number of observers can bind
callbacks to a particular hook called by a particular subject. Hook bindings can
be queried and deleted.
This man page is intended to be a reference only.
# <a name='section2'></a>Concepts
## <a name='subsection1'></a>Introduction
Tcl modules usually send notifications to other modules in two ways: via Tk
events, and via callback options like the text widget's __-yscrollcommand__
option. Tk events are available only in Tk, and callback options require tight
coupling between the modules sending and receiving the notification.
Loose coupling between sender and receiver is often desirable, however. In
Model/View/Controller terms, a View can send a command (stemming from user
input) to the Controller, which updates the Model. The Model can then call a
hook *to which all relevant Views subscribe.* The Model is decoupled from the
Views, and indeed need not know whether any Views actually exist. At present,
Tcl/Tk has no standard mechanism for implementing loose coupling of this kind.
This package defines a new command, __hook__, which implements just such a
mechanism.
## <a name='subsection2'></a>Bindings
The __hook__ command manages a collection of hook bindings. A hook binding has
four elements:
1. A *[subject](../../../../index.md#subject)*: the name of the entity that
will be calling the hook.
1. The *[hook](../../../../index.md#hook)* itself. A hook usually reflects
some occurrence in the life of the
*[subject](../../../../index.md#subject)* that other entities might care to
know about. A *[hook](../../../../index.md#hook)* has a name, and may also
have arguments. Hook names are arbitrary strings. Each
*[subject](../../../../index.md#subject)* must document the names and
arguments of the hooks it can call.
1. The name of the *[observer](../../../../index.md#observer)* that wishes to
receive the *[hook](../../../../index.md#hook)* from the
*[subject](../../../../index.md#subject)*.
1. A command prefix to which the *[hook](../../../../index.md#hook)* arguments
will be appended when the binding is executed.
## <a name='subsection3'></a>Subjects and observers
For convenience, this document collectively refers to subjects and observers as
*objects*, while placing no requirements on how these *objects* are actually
implemented. An object can be a __[TclOO](../../../../index.md#tcloo)__ or
__[Snit](../../../../index.md#snit)__ or __XOTcl__ object, a Tcl command, a
namespace, a module, a pseudo-object managed by some other object (as tags are
managed by the Tk text widget) or simply a well-known name.
Subject and observer names are arbitrary strings; however, as __hook__ might be
used at the package level, it's necessary to have conventions that avoid name
collisions between packages written by different people.
Therefore, any subject or observer name used in core or package level code
should look like a Tcl command name, and should be defined in a namespace owned
by the package. Consider, for example, an ensemble command __::foo__ that
creates a set of pseudo-objects and uses __hook__ to send notifications. The
pseudo-objects have names that are not commands and exist in their own
namespace, rather like file handles do. To avoid name collisions with subjects
defined by other packages, users of __hook__, these __::foo__ handles should
have names like __::foo::1__, __::foo::2__, and so on.
Because object names are arbitrary strings, application code can use whatever
additional conventions are dictated by the needs of the application.
# <a name='section3'></a>Reference
Hook provides the following commands:
- <a name='1'></a>__hook__ __bind__ ?*subject*? ?*hook*? ?*observer*? ?*cmdPrefix*?
This subcommand is used to create, update, delete, and query hook bindings.
Called with no arguments it returns a list of the subjects with hooks to
which observers are currently bound.
Called with one argument, a *subject*, it returns a list of the subject's
hooks to which observers are currently bound.
Called with two arguments, a *subject* and a *hook*, it returns a list of
the observers which are currently bound to this *subject* and *hook*.
Called with three arguments, a *subject*, a *hook*, and an *observer*, it
returns the binding proper, the command prefix to be called when the hook is
called, or the empty string if there is no such binding.
Called with four arguments, it creates, updates, or deletes a binding. If
*cmdPrefix* is the empty string, it deletes any existing binding for the
*subject*, *hook*, and *observer*; nothing is returned. Otherwise,
*cmdPrefix* must be a command prefix taking as many additional arguments as
are documented for the *subject* and *hook*. The binding is added or
updated, and the observer is returned.
If the *observer* is the empty string, "", it will create a new binding
using an automatically generated observer name of the form
__::hook::ob__<__number__>. The automatically generated name will be
returned, and can be used to query, update, and delete the binding as usual.
If automated observer names are always used, the observer name effectively
becomes a unique binding ID.
It is possible to call __hook bind__ to create or delete a binding to a
*subject* and *hook* while in an observer binding for that same *subject*
and *hook*. The following rules determine what happens when
hook bind $s $h $o $binding
is called during the execution of
hook call $s $h
No binding is ever called after it is deleted.
When a binding is called, the most recently given command prefix is always
used.
The set of observers whose bindings are to be called is determined when this
method begins to execute, and does not change thereafter, except that
deleted bindings are not called.
In particular:
If __$o__s binding to __$s__ and __$h__ is deleted, and __$o__s binding has
not yet been called during this execution of
hook call $s $h
it will not be called. (Note that it might already have been called; and in
all likelihood, it is probably deleting itself.)
If __$o__ changes the command prefix that's bound to __$s__ and __$h__, and
if __$o__s binding has not yet been called during this execution of
hook call $s $h
the new binding will be called when the time comes. (But again, it is
probably __$o__s binding that is is making the change.)
If a new observer is bound to __$s__ and __$h__, its binding will not be
called until the next invocation of
hook call $s $h
- <a name='2'></a>__hook__ __call__ *subject* *hook* ?*args*...?
This command is called when the named *subject* wishes to call the named
*hook*. All relevant bindings are called with the specified arguments in the
global namespace. Note that the bindings are called synchronously, before
the command returns; this allows the *args* to include references to
entities that will be cleaned up as soon as the hook has been called.
The order in which the bindings are called is not guaranteed. If sequence
among observers must be preserved, define one observer and have its bindings
call the other callbacks directly in the proper sequence.
Because the __hook__ mechanism is intended to support loose coupling, it is
presumed that the *subject* has no knowledge of the observers, nor any
expectation regarding return values. This has a number of implications:
__hook call__ returns the empty string.
Normal return values from observer bindings are ignored.
Errors and other exceptional returns propagate normally by default. This
will rarely be what is wanted, because the subjects usually have no
knowledge of the observers and will therefore have no particular competence
at handling their errors. That makes it an application issue, and so
applications will usually want to define an __-errorcommand__.
If the __-errorcommand__ configuration option has a non-empty value, its
value will be invoked for all errors and other exceptional returns in
observer bindings. See __hook configure__, below, for more information on
configuration options.
- <a name='3'></a>__hook__ __forget__ *object*
This command deletes any existing bindings in which the named *object*
appears as either the *[subject](../../../../index.md#subject)* or the
*[observer](../../../../index.md#observer)*. Bindings deleted by this method
will never be called again. In particular,
If an observer is forgotten during a call to __hook call__, any uncalled
binding it might have had to the relevant subject and hook will *not* be
called subsequently.
If a subject __$s__ is forgotten during a call to
hook call $s $h
then __hook call__ will return as soon as the current binding returns. No
further bindings will be called.
- <a name='4'></a>__hook__ __cget__ *option*
This command returns the value of one of the __hook__ command's
configuration options.
- <a name='5'></a>__hook__ __configure__ __option__ *value* ...
This command sets the value of one or more of the __hook__ command's
configuration options:
* __-errorcommand__ *cmdPrefix*
If the value of this option is the empty string, "", then errors and
other exception returns in binding scripts are propagated normally.
Otherwise, it must be a command prefix taking three additional
arguments:
a 4-element list {subject hook arglist observer},
the result string, and
the return options dictionary.
Given this information, the __-errorcommand__ can choose to log the
error, call __interp bgerror__, delete the errant binding (thus
preventing the error from arising a second time) and so forth.
* __-tracecommand__ *cmdPrefix*
The option's value should be a command prefix taking four arguments:
a *[subject](../../../../index.md#subject)*,
a *[hook](../../../../index.md#hook)*,
a list of the hook's argument values, and
a list of *objects* the hook was called for.
The command will be called for each hook that is called. This allows the
application to trace hook execution for debugging purposes.
# <a name='section4'></a>Example
The __::model__ module calls the <Update> hook in response to commands that
change the model's data:
hook call ::model <Update>
The __.view__ megawidget displays the model state, and needs to know about model
updates. Consequently, it subscribes to the ::model's <Update> hook.
hook bind ::model <Update> .view [list .view ModelUpdate]
When the __::model__ calls the hook, the __.view__s ModelUpdate subcommand will
be called.
Later the __.view__ megawidget is destroyed. In its destructor, it tells the
*[hook](../../../../index.md#hook)* that it no longer exists:
hook forget .view
All bindings involving __.view__ are deleted.
# <a name='section5'></a>Credits
Hook has been designed and implemented by William H. Duquette.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *hook* 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.
# <a name='see-also'></a>SEE ALSO
[uevent(n)](../uev/uevent.md)
# <a name='keywords'></a>KEYWORDS
[callback](../../../../index.md#callback), [event](../../../../index.md#event),
[hook](../../../../index.md#hook), [observer](../../../../index.md#observer),
[producer](../../../../index.md#producer),
[publisher](../../../../index.md#publisher),
[subject](../../../../index.md#subject),
[subscriber](../../../../index.md#subscriber),
[uevent](../../../../index.md#uevent)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010, by William H. Duquette
|
Added embedded/md/tcllib/files/modules/html/html.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
|
[//000000001]: # (html - HTML Generation)
[//000000002]: # (Generated from file 'html.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (html(n) 1.4.4 tcllib "HTML Generation")
# NAME
html - Procedures to generate HTML structures
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require html ?1.4.4?
[__::html::author__ *author*](#1)
[__::html::bodyTag__ *args*](#2)
[__::html::cell__ *param value* ?*tag*?](#3)
[__::html::checkbox__ *name value*](#4)
[__::html::checkSet__ *key sep list*](#5)
[__::html::checkValue__ *name* ?*value*?](#6)
[__::html::closeTag__](#7)
[__::html::default__ *key* ?*param*?](#8)
[__::html::description__ *description*](#9)
[__::html::end__](#10)
[__::html::eval__ *arg* ?*args*?](#11)
[__::html::extractParam__ *param key* ?*varName*?](#12)
[__::html::font__ *args*](#13)
[__::html::for__ *start test next body*](#14)
[__::html::foreach__ *varlist1 list1* ?*varlist2 list2 ...*? *body*](#15)
[__::html::formValue__ *name* ?*defvalue*?](#16)
[__::html::getFormInfo__ *args*](#17)
[__::html::getTitle__](#18)
[__::html::h__ *level string* ?*param*?](#19)
[__::html::h1__ *string* ?*param*?](#20)
[__::html::h2__ *string* ?*param*?](#21)
[__::html::h3__ *string* ?*param*?](#22)
[__::html::h4__ *string* ?*param*?](#23)
[__::html::h5__ *string* ?*param*?](#24)
[__::html::h6__ *string* ?*param*?](#25)
[__::html::hdrRow__ *args*](#26)
[__::html::head__ *title*](#27)
[__::html::headTag__ *string*](#28)
[__::html::html_entities__ *string*](#29)
[__::html::if__ *expr1 body1* ?__elseif__ *expr2 body2 ...*? ?__else__ *bodyN*?](#30)
[__::html::init__ ?*list*?](#31)
[__::html::keywords__ *args*](#32)
[__::html::mailto__ *email* ?*subject*?](#33)
[__::html::meta__ *args*](#34)
[__::html::css__ *href*](#35)
[__::html::css-clear__](#36)
[__::html::js__ *href*](#37)
[__::html::js-clear__](#38)
[__::html::minorList__ *list* ?*ordered*?](#39)
[__::html::minorMenu__ *list* ?*sep*?](#40)
[__::html::nl2br__ *string*](#41)
[__::html::openTag__ *tag* ?*param*?](#42)
[__::html::paramRow__ *list* ?*rparam*? ?*cparam*?](#43)
[__::html::passwordInput__ ?*name*?](#44)
[__::html::passwordInputRow__ *label* ?*name*?](#45)
[__::html::quoteFormValue__ *value*](#46)
[__::html::radioSet__ *key sep list*](#47)
[__::html::radioValue__ *name value*](#48)
[__::html::refresh__ *seconds url*](#49)
[__::html::row__ *args*](#50)
[__::html::select__ *name param choices* ?*current*?](#51)
[__::html::selectPlain__ *name param choices* ?*current*?](#52)
[__::html::set__ *var val*](#53)
[__::html::submit__ *label* ?*name*?](#54)
[__::html::tableFromArray__ *arrname* ?*param*? ?*pat*?](#55)
[__::html::tableFromList__ *querylist* ?*param*?](#56)
[__::html::textarea__ *name* ?*param*? ?*current*?](#57)
[__::html::textInput__ *name value args*](#58)
[__::html::textInputRow__ *label name value args*](#59)
[__::html::varEmpty__ *name*](#60)
[__::html::while__ *test body*](#61)
[__::html::doctype__ *id*](#62)
# <a name='description'></a>DESCRIPTION
The package __html__ provides commands that generate HTML. These commands
typically return an HTML string as their result. In particular, they do not
output their result to __stdout__.
The command __::html::init__ should be called early to initialize the module.
You can also use this procedure to define default values for HTML tag
parameters.
- <a name='1'></a>__::html::author__ *author*
*Side effect only*. Call this before __::html::head__ to define an author
for the page. The author is noted in a comment in the HEAD section.
- <a name='2'></a>__::html::bodyTag__ *args*
Generate a *body* tag. The tag parameters are taken from *args* or from the
body.* attributes define with __::html::init__.
- <a name='3'></a>__::html::cell__ *param value* ?*tag*?
Generate a *td* (or *th*) tag, a value, and a closing *td* (or *th*) tag.
The tag parameters come from *param* or TD.* attributes defined with
__::html::init__. This uses __::html::font__ to insert a standard *font* tag
into the table cell. The *tag* argument defaults to "td".
- <a name='4'></a>__::html::checkbox__ *name value*
Generate a *[checkbox](../../../../index.md#checkbox)* form element with the
specified name and value. This uses __::html::checkValue__.
- <a name='5'></a>__::html::checkSet__ *key sep list*
Generate a set of *[checkbox](../../../../index.md#checkbox)* form elements
and associated labels. The *list* should contain an alternating list of
labels and values. This uses __::html::checkbox__. All the
*[checkbox](../../../../index.md#checkbox)* buttons share the same *key* for
their name. The *sep* is text used to separate the elements.
- <a name='6'></a>__::html::checkValue__ *name* ?*value*?
Generate the "name=*name* value=*value*" for a
*[checkbox](../../../../index.md#checkbox)* form element. If the CGI
variable *name* has the value *value*, then SELECTED is added to the return
value. *value* defaults to "1".
- <a name='7'></a>__::html::closeTag__
Pop a tag off the stack created by __::html::openTag__ and generate the
corresponding close tag (e.g., </body>).
- <a name='8'></a>__::html::default__ *key* ?*param*?
This procedure is used by __::html::tagParam__ to generate the name, value
list of parameters for a tag. The __::html::default__ procedure is used to
generate default values for those items not already in *param*. If the value
identified by *key* matches a value in *param* then this procedure returns
the empty string. Otherwise, it returns a "parameter=value" string for a
form element identified by *key*. The *key* has the form "tag.parameter"
(e.g., body.bgcolor). Use __::html::init__ to register default values.
*param* defaults to the empty string.
- <a name='9'></a>__::html::description__ *description*
*Side effect only*. Call this before __::html::head__ to define a
description *meta* tag for the page. This tag is generated later in the call
to __::html::head__.
- <a name='10'></a>__::html::end__
Pop all open tags from the stack and generate the corresponding close HTML
tags, (e.g., </body></html>).
- <a name='11'></a>__::html::eval__ *arg* ?*args*?
This procedure is similar to the built-in Tcl __eval__ command. The only
difference is that it returns "" so it can be called from an HTML template
file without appending unwanted results.
- <a name='12'></a>__::html::extractParam__ *param key* ?*varName*?
This is a parsing procedure that extracts the value of *key* from *param*,
which is a HTML-style "name=quotedvalue" list. *varName* is used as the name
of a Tcl variable that is changed to have the value found in the parameters.
The function returns 1 if the parameter was found in *param*, otherwise it
returns 0. If the *varName* is not specified, then *key* is used as the
variable name.
- <a name='13'></a>__::html::font__ *args*
Generate a standard *font* tag. The parameters to the tag are taken from
*args* and the HTML defaults defined with __::html::init__.
- <a name='14'></a>__::html::for__ *start test next body*
This procedure is similar to the built-in Tcl __for__ control structure.
Rather than evaluating the body, it returns the subst'ed *body*. Each
iteration of the loop causes another string to be concatenated to the result
value.
- <a name='15'></a>__::html::foreach__ *varlist1 list1* ?*varlist2 list2 ...*? *body*
This procedure is similar to the built-in Tcl
__[foreach](../../../../index.md#foreach)__ control structure. Rather than
evaluating the body, it returns the subst'ed *body*. Each iteration of the
loop causes another string to be concatenated to the result value.
- <a name='16'></a>__::html::formValue__ *name* ?*defvalue*?
Return a name and value pair, where the value is initialized from existing
CGI data, if any. The result has this form:
name="fred" value="freds value"
- <a name='17'></a>__::html::getFormInfo__ *args*
Generate hidden fields to capture form values. If *args* is empty, then
hidden fields are generated for all CGI values. Otherwise args is a list of
string match patterns for form element names.
- <a name='18'></a>__::html::getTitle__
Return the title string, with out the surrounding *title* tag, set with a
previous call to __::html::title__.
- <a name='19'></a>__::html::h__ *level string* ?*param*?
Generate a heading (e.g., *h__level__*) tag. The *string* is nested in the
heading, and *param* is used for the tag parameters.
- <a name='20'></a>__::html::h1__ *string* ?*param*?
Generate an *h1* tag. See __::html::h__.
- <a name='21'></a>__::html::h2__ *string* ?*param*?
Generate an *h2* tag. See __::html::h__.
- <a name='22'></a>__::html::h3__ *string* ?*param*?
Generate an *h3* tag. See __::html::h__.
- <a name='23'></a>__::html::h4__ *string* ?*param*?
Generate an *h4* tag. See __::html::h__.
- <a name='24'></a>__::html::h5__ *string* ?*param*?
Generate an *h5* tag. See __::html::h__.
- <a name='25'></a>__::html::h6__ *string* ?*param*?
Generate an *h6* tag. See __::html::h__.
- <a name='26'></a>__::html::hdrRow__ *args*
Generate a table row, including *tr* and *th* tags. Each value in *args* is
place into its own table cell. This uses __::html::cell__.
- <a name='27'></a>__::html::head__ *title*
Generate the *head* section that includes the page *title*. If previous
calls have been made to __::html::author__, __::html::keywords__,
__::html::description__, or __::html::meta__ then additional tags are
inserted into the *head* section. This leaves an open
*[html](../../../../index.md#html)* tag pushed on the stack with
__::html::openTag__.
- <a name='28'></a>__::html::headTag__ *string*
Save a tag for inclusion in the *head* section generated by
__::html::head__. The *string* is everything in the tag except the enclosing
angle brackets, < >.
- <a name='29'></a>__::html::html_entities__ *string*
This command replaces all special characters in the *string* with their HTML
entities and returns the modified text.
- <a name='30'></a>__::html::if__ *expr1 body1* ?__elseif__ *expr2 body2 ...*? ?__else__ *bodyN*?
This procedure is similar to the built-in Tcl __if__ control structure.
Rather than evaluating the body of the branch that is taken, it returns the
subst'ed *body*. Note that the syntax is slightly more restrictive than that
of the built-in Tcl __if__ control structure.
- <a name='31'></a>__::html::init__ ?*list*?
__::html::init__ accepts a Tcl-style name-value list that defines values for
items with a name of the form "tag.parameter". For example, a default with
key "body.bgcolor" defines the background color for the *body* tag.
- <a name='32'></a>__::html::keywords__ *args*
*Side effect only*. Call this before __::html::head__ to define a keyword
*meta* tag for the page. The *meta* tag is included in the result of
__::html::head__.
- <a name='33'></a>__::html::mailto__ *email* ?*subject*?
Generate a hypertext link to a mailto: URL.
- <a name='34'></a>__::html::meta__ *args*
*Side effect only*. Call this before __::html::head__ to define a *meta* tag
for the page. The *args* is a Tcl-style name, value list that is used for
the name= and value= parameters for the *meta* tag. The *meta* tag is
included in the result of __::html::head__.
- <a name='35'></a>__::html::css__ *href*
*Side effect only*. Call this before __::html::head__ to define a *link* tag
for a linked CSS document. The *href* value is a HTTP URL to a CSS document.
The *link* tag is included in the result of __::html::head__.
Multiple calls of this command are allowed, enabling the use of multiple CSS
document references. In other words, the arguments of multiple calls are
accumulated, and do not overwrite each other.
- <a name='36'></a>__::html::css-clear__
*Side effect only*. Call this before __::html::head__ to clear all links to
CSS documents.
Multiple calls of this command are allowed, doing nothing after the first of
a sequence with no intervening __::html::css__.
- <a name='37'></a>__::html::js__ *href*
*Side effect only*. Call this before __::html::head__ to define a *script*
tag for a linked JavaScript document. The *href* is a HTTP URL to a
JavaScript document. The *script* tag is included in the result of
__::html::head__.
Multiple calls of this command are allowed, enabling the use of multiple
JavaScript document references. In other words, the arguments of multiple
calls are accumulated, and do not overwrite each other.
- <a name='38'></a>__::html::js-clear__
*Side effect only*. Call this before __::html::head__ to clear all links to
JavaScript documents.
Multiple calls of this command are allowed, doing nothing after the first of
a sequence with no intervening __::html::js__.
- <a name='39'></a>__::html::minorList__ *list* ?*ordered*?
Generate an ordered or unordered list of links. The *list* is a Tcl-style
name, value list of labels and urls for the links. *ordered* is a boolean
used to choose between an ordered or unordered list. It defaults to
__false__.
- <a name='40'></a>__::html::minorMenu__ *list* ?*sep*?
Generate a series of hypertext links. The *list* is a Tcl-style name, value
list of labels and urls for the links. The *sep* is the text to put between
each link. It defaults to " | ".
- <a name='41'></a>__::html::nl2br__ *string*
This command replaces all line-endings in the *string* with a *br* tag and
returns the modified text.
- <a name='42'></a>__::html::openTag__ *tag* ?*param*?
Push *tag* onto a stack and generate the opening tag for *tag*. Use
__::html::closeTag__ to pop the tag from the stack. The second argument
provides any tag arguments, as a list whose elements are formatted to be in
the form "__key__=__value__".
- <a name='43'></a>__::html::paramRow__ *list* ?*rparam*? ?*cparam*?
Generate a table row, including *tr* and *td* tags. Each value in *list* is
placed into its own table cell. This uses __::html::cell__. The value of
*rparam* is used as parameter for the *tr* tag. The value of *cparam* is
passed to __::html::cell__ as parameter for the *td* tags.
- <a name='44'></a>__::html::passwordInput__ ?*name*?
Generate an *input* tag of type *[password](../../../../index.md#password)*.
The *name* defaults to "password".
- <a name='45'></a>__::html::passwordInputRow__ *label* ?*name*?
Format a table row containing a label and an *input* tag of type
*[password](../../../../index.md#password)*. The *name* defaults to
"password".
- <a name='46'></a>__::html::quoteFormValue__ *value*
Quote special characters in *value* by replacing them with HTML entities for
quotes, ampersand, and angle brackets.
- <a name='47'></a>__::html::radioSet__ *key sep list*
Generate a set of *input* tags of type *radio* and an associated text label.
All the radio buttons share the same *key* for their name. The *sep* is text
used to separate the elements. The *list* is a Tcl-style label, value list.
- <a name='48'></a>__::html::radioValue__ *name value*
Generate the "name=*name* value=*value*" for a *radio* form element. If the
CGI variable *name* has the value *value*, then SELECTED is added to the
return value.
- <a name='49'></a>__::html::refresh__ *seconds url*
Set up a refresh *meta* tag. Call this before __::html::head__ and the HEAD
section will contain a *meta* tag that causes the document to refresh in
*seconds* seconds. The *url* is optional. If specified, it specifies a new
page to load after the refresh interval.
- <a name='50'></a>__::html::row__ *args*
Generate a table row, including *tr* and *td* tags. Each value in *args* is
place into its own table cell. This uses __::html::cell__. Ignores any
default information set up via __::html::init__.
- <a name='51'></a>__::html::select__ *name param choices* ?*current*?
Generate a *select* form element and nested *option* tags. The *name* and
*param* are used to generate the *select* tag. The *choices* list is a
Tcl-style name, value list.
- <a name='52'></a>__::html::selectPlain__ *name param choices* ?*current*?
Like __::html::select__ except that *choices* is a Tcl list of values used
for the *option* tags. The label and the value for each *option* are the
same.
- <a name='53'></a>__::html::set__ *var val*
This procedure is similar to the built-in Tcl
__[set](../../../../index.md#set)__ command. The main difference is that it
returns "" so it can be called from an HTML template file without appending
unwanted results. The other difference is that it must take two arguments.
- <a name='54'></a>__::html::submit__ *label* ?*name*?
Generate an *input* tag of type *submit*. *name* defaults to "submit".
- <a name='55'></a>__::html::tableFromArray__ *arrname* ?*param*? ?*pat*?
Generate a two-column *[table](../../../../index.md#table)* and nested rows
to display a Tcl array. The table gets a heading that matches the array
name, and each generated row contains a name, value pair. The array names
are sorted (__lsort__ without special options). The argument *param* is for
the *[table](../../../../index.md#table)* tag and has to contain a
pre-formatted string. The *pat* is a __string match__ pattern used to select
the array elements to show in the table. It defaults to __*__, i.e. the
whole array is shown.
- <a name='56'></a>__::html::tableFromList__ *querylist* ?*param*?
Generate a two-column *[table](../../../../index.md#table)* and nested rows
to display *querylist*, which is a Tcl dictionary. Each generated row
contains a name, value pair. The information is shown in the same order as
specified in the dictionary. The argument *param* is for the
*[table](../../../../index.md#table)* tag and has to contain a pre-formatted
string.
- <a name='57'></a>__::html::textarea__ *name* ?*param*? ?*current*?
Generate a *textarea* tag wrapped around its current values.
- <a name='58'></a>__::html::textInput__ *name value args*
Generate an *input* form tag with type *[text](../../../../index.md#text)*.
This uses __::html::formValue__. The args is any additional tag attributes
you want to put into the *input* tag.
- <a name='59'></a>__::html::textInputRow__ *label name value args*
Generate an *input* form tag with type *[text](../../../../index.md#text)*
formatted into a table row with an associated label. The args is any
additional tag attributes you want to put into the *input* tag.
- <a name='60'></a>__::html::varEmpty__ *name*
This returns 1 if the named variable either does not exist or has the empty
string for its value.
- <a name='61'></a>__::html::while__ *test body*
This procedure is similar to the built-in Tcl __while__ control structure.
Rather than evaluating the body, it returns the subst'ed *body*. Each
iteration of the loop causes another string to be concatenated to the result
value.
- <a name='62'></a>__::html::doctype__ *id*
This procedure can be used to build the standard DOCTYPE declaration string.
It will return the standard declaration string for the id, or throw an error
if the id is not known. The following id's are defined:
HTML32
HTML40
HTML40T
HTML40F
HTML401
HTML401T
HTML401F
XHTML10S
XHTML10T
XHTML10F
XHTML11
XHTMLB
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *html* 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.
# <a name='see-also'></a>SEE ALSO
[htmlparse](../htmlparse/htmlparse.md), [ncgi](../ncgi/ncgi.md)
# <a name='keywords'></a>KEYWORDS
[checkbox](../../../../index.md#checkbox),
[checkbutton](../../../../index.md#checkbutton),
[form](../../../../index.md#form), [html](../../../../index.md#html),
[radiobutton](../../../../index.md#radiobutton),
[table](../../../../index.md#table)
# <a name='category'></a>CATEGORY
CGI programming
|
Added embedded/md/tcllib/files/modules/htmlparse/htmlparse.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
[//000000001]: # (htmlparse - HTML Parser)
[//000000002]: # (Generated from file 'htmlparse.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (htmlparse(n) 1.2.2 tcllib "HTML Parser")
# NAME
htmlparse - Procedures to parse HTML strings
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::stack 1.3
package require cmdline 1.1
package require htmlparse ?1.2.2?
[__::htmlparse::parse__ ?-cmd *cmd*? ?-vroot *tag*? ?-split *n*? ?-incvar *var*? ?-queue *q*? *html*](#1)
[__::htmlparse::debugCallback__ ?*clientdata*? *tag slash param textBehindTheTag*](#2)
[__::htmlparse::mapEscapes__ *html*](#3)
[__::htmlparse::2tree__ *html tree*](#4)
[__::htmlparse::removeVisualFluff__ *tree*](#5)
[__::htmlparse::removeFormDefs__ *tree*](#6)
# <a name='description'></a>DESCRIPTION
The __htmlparse__ package provides commands that allow libraries and
applications to parse HTML in a string into a representation of their choice.
The following commands are available:
- <a name='1'></a>__::htmlparse::parse__ ?-cmd *cmd*? ?-vroot *tag*? ?-split *n*? ?-incvar *var*? ?-queue *q*? *html*
This command is the basic parser for HTML. It takes an HTML string, parses
it and invokes a command prefix for every tag encountered. It is not
necessary for the HTML to be valid for this parser to function. It is the
responsibility of the command invoked for every tag to check this. Another
responsibility of the invoked command is the handling of tag attributes and
character entities (escaped characters). The parser provides the
un-interpreted tag attributes to the invoked command to aid in the former,
and the package at large provides a helper command,
__::htmlparse::mapEscapes__, to aid in the handling of the latter. The
parser *does* ignore leading DOCTYPE declarations and all valid HTML
comments it encounters.
All information beyond the HTML string itself is specified via options,
these are explained below.
To help understand the options, some more background information about the
parser.
It is capable of detecting incomplete tags in the HTML string given to it.
Under normal circumstances this will cause the parser to throw an error, but
if the option *-incvar* is used to specify a global (or namespace) variable,
the parser will store the incomplete part of the input into this variable
instead. This will aid greatly in the handling of incrementally arriving
HTML, as the parser will handle whatever it can and defer the handling of
the incomplete part until more data has arrived.
Another feature of the parser are its two possible modes of operation. The
normal mode is activated if the option *-queue* is not present on the
command line invoking the parser. If it is present, the parser will go into
the incremental mode instead.
The main difference is that a parser in normal mode will immediately invoke
the command prefix for each tag it encounters. In incremental mode however
the parser will generate a number of scripts which invoke the command prefix
for groups of tags in the HTML string and then store these scripts in the
specified queue. It is then the responsibility of the caller of the parser
to ensure the execution of the scripts in the queue.
*Note*: The queue object given to the parser has to provide the same
interface as the queue defined in tcllib -> struct. This means, for example,
that all queues created via that tcllib module can be immediately used here.
Still, the queue doesn't have to come from tcllib -> struct as long as the
same interface is provided.
In both modes the parser will return an empty string to the caller.
The *-split* option may be given to a parser in incremental mode to specify
the size of the groups it creates. In other words, -split 5 means that each
of the generated scripts will invoke the command prefix for 5 consecutive
tags in the HTML string. A parser in normal mode will ignore this option and
its value.
The option *-vroot* specifies a virtual root tag. A parser in normal mode
will invoke the command prefix for it immediately before and after it
processes the tags in the HTML, thus simulating that the HTML string is
enclosed in a <vroot> </vroot> combination. In incremental mode however the
parser is unable to provide the closing virtual root as it never knows when
the input is complete. In this case the first script generated by each
invocation of the parser will contain an invocation of the command prefix
for the virtual root as its first command. The following options are
available:
* __-cmd__ *cmd*
The command prefix to invoke for every tag in the HTML string. Defaults
to *::htmlparse::debugCallback*.
* __-vroot__ *tag*
The virtual root tag to add around the HTML in normal mode. In
incremental mode it is the first tag in each chunk processed by the
parser, but there will be no closing tags. Defaults to *hmstart*.
* __-split__ *n*
The size of the groups produced by an incremental mode parser. Ignored
when in normal mode. Defaults to 10. Values <= 0 are not allowed.
* __-incvar__ *var*
The name of the variable where to store any incomplete HTML into. This
makes most sense for the incremental mode. The parser will throw an
error if it sees incomplete HTML and has no place to store it to. This
makes sense for the normal mode. Only incomplete tags are detected, not
missing tags. Optional, defaults to 'no variable'.
* *Interface to the command prefix*
In normal mode the parser will invoke the command prefix with four
arguments appended. See __::htmlparse::debugCallback__ for a
description.
In incremental mode, however, the generated scripts will invoke the
command prefix with five arguments appended. The last four of these are
the same which were mentioned above. The first is a placeholder string
(__@win@__) for a clientdata value to be supplied later during the
actual execution of the generated scripts. This could be a tk window
path, for example. This allows the user of this package to preprocess
HTML strings without committing them to a specific window, object,
whatever during parsing. This connection can be made later. This also
means that it is possible to cache preprocessed HTML. Of course, nothing
prevents the user of the parser from replacing the placeholder with an
empty string.
- <a name='2'></a>__::htmlparse::debugCallback__ ?*clientdata*? *tag slash param textBehindTheTag*
This command is the standard callback used by the parser in
__::htmlparse::parse__ if none was specified by the user. It simply dumps
its arguments to stdout. This callback can be used for both normal and
incremental mode of the calling parser. In other words, it accepts four or
five arguments. The last four arguments are described below. The optional
fifth argument contains the clientdata value passed to the callback by a
parser in incremental mode. All callbacks have to follow the signature of
this command in the last four arguments, and callbacks used in incremental
parsing have to follow this signature in the last five arguments.
The first argument, *clientdata*, is optional and present only if this
command is invoked by a parser in incremental mode. It contains whatever the
user of this package wishes.
The second argument, *tag*, contains the name of the tag which is currently
processed by the parser.
The third argument, *slash*, is either empty or contains a slash character.
It allows the callback to distinguish between opening (slash is empty) and
closing tags (slash contains a slash character).
The fourth argument, *param*, contains the un-interpreted list of parameters
to the tag.
The fifth and last argument, *textBehindTheTag*, contains the text found by
the parser behind the tag named in *tag*.
- <a name='3'></a>__::htmlparse::mapEscapes__ *html*
This command takes a HTML string, substitutes all escape sequences with
their actual characters and then returns the resulting string. HTML strings
which do not contain escape sequences are returned unchanged.
- <a name='4'></a>__::htmlparse::2tree__ *html tree*
This command is a wrapper around __::htmlparse::parse__ which takes an HTML
string (in *html*) and converts it into a tree containing the logical
structure of the parsed document. The name of the tree is given to the
command as its second argument (*tree*). The command does __not__ generate
the tree by itself but expects that the caller provided it with an existing
and empty tree. It also expects that the specified tree object follows the
same interface as the tree object in tcllib -> struct. It doesn't have to be
from tcllib -> struct, but it must provide the same interface.
The internal callback does some basic checking of HTML validity and tries to
recover from the most basic errors. The command returns the contents of its
second argument. Side effects are the creation and manipulation of a tree
object.
Each node in the generated tree represent one tag in the input. The name of
the tag is stored in the attribute *type* of the node. Any html attributes
coming with the tag are stored unmodified in the attribute *data* of the
tag. In other words, the command does *not* parse html attributes into their
names and values.
If a tag contains text its node will have children of type *PCDATA*
containing this text. The text will be stored in the attribute *data* of
these children.
- <a name='5'></a>__::htmlparse::removeVisualFluff__ *tree*
This command walks a tree as generated by __::htmlparse::2tree__ and removes
all the nodes which represent visual tags and not structural ones. The
purpose of the command is to make the tree easier to navigate without
getting bogged down in visual information not relevant to the search. Its
only argument is the name of the tree to cut down.
- <a name='6'></a>__::htmlparse::removeFormDefs__ *tree*
Like __::htmlparse::removeVisualFluff__ this command is here to cut down on
the size of the tree as generated by __::htmlparse::2tree__. It removes all
nodes representing forms and form elements. Its only argument is the name of
the tree to cut down.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *htmlparse* 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.
# <a name='see-also'></a>SEE ALSO
[struct::tree](../struct/struct_tree.md)
# <a name='keywords'></a>KEYWORDS
[html](../../../../index.md#html), [parsing](../../../../index.md#parsing),
[queue](../../../../index.md#queue), [tree](../../../../index.md#tree)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/http/autoproxy.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
[//000000001]: # (autoproxy - HTTP protocol helper modules)
[//000000002]: # (Generated from file 'autoproxy.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (autoproxy(n) 1.7 tcllib "HTTP protocol helper modules")
# NAME
autoproxy - Automatic HTTP proxy usage and authentication
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TLS Security Considerations](#section2)
- [COMMANDS](#section3)
- [OPTIONS](#section4)
- [Basic Authentication](#section5)
- [EXAMPLES](#section6)
- [REFERENCES](#section7)
- [BUGS](#section8)
- [AUTHORS](#section9)
- [Bugs, Ideas, Feedback](#section10)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require http ?2.0?
package require autoproxy ?1.7?
[__::autoproxy::init__](#1)
[__::autoproxy::cget__ *-option*](#2)
[__::autoproxy::configure__ ?-option *value*?](#3)
[__::autoproxy::tls_connect__ *args*](#4)
[__::autoproxy::tunnel_connect__ *args*](#5)
[__::autoproxy::tls_socket__ *args*](#6)
# <a name='description'></a>DESCRIPTION
This package attempts to automate the use of HTTP proxy servers in Tcl HTTP
client code. It tries to initialize the web access settings from system standard
locations and can be configured to negotiate authentication with the proxy if
required.
On Unix the standard for identifying the local HTTP proxy server seems to be to
use the environment variable http_proxy or ftp_proxy and no_proxy to list those
domains to be excluded from proxying. On Windows we can retrieve the Internet
Settings values from the registry to obtain pretty much the same information.
With this information we can setup a suitable filter procedure for the Tcl http
package and arrange for automatic use of the proxy.
There seem to be a number of ways that the http_proxy environment variable may
be set up. Either a plain host:port or more commonly a URL and sometimes the URL
may contain authentication parameters or these may be requested from the user or
provided via http_proxy_user and http_proxy_pass. This package attempts to deal
with all these schemes. It will do it's best to get the required parameters from
the environment or registry and if it fails can be reconfigured.
# <a name='section2'></a>TLS Security Considerations
*Note* This section only applies if TLS support is provided by the
__[TLS](../../../../index.md#tls)__ package. It does not apply when
__autoproxy__ was configured to use some other package which can provide the
same (i.e __twapi__), via the __-tls_package__ configuration option.
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section3'></a>COMMANDS
- <a name='1'></a>__::autoproxy::init__
Initialize the autoproxy package from system resources. Under unix this
means we look for environment variables. Under windows we look for the same
environment variables but also look at the registry settings used by
Internet Explorer.
- <a name='2'></a>__::autoproxy::cget__ *-option*
Retrieve individual package configuration options. See [OPTIONS](#section4).
- <a name='3'></a>__::autoproxy::configure__ ?-option *value*?
Configure the autoproxy package. Calling __configure__ with no options will
return a list of all option names and values. See [OPTIONS](#section4).
- <a name='4'></a>__::autoproxy::tls_connect__ *args*
Connect to a secure socket through a proxy. HTTP proxy servers permit the
use of the CONNECT HTTP command to open a link through the proxy to the
target machine. This function hides the details. For use with the http
package see __tls_socket__.
The *args* list may contain any of the options supported by the specific TLS
package that is in use but must end with the host and port as the last two
items.
- <a name='5'></a>__::autoproxy::tunnel_connect__ *args*
Connect to a target host throught a proxy. This uses the same CONNECT HTTP
command as the __tls_connect__ but does not promote the link security once
the connection is established.
The *args* list may contain any of the options supported by the specific TLS
package that is in use but must end with the host and port as the last two
items.
Note that many proxy servers will permit CONNECT calls to a limited set of
ports - typically only port 443 (the secure HTTP port).
- <a name='6'></a>__::autoproxy::tls_socket__ *args*
This function is to be used to register a proxy-aware secure socket handler
for the https protocol. It may only be used with the Tcl http package and
should be registered using the http::register command (see the examples
below). The job of actually creating the tunnelled connection is done by the
tls_connect command and this may be used when not registering with the http
package.
# <a name='section4'></a>OPTIONS
- __-host__ hostname
- __-proxy_host__ hostname
Set the proxy hostname. This is normally set up by __init__ but may be
configured here as well.
- __-port__ number
- __-proxy_port__ number
Set the proxy port number. This is normally set up by __init__. e.g.
__configure__ __-port__ *3128*
- __-no_proxy__ list
You may manipulate the __no_proxy__ list that was setup by __init__. The
value of this option is a tcl list of strings that are matched against the
http request host using the tcl __string match__ command. Therefore glob
patterns are permitted. For instance, __configure__ __-no_proxy__
**.localdomain*
- __-authProc__ procedure
This option may be used to set an application defined procedure to be called
when __configure__ __-basic__ is called with either no or insufficient
authentication details. This can be used to present a dialog to the user to
request the additional information.
- __-basic__
Following options are for configuring the Basic authentication scheme
parameters. See [Basic Authentication](#section5). To unset the proxy
authentication information retained from a previous call of this function
either "--" or no additional parameters can be supplied. This will remove
the existing authentication information.
- __-tls_package__ packagename
This option may be used to configure the Tcl package to use for TLS support.
Valid package names are __tls__ (default) and __twapi__.
# <a name='section5'></a>Basic Authentication
Basic is the simplest and most commonly use HTTP proxy authentication scheme. It
is described in (1 section 11) and also in (2). It offers no privacy whatsoever
and its use should be discouraged in favour of more secure alternatives like
Digest. To perform Basic authentication the client base64 encodes the username
and plaintext password separated by a colon. This encoded text is prefixed with
the word "Basic" and a space.
The following options exists for this scheme:
- __-username__ name
The username required to authenticate with the configured proxy.
- __-password__ password
The password required for the username specified.
- __-realm__ realm
This option is not used by this package but may be used in requesting
authentication details from the user.
- __--__
The end-of-options indicator may be used alone to unset any authentication
details currently enabled.
# <a name='section6'></a>EXAMPLES
package require autoproxy
autoproxy::init
autoproxy::configure -basic -username ME -password SEKRET
set tok [http::geturl http://wiki.tcl.tk/]
http::data $tok
package require http
package require tls
package require autoproxy
autoproxy::init
http::register https 443 autoproxy::tls_socket
set tok [http::geturl https://www.example.com/]
# <a name='section7'></a>REFERENCES
1. Berners-Lee, T., Fielding R. and Frystyk, H. "Hypertext Transfer Protocol
-- HTTP/1.0", RFC 1945, May 1996,
([http://www.rfc-editor.org/rfc/rfc1945.txt](http://www.rfc-editor.org/rfc/rfc1945.txt))
1. Franks, J. et al. "HTTP Authentication: Basic and Digest Access
Authentication", RFC 2617, June 1999
([http://www.rfc-editor.org/rfc/rfc2617.txt](http://www.rfc-editor.org/rfc/rfc2617.txt))
# <a name='section8'></a>BUGS
At this time only Basic authentication (1) (2) is supported. It is planned to
add support for Digest (2) and NTLM in the future.
# <a name='section9'></a>AUTHORS
Pat Thoyts
# <a name='section10'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *http :: autoproxy* 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.
# <a name='see-also'></a>SEE ALSO
http(n)
# <a name='keywords'></a>KEYWORDS
[authentication](../../../../index.md#authentication),
[http](../../../../index.md#http), [proxy](../../../../index.md#proxy)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/httpd/httpd.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
|
[//000000001]: # (tool - Tcl Web Server)
[//000000002]: # (Generated from file 'httpd.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tool(n) 4.1.1 tcllib "Tcl Web Server")
# NAME
tool - A TclOO and coroutine based web server
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Minimal Example](#section2)
- [Class ::httpd::server](#section3)
- [Class ::httpd::reply](#section4)
- [Reply Method Ensembles](#section5)
- [Reply Method Ensemble: http_info](#section6)
- [Reply Method Ensemble: request](#section7)
- [Reply Method Ensemble: reply](#section8)
- [Reply Methods](#section9)
- [Class ::httpd::content](#section10)
- [Class ::httpd::content.cgi](#section11)
- [Class ::httpd::content.file](#section12)
- [Class ::httpd::content.proxy](#section13)
- [Class ::httpd::content.scgi](#section14)
- [Class ::httpd::content.websocket](#section15)
- [SCGI Server Functions](#section16)
- [Class ::httpd::reply.scgi](#section17)
- [Class ::httpd::server.scgi](#section18)
- [AUTHORS](#section19)
- [Bugs, Ideas, Feedback](#section20)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require httpd ?4.1.1?
package require sha1
package require dicttool
package require oo::meta
package require oo::dialect
package require tool
package require coroutine
package require fileutil
package require fileutil::magic::filetype
package require websocket
package require mime
package require cron
package require uri
package require Markdown
[constructor ?port ?port?? ?myaddr ?ipaddr?|all? ?server_string ?string?? ?server_name ?string??](#1)
[method __add_uri__ *pattern* *dict*](#2)
[method __connect__ *sock* *ip* *port*](#3)
[method __Connect__ *uuid* *sock* *ip*](#4)
[method __[counter](../counter/counter.md)__ *which*](#5)
[method __CheckTimeout__](#6)
[method __dispatch__ *header_dict*](#7)
[method __[log](../log/log.md)__ *args*](#8)
[method __port_listening__](#9)
[method __PrefixNormalize__ *prefix*](#10)
[method __start__](#11)
[method __stop__](#12)
[method __template__ *page*](#13)
[method __TemplateSearch__ *page*](#14)
[method __Validate_Connection__ *sock* *ip*](#15)
[method __ENSEMBLE::add__ *field* *element*](#16)
[method __ENSEMBLE::dump__](#17)
[method __ENSEMBLE::get__ *field*](#18)
[method __ENSEMBLE::reset__](#19)
[method __ENSEMBLE::remove__ *field* *element*](#20)
[method __ENSEMBLE::replace__ *keyvaluelist*](#21)
[method __ENSEMBLE::reset__](#22)
[method __ENSEMBLE::set__ *field* *value*](#23)
[method __http_info::netstring__](#24)
[method __request::parse__ *string*](#25)
[method __reply::output__](#26)
[method __close__](#27)
[method __HttpHeaders__ *sock* *?debug?*](#28)
[method __dispatch__ *newsock* *datastate*](#29)
[method __[error](../../../../index.md#error)__ *code* *?message?* *?errorInfo?*](#30)
[method __content__](#31)
[method __EncodeStatus__ *status*](#32)
[method FormData](#33)
[method MimeParse *mimetext*](#34)
[method __DoOutput__](#35)
[method PostData *length*](#36)
[method __puts__ *string*](#37)
[method __reset__](#38)
[method __timeOutCheck__](#39)
[method __[timestamp](../../../../index.md#timestamp)__](#40)
[method __TransferComplete__ *args*](#41)
[method __Url_Decode__ *string*](#42)
[method cgi_info](#43)
[option __path__](#44)
[option __[prefix](../../../../index.md#prefix)__](#45)
[method proxy_info](#46)
[method scgi_info](#47)
# <a name='description'></a>DESCRIPTION
This module implements a web server, suitable for embedding in an application.
The server is object oriented, and contains all of the fundamentals needed for a
full service website.
# <a name='section2'></a>Minimal Example
Starting a web service requires starting a class of type __httpd::server__, and
providing that server with one or more URIs to service, and __httpd::reply__
derived classes to generate them.
tool::define ::reply.hello {
method content {} {
my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
my puts "<h1>Hello World!</h1>"
my puts </BODY></HTML>
}
}
::docserver::server create HTTPD port 8015 myaddr 127.0.0.1
HTTPD add_uri /* [list mixin reply.hello]
# <a name='section3'></a>Class ::httpd::server
This class is the root object of the webserver. It is responsible for opening
the socket and providing the initial connection negotiation.
- <a name='1'></a>constructor ?port ?port?? ?myaddr ?ipaddr?|all? ?server_string ?string?? ?server_name ?string??
Build a new server object. ?port? is the port to listen on
- <a name='2'></a>method __add_uri__ *pattern* *dict*
Set the hander for a URI pattern. Information given in the *dict* is stored
in the data structure the __dispatch__ method uses. If a field called
*mixin* is given, that class will be mixed into the reply object immediately
after construction.
- <a name='3'></a>method __connect__ *sock* *ip* *port*
Reply to an open socket. This method builds a coroutine to manage the
remainder of the connection. The coroutine's operations are driven by the
__Connect__ method.
- <a name='4'></a>method __Connect__ *uuid* *sock* *ip*
This method reads HTTP headers, and then consults the __dispatch__ method to
determine if the request is valid, and/or what kind of reply to generate.
Under normal cases, an object of class __::http::reply__ is created. Fields
the server are looking for in particular are: class: A class to use instead
of the server's own *reply_class* mixin: A class to be mixed into the new
object after construction. All other fields are passed along to the
__http_info__ structure of the reply object. After the class is created and
the mixin is mixed in, the server invokes the reply objects __dispatch__
method. This action passes control of the socket to the reply object. The
reply object manages the rest of the transaction, including closing the
socket.
- <a name='5'></a>method __[counter](../counter/counter.md)__ *which*
Increment an internal counter.
- <a name='6'></a>method __CheckTimeout__
Check open connections for a time out event.
- <a name='7'></a>method __dispatch__ *header_dict*
Given a key/value list of information, return a data structure describing
how the server should reply.
- <a name='8'></a>method __[log](../log/log.md)__ *args*
Log an event. The input for args is free form. This method is intended to be
replaced by the user, and is a noop for a stock http::server object.
- <a name='9'></a>method __port_listening__
Return the actual port that httpd is listening on.
- <a name='10'></a>method __PrefixNormalize__ *prefix*
For the stock version, trim trailing /'s and *'s from a prefix. This method
can be replaced by the end user to perform any other transformations needed
for the application.
- <a name='11'></a>method __start__
Open the socket listener.
- <a name='12'></a>method __stop__
Shut off the socket listener, and destroy any pending replies.
- <a name='13'></a>method __template__ *page*
Return a template for the string *page*
- <a name='14'></a>method __TemplateSearch__ *page*
Perform a search for the template that best matches *page*. This can include
local file searches, in-memory structures, or even database lookups. The
stock implementation simply looks for files with a .tml or .html extension
in the ?doc_root? directory.
- <a name='15'></a>method __Validate_Connection__ *sock* *ip*
Given a socket and an ip address, return true if this connection should be
terminated, or false if it should be allowed to continue. The stock
implementation always returns 0. This is intended for applications to be
able to implement black lists and/or provide security based on IP address.
# <a name='section4'></a>Class ::httpd::reply
A class which shephards a request through the process of generating a reply. The
socket associated with the reply is available at all times as the *chan*
variable. The process of generating a reply begins with an __httpd::server__
generating a __http::class__ object, mixing in a set of behaviors and then
invoking the reply object's __dispatch__ method. In normal operations the
__dispatch__ method:
1. Invokes the __reset__ method for the object to populate default headers.
1. Invokes the __HttpHeaders__ method to stream the MIME headers out of the
socket
1. Invokes the __request parse__ method to convert the stream of MIME headers
into a dict that can be read via the __request__ method.
1. Stores the raw stream of MIME headers in the *rawrequest* variable of the
object.
1. Invokes the __content__ method for the object, generating an call to the
__[error](../../../../index.md#error)__ method if an exception is raised.
1. Invokes the __output__ method for the object
# <a name='section5'></a>Reply Method Ensembles
The __http::reply__ class and its derivatives maintain several variables as
dictionaries internally. Access to these dictionaries is managed through a
dedicated ensemble. The ensemble implements most of the same behaviors as the
__[dict](../../../../index.md#dict)__ command. Each ensemble implements the
following methods above, beyond, or modifying standard dicts:
- <a name='16'></a>method __ENSEMBLE::add__ *field* *element*
Add *element* to a list stored in *field*, but only if it is not already
present om the list.
- <a name='17'></a>method __ENSEMBLE::dump__
Return the current contents of the data structure as a key/value list.
- <a name='18'></a>method __ENSEMBLE::get__ *field*
Return the value of the field *field*, or an empty string if it does not
exist.
- <a name='19'></a>method __ENSEMBLE::reset__
Return a key/value list of the default contents for this data structure.
- <a name='20'></a>method __ENSEMBLE::remove__ *field* *element*
Remove all instances of *element* from the list stored in *field*.
- <a name='21'></a>method __ENSEMBLE::replace__ *keyvaluelist*
Replace the internal dict with the contents of *keyvaluelist*
- <a name='22'></a>method __ENSEMBLE::reset__
Replace the internal dict with the default state.
- <a name='23'></a>method __ENSEMBLE::set__ *field* *value*
Set the value of *field* to *value*.
# <a name='section6'></a>Reply Method Ensemble: http_info
Manages HTTP headers passed in by the server. Ensemble Methods:
- <a name='24'></a>method __http_info::netstring__
Return the contents of this data structure as a netstring encoded block.
# <a name='section7'></a>Reply Method Ensemble: request
Managed data from MIME headers of the request.
- <a name='25'></a>method __request::parse__ *string*
Replace the contents of the data structure with information encoded in a
MIME formatted block of text (*string*).
# <a name='section8'></a>Reply Method Ensemble: reply
Manage the headers sent in the reply.
- <a name='26'></a>method __reply::output__
Return the contents of this data structure as a MIME encoded block
appropriate for an HTTP response.
# <a name='section9'></a>Reply Methods
- <a name='27'></a>method __close__
Terminate the transaction, and close the socket.
- <a name='28'></a>method __HttpHeaders__ *sock* *?debug?*
Stream MIME headers from the socket *sock*, stopping at an empty line.
Returns the stream as a block of text.
- <a name='29'></a>method __dispatch__ *newsock* *datastate*
Take over control of the socket *newsock*, and store that as the *chan*
variable for the object. This method runs through all of the steps of
reading HTTP headers, generating content, and closing the connection. (See
class writetup).
- <a name='30'></a>method __[error](../../../../index.md#error)__ *code* *?message?* *?errorInfo?*
Generate an error message of the specified *code*, and display the *message*
as the reason for the exception. *errorInfo* is passed in from calls, but
how or if it should be displayed is a prerogative of the developer.
- <a name='31'></a>method __content__
Generate the content for the reply. This method is intended to be replaced
by the mixin. Developers have the option of streaming output to a buffer via
the __puts__ method of the reply, or simply populating the *reply_body*
variable of the object. The information returned by the __content__ method
is not interpreted in any way. If an exception is thrown (via the
__[error](../../../../index.md#error)__ command in Tcl, for example) the
caller will auto-generate a 500 {Internal Error} message. A typical
implementation of __content__ look like:
tool::define ::test::content.file {
superclass ::httpd::content.file
# Return a file
# Note: this is using the content.file mixin which looks for the reply_file variable
# and will auto-compute the Content-Type
method content {} {
my reset
set doc_root [my http_info get doc_root]
my variable reply_file
set reply_file [file join $doc_root index.html]
}
}
tool::define ::test::content.time {
# return the current system time
method content {} {
my variable reply_body
my reply set Content-Type text/plain
set reply_body [clock seconds]
}
}
tool::define ::test::content.echo {
method content {} {
my variable reply_body
my reply set Content-Type [my request get CONTENT_TYPE]
set reply_body [my PostData [my request get CONTENT_LENGTH]]
}
}
tool::define ::test::content.form_handler {
method content {} {
set form [my FormData]
my reply set Content-Type {text/html; charset=UTF-8}
my puts [my html header {My Dynamic Page}]
my puts "<BODY>"
my puts "You Sent<p>"
my puts "<TABLE>"
foreach {f v} $form {
my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
}
my puts "</TABLE><p>"
my puts "Send some info:<p>"
my puts "<FORM action=/[my http_info get REQUEST_PATH] method POST>"
my puts "<TABLE>"
foreach field {name rank serial_number} {
set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
if {[dict exists $form $field]} {
append line " value=\"[dict get $form $field]\"""
}
append line " /></TD></TR>"
my puts $line
}
my puts "</TABLE>"
my puts [my html footer]
}
}
- <a name='32'></a>method __EncodeStatus__ *status*
Formulate a standard HTTP status header from he string provided.
- <a name='33'></a>method FormData
For GET requests, converts the QUERY_DATA header into a key/value list. For
POST requests, reads the Post data and converts that information to a
key/value list for application/x-www-form-urlencoded posts. For multipart
posts, it composites all of the MIME headers of the post to a singular
key/value list, and provides MIME_* information as computed by the
__[mime](../mime/mime.md)__ package, including the MIME_TOKEN, which can be
fed back into the mime package to read out the contents.
- <a name='34'></a>method MimeParse *mimetext*
Converts a block of mime encoded text to a key/value list. If an exception
is encountered, the method will generate its own call to the
__[error](../../../../index.md#error)__ method, and immediately invoke the
__output__ method to produce an error code and close the connection.
- <a name='35'></a>method __DoOutput__
Generates the the HTTP reply, and streams that reply back across *chan*.
- <a name='36'></a>method PostData *length*
Stream *length* bytes from the *chan* socket, but only of the request is a
POST or PUSH. Returns an empty string otherwise.
- <a name='37'></a>method __puts__ *string*
Appends the value of *string* to the end of *reply_body*, as well as a
trailing newline character.
- <a name='38'></a>method __reset__
Clear the contents of the *reply_body* variable, and reset all headers in
the __reply__ structure back to the defaults for this object.
- <a name='39'></a>method __timeOutCheck__
Called from the __http::server__ object which spawned this reply. Checks to
see if too much time has elapsed while waiting for data or generating a
reply, and issues a timeout error to the request if it has, as well as
destroy the object and close the *chan* socket.
- <a name='40'></a>method __[timestamp](../../../../index.md#timestamp)__
Return the current system time in the format:
%a, %d %b %Y %T %Z
- <a name='41'></a>method __TransferComplete__ *args*
Intended to be invoked from __chan copy__ as a callback. This closes every
channel fed to it on the command line, and then destroys the object.
###
# Output the body
###
chan configure $sock -translation binary -blocking 0 -buffering full -buffersize 4096
chan configure $chan -translation binary -blocking 0 -buffering full -buffersize 4096
if {$length} {
###
# Send any POST/PUT/etc content
###
chan copy $sock $chan -size $SIZE -command [info coroutine]
yield
}
catch {close $sock}
chan flush $chan
- <a name='42'></a>method __Url_Decode__ *string*
De-httpizes a string.
# <a name='section10'></a>Class ::httpd::content
The httpd module includes several ready to use implementations of content mixins
for common use cases. Options are passed in to the __add_uri__ method of the
server.
# <a name='section11'></a>Class ::httpd::content.cgi
An implementation to relay requests to process which will accept post data
streamed in vie stdin, and sent a reply streamed to stdout.
- <a name='43'></a>method cgi_info
Mandatory method to be replaced by the end user. If needed, activates the
process to proxy, and then returns a list of three values: *exec* - The
arguments to send to exec to fire off the responding process, minus the
stdin/stdout redirection.
# <a name='section12'></a>Class ::httpd::content.file
An implementation to deliver files from the local file system.
- <a name='44'></a>option __path__
The root directory on the local file system to be exposed via http.
- <a name='45'></a>option __[prefix](../../../../index.md#prefix)__
The prefix of the URI portion to ignore when calculating relative file
paths.
# <a name='section13'></a>Class ::httpd::content.proxy
An implementation to relay requests to another HTTP server, and relay the
results back across the request channel.
- <a name='46'></a>method proxy_info
Mandatory method to be replaced by the end user. If needed, activates the
process to proxy, and then returns a list of three values: *proxyhost* - The
hostname where the proxy is located *proxyport* - The port to connect to
*proxyscript* - A pre-amble block of text to send prior to the mirrored
request
# <a name='section14'></a>Class ::httpd::content.scgi
An implementation to relay requests to a server listening on a socket expecting
SCGI encoded requests, and relay the results back across the request channel.
- <a name='47'></a>method scgi_info
Mandatory method to be replaced by the end user. If needed, activates the
process to proxy, and then returns a list of three values: *scgihost* - The
hostname where the scgi listener is located *scgiport* - The port to connect
to *scgiscript* - The contents of the *SCRIPT_NAME* header to be sent
# <a name='section15'></a>Class ::httpd::content.websocket
A placeholder for a future implementation to manage requests that can expect to
be promoted to a Websocket. Currently it is an empty class.
# <a name='section16'></a>SCGI Server Functions
The HTTP module also provides an SCGI server implementation, as well as an HTTP
implementation. To use the SCGI functions, create an object of the
__http::server.scgi__ class instead of the __http::server__ class.
# <a name='section17'></a>Class ::httpd::reply.scgi
An modified __http::reply__ implementation that understands how to deal with
netstring encoded headers.
# <a name='section18'></a>Class ::httpd::server.scgi
A modified __http::server__ which is tailored to replying to request according
to the SCGI standard instead of the HTTP standard.
# <a name='section19'></a>AUTHORS
Sean Woods
# <a name='section20'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *network* 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.
# <a name='keywords'></a>KEYWORDS
[TclOO](../../../../index.md#tcloo), [WWW](../../../../index.md#www),
[http](../../../../index.md#http), [httpd](../../../../index.md#httpd),
[httpserver](../../../../index.md#httpserver),
[services](../../../../index.md#services)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2018 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/ident/ident.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
[//000000001]: # (ident - Identification protocol client)
[//000000002]: # (Generated from file 'ident.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ident(n) 0.42 tcllib "Identification protocol client")
# NAME
ident - Ident protocol client
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require ident ?0.42?
[__::ident::query__ *socket* ?*callback*?](#1)
# <a name='description'></a>DESCRIPTION
The __ident__ package provides a client implementation of the ident protocol as
defined in RFC 1413
([http://www.rfc-editor.org/rfc/rfc1413.txt](http://www.rfc-editor.org/rfc/rfc1413.txt)).
- <a name='1'></a>__::ident::query__ *socket* ?*callback*?
This command queries the ident daemon on the remote side of the given
socket, and returns the result of the query as a dictionary. Interpreting
the dictionary as list the first key will always be __resp-type__, and can
have one of the values __USERID__, __ERROR__, and __FATAL__. These *response
types* have the following meanings:
* USERID
This indicates a successful response. Two more keys and associated
values are returned, __opsys__, and __user-id__.
* ERROR
This means the ident server has returned an error. A second key named
__error__ is present whose value contains the __error-type__ field from
the server response.
* FATAL
Fatal errors happen when no ident server is listening on the remote
side, or when the ident server gives a response that does not conform to
the RFC. A detailed error message is returned under the __error__ key.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ident* 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.
# <a name='keywords'></a>KEYWORDS
[ident](../../../../index.md#ident),
[identification](../../../../index.md#identification), [rfc
1413](../../../../index.md#rfc_1413)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Reinhard Max <[email protected]>
|
Added embedded/md/tcllib/files/modules/imap4/imap4.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
|
[//000000001]: # (imap4 - imap client)
[//000000002]: # (Generated from file 'imap4.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (imap4(n) 0.5.3 tcllib "imap client")
# NAME
imap4 - imap client-side tcl implementation of imap protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [EXAMPLES](#section3)
- [TLS Security Considerations](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require imap4 ?0.5.2?
[__::imap4::open__ *hostname* ?*port*?](#1)
[__::imap4::starttls__ *chan*](#2)
[__::imap4::login__ *chan* *user* *pass*](#3)
[__::imap4::folders__ *chan* ?*-inline*? ?*mboxref*? ?*mboxname*?](#4)
[__::imap4::select__ *chan* ?*mailbox*?](#5)
[__::imap4::examine__ *chan* ?*mailbox*?](#6)
[__::imap4::fetch__ *chan* *range* ?*-inline*? ?*attr ...*?](#7)
[__::imap4::noop__ *chan*](#8)
[__::imap4::check__ *chan*](#9)
[__::imap4::folderinfo__ *chan* ?*info*?](#10)
[__::imap4::msginfo__ *chan* *msgid* ?*info*? ?*defval*?](#11)
[__::imap4::mboxinfo__ *chan* ?*info*?](#12)
[__::imap4::isableto__ *chan* ?*capability*?](#13)
[__::imap4::create__ *chan* *mailbox*](#14)
[__::imap4::delete__ *chan* *mailbox*](#15)
[__::imap4::rename__ *chan* *oldname* *newname*](#16)
[__::imap4::subscribe__ *chan* *mailbox*](#17)
[__::imap4::unsubscribe__ *chan* *mailbox*](#18)
[__::imap4::search__ *chan* *expr* ?*...*?](#19)
[__::imap4::close__ *chan*](#20)
[__::imap4::cleanup__ *chan*](#21)
[__::imap4::debugmode__ *chan* ?*errormsg*?](#22)
[__::imap4::store__ *chan* *range* *data* *flaglist*](#23)
[__::imap4::expunge__ *chan*](#24)
[__::imap4::copy__ *chan* *msgid* *mailbox*](#25)
[__::imap4::logout__ *chan*](#26)
# <a name='description'></a>DESCRIPTION
The __imap4__ library package provides the client side of the *Internet Message
Access Protocol* (IMAP) using standard sockets or secure connection via TLS/SSL.
The package is fully implemented in Tcl.
This document describes the procedures and explains their usage.
# <a name='section2'></a>PROCEDURES
This package defines the following public procedures:
- <a name='1'></a>__::imap4::open__ *hostname* ?*port*?
Open a new IMAP connection and initalize the handler, the imap communication
channel (handler) is returned.
*hostname* - mail server
*port* - connection port, defaults to 143
The namespace variable __::imap4::use_ssl__ can be used to establish to a
secure connection via TSL/SSL if set to true. In this case default
connection port defaults to 993.
*Note:* For connecting via SSL the Tcl module *tls* must be already loaded
otherwise an error is raised.
package require tls ; # must be loaded for TLS/SSL
set ::imap4::use_ssl 1 ; # request a secure connection
set chan [::imap4::open $server] ; # default port is now 993
- <a name='2'></a>__::imap4::starttls__ *chan*
Use this when tasked with connecting to an unsecure port which must be
changed to a secure port prior to user login. This feature is known as
*STARTTLS*.
- <a name='3'></a>__::imap4::login__ *chan* *user* *pass*
Login using the IMAP LOGIN command, 0 is returned on successful login.
*chan* - imap channel
*user* - username
*pass* - password
- <a name='4'></a>__::imap4::folders__ *chan* ?*-inline*? ?*mboxref*? ?*mboxname*?
Get list of matching folders, 0 is returned on success.
Wildcards '*' as '%' are allowed for *mboxref* and *mboxname*, command
__::imap4::folderinfo__ can be used to retrieve folder information.
*chan* - imap channel
*mboxref* - mailbox reference, defaults to ""
*mboxname* - mailbox name, defaults to "*"
If __-inline__ is specified a compact folderlist is returned instead of the
result code. All flags are converted to lowercase and leading special
characters are removed.
{{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}
- <a name='5'></a>__::imap4::select__ *chan* ?*mailbox*?
Select a mailbox, 0 is returned on success.
*chan* - imap channel
*mailbox* - Path of the mailbox, defaults to *INBOX*
Prior to examine/select an open mailbox must be closed - see:
__::imap4::close__.
- <a name='6'></a>__::imap4::examine__ *chan* ?*mailbox*?
"Examines" a mailbox, read-only equivalent of __::imap4::select__.
*chan* - imap channel
*mailbox* - mailbox name or path to mailbox, defaults to *INBOX*
Prior to examine/select an open mailbox must be closed - see:
__::imap4::close__.
- <a name='7'></a>__::imap4::fetch__ *chan* *range* ?*-inline*? ?*attr ...*?
Fetch attributes from messages.
The attributes are fetched and stored in the internal state which can be
retrieved with command __::imap4::msginfo__, 0 is returned on success. If
__-inline__ is specified, alle records are returned as list in order as
defined in the *attr* argument.
*chan* - imap channel
*range* - message index in format *FROM*:*TO*
*attr* - imap attributes to fetch
*Note:* If *FROM* is omitted, the 1st message is assumed, if *TO* is
ommitted the last message is assumed. All message index ranges are 1-based.
- <a name='8'></a>__::imap4::noop__ *chan*
Send NOOP command to server. May get information as untagged data.
*chan* - imap channel
- <a name='9'></a>__::imap4::check__ *chan*
Send CHECK command to server. Flush to disk.
*chan* - imap channel
- <a name='10'></a>__::imap4::folderinfo__ *chan* ?*info*?
Get information on the recently selected folderlist. If the *info* argument
is omitted or a null string, the full list of information available for the
mailbox is returned.
If the required information name is suffixed with a ? character, the command
returns true if the information is available, or false if it is not.
*chan* - imap channel
*info* - folderlist options to retrieve
Currently supported options: *delim* - hierarchy delimiter only, *match* -
ref and mbox search patterns (see __::imap4::folders__), *names* - list of
folder names only, *flags* - list of folder names with flags in format *{
{name {flags}} ... }* (see also compact format in function
__::imap4::folders__).
{{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}
- <a name='11'></a>__::imap4::msginfo__ *chan* *msgid* ?*info*? ?*defval*?
Get information (from previously collected using fetch) from a given
*msgid*. If the 'info' argument is omitted or a null string, the list of
available information options for the given message is returned.
If the required information name is suffixed with a ? character, the command
returns true if the information is available, or false if it is not.
*chan* - imap channel
*msgid* - message number
*info* - imap keyword to retrieve
*defval* - default value, returned if info is empty
*Note:* All message index ranges are 1-based.
- <a name='12'></a>__::imap4::mboxinfo__ *chan* ?*info*?
Get information on the currently selected mailbox. If the *info* argument is
omitted or a null string, the list of available information options for the
mailbox is returned.
If the required information name is suffixed with a ? character, the command
returns true if the information is available, or false if it is not.
*chan* - imap channel
*opt* - mailbox option to retrieve
Currently supported options: *EXISTS* (noof msgs), *RECENT* (noof 'recent'
flagged msgs), *FLAGS*
In conjunction with OK: *PERMFLAGS*, *UIDNEXT*, *UIDVAL*, *UNSEEN*
Div. states: *CURRENT*, *FOUND*, *PERM*.
::imap4::select $chan INBOX
puts "[::imap4::mboxinfo $chan exists] mails in INBOX"
- <a name='13'></a>__::imap4::isableto__ *chan* ?*capability*?
Test for capability. It returns 1 if requested capability is supported, 0
otherwise. If *capability* is omitted all capability imap codes are retured
as list.
*chan* - imap channel
*info* - imap keyword to retrieve
*Note:* Use the capability command to ask the server if not already done by
the user.
- <a name='14'></a>__::imap4::create__ *chan* *mailbox*
Create a new mailbox.
*chan* - imap channel
*mailbox* - mailbox name
- <a name='15'></a>__::imap4::delete__ *chan* *mailbox*
Delete a new mailbox.
*chan* - imap channel
*mailbox* - mailbox name
- <a name='16'></a>__::imap4::rename__ *chan* *oldname* *newname*
Rename a new mailbox.
*chan* - imap channel
*mailbox* - old mailbox name
*mailbox* - new mailbox name
- <a name='17'></a>__::imap4::subscribe__ *chan* *mailbox*
Subscribe a new mailbox.
*chan* - imap channel
*mailbox* - mailbox name
- <a name='18'></a>__::imap4::unsubscribe__ *chan* *mailbox*
Unsubscribe a new mailbox.
*chan* - imap channel
*mailbox* - mailbox name
- <a name='19'></a>__::imap4::search__ *chan* *expr* ?*...*?
Search for mails matching search criterions, 0 is returned on success.
*chan* - imap channel
*expr* - imap search expression
*Notes:* Currently the following search expressions are handled:
*Mail header flags:* all mail header entries (ending with a colon ":"), like
"From:", "Bcc:", ...
*Imap message search flags:* ANSWERED, DELETED, DRAFT, FLAGGED, RECENT,
SEEN, NEW, OLD, UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, UNSEEN, ALL
*Imap header search flags:* BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC
*Imap conditional search flags:* SMALLER, LARGER, ON, SENTBEFORE, SENTON,
SENTSINCE, SINCE, BEFORE (not implemented), UID (not implemented)
*Logical search conditions:* OR, NOT
::imap4::search $chan larger 4000 seen
puts "Found messages: [::imap4::mboxinfo $chan found]"
Found messages: 1 3 6 7 8 9 13 14 15 19 20
- <a name='20'></a>__::imap4::close__ *chan*
Close the mailbox. Permanently removes \Deleted messages and return to the
AUTH state.
*chan* - imap channel
- <a name='21'></a>__::imap4::cleanup__ *chan*
Destroy an IMAP connection and free the used space. Close the mailbox.
Permanently removes \Deleted messages and return to the AUTH state.
*chan* - imap channel
- <a name='22'></a>__::imap4::debugmode__ *chan* ?*errormsg*?
Switch client into command line debug mode.
This is a developers mode only that pass the control to the programmer.
Every line entered is sent verbatim to the server (after the addition of the
request identifier). The ::imap4::debug variable is automatically set to '1'
on enter.
It's possible to execute Tcl commands starting the line with a slash.
*chan* - imap channel
*errormsg* - optional error message to display
- <a name='23'></a>__::imap4::store__ *chan* *range* *data* *flaglist*
Alters data associated with a message in the selected mailbox.
*chan* - imap channel
*range* - message index in format *FROM*:*TO*
*flaglist* - Flags the *data* operates on.
*data* - The currently defined *data* items that can be stored are shown
below. *Note* that all of these data types may also be suffixed with
".SILENT" to suppress the untagged FETCH response.
* FLAGS
Replace the flags for the message (other than \Recent) with the
*flaglist*.
* +FLAGS
Add the flags in *flaglist* to the existing flags for the message.
* -FLAGS
Remove the flags in *flaglist* to the existing flags for the message.
For example:
::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted"
- <a name='24'></a>__::imap4::expunge__ *chan*
Permanently removes all messages that have the \Deleted flag set from the
currently selected mailbox, without the need to close the connection.
*chan* - imap channel
- <a name='25'></a>__::imap4::copy__ *chan* *msgid* *mailbox*
Copies the specified message (identified by its message number) to the named
mailbox, i.e. imap folder.
*chan* - imap channel
*msgid* - message number
*mailbox* - mailbox name
- <a name='26'></a>__::imap4::logout__ *chan*
Informs the server that the client is done with the connection and closes
the network connection. Permanently removes \Deleted messages.
A new connection will need to be established to login once more.
*chan* - imap channel
# <a name='section3'></a>EXAMPLES
set user myusername
set pass xtremescrt
set server imap.test.tld
set FOLDER INBOX
# Connect to server
set imap [::imap4::open $server]
::imap4::login $imap $user $pass
::imap4::select $imap $FOLDER
# Output all the information about that mailbox
foreach info [::imap4::mboxinfo $imap] {
puts "$info -> [::imap4::mboxinfo $imap $info]"
}
# fetch 3 records inline
set fields {from: to: subject: size}
foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] {
puts -nonewline "#[incr idx])"
for {set j 0} {$j<[llength $fields]} {incr j} {
puts "\t[lindex $fields $j] [lindex $rec $j]"
}
}
# Show all the information available about the message ID 1
puts "Available info about message 1: [::imap4::msginfo $imap 1]"
# Use the capability stuff
puts "Capabilities: [::imap4::isableto $imap]"
puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"
# Cleanup
::imap4::cleanup $imap
# <a name='section4'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section5'></a>REFERENCES
Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501,
March 2003,
[http://www.rfc-editor.org/rfc/rfc3501.txt](http://www.rfc-editor.org/rfc/rfc3501.txt)
OpenSSL, [http://www.openssl.org/](http://www.openssl.org/)
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *imap4* 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. Only a small part of rfc3501 implemented.
# <a name='see-also'></a>SEE ALSO
[ftp](../ftp/ftp.md), [http](../../../../index.md#http),
[imap](../../../../index.md#imap), [mime](../mime/mime.md),
[pop3](../pop3/pop3.md), [tls](../../../../index.md#tls)
# <a name='keywords'></a>KEYWORDS
[email](../../../../index.md#email), [imap](../../../../index.md#imap),
[internet](../../../../index.md#internet), [mail](../../../../index.md#mail),
[net](../../../../index.md#net), [rfc3501](../../../../index.md#rfc3501),
[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls)
|
Added embedded/md/tcllib/files/modules/inifile/ini.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
[//000000001]: # (inifile - Parsing of Windows INI files)
[//000000002]: # (Generated from file 'ini.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (inifile(n) 0.3.1 tcllib "Parsing of Windows INI files")
# NAME
inifile - Parsing of Windows INI files
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require inifile ?0.3.1?
[__::ini::open__ *file* ?__-encoding__ *encoding*? ?*access*?](#1)
[__::ini::close__ *ini*](#2)
[__::ini::commit__ *ini*](#3)
[__::ini::revert__ *ini*](#4)
[__::ini::filename__ *ini*](#5)
[__::ini::sections__ *ini*](#6)
[__::ini::keys__ *ini* *section*](#7)
[__::ini::get__ *ini* *section*](#8)
[__::ini::exists__ *ini* *section* ?*key*?](#9)
[__::ini::value__ *ini* *section* *key* ?*default*?](#10)
[__::ini::set__ *ini* *section* *key* *value*](#11)
[__::ini::delete__ *ini* *section* ?*key*?](#12)
[__::ini::comment__ *ini* *section* ?*key*? ?*text*?](#13)
[__::ini::commentchar__ ?char?](#14)
# <a name='description'></a>DESCRIPTION
This package provides an interface for easy manipulation of Windows INI files.
- <a name='1'></a>__::ini::open__ *file* ?__-encoding__ *encoding*? ?*access*?
Opens an INI file and returns a handle that is used by other commands.
*access* is the same as the first form (non POSIX) of the __open__ command,
with the exception that mode __a__ is not supported. The default mode is
__r+__.
The default *encoding* is the system encoding.
- <a name='2'></a>__::ini::close__ *ini*
Close the specified handle. If any changes were made and not written by
__commit__ they are lost.
- <a name='3'></a>__::ini::commit__ *ini*
Writes the file and all changes to disk. The sections are written in
arbitrary order. The keys in a section are written in alphabetical order. If
the ini was opened in read only mode an error will be thrown.
- <a name='4'></a>__::ini::revert__ *ini*
Rolls all changes made to the inifile object back to the last committed
state.
- <a name='5'></a>__::ini::filename__ *ini*
Returns the name of the file the *ini* object is associated with.
- <a name='6'></a>__::ini::sections__ *ini*
Returns a list of all the names of the existing sections in the file handle
specified.
- <a name='7'></a>__::ini::keys__ *ini* *section*
Returns a list of all they key names in the section and file specified.
- <a name='8'></a>__::ini::get__ *ini* *section*
Returns a list of key value pairs that exist in the section and file
specified.
- <a name='9'></a>__::ini::exists__ *ini* *section* ?*key*?
Returns a boolean value indicating the existance of the specified section as
a whole or the specified key within that section.
- <a name='10'></a>__::ini::value__ *ini* *section* *key* ?*default*?
Returns the value of the named key and section. If specified, the default
value will be returned if the key does not exist. If the key does not exist
and no default is specified an error will be thrown.
- <a name='11'></a>__::ini::set__ *ini* *section* *key* *value*
Sets the value of the key in the specified section. If the section does not
exist then a new one is created.
- <a name='12'></a>__::ini::delete__ *ini* *section* ?*key*?
Removes the key or the entire section and all its keys. A section is not
automatically deleted when it has no remaining keys.
- <a name='13'></a>__::ini::comment__ *ini* *section* ?*key*? ?*text*?
Reads and modifies comments for sections and keys. To write a section
comment use an empty string for the *key*. To remove all comments use an
empty string for *text*. *text* may consist of a list of lines or one single
line. Any embedded newlines in *text* are properly handled. Comments may be
written to nonexistant sections or keys and will not return an error.
Reading a comment from a nonexistant section or key will return an empty
string.
- <a name='14'></a>__::ini::commentchar__ ?char?
Reads and sets the comment character. Lines that begin with this character
are treated as comments. When comments are written out each line is preceded
by this character. The default is __;__.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *inifile* 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.
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/interp/deleg_method.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (deleg_method - Interpreter utilities)
[//000000002]: # (Generated from file 'deleg_method.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (deleg_method(n) 0.2 tcllib "Interpreter utilities")
# NAME
deleg_method - Creation of comm delegates (snit methods)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require snit ?1.1?
package require interp::delegate::method ?0.2?
[__::interp::delegate::method__ ?__-async__? *name* *arguments* *comm* *id*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single command for use within
__[snit](../snit/snit.md)__ type definition (i.e. actually a __snit::macro__)
for the convenient creation of methods which delegate the actual work to a
remote location via a "channel" created by the package
__[comm](../comm/comm.md)__.
# <a name='section2'></a>API
- <a name='1'></a>__::interp::delegate::method__ ?__-async__? *name* *arguments* *comm* *id*
This commands creates a method which is named by *name*. All invokations of
this method will delegate the actual work to the remote location identified
by the comm channel *comm* and the endpoint *id*.
The name of the remote method invoked by the delegator is identical to the
name of the method itself.
Normally the generated method marshalls the *arguments*, and returns the
result from the remote method as its own result. If however the option
__-async__ was specified then the generated method will not wait for a
result and return immediately.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *interp* 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.
# <a name='keywords'></a>KEYWORDS
[comm](../../../../index.md#comm),
[delegation](../../../../index.md#delegation),
[interpreter](../../../../index.md#interpreter),
[method](../../../../index.md#method), [snit](../../../../index.md#snit)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/interp/deleg_proc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
[//000000001]: # (deleg_proc - Interpreter utilities)
[//000000002]: # (Generated from file 'deleg_proc.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (deleg_proc(n) 0.2 tcllib "Interpreter utilities")
# NAME
deleg_proc - Creation of comm delegates (procedures)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require interp::delegate::proc ?0.2?
[__::interp::delegate::proc__ ?__-async__? *name* *arguments* *comm* *id*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single command for the convenient creation of procedures
which delegate the actual work to a remote location via a "channel" created by
the package __[comm](../comm/comm.md)__.
# <a name='section2'></a>API
- <a name='1'></a>__::interp::delegate::proc__ ?__-async__? *name* *arguments* *comm* *id*
This commands creates a procedure which is named by *name* and returns its
fully-qualified name. All invokations of this procedure will delegate the
actual work to the remote location identified by the comm channel *comm* and
the endpoint *id*.
The name of the remote procedure invoked by the delegator is [namespace tail
*name*]. I.e., namespace information is stripped from the call.
Normally the generated procedure marshalls the *arguments*, and returns the
result from the remote procedure as its own result. If however the option
__-async__ was specified then the generated procedure will not wait for a
result and return immediately.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *interp* 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.
# <a name='keywords'></a>KEYWORDS
[comm](../../../../index.md#comm),
[delegation](../../../../index.md#delegation),
[interpreter](../../../../index.md#interpreter),
[procedure](../../../../index.md#procedure)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/interp/tcllib_interp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
[//000000001]: # (interp - Interpreter utilities)
[//000000002]: # (Generated from file 'tcllib_interp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (interp(n) 0.1.2 tcllib "Interpreter utilities")
# NAME
interp - Interp creation and aliasing
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require interp ?0.1.2?
[__::interp::createEmpty__ ?*path*?](#1)
[__::interp::snitLink__ *path* *methodlist*](#2)
[__::interp::snitDictLink__ *path* *methoddict*](#3)
# <a name='description'></a>DESCRIPTION
This package provides a number of commands for the convenient creation of Tcl
interpreters for highly restricted execution.
# <a name='section2'></a>API
- <a name='1'></a>__::interp::createEmpty__ ?*path*?
This commands creates an empty Tcl interpreter and returns it name. Empty
means that the new interpreter has neither namespaces, nor any commands. It
is useful only for the creation of aliases.
If a *path* is specified then it is taken as the name of the new
interpreter.
- <a name='2'></a>__::interp::snitLink__ *path* *methodlist*
This command assumes that it was called from within a method of a snit
object, and that the command __mymethod__ is available.
It extends the interpreter specified by *path* with aliases for all methods
found in the *methodlist*, with the alias directing execution to the
same-named method of the snit object invoking this command. Each element of
*methodlist* is actually interpreted as a command prefix, with the first
word of each prefix the name of the method to link to.
The result of the command is the empty string.
- <a name='3'></a>__::interp::snitDictLink__ *path* *methoddict*
This command behaves like __::interp::snitLink__, except that it takes a
dictionary mapping from commands to methods as its input, and not a list of
methods. Like for __::interp::snitLink__ the method references are actually
command prefixes. This command allows the creation of more complex
command-method mappings than __::interp::snitLink__.
The result of the command is the empty string.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *interp* 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.
# <a name='keywords'></a>KEYWORDS
[alias](../../../../index.md#alias), [empty
interpreter](../../../../index.md#empty_interpreter),
[interpreter](../../../../index.md#interpreter),
[method](../../../../index.md#method), [snit](../../../../index.md#snit)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/irc/irc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
[//000000001]: # (irc - Low Level Tcl IRC Interface)
[//000000002]: # (Generated from file 'irc.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (irc(n) 0.6.2 tcllib "Low Level Tcl IRC Interface")
# NAME
irc - Create IRC connection and interface.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Per-connection Commands](#section2)
- [Callback Commands](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl
package require irc ?0.6.2?
[__::irc::config__ ?key? ?value?](#1)
[__::irc::connection__](#2)
[__::irc::connections__](#3)
[*net* __registerevent__ *event* *script*](#4)
[*net* __getevent__ *event* *script*](#5)
[*net* __eventexists__ *event* *script*](#6)
[*net* __connect__ *hostname* ?port?](#7)
[*net* __config__ ?key? ?value?](#8)
[*net* __log__ *level* *message*](#9)
[*net* __logname__](#10)
[*net* __connected__](#11)
[*net* __sockname__](#12)
[*net* __peername__](#13)
[*net* __socket__](#14)
[*net* __user__ *username* *localhostname* *localdomainname* *userinfo*](#15)
[*net* __nick__ *nick*](#16)
[*net* __ping__ *target*](#17)
[*net* __serverping__](#18)
[*net* __join__ *channel* ?*key*?](#19)
[*net* __part__ *channel* ?*message*?](#20)
[*net* __quit__ ?*message*?](#21)
[*net* __privmsg__ *target* *message*](#22)
[*net* __notice__ *target* *message*](#23)
[*net* __ctcp__ *target* *message*](#24)
[*net* __kick__ *channel* *target* ?*message*?](#25)
[*net* __mode__ *target* *args*](#26)
[*net* __topic__ *channel* *message*](#27)
[*net* __invite__ *channel* *target*](#28)
[*net* __send__ *text*](#29)
[*net* __destroy__](#30)
[__who__ ?__address__?](#31)
[__action__](#32)
[__target__](#33)
[__additional__](#34)
[__header__](#35)
[__msg__](#36)
# <a name='description'></a>DESCRIPTION
This package provides low-level commands to deal with the IRC protocol (Internet
Relay Chat) for immediate and interactive multi-cast communication.
- <a name='1'></a>__::irc::config__ ?key? ?value?
Sets configuration ?key? to ?value?. The configuration keys currently
defined are the boolean flags __logger__ and __debug__. __logger__ makes
__irc__ use the logger package for printing error. __debug__ requires
__logger__ and prints extra debug output. If no ?key? or ?value? is given
the current values are returned.
- <a name='2'></a>__::irc::connection__
The command creates a new object to deal with an IRC connection. Creating
this IRC object does not automatically create the network connection. It
returns a new irc namespace command which can be used to interact with the
new IRC connection. NOTE: the old form of the connection command, which took
a hostname and port as arguments, is deprecated. Use __connect__ instead to
specify this information.
- <a name='3'></a>__::irc::connections__
Returns a list of all the current connections that were created with
__connection__
# <a name='section2'></a>Per-connection Commands
In the following list of available connection methods *net* represents a
connection command as returned by __::irc::connection__.
- <a name='4'></a>*net* __registerevent__ *event* *script*
Registers a callback handler for the specific event. Events available are
those described in RFC 1459
[http://www.rfc-editor.org/rfc/rfc1459.txt](http://www.rfc-editor.org/rfc/rfc1459.txt).
In addition, there are several other events defined. __defaultcmd__ adds a
command that is called if no other callback is present. __EOF__ is called if
the connection signals an End of File condition. The events __defaultcmd__,
__defaultnumeric__, __defaultevent__, and __EOF__ are required. *script* is
executed in the connection namespace, which can take advantage of several
commands (see [Callback Commands](#section3) below) to aid in the parsing of
data.
- <a name='5'></a>*net* __getevent__ *event* *script*
Returns the current handler for the event if one exists. Otherwise an empty
string is returned.
- <a name='6'></a>*net* __eventexists__ *event* *script*
Returns a boolean value indicating the existence of the event handler.
- <a name='7'></a>*net* __connect__ *hostname* ?port?
This causes the socket to be established. __::irc::connection__ created the
namespace and the commands to be used, but did not actually open the socket.
This is done here. NOTE: the older form of 'connect' did not require the
user to specify a hostname and port, which were specified with 'connection'.
That form is deprecated.
- <a name='8'></a>*net* __config__ ?key? ?value?
The same as __::irc::config__ but sets and gets options for the *net*
connection only.
- <a name='9'></a>*net* __log__ *level* *message*
If logger is turned on by __config__ this will write a log *message* at
*level*.
- <a name='10'></a>*net* __logname__
Returns the name of the logger instance if logger is turned on.
- <a name='11'></a>*net* __connected__
Returns a boolean value indicating if this connection is connected to a
server.
- <a name='12'></a>*net* __sockname__
Returns a 3 element list consisting of the ip address, the hostname, and the
port of the local end of the connection, if currently connected.
- <a name='13'></a>*net* __peername__
Returns a 3 element list consisting of the ip address, the hostname, and the
port of the remote end of the connection, if currently connected.
- <a name='14'></a>*net* __socket__
Return the Tcl channel for the socket used by the connection.
- <a name='15'></a>*net* __user__ *username* *localhostname* *localdomainname* *userinfo*
Sends USER command to server. *username* is the username you want to appear.
*localhostname* is the host portion of your hostname, *localdomainname* is
your domain name, and *userinfo* is a short description of who you are. The
2nd and 3rd arguments are normally ignored by the IRC server.
- <a name='16'></a>*net* __nick__ *nick*
NICK command. *nick* is the nickname you wish to use for the particular
connection.
- <a name='17'></a>*net* __ping__ *target*
Send a CTCP PING to *target*.
- <a name='18'></a>*net* __serverping__
PING the server.
- <a name='19'></a>*net* __join__ *channel* ?*key*?
*channel* is the IRC channel to join. IRC channels typically begin with a
hashmark ("#") or ampersand ("&").
- <a name='20'></a>*net* __part__ *channel* ?*message*?
Makes the client leave *channel*. Some networks may support the optional
argument *message*
- <a name='21'></a>*net* __quit__ ?*message*?
Instructs the IRC server to close the current connection. The package will
use a generic default if no *message* was specified.
- <a name='22'></a>*net* __privmsg__ *target* *message*
Sends *message* to *target*, which can be either a channel, or another user,
in which case their nick is used.
- <a name='23'></a>*net* __notice__ *target* *message*
Sends a __notice__ with message *message* to *target*, which can be either a
channel, or another user, in which case their nick is used.
- <a name='24'></a>*net* __ctcp__ *target* *message*
Sends a CTCP of type *message* to *target*
- <a name='25'></a>*net* __kick__ *channel* *target* ?*message*?
Kicks the user *target* from the channel *channel* with a *message*. The
latter can be left out.
- <a name='26'></a>*net* __mode__ *target* *args*
Sets the mode *args* on the target *target*. *target* may be a channel, a
channel user, or yourself.
- <a name='27'></a>*net* __topic__ *channel* *message*
Sets the topic on *channel* to *message* specifying an empty string will
remove the topic.
- <a name='28'></a>*net* __invite__ *channel* *target*
Invites *target* to join the channel *channel*
- <a name='29'></a>*net* __send__ *text*
Sends *text* to the IRC server.
- <a name='30'></a>*net* __destroy__
Deletes the connection and its associated namespace and information.
# <a name='section3'></a>Callback Commands
These commands can be used within callbacks
- <a name='31'></a>__who__ ?__address__?
Returns the nick of the user who performed a command. The optional keyword
__address__ causes the command to return the user in the format
"username@address".
- <a name='32'></a>__action__
Returns the action performed, such as KICK, PRIVMSG, MODE, etc... Normally
not useful, as callbacks are bound to a particular event.
- <a name='33'></a>__target__
Returns the target of a particular command, such as the channel or user to
whom a PRIVMSG is sent.
- <a name='34'></a>__additional__
Returns a list of any additional arguments after the target.
- <a name='35'></a>__header__
Returns the entire event header (everything up to the :) as a proper list.
- <a name='36'></a>__msg__
Returns the message portion of the command (the part after the :).
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *irc* 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.
# <a name='see-also'></a>SEE ALSO
rfc 1459
# <a name='keywords'></a>KEYWORDS
[chat](../../../../index.md#chat), [irc](../../../../index.md#irc)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/irc/picoirc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
[//000000001]: # (picoirc - Simple embeddable IRC interface)
[//000000002]: # (Generated from file 'picoirc.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (picoirc(n) 0.5.2 tcllib "Simple embeddable IRC interface")
# NAME
picoirc - Small and simple embeddable IRC client.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [CALLBACK](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl
package require picoirc ?0.5.2?
[__::picoirc::connect__ *callback* *nick* *url*](#1)
[__::picoirc::post__ *context* *channel* *message*](#2)
[__::picoirc::splituri__ *uri*](#3)
[__::picoirc::send__ *context* *line*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a general purpose minimal IRC client suitable for
embedding in other applications. All communication with the parent application
is done via an application provided callback procedure. Each connection has its
own state so you can hook up multiple servers in a single application instance.
To initiate an IRC connection you must call __picoirc::connect__ with a callback
procedure, a nick-name to use on IRC and the IRC URL that describes the
connection. This will return a variable name that is the irc connection context.
See [CALLBACK](#section3) for details.
This package is a fairly simple IRC client. If you need something with more
capability investigate the __[irc](irc.md)__ package.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::picoirc::connect__ *callback* *nick* *url*
Create a new irc connection to the server specified by *url* and login using
the *nick* as the username. The *callback* must be as specified in
[CALLBACK](#section3). Returns a package-specific variable that is used when
calling other commands in this package.
- <a name='2'></a>__::picoirc::post__ *context* *channel* *message*
This should be called to process user input and send it to the server. A
number of commands are recognised when prefixed with a forward-slash (/).
Such commands are converted to IRC command sequences and then sent.
- <a name='3'></a>__::picoirc::splituri__ *uri*
Splits an IRC scheme uniform resource indicator into its component parts.
Returns a list of server, port and channel. The default port is 6667 and
there is no default channel.
- <a name='4'></a>__::picoirc::send__ *context* *line*
This command is where all raw output to the server is handled. The default
action is to write the *line* to the irc socket. However, before this
happens the callback is called with "debug write". This permits the
application author to inspect the raw IRC data and if desired to return a
break error code to halt further processing. In this way the application can
override the default send via the callback procedure.
# <a name='section3'></a>CALLBACK
The callback must look like:
proc Callback {context state args} {
}
where context is the irc context variable name (in case you need to pass it back
to a picoirc procedure). state is one of a number of states as described below.
- __init__
called just before the socket is created
- __connect__
called once we have connected, before we join any channels
- __close__
called when the socket gets closed, before the context is deleted. If an
error occurs before we get connected the only argument will be the socket
error message.
- __userlist__ *channel* *nicklist*
called to notify the application of an updated userlist. This is generated
when the output of the NAMES irc command is seen. The package collects the
entire output which can span a number of output lines from the server and
calls this callback when they have all been received.
- __chat__ *target* *nick* *message* *type*
called when a message arrives. *target* is the identity that the message was
targetted for. This can be the logged in nick or a channel name. *nick* is
the name of the sender of the message. *message* is the message text. *type*
is set to "ACTION" if the message was sent as a CTCP ACTION
- __system__ *channel* *message*
called when a system message is received
- __topic__ *channel* *topic*
called when the channel topic string is seen. *topic* is the text of the
channel topic.
- __traffic__ *action* *channel* *nick* ?*newnick*?
called when users join, leave or change names. *action* is either entered,
left or nickchange and *nick* is the user doing the action. *newnick* is the
new name if *action* is nickchange.
*NOTE*: *channel* is often empty for these messages as nick activities are
global for the irc server. You will have to manage the nick for all
connected channels yourself.
- __version__
This is called to request a version string to use to override the internal
version. If implemented, you should return as colon delimited string as
Appname:Appversion:LibraryVersion
For example, the default is
PicoIRC:[package provide picoirc]:Tcl [info patchlevel]
- __debug__ *type* *raw*
called when data is either being read or written to the network socket.
*type* is set to __read__ when reading data and __write__ if the data is to
be written. *raw* is the unprocessed IRC protocol data.
In both cases the application can return a break error code to interrupt
further processing of the raw data. If this is a __read__ operation then the
package will not handle this line. If the operation is __write__ then the
package will not send the data. This callback is intended for debugging
protocol issues but could be used to redirect all input and output if
desired.
# <a name='see-also'></a>SEE ALSO
rfc 1459
# <a name='keywords'></a>KEYWORDS
[chat](../../../../index.md#chat), [irc](../../../../index.md#irc)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/javascript/javascript.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
[//000000001]: # (javascript - HTML and Java Script Generation)
[//000000002]: # (Generated from file 'javascript.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (javascript(n) 1.0.2 tcllib "HTML and Java Script Generation")
# NAME
javascript - Procedures to generate HTML and Java Script structures.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require javascript ?1.0.2?
[__::javascript::makeSelectorWidget__ *id leftLabel leftValueList rightLabel rightValueList rightNameList* ?*length*? ?*minWidth*?](#1)
[__::javascript::makeSubmitButton__ *name value*](#2)
[__::javascript::makeProtectedSubmitButton__ *name value msg*](#3)
[__::javascript::makeMasterButton__ *master value slavePattern boolean*](#4)
[__::javascript::makeParentCheckbox__ *parentName childName*](#5)
[__::javascript::makeChildCheckbox__ *parentName childName*](#6)
# <a name='description'></a>DESCRIPTION
The __::javascript__ package provides commands that generate HTML and Java
Script code. These commands typically return an HTML string as their result. In
particular, they do not output their result to __stdout__.
- <a name='1'></a>__::javascript::makeSelectorWidget__ *id leftLabel leftValueList rightLabel rightValueList rightNameList* ?*length*? ?*minWidth*?
Construct HTML code to create a dual-multi-selection megawidget. This
megawidget consists of two side-by-side multi-selection boxes separated by a
left arrow and a right arrow button. The right arrow button moves all items
selected in the left box to the right box. The left arrow button moves all
items selected in the right box to the left box. The *id* argument is the
suffix of all HTML objects in this megawidget. The *leftLabel* argument is
the text that appears above the left selection box. The *leftValueList*
argument is the values of items in the left selection box. The
*leftNameList* argument is the names to appear in the left selection box.
The *rightLabel* argument is the text that appears above the right selection
box. The *rightValueList* argument is the values of items in the right
selection box. The *rightNameList* argument is the names to appear in the
right selection box. The *length* argument (optional) determines the number
of elts to show before adding a vertical scrollbar; it defaults to 8. The
*minWidth* argument (optional) is the number of spaces to determine the
minimum box width; it defaults to 32.
- <a name='2'></a>__::javascript::makeSubmitButton__ *name value*
Create an HTML submit button that resets a hidden field for each registered
multi-selection box. The *name* argument is the name of the HTML button
object to create. The *value* argument is the label of the HTML button
object to create.
- <a name='3'></a>__::javascript::makeProtectedSubmitButton__ *name value msg*
Create an HTML submit button that prompts the user with a continue/cancel
shutdown warning before the form is submitted. The *name* argument is the
name of the HTML button object to create. The *value* argument is the label
of the HTML button object to create. The *msg* argument is the message to
display when the button is pressed.
- <a name='4'></a>__::javascript::makeMasterButton__ *master value slavePattern boolean*
Create an HTML button that sets its slave checkboxs to the boolean value.
The *master* argument is the name of the child's parent html checkbox
object. The *value* argument is the value of the master. The *slaves*
argument is the name of child html checkbox object to create. The *boolean*
argument is the java script boolean value that will be given to all the
slaves; it must be "true" or "false".
- <a name='5'></a>__::javascript::makeParentCheckbox__ *parentName childName*
Create an HTML checkbox and tie its value to that of its child checkbox. If
the parent is unchecked, the child is automatically unchecked. The
*parentName* argument is the name of parent html checkbox object to create.
The *childName* argument is the name of the parent's child html checkbox
object.
- <a name='6'></a>__::javascript::makeChildCheckbox__ *parentName childName*
Create an HTML checkbox and tie its value to that of its parent checkbox. If
the child is checked, the parent is automatically checked. The *parentName*
argument is the name of the child's parent html checkbox object. The
*childName* argument is the name of child html checkbox object to create.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *javascript* 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.
# <a name='see-also'></a>SEE ALSO
[html](../html/html.md), [ncgi](../ncgi/ncgi.md)
# <a name='keywords'></a>KEYWORDS
[checkbox](../../../../index.md#checkbox), [html](../../../../index.md#html),
[javascript](../../../../index.md#javascript),
[selectionbox](../../../../index.md#selectionbox),
[submitbutton](../../../../index.md#submitbutton)
# <a name='category'></a>CATEGORY
CGI programming
|
Added embedded/md/tcllib/files/modules/jpeg/jpeg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
[//000000001]: # (jpeg - JPEG image manipulation)
[//000000002]: # (Generated from file 'jpeg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (jpeg(n) 0.5 tcllib "JPEG image manipulation")
# NAME
jpeg - JPEG querying and manipulation of meta data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [LIMITATIONS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require jpeg ?0.5?
[__::jpeg::isJPEG__ *file*](#1)
[__::jpeg::imageInfo__ *file*](#2)
[__::jpeg::dimensions__ *file*](#3)
[__::jpeg::getThumbnail__ *file*](#4)
[__::jpeg::getExif__ *file* ?*section*?](#5)
[__::jpeg::getExifFromChannel__ *channel* ?*section*?](#6)
[__::jpeg::formatExif__ *keys*](#7)
[__::jpeg::exifKeys__](#8)
[__::jpeg::removeExif__ *file*](#9)
[__::jpeg::stripJPEG__ *file*](#10)
[__::jpeg::getComments__ *file*](#11)
[__::jpeg::addComment__ *file* *text*...](#12)
[__::jpeg::removeComments__ *file*](#13)
[__::jpeg::replaceComment__ *file* *text*](#14)
[__::jpeg::debug__ *file*](#15)
[__::jpeg::markers__ *channel*](#16)
# <a name='description'></a>DESCRIPTION
This package provides commands to query and modify JPEG images. JPEG stands for
*Joint Photography Experts Group* and is a standard for the lossy compression of
photographical images. It is specified at [LINK_HERE](LINK_HERE).
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::jpeg::isJPEG__ *file*
Returns a boolean value indicating if *file* is a JPEG image.
- <a name='2'></a>__::jpeg::imageInfo__ *file*
Returns a dictionary with keys __version__, __units__, __xdensity__,
__ydensity__, __xthumb__, and __ythumb__. The values are the associated
properties of the JPEG image in *file*. Throws an error if *file* is not a
JPEG image.
- <a name='3'></a>__::jpeg::dimensions__ *file*
Returns the dimensions of the JPEG *file* as a list of the horizontal and
vertical pixel count. Throws an error if *file* is not a JPEG image.
- <a name='4'></a>__::jpeg::getThumbnail__ *file*
This procedure will return the binary thumbnail image data, if a JPEG
thumbnail is included in *file*, and the empty string otherwise. Note that
it is possible to include thumbnails in formats other than JPEG although
that is not common. The command finds thumbnails that are encoded in either
the JFXX or EXIF segments of the JPEG information. If both are present the
EXIF thumbnail will take precedence. Throws an error if *file* is not a JPEG
image.
set fh [open thumbnail.jpg w+]
fconfigure $fh -translation binary -encoding binary
puts -nonewline $fh [::jpeg::getThumbnail photo.jpg]
close $fh
- <a name='5'></a>__::jpeg::getExif__ *file* ?*section*?
*section* must be one of __main__ or __thumbnail__. The default is __main__.
Returns a dictionary containing the EXIF information for the specified
section. For example:
set exif {
Make Canon
Model {Canon DIGITAL IXUS}
DateTime {2001:06:09 15:17:32}
}
Throws an error if *file* is not a JPEG image.
- <a name='6'></a>__::jpeg::getExifFromChannel__ *channel* ?*section*?
This command is as per __::jpeg::getExif__ except that it uses a previously
opened channel. *channel* should be a seekable channel and *section* is as
described in the documentation of __::jpeg::getExif__.
*Note*: The jpeg parser expects that the start of the channel is the start
of the image data. If working with an image embedded in a container file
format it may be necessary to read the jpeg data into a temporary container:
either a temporary file or a memory channel.
*Attention*: It is the resonsibility of the caller to close the channel
after its use.
- <a name='7'></a>__::jpeg::formatExif__ *keys*
Takes a list of key-value pairs as returned by __getExif__ and formats many
of the values into a more human readable form. As few as one key-value may
be passed in, the entire exif is not required.
foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] {
puts "$key: $val"
}
array set exif [::jpeg::getExif photo.jpg]
puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]]
- <a name='8'></a>__::jpeg::exifKeys__
Returns a list of the EXIF keys which are currently understood. There may be
keys present in __getExif__ data that are not understood. Those keys will
appear in a 4 digit hexadecimal format.
- <a name='9'></a>__::jpeg::removeExif__ *file*
Removes the Exif data segment from the specified file and replaces it with a
standard JFIF segment. Throws an error if *file* is not a JPEG image.
- <a name='10'></a>__::jpeg::stripJPEG__ *file*
Removes all metadata from the JPEG file leaving only the image. This
includes comments, EXIF segments, JFXX segments, and application specific
segments. Throws an error if *file* is not a JPEG image.
- <a name='11'></a>__::jpeg::getComments__ *file*
Returns a list containing all the JPEG comments found in the *file*. Throws
an error if *file* is not a valid JPEG image.
- <a name='12'></a>__::jpeg::addComment__ *file* *text*...
Adds one or more plain *text* comments to the JPEG image in *file*. Throws
an error if *file* is not a valid JPEG image.
- <a name='13'></a>__::jpeg::removeComments__ *file*
Removes all comments from the file specified. Throws an error if *file* is
not a valid JPEG image.
- <a name='14'></a>__::jpeg::replaceComment__ *file* *text*
Replaces the first comment in the file with the new *text*. This is merely a
shortcut for __::jpeg::removeComments__ and __::jpeg::addComment__ Throws an
error if *file* is not a valid JPEG image.
- <a name='15'></a>__::jpeg::debug__ *file*
Prints everything we know about the given file in a nice format.
- <a name='16'></a>__::jpeg::markers__ *channel*
This is an internal helper command, we document it for use by advanced users
of the package. The argument *channel* is an open file handle positioned at
the start of the first marker (usually 2 bytes). The command returns a list
with one element for each JFIF marker found in the file. Each element
consists of a list of the marker name, its offset in the file, and its
length. The offset points to the beginning of the sections data, not the
marker itself. The length is the length of the data from the offset listed
to the start of the next marker.
# <a name='section3'></a>LIMITATIONS
can only work with files cant write exif data gps exif data not parsed makernote
data not yet implemented
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *jpeg* 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.
# <a name='keywords'></a>KEYWORDS
[comment](../../../../index.md#comment), [exif](../../../../index.md#exif),
[image](../../../../index.md#image), [jfif](../../../../index.md#jfif),
[jpeg](../../../../index.md#jpeg), [thumbnail](../../../../index.md#thumbnail)
# <a name='category'></a>CATEGORY
File formats
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2005, Code: Aaron Faupell <[email protected]>
Copyright © 2007, Code: Andreas Kupries <[email protected]>
Copyright © 2004-2009, Doc: Andreas Kupries <[email protected]>
Copyright © 2011, Code: Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/json/json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
[//000000001]: # (json - JSON)
[//000000002]: # (Generated from file 'json.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (json(n) 1.3.4 tcllib "JSON")
# NAME
json - JSON parser
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [RELATED](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require json ?1.3.4?
[__::json::json2dict__ *txt*](#1)
[__::json::many-json2dict__ *txt* ?*max*?](#2)
# <a name='description'></a>DESCRIPTION
The __json__ package provides a simple Tcl-only library for parsing the JSON
[http://www.json.org/](http://www.json.org/) data exchange format as specified
in RFC 4627
[http://www.ietf.org/rfc/rfc4627.txt](http://www.ietf.org/rfc/rfc4627.txt).
There is some ambiguity in parsing JSON because JSON has type information that
is not maintained by the Tcl conversion. The __json__ package returns data as a
Tcl __[dict](../../../../index.md#dict)__. Either the
__[dict](../../../../index.md#dict)__ package or Tcl 8.5 is required for use.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::json::json2dict__ *txt*
Parse JSON formatted text *txt* into a Tcl dict and return the value.
If *txt* contains more than one JSON entity only the first one is returned.
- <a name='2'></a>__::json::many-json2dict__ *txt* ?*max*?
Parse JSON formatted text *txt* containing multiple JSON entities into a
list of dictionaries and return that list.
If *max* is specified exactly that many entities are extracted from *txt*.
By default the command will attempt to extract all, without limits. A value
of "*max* == 0" does not make sense and will cause the command to throw an
error.
# <a name='section3'></a>EXAMPLES
An example of a JSON array converted to Tcl. A JSON array is returned as a
single item with multiple elements.
[
{
"precision": "zip",
"Latitude": 37.7668,
"Longitude": -122.3959,
"Address": "",
"City": "SAN FRANCISCO",
"State": "CA",
"Zip": "94107",
"Country": "US"
},
{
"precision": "zip",
"Latitude": 37.371991,
"Longitude": -122.026020,
"Address": "",
"City": "SUNNYVALE",
"State": "CA",
"Zip": "94085",
"Country": "US"
}
]
=>
{Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020}
An example of a JSON object converted to Tcl. A JSON object is returned as a
multi-element list (a dict).
{
"Image": {
"Width": 800,
"Height": 600,
"Title": "View from 15th Floor",
"Thumbnail": {
"Url": "http://www.example.com/image/481989943",
"Height": 125,
"Width": "100"
},
"IDs": [116, 943, 234, 38793]
}
}
=>
Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}}
# <a name='section4'></a>RELATED
To write json, instead of parsing it, see package
__[json::write](json_write.md)__.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *json* 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.
# <a name='keywords'></a>KEYWORDS
[data exchange](../../../../index.md#data_exchange), [exchange
format](../../../../index.md#exchange_format),
[javascript](../../../../index.md#javascript), [json](../../../../index.md#json)
# <a name='category'></a>CATEGORY
CGI programming
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 ActiveState Software Inc.
Copyright © 2009 Thomas Maeder, Glue Software Engineering AG
|
Added embedded/md/tcllib/files/modules/json/json_write.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
[//000000001]: # (json::write - JSON)
[//000000002]: # (Generated from file 'json_write.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (json::write(n) 1.0.3 tcllib "JSON")
# NAME
json::write - JSON generation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [RELATED](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require json::write ?1.0.3?
[__::json::write__ __indented__](#1)
[__::json::write__ __indented__ *flag*](#2)
[__::json::write__ __aligned__](#3)
[__::json::write__ __aligned__ *flag*](#4)
[__::json::write__ __string__ *s*](#5)
[__::json::write__ __array__ *arg*...](#6)
[__::json::write__ __object__ *key* *value*...](#7)
# <a name='description'></a>DESCRIPTION
The __json::write__ package provides a simple Tcl-only library for generation of
text in the JSON [http://www.json.org/](http://www.json.org/) data exchange
format as specified in RFC 4627
[http://www.ietf.org/rfc/rfc4627.txt](http://www.ietf.org/rfc/rfc4627.txt).
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::json::write__ __indented__
This method returns the current state of the indentation setting.
- <a name='2'></a>__::json::write__ __indented__ *flag*
This and the method __aligned__ configure the layout of the JSON generated
by the package.
If this *flag* is set (default) the package will break the generated JSON
code across lines and indent it according to its inner structure, with each
key of an object on a separate line.
If this flag is not set, the whole JSON object will be written on a single
line, with minimum spacing between all elements.
- <a name='3'></a>__::json::write__ __aligned__
This method returns the current state of the alignment setting.
- <a name='4'></a>__::json::write__ __aligned__ *flag*
This and the method __indented__ configure the layout of the JSON generated
by the package.
If this *flag* is set (default) the package ensures that the values for the
keys in an object are vertically aligned with each other, for a nice table
effect. To make this work this also implies that __indented__ is set as
well.
If this flag is not set, the output is formatted as per the value of
__indented__, without trying to align the values for object keys.
- <a name='5'></a>__::json::write__ __string__ *s*
This method takes the string *s* and returns it properly quoted for JSON as
its result.
- <a name='6'></a>__::json::write__ __array__ *arg*...
This method takes a series of JSON formatted arguments and returns them as a
properly formatted JSON array as its result.
- <a name='7'></a>__::json::write__ __object__ *key* *value*...
This method takes a series of key/value arguments, the values already
formatted for JSON, and returns them as a properly formatted JSON object as
its result, with the keys formatted as JSON strings.
# <a name='section3'></a>RELATED
To parse json, instead of writing it, see package __[json](json.md)__.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *json* 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.
# <a name='keywords'></a>KEYWORDS
[data exchange](../../../../index.md#data_exchange), [exchange
format](../../../../index.md#exchange_format),
[javascript](../../../../index.md#javascript), [json](../../../../index.md#json)
# <a name='category'></a>CATEGORY
CGI programming
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2013 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/lambda/lambda.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
[//000000001]: # (lambda - Utility commands for anonymous procedures)
[//000000002]: # (Generated from file 'lambda.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (lambda(n) 1 tcllib "Utility commands for anonymous procedures")
# NAME
lambda - Utility commands for anonymous procedures
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require lambda ?1?
[__::lambda__ *arguments* *body* ?*arg*...?](#1)
[__::lambda@__ *namespace* *arguments* *body* ?*arg*...?](#2)
# <a name='description'></a>DESCRIPTION
This package provides two convenience commands to make the writing of anonymous
procedures, i.e. lambdas more __[proc](../../../../index.md#proc)__-like.
Instead of, for example, to write
set f {::apply {{x} {
....
}}}
with its deep nesting of braces, or
set f [list ::apply {{x y} {
....
}} $value_for_x]
with a list command to insert some of the arguments of a partial application,
just write
set f [lambda {x} {
....
}]
and
set f [lambda {x y} {
....
} $value_for_x]
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::lambda__ *arguments* *body* ?*arg*...?
The command constructs an anonymous procedure from the list of arguments,
body script and (optional) predefined argument values and returns a command
prefix representing this anonymous procedure.
When invoked the *body* is run in a new procedure scope just underneath the
global scope, with the arguments set to the values supplied at both
construction and invokation time.
- <a name='2'></a>__::lambda@__ *namespace* *arguments* *body* ?*arg*...?
The command constructs an anonymous procedure from the namespace name, list
of arguments, body script and (optional) predefined argument values and
returns a command prefix representing this anonymous procedure.
When invoked the *body* is run in a new procedure scope in the *namespace*,
with the arguments set to the values supplied at both construction and
invokation time.
# <a name='section3'></a>AUTHORS
Andreas Kupries
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *lambda* 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.
# <a name='see-also'></a>SEE ALSO
apply(n), proc(n)
# <a name='keywords'></a>KEYWORDS
[anonymous procedure](../../../../index.md#anonymous_procedure),
[callback](../../../../index.md#callback), [command
prefix](../../../../index.md#command_prefix),
[currying](../../../../index.md#currying),
[lambda](../../../../index.md#lambda), [partial
application](../../../../index.md#partial_application),
[proc](../../../../index.md#proc)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries, BSD licensed
|
Added embedded/md/tcllib/files/modules/lazyset/lazyset.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
[//000000001]: # (lazyset - Lazy evaluation for variables and arrays)
[//000000002]: # (Generated from file 'lazyset.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (lazyset(n) 1 tcllib "Lazy evaluation for variables and arrays")
# NAME
lazyset - Lazy evaluation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [AUTHORS](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require lazyset ?1?
[__::lazyset::variable__ ?*-array boolean*? ?*-appendArgs boolean*? *variableName* *commandPrefix*](#1)
# <a name='description'></a>DESCRIPTION
The __lazyset__ package provides a mechanism for deferring execution of code
until a specific variable or any index of an array is referenced.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::lazyset::variable__ ?*-array boolean*? ?*-appendArgs boolean*? *variableName* *commandPrefix*
Arrange for the code specified as *commandPrefix* to be executed when the
variable whose name is specified by *variableName* is read for the first
time. If the optional argument *-array boolean* is specified as true, then
the variable specified as *variableName* is treated as an array and
attempting to read any index of the array causes that index to be set by the
*commandPrefix* as they are read. If the optional argument *-appendArgs
boolean* is specified as false, then the variable name and subnames are not
appended to the *commandPrefix* before it is evaluated. If the argument
*-appendArgs boolean* is not specified or is specified as true then 1 or 2
additional arguments are appended to the *commandPrefix*. If *-array
boolean* is specified as true, then 2 arguments are appended corresponding
to the name of the variable and the index, otherwise 1 argument is appended
containing the name of variable. The *commandPrefix* code is run in the same
scope as the variable is read.
# <a name='section3'></a>EXAMPLES
::lazyset::variable page {apply {{name} {
package require http
set token [http::geturl http://www.tcl.tk/]
set data [http::data $token]
return $data
}}}
puts $page
::lazyset::variable -array true page {apply {{name index} {
package require http
set token [http::geturl $index]
set data [http::data $token]
return $data
}}}
puts $page(http://www.tcl.tk/)
::lazyset::variable -appendArgs false simple {
return -level 0 42
}
puts $simple
# <a name='section4'></a>AUTHORS
Roy Keene
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *utility* 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.
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2018 Roy Keene
|
Added embedded/md/tcllib/files/modules/ldap/ldap.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
|
[//000000001]: # (ldap - LDAP client)
[//000000002]: # (Generated from file 'ldap.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ldap(n) 1.9.2 tcllib "LDAP client")
# NAME
ldap - LDAP client
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TLS Security Considerations](#section2)
- [COMMANDS](#section3)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require ldap ?1.9.2?
[__::ldap::connect__ *host* ?*port*?](#1)
[__::ldap::secure_connect__ *host* ?*port*? ?*verify_cert*? ?*sni_servername*?](#2)
[__::ldap::disconnect__ *handle*](#3)
[__::ldap::starttls__ *handle* ?*cafile*? ?*certfile*? ?*keyfile*? ?*verify_cert*? ?*sni_servername*?](#4)
[__::ldap::bind__ *handle* ?*name*? ?*password*?](#5)
[__::ldap::bindSASL__ *handle* ?*name*? ?*password*?](#6)
[__::ldap::unbind__ *handle*](#7)
[__::ldap::search__ *handle* *baseObject* *filterString* *attributes* *options*](#8)
[__::ldap::searchInit__ *handle* *baseObject* *filterString* *attributes* *options*](#9)
[__::ldap::searchNext__ *handle*](#10)
[__::ldap::searchEnd__ *handle*](#11)
[__::ldap::modify__ *handle* *dn* *attrValToReplace* ?*attrToDelete*? ?*attrValToAdd*?](#12)
[__::ldap::modifyMulti__ *handle* *dn* *attrValToReplace* ?*attrValToDelete*? ?*attrValToAdd*?](#13)
[__::ldap::add__ *handle* *dn* *attrValueTuples*](#14)
[__::ldap::addMulti__ *handle* *dn* *attrValueTuples*](#15)
[__::ldap::delete__ *handle* *dn*](#16)
[__::ldap::modifyDN__ *handle* *dn* *newrdn* ?*deleteOld*? ?*newSuperior*?](#17)
[__::ldap::info__ __[ip](../../../../index.md#ip)__ *handle*](#18)
[__::ldap::info__ __bound__ *handle*](#19)
[__::ldap::info__ __bounduser__ *handle*](#20)
[__::ldap::info__ __connections__](#21)
[__::ldap::info__ __[tls](../../../../index.md#tls)__ *handle*](#22)
[__::ldap::info__ __saslmechanisms__ *handle*](#23)
[__::ldap::info__ __[control](../control/control.md)__ *handle*](#24)
[__::ldap::info__ __extensions__ *extensions*](#25)
[__::ldap::info__ __whoami__ *handle*](#26)
# <a name='description'></a>DESCRIPTION
The __ldap__ package provides a Tcl-only client library for the LDAPv3 protocol
as specified in RFC 4511
([http://www.rfc-editor.org/rfc/rfc4511.txt](http://www.rfc-editor.org/rfc/rfc4511.txt)).
It works by opening the standard (or secure) LDAP socket on the server, and then
providing a Tcl API to access the LDAP protocol commands. All server errors are
returned as Tcl errors (thrown) which must be caught with the Tcl __catch__
command.
# <a name='section2'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section3'></a>COMMANDS
- <a name='1'></a>__::ldap::connect__ *host* ?*port*?
Opens a LDAPv3 connection to the specified *host*, at the given *port*, and
returns a token for the connection. This token is the *handle* argument for
all other commands. If no *port* is specified it will default to __389__.
The command blocks until the connection has been established, or
establishment definitely failed.
- <a name='2'></a>__::ldap::secure_connect__ *host* ?*port*? ?*verify_cert*? ?*sni_servername*?
Like __::ldap::connect__, except that the created connection is secured by
SSL. The port defaults to __636__. This command depends on the availability
of the package __[TLS](../../../../index.md#tls)__, which is a SSL binding
for Tcl. If __[TLS](../../../../index.md#tls)__ is not available, then this
command will fail.
The command blocks until the connection has been established, or
establishment definitely failed.
If *verify_cert* is set to 1, the default, this checks the server
certificate against the known hosts. If *sni_servername* is set, the given
hostname is used as the hostname for Server Name Indication in the TLS
handshake.
Use __::tls::init__ to setup defaults for trusted certificates.
tls::init -cadir /etc/ssl/certs/ca-certificates.crt
TLS supports different protocol levels. In common use are the versions 1.0,
1.1 and 1.2. By default all those versions are offered. If you need to
modify the acceptable protocols, you can change the ::ldap::tlsProtocols
list.
- <a name='3'></a>__::ldap::disconnect__ *handle*
Closes the ldap connection refered to by the token *handle*. Returns the
empty string as its result.
- <a name='4'></a>__::ldap::starttls__ *handle* ?*cafile*? ?*certfile*? ?*keyfile*? ?*verify_cert*? ?*sni_servername*?
Start TLS negotiation on the connection denoted by *handle*. You need to set
at least the *cafile* argument to a file with trusted certificates, if
*verify_cert* is 1, which is the default. The *sni_servername* can be used
to signal a different hostname during the TLS handshake. The announced
protocols are determined in the same way as __::ldap::secure_connect__. You
can specify a TLS client certificate with the *certfile* and *keyfile*
options.
- <a name='5'></a>__::ldap::bind__ *handle* ?*name*? ?*password*?
This command authenticates the ldap connection refered to by the token in
*handle*, with a user name and associated password. It blocks until a
response from the ldap server arrives. Its result is the empty string. Both
*name* and *passwd* default to the empty string if they are not specified.
By leaving out *name* and *passwd* you can make an anonymous bind to the
ldap server. You can issue __::ldap::bind__ again to bind with different
credentials.
- <a name='6'></a>__::ldap::bindSASL__ *handle* ?*name*? ?*password*?
This command uses SASL authentication mechanisms to do a multistage bind.
Its otherwise identical to the standard __::ldap::bind__. This feature is
currently experimental and subject to change. See the documentation for the
__[SASL](../sasl/sasl.md)__ and the "SASL.txt" in the tcllib CVS repository
for details how to setup and use SASL with openldap.
- <a name='7'></a>__::ldap::unbind__ *handle*
This command asks the ldap server to release the last bind done for the
connection refered to by the token in *handle*. The *handle* is invalid
after the unbind, as the server closes the connection. So this is effectivly
just a more polite disconnect operation.
- <a name='8'></a>__::ldap::search__ *handle* *baseObject* *filterString* *attributes* *options*
This command performs a LDAP search below the *baseObject* tree using a
complex LDAP search expression *filterString* and returns the specified
*attributes* of all matching objects (DNs). If the list of *attributes* was
empty all attributes are returned. The command blocks until it has received
all results. The valid *options* are identical to the options listed for
__::ldap::searchInit__.
An example of a search expression is
set filterString "|(cn=Linus*)(sn=Torvalds*)"
The return value of the command is a list of nested dictionaries. The first
level keys are object identifiers (DNs), second levels keys are attribute
names. In other words, it is in the form
{dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
- <a name='9'></a>__::ldap::searchInit__ *handle* *baseObject* *filterString* *attributes* *options*
This command initiates a LDAP search below the *baseObject* tree using a
complex LDAP search expression *filterString*. The search gets the specified
*attributes* of all matching objects (DNs). The command itself just starts
the search, to retrieve the actual results, use __::ldap::searchNext__. A
search can be terminated at any time by __::ldap::searchEnd__. This informs
the server that no further results should be sent by sending and ABANDON
message and cleans up the internal state of the search. Only one
__::ldap::search__ can be active at a given time, this includes the
introspection commands __::ldap::info saslmechanisms__, __ldap::info
control__ and __ldap::info extensions__, which invoke a search internally.
Error responses from the server due to wrong arguments or similar things are
returned with the first __::ldap::searchNext__ call and should be checked
and dealed with there. If the list of requested *attributes* is empty all
attributes will be returned. The parameter *options* specifies the options
to be used in the search, and has the following format:
{-option1 value1 -option2 value2 ... }
Following options are available:
* __-scope__ base one sub
Control the scope of the search to be one of __base__, __one__, or
__sub__, to specify a base object, one-level or subtree search. The
default is __sub__.
* __-derefaliases__ never search find always
Control how aliases dereferencing is done. Should be one of __never__,
__always__, __search__, or __find__ to specify that aliases are never
dereferenced, always dereferenced, dereferenced when searching, or
dereferenced only when locating the base object for the search. The
default is to never dereference aliases.
* __-sizelimit__ num
Determines the maximum number of entries to return in a search. If
specified as 0 no limit is enforced. The server may enforce a
configuration dependent sizelimit, which may be lower than the one given
by this option. The default is 0, no limit.
* __-timelimit__ seconds
Asks the server to use a timelimit of *seconds* for the search. Zero
means no limit. The default is 0, no limit.
* __-attrsonly__ boolean
If set to 1 only the attribute names but not the values will be present
in the search result. The default is to retrieve attribute names and
values.
* __-referencevar__ varname
If set the search result reference LDAPURIs, if any, are returned in the
given variable. The caller can than decide to follow those references
and query other LDAP servers for further results.
- <a name='10'></a>__::ldap::searchNext__ *handle*
This command returns the next entry from a LDAP search initiated by
__::ldap::searchInit__. It returns only after a new result is received or
when no further results are available, but takes care to keep the event loop
alive. The returned entry is a list with two elements: the first is the DN
of the entry, the second is the list of attributes and values, under the
format:
dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
The __::ldap::searchNext__ command returns an empty list at the end of the
search.
- <a name='11'></a>__::ldap::searchEnd__ *handle*
This command terminates a LDAP search initiated by __::ldap::searchInit__.
It also cleans up the internal state so a new search can be initiated. If
the client has not yet received all results, the client sends an ABANDON
message to inform the server that no further results for the previous search
should to be sent.
- <a name='12'></a>__::ldap::modify__ *handle* *dn* *attrValToReplace* ?*attrToDelete*? ?*attrValToAdd*?
This command modifies the object *dn* on the ldap server we are connected to
via *handle*. It replaces attributes with new values, deletes attributes,
and adds new attributes with new values. All arguments are dictionaries
mapping attribute names to values. The optional arguments default to the
empty dictionary, which means that no attributes will be deleted nor added.
* dictionary *attrValToReplace* (in)
No attributes will be changed if this argument is empty. The dictionary
contains the new attributes and their values. They *replace all*
attributes known to the object.
* dictionary *attrToDelete* (in)
No attributes will be deleted if this argument is empty. The dictionary
values are restrictions on the deletion. An attribute listed here will
be deleted if and only if its current value at the server matches the
value specified in the dictionary, or if the value in the dictionary is
the empty string.
* dictionary *attrValToAdd* (in)
No attributes will be added if this argument is empty. The dictionary
values are the values for the new attributes.
The command blocks until all modifications have completed. Its result is the
empty string.
- <a name='13'></a>__::ldap::modifyMulti__ *handle* *dn* *attrValToReplace* ?*attrValToDelete*? ?*attrValToAdd*?
This command modifies the object *dn* on the ldap server we are connected to
via *handle*. It replaces attributes with new values, deletes attributes,
and adds new attributes with new values. All arguments are lists with the
format:
attr1 {val11 val12 ...} attr2 {val21...} ...
where each value list may be empty for deleting all attributes. The optional
arguments default to empty lists of attributes to delete and to add.
* list *attrValToReplace* (in)
No attributes will be changed if this argument is empty. The dictionary
contains the new attributes and their values. They *replace all*
attributes known to the object.
* list *attrValToDelete* (in)
No attributes will be deleted if this argument is empty. If no value is
specified, the whole set of values for an attribute will be deleted.
* list *attrValToAdd* (in)
No attributes will be added if this argument is empty.
The command blocks until all modifications have completed. Its result is the
empty string.
- <a name='14'></a>__::ldap::add__ *handle* *dn* *attrValueTuples*
This command creates a new object using the specified *dn*. The attributes
of the new object are set to the values in the list *attrValueTuples*.
Multiple valuated attributes may be specified using multiple tuples. The
command blocks until the operation has completed. Its result is the empty
string.
- <a name='15'></a>__::ldap::addMulti__ *handle* *dn* *attrValueTuples*
This command is the preferred one to create a new object using the specified
*dn*. The attributes of the new object are set to the values in the
dictionary *attrValueTuples* (which is keyed by the attribute names). Each
tuple is a list containing multiple values. The command blocks until the
operation has completed. Its result is the empty string.
- <a name='16'></a>__::ldap::delete__ *handle* *dn*
This command removes the object specified by *dn*, and all its attributes
from the server. The command blocks until the operation has completed. Its
result is the empty string.
- <a name='17'></a>__::ldap::modifyDN__ *handle* *dn* *newrdn* ?*deleteOld*? ?*newSuperior*?
This command moves or copies the object specified by *dn* to a new location
in the tree of object. This location is specified by *newrdn*, a *relative*
designation, or by *newrdn* and *newSuperior*, a *absolute* designation. The
optional argument *deleteOld* defaults to __true__, i.e. a move operation.
If *deleteOld* is not set, then the operation will create a copy of *dn* in
the new location. The optional argument *newSuperior* defaults an empty
string, meaning that the object must not be relocated in another branch of
the tree. If this argument is given, the argument *deleteOld* must be
specified also. The command blocks until the operation has completed. Its
result is the empty string.
- <a name='18'></a>__::ldap::info__ __[ip](../../../../index.md#ip)__ *handle*
This command returns the IP address of the remote LDAP server the handle is
connected to.
- <a name='19'></a>__::ldap::info__ __bound__ *handle*
This command returns 1 if a handle has successfully completed a
__::ldap::bind__. If no bind was done or it failed, a 0 is returned.
- <a name='20'></a>__::ldap::info__ __bounduser__ *handle*
This command returns the username used in the bind operation if a handle has
successfully completed a __::ldap::bind__. If no bound was done or it
failed, an empty string is returned.
- <a name='21'></a>__::ldap::info__ __connections__
This command returns all currently existing ldap connection handles.
- <a name='22'></a>__::ldap::info__ __[tls](../../../../index.md#tls)__ *handle*
This command returns 1 if the ldap connection *handle* used TLS/SSL for
connection via __ldap::secure_connect__ or completed __ldap::starttls__, 0
otherwise.
- <a name='23'></a>__::ldap::info__ __saslmechanisms__ *handle*
Return the supported SASL mechanisms advertised by the server. Only valid in
a bound state (anonymous or other).
- <a name='24'></a>__::ldap::info__ __[control](../control/control.md)__ *handle*
Return the supported controls advertised by the server as a list of OIDs.
Only valid in a bound state. This is currently experimental and subject to
change.
- <a name='25'></a>__::ldap::info__ __extensions__ *extensions*
Returns the supported LDAP extensions as list of OIDs. Only valid in a bound
state. This is currently experimental and subject to change.
- <a name='26'></a>__::ldap::info__ __whoami__ *handle*
Returns authzId for the current connection. This implements the RFC 4532
protocol extension.
# <a name='section4'></a>EXAMPLES
A small example, extracted from the test application coming with this code.
package require ldap
# Connect, bind, add a new object, modify it in various ways
set handle [ldap::connect localhost 9009]
set dn "cn=Manager, o=University of Michigan, c=US"
set pw secret
ldap::bind $handle $dn $pw
set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
ldap::add $handle $dn {
objectClass OpenLDAPperson
cn {Test User}
mail [email protected]
uid testuid
sn User
telephoneNumber +31415926535
telephoneNumber +27182818285
}
set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
ldap::addMulti $handle $dn {
objectClass {OpenLDAPperson}
cn {{Anotther User}}
mail {[email protected]}
uid {testuid}
sn {User}
telephoneNumber {+31415926535 +27182818285}
}
# Replace all attributes
ldap::modify $handle $dn [list drink icetea uid JOLO]
# Add some more
ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]
# Delete
ldap::modify $handle $dn {} [list drink water pager ""]
# Move
ldap::modifyDN $handle $dn "cn=Tester"
# Kill the test object, and shut the connection down.
set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
ldap::delete $handle $dn
ldap::unbind $handle
ldap::disconnect $handle
And a another example, a simple query, and processing the results.
package require ldap
set handle [ldap::connect ldap.acme.com 389]
ldap::bind $handle
set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
foreach result $results {
foreach {object attributes} $result break
# The processing here is similar to what 'parray' does.
# I.e. finding the longest attribute name and then
# generating properly aligned output listing all attributes
# and their values.
set width 0
set sortedAttribs {}
foreach {type values} $attributes {
if {[string length $type] > $width} {
set width [string length $type]
}
lappend sortedAttribs [list $type $values]
}
puts "object='$object'"
foreach sortedAttrib $sortedAttribs {
foreach {type values} $sortedAttrib break
foreach value $values {
regsub -all "\[\x01-\x1f\]" $value ? value
puts [format " %-${width}s %s" $type $value]
}
}
puts ""
}
ldap::unbind $handle
ldap::disconnect $handle
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ldap* 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.
# <a name='keywords'></a>KEYWORDS
[directory access](../../../../index.md#directory_access),
[internet](../../../../index.md#internet), [ldap](../../../../index.md#ldap),
[ldap client](../../../../index.md#ldap_client),
[protocol](../../../../index.md#protocol), [rfc
2251](../../../../index.md#rfc_2251), [rfc 4511](../../../../index.md#rfc_4511),
[x.500](../../../../index.md#x_500)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Andreas Kupries <[email protected]>
Copyright © 2004 Jochen Loewer <[email protected]>
Copyright © 2006 Michael Schlenker <[email protected]>
|
Added embedded/md/tcllib/files/modules/ldap/ldapx.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
|
[//000000001]: # (ldapx - LDAP extended object interface)
[//000000002]: # (Generated from file 'ldapx.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ldapx(n) 1.1 tcllib "LDAP extended object interface")
# NAME
ldapx - LDAP extended object interface
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OVERVIEW](#section2)
- [ENTRY CLASS](#section3)
- [Entry Instance Data](#subsection1)
- [Entry Options](#subsection2)
- [Methods for all kinds of entries](#subsection3)
- [Methods for standard entries only](#subsection4)
- [Methods for change entries only](#subsection5)
- [Entry Example](#subsection6)
- [LDAP CLASS](#section4)
- [Ldap Instance Data](#subsection7)
- [Ldap Options](#subsection8)
- [Ldap Methods](#subsection9)
- [Ldap Example](#subsection10)
- [LDIF CLASS](#section5)
- [Ldif Instance Data](#subsection11)
- [Ldif Options](#subsection12)
- [Ldif Methods](#subsection13)
- [Ldif Example](#subsection14)
- [References](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require ldapx ?1.1?
[*e* __reset__](#1)
[*e* __dn__ ?*newdn*?](#2)
[*e* __rdn__](#3)
[*e* __superior__](#4)
[*e* __print__](#5)
[*se* __isempty__](#6)
[*se* __get__ *attr*](#7)
[*se* __get1__ *attr*](#8)
[*se* __set__ *attr* *values*](#9)
[*se* __set1__ *attr* *value*](#10)
[*se* __add__ *attr* *values*](#11)
[*se* __add1__ *attr* *value*](#12)
[*se* __del__ *attr* ?*values*?](#13)
[*se* __del1__ *attr* *value*](#14)
[*se* __getattr__](#15)
[*se* __getall__](#16)
[*se* __setall__ *avpairs*](#17)
[*se* __backup__ ?*other*?](#18)
[*se* __swap__](#19)
[*se* __restore__ ?*other*?](#20)
[*se* __apply__ *centry*](#21)
[*ce* __change__ ?*new*?](#22)
[*ce* __diff__ *new* ?*old*?](#23)
[*la* __error__ ?*newmsg*?](#24)
[*la* __connect__ *url* ?*binddn*? ?*bindpw*?](#25)
[*la* __disconnect__](#26)
[*la* __traverse__ *base* *filter* *attrs* *entry* *body*](#27)
[*la* __search__ *base* *filter* *attrs*](#28)
[*la* __read__ *base* *filter* *entry* ... *entry*](#29)
[*la* __commit__ *entry* ... *entry*](#30)
[*li* __channel__ *chan*](#31)
[*li* __error__ ?*newmsg*?](#32)
[*li* __read__ *entry*](#33)
[*li* __write__ *entry*](#34)
# <a name='description'></a>DESCRIPTION
The __ldapx__ package provides an extended Tcl interface to LDAP directores and
LDIF files. The __ldapx__ package is built upon the __[ldap](ldap.md)__ package
in order to get low level LDAP access.
LDAP access is compatible with RFC 2251
([http://www.rfc-editor.org/rfc/rfc2251.txt](http://www.rfc-editor.org/rfc/rfc2251.txt)).
LDIF access is compatible with RFC 2849
([http://www.rfc-editor.org/rfc/rfc2849.txt](http://www.rfc-editor.org/rfc/rfc2849.txt)).
# <a name='section2'></a>OVERVIEW
The __ldapx__ package provides objects to interact with LDAP directories and
LDIF files with an easy to use programming interface. It implements three
__[snit](../snit/snit.md)__::type classes.
The first class, __entry__, is used to store individual entries. Two different
formats are available: the first one is the *standard* format, which represents
an entry as read from the directory. The second format is the *change* format,
which stores differences between two standard entries.
With these entries, an application which wants to modify an entry in a directory
needs to read a (standard) entry from the directory, create a fresh copy into a
new (standard) entry, modify the new copy, and then compute the differences
between the two entries into a new (change) entry, which may be commited to the
directory.
Such kinds of modifications are so heavily used that standard entries may
contain their own copy of the original data. With such a copy, the application
described above reads a (standard) entry from the directory, backs-up the
original data, modifies the entry, and computes the differences between the
entry and its backup. These differences are then commited to the directory.
Methods are provided to compute differences between two entries, to apply
differences to an entry in order to get a new entry, and to get or set
attributes in standard entries.
The second class is the __ldap__ class. It provides a method to __connect__ and
bind to the directory with a uniform access to LDAP and LDAPS through an URL
(ldap:// or ldaps://). The __traverse__ control structure executes a body for
each entry found in the directory. The __commit__ method applies some changes
(represented as __entry__ objects) to the directory. Since some attributes are
represented as UTF-8 strings, the option __-utf8__ controls which attributes
must be converted and which attributes must not be converted.
The last class is the __ldif__ class. It provides a method to associate a
standard Tcl *channel* to an LDIF object. Then, methods __read__ and __write__
read or write entries from or to this channel. This class can make use of
standard or change entries, according to the type of the LDIF file which may
contain either standard entries or change entries (but not both at the same
time). The option __-utf8__ works exactly as with the __ldap__ class.
# <a name='section3'></a>ENTRY CLASS
## <a name='subsection1'></a>Entry Instance Data
An instance of the __entry__ class keeps the following data:
- dn
This is the DN of the entry, which includes (in LDAP terminology) the RDN
(relative DN) and the Superior parts.
- format
The format may be *uninitialized* (entry not yet used), *standard* or
*change*. Most methods check the format of the entry, which can be reset
with the __reset__ method.
- attrvals
In a *standard* entry, this is where the attributes and associated values
are stored. Many methods provide access to these informations. Attribute
names are always converted into lower case.
- backup
In a *standard* entry, the backup may contain a copy of the dn and all
attributes and values. Methods __backup__ and __restore__ manipulate these
data, and method __diff__ may use this backup.
- change
In a *change* entry, these data represent the modifications. Such
modifications are handled by specialized methods such as __apply__ or
__commit__. Detailed format should not be used directly by programs.
Internally, modifications are represented as a list of elements, each
element has one of the following formats (which match the corresponding LDAP
operations):
{__add__ {attr1 {val1...valn} attr2 {...} ...}}
Addition of a new entry.
{__mod__ {modop {attr1 ?val1...valn?} attr2 ...} {modop ...} ...}
Modification of one or more attributes and/or values, where <modop> can be
__modadd__, __moddel__ or __modrepl__ (see the LDAP modify operation).
{__del__}
Deletion of an old entry.
{__modrdn__ newrdn deleteoldrdn ?newsuperior?}
Renaming of an entry.
## <a name='subsection2'></a>Entry Options
No option is defined by this class.
## <a name='subsection3'></a>Methods for all kinds of entries
- <a name='1'></a>*e* __reset__
This method resets the entry to an uninitialized state.
- <a name='2'></a>*e* __dn__ ?*newdn*?
This method returns the current DN of the entry. If the optional *newdn* is
specified, it replaces the current DN of the entry.
- <a name='3'></a>*e* __rdn__
This method returns the RDN part of the DN of the entry.
- <a name='4'></a>*e* __superior__
This method returns the superior part of the DN of the entry.
- <a name='5'></a>*e* __print__
This method returns the entry as a string ready to be printed.
## <a name='subsection4'></a>Methods for standard entries only
In all methods, attribute names are converted in lower case.
- <a name='6'></a>*se* __isempty__
This method returns 1 if the entry is empty (i.e. without any attribute).
- <a name='7'></a>*se* __get__ *attr*
This method returns all values of the attribute *attr*, or the empty list if
the attribute is not fond.
- <a name='8'></a>*se* __get1__ *attr*
This method returns the first value of the attribute.
- <a name='9'></a>*se* __set__ *attr* *values*
This method sets the values (list *values*) of the attribute *attr*. If the
list is empty, this method deletes all
- <a name='10'></a>*se* __set1__ *attr* *value*
This method sets the values of the attribute *attr* to be an unique value
*value*. Previous values, if any, are replaced by the new value.
- <a name='11'></a>*se* __add__ *attr* *values*
This method adds all elements the list *values* to the values of the
attribute *attr*.
- <a name='12'></a>*se* __add1__ *attr* *value*
This method adds a single value given by the parameter *value* to the
attribute *attr*.
- <a name='13'></a>*se* __del__ *attr* ?*values*?
If the optional list *values* is specified, this method deletes all
specified values from the attribute *attr*. If the argument *values* is not
specified, this method deletes all values.
- <a name='14'></a>*se* __del1__ *attr* *value*
This method deletes a unique *value* from the attribute *attr*.
- <a name='15'></a>*se* __getattr__
This method returns all attributes names.
- <a name='16'></a>*se* __getall__
This method returns all attributes and values from the entry, packed in a
list of pairs <attribute, list of values>.
- <a name='17'></a>*se* __setall__ *avpairs*
This method sets at once all attributes and values. The format of the
*avpairs* argument is the same as the one returned by method __getall__.
- <a name='18'></a>*se* __backup__ ?*other*?
This method stores in an *other* standard entry object a copy of the current
DN and attributes/values. If the optional *other* argument is not specified,
copy is done in the current entry (in a specific place, see section
[OVERVIEW](#section2)).
- <a name='19'></a>*se* __swap__
This method swaps the current and backup contexts of the entry.
- <a name='20'></a>*se* __restore__ ?*other*?
If the optional argument *other* is given, which must then be a *standard*
entry, this method restores the current entry into the *other* entry. If the
argument *other* argument is not specified, this methods restores the
current entry from its internal backup (see section [OVERVIEW](#section2)).
- <a name='21'></a>*se* __apply__ *centry*
This method applies changes defined in the *centry* argument, which must be
a *change* entry.
## <a name='subsection5'></a>Methods for change entries only
- <a name='22'></a>*ce* __change__ ?*new*?
If the optional argument *new* is specified, this method modifies the change
list (see subsection [Entry Instance Data](#subsection1) for the exact
format). In both cases, current change list is returned. Warning: values
returned by this method should only be used by specialized methods such as
__apply__ or __commit__.
- <a name='23'></a>*ce* __diff__ *new* ?*old*?
This method computes the differences between the *new* and *old* entries
under the form of a change list, and stores this list into the current
*change* entry. If the optional argument *old* is not specified, difference
is computed from the entry and its internal backup (see section
[OVERVIEW](#section2)). Return value is the computed change list.
## <a name='subsection6'></a>Entry Example
package require ldapx
#
# Create an entry and fill it as a standard entry with
# attributes and values
#
::ldapx::entry create e
e dn "uid=joe,ou=people,o=mycomp"
e set1 "uid" "joe"
e set "objectClass" {person anotherObjectClass}
e set1 "givenName" "Joe"
e set1 "sn" "User"
e set "telephoneNumber" {+31415926535 +2182818}
e set1 "anotherAttr" "This is a beautiful day, isn't it?"
puts stdout "e\n[e print]"
#
# Create a second entry as a backup of the first, and
# make some changes on it.
# Entry is named automatically by snit.
#
set b [::ldapx::entry create %AUTO%]
e backup $b
puts stdout "$b\n[$b print]"
$b del "anotherAttr"
$b del1 "objectClass" "anotherObjectClass"
#
# Create a change entry, a compute differences between first
# and second entry.
#
::ldapx::entry create c
c diff e $b
puts stdout "$c\n[$c print]"
#
# Apply changes to first entry. It should be the same as the
# second entry, now.
#
e apply c
::ldapx::entry create nc
nc diff e $b
puts stdout "nc\n[nc print]"
#
# Clean-up
#
e destroy
$b destroy
c destroy
nc destroy
# <a name='section4'></a>LDAP CLASS
## <a name='subsection7'></a>Ldap Instance Data
An instance of the __ldap__ class keeps the following data:
- channel
This is the channel used by the __[ldap](ldap.md)__ package for
communication with the LDAP server.
- lastError
This variable contains the error message which appeared in the last method
of the __ldap__ class (this string is modified in nearly all methods). The
__error__ method may be used to fetch this message.
## <a name='subsection8'></a>Ldap Options
A first set of options of the __ldap__ class is used during search operations
(methods __traverse__, __search__ and __read__, see below).
- __-scope__ __base__|__one__|__sub__
Specify the scope of the LDAP search to be one of __base__, __one__ or
__sub__ to specify a base object, one-level or subtree search.
The default is __sub__.
- __-derefaliases__ __never__|__seach__|__find__|__always__
Specify how aliases dereferencing is handled: __never__ is used to specify
that aliases are never derefenced, __always__ that aliases are always
derefenced, __search__ that aliases are dereferenced when searching, or
__find__ that aliases are dereferenced only when locating the base object
for the search.
The default is __never__.
- __-sizelimit__ integer
Specify the maximum number of entries to be retreived during a search. A
value of __0__ means no limit.
Default is __0__.
- __-timelimit__ integer
Specify the time limit for a search to complete. A value of __0__ means no
limit.
Default is __0__.
- __-attrsonly__ __0__|__1__
Specify if only attribute names are to be retrieved (value __1__). Normally
(value __0__), attribute values are also retrieved.
Default is __0__.
The last option is used when getting entries or committing changes in the
directory:
- __-utf8__ pattern-yes pattern-no
Specify which attribute values are encoded in UTF-8. This information is
specific to the LDAP schema in use by the application, since some attributes
such as jpegPhoto, for example, are not encoded in UTF-8. This option takes
the form of a list with two regular expressions suitable for the __regexp__
command (anchored by ^ and $). The first specifies which attribute names are
to be UTF-8 encoded, and the second selects, among those, the attribute
names which will not be UTF-8 encoded. It is thus possible to say: convert
all attributes, except jpegPhoto.
Default is {{.*} {}}, meaning: all attributes are converted, without
exception.
## <a name='subsection9'></a>Ldap Methods
- <a name='24'></a>*la* __error__ ?*newmsg*?
This method returns the error message that occurred in the last call to a
__ldap__ class method. If the optional argument *newmsg* is supplied, it
becomes the last error message.
- <a name='25'></a>*la* __connect__ *url* ?*binddn*? ?*bindpw*?
This method connects to the LDAP server using given URL (which can be of the
form [ldap://host:port](ldap://host:port) or
[ldaps://host:port](ldaps://host:port)). If an optional *binddn* argument is
given together with the *bindpw* argument, the __connect__ binds to the LDAP
server using the specified DN and password.
- <a name='26'></a>*la* __disconnect__
This method disconnects (and unbinds, if necessary) from the LDAP server.
- <a name='27'></a>*la* __traverse__ *base* *filter* *attrs* *entry* *body*
This method is a new control structure. It searches the LDAP directory from
the specified base DN (given by the *base* argument) and selects entries
based on the argument *filter*. For each entry found, this method fetches
attributes specified by the *attrs* argument (or all attributes if it is an
empty list), stores them in the *entry* instance of class __entry__ and
executes the script defined by the argument *body*. Options are used to
refine the search.
Caution: when this method is used, the script *body* cannot perform another
LDAP search (methods __traverse__, __search__ or __read__).
- <a name='28'></a>*la* __search__ *base* *filter* *attrs*
This method searches the directory using the same way as method
__traverse__. All found entries are stored in newly created instances of
class __entry__, which are returned in a list. The newly created instances
should be destroyed when they are no longer used.
- <a name='29'></a>*la* __read__ *base* *filter* *entry* ... *entry*
This method reads one or more entries, using the same search criteria as
methods __traverse__ and __search__. All attributes are stored in the
entries. This method provides a quick way to read some entries. It returns
the number of entries found in the directory (which may be more than the
number of read entries). If called without any *entry* argument, this method
just returns the number of entries found, without returning any data.
- <a name='30'></a>*la* __commit__ *entry* ... *entry*
This method commits the changes stored in the *entry* arguments. Each
*entry* may be either a *change* entry, or a *standard* entry with a backup.
Note: in the future, this method should use the LDAP transaction extension
provided by OpenLDAP 2.3 and later.
## <a name='subsection10'></a>Ldap Example
package require ldapx
#
# Connects to the LDAP directory
#
::ldapx::ldap create l
set url "ldap://server.mycomp.com"
if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then {
puts stderr "error: [l error]"
exit 1
}
#
# Search all entries matching some criterion
#
l configure -scope one
::ldapx::entry create e
set n 0
l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
puts "dn: [e dn]"
puts " sn: [e get1 sn]"
puts " givenName: [e get1 givenName]"
incr n
}
puts "$n entries found"
e destroy
#
# Add a telephone number to some entries
# Note this modification cannot be done in the "traverse" operation.
#
set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
::ldapx::entry create c
foreach e $lent {
$e backup
$e add1 "telephoneNumber" "+31415926535"
c diff $e
if {! [l commit c]} then {
puts stderr "error: [l error]"
exit 1
}
$e destroy
}
c destroy
l disconnect
l destroy
# <a name='section5'></a>LDIF CLASS
## <a name='subsection11'></a>Ldif Instance Data
An instance of the __ldif__ class keeps the following data:
- channel
This is the Tcl channel used to retrieve or store LDIF file contents. The
association between an instance and a channel is made by the method
__channel__. There is no need to disrupt this association when the LDIF file
operation has ended.
- format
LDIF files may contain *standard* entries or *change* entries, but not both.
This variable contains the detected format of the file (when reading) or the
format of entries written to the file (when writing).
- lastError
This variable contains the error message which appeared in the last method
of the __ldif__ class (this string is modified in nearly all methods). The
__error__ method may be used to fetch this message.
- version
This is the version of the LDIF file. Only version 1 is supported: the
method __read__ can only read from version 1 files, and method __write__
only creates version 1 files.
## <a name='subsection12'></a>Ldif Options
This class defines two options:
- __-ignore__ list-of-attributes
This option is used to ignore certain attribute names on reading. For
example, to read OpenLDAP replica files (replog), one must ignore
__replica__ and __time__ attributes since they do not conform to the RFC
2849 standard for LDIF files.
Default is empty list: no attribute is ignored.
- __-utf8__ pattern-yes pattern-no
Specify which attribute values are encoded in UTF-8. This information is
specific to the LDAP schema in use by the application, since some attributes
such as jpegPhoto, for example, are not encoded in UTF-8. This option takes
the form of a list with two regular expressions suitable for the __regexp__
command (anchored by ^ and $). The first specifies which attribute names are
to be UTF-8 encoded, and the second selects, among those, the attribute
names which will not be UTF-8 encoded. It is thus possible to say: convert
all attributes, except jpegPhoto.
Default is {{.*} {}}, meaning: all attributes are converted, without
exception.
## <a name='subsection13'></a>Ldif Methods
- <a name='31'></a>*li* __channel__ *chan*
This method associates the Tcl channel named *chan* with the LDIF instance.
It resets the type of LDIF object to *uninitialized*.
- <a name='32'></a>*li* __error__ ?*newmsg*?
This method returns the error message that occurred in the last call to a
__ldif__ class method. If the optional argument *newmsg* is supplied, it
becomes the last error message.
- <a name='33'></a>*li* __read__ *entry*
This method reads the next entry from the LDIF file and stores it in the
*entry* object of class __entry__. The entry may be a *standard* or *change*
entry.
- <a name='34'></a>*li* __write__ *entry*
This method writes the entry given in the argument *entry* to the LDIF file.
## <a name='subsection14'></a>Ldif Example
package require ldapx
# This examples reads a LDIF file containing entries,
# compare them to a LDAP directory, and writes on standard
# output an LDIF file containing changes to apply to the
# LDAP directory to match exactly the LDIF file.
::ldapx::ldif create liin
liin channel stdin
::ldapx::ldif create liout
liout channel stdout
::ldapx::ldap create la
if {! [la connect "ldap://server.mycomp.com"]} then {
puts stderr "error: [la error]"
exit 1
}
la configure -scope one
# Reads LDIF file
::ldapx::entry create e1
::ldapx::entry create e2
::ldapx::entry create c
while {[liin read e1] != 0} {
set base [e1 superior]
set id [e1 rdn]
if {[la read $base "($id)" e2] == 0} then {
e2 reset
}
c diff e1 e2
if {[llength [c change]] != 0} then {
liout write c
}
}
la disconnect
la destroy
e1 destroy
e2 destroy
c destroy
liout destroy
liin destroy
# <a name='section6'></a>References
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ldap* 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.
# <a name='keywords'></a>KEYWORDS
[directory access](../../../../index.md#directory_access),
[internet](../../../../index.md#internet), [ldap](../../../../index.md#ldap),
[ldap client](../../../../index.md#ldap_client),
[ldif](../../../../index.md#ldif), [protocol](../../../../index.md#protocol),
[rfc 2251](../../../../index.md#rfc_2251), [rfc
2849](../../../../index.md#rfc_2849)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2018 Pierre David <[email protected]>
|
Added embedded/md/tcllib/files/modules/log/log.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
[//000000001]: # (log - Logging facility)
[//000000002]: # (Generated from file 'log.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (log(n) 1.4 tcllib "Logging facility")
# NAME
log - Procedures to log messages of libraries and applications.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [LEVELS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require log ?1.4?
[__::log::levels__](#1)
[__::log::lv2longform__ *level*](#2)
[__::log::lv2color__ *level*](#3)
[__::log::lv2priority__ *level*](#4)
[__::log::lv2cmd__ *level*](#5)
[__::log::lv2channel__ *level*](#6)
[__::log::lvCompare__ *level1* *level2*](#7)
[__::log::lvSuppress__ *level* {*suppress* 1}](#8)
[__::log::lvSuppressLE__ *level* {*suppress* 1}](#9)
[__::log::lvIsSuppressed__ *level*](#10)
[__::log::lvCmd__ *level* *cmd*](#11)
[__::log::lvCmdForall__ *cmd*](#12)
[__::log::lvChannel__ *level* *chan*](#13)
[__::log::lvChannelForall__ *chan*](#14)
[__::log::lvColor__ *level* *color*](#15)
[__::log::lvColorForall__ *color*](#16)
[__::log::log__ *level* *text*](#17)
[__::log::logarray__ *level* *arrayvar* ?*pattern*?](#18)
[__::log::loghex__ *level* *text* *data*](#19)
[__::log::logsubst__ *level* *msg*](#20)
[__::log::logMsg__ *text*](#21)
[__::log::logError__ *text*](#22)
[__::log::Puts__ *level* *text*](#23)
# <a name='description'></a>DESCRIPTION
The __log__ package provides commands that allow libraries and applications to
selectively log information about their internal operation and state.
To use the package just execute
package require log
log::log notice "Some message"
As can be seen above, each message given to the log facility is associated with
a *level* determining the importance of the message. The user can then select
which levels to log, what commands to use for the logging of each level and the
channel to write the message to. In the following example the logging of all
message with level __debug__ is deactivated.
package require log
log::lvSuppress debug
log::log debug "Unseen message" ; # No output
By default all messages associated with an error-level (__emergency__,
__alert__, __critical__, and __error__) are written to __stderr__. Messages with
any other level are written to __stdout__. In the following example the log
module is reconfigured to write __debug__ messages to __stderr__ too.
package require log
log::lvChannel debug stderr
log::log debug "Written to stderr"
Each message level is also associated with a command to use when logging a
message with that level. The behaviour above for example relies on the fact that
all message levels use by default the standard command __::log::Puts__ to log
any message. In the following example all messages of level __notice__ are given
to the non-standard command __toText__ for logging. This disables the channel
setting for such messages, assuming that __toText__ does not use it by itself.
package require log
log::lvCmd notice toText
log::log notice "Handled by \"toText\""
Another database maintained by this facility is a map from message levels to
colors. The information in this database has *no* influence on the behaviour of
the module. It is merely provided as a convenience and in anticipation of the
usage of this facility in __tk__-based application which may want to colorize
message logs.
# <a name='section2'></a>API
The following commands are available:
- <a name='1'></a>__::log::levels__
Returns the names of all known levels, in alphabetical order.
- <a name='2'></a>__::log::lv2longform__ *level*
Converts any unique abbreviation of a level name to the full level name.
- <a name='3'></a>__::log::lv2color__ *level*
Converts any level name including unique abbreviations to the corresponding
color.
- <a name='4'></a>__::log::lv2priority__ *level*
Converts any level name including unique abbreviations to the corresponding
priority.
- <a name='5'></a>__::log::lv2cmd__ *level*
Converts any level name including unique abbreviations to the command prefix
used to write messages with that level.
- <a name='6'></a>__::log::lv2channel__ *level*
Converts any level name including unique abbreviations to the channel used
by __::log::Puts__ to write messages with that level.
- <a name='7'></a>__::log::lvCompare__ *level1* *level2*
Compares two levels (including unique abbreviations) with respect to their
priority. This command can be used by the -command option of lsort. The
result is one of -1, 0 or 1 or an error. A result of -1 signals that level1
is of less priority than level2. 0 signals that both levels have the same
priority. 1 signals that level1 has higher priority than level2.
- <a name='8'></a>__::log::lvSuppress__ *level* {*suppress* 1}
(Un)suppresses the output of messages having the specified level. Unique
abbreviations for the level are allowed here too.
- <a name='9'></a>__::log::lvSuppressLE__ *level* {*suppress* 1}
(Un)suppresses the output of messages having the specified level or one of
lesser priority. Unique abbreviations for the level are allowed here too.
- <a name='10'></a>__::log::lvIsSuppressed__ *level*
Asks the package whether the specified level is currently suppressed. Unique
abbreviations of level names are allowed.
- <a name='11'></a>__::log::lvCmd__ *level* *cmd*
Defines for the specified level with which command to write the messages
having this level. Unique abbreviations of level names are allowed. The
command is actually a command prefix and this facility will append 2
arguments before calling it, the level of the message and the message
itself, in this order.
- <a name='12'></a>__::log::lvCmdForall__ *cmd*
Defines for all known levels with which command to write the messages having
this level. The command is actually a command prefix and this facility will
append 2 arguments before calling it, the level of the message and the
message itself, in this order.
- <a name='13'></a>__::log::lvChannel__ *level* *chan*
Defines for the specified level into which channel __::log::Puts__ (the
standard command) shall write the messages having this level. Unique
abbreviations of level names are allowed. The command is actually a command
prefix and this facility will append 2 arguments before calling it, the
level of the message and the message itself, in this order.
- <a name='14'></a>__::log::lvChannelForall__ *chan*
Defines for all known levels with which which channel __::log::Puts__ (the
standard command) shall write the messages having this level. The command is
actually a command prefix and this facility will append 2 arguments before
calling it, the level of the message and the message itself, in this order.
- <a name='15'></a>__::log::lvColor__ *level* *color*
Defines for the specified level the color to return for it in a call to
__::log::lv2color__. Unique abbreviations of level names are allowed.
- <a name='16'></a>__::log::lvColorForall__ *color*
Defines for all known levels the color to return for it in a call to
__::log::lv2color__. Unique abbreviations of level names are allowed.
- <a name='17'></a>__::log::log__ *level* *text*
Log a message according to the specifications for commands, channels and
suppression. In other words: The command will do nothing if the specified
level is suppressed. If it is not suppressed the actual logging is delegated
to the specified command. If there is no command specified for the level the
message won't be logged. The standard command __::log::Puts__ will write the
message to the channel specified for the given level. If no channel is
specified for the level the message won't be logged. Unique abbreviations of
level names are allowed. Errors in the actual logging command are *not*
caught, but propagated to the caller, as they may indicate misconfigurations
of the log facility or errors in the callers code itself.
- <a name='18'></a>__::log::logarray__ *level* *arrayvar* ?*pattern*?
Like __::log::log__, but logs the contents of the specified array variable
*arrayvar*, possibly restricted to entries matching the *pattern*. The
pattern defaults to __*__ (i.e. all entries) if none was specified.
- <a name='19'></a>__::log::loghex__ *level* *text* *data*
Like __::log::log__, but assumes that *data* contains binary data. It
converts this into a mixed hex/ascii representation before writing them to
the log.
- <a name='20'></a>__::log::logsubst__ *level* *msg*
Like __::log::log__, but *msg* may contain substitutions and variable
references, which are evaluated in the caller scope first. The purpose of
this command is to avoid overhead in the non-logging case, if the log
message building is expensive. Any substitution errors raise an error in the
command execution. The following example shows an xml text representation,
which is only generated in debug mode:
log::logsubst debug {XML of node $node is '[$node toXml]'}
- <a name='21'></a>__::log::logMsg__ *text*
Convenience wrapper around __::log::log__. Equivalent to __::log::log info
text__.
- <a name='22'></a>__::log::logError__ *text*
Convenience wrapper around __::log::log__. Equivalent to __::log::log error
text__.
- <a name='23'></a>__::log::Puts__ *level* *text*
The standard log command, it writes messages and their levels to
user-specified channels. Assumes that the suppression checks were done by
the caller. Expects full level names, abbreviations are *not allowed*.
# <a name='section3'></a>LEVELS
The package currently defines the following log levels, the level of highest
importance listed first.
- emergency
- alert
- critical
- error
- warning
- notice
- info
- debug
*Note* that by default all messages with levels __warning__ down to __debug__
are suppressed. This is done intentionally, because (we believe that) in most
situations debugging output is not wanted. Most people wish to have such output
only when actually debugging an application.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *log* 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.
# <a name='keywords'></a>KEYWORDS
[log](../../../../index.md#log), [log level](../../../../index.md#log_level),
[message](../../../../index.md#message), [message
level](../../../../index.md#message_level)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2001-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/log/logger.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
|
[//000000001]: # (logger - Object Oriented logging facility)
[//000000002]: # (Generated from file 'logger.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (logger(n) 0.9.4 tcllib "Object Oriented logging facility")
# NAME
logger - System to control logging of events.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [IMPLEMENTATION](#section2)
- [Logprocs and Callstack](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require logger ?0.9.4?
[__logger::init__ *service*](#1)
[__logger::import__ ?__-all__? ?__-force__? ?__-prefix__ *prefix*? ?__-namespace__ *namespace*? *service*](#2)
[__logger::initNamespace__ *ns* ?*level*?](#3)
[__logger::services__](#4)
[__logger::enable__ *level*](#5)
[__logger::disable__ *level*](#6)
[__logger::setlevel__ *level*](#7)
[__logger::levels__](#8)
[__logger::servicecmd__ *service*](#9)
[__${log}::debug__ *message*](#10)
[__${log}::info__ *message*](#11)
[__${log}::notice__ *message*](#12)
[__${log}::warn__ *message*](#13)
[__${log}::error__ *message*](#14)
[__${log}::critical__ *message*](#15)
[__${log}::alert__ *message*](#16)
[__${log}::emergency__ *message*](#17)
[__${log}::setlevel__ *level*](#18)
[__${log}::enable__ *level*](#19)
[__${log}::disable__ *level*](#20)
[__${log}::lvlchangeproc__ *command*](#21)
[__${log}::lvlchangeproc__](#22)
[__${log}::logproc__ *level*](#23)
[__${log}::logproc__ *level* *command*](#24)
[__${log}::logproc__ *level* *argname* *body*](#25)
[__${log}::services__](#26)
[__${log}::servicename__](#27)
[__${log}::currentloglevel__](#28)
[__${log}::delproc__ *command*](#29)
[__${log}::delproc__](#30)
[__${log}::delete__](#31)
[__${log}::trace__ *command*](#32)
[__${log}::trace__ __on__](#33)
[__${log}::trace__ __off__](#34)
[__${log}::trace__ __status__ ?procName? ?...?](#35)
[__${log}::trace__ __add__ *procName* ?...?](#36)
[__${log}::trace__ __add__ ?-ns? *nsName* ?...?](#37)
[__${log}::trace__ __[remove](../../../../index.md#remove)__ *procName* ?...?](#38)
[__${log}::trace__ __[remove](../../../../index.md#remove)__ ?-ns? *nsName* ?...?](#39)
# <a name='description'></a>DESCRIPTION
The __logger__ package provides a flexible system for logging messages from
different services, at priority levels, with different commands.
To begin using the logger package, we do the following:
package require logger
set log [logger::init myservice]
${log}::notice "Initialized myservice logging"
... code ...
${log}::notice "Ending myservice logging"
${log}::delete
In the above code, after the package is loaded, the following things happen:
- <a name='1'></a>__logger::init__ *service*
Initializes the service *service* for logging. The service names are
actually Tcl namespace names, so they are separated with '::'. The service
name may not be the empty string or only ':'s. When a logger service is
initialized, it "inherits" properties from its parents. For instance, if
there were a service *foo*, and we did a __logger::init__ *foo::bar* (to
create a *bar* service underneath *foo*), *bar* would copy the current
configuration of the *foo* service, although it would of course, also be
possible to then separately configure *bar*. If a logger service is
initialized and the parent does not yet exist, the parent is also created.
The new logger service is initialized with the default loglevel set with
__logger::setlevel__.
- <a name='2'></a>__logger::import__ ?__-all__? ?__-force__? ?__-prefix__ *prefix*? ?__-namespace__ *namespace*? *service*
Import the logger service commands into the current namespace. Without the
__-all__ option only the commands corresponding to the log levels are
imported. If __-all__ is given, all the __${log}::cmd__ style commands are
imported. If the import would overwrite a command an error is returned and
no command is imported. Use the __-force__ option to force the import and
overwrite existing commands without complaining. If the __-prefix__ option
is given, the commands are imported with the given *prefix* prepended to
their names. If the __-namespace__ option is given, the commands are
imported into the given namespace. If the namespace does not exist, it is
created. If a namespace without a leading :: is given, it is interpreted as
a child namespace to the current namespace.
- <a name='3'></a>__logger::initNamespace__ *ns* ?*level*?
Convenience command for setting up a namespace for logging. Creates a logger
service named after the namespace *ns* (a :: prefix is stripped), imports
all the log commands into the namespace, and sets the default logging level,
either as specified by *level*, or inherited from a service in the parent
namespace, or a hardwired default, __warn__.
- <a name='4'></a>__logger::services__
Returns a list of all the available services.
- <a name='5'></a>__logger::enable__ *level*
Globally enables logging at and "above" the given level. Levels are
__debug__, __info__, __notice__, __warn__, __error__, __critical__,
__alert__, __emergency__.
- <a name='6'></a>__logger::disable__ *level*
Globally disables logging at and "below" the given level. Levels are those
listed above.
- <a name='7'></a>__logger::setlevel__ *level*
Globally enable logging at and "above" the given level. Levels are those
listed above. This command changes the default loglevel for new loggers
created with __logger::init__.
- <a name='8'></a>__logger::levels__
Returns a list of the available log levels (also listed above under
__enable__).
- <a name='9'></a>__logger::servicecmd__ *service*
Returns the __${log}__ token created by __logger::init__ for this service.
- <a name='10'></a>__${log}::debug__ *message*
- <a name='11'></a>__${log}::info__ *message*
- <a name='12'></a>__${log}::notice__ *message*
- <a name='13'></a>__${log}::warn__ *message*
- <a name='14'></a>__${log}::error__ *message*
- <a name='15'></a>__${log}::critical__ *message*
- <a name='16'></a>__${log}::alert__ *message*
- <a name='17'></a>__${log}::emergency__ *message*
These are the commands called to actually log a message about an event.
__${log}__ is the variable obtained from __logger::init__.
- <a name='18'></a>__${log}::setlevel__ *level*
Enable logging, in the service referenced by __${log}__, and its children,
at and above the level specified, and disable logging below it.
- <a name='19'></a>__${log}::enable__ *level*
Enable logging, in the service referenced by __${log}__, and its children,
at and above the level specified. Note that this does *not* disable logging
below this level, so you should probably use __setlevel__ instead.
- <a name='20'></a>__${log}::disable__ *level*
Disable logging, in the service referenced by __${log}__, and its children,
at and below the level specified. Note that this does *not* enable logging
above this level, so you should probably use __setlevel__ instead. Disabling
the loglevel __emergency__ switches logging off for the service and its
children.
- <a name='21'></a>__${log}::lvlchangeproc__ *command*
- <a name='22'></a>__${log}::lvlchangeproc__
Set the script to call when the log instance in question changes its log
level. If called without a command it returns the currently registered
command. The command gets two arguments appended, the old and the new
loglevel. The callback is invoked after all changes have been done. If child
loggers are affected, their callbacks are called before their parents
callback.
proc lvlcallback {old new} {
puts "Loglevel changed from $old to $new"
}
${log}::lvlchangeproc lvlcallback
- <a name='23'></a>__${log}::logproc__ *level*
- <a name='24'></a>__${log}::logproc__ *level* *command*
- <a name='25'></a>__${log}::logproc__ *level* *argname* *body*
This command comes in three forms - the third, older one is deprecated and
may be removed from future versions of the logger package. The current set
version takes one argument, a command to be executed when the level is
called. The callback command takes on argument, the text to be logged. If
called only with a valid level __logproc__ returns the name of the command
currently registered as callback command. __logproc__ specifies which
command will perform the actual logging for a given level. The logger
package ships with default commands for all log levels, but with __logproc__
it is possible to replace them with custom code. This would let you send
your logs over the network, to a database, or anything else. For example:
proc logtoserver {txt} {
variable socket
puts $socket "Notice: $txt"
}
${log}::logproc notice logtoserver
Trace logs are slightly different: instead of a plain text argument, the
argument provided to the logproc is a dictionary consisting of the __enter__
or __leave__ keyword along with another dictionary of details about the
trace. These include:
__proc__ - Name of the procedure being traced.
__level__ - The stack level for the procedure invocation (from
__[info](../../../../index.md#info)__ __level__).
__script__ - The name of the file in which the procedure is defined, or an
empty string if defined in interactive mode.
__caller__ - The name of the procedure calling the procedure being traced,
or an empty string if the procedure was called from the global scope (stack
level 0).
__procargs__ - A dictionary consisting of the names of arguments to the
procedure paired with values given for those arguments (__enter__ traces
only).
__status__ - The Tcl return code (e.g. __ok__, __continue__, etc.)
(__leave__ traces only).
__result__ - The value returned by the procedure (__leave__ traces only).
- <a name='26'></a>__${log}::services__
Returns a list of the registered logging services which are children of this
service.
- <a name='27'></a>__${log}::servicename__
Returns the name of this service.
- <a name='28'></a>__${log}::currentloglevel__
Returns the currently enabled log level for this service. If no logging is
enabled returns __none__.
- <a name='29'></a>__${log}::delproc__ *command*
- <a name='30'></a>__${log}::delproc__
Set the script to call when the log instance in question is deleted. If
called without a command it returns the currently registered command. For
example:
${log}::delproc [list closesock $logsock]
- <a name='31'></a>__${log}::delete__
This command deletes a particular logging service, and its children. You
must call this to clean up the resources used by a service.
- <a name='32'></a>__${log}::trace__ *command*
This command controls logging of enter/leave traces for specified
procedures. It is used to enable and disable tracing, query tracing status,
and specify procedures are to be traced. Trace handlers are unregistered
when tracing is disabled. As a result, there is not performance impact to a
library when tracing is disabled, just as with other log level commands.
proc tracecmd { dict } {
puts $dict
}
set log [::logger::init example]
${log}::logproc trace tracecmd
proc foo { args } {
puts "In foo"
bar 1
return "foo_result"
}
proc bar { x } {
puts "In bar"
return "bar_result"
}
${log}::trace add foo bar
${log}::trace on
foo
# Output:
enter {proc ::foo level 1 script {} caller {} procargs {args {}}}
In foo
enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}}
In bar
leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result}
leave {proc ::foo level 1 script {} caller {} status ok result foo_result}
- <a name='33'></a>__${log}::trace__ __on__
Turns on trace logging for procedures registered through the
__[trace](../../../../index.md#trace)__ __add__ command. This is similar to
the __enable__ command for other logging levels, but allows trace logging to
take place at any level. The trace logging mechanism takes advantage of the
execution trace feature of Tcl 8.4 and later. The
__[trace](../../../../index.md#trace)__ __on__ command will return an error
if called from earlier versions of Tcl.
- <a name='34'></a>__${log}::trace__ __off__
Turns off trace logging for procedures registered for trace logging through
the __[trace](../../../../index.md#trace)__ __add__ command. This is similar
to the __disable__ command for other logging levels, but allows trace
logging to take place at any level. Procedures are not unregistered, so
logging for them can be turned back on with the
__[trace](../../../../index.md#trace)__ __on__ command. There is no overhead
imposed by trace registration when trace logging is disabled.
- <a name='35'></a>__${log}::trace__ __status__ ?procName? ?...?
This command returns a list of the procedures currently registered for trace
logging, or a flag indicating whether or not a trace is registered for one
or more specified procedures.
- <a name='36'></a>__${log}::trace__ __add__ *procName* ?...?
- <a name='37'></a>__${log}::trace__ __add__ ?-ns? *nsName* ?...?
This command registers one or more procedures for logging of entry/exit
traces. Procedures can be specified via a list of procedure names or
namespace names (in which case all procedure within the namespace are
targeted by the operation). By default, each name is first interpreted as a
procedure name or glob-style search pattern, and if not found its
interpreted as a namespace name. The *-ns* option can be used to force
interpretation of all provided arguments as namespace names. Procedures must
be defined prior to registering them for tracing through the
__[trace](../../../../index.md#trace)__ __add__ command. Any procedure or
namespace names/patterns that don't match any existing procedures will be
silently ignored.
- <a name='38'></a>__${log}::trace__ __[remove](../../../../index.md#remove)__ *procName* ?...?
- <a name='39'></a>__${log}::trace__ __[remove](../../../../index.md#remove)__ ?-ns? *nsName* ?...?
This command unregisters one or more procedures so that they will no longer
have trace logging performed, with the same matching rules as that of the
__[trace](../../../../index.md#trace)__ __add__ command.
# <a name='section2'></a>IMPLEMENTATION
The logger package is implemented in such a way as to optimize (for Tcl 8.4 and
newer) log procedures which are disabled. They are aliased to a proc which has
no body, which is compiled to a no op in bytecode. This should make the
peformance hit minimal. If you really want to pull out all the stops, you can
replace the ${log} token in your code with the actual namespace and command
(${log}::warn becomes ::logger::tree::myservice::warn), so that no variable
lookup is done. This puts the performance of disabled logger commands very close
to no logging at all.
The "object orientation" is done through a hierarchy of namespaces. Using an
actual object oriented system would probably be a better way of doing things, or
at least provide for a cleaner implementation.
The service "object orientation" is done with namespaces.
# <a name='section3'></a>Logprocs and Callstack
The logger package takes extra care to keep the logproc out of the call stack.
This enables logprocs to execute code in the callers scope by using uplevel or
linking to local variables by using upvar. This may fire traces with all usual
side effects.
# Print caller and current vars in the calling proc
proc log_local_var {txt} {
set caller [info level -1]
set vars [uplevel 1 info vars]
foreach var [lsort $vars] {
if {[uplevel 1 [list array exists $var]] == 1} {
lappend val $var <Array>
} else {
lappend val $var [uplevel 1 [list set $var]]
}
}
puts "$txt"
puts "Caller: $caller"
puts "Variables in callers scope:"
foreach {var value} $val {
puts "$var = $value"
}
}
# install as logproc
${log}::logproc debug log_local_var
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *logger* 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.
# <a name='keywords'></a>KEYWORDS
[log](../../../../index.md#log), [log level](../../../../index.md#log_level),
[logger](../../../../index.md#logger), [service](../../../../index.md#service)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/log/loggerAppender.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
[//000000001]: # (logger::appender - Object Oriented logging facility)
[//000000002]: # (Generated from file 'loggerAppender.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (logger::appender(n) 1.2 tcllib "Object Oriented logging facility")
# NAME
logger::appender - Collection of predefined appenders for logger
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require logger::appender ?1.2?
[__::logger::appender::console__ __-level__ *level* __-service__ *service* ?*options*...?](#1)
[__::logger::appender::colorConsole__ __-level__ *level* __-service__ *service* ?*options*...?](#2)
# <a name='description'></a>DESCRIPTION
This package provides a predefined set of logger templates.
- <a name='1'></a>__::logger::appender::console__ __-level__ *level* __-service__ *service* ?*options*...?
* __-level__ level
Name of the level to fill in as "priority" in the log procedure.
* __-service__ service
Name of the service to fill in as "category" in the log procedure.
* __-appenderArgs__ appenderArgs
Any additional arguments for the log procedure in list form
* __-conversionPattern__ conversionPattern
The log pattern to use (see __logger::utils::createLogProc__ for the
allowed substitutions).
* __-procName__ procName
Explicitly set the name of the created procedure.
* __-procNameVar__ procNameVar
Name of the variable to set in the calling context. This variable will
contain the name of the procedure.
- <a name='2'></a>__::logger::appender::colorConsole__ __-level__ *level* __-service__ *service* ?*options*...?
See __::logger::appender::colorConsole__ for a description of the applicable
options.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *logger* 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.
# <a name='keywords'></a>KEYWORDS
[appender](../../../../index.md#appender), [logger](../../../../index.md#logger)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Aamer Akhter <[email protected]>
|
Added embedded/md/tcllib/files/modules/log/loggerUtils.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
[//000000001]: # (logger::utils - Object Oriented logging facility)
[//000000002]: # (Generated from file 'loggerUtils.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (logger::utils(n) 1.3 tcllib "Object Oriented logging facility")
# NAME
logger::utils - Utilities for logger
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require logger::utils ?1.3?
[__::logger::utils::createFormatCmd__ *formatString*](#1)
[__::logger::utils::createLogProc__ __-procName__ *procName* ?*options*...?](#2)
[__::logger::utils::applyAppender__ __-appender__ *appenderType* ?*options*...?](#3)
[__::logger::utils::autoApplyAppender__ *command* *command-string* *log* *op* *args*...](#4)
# <a name='description'></a>DESCRIPTION
This package adds template based *appenders*.
- <a name='1'></a>__::logger::utils::createFormatCmd__ *formatString*
This command translates *formatString* into an expandable command string.
The following strings are the known substitutions (from log4perl) allowed to
occur in the *formatString*:
* %c
Category of the logging event
* %C
Fully qualified name of logging event
* %d
Current date in yyyy/MM/dd hh:mm:ss
* %H
Hostname
* %m
Message to be logged
* %M
Method where logging event was issued
* %p
Priority of logging event
* %P
Pid of current process
- <a name='2'></a>__::logger::utils::createLogProc__ __-procName__ *procName* ?*options*...?
This command ...
* __-procName__ procName
The name of the procedure to create.
* __-conversionPattern__ pattern
See __::logger::utils::createFormatCmd__ for the substitutions allowed
in the *pattern*.
* __-category__ category
The category (service).
* __-priority__ priority
The priority (level).
* __-outputChannel__ channel
channel to output on (default stdout)
- <a name='3'></a>__::logger::utils::applyAppender__ __-appender__ *appenderType* ?*options*...?
This command will create an appender for the specified logger services. If
no service is specified then the appender will be added as the default
appender for the specified levels. If no levels are specified, then all
levels are assumed.
* __-service__ loggerservices
* __-serviceCmd__ loggerserviceCmds
Name of the logger instance to modify. __-serviceCmd__ takes as input
the return of __logger::init__.
* __-appender__ appenderType
Type of the appender to use. One of __console__, __colorConsole__.
* __-appenderArgs__ appenderArgs
Additional arguments to apply to the appender. The argument of the
option is a list of options and their arguments.
For example
logger::utils::applyAppender -serviceCmd $log -appender console -appenderArgs {-conversionPattern {\[%M\] \[%p\] - %m}}
The usual Tcl quoting rules apply.
* __-levels__ levelList
The list of levels to apply this appender to. If not specified all
levels are assumed.
Example of usage:
% set log [logger::init testLog]
::logger::tree::testLog
% logger::utils::applyAppender -appender console -serviceCmd $log
% ${log}::error "this is an error"
[2005/08/22 10:14:13] [testLog] [global] [error] this is an error
- <a name='4'></a>__::logger::utils::autoApplyAppender__ *command* *command-string* *log* *op* *args*...
This command is designed to be added via __trace leave__ to calls of
__logger::init__. It will look at preconfigured state (via
__::logger::utils::applyAppender__) to autocreate appenders for newly
created logger instances. It will return its argument *log*.
Example of usage:
logger::utils::applyAppender -appender console
set log [logger::init applyAppender-3]
${log}::error "this is an error"
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *logger* 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.
# <a name='keywords'></a>KEYWORDS
[appender](../../../../index.md#appender), [logger](../../../../index.md#logger)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Aamer Akhter <[email protected]>
|
Added embedded/md/tcllib/files/modules/map/map_geocode_nominatim.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
[//000000001]: # (map::geocode::nominatim - Mapping utilities)
[//000000002]: # (Generated from file 'map_geocode_nominatim.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (map::geocode::nominatim(n) 0.1 tcllib "Mapping utilities")
# NAME
map::geocode::nominatim - Resolving geographical names with a Nominatim service
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#subsection1)
- [Methods](#subsection2)
- [References](#section3)
- [Keywords](#keywords)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require http
package require json
package require uri
package require snit
package require map::geocode::nominatim ?0.1?
[__::map::geocode::nominatim__ *requestor* ?__-baseurl__ *url*? ?__-callback__ *callback*? ?__-error__ *error callback*?](#1)
[__$cmdprefix__ *result*](#2)
[__$cmdprefix__ *errorstring*](#3)
[*requestor* __search__ *query*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a class for accessing geocoding services which implement
the *[Nominatim](../../../../index.md#nominatim)* interface (see
[References](#section3))
# <a name='section2'></a>API
- <a name='1'></a>__::map::geocode::nominatim__ *requestor* ?__-baseurl__ *url*? ?__-callback__ *callback*? ?__-error__ *error callback*?
Creates a geocoding request object *requestor*, which will send its requests
to the *[Nominatim](../../../../index.md#nominatim)* server.
The result of the command is *name*.
## <a name='subsection1'></a>Options
- __-baseurl__ *url*
The base URL of the *[Nominatim](../../../../index.md#nominatim)* service.
Default value is *OpenStreetMap's* service at
[http://nominatim.openstreetmap.org/search](http://nominatim.openstreetmap.org/search)
A possible free alternative is at
[http://open.mapquestapi.com//nominatim/v1/search](http://open.mapquestapi.com//nominatim/v1/search)
- __-callback__ *cmdprefix*
A command prefix to be invoked when search result become available. The
default setting, active when nothing was specified on object creation, is to
print the *result* (see below) to *[stdout](../../../../index.md#stdout)*.
The result of the command prefix is ignored. Errors thrown by the command
prefix are caught and cause the invokation of the error callback (see option
__-error__ below), with the error message as argument.
The signature of the command prefix is:
* <a name='2'></a>__$cmdprefix__ *result*
The *result* is a list of dictionaries, containing one item per hit.
Each dictionary will have the following entries:
+ place_id
The place ID (FIXME: what's this?)
+ licence
The data licence string
+ osm_type
The OSM type of the location
+ osm_id
FIXME
+ boundingbox
The coordinates of the bounding box (min and max latitude, min and
max longitude)
+ lat
The location's latitude
+ lon
The location's longitude
+ display_name
the location's human readable name
+ class
FIXME
+ type
FIXME
+ icon
FIXME
- __-error__ *cmdprefix*
A command prefix to be invoked when encountering errors. Typically these are
HTTP errors. The default setting, active when nothing was specified on
object creation, is to print the *errorstring* (see below) to *stderr*. The
result of the command prefix is ignored. Errors thrown by the command prefix
are passed to higher levels.
The signature of the command prefix is:
* <a name='3'></a>__$cmdprefix__ *errorstring*
## <a name='subsection2'></a>Methods
- <a name='4'></a>*requestor* __search__ *query*
This method returns a list of dictionaries, one item per hit for the
specified *query*.
# <a name='section3'></a>References
1. [http://wiki.openstreetmap.org/wiki/Nominatim](http://wiki.openstreetmap.org/wiki/Nominatim)
1. [http://open.mapquestapi.com/nominatim/](http://open.mapquestapi.com/nominatim/)
# <a name='keywords'></a>KEYWORDS
[geocoding](../../../../index.md#geocoding), [http](../../../../index.md#http),
[location](../../../../index.md#location), [map](../../../../index.md#map),
[nominatim](../../../../index.md#nominatim),
[server](../../../../index.md#server), [url](../../../../index.md#url)
|
Added embedded/md/tcllib/files/modules/map/map_slippy.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
[//000000001]: # (map::slippy - Mapping utilities)
[//000000002]: # (Generated from file 'map_slippy.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (map::slippy(n) 0.5 tcllib "Mapping utilities")
# NAME
map::slippy - Common code for slippy based map packages
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Coordinate systems](#section3)
- [Geographic](#subsection1)
- [Tiles](#subsection2)
- [Pixels/Points](#subsection3)
- [References](#section4)
- [Keywords](#keywords)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require Tk 8.4
package require map::slippy ?0.5?
[__::map::slippy__ __length__ *level*](#1)
[__::map::slippy__ __tiles__ *level*](#2)
[__::map::slippy__ __tile size__](#3)
[__::map::slippy__ __tile valid__ *tile* *levels* ?*msgvar*?](#4)
[__::map::slippy__ __geo 2tile__ *geo*](#5)
[__::map::slippy__ __geo 2tile.float__ *geo*](#6)
[__::map::slippy__ __geo 2point__ *geo*](#7)
[__::map::slippy__ __tile 2geo__ *tile*](#8)
[__::map::slippy__ __tile 2point__ *tile*](#9)
[__::map::slippy__ __point 2geo__ *point*](#10)
[__::map::slippy__ __point 2tile__ *point*](#11)
[__::map::slippy__ __fit geobox__ *canvdim* *geobox* *zmin* *zmax*](#12)
# <a name='description'></a>DESCRIPTION
This package provides a number of methods doing things needed by all types of
slippy-based map packages.
# <a name='section2'></a>API
- <a name='1'></a>__::map::slippy__ __length__ *level*
This method returns the width/height of a slippy-based map at the specified
zoom *level*, in pixels. This is, in essence, the result of
expr { [tiles $level] * [tile size] }
- <a name='2'></a>__::map::slippy__ __tiles__ *level*
This method returns the width/height of a slippy-based map at the specified
zoom *level*, in *tiles*.
- <a name='3'></a>__::map::slippy__ __tile size__
This method returns the width/height of a tile in a slippy-based map, in
pixels.
- <a name='4'></a>__::map::slippy__ __tile valid__ *tile* *levels* ?*msgvar*?
This method checks whether *tile* described a valid tile in a slippy-based
map containing that many zoom *levels*. The result is a boolean value,
__true__ if the tile is valid, and __false__ otherwise. For the latter a
message is left in the variable named by *msgvar*, should it be specified.
A tile identifier as stored in *tile* is a list containing zoom level, tile
row, and tile column, in this order. The command essentially checks this,
i.e. the syntax, that the zoom level is between 0 and "*levels*-1", and that
the row/col information is within the boundaries for the zoom level, i.e. 0
... "[tiles $zoom]-1".
- <a name='5'></a>__::map::slippy__ __geo 2tile__ *geo*
Converts a geographical location at a zoom level (*geo*, a list containing
zoom level, latitude, and longitude, in this order) to a tile identifier
(list containing zoom level, row, and column) at that level. The tile
identifier uses pure integer numbers for the tile coordinates, for all
geographic coordinates mapping to that tile.
- <a name='6'></a>__::map::slippy__ __geo 2tile.float__ *geo*
Converts a geographical location at a zoom level (*geo*, a list containing
zoom level, latitude, and longitude, in this order) to a tile identifier
(list containing zoom level, row, and column) at that level. The tile
identifier uses floating point numbers for the tile coordinates,
representing not only the tile the geographic coordinates map to, but also
the fractional location inside of that tile.
- <a name='7'></a>__::map::slippy__ __geo 2point__ *geo*
Converts a geographical location at a zoom level (*geo*, a list containing
zoom level, latitude, and longitude, in this order) to a pixel position
(list containing zoom level, y, and x) at that level.
- <a name='8'></a>__::map::slippy__ __tile 2geo__ *tile*
Converts a tile identifier at a zoom level (*tile*, list containing zoom
level, row, and column) to a geographical location (list containing zoom
level, latitude, and longitude, in this order) at that level.
- <a name='9'></a>__::map::slippy__ __tile 2point__ *tile*
Converts a tile identifier at a zoom level (*tile*, a list containing zoom
level, row, and column, in this order) to a pixel position (list containing
zoom level, y, and x) at that level.
- <a name='10'></a>__::map::slippy__ __point 2geo__ *point*
Converts a pixel position at a zoom level (*point*, list containing zoom
level, y, and x) to a geographical location (list containing zoom level,
latitude, and longitude, in this order) at that level.
- <a name='11'></a>__::map::slippy__ __point 2tile__ *point*
Converts a pixel position at a zoom level (*point*, a list containing zoom
level, y, and x, in this order) to a tile identifier (list containing zoom
level, row, and column) at that level.
- <a name='12'></a>__::map::slippy__ __fit geobox__ *canvdim* *geobox* *zmin* *zmax*
Calculates the zoom level (whithin the bounds *zmin* and *zmax*) such that
*geobox* (a 4-element list containing the latitudes and longitudes lat0,
lat1, lon0 and lon1 of a geo box, in this order) fits into a viewport given
by *canvdim*, a 2-element list containing the width and height of the
viewport, in this order.
# <a name='section3'></a>Coordinate systems
The commands of this package operate on three distinct coordinate systems, which
are explained below.
## <a name='subsection1'></a>Geographic
*Geographic*al coordinates are represented by *Latitude* and
*[Longitude](../../../../index.md#longitude)*, each of which is measured in
degrees, as they are essentially angles.
__Zero__ longitude is the *Greenwich meridian*, with positive values going
*east*, and negative values going *west*, for a total range of +/- 180 degrees.
Note that +180 and -180 longitude are the same *meridian*, opposite to
greenwich.
__zero__ latitude the *Equator*, with positive values going *north* and negative
values going *south*. While the true range is +/- 90 degrees the projection used
by the package requires us to cap the range at +/- 85.05112877983284 degrees.
This means that north and south pole are not representable and not part of any
map.
## <a name='subsection2'></a>Tiles
While [Geographic](#subsection1)al coordinates of the previous section are
independent of zoom level the *tile coordinates* are not.
Generally the integer part of tile coordinates represent the row and column
number of the tile in question, wheras the fractional parts signal how far
inside the tile the location in question is, with pure integer coordinates (no
fractional part) representing the upper left corner of the tile.
The zero point of the map is at the upper left corner, regardless of zoom level,
with larger coordinates going right (east) and down (south), and smaller
coordinates going left (west) and up (north). Again regardless of zxoom level.
Negative tile coordinates are not allowed.
At zoom level 0 the whole map is represented by a single, putting the geographic
zero at 1/2, 1/2 of tile coordinates, and the range of tile coordinates as
[0...1].
To go from a zoom level N to the next deeper level N+1 each tile of level N is
split into its four quadrants, which then are the tiles of level N+1.
This means that at zoom level N the map is sliced (horizontally and vertically)
into 2^N stripes, for a total of 4^N tiles, with tile coordinates ranging from 0
to 2^N+1.
## <a name='subsection3'></a>Pixels/Points
*pixel coordinates*, also called *point coordinates* are in essence [tile
coordinates](#subsection2) scaled by the size of the image representing a tile.
This tile size currently has a fixed value, __256__.
# <a name='section4'></a>References
1. [http://wiki.openstreetmap.org/wiki/Main_Page](http://wiki.openstreetmap.org/wiki/Main_Page)
# <a name='keywords'></a>KEYWORDS
[geodesy](../../../../index.md#geodesy),
[geography](../../../../index.md#geography),
[latitute](../../../../index.md#latitute),
[location](../../../../index.md#location),
[longitude](../../../../index.md#longitude), [map](../../../../index.md#map),
[slippy](../../../../index.md#slippy), [zoom](../../../../index.md#zoom)
|
Added embedded/md/tcllib/files/modules/map/map_slippy_cache.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
[//000000001]: # (map::slippy::cache - Mapping utilities)
[//000000002]: # (Generated from file 'map_slippy_cache.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (map::slippy::cache(n) 0.2 tcllib "Mapping utilities")
# NAME
map::slippy::cache - Management of a tile cache in the local filesystem
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Methods](#subsection1)
- [References](#section3)
- [Keywords](#keywords)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require Tk 8.4
package require img::png
package require map::slippy
package require map::slippy::cache ?0.2?
[__::map::slippy::cache__ *cacheName* *cachedir* *provider*](#1)
[*cacheName* __valid__ *tile* ?*msgvar*?](#2)
[*cacheName* __exists__ *tile*](#3)
[*cacheName* __get__ *tile* *donecmd*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a class for managing a cache of tiles for slippy-based
maps in the local filesystem.
# <a name='section2'></a>API
- <a name='1'></a>__::map::slippy::cache__ *cacheName* *cachedir* *provider*
Creates the cache *cacheName* and configures it with both the path to the
directory contaiing the locally cached tiles (*cachedir*), and the command
prefix from which it will pull tiles asked for and not yet known to the
cache itself (*provider*).
The result of the command is *cacheName*.
## <a name='subsection1'></a>Methods
- <a name='2'></a>*cacheName* __valid__ *tile* ?*msgvar*?
This method checks the validity of a the given *tile* identifier. This is a
convenience wrapper to __::map::slippy tile valid__ and has the same
interface.
- <a name='3'></a>*cacheName* __exists__ *tile*
This methods tests whether the cache contains the specified *tile* or not.
The result is a boolean value, __true__ if the tile is known, and __false__
otherwise. The tile is identified by a list containing three elements, zoom
level, row, and column number, in this order.
- <a name='4'></a>*cacheName* __get__ *tile* *donecmd*
This is the main method of the cache, retrieving the image for the specified
*tile* from the cache. The tile identifier is a list containing three
elements, the zoom level, row, and column number of the tile, in this order.
The command refix *donecmd* will be invoked when the cache either knows the
image for the tile or that no image will forthcoming. It will be invoked
with either 2 or 3 arguments, i.e.
The string __set__, the *tile*, and the image.
The string __unset__, and the *tile*.
These two possibilities are used to either signal the image for the *tile*,
or that the *tile* has no image defined for it.
When the cache has no information about the tile it will invoke the
*provider* command prefix specified during its construction, adding three
arguments: The string __get__, the *tile*, and a callback into the cache.
The latter will be invoked by the provider to either transfer the image to
the cache, or signal that the tile has no image.
When multiple requests for the same tile are made only one request will be
issued to the provider.
# <a name='section3'></a>References
1. [http://wiki.openstreetmap.org/wiki/Main_Page](http://wiki.openstreetmap.org/wiki/Main_Page)
# <a name='keywords'></a>KEYWORDS
[cache](../../../../index.md#cache),
[filesystem](../../../../index.md#filesystem),
[location](../../../../index.md#location), [map](../../../../index.md#map),
[slippy](../../../../index.md#slippy), [tile](../../../../index.md#tile),
[zoom](../../../../index.md#zoom)
|
Added embedded/md/tcllib/files/modules/map/map_slippy_fetcher.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
[//000000001]: # (map::slippy::fetcher - Mapping utilities)
[//000000002]: # (Generated from file 'map_slippy_fetcher.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (map::slippy::fetcher(n) 0.4 tcllib "Mapping utilities")
# NAME
map::slippy::fetcher - Accessing a server providing tiles for slippy-based maps
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Methods](#subsection1)
- [References](#section3)
- [Keywords](#keywords)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require Tk 8.4
package require img::png
package require map::slippy
package require map::slippy::fetcher ?0.4?
[__::map::slippy::fetcher__ *fetcherName* *levels* *url*](#1)
[*fetcherName* __levels__](#2)
[*fetcherName* __tileheight__](#3)
[*fetcherName* __tilewidth__](#4)
[*fetcherName* __get__ *tile* *donecmd*](#5)
# <a name='description'></a>DESCRIPTION
This package provides a class for accessing http servers providing tiles for
slippy-based maps.
# <a name='section2'></a>API
- <a name='1'></a>__::map::slippy::fetcher__ *fetcherName* *levels* *url*
Creates the fetcher *fetcherName* and configures it with the number of zoom
*levels* supported by the tile server, and the *url* it is listening on for
tile requests.
The result of the command is *fetcherName*.
## <a name='subsection1'></a>Methods
- <a name='2'></a>*fetcherName* __levels__
This method returns the number of zoom levels supported by the fetcher
object, and the tile server it is accessing.
- <a name='3'></a>*fetcherName* __tileheight__
This method returns the height of tiles served, in pixels.
- <a name='4'></a>*fetcherName* __tilewidth__
This method returns the width of tiles served, in pixels.
- <a name='5'></a>*fetcherName* __get__ *tile* *donecmd*
This is the main method of the fetcher, retrieving the image for the
specified *tile*. The tile identifier is a list containing three elements,
the zoom level, row, and column number of the tile, in this order.
The command refix *donecmd* will be invoked when the fetcher either knows
the image for the tile or that no image will forthcoming. It will be invoked
with either 2 or 3 arguments, i.e.
The string __set__, the *tile*, and the image.
The string __unset__, and the *tile*.
These two possibilities are used to either signal the image for the *tile*,
or that the *tile* has no image defined for it.
# <a name='section3'></a>References
1. [http://wiki.openstreetmap.org/wiki/Main_Page](http://wiki.openstreetmap.org/wiki/Main_Page)
# <a name='keywords'></a>KEYWORDS
[http](../../../../index.md#http), [location](../../../../index.md#location),
[map](../../../../index.md#map), [server](../../../../index.md#server),
[slippy](../../../../index.md#slippy), [tile](../../../../index.md#tile),
[url](../../../../index.md#url), [zoom](../../../../index.md#zoom)
|
Added embedded/md/tcllib/files/modules/mapproj/mapproj.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
|
[//000000001]: # (mapproj - Tcl Library)
[//000000002]: # (Generated from file 'mapproj.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (mapproj(n) 0.1 tcllib "Tcl Library")
# NAME
mapproj - Map projection routines
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Arguments](#section3)
- [Results](#section4)
- [Choosing a projection](#section5)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require math::interpolate ?1.0?
package require math::special ?0.2.1?
package require mapproj ?1.0?
[__::mapproj::toPlateCarree__ *lambda_0* *phi_0* *lambda* *phi*](#1)
[__::mapproj::fromPlateCarree__ *lambda_0* *phi_0* *x* *y*](#2)
[__::mapproj::toCylindricalEqualArea__ *lambda_0* *phi_0* *lambda* *phi*](#3)
[__::mapproj::fromCylindricalEqualArea__ *lambda_0* *phi_0* *x* *y*](#4)
[__::mapproj::toMercator__ *lambda_0* *phi_0* *lambda* *phi*](#5)
[__::mapproj::fromMercator__ *lambda_0* *phi_0* *x* *y*](#6)
[__::mapproj::toMillerCylindrical__ *lambda_0* *lambda* *phi*](#7)
[__::mapproj::fromMillerCylindrical__ *lambda_0* *x* *y*](#8)
[__::mapproj::toSinusoidal__ *lambda_0* *phi_0* *lambda* *phi*](#9)
[__::mapproj::fromSinusoidal__ *lambda_0* *phi_0* *x* *y*](#10)
[__::mapproj::toMollweide__ *lambda_0* *lambda* *phi*](#11)
[__::mapproj::fromMollweide__ *lambda_0* *x* *y*](#12)
[__::mapproj::toEckertIV__ *lambda_0* *lambda* *phi*](#13)
[__::mapproj::fromEckertIV__ *lambda_0* *x* *y*](#14)
[__::mapproj::toEckertVI__ *lambda_0* *lambda* *phi*](#15)
[__::mapproj::fromEckertVI__ *lambda_0* *x* *y*](#16)
[__::mapproj::toRobinson__ *lambda_0* *lambda* *phi*](#17)
[__::mapproj::fromRobinson__ *lambda_0* *x* *y*](#18)
[__::mapproj::toCassini__ *lambda_0* *phi_0* *lambda* *phi*](#19)
[__::mapproj::fromCassini__ *lambda_0* *phi_0* *x* *y*](#20)
[__::mapproj::toPeirceQuincuncial__ *lambda_0* *lambda* *phi*](#21)
[__::mapproj::fromPeirceQuincuncial__ *lambda_0* *x* *y*](#22)
[__::mapproj::toOrthographic__ *lambda_0* *phi_0* *lambda* *phi*](#23)
[__::mapproj::fromOrthographic__ *lambda_0* *phi_0* *x* *y*](#24)
[__::mapproj::toStereographic__ *lambda_0* *phi_0* *lambda* *phi*](#25)
[__::mapproj::fromStereographic__ *lambda_0* *phi_0* *x* *y*](#26)
[__::mapproj::toGnomonic__ *lambda_0* *phi_0* *lambda* *phi*](#27)
[__::mapproj::fromGnomonic__ *lambda_0* *phi_0* *x* *y*](#28)
[__::mapproj::toAzimuthalEquidistant__ *lambda_0* *phi_0* *lambda* *phi*](#29)
[__::mapproj::fromAzimuthalEquidistant__ *lambda_0* *phi_0* *x* *y*](#30)
[__::mapproj::toLambertAzimuthalEqualArea__ *lambda_0* *phi_0* *lambda* *phi*](#31)
[__::mapproj::fromLambertAzimuthalEqualArea__ *lambda_0* *phi_0* *x* *y*](#32)
[__::mapproj::toHammer__ *lambda_0* *lambda* *phi*](#33)
[__::mapproj::fromHammer__ *lambda_0* *x* *y*](#34)
[__::mapproj::toConicEquidistant__ *lambda_0* *phi_0* *phi_1* *phi_2* *lambda* *phi*](#35)
[__::mapproj::fromConicEquidistant__ *lambda_0* *phi_0* *phi_1* *phi_2* *x* *y*](#36)
[__::mapproj::toAlbersEqualAreaConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *lambda* *phi*](#37)
[__::mapproj::fromAlbersEqualAreaConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *x* *y*](#38)
[__::mapproj::toLambertConformalConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *lambda* *phi*](#39)
[__::mapproj::fromLambertConformalConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *x* *y*](#40)
[__::mapproj::toLambertCylindricalEqualArea__ *lambda_0* *phi_0* *lambda* *phi*](#41)
[__::mapproj::fromLambertCylindricalEqualArea__ *lambda_0* *phi_0* *x* *y*](#42)
[__::mapproj::toBehrmann__ *lambda_0* *phi_0* *lambda* *phi*](#43)
[__::mapproj::fromBehrmann__ *lambda_0* *phi_0* *x* *y*](#44)
[__::mapproj::toTrystanEdwards__ *lambda_0* *phi_0* *lambda* *phi*](#45)
[__::mapproj::fromTrystanEdwards__ *lambda_0* *phi_0* *x* *y*](#46)
[__::mapproj::toHoboDyer__ *lambda_0* *phi_0* *lambda* *phi*](#47)
[__::mapproj::fromHoboDyer__ *lambda_0* *phi_0* *x* *y*](#48)
[__::mapproj::toGallPeters__ *lambda_0* *phi_0* *lambda* *phi*](#49)
[__::mapproj::fromGallPeters__ *lambda_0* *phi_0* *x* *y*](#50)
[__::mapproj::toBalthasart__ *lambda_0* *phi_0* *lambda* *phi*](#51)
[__::mapproj::fromBalthasart__ *lambda_0* *phi_0* *x* *y*](#52)
# <a name='description'></a>DESCRIPTION
The __mapproj__ package provides a set of procedures for converting between
world co-ordinates (latitude and longitude) and map co-ordinates on a number of
different map projections.
# <a name='section2'></a>Commands
The following commands convert between world co-ordinates and map co-ordinates:
- <a name='1'></a>__::mapproj::toPlateCarree__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the *plate carrée* (cylindrical equidistant) projection.
- <a name='2'></a>__::mapproj::fromPlateCarree__ *lambda_0* *phi_0* *x* *y*
Converts from the *plate carrée* (cylindrical equidistant) projection.
- <a name='3'></a>__::mapproj::toCylindricalEqualArea__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the cylindrical equal-area projection.
- <a name='4'></a>__::mapproj::fromCylindricalEqualArea__ *lambda_0* *phi_0* *x* *y*
Converts from the cylindrical equal-area projection.
- <a name='5'></a>__::mapproj::toMercator__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Mercator (cylindrical conformal) projection.
- <a name='6'></a>__::mapproj::fromMercator__ *lambda_0* *phi_0* *x* *y*
Converts from the Mercator (cylindrical conformal) projection.
- <a name='7'></a>__::mapproj::toMillerCylindrical__ *lambda_0* *lambda* *phi*
Converts to the Miller Cylindrical projection.
- <a name='8'></a>__::mapproj::fromMillerCylindrical__ *lambda_0* *x* *y*
Converts from the Miller Cylindrical projection.
- <a name='9'></a>__::mapproj::toSinusoidal__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the sinusoidal (Sanson-Flamsteed) projection. projection.
- <a name='10'></a>__::mapproj::fromSinusoidal__ *lambda_0* *phi_0* *x* *y*
Converts from the sinusoidal (Sanson-Flamsteed) projection. projection.
- <a name='11'></a>__::mapproj::toMollweide__ *lambda_0* *lambda* *phi*
Converts to the Mollweide projection.
- <a name='12'></a>__::mapproj::fromMollweide__ *lambda_0* *x* *y*
Converts from the Mollweide projection.
- <a name='13'></a>__::mapproj::toEckertIV__ *lambda_0* *lambda* *phi*
Converts to the Eckert IV projection.
- <a name='14'></a>__::mapproj::fromEckertIV__ *lambda_0* *x* *y*
Converts from the Eckert IV projection.
- <a name='15'></a>__::mapproj::toEckertVI__ *lambda_0* *lambda* *phi*
Converts to the Eckert VI projection.
- <a name='16'></a>__::mapproj::fromEckertVI__ *lambda_0* *x* *y*
Converts from the Eckert VI projection.
- <a name='17'></a>__::mapproj::toRobinson__ *lambda_0* *lambda* *phi*
Converts to the Robinson projection.
- <a name='18'></a>__::mapproj::fromRobinson__ *lambda_0* *x* *y*
Converts from the Robinson projection.
- <a name='19'></a>__::mapproj::toCassini__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Cassini (transverse cylindrical equidistant) projection.
- <a name='20'></a>__::mapproj::fromCassini__ *lambda_0* *phi_0* *x* *y*
Converts from the Cassini (transverse cylindrical equidistant) projection.
- <a name='21'></a>__::mapproj::toPeirceQuincuncial__ *lambda_0* *lambda* *phi*
Converts to the Peirce Quincuncial Projection.
- <a name='22'></a>__::mapproj::fromPeirceQuincuncial__ *lambda_0* *x* *y*
Converts from the Peirce Quincuncial Projection.
- <a name='23'></a>__::mapproj::toOrthographic__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the orthographic projection.
- <a name='24'></a>__::mapproj::fromOrthographic__ *lambda_0* *phi_0* *x* *y*
Converts from the orthographic projection.
- <a name='25'></a>__::mapproj::toStereographic__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the stereographic (azimuthal conformal) projection.
- <a name='26'></a>__::mapproj::fromStereographic__ *lambda_0* *phi_0* *x* *y*
Converts from the stereographic (azimuthal conformal) projection.
- <a name='27'></a>__::mapproj::toGnomonic__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the gnomonic projection.
- <a name='28'></a>__::mapproj::fromGnomonic__ *lambda_0* *phi_0* *x* *y*
Converts from the gnomonic projection.
- <a name='29'></a>__::mapproj::toAzimuthalEquidistant__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the azimuthal equidistant projection.
- <a name='30'></a>__::mapproj::fromAzimuthalEquidistant__ *lambda_0* *phi_0* *x* *y*
Converts from the azimuthal equidistant projection.
- <a name='31'></a>__::mapproj::toLambertAzimuthalEqualArea__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Lambert azimuthal equal-area projection.
- <a name='32'></a>__::mapproj::fromLambertAzimuthalEqualArea__ *lambda_0* *phi_0* *x* *y*
Converts from the Lambert azimuthal equal-area projection.
- <a name='33'></a>__::mapproj::toHammer__ *lambda_0* *lambda* *phi*
Converts to the Hammer projection.
- <a name='34'></a>__::mapproj::fromHammer__ *lambda_0* *x* *y*
Converts from the Hammer projection.
- <a name='35'></a>__::mapproj::toConicEquidistant__ *lambda_0* *phi_0* *phi_1* *phi_2* *lambda* *phi*
Converts to the conic equidistant projection.
- <a name='36'></a>__::mapproj::fromConicEquidistant__ *lambda_0* *phi_0* *phi_1* *phi_2* *x* *y*
Converts from the conic equidistant projection.
- <a name='37'></a>__::mapproj::toAlbersEqualAreaConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *lambda* *phi*
Converts to the Albers equal-area conic projection.
- <a name='38'></a>__::mapproj::fromAlbersEqualAreaConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *x* *y*
Converts from the Albers equal-area conic projection.
- <a name='39'></a>__::mapproj::toLambertConformalConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *lambda* *phi*
Converts to the Lambert conformal conic projection.
- <a name='40'></a>__::mapproj::fromLambertConformalConic__ *lambda_0* *phi_0* *phi_1* *phi_2* *x* *y*
Converts from the Lambert conformal conic projection.
Among the cylindrical equal-area projections, there are a number of choices of
standard parallels that have names:
- <a name='41'></a>__::mapproj::toLambertCylindricalEqualArea__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Lambert cylindrical equal area projection. (standard
parallel is the Equator.)
- <a name='42'></a>__::mapproj::fromLambertCylindricalEqualArea__ *lambda_0* *phi_0* *x* *y*
Converts from the Lambert cylindrical equal area projection. (standard
parallel is the Equator.)
- <a name='43'></a>__::mapproj::toBehrmann__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Behrmann cylindrical equal area projection. (standard
parallels are 30 degrees North and South)
- <a name='44'></a>__::mapproj::fromBehrmann__ *lambda_0* *phi_0* *x* *y*
Converts from the Behrmann cylindrical equal area projection. (standard
parallels are 30 degrees North and South.)
- <a name='45'></a>__::mapproj::toTrystanEdwards__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Trystan Edwards cylindrical equal area projection. (standard
parallels are 37.4 degrees North and South)
- <a name='46'></a>__::mapproj::fromTrystanEdwards__ *lambda_0* *phi_0* *x* *y*
Converts from the Trystan Edwards cylindrical equal area projection.
(standard parallels are 37.4 degrees North and South.)
- <a name='47'></a>__::mapproj::toHoboDyer__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Hobo-Dyer cylindrical equal area projection. (standard
parallels are 37.5 degrees North and South)
- <a name='48'></a>__::mapproj::fromHoboDyer__ *lambda_0* *phi_0* *x* *y*
Converts from the Hobo-Dyer cylindrical equal area projection. (standard
parallels are 37.5 degrees North and South.)
- <a name='49'></a>__::mapproj::toGallPeters__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Gall-Peters cylindrical equal area projection. (standard
parallels are 45 degrees North and South)
- <a name='50'></a>__::mapproj::fromGallPeters__ *lambda_0* *phi_0* *x* *y*
Converts from the Gall-Peters cylindrical equal area projection. (standard
parallels are 45 degrees North and South.)
- <a name='51'></a>__::mapproj::toBalthasart__ *lambda_0* *phi_0* *lambda* *phi*
Converts to the Balthasart cylindrical equal area projection. (standard
parallels are 50 degrees North and South)
- <a name='52'></a>__::mapproj::fromBalthasart__ *lambda_0* *phi_0* *x* *y*
Converts from the Balthasart cylindrical equal area projection. (standard
parallels are 50 degrees North and South.)
# <a name='section3'></a>Arguments
The following arguments are accepted by the projection commands:
- *lambda*
Longitude of the point to be projected, in degrees.
- *phi*
Latitude of the point to be projected, in degrees.
- *lambda_0*
Longitude of the center of the sheet, in degrees. For many projections, this
figure is also the reference meridian of the projection.
- *phi_0*
Latitude of the center of the sheet, in degrees. For the azimuthal
projections, this figure is also the latitude of the center of the
projection.
- *phi_1*
Latitude of the first reference parallel, for projections that use reference
parallels.
- *phi_2*
Latitude of the second reference parallel, for projections that use
reference parallels.
- *x*
X co-ordinate of a point on the map, in units of Earth radii.
- *y*
Y co-ordinate of a point on the map, in units of Earth radii.
# <a name='section4'></a>Results
For all of the procedures whose names begin with 'to', the return value is a
list comprising an *x* co-ordinate and a *y* co-ordinate. The co-ordinates are
relative to the center of the map sheet to be drawn, measured in Earth radii at
the reference location on the map. For all of the functions whose names begin
with 'from', the return value is a list comprising the longitude and latitude,
in degrees.
# <a name='section5'></a>Choosing a projection
This package offers a great many projections, because no single projection is
appropriate to all maps. This section attempts to provide guidance on how to
choose a projection.
First, consider the type of data that you intend to display on the map. If the
data are *directional* (*e.g.,* winds, ocean currents, or magnetic fields) then
you need to use a projection that preserves angles; these are known as
*conformal* projections. Conformal projections include the Mercator, the Albers
azimuthal equal-area, the stereographic, and the Peirce Quincuncial projection.
If the data are *thematic*, describing properties of land or water, such as
temperature, population density, land use, or demographics; then you need a
projection that will show these data with the areas on the map proportional to
the areas in real life. These so-called *equal area* projections include the
various cylindrical equal area projections, the sinusoidal projection, the
Lambert azimuthal equal-area projection, the Albers equal-area conic projection,
and several of the world-map projections (Miller Cylindrical, Mollweide, Eckert
IV, Eckert VI, Robinson, and Hammer). If the significant factor in your data is
distance from a central point or line (such as air routes), then you will do
best with an *equidistant* projection such as *plate carrée*, Cassini, azimuthal
equidistant, or conic equidistant. If direction from a central point is a
critical factor in your data (for instance, air routes, radio antenna pointing),
then you will almost surely want to use one of the azimuthal projections.
Appropriate choices are azimuthal equidistant, azimuthal equal-area,
stereographic, and perhaps orthographic.
Next, consider how much of the Earth your map will cover, and the general shape
of the area of interest. For maps of the entire Earth, the cylindrical equal
area, Eckert IV and VI, Mollweide, Robinson, and Hammer projections are good
overall choices. The Mercator projection is traditional, but the extreme
distortions of area at high latitudes make it a poor choice unless a conformal
projection is required. The Peirce projection is a better choice of conformal
projection, having less distortion of landforms. The Miller Cylindrical is a
compromise designed to give shapes similar to the traditional Mercator, but with
less polar stretching. The Peirce Quincuncial projection shows all the
continents with acceptable distortion if a reference meridian close to +20
degrees is chosen. The Robinson projection yields attractive maps for things
like political divisions, but should be avoided in presenting scientific data,
since other projections have moe useful geometric properties.
If the map will cover a hemisphere, then choose stereographic,
azimuthal-equidistant, Hammer, or Mollweide projections; these all project the
hemisphere into a circle.
If the map will cover a large area (at least a few hundred km on a side), but
less than a hemisphere, then you have several choices. Azimuthal projections are
usually good (choose stereographic, azimuthal equidistant, or Lambert azimuthal
equal-area according to whether shapes, distances from a central point, or areas
are important). Azimuthal projections (and possibly the Cassini projection) are
the only really good choices for mapping the polar regions.
If the large area is in one of the temperate zones and is round or has a
primarily east-west extent, then the conic projections are good choices. Choose
the Lambert conformal conic, the conic equidistant, or the Albers equal-area
conic according to whether shape, distance, or area are the most important
parameters. For any of these, the reference parallels should be chosen at
approximately 1/6 and 5/6 of the range of latitudes to be displayed. For
instance, maps of the 48 coterminous United States are attractive with reference
parallels of 28.5 and 45.5 degrees.
If the large area is equatorial and is round or has a primarily east-west
extent, then the Mercator projection is a good choice for a conformal
projection; Lambert cylindrical equal-area and sinusoidal projections are good
equal-area projections; and the *plate carrée* is a good equidistant projection.
Large areas having a primarily North-South aspect, particularly those spanning
the Equator, need some other choices. The Cassini projection is a good choice
for an equidistant projection (for instance, a Cassini projection with a central
meridian of 80 degrees West produces an attractive map of the Americas). The
cylindrical equal-area, Albers equal-area conic, sinusoidal, Mollweide and
Hammer projections are possible choices for equal-area projections. A good
conformal projection in this situation is the Transverse Mercator, which alas,
is not yet implemented.
Small areas begin to get into a realm where the ellipticity of the Earth affects
the map scale. This package does not attempt to handle accurate mapping for
large-scale topographic maps. If slight scale errors are acceptable in your
application, then any of the projections appropriate to large areas should work
for small ones as well.
There are a few projections that are included for their special properties. The
orthographic projection produces views of the Earth as seen from space. The
gnomonic projection produces a map on which all great circles (the shortest
distance between two points on the Earth's surface) are rendered as straight
lines. While this projection is useful for navigational planning, it has extreme
distortions of shape and area, and can display only a limited area of the Earth
(substantially less than a hemisphere).
# <a name='keywords'></a>KEYWORDS
[geodesy](../../../../index.md#geodesy), [map](../../../../index.md#map),
[projection](../../../../index.md#projection)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Kevin B. Kenny <[email protected]>
|
Added embedded/md/tcllib/files/modules/markdown/markdown.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (markdown - Markdown to HTML Converter)
[//000000002]: # (Generated from file 'markdown.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (markdown(n) 1.1 tcllib "Markdown to HTML Converter")
# NAME
markdown - Converts Markdown text to HTML
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require Markdown 1.1
package require textutil ?0.8?
[__::Markdown::convert__ *markdown*](#1)
[__::Markdown::register__ *langspec* *converter*](#2)
[__::Markdown::get_lang_counter__](#3)
[__::Markdown::reset_lang_counter__](#4)
# <a name='description'></a>DESCRIPTION
The package __Markdown__ provides a command to convert Markdown annotated text
into HMTL.
- <a name='1'></a>__::Markdown::convert__ *markdown*
This command takes in a block of Markdown text, and returns a block of HTML.
The converter supports two types of syntax highlighting for fenced code
blocks: highlighting via a registered converter (see
__::Markdown::register__), or pure JavaScript highlighting, e.g. via
"highlight.js", where the language specifier used in the markup is set as
CSS class of the "code" element in the returned markup.
- <a name='2'></a>__::Markdown::register__ *langspec* *converter*
Register a language specific converter for prettifying a code block (e.g.
syntax highlighting). Markdown supports fenced code blocks with an optional
language specifier (e.g. "tcl"). When the markdown parser processes such a
code block and a converter for the specified langspec is registered, the
converter is called with the raw code block as argument. The converter is
supposed to return the markup of the code block as result. The specified
converter can be an arbitrary Tcl command, the raw text block is added as
last argument upon invocation.
- <a name='3'></a>__::Markdown::get_lang_counter__
Return a dict of language specifier and number of occurrences in fenced code
blocks. This function can be used e.g. to detect, whether some CSS or
JavaScript headers should be included for rendering without the need of
postprocessing the rendered result.
- <a name='4'></a>__::Markdown::reset_lang_counter__
Reset the language counters.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/math/bigfloat.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
|
[//000000001]: # (math::bigfloat - Tcl Math Library)
[//000000002]: # (Generated from file 'bigfloat.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::bigfloat(n) 2.0.1 tcllib "Tcl Math Library")
# NAME
math::bigfloat - Arbitrary precision floating-point numbers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [INTRODUCTION](#section2)
- [ARITHMETICS](#section3)
- [COMPARISONS](#section4)
- [ANALYSIS](#section5)
- [ROUNDING](#section6)
- [PRECISION](#section7)
- [WHAT ABOUT TCL 8.4 ?](#section8)
- [NAMESPACES AND OTHER PACKAGES](#section9)
- [EXAMPLES](#section10)
- [Bugs, Ideas, Feedback](#section11)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require math::bigfloat ?2.0.1?
[__fromstr__ *number* ?*trailingZeros*?](#1)
[__tostr__ ?__-nosci__? *number*](#2)
[__fromdouble__ *double* ?*decimals*?](#3)
[__todouble__ *number*](#4)
[__isInt__ *number*](#5)
[__isFloat__ *number*](#6)
[__int2float__ *integer* ?*decimals*?](#7)
[__add__ *x* *y*](#8)
[__sub__ *x* *y*](#9)
[__mul__ *x* *y*](#10)
[__div__ *x* *y*](#11)
[__mod__ *x* *y*](#12)
[__abs__ *x*](#13)
[__opp__ *x*](#14)
[__pow__ *x* *n*](#15)
[__iszero__ *x*](#16)
[__[equal](../../../../index.md#equal)__ *x* *y*](#17)
[__compare__ *x* *y*](#18)
[__sqrt__ *x*](#19)
[__[log](../log/log.md)__ *x*](#20)
[__exp__ *x*](#21)
[__cos__ *x*](#22)
[__sin__ *x*](#23)
[__tan__ *x*](#24)
[__cotan__ *x*](#25)
[__acos__ *x*](#26)
[__asin__ *x*](#27)
[__atan__ *x*](#28)
[__cosh__ *x*](#29)
[__sinh__ *x*](#30)
[__tanh__ *x*](#31)
[__[pi](../../../../index.md#pi)__ *n*](#32)
[__rad2deg__ *radians*](#33)
[__deg2rad__ *degrees*](#34)
[__round__ *x*](#35)
[__ceil__ *x*](#36)
[__floor__ *x*](#37)
# <a name='description'></a>DESCRIPTION
The bigfloat package provides arbitrary precision floating-point math
capabilities to the Tcl language. It is designed to work with Tcl 8.5, but for
Tcl 8.4 is provided an earlier version of this package. See [WHAT ABOUT TCL 8.4
?](#section8) for more explanations. By convention, we will talk about the
numbers treated in this library as :
- BigFloat for floating-point numbers of arbitrary length.
- integers for arbitrary length signed integers, just as basic integers since
Tcl 8.5.
Each BigFloat is an interval, namely [*m-d, m+d*], where *m* is the mantissa and
*d* the uncertainty, representing the limitation of that number's precision.
This is why we call such mathematics *interval computations*. Just take an
example in physics : when you measure a temperature, not all digits you read are
*significant*. Sometimes you just cannot trust all digits - not to mention if
doubles (f.p. numbers) can handle all these digits. BigFloat can handle this
problem - trusting the digits you get - plus the ability to store numbers with
an arbitrary precision. BigFloats are internally represented at Tcl lists: this
package provides a set of procedures operating against the internal
representation in order to :
- perform math operations on BigFloats and (optionnaly) with integers.
- convert BigFloats from their internal representations to strings, and vice
versa.
# <a name='section2'></a>INTRODUCTION
- <a name='1'></a>__fromstr__ *number* ?*trailingZeros*?
Converts *number* into a BigFloat. Its precision is at least the number of
digits provided by *number*. If the *number* contains only digits and
eventually a minus sign, it is considered as an integer. Subsequently, no
conversion is done at all.
*trailingZeros* - the number of zeros to append at the end of the
floating-point number to get more precision. It cannot be applied to an
integer.
# x and y are BigFloats : the first string contained a dot, and the second an e sign
set x [fromstr -1.000000]
set y [fromstr 2000e30]
# let's see how we get integers
set t 20000000000000
# the old way (package 1.2) is still supported for backwards compatibility :
set m [fromstr 10000000000]
# but we do not need fromstr for integers anymore
set n -39
# t, m and n are integers
The *number*'s last digit is considered by the procedure to be true at +/-1,
For example, 1.00 is the interval [0.99, 1.01], and 0.43 the interval [0.42,
0.44]. The Pi constant may be approximated by the number "3.1415". This
string could be considered as the interval [3.1414 , 3.1416] by __fromstr__.
So, when you mean 1.0 as a double, you may have to write 1.000000 to get
enough precision. To learn more about this subject, see
[PRECISION](#section7).
For example :
set x [fromstr 1.0000000000]
# the next line does the same, but smarter
set y [fromstr 1. 10]
- <a name='2'></a>__tostr__ ?__-nosci__? *number*
Returns a string form of a BigFloat, in which all digits are exacts. *All
exact digits* means a rounding may occur, for example to zero, if the
uncertainty interval does not clearly show the true digits. *number* may be
an integer, causing the command to return exactly the input argument. With
the __-nosci__ option, the number returned is never shown in scientific
notation, i.e. not like '3.4523e+5' but like '345230.'.
puts [tostr [fromstr 0.99999]] ;# 1.0000
puts [tostr [fromstr 1.00001]] ;# 1.0000
puts [tostr [fromstr 0.002]] ;# 0.e-2
See [PRECISION](#section7) for that matter. See also __iszero__ for how to
detect zeros, which is useful when performing a division.
- <a name='3'></a>__fromdouble__ *double* ?*decimals*?
Converts a double (a simple floating-point value) to a BigFloat, with
exactly *decimals* digits. Without the *decimals* argument, it behaves like
__fromstr__. Here, the only important feature you might care of is the
ability to create BigFloats with a fixed number of *decimals*.
tostr [fromstr 1.111 4]
# returns : 1.111000 (3 zeros)
tostr [fromdouble 1.111 4]
# returns : 1.111
- <a name='4'></a>__todouble__ *number*
Returns a double, that may be used in *expr*, from a BigFloat.
- <a name='5'></a>__isInt__ *number*
Returns 1 if *number* is an integer, 0 otherwise.
- <a name='6'></a>__isFloat__ *number*
Returns 1 if *number* is a BigFloat, 0 otherwise.
- <a name='7'></a>__int2float__ *integer* ?*decimals*?
Converts an integer to a BigFloat with *decimals* trailing zeros. The
default, and minimal, number of *decimals* is 1. When converting back to
string, one decimal is lost:
set n 10
set x [int2float $n]; # like fromstr 10.0
puts [tostr $x]; # prints "10."
set x [int2float $n 3]; # like fromstr 10.000
puts [tostr $x]; # prints "10.00"
# <a name='section3'></a>ARITHMETICS
- <a name='8'></a>__add__ *x* *y*
- <a name='9'></a>__sub__ *x* *y*
- <a name='10'></a>__mul__ *x* *y*
Return the sum, difference and product of *x* by *y*. *x* - may be either a
BigFloat or an integer *y* - may be either a BigFloat or an integer When
both are integers, these commands behave like __expr__.
- <a name='11'></a>__div__ *x* *y*
- <a name='12'></a>__mod__ *x* *y*
Return the quotient and the rest of *x* divided by *y*. Each argument (*x*
and *y*) can be either a BigFloat or an integer, but you cannot divide an
integer by a BigFloat Divide by zero throws an error.
- <a name='13'></a>__abs__ *x*
Returns the absolute value of *x*
- <a name='14'></a>__opp__ *x*
Returns the opposite of *x*
- <a name='15'></a>__pow__ *x* *n*
Returns *x* taken to the *n*th power. It only works if *n* is an integer.
*x* might be a BigFloat or an integer.
# <a name='section4'></a>COMPARISONS
- <a name='16'></a>__iszero__ *x*
Returns 1 if *x* is :
a BigFloat close enough to zero to raise "divide by zero".
the integer 0.
See here how numbers that are close to zero are converted to strings:
tostr [fromstr 0.001] ; # -> 0.e-2
tostr [fromstr 0.000000] ; # -> 0.e-5
tostr [fromstr -0.000001] ; # -> 0.e-5
tostr [fromstr 0.0] ; # -> 0.
tostr [fromstr 0.002] ; # -> 0.e-2
set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003
tostr $a ; # 0.e-2
iszero $a ; # false
set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002
tostr $a ; # 0.e-2
iszero $a ; # true
- <a name='17'></a>__[equal](../../../../index.md#equal)__ *x* *y*
Returns 1 if *x* and *y* are equal, 0 elsewhere.
- <a name='18'></a>__compare__ *x* *y*
Returns 0 if both BigFloat arguments are equal, 1 if *x* is greater than
*y*, and -1 if *x* is lower than *y*. You would not be able to compare an
integer to a BigFloat : the operands should be both BigFloats, or both
integers.
# <a name='section5'></a>ANALYSIS
- <a name='19'></a>__sqrt__ *x*
- <a name='20'></a>__[log](../log/log.md)__ *x*
- <a name='21'></a>__exp__ *x*
- <a name='22'></a>__cos__ *x*
- <a name='23'></a>__sin__ *x*
- <a name='24'></a>__tan__ *x*
- <a name='25'></a>__cotan__ *x*
- <a name='26'></a>__acos__ *x*
- <a name='27'></a>__asin__ *x*
- <a name='28'></a>__atan__ *x*
- <a name='29'></a>__cosh__ *x*
- <a name='30'></a>__sinh__ *x*
- <a name='31'></a>__tanh__ *x*
The above functions return, respectively, the following : square root,
logarithm, exponential, cosine, sine, tangent, cotangent, arc cosine, arc
sine, arc tangent, hyperbolic cosine, hyperbolic sine, hyperbolic tangent,
of a BigFloat named *x*.
- <a name='32'></a>__[pi](../../../../index.md#pi)__ *n*
Returns a BigFloat representing the Pi constant with *n* digits after the
dot. *n* is a positive integer.
- <a name='33'></a>__rad2deg__ *radians*
- <a name='34'></a>__deg2rad__ *degrees*
*radians* - angle expressed in radians (BigFloat)
*degrees* - angle expressed in degrees (BigFloat)
Convert an angle from radians to degrees, and *vice versa*.
# <a name='section6'></a>ROUNDING
- <a name='35'></a>__round__ *x*
- <a name='36'></a>__ceil__ *x*
- <a name='37'></a>__floor__ *x*
The above functions return the *x* BigFloat, rounded like with the same
mathematical function in *expr*, and returns it as an integer.
# <a name='section7'></a>PRECISION
How do conversions work with precision ?
- When a BigFloat is converted from string, the internal representation holds
its uncertainty as 1 at the level of the last digit.
- During computations, the uncertainty of each result is internally computed
the closest to the reality, thus saving the memory used.
- When converting back to string, the digits that are printed are not subject
to uncertainty. However, some rounding is done, as not doing so causes
severe problems.
Uncertainties are kept in the internal representation of the number ; it is
recommended to use __tostr__ only for outputting data (on the screen or in a
file), and NEVER call __fromstr__ with the result of __tostr__. It is better to
always keep operands in their internal representation. Due to the internals of
this library, the uncertainty interval may be slightly wider than expected, but
this should not cause false digits.
Now you may ask this question : What precision am I going to get after calling
add, sub, mul or div? First you set a number from the string representation and,
by the way, its uncertainty is set:
set a [fromstr 1.230]
# $a belongs to [1.229, 1.231]
set a [fromstr 1.000]
# $a belongs to [0.999, 1.001]
# $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value)
The uncertainty of the sum, or the difference, of two numbers, is the sum of
their respective uncertainties.
set a [fromstr 1.230]
set b [fromstr 2.340]
set sum [add $a $b]]
# the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2)
tostr $sum ; # 3.57
But when, for example, we add or substract an integer to a BigFloat, the
relative uncertainty of the result is unchanged. So it is desirable not to
convert integers to BigFloats:
set a [fromstr 0.999999999]
# now something dangerous
set b [fromstr 2.000]
# the result has only 3 digits
tostr [add $a $b]
# how to keep precision at its maximum
puts [tostr [add $a 2]]
For multiplication and division, the relative uncertainties of the product or
the quotient, is the sum of the relative uncertainties of the operands. Take
care of division by zero : check each divider with __iszero__.
set num [fromstr 4.00]
set denom [fromstr 0.01]
puts [iszero $denom];# true
set quotient [div $num $denom];# error : divide by zero
# opposites of our operands
puts [compare $num [opp $num]]; # 1
puts [compare $denom [opp $denom]]; # 0 !!!
# No suprise ! 0 and its opposite are the same...
Effects of the precision of a number considered equal to zero to the cos
function:
puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000
puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000
puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000
puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000
BigFloats with different internal representations may be converted to the same
string.
For most analysis functions (cosine, square root, logarithm, etc.), determining
the precision of the result is difficult. It seems however that in many cases,
the loss of precision in the result is of one or two digits. There are some
exceptions : for example,
tostr [exp [fromstr 100.0 10]]
# returns : 2.688117142e+43 which has only 10 digits of precision, although the entry
# has 14 digits of precision.
# <a name='section8'></a>WHAT ABOUT TCL 8.4 ?
If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be
loaded, switching back to *math::bigfloat* 1.2. Indeed, an important function
introduced in Tcl 8.5 is required - the ability to handle bignums, that we can
do with __expr__. Before 8.5, this ability was provided by several packages,
including the pure-Tcl *math::bignum* package provided by *tcllib*. In this
case, all you need to know, is that arguments to the commands explained here,
are expected to be in their internal representation. So even with integers, you
will need to call __fromstr__ and __tostr__ in order to convert them between
string and internal representations.
#
# with Tcl 8.5
# ============
set a [pi 20]
# round returns an integer and 'everything is a string' applies to integers
# whatever big they are
puts [round [mul $a 10000000000]]
#
# the same with Tcl 8.4
# =====================
set a [pi 20]
# bignums (arbitrary length integers) need a conversion hook
set b [fromstr 10000000000]
# round returns a bignum:
# before printing it, we need to convert it with 'tostr'
puts [tostr [round [mul $a $b]]]
# <a name='section9'></a>NAMESPACES AND OTHER PACKAGES
We have not yet discussed about namespaces because we assumed that you had
imported public commands into the global namespace, like this:
namespace import ::math::bigfloat::*
If you matter much about avoiding names conflicts, I considere it should be
resolved by the following :
package require math::bigfloat
# beware: namespace ensembles are not available in Tcl 8.4
namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat}
# from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands
set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]]
puts [bigfloat tostr $a]
# <a name='section10'></a>EXAMPLES
Guess what happens when you are doing some astronomy. Here is an example :
# convert acurrate angles with a millisecond-rated accuracy
proc degree-angle {degrees minutes seconds milliseconds} {
set result 0
set div 1
foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] {
# we convert each entry var into milliseconds
set div [expr {$div*$factor}]
incr result [expr {$var*$div}]
}
return [div [int2float $result] $div]
}
# load the package
package require math::bigfloat
namespace import ::math::bigfloat::*
# work with angles : a standard formula for navigation (taking bearings)
set angle1 [deg2rad [degree-angle 20 30 40 0]]
set angle2 [deg2rad [degree-angle 21 0 50 500]]
set opposite3 [deg2rad [degree-angle 51 0 50 500]]
set sinProduct [mul [sin $angle1] [sin $angle2]]
set cosProduct [mul [cos $angle1] [cos $angle2]]
set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]]
puts "angle3 : [tostr [rad2deg $angle3]]"
# <a name='section11'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: bignum :: float* 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.
# <a name='keywords'></a>KEYWORDS
[computations](../../../../index.md#computations),
[floating-point](../../../../index.md#floating_point),
[interval](../../../../index.md#interval), [math](../../../../index.md#math),
[multiprecision](../../../../index.md#multiprecision),
[tcl](../../../../index.md#tcl)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2008, by Stephane Arnold <stephanearnold at yahoo dot fr>
|
Added embedded/md/tcllib/files/modules/math/bignum.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
[//000000001]: # (math::bignum - Tcl Math Library)
[//000000002]: # (Generated from file 'bignum.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::bignum(n) 3.1 tcllib "Tcl Math Library")
# NAME
math::bignum - Arbitrary precision integer numbers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require math::bignum ?3.1?
[__::math::bignum::fromstr__ *string* ?*radix*?](#1)
[__::math::bignum::tostr__ *bignum* ?*radix*?](#2)
[__::math::bignum::sign__ *bignum*](#3)
[__::math::bignum::abs__ *bignum*](#4)
[__::math::bignum::cmp__ *a* *b*](#5)
[__::math::bignum::iszero__ *bignum*](#6)
[__::math::bignum::lt__ *a* *b*](#7)
[__::math::bignum::le__ *a* *b*](#8)
[__::math::bignum::gt__ *a* *b*](#9)
[__::math::bignum::ge__ *a* *b*](#10)
[__::math::bignum::eq__ *a* *b*](#11)
[__::math::bignum::ne__ *a* *b*](#12)
[__::math::bignum::isodd__ *bignum*](#13)
[__::math::bignum::iseven__ *bignum*](#14)
[__::math::bignum::add__ *a* *b*](#15)
[__::math::bignum::sub__ *a* *b*](#16)
[__::math::bignum::mul__ *a* *b*](#17)
[__::math::bignum::divqr__ *a* *b*](#18)
[__::math::bignum::div__ *a* *b*](#19)
[__::math::bignum::rem__ *a* *b*](#20)
[__::math::bignum::mod__ *n* *m*](#21)
[__::math::bignum::pow__ *base* *exp*](#22)
[__::math::bignum::powm__ *base* *exp* *m*](#23)
[__::math::bignum::sqrt__ *bignum*](#24)
[__::math::bignum::rand__ *bits*](#25)
[__::math::bignum::lshift__ *bignum* *bits*](#26)
[__::math::bignum::rshift__ *bignum* *bits*](#27)
[__::math::bignum::bitand__ *a* *b*](#28)
[__::math::bignum::bitor__ *a* *b*](#29)
[__::math::bignum::bitxor__ *a* *b*](#30)
[__::math::bignum::setbit__ *bignumVar* *bit*](#31)
[__::math::bignum::clearbit__ *bignumVar* *bit*](#32)
[__::math::bignum::testbit__ *bignum* *bit*](#33)
[__::math::bignum::bits__ *bignum*](#34)
# <a name='description'></a>DESCRIPTION
The bignum package provides arbitrary precision integer math (also known as "big
numbers") capabilities to the Tcl language. Big numbers are internally
represented at Tcl lists: this package provides a set of procedures operating
against the internal representation in order to:
- perform math operations
- convert bignums from the internal representation to a string in the desired
radix and vice versa.
But the two constants "0" and "1" are automatically converted to the internal
representation, in order to easily compare a number to zero, or increment a big
number.
The bignum interface is opaque, so operations on bignums that are not returned
by procedures in this package (but created by hand) may lead to unspecified
behaviours. It's safe to treat bignums as pure values, so there is no need to
free a bignum, or to duplicate it via a special operation.
# <a name='section2'></a>EXAMPLES
This section shows some simple example. This library being just a way to perform
math operations, examples may be the simplest way to learn how to work with it.
Consult the API section of this man page for information about individual
procedures.
package require math::bignum
# Multiplication of two bignums
set a [::math::bignum::fromstr 88888881111111]
set b [::math::bignum::fromstr 22222220000000]
set c [::math::bignum::mul $a $b]
puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000
set c [::math::bignum::sqrt $c]
puts [::math::bignum::tostr $c] ; # => will output 44444440277777
# From/To string conversion in different radix
set a [::math::bignum::fromstr 1100010101010111001001111010111 2]
puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7
# Factorial example
proc fact n {
# fromstr is not needed for 0 and 1
set z 1
for {set i 2} {$i <= $n} {incr i} {
set z [::math::bignum::mul $z [::math::bignum::fromstr $i]]
}
return $z
}
puts [::math::bignum::tostr [fact 100]]
# <a name='section3'></a>API
- <a name='1'></a>__::math::bignum::fromstr__ *string* ?*radix*?
Convert *string* into a bignum. If *radix* is omitted or zero, the string is
interpreted in hex if prefixed with *0x*, in octal if prefixed with *ox*, in
binary if it's pefixed with *bx*, as a number in radix 10 otherwise. If
instead the *radix* argument is specified in the range 2-36, the *string* is
interpreted in the given radix. Please note that this conversion is not
needed for two constants : *0* and *1*. (see the example)
- <a name='2'></a>__::math::bignum::tostr__ *bignum* ?*radix*?
Convert *bignum* into a string representing the number in the specified
radix. If *radix* is omitted, the default is 10.
- <a name='3'></a>__::math::bignum::sign__ *bignum*
Return the sign of the bignum. The procedure returns 0 if the number is
positive, 1 if it's negative.
- <a name='4'></a>__::math::bignum::abs__ *bignum*
Return the absolute value of the bignum.
- <a name='5'></a>__::math::bignum::cmp__ *a* *b*
Compare the two bignums a and b, returning *0* if *a == b*, *1* if *a > b*,
and *-1* if *a < b*.
- <a name='6'></a>__::math::bignum::iszero__ *bignum*
Return true if *bignum* value is zero, otherwise false is returned.
- <a name='7'></a>__::math::bignum::lt__ *a* *b*
Return true if *a < b*, otherwise false is returned.
- <a name='8'></a>__::math::bignum::le__ *a* *b*
Return true if *a <= b*, otherwise false is returned.
- <a name='9'></a>__::math::bignum::gt__ *a* *b*
Return true if *a > b*, otherwise false is returned.
- <a name='10'></a>__::math::bignum::ge__ *a* *b*
Return true if *a >= b*, otherwise false is returned.
- <a name='11'></a>__::math::bignum::eq__ *a* *b*
Return true if *a == b*, otherwise false is returned.
- <a name='12'></a>__::math::bignum::ne__ *a* *b*
Return true if *a != b*, otherwise false is returned.
- <a name='13'></a>__::math::bignum::isodd__ *bignum*
Return true if *bignum* is odd.
- <a name='14'></a>__::math::bignum::iseven__ *bignum*
Return true if *bignum* is even.
- <a name='15'></a>__::math::bignum::add__ *a* *b*
Return the sum of the two bignums *a* and *b*.
- <a name='16'></a>__::math::bignum::sub__ *a* *b*
Return the difference of the two bignums *a* and *b*.
- <a name='17'></a>__::math::bignum::mul__ *a* *b*
Return the product of the two bignums *a* and *b*. The implementation uses
Karatsuba multiplication if both the numbers are bigger than a given
threshold, otherwise the direct algorith is used.
- <a name='18'></a>__::math::bignum::divqr__ *a* *b*
Return a two-elements list containing as first element the quotient of the
division between the two bignums *a* and *b*, and the remainder of the
division as second element.
- <a name='19'></a>__::math::bignum::div__ *a* *b*
Return the quotient of the division between the two bignums *a* and *b*.
- <a name='20'></a>__::math::bignum::rem__ *a* *b*
Return the remainder of the division between the two bignums *a* and *b*.
- <a name='21'></a>__::math::bignum::mod__ *n* *m*
Return *n* modulo *m*. This operation is called modular reduction.
- <a name='22'></a>__::math::bignum::pow__ *base* *exp*
Return *base* raised to the exponent *exp*.
- <a name='23'></a>__::math::bignum::powm__ *base* *exp* *m*
Return *base* raised to the exponent *exp*, modulo *m*. This function is
often used in the field of cryptography.
- <a name='24'></a>__::math::bignum::sqrt__ *bignum*
Return the integer part of the square root of *bignum*
- <a name='25'></a>__::math::bignum::rand__ *bits*
Return a random number of at most *bits* bits. The returned number is
internally generated using Tcl's *expr rand()* function and is not suitable
where an unguessable and cryptographically secure random number is needed.
- <a name='26'></a>__::math::bignum::lshift__ *bignum* *bits*
Return the result of left shifting *bignum*'s binary representation of
*bits* positions on the left. This is equivalent to multiplying by 2^*bits*
but much faster.
- <a name='27'></a>__::math::bignum::rshift__ *bignum* *bits*
Return the result of right shifting *bignum*'s binary representation of
*bits* positions on the right. This is equivalent to dividing by *2^bits*
but much faster.
- <a name='28'></a>__::math::bignum::bitand__ *a* *b*
Return the result of doing a bitwise AND operation on a and b. The operation
is restricted to positive numbers, including zero. When negative numbers are
provided as arguments the result is undefined.
- <a name='29'></a>__::math::bignum::bitor__ *a* *b*
Return the result of doing a bitwise OR operation on a and b. The operation
is restricted to positive numbers, including zero. When negative numbers are
provided as arguments the result is undefined.
- <a name='30'></a>__::math::bignum::bitxor__ *a* *b*
Return the result of doing a bitwise XOR operation on a and b. The operation
is restricted to positive numbers, including zero. When negative numbers are
provided as arguments the result is undefined.
- <a name='31'></a>__::math::bignum::setbit__ *bignumVar* *bit*
Set the bit at *bit* position to 1 in the bignum stored in the variable
*bignumVar*. Bit 0 is the least significant.
- <a name='32'></a>__::math::bignum::clearbit__ *bignumVar* *bit*
Set the bit at *bit* position to 0 in the bignum stored in the variable
*bignumVar*. Bit 0 is the least significant.
- <a name='33'></a>__::math::bignum::testbit__ *bignum* *bit*
Return true if the bit at the *bit* position of *bignum* is on, otherwise
false is returned. If *bit* is out of range, it is considered as set to
zero.
- <a name='34'></a>__::math::bignum::bits__ *bignum*
Return the number of bits needed to represent bignum in radix 2.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: bignum* 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.
# <a name='keywords'></a>KEYWORDS
[bignums](../../../../index.md#bignums), [math](../../../../index.md#math),
[multiprecision](../../../../index.md#multiprecision),
[tcl](../../../../index.md#tcl)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Salvatore Sanfilippo <antirez at invece dot org>
Copyright © 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net>
|
Added embedded/md/tcllib/files/modules/math/calculus.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
|
[//000000001]: # (math::calculus - Tcl Math Library)
[//000000002]: # (Generated from file 'calculus.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::calculus(n) 0.8.2 tcllib "Tcl Math Library")
# NAME
math::calculus - Integration and ordinary differential equations
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [EXAMPLES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require math::calculus 0.8.2
[__::math::calculus::integral__ *begin* *end* *nosteps* *func*](#1)
[__::math::calculus::integralExpr__ *begin* *end* *nosteps* *expression*](#2)
[__::math::calculus::integral2D__ *xinterval* *yinterval* *func*](#3)
[__::math::calculus::integral2D_accurate__ *xinterval* *yinterval* *func*](#4)
[__::math::calculus::integral3D__ *xinterval* *yinterval* *zinterval* *func*](#5)
[__::math::calculus::integral3D_accurate__ *xinterval* *yinterval* *zinterval* *func*](#6)
[__::math::calculus::qk15__ *xstart* *xend* *func* *nosteps*](#7)
[__::math::calculus::qk15_detailed__ *xstart* *xend* *func* *nosteps*](#8)
[__::math::calculus::eulerStep__ *t* *tstep* *xvec* *func*](#9)
[__::math::calculus::heunStep__ *t* *tstep* *xvec* *func*](#10)
[__::math::calculus::rungeKuttaStep__ *t* *tstep* *xvec* *func*](#11)
[__::math::calculus::boundaryValueSecondOrder__ *coeff_func* *force_func* *leftbnd* *rightbnd* *nostep*](#12)
[__::math::calculus::solveTriDiagonal__ *acoeff* *bcoeff* *ccoeff* *dvalue*](#13)
[__::math::calculus::newtonRaphson__ *func* *deriv* *initval*](#14)
[__::math::calculus::newtonRaphsonParameters__ *maxiter* *tolerance*](#15)
[__::math::calculus::regula_falsi__ *f* *xb* *xe* *eps*](#16)
# <a name='description'></a>DESCRIPTION
This package implements several simple mathematical algorithms:
- The integration of a function over an interval
- The numerical integration of a system of ordinary differential equations.
- Estimating the root(s) of an equation of one variable.
The package is fully implemented in Tcl. No particular attention has been paid
to the accuracy of the calculations. Instead, well-known algorithms have been
used in a straightforward manner.
This document describes the procedures and explains their usage.
# <a name='section2'></a>PROCEDURES
This package defines the following public procedures:
- <a name='1'></a>__::math::calculus::integral__ *begin* *end* *nosteps* *func*
Determine the integral of the given function using the Simpson rule. The
interval for the integration is [*begin*, *end*]. The remaining arguments
are:
* *nosteps*
Number of steps in which the interval is divided.
* *func*
Function to be integrated. It should take one single argument.
- <a name='2'></a>__::math::calculus::integralExpr__ *begin* *end* *nosteps* *expression*
Similar to the previous proc, this one determines the integral of the given
*expression* using the Simpson rule. The interval for the integration is
[*begin*, *end*]. The remaining arguments are:
* *nosteps*
Number of steps in which the interval is divided.
* *expression*
Expression to be integrated. It should use the variable "x" as the only
variable (the "integrate")
- <a name='3'></a>__::math::calculus::integral2D__ *xinterval* *yinterval* *func*
- <a name='4'></a>__::math::calculus::integral2D_accurate__ *xinterval* *yinterval* *func*
The commands __integral2D__ and __integral2D_accurate__ calculate the
integral of a function of two variables over the rectangle given by the
first two arguments, each a list of three items, the start and stop interval
for the variable and the number of steps.
The command __integral2D__ evaluates the function at the centre of each
rectangle, whereas the command __integral2D_accurate__ uses a four-point
quadrature formula. This results in an exact integration of polynomials of
third degree or less.
The function must take two arguments and return the function value.
- <a name='5'></a>__::math::calculus::integral3D__ *xinterval* *yinterval* *zinterval* *func*
- <a name='6'></a>__::math::calculus::integral3D_accurate__ *xinterval* *yinterval* *zinterval* *func*
The commands __integral3D__ and __integral3D_accurate__ are the
three-dimensional equivalent of __integral2D__ and __integral3D_accurate__.
The function *func* takes three arguments and is integrated over the block
in 3D space given by three intervals.
- <a name='7'></a>__::math::calculus::qk15__ *xstart* *xend* *func* *nosteps*
Determine the integral of the given function using the Gauss-Kronrod 15
points quadrature rule. The returned value is the estimate of the integral
over the interval [*xstart*, *xend*]. The remaining arguments are:
* *func*
Function to be integrated. It should take one single argument.
* ?nosteps?
Number of steps in which the interval is divided. Defaults to 1.
- <a name='8'></a>__::math::calculus::qk15_detailed__ *xstart* *xend* *func* *nosteps*
Determine the integral of the given function using the Gauss-Kronrod 15
points quadrature rule. The interval for the integration is [*xstart*,
*xend*]. The procedure returns a list of four values:
The estimate of the integral over the specified interval (I).
An estimate of the absolute error in I.
The estimate of the integral of the absolute value of the function over the
interval.
The estimate of the integral of the absolute value of the function minus its
mean over the interval.
The remaining arguments are:
* *func*
Function to be integrated. It should take one single argument.
* ?nosteps?
Number of steps in which the interval is divided. Defaults to 1.
- <a name='9'></a>__::math::calculus::eulerStep__ *t* *tstep* *xvec* *func*
Set a single step in the numerical integration of a system of differential
equations. The method used is Euler's.
* *t*
Value of the independent variable (typically time) at the beginning of
the step.
* *tstep*
Step size for the independent variable.
* *xvec*
List (vector) of dependent values
* *func*
Function of t and the dependent values, returning a list of the
derivatives of the dependent values. (The lengths of xvec and the return
value of "func" must match).
- <a name='10'></a>__::math::calculus::heunStep__ *t* *tstep* *xvec* *func*
Set a single step in the numerical integration of a system of differential
equations. The method used is Heun's.
* *t*
Value of the independent variable (typically time) at the beginning of
the step.
* *tstep*
Step size for the independent variable.
* *xvec*
List (vector) of dependent values
* *func*
Function of t and the dependent values, returning a list of the
derivatives of the dependent values. (The lengths of xvec and the return
value of "func" must match).
- <a name='11'></a>__::math::calculus::rungeKuttaStep__ *t* *tstep* *xvec* *func*
Set a single step in the numerical integration of a system of differential
equations. The method used is Runge-Kutta 4th order.
* *t*
Value of the independent variable (typically time) at the beginning of
the step.
* *tstep*
Step size for the independent variable.
* *xvec*
List (vector) of dependent values
* *func*
Function of t and the dependent values, returning a list of the
derivatives of the dependent values. (The lengths of xvec and the return
value of "func" must match).
- <a name='12'></a>__::math::calculus::boundaryValueSecondOrder__ *coeff_func* *force_func* *leftbnd* *rightbnd* *nostep*
Solve a second order linear differential equation with boundary values at
two sides. The equation has to be of the form (the "conservative" form):
d dy d
-- A(x)-- + -- B(x)y + C(x)y = D(x)
dx dx dx
Ordinarily, such an equation would be written as:
d2y dy
a(x)--- + b(x)-- + c(x) y = D(x)
dx2 dx
The first form is easier to discretise (by integrating over a finite volume)
than the second form. The relation between the two forms is fairly
straightforward:
A(x) = a(x)
B(x) = b(x) - a'(x)
C(x) = c(x) - B'(x) = c(x) - b'(x) + a''(x)
Because of the differentiation, however, it is much easier to ask the user
to provide the functions A, B and C directly.
* *coeff_func*
Procedure returning the three coefficients (A, B, C) of the equation,
taking as its one argument the x-coordinate.
* *force_func*
Procedure returning the right-hand side (D) as a function of the
x-coordinate.
* *leftbnd*
A list of two values: the x-coordinate of the left boundary and the
value at that boundary.
* *rightbnd*
A list of two values: the x-coordinate of the right boundary and the
value at that boundary.
* *nostep*
Number of steps by which to discretise the interval. The procedure
returns a list of x-coordinates and the approximated values of the
solution.
- <a name='13'></a>__::math::calculus::solveTriDiagonal__ *acoeff* *bcoeff* *ccoeff* *dvalue*
Solve a system of linear equations Ax = b with A a tridiagonal matrix.
Returns the solution as a list.
* *acoeff*
List of values on the lower diagonal
* *bcoeff*
List of values on the main diagonal
* *ccoeff*
List of values on the upper diagonal
* *dvalue*
List of values on the righthand-side
- <a name='14'></a>__::math::calculus::newtonRaphson__ *func* *deriv* *initval*
Determine the root of an equation given by
func(x) = 0
using the method of Newton-Raphson. The procedure takes the following
arguments:
* *func*
Procedure that returns the value the function at x
* *deriv*
Procedure that returns the derivative of the function at x
* *initval*
Initial value for x
- <a name='15'></a>__::math::calculus::newtonRaphsonParameters__ *maxiter* *tolerance*
Set the numerical parameters for the Newton-Raphson method:
* *maxiter*
Maximum number of iteration steps (defaults to 20)
* *tolerance*
Relative precision (defaults to 0.001)
- <a name='16'></a>__::math::calculus::regula_falsi__ *f* *xb* *xe* *eps*
Return an estimate of the zero or one of the zeros of the function contained
in the interval [xb,xe]. The error in this estimate is of the order of
eps*abs(xe-xb), the actual error may be slightly larger.
The method used is the so-called *regula falsi* or *false position* method.
It is a straightforward implementation. The method is robust, but requires
that the interval brackets a zero or at least an uneven number of zeros, so
that the value of the function at the start has a different sign than the
value at the end.
In contrast to Newton-Raphson there is no need for the computation of the
function's derivative.
* command *f*
Name of the command that evaluates the function for which the zero is to
be returned
* float *xb*
Start of the interval in which the zero is supposed to lie
* float *xe*
End of the interval
* float *eps*
Relative allowed error (defaults to 1.0e-4)
*Notes:*
Several of the above procedures take the *names* of procedures as arguments. To
avoid problems with the *visibility* of these procedures, the fully-qualified
name of these procedures is determined inside the calculus routines. For the
user this has only one consequence: the named procedure must be visible in the
calling procedure. For instance:
namespace eval ::mySpace {
namespace export calcfunc
proc calcfunc { x } { return $x }
}
#
# Use a fully-qualified name
#
namespace eval ::myCalc {
proc detIntegral { begin end } {
return [integral $begin $end 100 ::mySpace::calcfunc]
}
}
#
# Import the name
#
namespace eval ::myCalc {
namespace import ::mySpace::calcfunc
proc detIntegral { begin end } {
return [integral $begin $end 100 calcfunc]
}
}
Enhancements for the second-order boundary value problem:
- Other types of boundary conditions (zero gradient, zero flux)
- Other schematisation of the first-order term (now central differences are
used, but upstream differences might be useful too).
# <a name='section3'></a>EXAMPLES
Let us take a few simple examples:
Integrate x over the interval [0,100] (20 steps):
proc linear_func { x } { return $x }
puts "Integral: [::math::calculus::integral 0 100 20 linear_func]"
For simple functions, the alternative could be:
puts "Integral: [::math::calculus::integralExpr 0 100 20 {$x}]"
Do not forget the braces!
The differential equation for a dampened oscillator:
x'' + rx' + wx = 0
can be split into a system of first-order equations:
x' = y
y' = -ry - wx
Then this system can be solved with code like this:
proc dampened_oscillator { t xvec } {
set x [lindex $xvec 0]
set x1 [lindex $xvec 1]
return [list $x1 [expr {-$x1-$x}]]
}
set xvec { 1.0 0.0 }
set t 0.0
set tstep 0.1
for { set i 0 } { $i < 20 } { incr i } {
set result [::math::calculus::eulerStep $t $tstep $xvec dampened_oscillator]
puts "Result ($t): $result"
set t [expr {$t+$tstep}]
set xvec $result
}
Suppose we have the boundary value problem:
Dy'' + ky = 0
x = 0: y = 1
x = L: y = 0
This boundary value problem could originate from the diffusion of a decaying
substance.
It can be solved with the following fragment:
proc coeffs { x } { return [list $::Diff 0.0 $::decay] }
proc force { x } { return 0.0 }
set Diff 1.0e-2
set decay 0.0001
set length 100.0
set y [::math::calculus::boundaryValueSecondOrder \
coeffs force {0.0 1.0} [list $length 0.0] 100]
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: calculus* 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.
# <a name='see-also'></a>SEE ALSO
romberg
# <a name='keywords'></a>KEYWORDS
[calculus](../../../../index.md#calculus), [differential
equations](../../../../index.md#differential_equations),
[integration](../../../../index.md#integration),
[math](../../../../index.md#math), [roots](../../../../index.md#roots)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002,2003,2004 Arjen Markus
|
Added embedded/md/tcllib/files/modules/math/combinatorics.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
[//000000001]: # (math::combinatorics - Tcl Math Library)
[//000000002]: # (Generated from file 'combinatorics.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::combinatorics(n) 1.2.3 tcllib "Tcl Math Library")
# NAME
math::combinatorics - Combinatorial functions in the Tcl Math Library
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require math ?1.2.3?
[__::math::ln_Gamma__ *z*](#1)
[__::math::factorial__ *x*](#2)
[__::math::choose__ *n k*](#3)
[__::math::Beta__ *z w*](#4)
# <a name='description'></a>DESCRIPTION
The __[math](math.md)__ package contains implementations of several functions
useful in combinatorial problems.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::math::ln_Gamma__ *z*
Returns the natural logarithm of the Gamma function for the argument *z*.
The Gamma function is defined as the improper integral from zero to positive
infinity of
t**(x-1)*exp(-t) dt
The approximation used in the Tcl Math Library is from Lanczos, *ISIAM J.
Numerical Analysis, series B,* volume 1, p. 86. For "__x__ > 1", the
absolute error of the result is claimed to be smaller than 5.5*10**-10 --
that is, the resulting value of Gamma when
exp( ln_Gamma( x) )
is computed is expected to be precise to better than nine significant
figures.
- <a name='2'></a>__::math::factorial__ *x*
Returns the factorial of the argument *x*.
For integer *x*, 0 <= *x* <= 12, an exact integer result is returned.
For integer *x*, 13 <= *x* <= 21, an exact floating-point result is returned
on machines with IEEE floating point.
For integer *x*, 22 <= *x* <= 170, the result is exact to 1 ULP.
For real *x*, *x* >= 0, the result is approximated by computing *Gamma(x+1)*
using the __::math::ln_Gamma__ function, and the result is expected to be
precise to better than nine significant figures.
It is an error to present *x* <= -1 or *x* > 170, or a value of *x* that is
not numeric.
- <a name='3'></a>__::math::choose__ *n k*
Returns the binomial coefficient *C(n, k)*
C(n,k) = n! / k! (n-k)!
If both parameters are integers and the result fits in 32 bits, the result
is rounded to an integer.
Integer results are exact up to at least *n* = 34. Floating point results
are precise to better than nine significant figures.
- <a name='4'></a>__::math::Beta__ *z w*
Returns the Beta function of the parameters *z* and *w*.
Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w)
Results are returned as a floating point number precise to better than nine
significant digits provided that *w* and *z* are both at least 1.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math* 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.
# <a name='category'></a>CATEGORY
Mathematics
|
Added embedded/md/tcllib/files/modules/math/constants.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
[//000000001]: # (math::constants - Tcl Math Library)
[//000000002]: # (Generated from file 'constants.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::constants(n) 1.0.2 tcllib "Tcl Math Library")
# NAME
math::constants - Mathematical and numerical constants
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [Constants](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.3?
package require math::constants ?1.0.2?
[__::math::constants::constants__ *args*](#1)
[__::math::constants::print-constants__ *args*](#2)
# <a name='description'></a>DESCRIPTION
This package defines some common mathematical and numerical constants. By using
the package you get consistent values for numbers like pi and ln(10).
It defines two commands:
- One for importing the constants
- One for reporting which constants are defined and what values they actually
have.
The motivation for this package is that quite often, with (mathematical)
computations, you need a good approximation to, say, the ratio of degrees to
radians. You can, of course, define this like:
variable radtodeg [expr {180.0/(4.0*atan(1.0))}]
and use the variable radtodeg whenever you need the conversion.
This has two drawbacks:
- You need to remember the proper formula or value and that is error-prone.
- Especially with the use of mathematical functions like *atan* you assume
that they have been accurately implemented. This is seldom or never the case
and for each platform you can get subtle differences.
Here is the way you can do it with the *math::constants* package:
package require math::constants
::math::constants::constants radtodeg degtorad
which creates two variables, radtodeg and (its reciprocal) degtorad in the
calling namespace.
Constants that have been defined (their values are mostly taken from
mathematical tables with more precision than usually can be handled) include:
- basic constants like pi, e, gamma (Euler's constant)
- derived values like ln(10) and sqrt(2)
- purely numerical values such as 1/3 that are included for convenience and
for the fact that certain seemingly trivial computations like:
set value [expr {3.0*$onethird}]
give *exactly* the value you expect (if IEEE arithmetic is available).
The full set of named constants is listed in section [Constants](#section3).
# <a name='section2'></a>PROCEDURES
The package defines the following public procedures:
- <a name='1'></a>__::math::constants::constants__ *args*
Import the constants whose names are given as arguments
- <a name='2'></a>__::math::constants::print-constants__ *args*
Print the constants whose names are given as arguments on the screen (name,
value and description) or, if no arguments are given, print all defined
constants. This is mainly a convenience procedure.
# <a name='section3'></a>Constants
- __pi__
Ratio of circle circumference to diameter
- __e__
Base for natural logarithm
- __ln10__
Natural logarithm of 10
- __phi__
Golden ratio
- __gamma__
Euler's constant
- __sqrt2__
Square root of 2
- __thirdrt2__
One-third power of 2
- __sqrt3__
Square root of 3
- __radtodeg__
Conversion from radians to degrees
- __degtorad__
Conversion from degrees to radians
- __onethird__
One third (0.3333....)
- __twothirds__
Two thirds (0.6666....)
- __onesixth__
One sixth (0.1666....)
- __huge__
(Approximately) largest number
- __tiny__
(Approximately) smallest number not equal zero
- __eps__
Smallest number such that 1+eps != 1
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: constants* 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.
# <a name='keywords'></a>KEYWORDS
[constants](../../../../index.md#constants),
[degrees](../../../../index.md#degrees), [e](../../../../index.md#e),
[math](../../../../index.md#math), [pi](../../../../index.md#pi),
[radians](../../../../index.md#radians)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/decimal.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
[//000000001]: # (math::decimal - Tcl Decimal Arithmetic Library)
[//000000002]: # (Generated from file 'decimal.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::decimal(n) 1.0.3 tcllib "Tcl Decimal Arithmetic Library")
# NAME
math::decimal - General decimal arithmetic
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.5?
package require math::decimal 1.0.3
[__::math::decimal::fromstr__ *string*](#1)
[__::math::decimal::tostr__ *decimal*](#2)
[__::math::decimal::setVariable__ *variable* *setting*](#3)
[__::math::decimal::add__ *a* *b*](#4)
[__::math::decimal::+__ *a* *b*](#5)
[__::math::decimal::subtract__ *a* *b*](#6)
[__::math::decimal::-__ *a* *b*](#7)
[__::math::decimal::multiply__ *a* *b*](#8)
[__::math::decimal::*__ *a* *b*](#9)
[__::math::decimal::divide__ *a* *b*](#10)
[__::math::decimal::/__ *a* *b*](#11)
[__::math::decimal::divideint__ *a* *b*](#12)
[__::math::decimal::remainder__ *a* *b*](#13)
[__::math::decimal::abs__ *decimal*](#14)
[__::math::decimal::compare__ *a* *b*](#15)
[__::math::decimal::max__ *a* *b*](#16)
[__::math::decimal::maxmag__ *a* *b*](#17)
[__::math::decimal::min__ *a* *b*](#18)
[__::math::decimal::minmag__ *a* *b*](#19)
[__::math::decimal::plus__ *a*](#20)
[__::math::decimal::minus__ *a*](#21)
[__::math::decimal::copynegate__ *a*](#22)
[__::math::decimal::copysign__ *a* *b*](#23)
[__::math::decimal::is-signed__ *decimal*](#24)
[__::math::decimal::is-zero__ *decimal*](#25)
[__::math::decimal::is-NaN__ *decimal*](#26)
[__::math::decimal::is-infinite__ *decimal*](#27)
[__::math::decimal::is-finite__ *decimal*](#28)
[__::math::decimal::fma__ *a* *b* *c*](#29)
[__::math::decimal::round_half_even__ *decimal* *digits*](#30)
[__::math::decimal::round_half_up__ *decimal* *digits*](#31)
[__::math::decimal::round_half_down__ *decimal* *digits*](#32)
[__::math::decimal::round_down__ *decimal* *digits*](#33)
[__::math::decimal::round_up__ *decimal* *digits*](#34)
[__::math::decimal::round_floor__ *decimal* *digits*](#35)
[__::math::decimal::round_ceiling__ *decimal* *digits*](#36)
[__::math::decimal::round_05up__ *decimal* *digits*](#37)
# <a name='description'></a>DESCRIPTION
The decimal package provides decimal arithmetic support for both limited
precision floating point and arbitrary precision floating point. Additionally,
integer arithmetic is supported.
More information and the specifications on which this package depends can be
found on the general decimal arithmetic page at http://speleotrove.com/decimal
This package provides for:
- A new data type decimal which is represented as a list containing sign,
mantissa and exponent.
- Arithmetic operations on those decimal numbers such as addition,
subtraction, multiplication, etc...
Numbers are converted to decimal format using the operation
::math::decimal::fromstr.
Numbers are converted back to string format using the operation
::math::decimal::tostr.
# <a name='section2'></a>EXAMPLES
This section shows some simple examples. Since the purpose of this library is to
perform decimal math operations, examples may be the simplest way to learn how
to work with it and to see the difference between using this package and
sticking with expr. Consult the API section of this man page for information
about individual procedures.
package require math::decimal
# Various operations on two numbers.
# We first convert them to decimal format.
set a [::math::decimal::fromstr 8.2]
set b [::math::decimal::fromstr .2]
# Then we perform our operations. Here we add
set c [::math::decimal::+ $a $b]
# Finally we convert back to string format for presentation to the user.
puts [::math::decimal::tostr $c] ; # => will output 8.4
# Other examples
#
# Subtraction
set c [::math::decimal::- $a $b]
puts [::math::decimal::tostr $c] ; # => will output 8.0
# Why bother using this instead of simply expr?
puts [expr {8.2 + .2}] ; # => will output 8.399999999999999
puts [expr {8.2 - .2}] ; # => will output 7.999999999999999
# See http://speleotrove.com/decimal to learn more about why this happens.
# <a name='section3'></a>API
- <a name='1'></a>__::math::decimal::fromstr__ *string*
Convert *string* into a decimal.
- <a name='2'></a>__::math::decimal::tostr__ *decimal*
Convert *decimal* into a string representing the number in base 10.
- <a name='3'></a>__::math::decimal::setVariable__ *variable* *setting*
Sets the *variable* to *setting*. Valid variables are:
*rounding* - Method of rounding to use during rescale. Valid methods are
round_half_even, round_half_up, round_half_down, round_down, round_up,
round_floor, round_ceiling.
*precision* - Maximum number of digits allowed in mantissa.
*extended* - Set to 1 for extended mode. 0 for simplified mode.
*maxExponent* - Maximum value for the exponent. Defaults to 999.
*minExponent* - Minimum value for the exponent. Default to -998.
- <a name='4'></a>__::math::decimal::add__ *a* *b*
- <a name='5'></a>__::math::decimal::+__ *a* *b*
Return the sum of the two decimals *a* and *b*.
- <a name='6'></a>__::math::decimal::subtract__ *a* *b*
- <a name='7'></a>__::math::decimal::-__ *a* *b*
Return the differnece of the two decimals *a* and *b*.
- <a name='8'></a>__::math::decimal::multiply__ *a* *b*
- <a name='9'></a>__::math::decimal::*__ *a* *b*
Return the product of the two decimals *a* and *b*.
- <a name='10'></a>__::math::decimal::divide__ *a* *b*
- <a name='11'></a>__::math::decimal::/__ *a* *b*
Return the quotient of the division between the two decimals *a* and *b*.
- <a name='12'></a>__::math::decimal::divideint__ *a* *b*
Return a the integer portion of the quotient of the division between
decimals *a* and *b*
- <a name='13'></a>__::math::decimal::remainder__ *a* *b*
Return the remainder of the division between the two decimals *a* and *b*.
- <a name='14'></a>__::math::decimal::abs__ *decimal*
Return the absolute value of the decimal.
- <a name='15'></a>__::math::decimal::compare__ *a* *b*
Compare the two decimals a and b, returning *0* if *a == b*, *1* if *a > b*,
and *-1* if *a < b*.
- <a name='16'></a>__::math::decimal::max__ *a* *b*
Compare the two decimals a and b, and return *a* if *a >= b*, and *b* if *a
< b*.
- <a name='17'></a>__::math::decimal::maxmag__ *a* *b*
Compare the two decimals a and b while ignoring their signs, and return *a*
if *abs(a) >= abs(b)*, and *b* if *abs(a) < abs(b)*.
- <a name='18'></a>__::math::decimal::min__ *a* *b*
Compare the two decimals a and b, and return *a* if *a <= b*, and *b* if *a
> b*.
- <a name='19'></a>__::math::decimal::minmag__ *a* *b*
Compare the two decimals a and b while ignoring their signs, and return *a*
if *abs(a) <= abs(b)*, and *b* if *abs(a) > abs(b)*.
- <a name='20'></a>__::math::decimal::plus__ *a*
Return the result from *::math::decimal::+ 0 $a*.
- <a name='21'></a>__::math::decimal::minus__ *a*
Return the result from *::math::decimal::- 0 $a*.
- <a name='22'></a>__::math::decimal::copynegate__ *a*
Returns *a* with the sign flipped.
- <a name='23'></a>__::math::decimal::copysign__ *a* *b*
Returns *a* with the sign set to the sign of the *b*.
- <a name='24'></a>__::math::decimal::is-signed__ *decimal*
Return the sign of the decimal. The procedure returns 0 if the number is
positive, 1 if it's negative.
- <a name='25'></a>__::math::decimal::is-zero__ *decimal*
Return true if *decimal* value is zero, otherwise false is returned.
- <a name='26'></a>__::math::decimal::is-NaN__ *decimal*
Return true if *decimal* value is NaN (not a number), otherwise false is
returned.
- <a name='27'></a>__::math::decimal::is-infinite__ *decimal*
Return true if *decimal* value is Infinite, otherwise false is returned.
- <a name='28'></a>__::math::decimal::is-finite__ *decimal*
Return true if *decimal* value is finite, otherwise false is returned.
- <a name='29'></a>__::math::decimal::fma__ *a* *b* *c*
Return the result from first multiplying *a* by *b* and then adding *c*.
Rescaling only occurs after completion of all operations. In this way the
result may vary from that returned by performing the operations
individually.
- <a name='30'></a>__::math::decimal::round_half_even__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round to the nearest. If equidistant, round so the final digit is
even.
- <a name='31'></a>__::math::decimal::round_half_up__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round to the nearest. If equidistant, round up.
- <a name='32'></a>__::math::decimal::round_half_down__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round to the nearest. If equidistant, round down.
- <a name='33'></a>__::math::decimal::round_down__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round toward 0. (Truncate)
- <a name='34'></a>__::math::decimal::round_up__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round away from 0
- <a name='35'></a>__::math::decimal::round_floor__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round toward -Infinity.
- <a name='36'></a>__::math::decimal::round_ceiling__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round toward Infinity
- <a name='37'></a>__::math::decimal::round_05up__ *decimal* *digits*
Rounds *decimal* to *digits* number of decimal points with the following
rules: Round zero or five away from 0. The same as round-up, except that
rounding up only occurs if the digit to be rounded up is 0 or 5, and after
overflow the result is the same as for round-down.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *decimal* 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.
# <a name='keywords'></a>KEYWORDS
[decimal](../../../../index.md#decimal), [math](../../../../index.md#math),
[tcl](../../../../index.md#tcl)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Mark Alston <mark at beernut dot com>
|
Added embedded/md/tcllib/files/modules/math/exact.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
[//000000001]: # (math::exact - Tcl Math Library)
[//000000002]: # (Generated from file 'exact.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::exact(n) 1.0.1 tcllib "Tcl Math Library")
# NAME
math::exact - Exact Real Arithmetic
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Procedures](#section2)
- [Parameters](#section3)
- [Expressions](#section4)
- [Functions](#section5)
- [Summary](#section6)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require grammar::aycock 1.0
package require math::exact 1.0.1
[__::math::exact::exactexpr__ *expr*](#1)
[*number* __ref__](#2)
[*number* __unref__](#3)
[*number* __asPrint__ *precision*](#4)
[*number* __asFloat__ *precision*](#5)
# <a name='description'></a>DESCRIPTION
The __exactexpr__ command in the __math::exact__ package allows for exact
computations over the computable real numbers. These are not arbitrary-precision
calculations; rather they are exact, with numbers represented by algorithms that
produce successive approximations. At the end of a calculation, the caller can
request a given precision for the end result, and intermediate results are
computed to whatever precision is necessary to satisfy the request.
# <a name='section2'></a>Procedures
The following procedure is the primary entry into the __math::exact__ package.
- <a name='1'></a>__::math::exact::exactexpr__ *expr*
Accepts a mathematical expression in Tcl syntax, and returns an object that
represents the program to calculate successive approximations to the
expression's value. The result will be referred to as an exact real number.
- <a name='2'></a>*number* __ref__
Increases the reference count of a given exact real number.
- <a name='3'></a>*number* __unref__
Decreases the reference count of a given exact real number, and destroys the
number if the reference count is zero.
- <a name='4'></a>*number* __asPrint__ *precision*
Formats the given *number* for printing, with the specified *precision*.
(See below for how *precision* is interpreted). Numbers that are known to be
rational are formatted as fractions.
- <a name='5'></a>*number* __asFloat__ *precision*
Formats the given *number* for printing, with the specified *precision*.
(See below for how *precision* is interpreted). All numbers are formatted in
floating-point E format.
# <a name='section3'></a>Parameters
- *expr*
Expression to evaluate. The syntax for expressions is the same as it is in
Tcl, but the set of operations is smaller. See [Expressions](#section4)
below for details.
- *number*
The object returned by an earlier invocation of __math::exact::exactexpr__
- *precision*
The requested 'precision' of the result. The precision is (approximately)
the absolute value of the binary exponent plus the number of bits of the
binary significand. For instance, to return results to IEEE-754 double
precision, 56 bits plus the exponent are required. Numbers between 1/2 and 2
will require a precision of 57; numbers between 1/4 and 1/2 or between 2 and
4 will require 58; numbers between 1/8 and 1/4 or between 4 and 8 will
require 59; and so on.
# <a name='section4'></a>Expressions
The __math::exact::exactexpr__ command accepts expressions in a subset of Tcl's
syntax. The following components may be used in an expression.
- Decimal integers.
- Variable references with the dollar sign (__$__). The value of the variable
must be the result of another call to __math::exact::exactexpr__. The
reference count of the value will be increased by one for each position at
which it appears in the expression.
- The exponentiation operator (__**__).
- Unary plus (__+__) and minus (__-__) operators.
- Multiplication (__*__) and division (__/__) operators.
- Parentheses used for grouping.
- Functions. See [Functions](#section5) below for the functions that are
available.
# <a name='section5'></a>Functions
The following functions are available for use within exact real expressions.
- __acos(__*x*__)__
The inverse cosine of *x*. The result is expressed in radians. The absolute
value of *x* must be less than 1.
- __acosh(__*x*__)__
The inverse hyperbolic cosine of *x*. *x* must be greater than 1.
- __asin(__*x*__)__
The inverse sine of *x*. The result is expressed in radians. The absolute
value of *x* must be less than 1.
- __asinh(__*x*__)__
The inverse hyperbolic sine of *x*.
- __atan(__*x*__)__
The inverse tangent of *x*. The result is expressed in radians.
- __atanh(__*x*__)__
The inverse hyperbolic tangent of *x*. The absolute value of *x* must be
less than 1.
- __cos(__*x*__)__
The cosine of *x*. *x* is expressed in radians.
- __cosh(__*x*__)__
The hyperbolic cosine of *x*.
- __e()__
The base of the natural logarithms = __2.71828...__
- __exp(__*x*__)__
The exponential function of *x*.
- __log(__*x*__)__
The natural logarithm of *x*. *x* must be positive.
- __pi()__
The value of pi = __3.15159...__
- __sin(__*x*__)__
The sine of *x*. *x* is expressed in radians.
- __sinh(__*x*__)__
The hyperbolic sine of *x*.
- __sqrt(__*x*__)__
The square root of *x*. *x* must be positive.
- __tan(__*x*__)__
The tangent of *x*. *x* is expressed in radians.
- __tanh(__*x*__)__
The hyperbolic tangent of *x*.
# <a name='section6'></a>Summary
The __math::exact::exactexpr__ command provides a system that performs exact
arithmetic over computable real numbers, representing the numbers as algorithms
for successive approximation. An example, which implements the high-school
quadratic formula, is shown below.
namespace import math::exact::exactexpr
proc exactquad {a b c} {
set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref]
set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref]
set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref]
$d unref
return [list $r0 $r1]
}
set a [[exactexpr 1] ref]
set b [[exactexpr 200] ref]
set c [[exactexpr {(-3/2) * 10**-12}] ref]
lassign [exactquad $a $b $c] r0 r1
$a unref; $b unref; $c unref
puts [list [$r0 asFloat 70] [$r1 asFloat 110]]
$r0 unref; $r1 unref
The program prints the result:
-2.000000000000000075e2 7.499999999999999719e-15
Note that if IEEE-754 floating point had been used, a catastrophic roundoff
error would yield a smaller root that is a factor of two too high:
-200.0 1.4210854715202004e-14
The invocations of __exactexpr__ should be fairly self-explanatory. The other
commands of note are __ref__ and __unref__. It is necessary for the caller to
keep track of references to exact expressions - to call __ref__ every time an
exact expression is stored in a variable and __unref__ every time the variable
goes out of scope or is overwritten. The __asFloat__ method emits decimal digits
as long as the requested precision supports them. It terminates when the
requested precision yields an uncertainty of more than one unit in the least
significant digit.
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015 Kevin B. Kenny <[email protected]>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>
|
Added embedded/md/tcllib/files/modules/math/fourier.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
[//000000001]: # (math::fourier - Tcl Math Library)
[//000000002]: # (Generated from file 'fourier.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::fourier(n) 1.0.2 tcllib "Tcl Math Library")
# NAME
math::fourier - Discrete and fast fourier transforms
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [GENERAL INFORMATION](#section2)
- [PROCEDURES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require math::fourier 1.0.2
[__::math::fourier::dft__ *in_data*](#1)
[__::math::fourier::inverse_dft__ *in_data*](#2)
[__::math::fourier::lowpass__ *cutoff* *in_data*](#3)
[__::math::fourier::highpass__ *cutoff* *in_data*](#4)
# <a name='description'></a>DESCRIPTION
The __math::fourier__ package implements two versions of discrete Fourier
transforms, the ordinary transform and the fast Fourier transform. It also
provides a few simple filter procedures as an illustrations of how such filters
can be implemented.
The purpose of this document is to describe the implemented procedures and
provide some examples of their usage. As there is ample literature on the
algorithms involved, we refer to relevant text books for more explanations. We
also refer to the original Wiki page on the subject which describes some of the
considerations behind the current implementation.
# <a name='section2'></a>GENERAL INFORMATION
The two top-level procedures defined are
- dft data-list
- inverse_dft data-list
Both take a list of *complex numbers* and apply a Discrete Fourier Transform
(DFT) or its inverse respectively to these lists of numbers. A "complex number"
in this case is either (i) a pair (two element list) of numbers, interpreted as
the real and imaginary parts of the complex number, or (ii) a single number,
interpreted as the real part of a complex number whose imaginary part is zero.
The return value is always in the first format. (The DFT generally produces
complex results even if the input is purely real.) Applying first one and then
the other of these procedures to a list of complex numbers will (modulo rounding
errors due to floating point arithmetic) return the original list of numbers.
If the input length N is a power of two then these procedures will utilize the
O(N log N) Fast Fourier Transform algorithm. If input length is not a power of
two then the DFT will instead be computed using a the naive quadratic algorithm.
Some examples:
% dft {1 2 3 4}
{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}
% inverse_dft {{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}}
{1.0 0.0} {2.0 0.0} {3.0 0.0} {4.0 0.0}
% dft {1 2 3 4 5}
{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}
% inverse_dft {{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}}
{1.0 0.0} {2.0 8.881784197e-17} {3.0 4.4408920985e-17} {4.0 4.4408920985e-17} {5.0 -8.881784197e-17}
In the last case, the imaginary parts <1e-16 would have been zero in exact
arithmetic, but aren't here due to rounding errors.
Internally, the procedures use a flat list format where every even index element
of a list is a real part and every odd index element is an imaginary part. This
is reflected in the variable names by Re_ and Im_ prefixes.
The package includes two simple filters. They have an analogue equivalent in a
simple electronic circuit, a resistor and a capacitance in series. Using these
filters requires the __[math::complexnumbers](qcomplex.md)__ package.
# <a name='section3'></a>PROCEDURES
The public Fourier transform procedures are:
- <a name='1'></a>__::math::fourier::dft__ *in_data*
Determine the *Fourier transform* of the given list of complex numbers. The
result is a list of complex numbers representing the (complex) amplitudes of
the Fourier components.
* list *in_data*
List of data
- <a name='2'></a>__::math::fourier::inverse_dft__ *in_data*
Determine the *inverse Fourier transform* of the given list of complex
numbers (interpreted as amplitudes). The result is a list of complex numbers
representing the original (complex) data
* list *in_data*
List of data (amplitudes)
- <a name='3'></a>__::math::fourier::lowpass__ *cutoff* *in_data*
Filter the (complex) amplitudes so that high-frequency components are
suppressed. The implemented filter is a first-order low-pass filter, the
discrete equivalent of a simple electronic circuit with a resistor and a
capacitance.
* float *cutoff*
Cut-off frequency
* list *in_data*
List of data (amplitudes)
- <a name='4'></a>__::math::fourier::highpass__ *cutoff* *in_data*
Filter the (complex) amplitudes so that low-frequency components are
suppressed. The implemented filter is a first-order low-pass filter, the
discrete equivalent of a simple electronic circuit with a resistor and a
capacitance.
* float *cutoff*
Cut-off frequency
* list *in_data*
List of data (amplitudes)
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: fourier* 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.
# <a name='keywords'></a>KEYWORDS
[FFT](../../../../index.md#fft), [Fourier
transform](../../../../index.md#fourier_transform), [complex
numbers](../../../../index.md#complex_numbers),
[mathematics](../../../../index.md#mathematics)
# <a name='category'></a>CATEGORY
Mathematics
|
Added embedded/md/tcllib/files/modules/math/fuzzy.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
[//000000001]: # (math::fuzzy - Tcl Math Library)
[//000000002]: # (Generated from file 'fuzzy.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::fuzzy(n) 0.2 tcllib "Tcl Math Library")
# NAME
math::fuzzy - Fuzzy comparison of floating-point numbers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [TEST CASES](#section3)
- [REFERENCES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.3?
package require math::fuzzy ?0.2?
[__::math::fuzzy::teq__ *value1* *value2*](#1)
[__::math::fuzzy::tne__ *value1* *value2*](#2)
[__::math::fuzzy::tge__ *value1* *value2*](#3)
[__::math::fuzzy::tle__ *value1* *value2*](#4)
[__::math::fuzzy::tlt__ *value1* *value2*](#5)
[__::math::fuzzy::tgt__ *value1* *value2*](#6)
[__::math::fuzzy::tfloor__ *value*](#7)
[__::math::fuzzy::tceil__ *value*](#8)
[__::math::fuzzy::tround__ *value*](#9)
[__::math::fuzzy::troundn__ *value* *ndigits*](#10)
# <a name='description'></a>DESCRIPTION
The package Fuzzy is meant to solve common problems with floating-point numbers
in a systematic way:
- Comparing two numbers that are "supposed" to be identical, like 1.0 and
2.1/(1.2+0.9) is not guaranteed to give the intuitive result.
- Rounding a number that is halfway two integer numbers can cause strange
errors, like int(100.0*2.8) != 28 but 27
The Fuzzy package is meant to help sorting out this type of problems by defining
"fuzzy" comparison procedures for floating-point numbers. It does so by allowing
for a small margin that is determined automatically - the margin is three times
the "epsilon" value, that is three times the smallest number *eps* such that 1.0
and 1.0+$eps canbe distinguished. In Tcl, which uses double precision
floating-point numbers, this is typically 1.1e-16.
# <a name='section2'></a>PROCEDURES
Effectively the package provides the following procedures:
- <a name='1'></a>__::math::fuzzy::teq__ *value1* *value2*
Compares two floating-point numbers and returns 1 if their values fall
within a small range. Otherwise it returns 0.
- <a name='2'></a>__::math::fuzzy::tne__ *value1* *value2*
Returns the negation, that is, if the difference is larger than the margin,
it returns 1.
- <a name='3'></a>__::math::fuzzy::tge__ *value1* *value2*
Compares two floating-point numbers and returns 1 if their values either
fall within a small range or if the first number is larger than the second.
Otherwise it returns 0.
- <a name='4'></a>__::math::fuzzy::tle__ *value1* *value2*
Returns 1 if the two numbers are equal according to [teq] or if the first is
smaller than the second.
- <a name='5'></a>__::math::fuzzy::tlt__ *value1* *value2*
Returns the opposite of [tge].
- <a name='6'></a>__::math::fuzzy::tgt__ *value1* *value2*
Returns the opposite of [tle].
- <a name='7'></a>__::math::fuzzy::tfloor__ *value*
Returns the integer number that is lower or equal to the given
floating-point number, within a well-defined tolerance.
- <a name='8'></a>__::math::fuzzy::tceil__ *value*
Returns the integer number that is greater or equal to the given
floating-point number, within a well-defined tolerance.
- <a name='9'></a>__::math::fuzzy::tround__ *value*
Rounds the floating-point number off.
- <a name='10'></a>__::math::fuzzy::troundn__ *value* *ndigits*
Rounds the floating-point number off to the specified number of decimals
(Pro memorie).
Usage:
if { [teq $x $y] } { puts "x == y" }
if { [tne $x $y] } { puts "x != y" }
if { [tge $x $y] } { puts "x >= y" }
if { [tgt $x $y] } { puts "x > y" }
if { [tlt $x $y] } { puts "x < y" }
if { [tle $x $y] } { puts "x <= y" }
set fx [tfloor $x]
set fc [tceil $x]
set rounded [tround $x]
set roundn [troundn $x $nodigits]
# <a name='section3'></a>TEST CASES
The problems that can occur with floating-point numbers are illustrated by the
test cases in the file "fuzzy.test":
- Several test case use the ordinary comparisons, and they fail invariably to
produce understandable results
- One test case uses [expr] without braces ({ and }). It too fails.
The conclusion from this is that any expression should be surrounded by braces,
because otherwise very awkward things can happen if you need accuracy.
Furthermore, accuracy and understandable results are enhanced by using these
"tolerant" or fuzzy comparisons.
Note that besides the Tcl-only package, there is also a C-based version.
# <a name='section4'></a>REFERENCES
Original implementation in Fortran by dr. H.D. Knoble (Penn State University).
P. E. Hagerty, "More on Fuzzy Floor and Ceiling," APL QUOTE QUAD 8(4):20-24,
June 1978. Note that TFLOOR=FL5 took five years of refereed evolution
(publication).
L. M. Breed, "Definitions for Fuzzy Floor and Ceiling", APL QUOTE QUAD
8(3):16-23, March 1978.
D. Knuth, Art of Computer Programming, Vol. 1, Problem 1.2.4-5.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: fuzzy* 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.
# <a name='keywords'></a>KEYWORDS
[floating-point](../../../../index.md#floating_point),
[math](../../../../index.md#math), [rounding](../../../../index.md#rounding)
# <a name='category'></a>CATEGORY
Mathematics
|
Added embedded/md/tcllib/files/modules/math/interpolate.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
|
[//000000001]: # (math::interpolate - Tcl Math Library)
[//000000002]: # (Generated from file 'interpolate.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::interpolate(n) 1.1 tcllib "Tcl Math Library")
# NAME
math::interpolate - Interpolation routines
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [INCOMPATIBILITY WITH VERSION 1.0.3](#section2)
- [PROCEDURES](#section3)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require struct
package require math::interpolate ?1.1?
[__::math::interpolate::defineTable__ *name* *colnames* *values*](#1)
[__::math::interpolate::interp-1d-table__ *name* *xval*](#2)
[__::math::interpolate::interp-table__ *name* *xval* *yval*](#3)
[__::math::interpolate::interp-linear__ *xyvalues* *xval*](#4)
[__::math::interpolate::interp-lagrange__ *xyvalues* *xval*](#5)
[__::math::interpolate::prepare-cubic-splines__ *xcoord* *ycoord*](#6)
[__::math::interpolate::interp-cubic-splines__ *coeffs* *x*](#7)
[__::math::interpolate::interp-spatial__ *xyvalues* *coord*](#8)
[__::math::interpolate::interp-spatial-params__ *max_search* *power*](#9)
[__::math::interpolate::neville__ *xlist* *ylist* *x*](#10)
# <a name='description'></a>DESCRIPTION
This package implements several interpolation algorithms:
- Interpolation into a table (one or two independent variables), this is
useful for example, if the data are static, like with tables of statistical
functions.
- Linear interpolation into a given set of data (organised as (x,y) pairs).
- Lagrange interpolation. This is mainly of theoretical interest, because
there is no guarantee about error bounds. One possible use: if you need a
line or a parabola through given points (it will calculate the values, but
not return the coefficients).
A variation is Neville's method which has better behaviour and error bounds.
- Spatial interpolation using a straightforward distance-weight method. This
procedure allows any number of spatial dimensions and any number of
dependent variables.
- Interpolation in one dimension using cubic splines.
This document describes the procedures and explains their usage.
# <a name='section2'></a>INCOMPATIBILITY WITH VERSION 1.0.3
The interpretation of the tables in the
__::math::interpolate::interpolate-1d-table__ command has been changed to be
compatible with the interpretation for 2D interpolation in the
__::math::interpolate::interpolate-table__ command. As a consequence this
version is incompatible with the previous versions of the command (1.0.x).
# <a name='section3'></a>PROCEDURES
The interpolation package defines the following public procedures:
- <a name='1'></a>__::math::interpolate::defineTable__ *name* *colnames* *values*
Define a table with one or two independent variables (the distinction is
implicit in the data). The procedure returns the name of the table - this
name is used whenever you want to interpolate the values. *Note:* this
procedure is a convenient wrapper for the struct::matrix procedure.
Therefore you can access the data at any location in your program.
* string *name* (in)
Name of the table to be created
* list *colnames* (in)
List of column names
* list *values* (in)
List of values (the number of elements should be a multiple of the
number of columns. See [EXAMPLES](#section4) for more information on the
interpretation of the data.
The values must be sorted with respect to the independent variable(s).
- <a name='2'></a>__::math::interpolate::interp-1d-table__ *name* *xval*
Interpolate into the one-dimensional table "name" and return a list of
values, one for each dependent column.
* string *name* (in)
Name of an existing table
* float *xval* (in)
Value of the independent *row* variable
- <a name='3'></a>__::math::interpolate::interp-table__ *name* *xval* *yval*
Interpolate into the two-dimensional table "name" and return the
interpolated value.
* string *name* (in)
Name of an existing table
* float *xval* (in)
Value of the independent *row* variable
* float *yval* (in)
Value of the independent *column* variable
- <a name='4'></a>__::math::interpolate::interp-linear__ *xyvalues* *xval*
Interpolate linearly into the list of x,y pairs and return the interpolated
value.
* list *xyvalues* (in)
List of pairs of (x,y) values, sorted to increasing x. They are used as
the breakpoints of a piecewise linear function.
* float *xval* (in)
Value of the independent variable for which the value of y must be
computed.
- <a name='5'></a>__::math::interpolate::interp-lagrange__ *xyvalues* *xval*
Use the list of x,y pairs to construct the unique polynomial of lowest
degree that passes through all points and return the interpolated value.
* list *xyvalues* (in)
List of pairs of (x,y) values
* float *xval* (in)
Value of the independent variable for which the value of y must be
computed.
- <a name='6'></a>__::math::interpolate::prepare-cubic-splines__ *xcoord* *ycoord*
Returns a list of coefficients for the second routine *interp-cubic-splines*
to actually interpolate.
* list *xcoord*
List of x-coordinates for the value of the function to be interpolated
is known. The coordinates must be strictly ascending. At least three
points are required.
* list *ycoord*
List of y-coordinates (the values of the function at the given
x-coordinates).
- <a name='7'></a>__::math::interpolate::interp-cubic-splines__ *coeffs* *x*
Returns the interpolated value at coordinate x. The coefficients are
computed by the procedure *prepare-cubic-splines*.
* list *coeffs*
List of coefficients as returned by prepare-cubic-splines
* float *x*
x-coordinate at which to estimate the function. Must be between the
first and last x-coordinate for which values were given.
- <a name='8'></a>__::math::interpolate::interp-spatial__ *xyvalues* *coord*
Use a straightforward interpolation method with weights as function of the
inverse distance to interpolate in 2D and N-dimensional space
The list xyvalues is a list of lists:
{ {x1 y1 z1 {v11 v12 v13 v14}}
{x2 y2 z2 {v21 v22 v23 v24}}
...
}
The last element of each inner list is either a single number or a list in
itself. In the latter case the return value is a list with the same number
of elements.
The method is influenced by the search radius and the power of the inverse
distance
* list *xyvalues* (in)
List of lists, each sublist being a list of coordinates and of dependent
values.
* list *coord* (in)
List of coordinates for which the values must be calculated
- <a name='9'></a>__::math::interpolate::interp-spatial-params__ *max_search* *power*
Set the parameters for spatial interpolation
* float *max_search* (in)
Search radius (data points further than this are ignored)
* integer *power* (in)
Power for the distance (either 1 or 2; defaults to 2)
- <a name='10'></a>__::math::interpolate::neville__ *xlist* *ylist* *x*
Interpolates between the tabulated values of a function whose abscissae are
*xlist* and whose ordinates are *ylist* to produce an estimate for the value
of the function at *x*. The result is a two-element list; the first element
is the function's estimated value, and the second is an estimate of the
absolute error of the result. Neville's algorithm for polynomial
interpolation is used. Note that a large table of values will use an
interpolating polynomial of high degree, which is likely to result in
numerical instabilities; one is better off using only a few tabulated values
near the desired abscissa.
# <a name='section4'></a>EXAMPLES
*Example of using one-dimensional tables:*
Suppose you have several tabulated functions of one variable:
x y1 y2
0.0 0.0 0.0
1.0 1.0 1.0
2.0 4.0 8.0
3.0 9.0 27.0
4.0 16.0 64.0
Then to estimate the values at 0.5, 1.5, 2.5 and 3.5, you can use:
set table [::math::interpolate::defineTable table1 {x y1 y2} { - 1 2
0.0 0.0 0.0
1.0 1.0 1.0
2.0 4.0 8.0
3.0 9.0 27.0
4.0 16.0 64.0}]
foreach x {0.5 1.5 2.5 3.5} {
puts "$x: [::math::interpolate::interp-1d-table $table $x]"
}
For one-dimensional tables the first row is not used. For two-dimensional
tables, the first row represents the values for the second independent variable.
*Example of using the cubic splines:*
Suppose the following values are given:
x y
0.1 1.0
0.3 2.1
0.4 2.2
0.8 4.11
1.0 4.12
Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use:
set coeffs [::math::interpolate::prepare-cubic-splines {0.1 0.3 0.4 0.8 1.0} {1.0 2.1 2.2 4.11 4.12}]
foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} {
puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]"
}
to get the following output:
0.1: 1.0
0.2: 1.68044117647
0.3: 2.1
0.4: 2.2
0.5: 3.11221507353
0.6: 4.25242647059
0.7: 5.41804227941
0.8: 4.11
0.9: 3.95675857843
1.0: 4.12
As you can see, the values at the abscissae are reproduced perfectly.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: interpolate* 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.
# <a name='keywords'></a>KEYWORDS
[interpolation](../../../../index.md#interpolation),
[math](../../../../index.md#math), [spatial
interpolation](../../../../index.md#spatial_interpolation)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
Copyright © 2004 Kevn B. Kenny <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/linalg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
|
[//000000001]: # (math::linearalgebra - Tcl Math Library)
[//000000002]: # (Generated from file 'linalg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::linearalgebra(n) 1.1.5 tcllib "Tcl Math Library")
# NAME
math::linearalgebra - Linear Algebra
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [STORAGE](#section3)
- [REMARKS ON THE IMPLEMENTATION](#section4)
- [TODO](#section5)
- [NAMING CONFLICT](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require math::linearalgebra ?1.1.5?
[__::math::linearalgebra::mkVector__ *ndim* *value*](#1)
[__::math::linearalgebra::mkUnitVector__ *ndim* *ndir*](#2)
[__::math::linearalgebra::mkMatrix__ *nrows* *ncols* *value*](#3)
[__::math::linearalgebra::getrow__ *matrix* *row* ?imin? ?imax?](#4)
[__::math::linearalgebra::setrow__ *matrix* *row* *newvalues* ?imin? ?imax?](#5)
[__::math::linearalgebra::getcol__ *matrix* *col* ?imin? ?imax?](#6)
[__::math::linearalgebra::setcol__ *matrix* *col* *newvalues* ?imin? ?imax?](#7)
[__::math::linearalgebra::getelem__ *matrix* *row* *col*](#8)
[__::math::linearalgebra::setelem__ *matrix* *row* ?col? *newvalue*](#9)
[__::math::linearalgebra::swaprows__ *matrix* *irow1* *irow2* ?imin? ?imax?](#10)
[__::math::linearalgebra::swapcols__ *matrix* *icol1* *icol2* ?imin? ?imax?](#11)
[__::math::linearalgebra::show__ *obj* ?format? ?rowsep? ?colsep?](#12)
[__::math::linearalgebra::dim__ *obj*](#13)
[__::math::linearalgebra::shape__ *obj*](#14)
[__::math::linearalgebra::conforming__ *type* *obj1* *obj2*](#15)
[__::math::linearalgebra::symmetric__ *matrix* ?eps?](#16)
[__::math::linearalgebra::norm__ *vector* *type*](#17)
[__::math::linearalgebra::norm_one__ *vector*](#18)
[__::math::linearalgebra::norm_two__ *vector*](#19)
[__::math::linearalgebra::norm_max__ *vector* ?index?](#20)
[__::math::linearalgebra::normMatrix__ *matrix* *type*](#21)
[__::math::linearalgebra::dotproduct__ *vect1* *vect2*](#22)
[__::math::linearalgebra::unitLengthVector__ *vector*](#23)
[__::math::linearalgebra::normalizeStat__ *mv*](#24)
[__::math::linearalgebra::axpy__ *scale* *mv1* *mv2*](#25)
[__::math::linearalgebra::add__ *mv1* *mv2*](#26)
[__::math::linearalgebra::sub__ *mv1* *mv2*](#27)
[__::math::linearalgebra::scale__ *scale* *mv*](#28)
[__::math::linearalgebra::rotate__ *c* *s* *vect1* *vect2*](#29)
[__::math::linearalgebra::transpose__ *matrix*](#30)
[__::math::linearalgebra::matmul__ *mv1* *mv2*](#31)
[__::math::linearalgebra::angle__ *vect1* *vect2*](#32)
[__::math::linearalgebra::crossproduct__ *vect1* *vect2*](#33)
[__::math::linearalgebra::matmul__ *mv1* *mv2*](#34)
[__::math::linearalgebra::mkIdentity__ *size*](#35)
[__::math::linearalgebra::mkDiagonal__ *diag*](#36)
[__::math::linearalgebra::mkRandom__ *size*](#37)
[__::math::linearalgebra::mkTriangular__ *size* ?uplo? ?value?](#38)
[__::math::linearalgebra::mkHilbert__ *size*](#39)
[__::math::linearalgebra::mkDingdong__ *size*](#40)
[__::math::linearalgebra::mkOnes__ *size*](#41)
[__::math::linearalgebra::mkMoler__ *size*](#42)
[__::math::linearalgebra::mkFrank__ *size*](#43)
[__::math::linearalgebra::mkBorder__ *size*](#44)
[__::math::linearalgebra::mkWilkinsonW+__ *size*](#45)
[__::math::linearalgebra::mkWilkinsonW-__ *size*](#46)
[__::math::linearalgebra::solveGauss__ *matrix* *bvect*](#47)
[__::math::linearalgebra::solvePGauss__ *matrix* *bvect*](#48)
[__::math::linearalgebra::solveTriangular__ *matrix* *bvect* ?uplo?](#49)
[__::math::linearalgebra::solveGaussBand__ *matrix* *bvect*](#50)
[__::math::linearalgebra::solveTriangularBand__ *matrix* *bvect*](#51)
[__::math::linearalgebra::determineSVD__ *A* *eps*](#52)
[__::math::linearalgebra::eigenvectorsSVD__ *A* *eps*](#53)
[__::math::linearalgebra::leastSquaresSVD__ *A* *y* *qmin* *eps*](#54)
[__::math::linearalgebra::choleski__ *matrix*](#55)
[__::math::linearalgebra::orthonormalizeColumns__ *matrix*](#56)
[__::math::linearalgebra::orthonormalizeRows__ *matrix*](#57)
[__::math::linearalgebra::dger__ *matrix* *alpha* *x* *y* ?scope?](#58)
[__::math::linearalgebra::dgetrf__ *matrix*](#59)
[__::math::linearalgebra::det__ *matrix*](#60)
[__::math::linearalgebra::largesteigen__ *matrix* *tolerance* *maxiter*](#61)
[__::math::linearalgebra::to_LA__ *mv*](#62)
[__::math::linearalgebra::from_LA__ *mv*](#63)
# <a name='description'></a>DESCRIPTION
This package offers both low-level procedures and high-level algorithms to deal
with linear algebra problems:
- robust solution of linear equations or least squares problems
- determining eigenvectors and eigenvalues of symmetric matrices
- various decompositions of general matrices or matrices of a specific form
- (limited) support for matrices in band storage, a common type of sparse
matrices
It arose as a re-implementation of Hume's LA package and the desire to offer
low-level procedures as found in the well-known BLAS library. Matrices are
implemented as lists of lists rather linear lists with reserved elements, as in
the original LA package, as it was found that such an implementation is actually
faster.
It is advisable, however, to use the procedures that are offered, such as
*setrow* and *getrow*, rather than rely on this representation explicitly: that
way it is to switch to a possibly even faster compiled implementation that
supports the same API.
*Note:* When using this package in combination with Tk, there may be a naming
conflict, as both this package and Tk define a command *scale*. See the [NAMING
CONFLICT](#section6) section below.
# <a name='section2'></a>PROCEDURES
The package defines the following public procedures (several exist as
specialised procedures, see below):
*Constructing matrices and vectors*
- <a name='1'></a>__::math::linearalgebra::mkVector__ *ndim* *value*
Create a vector with ndim elements, each with the value *value*.
* integer *ndim*
Dimension of the vector (number of components)
* double *value*
Uniform value to be used (default: 0.0)
- <a name='2'></a>__::math::linearalgebra::mkUnitVector__ *ndim* *ndir*
Create a unit vector in *ndim*-dimensional space, along the *ndir*-th
direction.
* integer *ndim*
Dimension of the vector (number of components)
* integer *ndir*
Direction (0, ..., ndim-1)
- <a name='3'></a>__::math::linearalgebra::mkMatrix__ *nrows* *ncols* *value*
Create a matrix with *nrows* rows and *ncols* columns. All elements have the
value *value*.
* integer *nrows*
Number of rows
* integer *ncols*
Number of columns
* double *value*
Uniform value to be used (default: 0.0)
- <a name='4'></a>__::math::linearalgebra::getrow__ *matrix* *row* ?imin? ?imax?
Returns a single row of a matrix as a list
* list *matrix*
Matrix in question
* integer *row*
Index of the row to return
* integer *imin*
Minimum index of the column (default: 0)
* integer *imax*
Maximum index of the column (default: ncols-1)
- <a name='5'></a>__::math::linearalgebra::setrow__ *matrix* *row* *newvalues* ?imin? ?imax?
Set a single row of a matrix to new values (this list must have the same
number of elements as the number of *columns* in the matrix)
* list *matrix*
*name* of the matrix in question
* integer *row*
Index of the row to update
* list *newvalues*
List of new values for the row
* integer *imin*
Minimum index of the column (default: 0)
* integer *imax*
Maximum index of the column (default: ncols-1)
- <a name='6'></a>__::math::linearalgebra::getcol__ *matrix* *col* ?imin? ?imax?
Returns a single column of a matrix as a list
* list *matrix*
Matrix in question
* integer *col*
Index of the column to return
* integer *imin*
Minimum index of the row (default: 0)
* integer *imax*
Maximum index of the row (default: nrows-1)
- <a name='7'></a>__::math::linearalgebra::setcol__ *matrix* *col* *newvalues* ?imin? ?imax?
Set a single column of a matrix to new values (this list must have the same
number of elements as the number of *rows* in the matrix)
* list *matrix*
*name* of the matrix in question
* integer *col*
Index of the column to update
* list *newvalues*
List of new values for the column
* integer *imin*
Minimum index of the row (default: 0)
* integer *imax*
Maximum index of the row (default: nrows-1)
- <a name='8'></a>__::math::linearalgebra::getelem__ *matrix* *row* *col*
Returns a single element of a matrix/vector
* list *matrix*
Matrix or vector in question
* integer *row*
Row of the element
* integer *col*
Column of the element (not present for vectors)
- <a name='9'></a>__::math::linearalgebra::setelem__ *matrix* *row* ?col? *newvalue*
Set a single element of a matrix (or vector) to a new value
* list *matrix*
*name* of the matrix in question
* integer *row*
Row of the element
* integer *col*
Column of the element (not present for vectors)
- <a name='10'></a>__::math::linearalgebra::swaprows__ *matrix* *irow1* *irow2* ?imin? ?imax?
Swap two rows in a matrix completely or only a selected part
* list *matrix*
*name* of the matrix in question
* integer *irow1*
Index of first row
* integer *irow2*
Index of second row
* integer *imin*
Minimum column index (default: 0)
* integer *imin*
Maximum column index (default: ncols-1)
- <a name='11'></a>__::math::linearalgebra::swapcols__ *matrix* *icol1* *icol2* ?imin? ?imax?
Swap two columns in a matrix completely or only a selected part
* list *matrix*
*name* of the matrix in question
* integer *irow1*
Index of first column
* integer *irow2*
Index of second column
* integer *imin*
Minimum row index (default: 0)
* integer *imin*
Maximum row index (default: nrows-1)
*Querying matrices and vectors*
- <a name='12'></a>__::math::linearalgebra::show__ *obj* ?format? ?rowsep? ?colsep?
Return a string representing the vector or matrix, for easy printing. (There
is currently no way to print fixed sets of columns)
* list *obj*
Matrix or vector in question
* string *format*
Format for printing the numbers (default: %6.4f)
* string *rowsep*
String to use for separating rows (default: newline)
* string *colsep*
String to use for separating columns (default: space)
- <a name='13'></a>__::math::linearalgebra::dim__ *obj*
Returns the number of dimensions for the object (either 0 for a scalar, 1
for a vector and 2 for a matrix)
* any *obj*
Scalar, vector, or matrix
- <a name='14'></a>__::math::linearalgebra::shape__ *obj*
Returns the number of elements in each dimension for the object (either an
empty list for a scalar, a single number for a vector and a list of the
number of rows and columns for a matrix)
* any *obj*
Scalar, vector, or matrix
- <a name='15'></a>__::math::linearalgebra::conforming__ *type* *obj1* *obj2*
Checks if two objects (vector or matrix) have conforming shapes, that is if
they can be applied in an operation like addition or matrix multiplication.
* string *type*
Type of check:
"shape" - the two objects have the same shape (for all element-wise
operations)
"rows" - the two objects have the same number of rows (for use as A and
b in a system of linear equations *Ax = b*
"matmul" - the first object has the same number of columns as the number
of rows of the second object. Useful for matrix-matrix or matrix-vector
multiplication.
* list *obj1*
First vector or matrix (left operand)
* list *obj2*
Second vector or matrix (right operand)
- <a name='16'></a>__::math::linearalgebra::symmetric__ *matrix* ?eps?
Checks if the given (square) matrix is symmetric. The argument eps is the
tolerance.
* list *matrix*
Matrix to be inspected
* float *eps*
Tolerance for determining approximate equality (defaults to 1.0e-8)
*Basic operations*
- <a name='17'></a>__::math::linearalgebra::norm__ *vector* *type*
Returns the norm of the given vector. The type argument can be: 1, 2, inf or
max, respectively the sum of absolute values, the ordinary Euclidean norm or
the max norm.
* list *vector*
Vector, list of coefficients
* string *type*
Type of norm (default: 2, the Euclidean norm)
- <a name='18'></a>__::math::linearalgebra::norm_one__ *vector*
Returns the L1 norm of the given vector, the sum of absolute values
* list *vector*
Vector, list of coefficients
- <a name='19'></a>__::math::linearalgebra::norm_two__ *vector*
Returns the L2 norm of the given vector, the ordinary Euclidean norm
* list *vector*
Vector, list of coefficients
- <a name='20'></a>__::math::linearalgebra::norm_max__ *vector* ?index?
Returns the Linf norm of the given vector, the maximum absolute coefficient
* list *vector*
Vector, list of coefficients
* integer *index*
(optional) if non zero, returns a list made of the maximum value and the
index where that maximum was found. if zero, returns the maximum value.
- <a name='21'></a>__::math::linearalgebra::normMatrix__ *matrix* *type*
Returns the norm of the given matrix. The type argument can be: 1, 2, inf or
max, respectively the sum of absolute values, the ordinary Euclidean norm or
the max norm.
* list *matrix*
Matrix, list of row vectors
* string *type*
Type of norm (default: 2, the Euclidean norm)
- <a name='22'></a>__::math::linearalgebra::dotproduct__ *vect1* *vect2*
Determine the inproduct or dot product of two vectors. These must have the
same shape (number of dimensions)
* list *vect1*
First vector, list of coefficients
* list *vect2*
Second vector, list of coefficients
- <a name='23'></a>__::math::linearalgebra::unitLengthVector__ *vector*
Return a vector in the same direction with length 1.
* list *vector*
Vector to be normalized
- <a name='24'></a>__::math::linearalgebra::normalizeStat__ *mv*
Normalize the matrix or vector in a statistical sense: the mean of the
elements of the columns of the result is zero and the standard deviation is
1.
* list *mv*
Vector or matrix to be normalized in the above sense
- <a name='25'></a>__::math::linearalgebra::axpy__ *scale* *mv1* *mv2*
Return a vector or matrix that results from a "daxpy" operation, that is:
compute a*x+y (a a scalar and x and y both vectors or matrices of the same
shape) and return the result.
Specialised variants are: axpy_vect and axpy_mat (slightly faster, but no
check on the arguments)
* double *scale*
The scale factor for the first vector/matrix (a)
* list *mv1*
First vector or matrix (x)
* list *mv2*
Second vector or matrix (y)
- <a name='26'></a>__::math::linearalgebra::add__ *mv1* *mv2*
Return a vector or matrix that is the sum of the two arguments (x+y)
Specialised variants are: add_vect and add_mat (slightly faster, but no
check on the arguments)
* list *mv1*
First vector or matrix (x)
* list *mv2*
Second vector or matrix (y)
- <a name='27'></a>__::math::linearalgebra::sub__ *mv1* *mv2*
Return a vector or matrix that is the difference of the two arguments (x-y)
Specialised variants are: sub_vect and sub_mat (slightly faster, but no
check on the arguments)
* list *mv1*
First vector or matrix (x)
* list *mv2*
Second vector or matrix (y)
- <a name='28'></a>__::math::linearalgebra::scale__ *scale* *mv*
Scale a vector or matrix and return the result, that is: compute a*x.
Specialised variants are: scale_vect and scale_mat (slightly faster, but no
check on the arguments)
* double *scale*
The scale factor for the vector/matrix (a)
* list *mv*
Vector or matrix (x)
- <a name='29'></a>__::math::linearalgebra::rotate__ *c* *s* *vect1* *vect2*
Apply a planar rotation to two vectors and return the result as a list of
two vectors: c*x-s*y and s*x+c*y. In algorithms you can often easily
determine the cosine and sine of the angle, so it is more efficient to pass
that information directly.
* double *c*
The cosine of the angle
* double *s*
The sine of the angle
* list *vect1*
First vector (x)
* list *vect2*
Seocnd vector (x)
- <a name='30'></a>__::math::linearalgebra::transpose__ *matrix*
Transpose a matrix
* list *matrix*
Matrix to be transposed
- <a name='31'></a>__::math::linearalgebra::matmul__ *mv1* *mv2*
Multiply a vector/matrix with another vector/matrix. The result is a matrix,
if both x and y are matrices or both are vectors, in which case the "outer
product" is computed. If one is a vector and the other is a matrix, then the
result is a vector.
* list *mv1*
First vector/matrix (x)
* list *mv2*
Second vector/matrix (y)
- <a name='32'></a>__::math::linearalgebra::angle__ *vect1* *vect2*
Compute the angle between two vectors (in radians)
* list *vect1*
First vector
* list *vect2*
Second vector
- <a name='33'></a>__::math::linearalgebra::crossproduct__ *vect1* *vect2*
Compute the cross product of two (three-dimensional) vectors
* list *vect1*
First vector
* list *vect2*
Second vector
- <a name='34'></a>__::math::linearalgebra::matmul__ *mv1* *mv2*
Multiply a vector/matrix with another vector/matrix. The result is a matrix,
if both x and y are matrices or both are vectors, in which case the "outer
product" is computed. If one is a vector and the other is a matrix, then the
result is a vector.
* list *mv1*
First vector/matrix (x)
* list *mv2*
Second vector/matrix (y)
*Common matrices and test matrices*
- <a name='35'></a>__::math::linearalgebra::mkIdentity__ *size*
Create an identity matrix of dimension *size*.
* integer *size*
Dimension of the matrix
- <a name='36'></a>__::math::linearalgebra::mkDiagonal__ *diag*
Create a diagonal matrix whose diagonal elements are the elements of the
vector *diag*.
* list *diag*
Vector whose elements are used for the diagonal
- <a name='37'></a>__::math::linearalgebra::mkRandom__ *size*
Create a square matrix whose elements are uniformly distributed random
numbers between 0 and 1 of dimension *size*.
* integer *size*
Dimension of the matrix
- <a name='38'></a>__::math::linearalgebra::mkTriangular__ *size* ?uplo? ?value?
Create a triangular matrix with non-zero elements in the upper or lower
part, depending on argument *uplo*.
* integer *size*
Dimension of the matrix
* string *uplo*
Fill the upper (U) or lower part (L)
* double *value*
Value to fill the matrix with
- <a name='39'></a>__::math::linearalgebra::mkHilbert__ *size*
Create a Hilbert matrix of dimension *size*. Hilbert matrices are very
ill-conditioned with respect to eigenvalue/eigenvector problems. Therefore
they are good candidates for testing the accuracy of algorithms and
implementations.
* integer *size*
Dimension of the matrix
- <a name='40'></a>__::math::linearalgebra::mkDingdong__ *size*
Create a "dingdong" matrix of dimension *size*. Dingdong matrices are
imprecisely represented, but have the property of being very stable in such
algorithms as Gauss elimination.
* integer *size*
Dimension of the matrix
- <a name='41'></a>__::math::linearalgebra::mkOnes__ *size*
Create a square matrix of dimension *size* whose entries are all 1.
* integer *size*
Dimension of the matrix
- <a name='42'></a>__::math::linearalgebra::mkMoler__ *size*
Create a Moler matrix of size *size*. (Moler matrices have a very simple
Choleski decomposition. It has one small eigenvalue and it can easily upset
elimination methods for systems of linear equations.)
* integer *size*
Dimension of the matrix
- <a name='43'></a>__::math::linearalgebra::mkFrank__ *size*
Create a Frank matrix of size *size*. (Frank matrices are fairly
well-behaved matrices)
* integer *size*
Dimension of the matrix
- <a name='44'></a>__::math::linearalgebra::mkBorder__ *size*
Create a bordered matrix of size *size*. (Bordered matrices have a very low
rank and can upset certain specialised algorithms.)
* integer *size*
Dimension of the matrix
- <a name='45'></a>__::math::linearalgebra::mkWilkinsonW+__ *size*
Create a Wilkinson W+ of size *size*. This kind of matrix has pairs of
eigenvalues that are very close together. Usually the order (size) is odd.
* integer *size*
Dimension of the matrix
- <a name='46'></a>__::math::linearalgebra::mkWilkinsonW-__ *size*
Create a Wilkinson W- of size *size*. This kind of matrix has pairs of
eigenvalues with opposite signs, when the order (size) is odd.
* integer *size*
Dimension of the matrix
*Common algorithms*
- <a name='47'></a>__::math::linearalgebra::solveGauss__ *matrix* *bvect*
Solve a system of linear equations (Ax=b) using Gauss elimination. Returns
the solution (x) as a vector or matrix of the same shape as bvect.
* list *matrix*
Square matrix (matrix A)
* list *bvect*
Vector or matrix whose columns are the individual b-vectors
- <a name='48'></a>__::math::linearalgebra::solvePGauss__ *matrix* *bvect*
Solve a system of linear equations (Ax=b) using Gauss elimination with
partial pivoting. Returns the solution (x) as a vector or matrix of the same
shape as bvect.
* list *matrix*
Square matrix (matrix A)
* list *bvect*
Vector or matrix whose columns are the individual b-vectors
- <a name='49'></a>__::math::linearalgebra::solveTriangular__ *matrix* *bvect* ?uplo?
Solve a system of linear equations (Ax=b) by backward substitution. The
matrix is supposed to be upper-triangular.
* list *matrix*
Lower or upper-triangular matrix (matrix A)
* list *bvect*
Vector or matrix whose columns are the individual b-vectors
* string *uplo*
Indicates whether the matrix is lower-triangular (L) or upper-triangular
(U). Defaults to "U".
- <a name='50'></a>__::math::linearalgebra::solveGaussBand__ *matrix* *bvect*
Solve a system of linear equations (Ax=b) using Gauss elimination, where the
matrix is stored as a band matrix (*cf.* [STORAGE](#section3)). Returns the
solution (x) as a vector or matrix of the same shape as bvect.
* list *matrix*
Square matrix (matrix A; in band form)
* list *bvect*
Vector or matrix whose columns are the individual b-vectors
- <a name='51'></a>__::math::linearalgebra::solveTriangularBand__ *matrix* *bvect*
Solve a system of linear equations (Ax=b) by backward substitution. The
matrix is supposed to be upper-triangular and stored in band form.
* list *matrix*
Upper-triangular matrix (matrix A)
* list *bvect*
Vector or matrix whose columns are the individual b-vectors
- <a name='52'></a>__::math::linearalgebra::determineSVD__ *A* *eps*
Determines the Singular Value Decomposition of a matrix: A = U S Vtrans.
Returns a list with the matrix U, the vector of singular values S and the
matrix V.
* list *A*
Matrix to be decomposed
* float *eps*
Tolerance (defaults to 2.3e-16)
- <a name='53'></a>__::math::linearalgebra::eigenvectorsSVD__ *A* *eps*
Determines the eigenvectors and eigenvalues of a real *symmetric* matrix,
using SVD. Returns a list with the matrix of normalized eigenvectors and
their eigenvalues.
* list *A*
Matrix whose eigenvalues must be determined
* float *eps*
Tolerance (defaults to 2.3e-16)
- <a name='54'></a>__::math::linearalgebra::leastSquaresSVD__ *A* *y* *qmin* *eps*
Determines the solution to a least-sqaures problem Ax ~ y via singular value
decomposition. The result is the vector x.
Note that if you add a column of 1s to the matrix, then this column will
represent a constant like in: y = a*x1 + b*x2 + c. To force the intercept to
be zero, simply leave it out.
* list *A*
Matrix of independent variables
* list *y*
List of observed values
* float *qmin*
Minimum singular value to be considered (defaults to 0.0)
* float *eps*
Tolerance (defaults to 2.3e-16)
- <a name='55'></a>__::math::linearalgebra::choleski__ *matrix*
Determine the Choleski decomposition of a symmetric positive semidefinite
matrix (this condition is not checked!). The result is the lower-triangular
matrix L such that L Lt = matrix.
* list *matrix*
Matrix to be decomposed
- <a name='56'></a>__::math::linearalgebra::orthonormalizeColumns__ *matrix*
Use the modified Gram-Schmidt method to orthogonalize and normalize the
*columns* of the given matrix and return the result.
* list *matrix*
Matrix whose columns must be orthonormalized
- <a name='57'></a>__::math::linearalgebra::orthonormalizeRows__ *matrix*
Use the modified Gram-Schmidt method to orthogonalize and normalize the
*rows* of the given matrix and return the result.
* list *matrix*
Matrix whose rows must be orthonormalized
- <a name='58'></a>__::math::linearalgebra::dger__ *matrix* *alpha* *x* *y* ?scope?
Perform the rank 1 operation A + alpha*x*y' inline (that is: the matrix A is
adjusted). For convenience the new matrix is also returned as the result.
* list *matrix*
Matrix whose rows must be adjusted
* double *alpha*
Scale factor
* list *x*
A column vector
* list *y*
A column vector
* list *scope*
If not provided, the operation is performed on all rows/columns of A if
provided, it is expected to be the list {imin imax jmin jmax} where:
*imin* Minimum row index
*imax* Maximum row index
*jmin* Minimum column index
*jmax* Maximum column index
- <a name='59'></a>__::math::linearalgebra::dgetrf__ *matrix*
Computes an LU factorization of a general matrix, using partial, pivoting
with row interchanges. Returns the permutation vector.
The factorization has the form
P * A = L * U
where P is a permutation matrix, L is lower triangular with unit diagonal
elements, and U is upper triangular. Returns the permutation vector, as a
list of length n-1. The last entry of the permutation is not stored, since
it is implicitely known, with value n (the last row is not swapped with any
other row). At index #i of the permutation is stored the index of the row #j
which is swapped with row #i at step #i. That means that each index of the
permutation gives the permutation at each step, not the cumulated
permutation matrix, which is the product of permutations.
* list *matrix*
On entry, the matrix to be factored. On exit, the factors L and U from
the factorization P*A = L*U; the unit diagonal elements of L are not
stored.
- <a name='60'></a>__::math::linearalgebra::det__ *matrix*
Returns the determinant of the given matrix, based on PA=LU decomposition,
i.e. Gauss partial pivotal.
* list *matrix*
Square matrix (matrix A)
* list *ipiv*
The pivots (optionnal). If the pivots are not provided, a PA=LU
decomposition is performed. If the pivots are provided, we assume that
it contains the pivots and that the matrix A contains the L and U
factors, as provided by dgterf. b-vectors
- <a name='61'></a>__::math::linearalgebra::largesteigen__ *matrix* *tolerance* *maxiter*
Returns a list made of the largest eigenvalue (in magnitude) and associated
eigenvector. Uses iterative Power Method as provided as algorithm #7.3.3 of
Golub & Van Loan. This algorithm is used here for a dense matrix (but is
usually used for sparse matrices).
* list *matrix*
Square matrix (matrix A)
* double *tolerance*
The relative tolerance of the eigenvalue (default:1.e-8).
* integer *maxiter*
The maximum number of iterations (default:10).
*Compability with the LA package* Two procedures are provided for compatibility
with Hume's LA package:
- <a name='62'></a>__::math::linearalgebra::to_LA__ *mv*
Transforms a vector or matrix into the format used by the original LA
package.
* list *mv*
Matrix or vector
- <a name='63'></a>__::math::linearalgebra::from_LA__ *mv*
Transforms a vector or matrix from the format used by the original LA
package into the format used by the present implementation.
* list *mv*
Matrix or vector as used by the LA package
# <a name='section3'></a>STORAGE
While most procedures assume that the matrices are given in full form, the
procedures *solveGaussBand* and *solveTriangularBand* assume that the matrices
are stored as *band matrices*. This common type of "sparse" matrices is related
to ordinary matrices as follows:
- "A" is a full-size matrix with N rows and M columns.
- "B" is a band matrix, with m upper and lower diagonals and n rows.
- "B" can be stored in an ordinary matrix of (2m+1) columns (one for each
off-diagonal and the main diagonal) and n rows.
- Element i,j (i = -m,...,m; j =1,...,n) of "B" corresponds to element k,j of
"A" where k = M+i-1 and M is at least (!) n, the number of rows in "B".
- To set element (i,j) of matrix "B" use:
setelem B $j [expr {$N+$i-1}] $value
(There is no convenience procedure for this yet)
# <a name='section4'></a>REMARKS ON THE IMPLEMENTATION
There is a difference between the original LA package by Hume and the current
implementation. Whereas the LA package uses a linear list, the current package
uses lists of lists to represent matrices. It turns out that with this
representation, the algorithms are faster and easier to implement.
The LA package was used as a model and in fact the implementation of, for
instance, the SVD algorithm was taken from that package. The set of procedures
was expanded using ideas from the well-known BLAS library and some algorithms
were updated from the second edition of J.C. Nash's book, Compact Numerical
Methods for Computers, (Adam Hilger, 1990) that inspired the LA package.
Two procedures are provided to make the transition between the two
implementations easier: *to_LA* and *from_LA*. They are described above.
# <a name='section5'></a>TODO
Odds and ends: the following algorithms have not been implemented yet:
- determineQR
- certainlyPositive, diagonallyDominant
# <a name='section6'></a>NAMING CONFLICT
If you load this package in a Tk-enabled shell like wish, then the command
namespace import ::math::linearalgebra
results in an error message about "scale". This is due to the fact that Tk
defines all its commands in the global namespace. The solution is to import the
linear algebra commands in a namespace that is not the global one:
package require math::linearalgebra
namespace eval compute {
namespace import ::math::linearalgebra::*
... use the linear algebra version of scale ...
}
To use Tk's scale command in that same namespace you can rename it:
namespace eval compute {
rename ::scale scaleTk
scaleTk .scale ...
}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: linearalgebra* 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.
# <a name='keywords'></a>KEYWORDS
[least squares](../../../../index.md#least_squares), [linear
algebra](../../../../index.md#linear_algebra), [linear
equations](../../../../index.md#linear_equations),
[math](../../../../index.md#math), [matrices](../../../../index.md#matrices),
[matrix](../../../../index.md#matrix), [vectors](../../../../index.md#vectors)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2008 Arjen Markus <[email protected]>
Copyright © 2004 Ed Hume <http://www.hume.com/contact.us.htm>
Copyright © 2008 Michael Buadin <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/machineparameters.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
[//000000001]: # (tclrep/machineparameters - tclrep)
[//000000002]: # (Generated from file 'machineparameters.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tclrep/machineparameters(n) 1.0 tcllib "tclrep")
# NAME
tclrep/machineparameters - Compute double precision machine parameters.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLE](#section2)
- [REFERENCES](#section3)
- [CLASS API](#section4)
- [OBJECT API](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit
package require math::machineparameters 0.1
[__machineparameters__ create *objectname* ?*options*...?](#1)
[*objectname* __configure__ ?*options*...?](#2)
[*objectname* __cget__ *opt*](#3)
[*objectname* __destroy__](#4)
[*objectname* __compute__](#5)
[*objectname* __get__ *key*](#6)
[*objectname* __tostring__](#7)
[*objectname* __print__](#8)
# <a name='description'></a>DESCRIPTION
The *math::machineparameters* package is the Tcl equivalent of the DLAMCH LAPACK
function. In floating point systems, a floating point number is represented by
x = +/- d1 d2 ... dt basis^e
where digits satisfy
0 <= di <= basis - 1, i = 1, t
with the convention :
- t is the size of the mantissa
- basis is the basis (the "radix")
The __compute__ method computes all machine parameters. Then, the __get__ method
can be used to get each parameter. The __print__ method prints a report on
standard output.
# <a name='section2'></a>EXAMPLE
In the following example, one compute the parameters of a desktop under Linux
with the following Tcl 8.4.19 properties :
% parray tcl_platform
tcl_platform(byteOrder) = littleEndian
tcl_platform(machine) = i686
tcl_platform(os) = Linux
tcl_platform(osVersion) = 2.6.24-19-generic
tcl_platform(platform) = unix
tcl_platform(tip,268) = 1
tcl_platform(tip,280) = 1
tcl_platform(user) = <username>
tcl_platform(wordSize) = 4
The following example creates a machineparameters object, computes the
properties and displays it.
set pp [machineparameters create %AUTO%]
$pp compute
$pp print
$pp destroy
This prints out :
Machine parameters
Epsilon : 1.11022302463e-16
Beta : 2
Rounding : proper
Mantissa : 53
Maximum exponent : 1024
Minimum exponent : -1021
Overflow threshold : 8.98846567431e+307
Underflow threshold : 2.22507385851e-308
That compares well with the results produced by Lapack 3.1.1 :
Epsilon = 1.11022302462515654E-016
Safe minimum = 2.22507385850720138E-308
Base = 2.0000000000000000
Precision = 2.22044604925031308E-016
Number of digits in mantissa = 53.000000000000000
Rounding mode = 1.00000000000000000
Minimum exponent = -1021.0000000000000
Underflow threshold = 2.22507385850720138E-308
Largest exponent = 1024.0000000000000
Overflow threshold = 1.79769313486231571E+308
Reciprocal of safe minimum = 4.49423283715578977E+307
The following example creates a machineparameters object, computes the
properties and gets the epsilon for the machine.
set pp [machineparameters create %AUTO%]
$pp compute
set eps [$pp get -epsilon]
$pp destroy
# <a name='section3'></a>REFERENCES
- "Algorithms to Reveal Properties of Floating-Point Arithmetic", Michael A.
Malcolm, Stanford University, Communications of the ACM, Volume 15 , Issue
11 (November 1972), Pages: 949 - 951
- "More on Algorithms that Reveal Properties of Floating, Point Arithmetic
Units", W. Morven Gentleman, University of Waterloo, Scott B. Marovich,
Purdue University, Communications of the ACM, Volume 17 , Issue 5 (May
1974), Pages: 276 - 277
# <a name='section4'></a>CLASS API
- <a name='1'></a>__machineparameters__ create *objectname* ?*options*...?
The command creates a new machineparameters object and returns the fully
qualified name of the object command as its result.
* __-verbose__ *verbose*
Set this option to 1 to enable verbose logging. This option is mainly
for debug purposes. The default value of *verbose* is 0.
# <a name='section5'></a>OBJECT API
- <a name='2'></a>*objectname* __configure__ ?*options*...?
The command configure the options of the object *objectname*. The options
are the same as the static method __create__.
- <a name='3'></a>*objectname* __cget__ *opt*
Returns the value of the option which name is *opt*. The options are the
same as the method __create__ and __configure__.
- <a name='4'></a>*objectname* __destroy__
Destroys the object *objectname*.
- <a name='5'></a>*objectname* __compute__
Computes the machine parameters.
- <a name='6'></a>*objectname* __get__ *key*
Returns the value corresponding with given key. The following is the list of
available keys.
-epsilon : smallest value so that 1+epsilon>1 is false
-rounding : The rounding mode used on the machine. The rounding occurs when
more than t digits would be required to represent the number. Two modes can
be determined with the current system : "chop" means than only t digits are
kept, no matter the value of the number "proper" means that another rounding
mode is used, be it "round to nearest", "round up", "round down".
-basis : the basis of the floating-point representation. The basis is
usually 2, i.e. binary representation (for example IEEE 754 machines), but
some machines (like HP calculators for example) uses 10, or 16, etc...
-mantissa : the number of bits in the mantissa
-exponentmax : the largest positive exponent before overflow occurs
-exponentmin : the largest negative exponent before (gradual) underflow
occurs
-vmax : largest positive value before overflow occurs
-vmin : largest negative value before (gradual) underflow occurs
- <a name='7'></a>*objectname* __tostring__
Return a report for machine parameters.
- <a name='8'></a>*objectname* __print__
Print machine parameters on standard output.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math* 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.
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Michael Baudin <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/math.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
[//000000001]: # (math - Tcl Math Library)
[//000000002]: # (Generated from file 'math.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math(n) 1.2.5 tcllib "Tcl Math Library")
# NAME
math - Tcl Math Library
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [BASIC COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require math ?1.2.5?
[__::math::cov__ *value* *value* ?*value ...*?](#1)
[__::math::integrate__ *list of xy value pairs*](#2)
[__::math::fibonacci__ *n*](#3)
[__::math::max__ *value* ?*value ...*?](#4)
[__::math::mean__ *value* ?*value ...*?](#5)
[__::math::min__ *value* ?*value ...*?](#6)
[__::math::product__ *value* ?*value ...*?](#7)
[__::math::random__ ?*value1*? ?*value2*?](#8)
[__::math::sigma__ *value* *value* ?*value ...*?](#9)
[__::math::stats__ *value* *value* ?*value ...*?](#10)
[__::math::sum__ *value* ?*value ...*?](#11)
# <a name='description'></a>DESCRIPTION
The __math__ package provides utility math functions.
Besides a set of basic commands, available via the package *math*, there are
more specialised packages:
- __[math::bigfloat](bigfloat.md)__ - Arbitrary-precision floating-point
arithmetic
- __[math::bignum](bignum.md)__ - Arbitrary-precision integer arithmetic
- __[math::calculus::romberg](romberg.md)__ - Robust integration methods for
functions of one variable, using Romberg integration
- __[math::calculus](calculus.md)__ - Integration of functions, solving
ordinary differential equations
- __[math::combinatorics](combinatorics.md)__ - Procedures for various
combinatorial functions (for instance the Gamma function and "k out of n")
- __[math::complexnumbers](qcomplex.md)__ - Complex number arithmetic
- __[math::constants](constants.md)__ - A set of well-known mathematical
constants, such as Pi, E, and the golden ratio
- __[math::fourier](fourier.md)__ - Discrete Fourier transforms
- __[math::fuzzy](fuzzy.md)__ - Fuzzy comparisons of floating-point numbers
- __[math::geometry](math_geometry.md)__ - 2D geometrical computations
- __[math::interpolate](interpolate.md)__ - Various interpolation methods
- __[math::linearalgebra](linalg.md)__ - Linear algebra package
- __[math::optimize](optimize.md)__ - Optimization methods
- __[math::polynomials](polynomials.md)__ - Polynomial arithmetic (includes
families of classical polynomials)
- __[math::rationalfunctions](rational_funcs.md)__ - Arithmetic of rational
functions
- __[math::roman](roman.md)__ - Manipulation (including arithmetic) of Roman
numerals
- __[math::special](special.md)__ - Approximations of special functions from
mathematical physics
- __[math::statistics](statistics.md)__ - Statistical operations and tests
# <a name='section2'></a>BASIC COMMANDS
- <a name='1'></a>__::math::cov__ *value* *value* ?*value ...*?
Return the coefficient of variation expressed as percent of two or more
numeric values.
- <a name='2'></a>__::math::integrate__ *list of xy value pairs*
Return the area under a "curve" defined by a set of x,y pairs and the error
bound as a list.
- <a name='3'></a>__::math::fibonacci__ *n*
Return the *n*'th Fibonacci number.
- <a name='4'></a>__::math::max__ *value* ?*value ...*?
Return the maximum of one or more numeric values.
- <a name='5'></a>__::math::mean__ *value* ?*value ...*?
Return the mean, or "average" of one or more numeric values.
- <a name='6'></a>__::math::min__ *value* ?*value ...*?
Return the minimum of one or more numeric values.
- <a name='7'></a>__::math::product__ *value* ?*value ...*?
Return the product of one or more numeric values.
- <a name='8'></a>__::math::random__ ?*value1*? ?*value2*?
Return a random number. If no arguments are given, the number is a floating
point value between 0 and 1. If one argument is given, the number is an
integer value between 0 and *value1*. If two arguments are given, the number
is an integer value between *value1* and *value2*.
- <a name='9'></a>__::math::sigma__ *value* *value* ?*value ...*?
Return the population standard deviation of two or more numeric values.
- <a name='10'></a>__::math::stats__ *value* *value* ?*value ...*?
Return the mean, standard deviation, and coefficient of variation (as
percent) as a list.
- <a name='11'></a>__::math::sum__ *value* ?*value ...*?
Return the sum of one or more numeric values.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math* 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.
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math), [statistics](../../../../index.md#statistics)
# <a name='category'></a>CATEGORY
Mathematics
|
Added embedded/md/tcllib/files/modules/math/math_geometry.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
|
[//000000001]: # (math::geometry - Tcl Math Library)
[//000000002]: # (Generated from file 'math_geometry.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::geometry(n) 1.3.0 tcllib "Tcl Math Library")
# NAME
math::geometry - Geometrical computations
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [References](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.5?
package require math::geometry ?1.3.0?
[__::math::geometry::+__ *point1* *point2*](#1)
[__::math::geometry::-__ *point1* *point2*](#2)
[__::math::geometry::p__ *x* *y*](#3)
[__::math::geometry::distance__ *point1* *point2*](#4)
[__::math::geometry::length__ *point*](#5)
[__::math::geometry::s*__ *factor* *point*](#6)
[__::math::geometry::direction__ *angle*](#7)
[__::math::geometry::h__ *length*](#8)
[__::math::geometry::v__ *length*](#9)
[__::math::geometry::between__ *point1* *point2* *s*](#10)
[__::math::geometry::octant__ *point*](#11)
[__::math::geometry::rect__ *nw* *se*](#12)
[__::math::geometry::nwse__ *rect*](#13)
[__::math::geometry::angle__ *line*](#14)
[__::math::geometry::calculateDistanceToLine__ *P* *line*](#15)
[__::math::geometry::calculateDistanceToLineSegment__ *P* *linesegment*](#16)
[__::math::geometry::calculateDistanceToPolyline__ *P* *polyline*](#17)
[__::math::geometry::calculateDistanceToPolygon__ *P* *polygon*](#18)
[__::math::geometry::findClosestPointOnLine__ *P* *line*](#19)
[__::math::geometry::findClosestPointOnLineSegment__ *P* *linesegment*](#20)
[__::math::geometry::findClosestPointOnPolyline__ *P* *polyline*](#21)
[__::math::geometry::lengthOfPolyline__ *polyline*](#22)
[__::math::geometry::movePointInDirection__ *P* *direction* *dist*](#23)
[__::math::geometry::lineSegmentsIntersect__ *linesegment1* *linesegment2*](#24)
[__::math::geometry::findLineSegmentIntersection__ *linesegment1* *linesegment2*](#25)
[__::math::geometry::findLineIntersection__ *line1* *line2*](#26)
[__::math::geometry::polylinesIntersect__ *polyline1* *polyline2*](#27)
[__::math::geometry::polylinesBoundingIntersect__ *polyline1* *polyline2* *granularity*](#28)
[__::math::geometry::intervalsOverlap__ *y1* *y2* *y3* *y4* *strict*](#29)
[__::math::geometry::rectanglesOverlap__ *P1* *P2* *Q1* *Q2* *strict*](#30)
[__::math::geometry::bbox__ *polyline*](#31)
[__::math::geometry::pointInsidePolygon__ *P* *polyline*](#32)
[__::math::geometry::pointInsidePolygonAlt__ *P* *polyline*](#33)
[__::math::geometry::rectangleInsidePolygon__ *P1* *P2* *polyline*](#34)
[__::math::geometry::areaPolygon__ *polygon*](#35)
[__::math::geometry::translate__ *vector* *polyline*](#36)
[__::math::geometry::rotate__ *angle* *polyline*](#37)
[__::math::geometry::reflect__ *angle* *polyline*](#38)
[__::math::geometry::degToRad__ *angle*](#39)
[__::math::geometry::radToDeg__ *angle*](#40)
[__::math::geometry::circle__ *centre* *radius*](#41)
[__::math::geometry::circleTwoPoints__ *point1* *point2*](#42)
[__::math::geometry::pointInsideCircle__ *point* *circle*](#43)
[__::math::geometry::lineIntersectsCircle__ *line* *circle*](#44)
[__::math::geometry::lineSegmentIntersectsCircle__ *segment* *circle*](#45)
[__::math::geometry::intersectionLineWithCircle__ *line* *circle*](#46)
[__::math::geometry::intersectionCircleWithCircle__ *circle1* *circle2*](#47)
[__::math::geometry::tangentLinesToCircle__ *point* *circle*](#48)
# <a name='description'></a>DESCRIPTION
The __math::geometry__ package is a collection of functions for computations and
manipulations on two-dimensional geometrical objects, such as points, lines and
polygons.
The geometrical objects are implemented as plain lists of coordinates. For
instance a line is defined by a list of four numbers, the x- and y-coordinate of
a first point and the x- and y-coordinates of a second point on the line.
The various types of object are recognised by the number of coordinate pairs and
the context in which they are used: a list of four elements can be regarded as
an infinite line, a finite line segment but also as a polyline of one segment
and a point set of two points.
Currently the following types of objects are distinguished:
- *point* - a list of two coordinates representing the x- and y-coordinates
respectively.
- *line* - a list of four coordinates, interpreted as the x- and y-coordinates
of two distinct points on the line.
- *line segment* - a list of four coordinates, interpreted as the x- and
y-coordinates of the first and the last points on the line segment.
- *polyline* - a list of an even number of coordinates, interpreted as the x-
and y-coordinates of an ordered set of points.
- *polygon* - like a polyline, but the implicit assumption is that the
polyline is closed (if the first and last points do not coincide, the
missing segment is automatically added).
- *point set* - again a list of an even number of coordinates, but the points
are regarded without any ordering.
- *circle* - a list of three numbers, the first two are the coordinates of the
centre and the third is the radius.
# <a name='section2'></a>PROCEDURES
The package defines the following public procedures:
- <a name='1'></a>__::math::geometry::+__ *point1* *point2*
Compute the sum of the two vectors given as points and return it. The result
is a vector as well.
- <a name='2'></a>__::math::geometry::-__ *point1* *point2*
Compute the difference (point1 - point2) of the two vectors given as points
and return it. The result is a vector as well.
- <a name='3'></a>__::math::geometry::p__ *x* *y*
Construct a point from its coordinates and return it as the result of the
command.
- <a name='4'></a>__::math::geometry::distance__ *point1* *point2*
Compute the distance between the two points and return it as the result of
the command. This is in essence the same as
math::geometry::length [math::geomtry::- point1 point2]
- <a name='5'></a>__::math::geometry::length__ *point*
Compute the length of the vector and return it as the result of the command.
- <a name='6'></a>__::math::geometry::s*__ *factor* *point*
Scale the vector by the factor and return it as the result of the command.
This is a vector as well.
- <a name='7'></a>__::math::geometry::direction__ *angle*
Given the angle in degrees this command computes and returns the unit vector
pointing into this direction. The vector for angle == 0 points to the right
(up), and for angle == 90 up (north).
- <a name='8'></a>__::math::geometry::h__ *length*
Returns a horizontal vector on the X-axis of the specified length. Positive
lengths point to the right (east).
- <a name='9'></a>__::math::geometry::v__ *length*
Returns a vertical vector on the Y-axis of the specified length. Positive
lengths point down (south).
- <a name='10'></a>__::math::geometry::between__ *point1* *point2* *s*
Compute the point which is at relative distance *s* between the two points
and return it as the result of the command. A relative distance of __0__
returns *point1*, the distance __1__ returns *point2*. Distances < 0 or > 1
extrapolate along the line between the two point.
- <a name='11'></a>__::math::geometry::octant__ *point*
Compute the octant of the circle the point is in and return it as the result
of the command. The possible results are
east
northeast
north
northwest
west
southwest
south
southeast
Each octant is the arc of the circle +/- 22.5 degrees from the cardinal
direction the octant is named for.
- <a name='12'></a>__::math::geometry::rect__ *nw* *se*
Construct a rectangle from its northwest and southeast corners and return it
as the result of the command.
- <a name='13'></a>__::math::geometry::nwse__ *rect*
Extract the northwest and southeast corners of the rectangle and return them
as the result of the command (a 2-element list containing the points, in the
named order).
- <a name='14'></a>__::math::geometry::angle__ *line*
Calculate the angle from the positive x-axis to a given line (in two
dimensions only).
* list *line*
Coordinates of the line
- <a name='15'></a>__::math::geometry::calculateDistanceToLine__ *P* *line*
Calculate the distance of point P to the (infinite) line and return the
result
* list *P*
List of two numbers, the coordinates of the point
* list *line*
List of four numbers, the coordinates of two points on the line
- <a name='16'></a>__::math::geometry::calculateDistanceToLineSegment__ *P* *linesegment*
Calculate the distance of point P to the (finite) line segment and return
the result.
* list *P*
List of two numbers, the coordinates of the point
* list *linesegment*
List of four numbers, the coordinates of the first and last points of
the line segment
- <a name='17'></a>__::math::geometry::calculateDistanceToPolyline__ *P* *polyline*
Calculate the distance of point P to the polyline and return the result.
Note that a polyline needs not to be closed.
* list *P*
List of two numbers, the coordinates of the point
* list *polyline*
List of numbers, the coordinates of the vertices of the polyline
- <a name='18'></a>__::math::geometry::calculateDistanceToPolygon__ *P* *polygon*
Calculate the distance of point P to the polygon and return the result. If
the list of coordinates is not closed (first and last points differ), it is
automatically closed.
* list *P*
List of two numbers, the coordinates of the point
* list *polygon*
List of numbers, the coordinates of the vertices of the polygon
- <a name='19'></a>__::math::geometry::findClosestPointOnLine__ *P* *line*
Return the point on a line which is closest to a given point.
* list *P*
List of two numbers, the coordinates of the point
* list *line*
List of four numbers, the coordinates of two points on the line
- <a name='20'></a>__::math::geometry::findClosestPointOnLineSegment__ *P* *linesegment*
Return the point on a *line segment* which is closest to a given point.
* list *P*
List of two numbers, the coordinates of the point
* list *linesegment*
List of four numbers, the first and last points on the line segment
- <a name='21'></a>__::math::geometry::findClosestPointOnPolyline__ *P* *polyline*
Return the point on a *polyline* which is closest to a given point.
* list *P*
List of two numbers, the coordinates of the point
* list *polyline*
List of numbers, the vertices of the polyline
- <a name='22'></a>__::math::geometry::lengthOfPolyline__ *polyline*
Return the length of the *polyline* (note: it not regarded as a polygon)
* list *polyline*
List of numbers, the vertices of the polyline
- <a name='23'></a>__::math::geometry::movePointInDirection__ *P* *direction* *dist*
Move a point over a given distance in a given direction and return the new
coordinates (in two dimensions only).
* list *P*
Coordinates of the point to be moved
* double *direction*
Direction (in degrees; 0 is to the right, 90 upwards)
* list *dist*
Distance over which to move the point
- <a name='24'></a>__::math::geometry::lineSegmentsIntersect__ *linesegment1* *linesegment2*
Check if two line segments intersect or coincide. Returns 1 if that is the
case, 0 otherwise (in two dimensions only). If an endpoint of one segment
lies on the other segment (or is very close to the segment), they are
considered to intersect
* list *linesegment1*
First line segment
* list *linesegment2*
Second line segment
- <a name='25'></a>__::math::geometry::findLineSegmentIntersection__ *linesegment1* *linesegment2*
Find the intersection point of two line segments. Return the coordinates or
the keywords "coincident" or "none" if the line segments coincide or have no
points in common (in two dimensions only).
* list *linesegment1*
First line segment
* list *linesegment2*
Second line segment
- <a name='26'></a>__::math::geometry::findLineIntersection__ *line1* *line2*
Find the intersection point of two (infinite) lines. Return the coordinates
or the keywords "coincident" or "none" if the lines coincide or have no
points in common (in two dimensions only).
* list *line1*
First line
* list *line2*
Second line
See section [References](#section3) for details on the algorithm and math
behind it.
- <a name='27'></a>__::math::geometry::polylinesIntersect__ *polyline1* *polyline2*
Check if two polylines intersect or not (in two dimensions only).
* list *polyline1*
First polyline
* list *polyline2*
Second polyline
- <a name='28'></a>__::math::geometry::polylinesBoundingIntersect__ *polyline1* *polyline2* *granularity*
Check whether two polylines intersect, but reduce the correctness of the
result to the given granularity. Use this for faster, but weaker,
intersection checking.
How it works:
Each polyline is split into a number of smaller polylines, consisting of
granularity points each. If a pair of those smaller lines' bounding boxes
intersect, then this procedure returns 1, otherwise it returns 0.
* list *polyline1*
First polyline
* list *polyline2*
Second polyline
* int *granularity*
Number of points in each part (<=1 means check every edge)
- <a name='29'></a>__::math::geometry::intervalsOverlap__ *y1* *y2* *y3* *y4* *strict*
Check if two intervals overlap.
* double *y1,y2*
Begin and end of first interval
* double *y3,y4*
Begin and end of second interval
* logical *strict*
Check for strict or non-strict overlap
- <a name='30'></a>__::math::geometry::rectanglesOverlap__ *P1* *P2* *Q1* *Q2* *strict*
Check if two rectangles overlap.
* list *P1*
upper-left corner of the first rectangle
* list *P2*
lower-right corner of the first rectangle
* list *Q1*
upper-left corner of the second rectangle
* list *Q2*
lower-right corner of the second rectangle
* list *strict*
choosing strict or non-strict interpretation
- <a name='31'></a>__::math::geometry::bbox__ *polyline*
Calculate the bounding box of a polyline. Returns a list of four
coordinates: the upper-left and the lower-right corner of the box.
* list *polyline*
The polyline to be examined
- <a name='32'></a>__::math::geometry::pointInsidePolygon__ *P* *polyline*
Determine if a point is completely inside a polygon. If the point touches
the polygon, then the point is not completely inside the polygon.
* list *P*
Coordinates of the point
* list *polyline*
The polyline to be examined
- <a name='33'></a>__::math::geometry::pointInsidePolygonAlt__ *P* *polyline*
Determine if a point is completely inside a polygon. If the point touches
the polygon, then the point is not completely inside the polygon. *Note:*
this alternative procedure uses the so-called winding number to determine
this. It handles self-intersecting polygons in a "natural" way.
* list *P*
Coordinates of the point
* list *polyline*
The polyline to be examined
- <a name='34'></a>__::math::geometry::rectangleInsidePolygon__ *P1* *P2* *polyline*
Determine if a rectangle is completely inside a polygon. If polygon touches
the rectangle, then the rectangle is not complete inside the polygon.
* list *P1*
Upper-left corner of the rectangle
* list *P2*
Lower-right corner of the rectangle
* list *polygon*
The polygon in question
- <a name='35'></a>__::math::geometry::areaPolygon__ *polygon*
Calculate the area of a polygon.
* list *polygon*
The polygon in question
- <a name='36'></a>__::math::geometry::translate__ *vector* *polyline*
Translate a polyline over a given vector
* list *vector*
Translation vector
* list *polyline*
The polyline to be rotated
- <a name='37'></a>__::math::geometry::rotate__ *angle* *polyline*
Rotate a polyline over a given angle (degrees) around the origin
* list *angle*
Angle over which to rotate the polyline (degrees)
* list *polyline*
The polyline to be translated
- <a name='38'></a>__::math::geometry::reflect__ *angle* *polyline*
Reflect a polyline in a line through the origin at a given angle (degrees)
to the x-axis
* list *angle*
Angle of the line of reflection (degrees)
* list *polyline*
The polyline to be reflected
- <a name='39'></a>__::math::geometry::degToRad__ *angle*
Convert from degrees to radians
* list *angle*
Angle in degrees
- <a name='40'></a>__::math::geometry::radToDeg__ *angle*
Convert from radians to degrees
* list *angle*
Angle in radians
- <a name='41'></a>__::math::geometry::circle__ *centre* *radius*
Convenience procedure to create a circle from a point and a radius.
* list *centre*
Coordinates of the circle centre
* list *radius*
Radius of the circle
- <a name='42'></a>__::math::geometry::circleTwoPoints__ *point1* *point2*
Convenience procedure to create a circle from two points on its
circumference The centre is the point between the two given points, the
radius is half the distance between them.
* list *point1*
First point
* list *point2*
Second point
- <a name='43'></a>__::math::geometry::pointInsideCircle__ *point* *circle*
Determine if the given point is inside the circle or on the circumference
(1) or outside (0).
* list *point*
Point to be checked
* list *circle*
Circle that may or may not contain the point
- <a name='44'></a>__::math::geometry::lineIntersectsCircle__ *line* *circle*
Determine if the given line intersects the circle or touches it (1) or does
not (0).
* list *line*
Line to be checked
* list *circle*
Circle that may or may not be intersected
- <a name='45'></a>__::math::geometry::lineSegmentIntersectsCircle__ *segment* *circle*
Determine if the given line segment intersects the circle or touches it (1)
or does not (0).
* list *segment*
Line segment to be checked
* list *circle*
Circle that may or may not be intersected
- <a name='46'></a>__::math::geometry::intersectionLineWithCircle__ *line* *circle*
Determine the points at which the given line intersects the circle. There
can be zero, one or two points. (If the line touches the circle or is close
to it, then one point is returned. An arbitrary margin of 1.0e-10 times the
radius is used to determine this situation.)
* list *line*
Line to be checked
* list *circle*
Circle that may or may not be intersected
- <a name='47'></a>__::math::geometry::intersectionCircleWithCircle__ *circle1* *circle2*
Determine the points at which the given two circles intersect. There can be
zero, one or two points. (If the two circles touch the circle or are very
close, then one point is returned. An arbitrary margin of 1.0e-10 times the
mean of the radii of the two circles is used to determine this situation.)
* list *circle1*
First circle
* list *circle2*
Second circle
- <a name='48'></a>__::math::geometry::tangentLinesToCircle__ *point* *circle*
Determine the tangent lines from the given point to the circle. There can be
zero, one or two lines. (If the point is on the cirucmference or very close
to the circle, then one line is returned. An arbitrary margin of 1.0e-10
times the radius of the circle is used to determine this situation.)
* list *point*
Point in question
* list *circle*
Circle to which the tangent lines are to be determined
# <a name='section3'></a>References
1. [Polygon Intersection](http:/wiki.tcl.tk/12070)
1. [http://en.wikipedia.org/wiki/Line-line_intersection](http://en.wikipedia.org/wiki/Line-line_intersection)
1. [http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/](http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/)
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: geometry* 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.
# <a name='keywords'></a>KEYWORDS
[angle](../../../../index.md#angle), [distance](../../../../index.md#distance),
[line](../../../../index.md#line), [math](../../../../index.md#math), [plane
geometry](../../../../index.md#plane_geometry),
[point](../../../../index.md#point)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2001 by Ideogramic ApS and other parties
Copyright © 2010 by Andreas Kupries
Copyright © 2010 by Kevin Kenny
Copyright © 2018 by Arjen Markus
|
Added embedded/md/tcllib/files/modules/math/numtheory.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
[//000000001]: # (math::numtheory - Tcl Math Library)
[//000000002]: # (Generated from file 'numtheory.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::numtheory(n) 1.1.1 tcllib "Tcl Math Library")
# NAME
math::numtheory - Number Theory
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.5?
package require math::numtheory ?1.1.1?
[__math::numtheory::isprime__ *N* ?*option* *value* ...?](#1)
[__math::numtheory::firstNprimes__ *N*](#2)
[__math::numtheory::primesLowerThan__ *N*](#3)
[__math::numtheory::primeFactors__ *N*](#4)
[__math::numtheory::primesLowerThan__ *N*](#5)
[__math::numtheory::primeFactors__ *N*](#6)
[__math::numtheory::uniquePrimeFactors__ *N*](#7)
[__math::numtheory::factors__ *N*](#8)
[__math::numtheory::totient__ *N*](#9)
[__math::numtheory::moebius__ *N*](#10)
[__math::numtheory::legendre__ *a* *p*](#11)
[__math::numtheory::jacobi__ *a* *b*](#12)
[__math::numtheory::gcd__ *m* *n*](#13)
[__math::numtheory::lcm__ *m* *n*](#14)
[__math::numtheory::numberPrimesGauss__ *N*](#15)
[__math::numtheory::numberPrimesLegendre__ *N*](#16)
[__math::numtheory::numberPrimesLegendreModified__ *N*](#17)
# <a name='description'></a>DESCRIPTION
This package is for collecting various number-theoretic operations, with a
slight bias to prime numbers.
- <a name='1'></a>__math::numtheory::isprime__ *N* ?*option* *value* ...?
The __isprime__ command tests whether the integer *N* is a prime, returning
a boolean true value for prime *N* and a boolean false value for non-prime
*N*. The formal definition of 'prime' used is the conventional, that the
number being tested is greater than 1 and only has trivial divisors.
To be precise, the return value is one of __0__ (if *N* is definitely not a
prime), __1__ (if *N* is definitely a prime), and __on__ (if *N* is probably
prime); the latter two are both boolean true values. The case that an
integer may be classified as "probably prime" arises because the
Miller-Rabin algorithm used in the test implementation is basically
probabilistic, and may if we are unlucky fail to detect that a number is in
fact composite. Options may be used to select the risk of such "false
positives" in the test. __1__ is returned for "small" *N* (which currently
means *N* < 118670087467), where it is known that no false positives are
possible.
The only option currently defined is:
* __-randommr__ *repetitions*
which controls how many times the Miller-Rabin test should be repeated
with randomly chosen bases. Each repetition reduces the probability of a
false positive by a factor at least 4. The default for *repetitions* is
4.
Unknown options are silently ignored.
- <a name='2'></a>__math::numtheory::firstNprimes__ *N*
Return the first N primes
* integer *N* (in)
Number of primes to return
- <a name='3'></a>__math::numtheory::primesLowerThan__ *N*
Return the prime numbers lower/equal to N
* integer *N* (in)
Maximum number to consider
- <a name='4'></a>__math::numtheory::primeFactors__ *N*
Return a list of the prime numbers in the number N
* integer *N* (in)
Number to be factorised
- <a name='5'></a>__math::numtheory::primesLowerThan__ *N*
Return the prime numbers lower/equal to N
* integer *N* (in)
Maximum number to consider
- <a name='6'></a>__math::numtheory::primeFactors__ *N*
Return a list of the prime numbers in the number N
* integer *N* (in)
Number to be factorised
- <a name='7'></a>__math::numtheory::uniquePrimeFactors__ *N*
Return a list of the *unique* prime numbers in the number N
* integer *N* (in)
Number to be factorised
- <a name='8'></a>__math::numtheory::factors__ *N*
Return a list of all *unique* factors in the number N, including 1 and N
itself
* integer *N* (in)
Number to be factorised
- <a name='9'></a>__math::numtheory::totient__ *N*
Evaluate the Euler totient function for the number N (number of numbers
relatively prime to N)
* integer *N* (in)
Number in question
- <a name='10'></a>__math::numtheory::moebius__ *N*
Evaluate the Moebius function for the number N
* integer *N* (in)
Number in question
- <a name='11'></a>__math::numtheory::legendre__ *a* *p*
Evaluate the Legendre symbol (a/p)
* integer *a* (in)
Upper number in the symbol
* integer *p* (in)
Lower number in the symbol (must be non-zero)
- <a name='12'></a>__math::numtheory::jacobi__ *a* *b*
Evaluate the Jacobi symbol (a/b)
* integer *a* (in)
Upper number in the symbol
* integer *b* (in)
Lower number in the symbol (must be odd)
- <a name='13'></a>__math::numtheory::gcd__ *m* *n*
Return the greatest common divisor of *m* and *n*
* integer *m* (in)
First number
* integer *n* (in)
Second number
- <a name='14'></a>__math::numtheory::lcm__ *m* *n*
Return the lowest common multiple of *m* and *n*
* integer *m* (in)
First number
* integer *n* (in)
Second number
- <a name='15'></a>__math::numtheory::numberPrimesGauss__ *N*
Estimate the number of primes according the formula by Gauss.
* integer *N* (in)
Number in question
- <a name='16'></a>__math::numtheory::numberPrimesLegendre__ *N*
Estimate the number of primes according the formula by Legendre.
* integer *N* (in)
Number in question
- <a name='17'></a>__math::numtheory::numberPrimesLegendreModified__ *N*
Estimate the number of primes according the modified formula by Legendre.
* integer *N* (in)
Number in question
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: numtheory* 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.
# <a name='keywords'></a>KEYWORDS
[number theory](../../../../index.md#number_theory),
[prime](../../../../index.md#prime)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010 Lars Hellström <Lars dot Hellstrom at residenset dot net>
|
Added embedded/md/tcllib/files/modules/math/optimize.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
[//000000001]: # (math::optimize - Tcl Math Library)
[//000000002]: # (Generated from file 'optimize.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::optimize(n) 1.0 tcllib "Tcl Math Library")
# NAME
math::optimize - Optimisation routines
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [NOTES](#section3)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require math::optimize ?1.0?
[__::math::optimize::minimum__ *begin* *end* *func* *maxerr*](#1)
[__::math::optimize::maximum__ *begin* *end* *func* *maxerr*](#2)
[__::math::optimize::min_bound_1d__ *func* *begin* *end* ?__-relerror__ *reltol*? ?__-abserror__ *abstol*? ?__-maxiter__ *maxiter*? ?__-trace__ *traceflag*?](#3)
[__::math::optimize::min_unbound_1d__ *func* *begin* *end* ?__-relerror__ *reltol*? ?__-abserror__ *abstol*? ?__-maxiter__ *maxiter*? ?__-trace__ *traceflag*?](#4)
[__::math::optimize::solveLinearProgram__ *objective* *constraints*](#5)
[__::math::optimize::linearProgramMaximum__ *objective* *result*](#6)
[__::math::optimize::nelderMead__ *objective* *xVector* ?__-scale__ *xScaleVector*? ?__-ftol__ *epsilon*? ?__-maxiter__ *count*? ??-trace? *flag*?](#7)
# <a name='description'></a>DESCRIPTION
This package implements several optimisation algorithms:
- Minimize or maximize a function over a given interval
- Solve a linear program (maximize a linear function subject to linear
constraints)
- Minimize a function of several variables given an initial guess for the
location of the minimum.
The package is fully implemented in Tcl. No particular attention has been paid
to the accuracy of the calculations. Instead, the algorithms have been used in a
straightforward manner.
This document describes the procedures and explains their usage.
# <a name='section2'></a>PROCEDURES
This package defines the following public procedures:
- <a name='1'></a>__::math::optimize::minimum__ *begin* *end* *func* *maxerr*
Minimize the given (continuous) function by examining the values in the
given interval. The procedure determines the values at both ends and in the
centre of the interval and then constructs a new interval of 1/2 length that
includes the minimum. No guarantee is made that the *global* minimum is
found.
The procedure returns the "x" value for which the function is minimal.
*This procedure has been deprecated - use min_bound_1d instead*
*begin* - Start of the interval
*end* - End of the interval
*func* - Name of the function to be minimized (a procedure taking one
argument).
*maxerr* - Maximum relative error (defaults to 1.0e-4)
- <a name='2'></a>__::math::optimize::maximum__ *begin* *end* *func* *maxerr*
Maximize the given (continuous) function by examining the values in the
given interval. The procedure determines the values at both ends and in the
centre of the interval and then constructs a new interval of 1/2 length that
includes the maximum. No guarantee is made that the *global* maximum is
found.
The procedure returns the "x" value for which the function is maximal.
*This procedure has been deprecated - use max_bound_1d instead*
*begin* - Start of the interval
*end* - End of the interval
*func* - Name of the function to be maximized (a procedure taking one
argument).
*maxerr* - Maximum relative error (defaults to 1.0e-4)
- <a name='3'></a>__::math::optimize::min_bound_1d__ *func* *begin* *end* ?__-relerror__ *reltol*? ?__-abserror__ *abstol*? ?__-maxiter__ *maxiter*? ?__-trace__ *traceflag*?
Miminizes a function of one variable in the given interval. The procedure
uses Brent's method of parabolic interpolation, protected by golden-section
subdivisions if the interpolation is not converging. No guarantee is made
that a *global* minimum is found. The function to evaluate, *func*, must be
a single Tcl command; it will be evaluated with an abscissa appended as the
last argument.
*x1* and *x2* are the two bounds of the interval in which the minimum is to
be found. They need not be in increasing order.
*reltol*, if specified, is the desired upper bound on the relative error of
the result; default is 1.0e-7. The given value should never be smaller than
the square root of the machine's floating point precision, or else
convergence is not guaranteed. *abstol*, if specified, is the desired upper
bound on the absolute error of the result; default is 1.0e-10. Caution must
be used with small values of *abstol* to avoid overflow/underflow
conditions; if the minimum is expected to lie about a small but non-zero
abscissa, you consider either shifting the function or changing its length
scale.
*maxiter* may be used to constrain the number of function evaluations to be
performed; default is 100. If the command evaluates the function more than
*maxiter* times, it returns an error to the caller.
*traceFlag* is a Boolean value. If true, it causes the command to print a
message on the standard output giving the abscissa and ordinate at each
function evaluation, together with an indication of what type of
interpolation was chosen. Default is 0 (no trace).
- <a name='4'></a>__::math::optimize::min_unbound_1d__ *func* *begin* *end* ?__-relerror__ *reltol*? ?__-abserror__ *abstol*? ?__-maxiter__ *maxiter*? ?__-trace__ *traceflag*?
Miminizes a function of one variable over the entire real number line. The
procedure uses parabolic extrapolation combined with golden-section
dilatation to search for a region where a minimum exists, followed by
Brent's method of parabolic interpolation, protected by golden-section
subdivisions if the interpolation is not converging. No guarantee is made
that a *global* minimum is found. The function to evaluate, *func*, must be
a single Tcl command; it will be evaluated with an abscissa appended as the
last argument.
*x1* and *x2* are two initial guesses at where the minimum may lie. *x1* is
the starting point for the minimization, and the difference between *x2* and
*x1* is used as a hint at the characteristic length scale of the problem.
*reltol*, if specified, is the desired upper bound on the relative error of
the result; default is 1.0e-7. The given value should never be smaller than
the square root of the machine's floating point precision, or else
convergence is not guaranteed. *abstol*, if specified, is the desired upper
bound on the absolute error of the result; default is 1.0e-10. Caution must
be used with small values of *abstol* to avoid overflow/underflow
conditions; if the minimum is expected to lie about a small but non-zero
abscissa, you consider either shifting the function or changing its length
scale.
*maxiter* may be used to constrain the number of function evaluations to be
performed; default is 100. If the command evaluates the function more than
*maxiter* times, it returns an error to the caller.
*traceFlag* is a Boolean value. If true, it causes the command to print a
message on the standard output giving the abscissa and ordinate at each
function evaluation, together with an indication of what type of
interpolation was chosen. Default is 0 (no trace).
- <a name='5'></a>__::math::optimize::solveLinearProgram__ *objective* *constraints*
Solve a *linear program* in standard form using a straightforward
implementation of the Simplex algorithm. (In the explanation below: The
linear program has N constraints and M variables).
The procedure returns a list of M values, the values for which the objective
function is maximal or a single keyword if the linear program is not
feasible or unbounded (either "unfeasible" or "unbounded")
*objective* - The M coefficients of the objective function
*constraints* - Matrix of coefficients plus maximum values that implement
the linear constraints. It is expected to be a list of N lists of M+1
numbers each, M coefficients and the maximum value.
- <a name='6'></a>__::math::optimize::linearProgramMaximum__ *objective* *result*
Convenience function to return the maximum for the solution found by the
solveLinearProgram procedure.
*objective* - The M coefficients of the objective function
*result* - The result as returned by solveLinearProgram
- <a name='7'></a>__::math::optimize::nelderMead__ *objective* *xVector* ?__-scale__ *xScaleVector*? ?__-ftol__ *epsilon*? ?__-maxiter__ *count*? ??-trace? *flag*?
Minimizes, in unconstrained fashion, a function of several variable over all
of space. The function to evaluate, *objective*, must be a single Tcl
command. To it will be appended as many elements as appear in the initial
guess at the location of the minimum, passed in as a Tcl list, *xVector*.
*xScaleVector* is an initial guess at the problem scale; the first function
evaluations will be made by varying the co-ordinates in *xVector* by the
amounts in *xScaleVector*. If *xScaleVector* is not supplied, the
co-ordinates will be varied by a factor of 1.0001 (if the co-ordinate is
non-zero) or by a constant 0.0001 (if the co-ordinate is zero).
*epsilon* is the desired relative error in the value of the function
evaluated at the minimum. The default is 1.0e-7, which usually gives three
significant digits of accuracy in the values of the x's.
pp *count* is a limit on the number of trips through the main loop of the
optimizer. The number of function evaluations may be several times this
number. If the optimizer fails to find a minimum to within *ftol* in
*maxiter* iterations, it returns its current best guess and an error status.
Default is to allow 500 iterations.
*flag* is a flag that, if true, causes a line to be written to the standard
output for each evaluation of the objective function, giving the arguments
presented to the function and the value returned. Default is false.
The __nelderMead__ procedure returns a list of alternating keywords and
values suitable for use with __array set__. The meaning of the keywords is:
*x* is the approximate location of the minimum.
*y* is the value of the function at *x*.
*yvec* is a vector of the best N+1 function values achieved, where N is the
dimension of *x*
*vertices* is a list of vectors giving the function arguments corresponding
to the values in *yvec*.
*nIter* is the number of iterations required to achieve convergence or fail.
*status* is 'ok' if the operation succeeded, or 'too-many-iterations' if the
maximum iteration count was exceeded.
__nelderMead__ minimizes the given function using the downhill simplex
method of Nelder and Mead. This method is quite slow - much faster methods
for minimization are known - but has the advantage of being extremely robust
in the face of problems where the minimum lies in a valley of complex
topology.
__nelderMead__ can occasionally find itself "stuck" at a point where it can
make no further progress; it is recommended that the caller run it at least
a second time, passing as the initial guess the result found by the previous
call. The second run is usually very fast.
__nelderMead__ can be used in some cases for constrained optimization. To do
this, add a large value to the objective function if the parameters are
outside the feasible region. To work effectively in this mode,
__nelderMead__ requires that the initial guess be feasible and usually
requires that the feasible region be convex.
# <a name='section3'></a>NOTES
Several of the above procedures take the *names* of procedures as arguments. To
avoid problems with the *visibility* of these procedures, the fully-qualified
name of these procedures is determined inside the optimize routines. For the
user this has only one consequence: the named procedure must be visible in the
calling procedure. For instance:
namespace eval ::mySpace {
namespace export calcfunc
proc calcfunc { x } { return $x }
}
#
# Use a fully-qualified name
#
namespace eval ::myCalc {
puts [min_bound_1d ::myCalc::calcfunc $begin $end]
}
#
# Import the name
#
namespace eval ::myCalc {
namespace import ::mySpace::calcfunc
puts [min_bound_1d calcfunc $begin $end]
}
The simple procedures *minimum* and *maximum* have been deprecated: the
alternatives are much more flexible, robust and require less function
evaluations.
# <a name='section4'></a>EXAMPLES
Let us take a few simple examples:
Determine the maximum of f(x) = x^3 exp(-3x), on the interval (0,10):
proc efunc { x } { expr {$x*$x*$x * exp(-3.0*$x)} }
puts "Maximum at: [::math::optimize::max_bound_1d efunc 0.0 10.0]"
The maximum allowed error determines the number of steps taken (with each step
in the iteration the interval is reduced with a factor 1/2). Hence, a maximum
error of 0.0001 is achieved in approximately 14 steps.
An example of a *linear program* is:
Optimise the expression 3x+2y, where:
x >= 0 and y >= 0 (implicit constraints, part of the
definition of linear programs)
x + y <= 1 (constraints specific to the problem)
2x + 5y <= 10
This problem can be solved as follows:
set solution [::math::optimize::solveLinearProgram { 3.0 2.0 } { { 1.0 1.0 1.0 }
{ 2.0 5.0 10.0 } } ]
Note, that a constraint like:
x + y >= 1
can be turned into standard form using:
-x -y <= -1
The theory of linear programming is the subject of many a text book and the
Simplex algorithm that is implemented here is the best-known method to solve
this type of problems, but it is not the only one.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: optimize* 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.
# <a name='keywords'></a>KEYWORDS
[linear program](../../../../index.md#linear_program),
[math](../../../../index.md#math), [maximum](../../../../index.md#maximum),
[minimum](../../../../index.md#minimum),
[optimization](../../../../index.md#optimization)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
Copyright © 2004,2005 Kevn B. Kenny <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/pca.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
[//000000001]: # (math::PCA - Principal Components Analysis)
[//000000002]: # (Generated from file 'pca.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::PCA(n) 1.0 tcllib "Principal Components Analysis")
# NAME
math::PCA - Package for Principal Component Analysis
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [EXAMPLE](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.6?
package require math::linearalgebra 1.0
[__::math::PCA::createPCA__ *data* ?args?](#1)
[__$pca using__ ?number?|?-minproportion value?](#2)
[__$pca eigenvectors__ ?option?](#3)
[__$pca eigenvalues__ ?option?](#4)
[__$pca proportions__ ?option?](#5)
[__$pca approximate__ *observation*](#6)
[__$pca approximatOriginal__](#7)
[__$pca scores__ *observation*](#8)
[__$pca distance__ *observation*](#9)
[__$pca qstatistic__ *observation* ?option?](#10)
# <a name='description'></a>DESCRIPTION
The PCA package provides a means to perform principal components analysis in
Tcl, using an object-oriented technique as facilitated by TclOO. It actually
defines a single public method, *::math::PCA::createPCA*, which constructs an
object based on the data that are passed to perform the actual analysis.
The methods of the PCA objects that are created with this command allow one to
examine the principal components, to approximate (new) observations using all or
a selected number of components only and to examine the properties of the
components and the statistics of the approximations.
The package has been modelled after the PCA example provided by the original
linear algebra package by Ed Hume.
# <a name='section2'></a>Commands
The *math::PCA* package provides one public command:
- <a name='1'></a>__::math::PCA::createPCA__ *data* ?args?
Create a new object, based on the data that are passed via the *data*
argument. The principal components may be based on either correlations or
covariances. All observations will be normalised according to the mean and
standard deviation of the original data.
* list *data*
- A list of observations (see the example below).
* list *args*
- A list of key-value pairs defining the options. Currently there is
only one key: *-covariances*. This indicates if covariances are to be
used (if the value is 1) or instead correlations (value is 0). The
default is to use correlations.
The PCA object that is created has the following methods:
- <a name='2'></a>__$pca using__ ?number?|?-minproportion value?
Set the number of components to be used in the analysis (the number of
retained components). Returns the number of components, also if no argument
is given.
* int *number*
- The number of components to be retained
* double *value*
- Select the number of components based on the minimum proportion of
variation that is retained by them. Should be a value between 0 and 1.
- <a name='3'></a>__$pca eigenvectors__ ?option?
Return the eigenvectors as a list of lists.
* string *option*
- By default only the *retained* components are returned. If all
eigenvectors are required, use the option *-all*.
- <a name='4'></a>__$pca eigenvalues__ ?option?
Return the eigenvalues as a list of lists.
* string *option*
- By default only the eigenvalues of the *retained* components are
returned. If all eigenvalues are required, use the option *-all*.
- <a name='5'></a>__$pca proportions__ ?option?
Return the proportions for all components, that is, the amount of variations
that each components can explain.
- <a name='6'></a>__$pca approximate__ *observation*
Return an approximation of the observation based on the retained components
* list *observation*
- The values for the observation.
- <a name='7'></a>__$pca approximatOriginal__
Return an approximation of the original data, using the retained components.
It is a convenience method that works on the complete set of original data.
- <a name='8'></a>__$pca scores__ *observation*
Return the scores per retained component for the given observation.
* list *observation*
- The values for the observation.
- <a name='9'></a>__$pca distance__ *observation*
Return the distance between the given observation and its approximation.
(Note: this distance is based on the normalised vectors.)
* list *observation*
- The values for the observation.
- <a name='10'></a>__$pca qstatistic__ *observation* ?option?
Return the Q statistic, basically the square of the distance, for the given
observation.
* list *observation*
- The values for the observation.
* string *option*
- If the observation is part of the original data, you may want to use
the corrected Q statistic. This is achieved with the option "-original".
# <a name='section3'></a>EXAMPLE
TODO: NIST example
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *PCA* 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.
# <a name='keywords'></a>KEYWORDS
[PCA](../../../../index.md#pca), [math](../../../../index.md#math),
[statistics](../../../../index.md#statistics), [tcl](../../../../index.md#tcl)
# <a name='category'></a>CATEGORY
Mathematics
|
Added embedded/md/tcllib/files/modules/math/polynomials.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
[//000000001]: # (math::polynomials - Tcl Math Library)
[//000000002]: # (Generated from file 'polynomials.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::polynomials(n) 1.0.1 tcllib "Tcl Math Library")
# NAME
math::polynomials - Polynomial functions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [REMARKS ON THE IMPLEMENTATION](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.3?
package require math::polynomials ?1.0.1?
[__::math::polynomials::polynomial__ *coeffs*](#1)
[__::math::polynomials::polynCmd__ *coeffs*](#2)
[__::math::polynomials::evalPolyn__ *polynomial* *x*](#3)
[__::math::polynomials::addPolyn__ *polyn1* *polyn2*](#4)
[__::math::polynomials::subPolyn__ *polyn1* *polyn2*](#5)
[__::math::polynomials::multPolyn__ *polyn1* *polyn2*](#6)
[__::math::polynomials::divPolyn__ *polyn1* *polyn2*](#7)
[__::math::polynomials::remainderPolyn__ *polyn1* *polyn2*](#8)
[__::math::polynomials::derivPolyn__ *polyn*](#9)
[__::math::polynomials::primitivePolyn__ *polyn*](#10)
[__::math::polynomials::degreePolyn__ *polyn*](#11)
[__::math::polynomials::coeffPolyn__ *polyn* *index*](#12)
[__::math::polynomials::allCoeffsPolyn__ *polyn*](#13)
# <a name='description'></a>DESCRIPTION
This package deals with polynomial functions of one variable:
- the basic arithmetic operations are extended to polynomials
- computing the derivatives and primitives of these functions
- evaluation through a general procedure or via specific procedures)
# <a name='section2'></a>PROCEDURES
The package defines the following public procedures:
- <a name='1'></a>__::math::polynomials::polynomial__ *coeffs*
Return an (encoded) list that defines the polynomial. A polynomial
f(x) = a + b.x + c.x**2 + d.x**3
can be defined via:
set f [::math::polynomials::polynomial [list $a $b $c $d]
* list *coeffs*
Coefficients of the polynomial (in ascending order)
- <a name='2'></a>__::math::polynomials::polynCmd__ *coeffs*
Create a new procedure that evaluates the polynomial. The name of the
polynomial is automatically generated. Useful if you need to evualuate the
polynomial many times, as the procedure consists of a single [expr] command.
* list *coeffs*
Coefficients of the polynomial (in ascending order) or the polynomial
definition returned by the *polynomial* command.
- <a name='3'></a>__::math::polynomials::evalPolyn__ *polynomial* *x*
Evaluate the polynomial at x.
* list *polynomial*
The polynomial's definition (as returned by the polynomial command).
order)
* float *x*
The coordinate at which to evaluate the polynomial
- <a name='4'></a>__::math::polynomials::addPolyn__ *polyn1* *polyn2*
Return a new polynomial which is the sum of the two others.
* list *polyn1*
The first polynomial operand
* list *polyn2*
The second polynomial operand
- <a name='5'></a>__::math::polynomials::subPolyn__ *polyn1* *polyn2*
Return a new polynomial which is the difference of the two others.
* list *polyn1*
The first polynomial operand
* list *polyn2*
The second polynomial operand
- <a name='6'></a>__::math::polynomials::multPolyn__ *polyn1* *polyn2*
Return a new polynomial which is the product of the two others. If one of
the arguments is a scalar value, the other polynomial is simply scaled.
* list *polyn1*
The first polynomial operand or a scalar
* list *polyn2*
The second polynomial operand or a scalar
- <a name='7'></a>__::math::polynomials::divPolyn__ *polyn1* *polyn2*
Divide the first polynomial by the second polynomial and return the result.
The remainder is dropped
* list *polyn1*
The first polynomial operand
* list *polyn2*
The second polynomial operand
- <a name='8'></a>__::math::polynomials::remainderPolyn__ *polyn1* *polyn2*
Divide the first polynomial by the second polynomial and return the
remainder.
* list *polyn1*
The first polynomial operand
* list *polyn2*
The second polynomial operand
- <a name='9'></a>__::math::polynomials::derivPolyn__ *polyn*
Differentiate the polynomial and return the result.
* list *polyn*
The polynomial to be differentiated
- <a name='10'></a>__::math::polynomials::primitivePolyn__ *polyn*
Integrate the polynomial and return the result. The integration constant is
set to zero.
* list *polyn*
The polynomial to be integrated
- <a name='11'></a>__::math::polynomials::degreePolyn__ *polyn*
Return the degree of the polynomial.
* list *polyn*
The polynomial to be examined
- <a name='12'></a>__::math::polynomials::coeffPolyn__ *polyn* *index*
Return the coefficient of the term of the index'th degree of the polynomial.
* list *polyn*
The polynomial to be examined
* int *index*
The degree of the term
- <a name='13'></a>__::math::polynomials::allCoeffsPolyn__ *polyn*
Return the coefficients of the polynomial (in ascending order).
* list *polyn*
The polynomial in question
# <a name='section3'></a>REMARKS ON THE IMPLEMENTATION
The implementation for evaluating the polynomials at some point uses Horn's
rule, which guarantees numerical stability and a minimum of arithmetic
operations. To recognise that a polynomial definition is indeed a correct
definition, it consists of a list of two elements: the keyword "POLYNOMIAL" and
the list of coefficients in descending order. The latter makes it easier to
implement Horner's rule.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: polynomials* 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.
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math), [polynomial
functions](../../../../index.md#polynomial_functions)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/qcomplex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
[//000000001]: # (math::complexnumbers - Tcl Math Library)
[//000000002]: # (Generated from file 'qcomplex.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::complexnumbers(n) 1.0.2 tcllib "Tcl Math Library")
# NAME
math::complexnumbers - Straightforward complex number package
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [AVAILABLE PROCEDURES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require math::complexnumbers ?1.0.2?
[__::math::complexnumbers::+__ *z1* *z2*](#1)
[__::math::complexnumbers::-__ *z1* *z2*](#2)
[__::math::complexnumbers::*__ *z1* *z2*](#3)
[__::math::complexnumbers::/__ *z1* *z2*](#4)
[__::math::complexnumbers::conj__ *z1*](#5)
[__::math::complexnumbers::real__ *z1*](#6)
[__::math::complexnumbers::imag__ *z1*](#7)
[__::math::complexnumbers::mod__ *z1*](#8)
[__::math::complexnumbers::arg__ *z1*](#9)
[__::math::complexnumbers::complex__ *real* *imag*](#10)
[__::math::complexnumbers::tostring__ *z1*](#11)
[__::math::complexnumbers::exp__ *z1*](#12)
[__::math::complexnumbers::sin__ *z1*](#13)
[__::math::complexnumbers::cos__ *z1*](#14)
[__::math::complexnumbers::tan__ *z1*](#15)
[__::math::complexnumbers::log__ *z1*](#16)
[__::math::complexnumbers::sqrt__ *z1*](#17)
[__::math::complexnumbers::pow__ *z1* *z2*](#18)
# <a name='description'></a>DESCRIPTION
The mathematical module *complexnumbers* provides a straightforward
implementation of complex numbers in pure Tcl. The philosophy is that the user
knows he or she is dealing with complex numbers in an abstract way and wants as
high a performance as can be had within the limitations of an interpreted
language.
Therefore the procedures defined in this package assume that the arguments are
valid (representations of) "complex numbers", that is, lists of two numbers
defining the real and imaginary part of a complex number (though this is a mere
detail: rely on the *complex* command to construct a valid number.)
Most procedures implement the basic arithmetic operations or elementary
functions whereas several others convert to and from different representations:
set z [complex 0 1]
puts "z = [tostring $z]"
puts "z**2 = [* $z $z]
would result in:
z = i
z**2 = -1
# <a name='section2'></a>AVAILABLE PROCEDURES
The package implements all or most basic operations and elementary functions.
*The arithmetic operations are:*
- <a name='1'></a>__::math::complexnumbers::+__ *z1* *z2*
Add the two arguments and return the resulting complex number
* complex *z1* (in)
First argument in the summation
* complex *z2* (in)
Second argument in the summation
- <a name='2'></a>__::math::complexnumbers::-__ *z1* *z2*
Subtract the second argument from the first and return the resulting complex
number. If there is only one argument, the opposite of z1 is returned (i.e.
-z1)
* complex *z1* (in)
First argument in the subtraction
* complex *z2* (in)
Second argument in the subtraction (optional)
- <a name='3'></a>__::math::complexnumbers::*__ *z1* *z2*
Multiply the two arguments and return the resulting complex number
* complex *z1* (in)
First argument in the multiplication
* complex *z2* (in)
Second argument in the multiplication
- <a name='4'></a>__::math::complexnumbers::/__ *z1* *z2*
Divide the first argument by the second and return the resulting complex
number
* complex *z1* (in)
First argument (numerator) in the division
* complex *z2* (in)
Second argument (denominator) in the division
- <a name='5'></a>__::math::complexnumbers::conj__ *z1*
Return the conjugate of the given complex number
* complex *z1* (in)
Complex number in question
*Conversion/inquiry procedures:*
- <a name='6'></a>__::math::complexnumbers::real__ *z1*
Return the real part of the given complex number
* complex *z1* (in)
Complex number in question
- <a name='7'></a>__::math::complexnumbers::imag__ *z1*
Return the imaginary part of the given complex number
* complex *z1* (in)
Complex number in question
- <a name='8'></a>__::math::complexnumbers::mod__ *z1*
Return the modulus of the given complex number
* complex *z1* (in)
Complex number in question
- <a name='9'></a>__::math::complexnumbers::arg__ *z1*
Return the argument ("angle" in radians) of the given complex number
* complex *z1* (in)
Complex number in question
- <a name='10'></a>__::math::complexnumbers::complex__ *real* *imag*
Construct the complex number "real + imag*i" and return it
* float *real* (in)
The real part of the new complex number
* float *imag* (in)
The imaginary part of the new complex number
- <a name='11'></a>__::math::complexnumbers::tostring__ *z1*
Convert the complex number to the form "real + imag*i" and return the string
* float *complex* (in)
The complex number to be converted
*Elementary functions:*
- <a name='12'></a>__::math::complexnumbers::exp__ *z1*
Calculate the exponential for the given complex argument and return the
result
* complex *z1* (in)
The complex argument for the function
- <a name='13'></a>__::math::complexnumbers::sin__ *z1*
Calculate the sine function for the given complex argument and return the
result
* complex *z1* (in)
The complex argument for the function
- <a name='14'></a>__::math::complexnumbers::cos__ *z1*
Calculate the cosine function for the given complex argument and return the
result
* complex *z1* (in)
The complex argument for the function
- <a name='15'></a>__::math::complexnumbers::tan__ *z1*
Calculate the tangent function for the given complex argument and return the
result
* complex *z1* (in)
The complex argument for the function
- <a name='16'></a>__::math::complexnumbers::log__ *z1*
Calculate the (principle value of the) logarithm for the given complex
argument and return the result
* complex *z1* (in)
The complex argument for the function
- <a name='17'></a>__::math::complexnumbers::sqrt__ *z1*
Calculate the (principle value of the) square root for the given complex
argument and return the result
* complex *z1* (in)
The complex argument for the function
- <a name='18'></a>__::math::complexnumbers::pow__ *z1* *z2*
Calculate "z1 to the power of z2" and return the result
* complex *z1* (in)
The complex number to be raised to a power
* complex *z2* (in)
The complex power to be used
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: complexnumbers* 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.
# <a name='keywords'></a>KEYWORDS
[complex numbers](../../../../index.md#complex_numbers),
[math](../../../../index.md#math)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/rational_funcs.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
[//000000001]: # (math::rationalfunctions - Math)
[//000000002]: # (Generated from file 'rational_funcs.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::rationalfunctions(n) 1.0.1 tcllib "Math")
# NAME
math::rationalfunctions - Polynomial functions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [REMARKS ON THE IMPLEMENTATION](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require math::rationalfunctions ?1.0.1?
[__::math::rationalfunctions::rationalFunction__ *num* *den*](#1)
[__::math::rationalfunctions::ratioCmd__ *num* *den*](#2)
[__::math::rationalfunctions::evalRatio__ *rational* *x*](#3)
[__::math::rationalfunctions::addRatio__ *ratio1* *ratio2*](#4)
[__::math::rationalfunctions::subRatio__ *ratio1* *ratio2*](#5)
[__::math::rationalfunctions::multRatio__ *ratio1* *ratio2*](#6)
[__::math::rationalfunctions::divRatio__ *ratio1* *ratio2*](#7)
[__::math::rationalfunctions::derivPolyn__ *ratio*](#8)
[__::math::rationalfunctions::coeffsNumerator__ *ratio*](#9)
[__::math::rationalfunctions::coeffsDenominator__ *ratio*](#10)
# <a name='description'></a>DESCRIPTION
This package deals with rational functions of one variable:
- the basic arithmetic operations are extended to rational functions
- computing the derivatives of these functions
- evaluation through a general procedure or via specific procedures)
# <a name='section2'></a>PROCEDURES
The package defines the following public procedures:
- <a name='1'></a>__::math::rationalfunctions::rationalFunction__ *num* *den*
Return an (encoded) list that defines the rational function. A rational
function
1 + x^3
f(x) = ------------
1 + 2x + x^2
can be defined via:
set f [::math::rationalfunctions::rationalFunction [list 1 0 0 1] [list 1 2 1]]
* list *num*
Coefficients of the numerator of the rational function (in ascending
order)
* list *den*
Coefficients of the denominator of the rational function (in ascending
order)
- <a name='2'></a>__::math::rationalfunctions::ratioCmd__ *num* *den*
Create a new procedure that evaluates the rational function. The name of the
function is automatically generated. Useful if you need to evaluate the
function many times, as the procedure consists of a single [expr] command.
* list *num*
Coefficients of the numerator of the rational function (in ascending
order)
* list *den*
Coefficients of the denominator of the rational function (in ascending
order)
- <a name='3'></a>__::math::rationalfunctions::evalRatio__ *rational* *x*
Evaluate the rational function at x.
* list *rational*
The rational function's definition (as returned by the rationalFunction
command). order)
* float *x*
The coordinate at which to evaluate the function
- <a name='4'></a>__::math::rationalfunctions::addRatio__ *ratio1* *ratio2*
Return a new rational function which is the sum of the two others.
* list *ratio1*
The first rational function operand
* list *ratio2*
The second rational function operand
- <a name='5'></a>__::math::rationalfunctions::subRatio__ *ratio1* *ratio2*
Return a new rational function which is the difference of the two others.
* list *ratio1*
The first rational function operand
* list *ratio2*
The second rational function operand
- <a name='6'></a>__::math::rationalfunctions::multRatio__ *ratio1* *ratio2*
Return a new rational function which is the product of the two others. If
one of the arguments is a scalar value, the other rational function is
simply scaled.
* list *ratio1*
The first rational function operand or a scalar
* list *ratio2*
The second rational function operand or a scalar
- <a name='7'></a>__::math::rationalfunctions::divRatio__ *ratio1* *ratio2*
Divide the first rational function by the second rational function and
return the result. The remainder is dropped
* list *ratio1*
The first rational function operand
* list *ratio2*
The second rational function operand
- <a name='8'></a>__::math::rationalfunctions::derivPolyn__ *ratio*
Differentiate the rational function and return the result.
* list *ratio*
The rational function to be differentiated
- <a name='9'></a>__::math::rationalfunctions::coeffsNumerator__ *ratio*
Return the coefficients of the numerator of the rational function.
* list *ratio*
The rational function to be examined
- <a name='10'></a>__::math::rationalfunctions::coeffsDenominator__ *ratio*
Return the coefficients of the denominator of the rational function.
* list *ratio*
The rational function to be examined
# <a name='section3'></a>REMARKS ON THE IMPLEMENTATION
The implementation of the rational functions relies on the math::polynomials
package. For further remarks see the documentation on that package.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: rationalfunctions*
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.
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math), [rational
functions](../../../../index.md#rational_functions)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/roman.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
[//000000001]: # (math::roman - Tcl Math Library)
[//000000002]: # (Generated from file 'roman.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::roman() 1.0 tcllib "Tcl Math Library")
# NAME
math::roman - Tools for creating and manipulating roman numerals
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require math::roman ?1.0?
[__::math::roman::toroman__ *i*](#1)
[__::math::roman::tointeger__ *r*](#2)
[__::math::roman::sort__ *list*](#3)
[__::math::roman::expr__ *args*](#4)
# <a name='description'></a>DESCRIPTION
__::math::roman__ is a pure-Tcl library for converting between integers and
roman numerals. It also provides utility functions for sorting and performing
arithmetic on roman numerals.
This code was originally harvested from the Tcler's wiki at
http://wiki.tcl.tk/1823 and as such is free for any use for any purpose. Many
thanks to the ingeneous folk who devised these clever routines and generously
contributed them to the Tcl community.
While written and tested under Tcl 8.3, I expect this library will work under
all 8.x versions of Tcl.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::math::roman::toroman__ *i*
Convert an integer to roman numerals. The result is always in upper case.
The value zero is converted to an empty string.
- <a name='2'></a>__::math::roman::tointeger__ *r*
Convert a roman numeral into an integer.
- <a name='3'></a>__::math::roman::sort__ *list*
Sort a list of roman numerals from smallest to largest.
- <a name='4'></a>__::math::roman::expr__ *args*
Evaluate an expression where the operands are all roman numerals.
Of these commands both *toroman* and *tointeger* are exported for easier use.
The other two are not, as they could interfer or be confused with existing Tcl
commands.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: roman* 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.
# <a name='keywords'></a>KEYWORDS
[conversion](../../../../index.md#conversion),
[integer](../../../../index.md#integer), [roman
numeral](../../../../index.md#roman_numeral)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Kenneth Green <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/romberg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
|
[//000000001]: # (math::calculus::romberg - Tcl Math Library)
[//000000002]: # (Generated from file 'romberg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::calculus::romberg(n) 0.6 tcllib "Tcl Math Library")
# NAME
math::calculus::romberg - Romberg integration
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [PARAMETERS](#section3)
- [OPTIONS](#section4)
- [DESCRIPTION](#section5)
- [IMPROPER INTEGRALS](#section6)
- [OTHER CHANGES OF VARIABLE](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [See Also](#see-also)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require math::calculus 0.6
[__::math::calculus::romberg__ *f* *a* *b* ?*-option value*...?](#1)
[__::math::calculus::romberg_infinity__ *f* *a* *b* ?*-option value*...?](#2)
[__::math::calculus::romberg_sqrtSingLower__ *f* *a* *b* ?*-option value*...?](#3)
[__::math::calculus::romberg_sqrtSingUpper__ *f* *a* *b* ?*-option value*...?](#4)
[__::math::calculus::romberg_powerLawLower__ *gamma* *f* *a* *b* ?*-option value*...?](#5)
[__::math::calculus::romberg_powerLawUpper__ *gamma* *f* *a* *b* ?*-option value*...?](#6)
[__::math::calculus::romberg_expLower__ *f* *a* *b* ?*-option value*...?](#7)
[__::math::calculus::romberg_expUpper__ *f* *a* *b* ?*-option value*...?](#8)
# <a name='description'></a>DESCRIPTION
The __romberg__ procedures in the __[math::calculus](calculus.md)__ package
perform numerical integration of a function of one variable. They are intended
to be of "production quality" in that they are robust, precise, and reasonably
efficient in terms of the number of function evaluations.
# <a name='section2'></a>PROCEDURES
The following procedures are available for Romberg integration:
- <a name='1'></a>__::math::calculus::romberg__ *f* *a* *b* ?*-option value*...?
Integrates an analytic function over a given interval.
- <a name='2'></a>__::math::calculus::romberg_infinity__ *f* *a* *b* ?*-option value*...?
Integrates an analytic function over a half-infinite interval.
- <a name='3'></a>__::math::calculus::romberg_sqrtSingLower__ *f* *a* *b* ?*-option value*...?
Integrates a function that is expected to be analytic over an interval
except for the presence of an inverse square root singularity at the lower
limit.
- <a name='4'></a>__::math::calculus::romberg_sqrtSingUpper__ *f* *a* *b* ?*-option value*...?
Integrates a function that is expected to be analytic over an interval
except for the presence of an inverse square root singularity at the upper
limit.
- <a name='5'></a>__::math::calculus::romberg_powerLawLower__ *gamma* *f* *a* *b* ?*-option value*...?
Integrates a function that is expected to be analytic over an interval
except for the presence of a power law singularity at the lower limit.
- <a name='6'></a>__::math::calculus::romberg_powerLawUpper__ *gamma* *f* *a* *b* ?*-option value*...?
Integrates a function that is expected to be analytic over an interval
except for the presence of a power law singularity at the upper limit.
- <a name='7'></a>__::math::calculus::romberg_expLower__ *f* *a* *b* ?*-option value*...?
Integrates an exponentially growing function; the lower limit of the region
of integration may be arbitrarily large and negative.
- <a name='8'></a>__::math::calculus::romberg_expUpper__ *f* *a* *b* ?*-option value*...?
Integrates an exponentially decaying function; the upper limit of the region
of integration may be arbitrarily large.
# <a name='section3'></a>PARAMETERS
- *f*
Function to integrate. Must be expressed as a single Tcl command, to which
will be appended a single argument, specifically, the abscissa at which the
function is to be evaluated. The first word of the command will be processed
with __namespace which__ in the caller's scope prior to any evaluation.
Given this processing, the command may local to the calling namespace rather
than needing to be global.
- *a*
Lower limit of the region of integration.
- *b*
Upper limit of the region of integration. For the __romberg_sqrtSingLower__,
__romberg_sqrtSingUpper__, __romberg_powerLawLower__,
__romberg_powerLawUpper__, __romberg_expLower__, and __romberg_expUpper__
procedures, the lower limit must be strictly less than the upper. For the
other procedures, the limits may appear in either order.
- *gamma*
Power to use for a power law singularity; see section [IMPROPER
INTEGRALS](#section6) for details.
# <a name='section4'></a>OPTIONS
- __-abserror__ *epsilon*
Requests that the integration machinery proceed at most until the estimated
absolute error of the integral is less than *epsilon*. The error may be
seriously over- or underestimated if the function (or any of its
derivatives) contains singularities; see section [IMPROPER
INTEGRALS](#section6) for details. Default is 1.0e-08.
- __-relerror__ *epsilon*
Requests that the integration machinery proceed at most until the estimated
relative error of the integral is less than *epsilon*. The error may be
seriously over- or underestimated if the function (or any of its
derivatives) contains singularities; see section [IMPROPER
INTEGRALS](#section6) for details. Default is 1.0e-06.
- __-maxiter__ *m*
Requests that integration terminate after at most *n* triplings of the
number of evaluations performed. In other words, given *n* for __-maxiter__,
the integration machinery will make at most 3***n* evaluations of the
function. Default is 14, corresponding to a limit approximately 4.8 million
evaluations. (Well-behaved functions will seldom require more than a few
hundred evaluations.)
- __-degree__ *d*
Requests that an extrapolating polynomial of degree *d* be used in Romberg
integration; see section [DESCRIPTION](#section5) for details. Default is 4.
Can be at most *m*-1.
# <a name='section5'></a>DESCRIPTION
The __romberg__ procedure performs Romberg integration using the modified
midpoint rule. Romberg integration is an iterative process. At the first step,
the function is evaluated at the midpoint of the region of integration, and the
value is multiplied by the width of the interval for the coarsest possible
estimate. At the second step, the interval is divided into three parts, and the
function is evaluated at the midpoint of each part; the sum of the values is
multiplied by three. At the third step, nine parts are used, at the fourth
twenty-seven, and so on, tripling the number of subdivisions at each step.
Once the interval has been divided at least *d* times, a polynomial is fitted to
the integrals estimated in the last *d*+1 divisions. The integrals are
considered to be a function of the square of the width of the subintervals (any
good numerical analysis text will discuss this process under "Romberg
integration"). The polynomial is extrapolated to a step size of zero, computing
a value for the integral and an estimate of the error.
This process will be well-behaved only if the function is analytic over the
region of integration; there may be removable singularities at either end of the
region provided that the limit of the function (and of all its derivatives)
exists as the ends are approached. Thus, __romberg__ may be used to integrate a
function like f(x)=sin(x)/x over an interval beginning or ending at zero.
Note that __romberg__ will either fail to converge or else return incorrect
error estimates if the function, or any of its derivatives, has a singularity
anywhere in the region of integration (except for the case mentioned above).
Care must be used, therefore, in integrating a function like 1/(1-x**2) to avoid
the places where the derivative is singular.
# <a name='section6'></a>IMPROPER INTEGRALS
Romberg integration is also useful for integrating functions over half-infinite
intervals or functions that have singularities. The trick is to make a change of
variable to eliminate the singularity, and to put the singularity at one end or
the other of the region of integration. The __[math::calculus](calculus.md)__
package supplies a number of __romberg__ procedures to deal with the commoner
cases.
- __romberg_infinity__
Integrates a function over a half-infinite interval; either *a* or *b* may
be infinite. *a* and *b* must be of the same sign; if you need to integrate
across the axis, say, from a negative value to positive infinity, use
__romberg__ to integrate from the negative value to a small positive value,
and then __romberg_infinity__ to integrate from the positive value to
positive infinity. The __romberg_infinity__ procedure works by making the
change of variable u=1/x, so that the integral from a to b of f(x) is
evaluated as the integral from 1/a to 1/b of f(1/u)/u**2.
- __romberg_powerLawLower__ and __romberg_powerLawUpper__
Integrate a function that has an integrable power law singularity at either
the lower or upper bound of the region of integration (or has a derivative
with a power law singularity there). These procedures take a first
parameter, *gamma*, which gives the power law. The function or its first
derivative are presumed to diverge as (x-*a*)**(-*gamma*) or
(*b*-x)**(-*gamma*). *gamma* must be greater than zero and less than 1.
These procedures are useful not only in integrating functions that go to
infinity at one end of the region of integration, but also functions whose
derivatives do not exist at the end of the region. For instance, integrating
f(x)=pow(x,0.25) with the origin as one end of the region will result in the
__romberg__ procedure greatly underestimating the error in the integral. The
problem can be fixed by observing that the first derivative of f(x),
f'(x)=x**(-3/4)/4, goes to infinity at the origin. Integrating using
__romberg_powerLawLower__ with *gamma* set to 0.75 gives much more orderly
convergence.
These procedures operate by making the change of variable u=(x-a)**(1-gamma)
(__romberg_powerLawLower__) or u=(b-x)**(1-gamma)
(__romberg_powerLawUpper__).
To summarize the meaning of gamma:
If f(x) ~ x**(-a) (0 < a < 1), use gamma = a
If f'(x) ~ x**(-b) (0 < b < 1), use gamma = b
- __romberg_sqrtSingLower__ and __romberg_sqrtSingUpper__
These procedures behave identically to __romberg_powerLawLower__ and
__romberg_powerLawUpper__ for the common case of *gamma*=0.5; that is, they
integrate a function with an inverse square root singularity at one end of
the interval. They have a simpler implementation involving square roots
rather than arbitrary powers.
- __romberg_expLower__ and __romberg_expUpper__
These procedures are for integrating a function that grows or decreases
exponentially over a half-infinite interval. __romberg_expLower__ handles
exponentially growing functions, and allows the lower limit of integration
to be an arbitrarily large negative number. __romberg_expUpper__ handles
exponentially decaying functions and allows the upper limit of integration
to be an arbitrary large positive number. The functions make the change of
variable u=exp(-x) and u=exp(x) respectively.
# <a name='section7'></a>OTHER CHANGES OF VARIABLE
If you need an improper integral other than the ones listed here, a change of
variable can be written in very few lines of Tcl. Because the Tcl coding that
does it is somewhat arcane, we offer a worked example here.
Let's say that the function that we want to integrate is f(x)=exp(x)/sqrt(1-x*x)
(not a very natural function, but a good example), and we want to integrate it
over the interval (-1,1). The denominator falls to zero at both ends of the
interval. We wish to make a change of variable from x to u so that
dx/sqrt(1-x**2) maps to du. Choosing x=sin(u), we can find that dx=cos(u)*du,
and sqrt(1-x**2)=cos(u). The integral from a to b of f(x) is the integral from
asin(a) to asin(b) of f(sin(u))*cos(u).
We can make a function __g__ that accepts an arbitrary function __f__ and the
parameter u, and computes this new integrand.
proc g { f u } {
set x [expr { sin($u) }]
set cmd $f; lappend cmd $x; set y [eval $cmd]
return [expr { $y / cos($u) }]
}
Now integrating __f__ from *a* to *b* is the same as integrating __g__ from
*asin(a)* to *asin(b)*. It's a little tricky to get __f__ consistently evaluated
in the caller's scope; the following procedure does it.
proc romberg_sine { f a b args } {
set f [lreplace $f 0 0 [uplevel 1 [list namespace which [lindex $f 0]]]]
set f [list g $f]
return [eval [linsert $args 0 romberg $f [expr { asin($a) }] [expr { asin($b) }]]]
}
This __romberg_sine__ procedure will do any function with sqrt(1-x*x) in the
denominator. Our sample function is f(x)=exp(x)/sqrt(1-x*x):
proc f { x } {
expr { exp($x) / sqrt( 1. - $x*$x ) }
}
Integrating it is a matter of applying __romberg_sine__ as we would any of the
other __romberg__ procedures:
foreach { value error } [romberg_sine f -1.0 1.0] break
puts [format "integral is %.6g +/- %.6g" $value $error]
integral is 3.97746 +/- 2.3557e-010
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: calculus* 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.
# <a name='see-also'></a>SEE ALSO
[math::calculus](calculus.md), [math::interpolate](interpolate.md)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Kevin B. Kenny <[email protected]>. All rights reserved. Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>
|
Added embedded/md/tcllib/files/modules/math/special.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
|
[//000000001]: # (math::special - Tcl Math Library)
[//000000002]: # (Generated from file 'special.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::special(n) 0.3 tcllib "Tcl Math Library")
# NAME
math::special - Special mathematical functions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [OVERVIEW](#section2)
- [PROCEDURES](#section3)
- [THE ORTHOGONAL POLYNOMIALS](#section4)
- [REMARKS ON THE IMPLEMENTATION](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.3?
package require math::special ?0.3?
[__::math::special::Beta__ *x* *y*](#1)
[__::math::special::Gamma__ *x*](#2)
[__::math::special::erf__ *x*](#3)
[__::math::special::erfc__ *x*](#4)
[__::math::special::invnorm__ *p*](#5)
[__::math::special::J0__ *x*](#6)
[__::math::special::J1__ *x*](#7)
[__::math::special::Jn__ *n* *x*](#8)
[__::math::special::J1/2__ *x*](#9)
[__::math::special::J-1/2__ *x*](#10)
[__::math::special::I_n__ *x*](#11)
[__::math::special::cn__ *u* *k*](#12)
[__::math::special::dn__ *u* *k*](#13)
[__::math::special::sn__ *u* *k*](#14)
[__::math::special::elliptic_K__ *k*](#15)
[__::math::special::elliptic_E__ *k*](#16)
[__::math::special::exponential_Ei__ *x*](#17)
[__::math::special::exponential_En__ *n* *x*](#18)
[__::math::special::exponential_li__ *x*](#19)
[__::math::special::exponential_Ci__ *x*](#20)
[__::math::special::exponential_Si__ *x*](#21)
[__::math::special::exponential_Chi__ *x*](#22)
[__::math::special::exponential_Shi__ *x*](#23)
[__::math::special::fresnel_C__ *x*](#24)
[__::math::special::fresnel_S__ *x*](#25)
[__::math::special::sinc__ *x*](#26)
[__::math::special::legendre__ *n*](#27)
[__::math::special::chebyshev__ *n*](#28)
[__::math::special::laguerre__ *alpha* *n*](#29)
[__::math::special::hermite__ *n*](#30)
# <a name='description'></a>DESCRIPTION
This package implements several so-called special functions, like the Gamma
function, the Bessel functions and such.
Each function is implemented by a procedure that bears its name (well, in close
approximation):
- J0 for the zeroth-order Bessel function of the first kind
- J1 for the first-order Bessel function of the first kind
- Jn for the nth-order Bessel function of the first kind
- J1/2 for the half-order Bessel function of the first kind
- J-1/2 for the minus-half-order Bessel function of the first kind
- I_n for the modified Bessel function of the first kind of order n
- Gamma for the Gamma function, erf and erfc for the error function and the
complementary error function
- fresnel_C and fresnel_S for the Fresnel integrals
- elliptic_K and elliptic_E (complete elliptic integrals)
- exponent_Ei and other functions related to the so-called exponential
integrals
- legendre, hermite: some of the classical orthogonal polynomials.
# <a name='section2'></a>OVERVIEW
In the following table several characteristics of the functions in this package
are summarized: the domain for the argument, the values for the parameters and
error bounds.
Family | Function | Domain x | Parameter | Error bound
-------------+-------------+-------------+-------------+--------------
Bessel | J0, J1, | all of R | n = integer | < 1.0e-8
| Jn | | | (|x|<20, n<20)
Bessel | J1/2, J-1/2,| x > 0 | n = integer | exact
Bessel | I_n | all of R | n = integer | < 1.0e-6
| | | |
Elliptic | cn | 0 <= x <= 1 | -- | < 1.0e-10
functions | dn | 0 <= x <= 1 | -- | < 1.0e-10
| sn | 0 <= x <= 1 | -- | < 1.0e-10
Elliptic | K | 0 <= x < 1 | -- | < 1.0e-6
integrals | E | 0 <= x < 1 | -- | < 1.0e-6
| | | |
Error | erf | | -- |
functions | erfc | | |
| | | |
Inverse | invnorm | 0 < x < 1 | -- | < 1.2e-9
normal | | | |
distribution | | | |
| | | |
Exponential | Ei | x != 0 | -- | < 1.0e-10 (relative)
integrals | En | x > 0 | -- | as Ei
| li | x > 0 | -- | as Ei
| Chi | x > 0 | -- | < 1.0e-8
| Shi | x > 0 | -- | < 1.0e-8
| Ci | x > 0 | -- | < 2.0e-4
| Si | x > 0 | -- | < 2.0e-4
| | | |
Fresnel | C | all of R | -- | < 2.0e-3
integrals | S | all of R | -- | < 2.0e-3
| | | |
general | Beta | (see Gamma) | -- | < 1.0e-9
| Gamma | x != 0,-1, | -- | < 1.0e-9
| | -2, ... | |
| sinc | all of R | -- | exact
| | | |
orthogonal | Legendre | all of R | n = 0,1,... | exact
polynomials | Chebyshev | all of R | n = 0,1,... | exact
| Laguerre | all of R | n = 0,1,... | exact
| | | alpha el. R |
| Hermite | all of R | n = 0,1,... | exact
*Note:* Some of the error bounds are estimated, as no "formal" bounds were
available with the implemented approximation method, others hold for the
auxiliary functions used for estimating the primary functions.
The following well-known functions are currently missing from the package:
- Bessel functions of the second kind (Y_n, K_n)
- Bessel functions of arbitrary order (and hence the Airy functions)
- Chebyshev polynomials of the second kind (U_n)
- The digamma function (psi)
- The incomplete gamma and beta functions
# <a name='section3'></a>PROCEDURES
The package defines the following public procedures:
- <a name='1'></a>__::math::special::Beta__ *x* *y*
Compute the Beta function for arguments "x" and "y"
* float *x*
First argument for the Beta function
* float *y*
Second argument for the Beta function
- <a name='2'></a>__::math::special::Gamma__ *x*
Compute the Gamma function for argument "x"
* float *x*
Argument for the Gamma function
- <a name='3'></a>__::math::special::erf__ *x*
Compute the error function for argument "x"
* float *x*
Argument for the error function
- <a name='4'></a>__::math::special::erfc__ *x*
Compute the complementary error function for argument "x"
* float *x*
Argument for the complementary error function
- <a name='5'></a>__::math::special::invnorm__ *p*
Compute the inverse of the normal distribution function for argument "p"
* float *p*
Argument for the inverse normal distribution function (p must be greater
than 0 and lower than 1)
- <a name='6'></a>__::math::special::J0__ *x*
Compute the zeroth-order Bessel function of the first kind for the argument
"x"
* float *x*
Argument for the Bessel function
- <a name='7'></a>__::math::special::J1__ *x*
Compute the first-order Bessel function of the first kind for the argument
"x"
* float *x*
Argument for the Bessel function
- <a name='8'></a>__::math::special::Jn__ *n* *x*
Compute the nth-order Bessel function of the first kind for the argument "x"
* integer *n*
Order of the Bessel function
* float *x*
Argument for the Bessel function
- <a name='9'></a>__::math::special::J1/2__ *x*
Compute the half-order Bessel function of the first kind for the argument
"x"
* float *x*
Argument for the Bessel function
- <a name='10'></a>__::math::special::J-1/2__ *x*
Compute the minus-half-order Bessel function of the first kind for the
argument "x"
* float *x*
Argument for the Bessel function
- <a name='11'></a>__::math::special::I_n__ *x*
Compute the modified Bessel function of the first kind of order n for the
argument "x"
* int *x*
Positive integer order of the function
* float *x*
Argument for the function
- <a name='12'></a>__::math::special::cn__ *u* *k*
Compute the elliptic function *cn* for the argument "u" and parameter "k".
* float *u*
Argument for the function
* float *k*
Parameter
- <a name='13'></a>__::math::special::dn__ *u* *k*
Compute the elliptic function *dn* for the argument "u" and parameter "k".
* float *u*
Argument for the function
* float *k*
Parameter
- <a name='14'></a>__::math::special::sn__ *u* *k*
Compute the elliptic function *sn* for the argument "u" and parameter "k".
* float *u*
Argument for the function
* float *k*
Parameter
- <a name='15'></a>__::math::special::elliptic_K__ *k*
Compute the complete elliptic integral of the first kind for the argument
"k"
* float *k*
Argument for the function
- <a name='16'></a>__::math::special::elliptic_E__ *k*
Compute the complete elliptic integral of the second kind for the argument
"k"
* float *k*
Argument for the function
- <a name='17'></a>__::math::special::exponential_Ei__ *x*
Compute the exponential integral of the second kind for the argument "x"
* float *x*
Argument for the function (x != 0)
- <a name='18'></a>__::math::special::exponential_En__ *n* *x*
Compute the exponential integral of the first kind for the argument "x" and
order n
* int *n*
Order of the integral (n >= 0)
* float *x*
Argument for the function (x >= 0)
- <a name='19'></a>__::math::special::exponential_li__ *x*
Compute the logarithmic integral for the argument "x"
* float *x*
Argument for the function (x > 0)
- <a name='20'></a>__::math::special::exponential_Ci__ *x*
Compute the cosine integral for the argument "x"
* float *x*
Argument for the function (x > 0)
- <a name='21'></a>__::math::special::exponential_Si__ *x*
Compute the sine integral for the argument "x"
* float *x*
Argument for the function (x > 0)
- <a name='22'></a>__::math::special::exponential_Chi__ *x*
Compute the hyperbolic cosine integral for the argument "x"
* float *x*
Argument for the function (x > 0)
- <a name='23'></a>__::math::special::exponential_Shi__ *x*
Compute the hyperbolic sine integral for the argument "x"
* float *x*
Argument for the function (x > 0)
- <a name='24'></a>__::math::special::fresnel_C__ *x*
Compute the Fresnel cosine integral for real argument x
* float *x*
Argument for the function
- <a name='25'></a>__::math::special::fresnel_S__ *x*
Compute the Fresnel sine integral for real argument x
* float *x*
Argument for the function
- <a name='26'></a>__::math::special::sinc__ *x*
Compute the sinc function for real argument x
* float *x*
Argument for the function
- <a name='27'></a>__::math::special::legendre__ *n*
Return the Legendre polynomial of degree n (see [THE ORTHOGONAL
POLYNOMIALS](#section4))
* int *n*
Degree of the polynomial
- <a name='28'></a>__::math::special::chebyshev__ *n*
Return the Chebyshev polynomial of degree n (of the first kind)
* int *n*
Degree of the polynomial
- <a name='29'></a>__::math::special::laguerre__ *alpha* *n*
Return the Laguerre polynomial of degree n with parameter alpha
* float *alpha*
Parameter of the Laguerre polynomial
* int *n*
Degree of the polynomial
- <a name='30'></a>__::math::special::hermite__ *n*
Return the Hermite polynomial of degree n
* int *n*
Degree of the polynomial
# <a name='section4'></a>THE ORTHOGONAL POLYNOMIALS
For dealing with the classical families of orthogonal polynomials, the package
relies on the *math::polynomials* package. To evaluate the polynomial at some
coordinate, use the *evalPolyn* command:
set leg2 [::math::special::legendre 2]
puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]"
The return value from the *legendre* and other commands is actually the
definition of the corresponding polynomial as used in that package.
# <a name='section5'></a>REMARKS ON THE IMPLEMENTATION
It should be noted, that the actual implementation of J0 and J1 depends on
straightforward Gaussian quadrature formulas. The (absolute) accuracy of the
results is of the order 1.0e-4 or better. The main reason to implement them like
that was that it was fast to do (the formulas are simple) and the computations
are fast too.
The implementation of J1/2 does not suffer from this: this function can be
expressed exactly in terms of elementary functions.
The functions J0 and J1 are the ones you will encounter most frequently in
practice.
The computation of I_n is based on Miller's algorithm for computing the minimal
function from recurrence relations.
The computation of the Gamma and Beta functions relies on the combinatorics
package, whereas that of the error functions relies on the statistics package.
The computation of the complete elliptic integrals uses the AGM algorithm.
Much information about these functions can be found in:
Abramowitz and Stegun: *Handbook of Mathematical Functions* (Dover, ISBN
486-61272-4)
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: special* 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.
# <a name='keywords'></a>KEYWORDS
[Bessel functions](../../../../index.md#bessel_functions), [error
function](../../../../index.md#error_function),
[math](../../../../index.md#math), [special
functions](../../../../index.md#special_functions)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/math/statistics.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
|
[//000000001]: # (math::statistics - Tcl Math Library)
[//000000002]: # (Generated from file 'statistics.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::statistics(n) 1 tcllib "Tcl Math Library")
# NAME
math::statistics - Basic statistical functions and procedures
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [GENERAL PROCEDURES](#section2)
- [MULTIVARIATE LINEAR REGRESSION](#section3)
- [STATISTICAL DISTRIBUTIONS](#section4)
- [DATA MANIPULATION](#section5)
- [PLOT PROCEDURES](#section6)
- [THINGS TO DO](#section7)
- [EXAMPLES](#section8)
- [Bugs, Ideas, Feedback](#section9)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require math::statistics 1
[__::math::statistics::mean__ *data*](#1)
[__::math::statistics::min__ *data*](#2)
[__::math::statistics::max__ *data*](#3)
[__::math::statistics::number__ *data*](#4)
[__::math::statistics::stdev__ *data*](#5)
[__::math::statistics::var__ *data*](#6)
[__::math::statistics::pstdev__ *data*](#7)
[__::math::statistics::pvar__ *data*](#8)
[__::math::statistics::median__ *data*](#9)
[__::math::statistics::basic-stats__ *data*](#10)
[__::math::statistics::histogram__ *limits* *values* ?weights?](#11)
[__::math::statistics::histogram-alt__ *limits* *values* ?weights?](#12)
[__::math::statistics::corr__ *data1* *data2*](#13)
[__::math::statistics::interval-mean-stdev__ *data* *confidence*](#14)
[__::math::statistics::t-test-mean__ *data* *est_mean* *est_stdev* *alpha*](#15)
[__::math::statistics::test-normal__ *data* *significance*](#16)
[__::math::statistics::lillieforsFit__ *data*](#17)
[__::math::statistics::test-Duckworth__ *list1* *list2* *significance*](#18)
[__::math::statistics::test-anova-F__ *alpha* *args*](#19)
[__::math::statistics::test-Tukey-range__ *alpha* *args*](#20)
[__::math::statistics::test-Dunnett__ *alpha* *control* *args*](#21)
[__::math::statistics::quantiles__ *data* *confidence*](#22)
[__::math::statistics::quantiles__ *limits* *counts* *confidence*](#23)
[__::math::statistics::autocorr__ *data*](#24)
[__::math::statistics::crosscorr__ *data1* *data2*](#25)
[__::math::statistics::mean-histogram-limits__ *mean* *stdev* *number*](#26)
[__::math::statistics::minmax-histogram-limits__ *min* *max* *number*](#27)
[__::math::statistics::linear-model__ *xdata* *ydata* *intercept*](#28)
[__::math::statistics::linear-residuals__ *xdata* *ydata* *intercept*](#29)
[__::math::statistics::test-2x2__ *n11* *n21* *n12* *n22*](#30)
[__::math::statistics::print-2x2__ *n11* *n21* *n12* *n22*](#31)
[__::math::statistics::control-xbar__ *data* ?nsamples?](#32)
[__::math::statistics::control-Rchart__ *data* ?nsamples?](#33)
[__::math::statistics::test-xbar__ *control* *data*](#34)
[__::math::statistics::test-Rchart__ *control* *data*](#35)
[__::math::statistics::test-Kruskal-Wallis__ *confidence* *args*](#36)
[__::math::statistics::analyse-Kruskal-Wallis__ *args*](#37)
[__::math::statistics::group-rank__ *args*](#38)
[__::math::statistics::test-Wilcoxon__ *sample_a* *sample_b*](#39)
[__::math::statistics::spearman-rank__ *sample_a* *sample_b*](#40)
[__::math::statistics::spearman-rank-extended__ *sample_a* *sample_b*](#41)
[__::math::statistics::kernel-density__ *data* opt *-option value* ...](#42)
[__::math::statistics::bootstrap__ *data* *sampleSize* ?numberSamples?](#43)
[__::math::statistics::wasserstein-distance__ *prob1* *prob2*](#44)
[__::math::statistics::kl-divergence__ *prob1* *prob2*](#45)
[__::math::statistics::logistic-model__ *xdata* *ydata*](#46)
[__::math::statistics::logistic-probability__ *coeffs* *x*](#47)
[__::math::statistics::tstat__ *dof* ?alpha?](#48)
[__::math::statistics::mv-wls__ *wt1* *weights_and_values*](#49)
[__::math::statistics::mv-ols__ *values*](#50)
[__::math::statistics::pdf-normal__ *mean* *stdev* *value*](#51)
[__::math::statistics::pdf-lognormal__ *mean* *stdev* *value*](#52)
[__::math::statistics::pdf-exponential__ *mean* *value*](#53)
[__::math::statistics::pdf-uniform__ *xmin* *xmax* *value*](#54)
[__::math::statistics::pdf-gamma__ *alpha* *beta* *value*](#55)
[__::math::statistics::pdf-poisson__ *mu* *k*](#56)
[__::math::statistics::pdf-chisquare__ *df* *value*](#57)
[__::math::statistics::pdf-student-t__ *df* *value*](#58)
[__::math::statistics::pdf-gamma__ *a* *b* *value*](#59)
[__::math::statistics::pdf-beta__ *a* *b* *value*](#60)
[__::math::statistics::pdf-weibull__ *scale* *shape* *value*](#61)
[__::math::statistics::pdf-gumbel__ *location* *scale* *value*](#62)
[__::math::statistics::pdf-pareto__ *scale* *shape* *value*](#63)
[__::math::statistics::pdf-cauchy__ *location* *scale* *value*](#64)
[__::math::statistics::cdf-normal__ *mean* *stdev* *value*](#65)
[__::math::statistics::cdf-lognormal__ *mean* *stdev* *value*](#66)
[__::math::statistics::cdf-exponential__ *mean* *value*](#67)
[__::math::statistics::cdf-uniform__ *xmin* *xmax* *value*](#68)
[__::math::statistics::cdf-students-t__ *degrees* *value*](#69)
[__::math::statistics::cdf-gamma__ *alpha* *beta* *value*](#70)
[__::math::statistics::cdf-poisson__ *mu* *k*](#71)
[__::math::statistics::cdf-beta__ *a* *b* *value*](#72)
[__::math::statistics::cdf-weibull__ *scale* *shape* *value*](#73)
[__::math::statistics::cdf-gumbel__ *location* *scale* *value*](#74)
[__::math::statistics::cdf-pareto__ *scale* *shape* *value*](#75)
[__::math::statistics::cdf-cauchy__ *location* *scale* *value*](#76)
[__::math::statistics::cdf-F__ *nf1* *nf2* *value*](#77)
[__::math::statistics::empirical-distribution__ *values*](#78)
[__::math::statistics::random-normal__ *mean* *stdev* *number*](#79)
[__::math::statistics::random-lognormal__ *mean* *stdev* *number*](#80)
[__::math::statistics::random-exponential__ *mean* *number*](#81)
[__::math::statistics::random-uniform__ *xmin* *xmax* *number*](#82)
[__::math::statistics::random-gamma__ *alpha* *beta* *number*](#83)
[__::math::statistics::random-poisson__ *mu* *number*](#84)
[__::math::statistics::random-chisquare__ *df* *number*](#85)
[__::math::statistics::random-student-t__ *df* *number*](#86)
[__::math::statistics::random-beta__ *a* *b* *number*](#87)
[__::math::statistics::random-weibull__ *scale* *shape* *number*](#88)
[__::math::statistics::random-gumbel__ *location* *scale* *number*](#89)
[__::math::statistics::random-pareto__ *scale* *shape* *number*](#90)
[__::math::statistics::random-cauchy__ *location* *scale* *number*](#91)
[__::math::statistics::histogram-uniform__ *xmin* *xmax* *limits* *number*](#92)
[__::math::statistics::incompleteGamma__ *x* *p* ?tol?](#93)
[__::math::statistics::incompleteBeta__ *a* *b* *x* ?tol?](#94)
[__::math::statistics::estimate-pareto__ *values*](#95)
[__::math::statistics::filter__ *varname* *data* *expression*](#96)
[__::math::statistics::map__ *varname* *data* *expression*](#97)
[__::math::statistics::samplescount__ *varname* *list* *expression*](#98)
[__::math::statistics::subdivide__](#99)
[__::math::statistics::plot-scale__ *canvas* *xmin* *xmax* *ymin* *ymax*](#100)
[__::math::statistics::plot-xydata__ *canvas* *xdata* *ydata* *tag*](#101)
[__::math::statistics::plot-xyline__ *canvas* *xdata* *ydata* *tag*](#102)
[__::math::statistics::plot-tdata__ *canvas* *tdata* *tag*](#103)
[__::math::statistics::plot-tline__ *canvas* *tdata* *tag*](#104)
[__::math::statistics::plot-histogram__ *canvas* *counts* *limits* *tag*](#105)
# <a name='description'></a>DESCRIPTION
The __math::statistics__ package contains functions and procedures for basic
statistical data analysis, such as:
- Descriptive statistical parameters (mean, minimum, maximum, standard
deviation)
- Estimates of the distribution in the form of histograms and quantiles
- Basic testing of hypotheses
- Probability and cumulative density functions
It is meant to help in developing data analysis applications or doing ad hoc
data analysis, it is not in itself a full application, nor is it intended to
rival with full (non-)commercial statistical packages.
The purpose of this document is to describe the implemented procedures and
provide some examples of their usage. As there is ample literature on the
algorithms involved, we refer to relevant text books for more explanations. The
package contains a fairly large number of public procedures. They can be
distinguished in three sets: general procedures, procedures that deal with
specific statistical distributions, list procedures to select or transform data
and simple plotting procedures (these require Tk). *Note:* The data that need to
be analyzed are always contained in a simple list. Missing values are
represented as empty list elements. *Note:* With version 1.0.1 a mistake in the
procs *pdf-lognormal*, *cdf-lognormal* and *random-lognormal* has been
corrected. In previous versions the argument for the standard deviation was
actually used as if it was the variance.
# <a name='section2'></a>GENERAL PROCEDURES
The general statistical procedures are:
- <a name='1'></a>__::math::statistics::mean__ *data*
Determine the *mean* value of the given list of data.
* list *data*
- List of data
- <a name='2'></a>__::math::statistics::min__ *data*
Determine the *[minimum](../../../../index.md#minimum)* value of the given
list of data.
* list *data*
- List of data
- <a name='3'></a>__::math::statistics::max__ *data*
Determine the *[maximum](../../../../index.md#maximum)* value of the given
list of data.
* list *data*
- List of data
- <a name='4'></a>__::math::statistics::number__ *data*
Determine the *number* of non-missing data in the given list
* list *data*
- List of data
- <a name='5'></a>__::math::statistics::stdev__ *data*
Determine the *sample standard deviation* of the data in the given list
* list *data*
- List of data
- <a name='6'></a>__::math::statistics::var__ *data*
Determine the *sample variance* of the data in the given list
* list *data*
- List of data
- <a name='7'></a>__::math::statistics::pstdev__ *data*
Determine the *population standard deviation* of the data in the given list
* list *data*
- List of data
- <a name='8'></a>__::math::statistics::pvar__ *data*
Determine the *population variance* of the data in the given list
* list *data*
- List of data
- <a name='9'></a>__::math::statistics::median__ *data*
Determine the *median* of the data in the given list (Note that this
requires sorting the data, which may be a costly operation)
* list *data*
- List of data
- <a name='10'></a>__::math::statistics::basic-stats__ *data*
Determine a list of all the descriptive parameters: mean, minimum, maximum,
number of data, sample standard deviation, sample variance, population
standard deviation and population variance.
(This routine is called whenever either or all of the basic statistical
parameters are required. Hence all calculations are done and the relevant
values are returned.)
* list *data*
- List of data
- <a name='11'></a>__::math::statistics::histogram__ *limits* *values* ?weights?
Determine histogram information for the given list of data. Returns a list
consisting of the number of values that fall into each interval. (The first
interval consists of all values lower than the first limit, the last
interval consists of all values greater than the last limit. There is one
more interval than there are limits.)
Optionally, you can use weights to influence the histogram.
* list *limits*
- List of upper limits (in ascending order) for the intervals of the
histogram.
* list *values*
- List of data
* list *weights*
- List of weights, one weight per value
- <a name='12'></a>__::math::statistics::histogram-alt__ *limits* *values* ?weights?
Alternative implementation of the histogram procedure: the open end of the
intervals is at the lower bound instead of the upper bound.
* list *limits*
- List of upper limits (in ascending order) for the intervals of the
histogram.
* list *values*
- List of data
* list *weights*
- List of weights, one weight per value
- <a name='13'></a>__::math::statistics::corr__ *data1* *data2*
Determine the correlation coefficient between two sets of data.
* list *data1*
- First list of data
* list *data2*
- Second list of data
- <a name='14'></a>__::math::statistics::interval-mean-stdev__ *data* *confidence*
Return the interval containing the mean value and one containing the
standard deviation with a certain level of confidence (assuming a normal
distribution)
* list *data*
- List of raw data values (small sample)
* float *confidence*
- Confidence level (0.95 or 0.99 for instance)
- <a name='15'></a>__::math::statistics::t-test-mean__ *data* *est_mean* *est_stdev* *alpha*
Test whether the mean value of a sample is in accordance with the estimated
normal distribution with a certain probability. Returns 1 if the test
succeeds or 0 if the mean is unlikely to fit the given distribution.
* list *data*
- List of raw data values (small sample)
* float *est_mean*
- Estimated mean of the distribution
* float *est_stdev*
- Estimated stdev of the distribution
* float *alpha*
- Probability level (0.95 or 0.99 for instance)
- <a name='16'></a>__::math::statistics::test-normal__ *data* *significance*
Test whether the given data follow a normal distribution with a certain
level of significance. Returns 1 if the data are normally distributed within
the level of significance, returns 0 if not. The underlying test is the
Lilliefors test. Smaller values of the significance mean a stricter testing.
* list *data*
- List of raw data values
* float *significance*
- Significance level (one of 0.01, 0.05, 0.10, 0.15 or 0.20). For
compatibility reasons the values "1-significance", 0.80, 0.85, 0.90,
0.95 or 0.99 are also accepted.
Compatibility issue: the original implementation and documentation used the
term "confidence" and used a value 1-significance (see ticket 2812473fff).
This has been corrected as of version 0.9.3.
- <a name='17'></a>__::math::statistics::lillieforsFit__ *data*
Returns the goodness of fit to a normal distribution according to
Lilliefors. The higher the number, the more likely the data are indeed
normally distributed. The test requires at least *five* data points.
* list *data*
- List of raw data values
- <a name='18'></a>__::math::statistics::test-Duckworth__ *list1* *list2* *significance*
Determine if two data sets have the same median according to the
Tukey-Duckworth test. The procedure returns 0 if the medians are unequal, 1
if they are equal, -1 if the test can not be conducted (the smallest value
must be in a different set than the greatest value). # # Arguments: # list1
Values in the first data set # list2 Values in the second data set #
significance Significance level (either 0.05, 0.01 or 0.001) # # Returns:
Test whether the given data follow a normal distribution with a certain
level of significance. Returns 1 if the data are normally distributed within
the level of significance, returns 0 if not. The underlying test is the
Lilliefors test. Smaller values of the significance mean a stricter testing.
* list *list1*
- First list of data
* list *list2*
- Second list of data
* float *significance*
- Significance level (either 0.05, 0.01 or 0.001)
- <a name='19'></a>__::math::statistics::test-anova-F__ *alpha* *args*
Determine if two or more groups with normally distributed data have the same
means. The procedure returns 0 if the means are likely unequal, 1 if they
are. This is a one-way ANOVA test. The groups may also be stored in a nested
list: The procedure returns a list of the comparison results for each pair
of groups. Each element of this list contains: the index of the first group
and that of the second group, whether the means are likely to be different
(1) or not (0) and the confidence interval the conclusion is based on. The
groups may also be stored in a nested list:
test-anova-F 0.05 $A $B $C
#
# Or equivalently:
#
test-anova-F 0.05 [list $A $B $C]
* float *alpha*
- Significance level
* list *args*
- Two or more groups of data to be checked
- <a name='20'></a>__::math::statistics::test-Tukey-range__ *alpha* *args*
Determine if two or more groups with normally distributed data have the same
means, using Tukey's range test. It is complementary to the ANOVA test. The
procedure returns a list of the comparison results for each pair of groups.
Each element of this list contains: the index of the first group and that of
the second group, whether the means are likely to be different (1) or not
(0) and the confidence interval the conclusion is based on. The groups may
also be stored in a nested list, just as with the ANOVA test.
* float *alpha*
- Significance level - either 0.05 or 0.01
* list *args*
- Two or more groups of data to be checked
- <a name='21'></a>__::math::statistics::test-Dunnett__ *alpha* *control* *args*
Determine if one or more groups with normally distributed data have the same
means as the group of control data, using Dunnett's test. It is
complementary to the ANOVA test. The procedure returns a list of the
comparison results for each group with the control group. Each element of
this list contains: whether the means are likely to be different (1) or not
(0) and the confidence interval the conclusion is based on. The groups may
also be stored in a nested list, just as with the ANOVA test.
Note: some care is required if there is only one group to compare the
control with:
test-Dunnett-F 0.05 $control [list $A]
Otherwise the group A is split up into groups of one element - this is due
to an ambiguity.
* float *alpha*
- Significance level - either 0.05 or 0.01
* list *args*
- One or more groups of data to be checked
- <a name='22'></a>__::math::statistics::quantiles__ *data* *confidence*
Return the quantiles for a given set of data
* list *data*
- List of raw data values
* float *confidence*
- Confidence level (0.95 or 0.99 for instance) or a list of confidence
levels.
- <a name='23'></a>__::math::statistics::quantiles__ *limits* *counts* *confidence*
Return the quantiles based on histogram information (alternative to the call
with two arguments)
* list *limits*
- List of upper limits from histogram
* list *counts*
- List of counts for for each interval in histogram
* float *confidence*
- Confidence level (0.95 or 0.99 for instance) or a list of confidence
levels.
- <a name='24'></a>__::math::statistics::autocorr__ *data*
Return the autocorrelation function as a list of values (assuming
equidistance between samples, about 1/2 of the number of raw data)
The correlation is determined in such a way that the first value is always 1
and all others are equal to or smaller than 1. The number of values involved
will diminish as the "time" (the index in the list of returned values)
increases
* list *data*
- Raw data for which the autocorrelation must be determined
- <a name='25'></a>__::math::statistics::crosscorr__ *data1* *data2*
Return the cross-correlation function as a list of values (assuming
equidistance between samples, about 1/2 of the number of raw data)
The correlation is determined in such a way that the values can never exceed
1 in magnitude. The number of values involved will diminish as the "time"
(the index in the list of returned values) increases.
* list *data1*
- First list of data
* list *data2*
- Second list of data
- <a name='26'></a>__::math::statistics::mean-histogram-limits__ *mean* *stdev* *number*
Determine reasonable limits based on mean and standard deviation for a
histogram Convenience function - the result is suitable for the histogram
function.
* float *mean*
- Mean of the data
* float *stdev*
- Standard deviation
* int *number*
- Number of limits to generate (defaults to 8)
- <a name='27'></a>__::math::statistics::minmax-histogram-limits__ *min* *max* *number*
Determine reasonable limits based on a minimum and maximum for a histogram
Convenience function - the result is suitable for the histogram function.
* float *min*
- Expected minimum
* float *max*
- Expected maximum
* int *number*
- Number of limits to generate (defaults to 8)
- <a name='28'></a>__::math::statistics::linear-model__ *xdata* *ydata* *intercept*
Determine the coefficients for a linear regression between two series of
data (the model: Y = A + B*X). Returns a list of parameters describing the
fit
* list *xdata*
- List of independent data
* list *ydata*
- List of dependent data to be fitted
* boolean *intercept*
- (Optional) compute the intercept (1, default) or fit to a line through
the origin (0)
The result consists of the following list:
(Estimate of) Intercept A
(Estimate of) Slope B
Standard deviation of Y relative to fit
Correlation coefficient R2
Number of degrees of freedom df
Standard error of the intercept A
Significance level of A
Standard error of the slope B
Significance level of B
- <a name='29'></a>__::math::statistics::linear-residuals__ *xdata* *ydata* *intercept*
Determine the difference between actual data and predicted from the linear
model.
Returns a list of the differences between the actual data and the predicted
values.
* list *xdata*
- List of independent data
* list *ydata*
- List of dependent data to be fitted
* boolean *intercept*
- (Optional) compute the intercept (1, default) or fit to a line through
the origin (0)
- <a name='30'></a>__::math::statistics::test-2x2__ *n11* *n21* *n12* *n22*
Determine if two set of samples, each from a binomial distribution, differ
significantly or not (implying a different parameter).
Returns the "chi-square" value, which can be used to the determine the
significance.
* int *n11*
- Number of outcomes with the first value from the first sample.
* int *n21*
- Number of outcomes with the first value from the second sample.
* int *n12*
- Number of outcomes with the second value from the first sample.
* int *n22*
- Number of outcomes with the second value from the second sample.
- <a name='31'></a>__::math::statistics::print-2x2__ *n11* *n21* *n12* *n22*
Determine if two set of samples, each from a binomial distribution, differ
significantly or not (implying a different parameter).
Returns a short report, useful in an interactive session.
* int *n11*
- Number of outcomes with the first value from the first sample.
* int *n21*
- Number of outcomes with the first value from the second sample.
* int *n12*
- Number of outcomes with the second value from the first sample.
* int *n22*
- Number of outcomes with the second value from the second sample.
- <a name='32'></a>__::math::statistics::control-xbar__ *data* ?nsamples?
Determine the control limits for an xbar chart. The number of data in each
subsample defaults to 4. At least 20 subsamples are required.
Returns the mean, the lower limit, the upper limit and the number of data
per subsample.
* list *data*
- List of observed data
* int *nsamples*
- Number of data per subsample
- <a name='33'></a>__::math::statistics::control-Rchart__ *data* ?nsamples?
Determine the control limits for an R chart. The number of data in each
subsample (nsamples) defaults to 4. At least 20 subsamples are required.
Returns the mean range, the lower limit, the upper limit and the number of
data per subsample.
* list *data*
- List of observed data
* int *nsamples*
- Number of data per subsample
- <a name='34'></a>__::math::statistics::test-xbar__ *control* *data*
Determine if the data exceed the control limits for the xbar chart.
Returns a list of subsamples (their indices) that indeed violate the limits.
* list *control*
- Control limits as returned by the "control-xbar" procedure
* list *data*
- List of observed data
- <a name='35'></a>__::math::statistics::test-Rchart__ *control* *data*
Determine if the data exceed the control limits for the R chart.
Returns a list of subsamples (their indices) that indeed violate the limits.
* list *control*
- Control limits as returned by the "control-Rchart" procedure
* list *data*
- List of observed data
- <a name='36'></a>__::math::statistics::test-Kruskal-Wallis__ *confidence* *args*
Check if the population medians of two or more groups are equal with a given
confidence level, using the Kruskal-Wallis test.
* float *confidence*
- Confidence level to be used (0-1)
* list *args*
- Two or more lists of data
- <a name='37'></a>__::math::statistics::analyse-Kruskal-Wallis__ *args*
Compute the statistical parameters for the Kruskal-Wallis test. Returns the
Kruskal-Wallis statistic and the probability that that value would occur
assuming the medians of the populations are equal.
* list *args*
- Two or more lists of data
- <a name='38'></a>__::math::statistics::group-rank__ *args*
Rank the groups of data with respect to the complete set. Returns a list
consisting of the group ID, the value and the rank (possibly a rational
number, in case of ties) for each data item.
* list *args*
- Two or more lists of data
- <a name='39'></a>__::math::statistics::test-Wilcoxon__ *sample_a* *sample_b*
Compute the Wilcoxon test statistic to determine if two samples have the
same median or not. (The statistic can be regarded as standard normal, if
the sample sizes are both larger than 10. Returns the value of this
statistic.
* list *sample_a*
- List of data comprising the first sample
* list *sample_b*
- List of data comprising the second sample
- <a name='40'></a>__::math::statistics::spearman-rank__ *sample_a* *sample_b*
Return the Spearman rank correlation as an alternative to the ordinary
(Pearson's) correlation coefficient. The two samples should have the same
number of data.
* list *sample_a*
- First list of data
* list *sample_b*
- Second list of data
- <a name='41'></a>__::math::statistics::spearman-rank-extended__ *sample_a* *sample_b*
Return the Spearman rank correlation as an alternative to the ordinary
(Pearson's) correlation coefficient as well as additional data. The two
samples should have the same number of data. The procedure returns the
correlation coefficient, the number of data pairs used and the z-score, an
approximately standard normal statistic, indicating the significance of the
correlation.
* list *sample_a*
- First list of data
* list *sample_b*
- Second list of data
- <a name='42'></a>__::math::statistics::kernel-density__ *data* opt *-option value* ...
Return the density function based on kernel density estimation. The
procedure is controlled by a small set of options, each of which is given a
reasonable default.
The return value consists of three lists: the centres of the bins, the
associated probability density and a list of computational parameters (begin
and end of the interval, mean and standard deviation and the used
bandwidth). The computational parameters can be used for further analysis.
* list *data*
- The data to be examined
* list *args*
- Option-value pairs:
+ __-weights__ *weights*
Per data point the weight (default: 1 for all data)
+ __-bandwidth__ *value*
Bandwidth to be used for the estimation (default: determined from
standard deviation)
+ __-number__ *value*
Number of bins to be returned (default: 100)
+ __-interval__ *{begin end}*
Begin and end of the interval for which the density is returned
(default: mean +/- 3*standard deviation)
+ __-kernel__ *function*
Kernel to be used (One of: gaussian, cosine, epanechnikov, uniform,
triangular, biweight, logistic; default: gaussian)
- <a name='43'></a>__::math::statistics::bootstrap__ *data* *sampleSize* ?numberSamples?
Create a subsample or subsamples from a given list of data. The data in the
samples are chosen from this list - multiples may occur. If there is only
one subsample, the sample itself is returned (as a list of "sampleSize"
values), otherwise a list of samples is returned.
* list *data*
List of values to chose from
* int *sampleSize*
Number of values per sample
* int *numberSamples*
Number of samples (default: 1)
- <a name='44'></a>__::math::statistics::wasserstein-distance__ *prob1* *prob2*
Compute the Wasserstein distance or earth mover's distance for two
equidstantly spaced histograms or probability densities. The histograms need
not to be normalised to sum to one, but they must have the same number of
entries.
Note: the histograms are assumed to be based on the same equidistant
intervals. As the bounds are not passed, the value is expressed in the
length of the intervals.
* list *prob1*
List of values for the first histogram/probability density
* list *prob2*
List of values for the second histogram/probability density
- <a name='45'></a>__::math::statistics::kl-divergence__ *prob1* *prob2*
Compute the Kullback-Leibler (KL) divergence for two equidstantly spaced
histograms or probability densities. The histograms need not to be
normalised to sum to one, but they must have the same number of entries.
Note: the histograms are assumed to be based on the same equidistant
intervals. As the bounds are not passed, the value is expressed in the
length of the intervals.
Note also that the KL divergence is not symmetric and that the second
histogram should not contain zeroes in places where the first histogram has
non-zero values.
* list *prob1*
List of values for the first histogram/probability density
* list *prob2*
List of values for the second histogram/probability density
- <a name='46'></a>__::math::statistics::logistic-model__ *xdata* *ydata*
Estimate the coefficients of the logistic model that fits the data best. The
data consist of independent x-values and the outcome 0 or 1 for each of the
x-values. The result can be used to estimate the probability that a certain
x-value gives 1.
* list *xdata*
List of values for which the success (1) or failure (0) is known
* list *ydata*
List of successes or failures corresponding to each value in *xdata*.
- <a name='47'></a>__::math::statistics::logistic-probability__ *coeffs* *x*
Calculate the probability of success for the value *x* given the
coefficients of the logistic model.
* list *coeffs*
List of coefficients as determine by the __logistic-model__ command
* float *x*
X-value for which the probability needs to be determined
# <a name='section3'></a>MULTIVARIATE LINEAR REGRESSION
Besides the linear regression with a single independent variable, the statistics
package provides two procedures for doing ordinary least squares (OLS) and
weighted least squares (WLS) linear regression with several variables. They were
written by Eric Kemp-Benedict.
In addition to these two, it provides a procedure (tstat) for calculating the
value of the t-statistic for the specified number of degrees of freedom that is
required to demonstrate a given level of significance.
Note: These procedures depend on the math::linearalgebra package.
*Description of the procedures*
- <a name='48'></a>__::math::statistics::tstat__ *dof* ?alpha?
Returns the value of the t-distribution t* satisfying
P(t*) = 1 - alpha/2
P(-t*) = alpha/2
for the number of degrees of freedom dof.
Given a sample of normally-distributed data x, with an estimate xbar for the
mean and sbar for the standard deviation, the alpha confidence interval for
the estimate of the mean can be calculated as
( xbar - t* sbar , xbar + t* sbar)
The return values from this procedure can be compared to an estimated
t-statistic to determine whether the estimated value of a parameter is
significantly different from zero at the given confidence level.
* int *dof*
Number of degrees of freedom
* float *alpha*
Confidence level of the t-distribution. Defaults to 0.05.
- <a name='49'></a>__::math::statistics::mv-wls__ *wt1* *weights_and_values*
Carries out a weighted least squares linear regression for the data points
provided, with weights assigned to each point.
The linear model is of the form
y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error
and each point satisfies
yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i
The procedure returns a list with the following elements:
The r-squared statistic
The adjusted r-squared statistic
A list containing the estimated coefficients b1, ... bN, b0 (The constant b0
comes last in the list.)
A list containing the standard errors of the coefficients
A list containing the 95% confidence bounds of the coefficients, with each
set of bounds returned as a list with two values
Arguments:
* list *weights_and_values*
A list consisting of: the weight for the first observation, the data for
the first observation (as a sublist), the weight for the second
observation (as a sublist) and so on. The sublists of data are organised
as lists of the value of the dependent variable y and the independent
variables x1, x2 to xN.
- <a name='50'></a>__::math::statistics::mv-ols__ *values*
Carries out an ordinary least squares linear regression for the data points
provided.
This procedure simply calls ::mvlinreg::wls with the weights set to 1.0, and
returns the same information.
*Example of the use:*
# Store the value of the unicode value for the "+/-" character
set pm "\u00B1"
# Provide some data
set data {{ -.67 14.18 60.03 -7.5 }
{ 36.97 15.52 34.24 14.61 }
{-29.57 21.85 83.36 -7. }
{-16.9 11.79 51.67 -6.56 }
{ 14.09 16.24 36.97 -12.84}
{ 31.52 20.93 45.99 -25.4 }
{ 24.05 20.69 50.27 17.27}
{ 22.23 16.91 45.07 -4.3 }
{ 40.79 20.49 38.92 -.73 }
{-10.35 17.24 58.77 18.78}}
# Call the ols routine
set results [::math::statistics::mv-ols $data]
# Pretty-print the results
puts "R-squared: [lindex $results 0]"
puts "Adj R-squared: [lindex $results 1]"
puts "Coefficients $pm s.e. -- \[95% confidence interval\]:"
foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] {
set lb [lindex $bounds 0]
set ub [lindex $bounds 1]
puts " $val $pm $se -- \[$lb to $ub\]"
}
# <a name='section4'></a>STATISTICAL DISTRIBUTIONS
In the literature a large number of probability distributions can be found. The
statistics package supports:
- The normal or Gaussian distribution as well as the log-normal distribution
- The uniform distribution - equal probability for all data within a given
interval
- The exponential distribution - useful as a model for certain extreme-value
distributions.
- The gamma distribution - based on the incomplete Gamma integral
- The beta distribution
- The chi-square distribution
- The student's T distribution
- The Poisson distribution
- The Pareto distribution
- The Gumbel distribution
- The Weibull distribution
- The Cauchy distribution
- The F distribution (only the cumulative density function)
- PM - binomial.
In principle for each distribution one has procedures for:
- The probability density (pdf-*)
- The cumulative density (cdf-*)
- Quantiles for the given distribution (quantiles-*)
- Histograms for the given distribution (histogram-*)
- List of random values with the given distribution (random-*)
The following procedures have been implemented:
- <a name='51'></a>__::math::statistics::pdf-normal__ *mean* *stdev* *value*
Return the probability of a given value for a normal distribution with given
mean and standard deviation.
* float *mean*
- Mean value of the distribution
* float *stdev*
- Standard deviation of the distribution
* float *value*
- Value for which the probability is required
- <a name='52'></a>__::math::statistics::pdf-lognormal__ *mean* *stdev* *value*
Return the probability of a given value for a log-normal distribution with
given mean and standard deviation.
* float *mean*
- Mean value of the distribution
* float *stdev*
- Standard deviation of the distribution
* float *value*
- Value for which the probability is required
- <a name='53'></a>__::math::statistics::pdf-exponential__ *mean* *value*
Return the probability of a given value for an exponential distribution with
given mean.
* float *mean*
- Mean value of the distribution
* float *value*
- Value for which the probability is required
- <a name='54'></a>__::math::statistics::pdf-uniform__ *xmin* *xmax* *value*
Return the probability of a given value for a uniform distribution with
given extremes.
* float *xmin*
- Minimum value of the distribution
* float *xmin*
- Maximum value of the distribution
* float *value*
- Value for which the probability is required
- <a name='55'></a>__::math::statistics::pdf-gamma__ *alpha* *beta* *value*
Return the probability of a given value for a Gamma distribution with given
shape and rate parameters
* float *alpha*
- Shape parameter
* float *beta*
- Rate parameter
* float *value*
- Value for which the probability is required
- <a name='56'></a>__::math::statistics::pdf-poisson__ *mu* *k*
Return the probability of a given number of occurrences in the same interval
(k) for a Poisson distribution with given mean (mu)
* float *mu*
- Mean number of occurrences
* int *k*
- Number of occurences
- <a name='57'></a>__::math::statistics::pdf-chisquare__ *df* *value*
Return the probability of a given value for a chi square distribution with
given degrees of freedom
* float *df*
- Degrees of freedom
* float *value*
- Value for which the probability is required
- <a name='58'></a>__::math::statistics::pdf-student-t__ *df* *value*
Return the probability of a given value for a Student's t distribution with
given degrees of freedom
* float *df*
- Degrees of freedom
* float *value*
- Value for which the probability is required
- <a name='59'></a>__::math::statistics::pdf-gamma__ *a* *b* *value*
Return the probability of a given value for a Gamma distribution with given
shape and rate parameters
* float *a*
- Shape parameter
* float *b*
- Rate parameter
* float *value*
- Value for which the probability is required
- <a name='60'></a>__::math::statistics::pdf-beta__ *a* *b* *value*
Return the probability of a given value for a Beta distribution with given
shape parameters
* float *a*
- First shape parameter
* float *b*
- Second shape parameter
* float *value*
- Value for which the probability is required
- <a name='61'></a>__::math::statistics::pdf-weibull__ *scale* *shape* *value*
Return the probability of a given value for a Weibull distribution with
given scale and shape parameters
* float *location*
- Scale parameter
* float *scale*
- Shape parameter
* float *value*
- Value for which the probability is required
- <a name='62'></a>__::math::statistics::pdf-gumbel__ *location* *scale* *value*
Return the probability of a given value for a Gumbel distribution with given
location and shape parameters
* float *location*
- Location parameter
* float *scale*
- Shape parameter
* float *value*
- Value for which the probability is required
- <a name='63'></a>__::math::statistics::pdf-pareto__ *scale* *shape* *value*
Return the probability of a given value for a Pareto distribution with given
scale and shape parameters
* float *scale*
- Scale parameter
* float *shape*
- Shape parameter
* float *value*
- Value for which the probability is required
- <a name='64'></a>__::math::statistics::pdf-cauchy__ *location* *scale* *value*
Return the probability of a given value for a Cauchy distribution with given
location and shape parameters. Note that the Cauchy distribution has no
finite higher-order moments.
* float *location*
- Location parameter
* float *scale*
- Shape parameter
* float *value*
- Value for which the probability is required
- <a name='65'></a>__::math::statistics::cdf-normal__ *mean* *stdev* *value*
Return the cumulative probability of a given value for a normal distribution
with given mean and standard deviation, that is the probability for values
up to the given one.
* float *mean*
- Mean value of the distribution
* float *stdev*
- Standard deviation of the distribution
* float *value*
- Value for which the probability is required
- <a name='66'></a>__::math::statistics::cdf-lognormal__ *mean* *stdev* *value*
Return the cumulative probability of a given value for a log-normal
distribution with given mean and standard deviation, that is the probability
for values up to the given one.
* float *mean*
- Mean value of the distribution
* float *stdev*
- Standard deviation of the distribution
* float *value*
- Value for which the probability is required
- <a name='67'></a>__::math::statistics::cdf-exponential__ *mean* *value*
Return the cumulative probability of a given value for an exponential
distribution with given mean.
* float *mean*
- Mean value of the distribution
* float *value*
- Value for which the probability is required
- <a name='68'></a>__::math::statistics::cdf-uniform__ *xmin* *xmax* *value*
Return the cumulative probability of a given value for a uniform
distribution with given extremes.
* float *xmin*
- Minimum value of the distribution
* float *xmin*
- Maximum value of the distribution
* float *value*
- Value for which the probability is required
- <a name='69'></a>__::math::statistics::cdf-students-t__ *degrees* *value*
Return the cumulative probability of a given value for a Student's t
distribution with given number of degrees.
* int *degrees*
- Number of degrees of freedom
* float *value*
- Value for which the probability is required
- <a name='70'></a>__::math::statistics::cdf-gamma__ *alpha* *beta* *value*
Return the cumulative probability of a given value for a Gamma distribution
with given shape and rate parameters.
* float *alpha*
- Shape parameter
* float *beta*
- Rate parameter
* float *value*
- Value for which the cumulative probability is required
- <a name='71'></a>__::math::statistics::cdf-poisson__ *mu* *k*
Return the cumulative probability of a given number of occurrences in the
same interval (k) for a Poisson distribution with given mean (mu).
* float *mu*
- Mean number of occurrences
* int *k*
- Number of occurences
- <a name='72'></a>__::math::statistics::cdf-beta__ *a* *b* *value*
Return the cumulative probability of a given value for a Beta distribution
with given shape parameters
* float *a*
- First shape parameter
* float *b*
- Second shape parameter
* float *value*
- Value for which the probability is required
- <a name='73'></a>__::math::statistics::cdf-weibull__ *scale* *shape* *value*
Return the cumulative probability of a given value for a Weibull
distribution with given scale and shape parameters.
* float *scale*
- Scale parameter
* float *shape*
- Shape parameter
* float *value*
- Value for which the probability is required
- <a name='74'></a>__::math::statistics::cdf-gumbel__ *location* *scale* *value*
Return the cumulative probability of a given value for a Gumbel distribution
with given location and scale parameters.
* float *location*
- Location parameter
* float *scale*
- Scale parameter
* float *value*
- Value for which the probability is required
- <a name='75'></a>__::math::statistics::cdf-pareto__ *scale* *shape* *value*
Return the cumulative probability of a given value for a Pareto distribution
with given scale and shape parameters
* float *scale*
- Scale parameter
* float *shape*
- Shape parameter
* float *value*
- Value for which the probability is required
- <a name='76'></a>__::math::statistics::cdf-cauchy__ *location* *scale* *value*
Return the cumulative probability of a given value for a Cauchy distribution
with given location and scale parameters.
* float *location*
- Location parameter
* float *scale*
- Scale parameter
* float *value*
- Value for which the probability is required
- <a name='77'></a>__::math::statistics::cdf-F__ *nf1* *nf2* *value*
Return the cumulative probability of a given value for an F distribution
with nf1 and nf2 degrees of freedom.
* float *nf1*
- Degrees of freedom for the numerator
* float *nf2*
- Degrees of freedom for the denominator
* float *value*
- Value for which the probability is required
- <a name='78'></a>__::math::statistics::empirical-distribution__ *values*
Return a list of values and their empirical probability. The values are
sorted in increasing order. (The implementation follows the description at
the corresponding Wikipedia page)
* list *values*
- List of data to be examined
- <a name='79'></a>__::math::statistics::random-normal__ *mean* *stdev* *number*
Return a list of "number" random values satisfying a normal distribution
with given mean and standard deviation.
* float *mean*
- Mean value of the distribution
* float *stdev*
- Standard deviation of the distribution
* int *number*
- Number of values to be returned
- <a name='80'></a>__::math::statistics::random-lognormal__ *mean* *stdev* *number*
Return a list of "number" random values satisfying a log-normal distribution
with given mean and standard deviation.
* float *mean*
- Mean value of the distribution
* float *stdev*
- Standard deviation of the distribution
* int *number*
- Number of values to be returned
- <a name='81'></a>__::math::statistics::random-exponential__ *mean* *number*
Return a list of "number" random values satisfying an exponential
distribution with given mean.
* float *mean*
- Mean value of the distribution
* int *number*
- Number of values to be returned
- <a name='82'></a>__::math::statistics::random-uniform__ *xmin* *xmax* *number*
Return a list of "number" random values satisfying a uniform distribution
with given extremes.
* float *xmin*
- Minimum value of the distribution
* float *xmax*
- Maximum value of the distribution
* int *number*
- Number of values to be returned
- <a name='83'></a>__::math::statistics::random-gamma__ *alpha* *beta* *number*
Return a list of "number" random values satisfying a Gamma distribution with
given shape and rate parameters.
* float *alpha*
- Shape parameter
* float *beta*
- Rate parameter
* int *number*
- Number of values to be returned
- <a name='84'></a>__::math::statistics::random-poisson__ *mu* *number*
Return a list of "number" random values satisfying a Poisson distribution
with given mean.
* float *mu*
- Mean of the distribution
* int *number*
- Number of values to be returned
- <a name='85'></a>__::math::statistics::random-chisquare__ *df* *number*
Return a list of "number" random values satisfying a chi square distribution
with given degrees of freedom.
* float *df*
- Degrees of freedom
* int *number*
- Number of values to be returned
- <a name='86'></a>__::math::statistics::random-student-t__ *df* *number*
Return a list of "number" random values satisfying a Student's t
distribution with given degrees of freedom.
* float *df*
- Degrees of freedom
* int *number*
- Number of values to be returned
- <a name='87'></a>__::math::statistics::random-beta__ *a* *b* *number*
Return a list of "number" random values satisfying a Beta distribution with
given shape parameters.
* float *a*
- First shape parameter
* float *b*
- Second shape parameter
* int *number*
- Number of values to be returned
- <a name='88'></a>__::math::statistics::random-weibull__ *scale* *shape* *number*
Return a list of "number" random values satisfying a Weibull distribution
with given scale and shape parameters.
* float *scale*
- Scale parameter
* float *shape*
- Shape parameter
* int *number*
- Number of values to be returned
- <a name='89'></a>__::math::statistics::random-gumbel__ *location* *scale* *number*
Return a list of "number" random values satisfying a Gumbel distribution
with given location and scale parameters.
* float *location*
- Location parameter
* float *scale*
- Scale parameter
* int *number*
- Number of values to be returned
- <a name='90'></a>__::math::statistics::random-pareto__ *scale* *shape* *number*
Return a list of "number" random values satisfying a Pareto distribution
with given scale and shape parameters.
* float *scale*
- Scale parameter
* float *shape*
- Shape parameter
* int *number*
- Number of values to be returned
- <a name='91'></a>__::math::statistics::random-cauchy__ *location* *scale* *number*
Return a list of "number" random values satisfying a Cauchy distribution
with given location and scale parameters.
* float *location*
- Location parameter
* float *scale*
- Scale parameter
* int *number*
- Number of values to be returned
- <a name='92'></a>__::math::statistics::histogram-uniform__ *xmin* *xmax* *limits* *number*
Return the expected histogram for a uniform distribution.
* float *xmin*
- Minimum value of the distribution
* float *xmax*
- Maximum value of the distribution
* list *limits*
- Upper limits for the buckets in the histogram
* int *number*
- Total number of "observations" in the histogram
- <a name='93'></a>__::math::statistics::incompleteGamma__ *x* *p* ?tol?
Evaluate the incomplete Gamma integral
1 / x p-1
P(p,x) = -------- | dt exp(-t) * t
Gamma(p) / 0
* float *x*
- Value of x (limit of the integral)
* float *p*
- Value of p in the integrand
* float *tol*
- Required tolerance (default: 1.0e-9)
- <a name='94'></a>__::math::statistics::incompleteBeta__ *a* *b* *x* ?tol?
Evaluate the incomplete Beta integral
* float *a*
- First shape parameter
* float *b*
- Second shape parameter
* float *x*
- Value of x (limit of the integral)
* float *tol*
- Required tolerance (default: 1.0e-9)
- <a name='95'></a>__::math::statistics::estimate-pareto__ *values*
Estimate the parameters for the Pareto distribution that comes closest to
the given values. Returns the estimated scale and shape parameters, as well
as the standard error for the shape parameter.
* list *values*
- List of values, assumed to be distributed according to a Pareto
distribution
TO DO: more function descriptions to be added
# <a name='section5'></a>DATA MANIPULATION
The data manipulation procedures act on lists or lists of lists:
- <a name='96'></a>__::math::statistics::filter__ *varname* *data* *expression*
Return a list consisting of the data for which the logical expression is
true (this command works analogously to the command
__[foreach](../../../../index.md#foreach)__).
* string *varname*
- Name of the variable used in the expression
* list *data*
- List of data
* string *expression*
- Logical expression using the variable name
- <a name='97'></a>__::math::statistics::map__ *varname* *data* *expression*
Return a list consisting of the data that are transformed via the
expression.
* string *varname*
- Name of the variable used in the expression
* list *data*
- List of data
* string *expression*
- Expression to be used to transform (map) the data
- <a name='98'></a>__::math::statistics::samplescount__ *varname* *list* *expression*
Return a list consisting of the *counts* of all data in the sublists of the
"list" argument for which the expression is true.
* string *varname*
- Name of the variable used in the expression
* list *data*
- List of sublists, each containing the data
* string *expression*
- Logical expression to test the data (defaults to "true").
- <a name='99'></a>__::math::statistics::subdivide__
Routine *PM* - not implemented yet
# <a name='section6'></a>PLOT PROCEDURES
The following simple plotting procedures are available:
- <a name='100'></a>__::math::statistics::plot-scale__ *canvas* *xmin* *xmax* *ymin* *ymax*
Set the scale for a plot in the given canvas. All plot routines expect this
function to be called first. There is no automatic scaling provided.
* widget *canvas*
- Canvas widget to use
* float *xmin*
- Minimum x value
* float *xmax*
- Maximum x value
* float *ymin*
- Minimum y value
* float *ymax*
- Maximum y value
- <a name='101'></a>__::math::statistics::plot-xydata__ *canvas* *xdata* *ydata* *tag*
Create a simple XY plot in the given canvas - the data are shown as a
collection of dots. The tag can be used to manipulate the appearance.
* widget *canvas*
- Canvas widget to use
* float *xdata*
- Series of independent data
* float *ydata*
- Series of dependent data
* string *tag*
- Tag to give to the plotted data (defaults to xyplot)
- <a name='102'></a>__::math::statistics::plot-xyline__ *canvas* *xdata* *ydata* *tag*
Create a simple XY plot in the given canvas - the data are shown as a line
through the data points. The tag can be used to manipulate the appearance.
* widget *canvas*
- Canvas widget to use
* list *xdata*
- Series of independent data
* list *ydata*
- Series of dependent data
* string *tag*
- Tag to give to the plotted data (defaults to xyplot)
- <a name='103'></a>__::math::statistics::plot-tdata__ *canvas* *tdata* *tag*
Create a simple XY plot in the given canvas - the data are shown as a
collection of dots. The horizontal coordinate is equal to the index. The tag
can be used to manipulate the appearance. This type of presentation is
suitable for autocorrelation functions for instance or for inspecting the
time-dependent behaviour.
* widget *canvas*
- Canvas widget to use
* list *tdata*
- Series of dependent data
* string *tag*
- Tag to give to the plotted data (defaults to xyplot)
- <a name='104'></a>__::math::statistics::plot-tline__ *canvas* *tdata* *tag*
Create a simple XY plot in the given canvas - the data are shown as a line.
See plot-tdata for an explanation.
* widget *canvas*
- Canvas widget to use
* list *tdata*
- Series of dependent data
* string *tag*
- Tag to give to the plotted data (defaults to xyplot)
- <a name='105'></a>__::math::statistics::plot-histogram__ *canvas* *counts* *limits* *tag*
Create a simple histogram in the given canvas
* widget *canvas*
- Canvas widget to use
* list *counts*
- Series of bucket counts
* list *limits*
- Series of upper limits for the buckets
* string *tag*
- Tag to give to the plotted data (defaults to xyplot)
# <a name='section7'></a>THINGS TO DO
The following procedures are yet to be implemented:
- F-test-stdev
- interval-mean-stdev
- histogram-normal
- histogram-exponential
- test-histogram
- test-corr
- quantiles-*
- fourier-coeffs
- fourier-residuals
- onepar-function-fit
- onepar-function-residuals
- plot-linear-model
- subdivide
# <a name='section8'></a>EXAMPLES
The code below is a small example of how you can examine a set of data:
# Simple example:
# - Generate data (as a cheap way of getting some)
# - Perform statistical analysis to describe the data
#
package require math::statistics
#
# Two auxiliary procs
#
proc pause {time} {
set wait 0
after [expr {$time*1000}] {set ::wait 1}
vwait wait
}
proc print-histogram {counts limits} {
foreach count $counts limit $limits {
if { $limit != {} } {
puts [format "<%12.4g\t%d" $limit $count]
set prev_limit $limit
} else {
puts [format ">%12.4g\t%d" $prev_limit $count]
}
}
}
#
# Our source of arbitrary data
#
proc generateData { data1 data2 } {
upvar 1 $data1 _data1
upvar 1 $data2 _data2
set d1 0.0
set d2 0.0
for { set i 0 } { $i < 100 } { incr i } {
set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}]
set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}]
lappend _data1 $d1
lappend _data2 $d2
}
return {}
}
#
# The analysis session
#
package require Tk
console show
canvas .plot1
canvas .plot2
pack .plot1 .plot2 -fill both -side top
generateData data1 data2
puts "Basic statistics:"
set b1 [::math::statistics::basic-stats $data1]
set b2 [::math::statistics::basic-stats $data2]
foreach label {mean min max number stdev var} v1 $b1 v2 $b2 {
puts "$label\t$v1\t$v2"
}
puts "Plot the data as function of \"time\" and against each other"
::math::statistics::plot-scale .plot1 0 100 0 20
::math::statistics::plot-scale .plot2 0 20 0 20
::math::statistics::plot-tline .plot1 $data1
::math::statistics::plot-tline .plot1 $data2
::math::statistics::plot-xydata .plot2 $data1 $data2
puts "Correlation coefficient:"
puts [::math::statistics::corr $data1 $data2]
pause 2
puts "Plot histograms"
.plot2 delete all
::math::statistics::plot-scale .plot2 0 20 0 100
set limits [::math::statistics::minmax-histogram-limits 7 16]
set histogram_data [::math::statistics::histogram $limits $data1]
::math::statistics::plot-histogram .plot2 $histogram_data $limits
puts "First series:"
print-histogram $histogram_data $limits
pause 2
set limits [::math::statistics::minmax-histogram-limits 0 15 10]
set histogram_data [::math::statistics::histogram $limits $data2]
::math::statistics::plot-histogram .plot2 $histogram_data $limits d2
.plot2 itemconfigure d2 -fill red
puts "Second series:"
print-histogram $histogram_data $limits
puts "Autocorrelation function:"
set autoc [::math::statistics::autocorr $data1]
puts [::math::statistics::map $autoc {[format "%.2f" $x]}]
puts "Cross-correlation function:"
set crossc [::math::statistics::crosscorr $data1 $data2]
puts [::math::statistics::map $crossc {[format "%.2f" $x]}]
::math::statistics::plot-scale .plot1 0 100 -1 4
::math::statistics::plot-tline .plot1 $autoc "autoc"
::math::statistics::plot-tline .plot1 $crossc "crossc"
.plot1 itemconfigure autoc -fill green
.plot1 itemconfigure crossc -fill yellow
puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9"
puts "First: [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]"
puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]"
If you run this example, then the following should be clear:
- There is a strong correlation between two time series, as displayed by the
raw data and especially by the correlation functions.
- Both time series show a significant periodic component
- The histograms are not very useful in identifying the nature of the time
series - they do not show the periodic nature.
# <a name='section9'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: statistics* 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.
# <a name='keywords'></a>KEYWORDS
[data analysis](../../../../index.md#data_analysis),
[mathematics](../../../../index.md#mathematics),
[statistics](../../../../index.md#statistics)
# <a name='category'></a>CATEGORY
Mathematics
|
Added embedded/md/tcllib/files/modules/math/symdiff.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
[//000000001]: # (math::calculus::symdiff - Symbolic differentiation for Tcl)
[//000000002]: # (Generated from file 'symdiff.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::calculus::symdiff(n) 1.0.1 tcllib "Symbolic differentiation for Tcl")
# NAME
math::calculus::symdiff - Symbolic differentiation for Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Procedures](#section2)
- [Expressions](#section3)
- [Examples](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require grammar::aycock 1.0
package require math::calculus::symdiff 1.0.1
[__math::calculus::symdiff::symdiff__ *expression* *variable*](#1)
[__math::calculus::jacobian__ *variableDict*](#2)
# <a name='description'></a>DESCRIPTION
The __math::calculus::symdiff__ package provides a symbolic differentiation
facility for Tcl math expressions. It is useful for providing derivatives to
packages that either require the Jacobian of a set of functions or else are more
efficient or stable when the Jacobian is provided.
# <a name='section2'></a>Procedures
The __math::calculus::symdiff__ package exports the two procedures:
- <a name='1'></a>__math::calculus::symdiff::symdiff__ *expression* *variable*
Differentiates the given *expression* with respect to the specified
*variable*. (See [Expressions](#section3) below for a discussion of the
subset of Tcl math expressions that are acceptable to
__math::calculus::symdiff__.) The result is a Tcl expression that evaluates
the derivative. Returns an error if *expression* is not a well-formed
expression or is not differentiable.
- <a name='2'></a>__math::calculus::jacobian__ *variableDict*
Computes the Jacobian of a system of equations. The system is given by the
dictionary *variableDict*, whose keys are the names of variables in the
system, and whose values are Tcl expressions giving the values of those
variables. (See [Expressions](#section3) below for a discussion of the
subset of Tcl math expressions that are acceptable to
__math::calculus::symdiff__. The result is a list of lists: the i'th element
of the j'th sublist is the partial derivative of the i'th variable with
respect to the j'th variable. Returns an error if any of the expressions
cannot be differentiated, or if *variableDict* is not a well-formed
dictionary.
# <a name='section3'></a>Expressions
The __math::calculus::symdiff__ package accepts only a small subset of the
expressions that are acceptable to Tcl commands such as __expr__ or __if__.
Specifically, the only constructs accepted are:
- Floating-point constants such as __5__ or __3.14159e+00__.
- References to Tcl variable using $-substitution. The variable names must
consist of alphanumerics and underscores: the __${...}__ notation is not
accepted.
- Parentheses.
- The __+__, __-__, __*__, __/__. and __**__ operators.
- Calls to the functions __acos__, __asin__, __atan__, __atan2__, __cos__,
__cosh__, __exp__, __hypot__, __[log](../log/log.md)__, __log10__, __pow__,
__sin__, __sinh__. __sqrt__, __tan__, and __tanh__.
Command substitution, backslash substitution, and argument expansion are not
accepted.
# <a name='section4'></a>Examples
math::calculus::symdiff::symdiff {($a*$x+$b)*($c*$x+$d)} x
==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d)))
math::calculus::symdiff::jacobian {x {$a * $x + $b * $y}
y {$c * $x + $d * $y}}
==> {{$a} {$b}} {{$c} {$d}}
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: calculus* 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.
# <a name='see-also'></a>SEE ALSO
[math::calculus](calculus.md), [math::interpolate](interpolate.md)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010 by Kevin B. Kenny <[email protected]>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>
|
Added embedded/md/tcllib/files/modules/math/trig.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
[//000000001]: # (math::trig - Tcl Math Library)
[//000000002]: # (Generated from file 'trig.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::trig(n) 1.0.0 tcllib "Tcl Math Library")
# NAME
math::trig - Trigonometric anf hyperbolic functions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [FUNCTIONS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require math::trig 1.0.0
[__::math::trig::radian_reduced__ *angle*](#1)
[__::math::trig::degree_reduced__ *angle*](#2)
[__::math::trig::cosec__ *angle*](#3)
[__::math::trig::sec__ *angle*](#4)
[__::math::trig::cotan__ *angle*](#5)
[__::math::trig::acosec__ *value*](#6)
[__::math::trig::asec__ *value*](#7)
[__::math::trig::acotan__ *value*](#8)
[__::math::trig::cosech__ *value*](#9)
[__::math::trig::sech__ *value*](#10)
[__::math::trig::cotanh__ *value*](#11)
[__::math::trig::asinh__ *value*](#12)
[__::math::trig::acosh__ *value*](#13)
[__::math::trig::atanh__ *value*](#14)
[__::math::trig::acosech__ *value*](#15)
[__::math::trig::asech__ *value*](#16)
[__::math::trig::acotanh__ *value*](#17)
[__::math::trig::sind__ *angle*](#18)
[__::math::trig::cosd__ *angle*](#19)
[__::math::trig::tand__ *angle*](#20)
[__::math::trig::cosecd__ *angle*](#21)
[__::math::trig::secd__ *angle*](#22)
[__::math::trig::cotand__ *angle*](#23)
# <a name='description'></a>DESCRIPTION
The *math::trig* package defines a set of trigonomic and hyperbolic functions
and their inverses. In addition it defines versions of the trigonomic functions
that take arguments in degrees instead of radians.
For easy use these functions may be imported into the *tcl::mathfunc* namespace,
so that they can be used directly in the *expr* command.
# <a name='section2'></a>FUNCTIONS
The functions *radian_reduced* and *degree_reduced* return a reduced angle, in
respectively radians and degrees, in the intervals [0, 2pi) and [0, 360):
- <a name='1'></a>__::math::trig::radian_reduced__ *angle*
Return the equivalent angle in the interval [0, 2pi).
* float *angle*
Angle (in radians)
- <a name='2'></a>__::math::trig::degree_reduced__ *angle*
Return the equivalent angle in the interval [0, 360).
* float *angle*
Angle (in degrees)
The following trigonomic functions are defined in addition to the ones defined
in the *expr* command:
- <a name='3'></a>__::math::trig::cosec__ *angle*
Calculate the cosecant of the angle (1/cos(angle))
* float *angle*
Angle (in radians)
- <a name='4'></a>__::math::trig::sec__ *angle*
Calculate the secant of the angle (1/sin(angle))
* float *angle*
Angle (in radians)
- <a name='5'></a>__::math::trig::cotan__ *angle*
Calculate the cotangent of the angle (1/tan(angle))
* float *angle*
Angle (in radians)
For these functions also the inverses are defined:
- <a name='6'></a>__::math::trig::acosec__ *value*
Calculate the arc cosecant of the value
* float *value*
Value of the argument
- <a name='7'></a>__::math::trig::asec__ *value*
Calculate the arc secant of the value
* float *value*
Value of the argument
- <a name='8'></a>__::math::trig::acotan__ *value*
Calculate the arc cotangent of the value
* float *value*
Value of the argument
The following hyperbolic and inverse hyperbolic functions are defined:
- <a name='9'></a>__::math::trig::cosech__ *value*
Calculate the hyperbolic cosecant of the value (1/sinh(value))
* float *value*
Value of the argument
- <a name='10'></a>__::math::trig::sech__ *value*
Calculate the hyperbolic secant of the value (1/cosh(value))
* float *value*
Value of the argument
- <a name='11'></a>__::math::trig::cotanh__ *value*
Calculate the hyperbolic cotangent of the value (1/tanh(value))
* float *value*
Value of the argument
- <a name='12'></a>__::math::trig::asinh__ *value*
Calculate the arc hyperbolic sine of the value
* float *value*
Value of the argument
- <a name='13'></a>__::math::trig::acosh__ *value*
Calculate the arc hyperbolic cosine of the value
* float *value*
Value of the argument
- <a name='14'></a>__::math::trig::atanh__ *value*
Calculate the arc hyperbolic tangent of the value
* float *value*
Value of the argument
- <a name='15'></a>__::math::trig::acosech__ *value*
Calculate the arc hyperbolic cosecant of the value
* float *value*
Value of the argument
- <a name='16'></a>__::math::trig::asech__ *value*
Calculate the arc hyperbolic secant of the value
* float *value*
Value of the argument
- <a name='17'></a>__::math::trig::acotanh__ *value*
Calculate the arc hyperbolic cotangent of the value
* float *value*
Value of the argument
The following versions of the common trigonometric functions and their inverses
are defined:
- <a name='18'></a>__::math::trig::sind__ *angle*
Calculate the sine of the angle (in degrees)
* float *angle*
Angle (in degrees)
- <a name='19'></a>__::math::trig::cosd__ *angle*
Calculate the cosine of the angle (in degrees)
* float *angle*
Angle (in radians)
- <a name='20'></a>__::math::trig::tand__ *angle*
Calculate the cotangent of the angle (in degrees)
* float *angle*
Angle (in degrees)
- <a name='21'></a>__::math::trig::cosecd__ *angle*
Calculate the cosecant of the angle (in degrees)
* float *angle*
Angle (in degrees)
- <a name='22'></a>__::math::trig::secd__ *angle*
Calculate the secant of the angle (in degrees)
* float *angle*
Angle (in degrees)
- <a name='23'></a>__::math::trig::cotand__ *angle*
Calculate the cotangent of the angle (in degrees)
* float *angle*
Angle (in degrees)
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *math :: trig* 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.
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math),
[trigonometry](../../../../index.md#trigonometry)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2018 Arjen Markus
|
Added embedded/md/tcllib/files/modules/md4/md4.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
[//000000001]: # (md4 - MD4 Message-Digest Algorithm)
[//000000002]: # (Generated from file 'md4.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (md4(n) 1.0.7 tcllib "MD4 Message-Digest Algorithm")
# NAME
md4 - MD4 Message-Digest Algorithm
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require md4 ?1.0.7?
[__::md4::md4__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]](#1)
[__::md4::hmac__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]](#2)
[__::md4::MD4Init__](#3)
[__::md4::MD4Update__ *token* *data*](#4)
[__::md4::MD4Final__ *token*](#5)
[__::md4::HMACInit__ *key*](#6)
[__::md4::HMACUpdate__ *token* *data*](#7)
[__::md4::HMACFinal__ *token*](#8)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the MD4 message-digest algorithm as
described in RFC 1320 (1) and (2). This algorithm takes an arbitrary quantity of
data and generates a 128-bit message digest from the input. The MD4 algorithm is
faster but potentially weaker than the related MD5 algorithm (3).
If you have __critcl__ and have built the __tcllibc__ package then the
implementation of the hashing function will be performed by compiled code.
Alternatively if __cryptkit__ is available this will be used. If no accelerator
package can be found then the pure-tcl implementation is used. The programming
interface remains the same in all cases.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::md4::md4__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]
Calculate the MD4 digest of the data given in string. This is returned as a
binary string by default. Giving the *-hex* option will return a hexadecimal
encoded version of the digest.
The data to be hashed can be specified either as a string argument to the
md4 command, or as a filename or a pre-opened channel. If the *-filename*
argument is given then the file is opened, the data read and hashed and the
file is closed. If the *-channel* argument is given then data is read from
the channel until the end of file. The channel is not closed.
Only one of *-file*, *-channel* or *string* should be given.
- <a name='2'></a>__::md4::hmac__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]
Calculate an Hashed Message Authentication digest (HMAC) using the MD4
digest algorithm. HMACs are described in RFC 2104 (4) and provide an MD4
digest that includes a key. All options other than *-key* are as for the
__::md4::md4__ command.
# <a name='section3'></a>PROGRAMMING INTERFACE
For the programmer, the MD4 hash can be viewed as a bucket into which one pours
data. When you have finished, you extract a value that is derived from the data
that was poured into the bucket. The programming interface to the MD4 hash
operates on a token (equivalent to the bucket). You call __MD4Init__ to obtain a
token and then call __MD4Update__ as many times as required to add data to the
hash. To release any resources and obtain the hash value, you then call
__MD4Final__. An equivalent set of functions gives you a keyed digest (HMAC).
- <a name='3'></a>__::md4::MD4Init__
Begins a new MD4 hash. Returns a token ID that must be used for the
remaining functions.
- <a name='4'></a>__::md4::MD4Update__ *token* *data*
Add data to the hash identified by token. Calling *MD4Update $token "abcd"*
is equivalent to calling *MD4Update $token "ab"* followed by *MD4Update
$token "cb"*. See [EXAMPLES](#section4).
- <a name='5'></a>__::md4::MD4Final__ *token*
Returns the hash value and releases any resources held by this token. Once
this command completes the token will be invalid. The result is a binary
string of 16 bytes representing the 128 bit MD4 digest value.
- <a name='6'></a>__::md4::HMACInit__ *key*
This is equivalent to the __::md4::MD4Init__ command except that it requires
the key that will be included in the HMAC.
- <a name='7'></a>__::md4::HMACUpdate__ *token* *data*
- <a name='8'></a>__::md4::HMACFinal__ *token*
These commands are identical to the MD4 equivalent commands.
# <a name='section4'></a>EXAMPLES
% md4::md4 -hex "Tcl does MD4"
858da9b31f57648a032230447bd15f25
% md4::hmac -hex -key Sekret "Tcl does MD4"
c324088e5752872689caedf2a0464758
% set tok [md4::MD4Init]
::md4::1
% md4::MD4Update $tok "Tcl "
% md4::MD4Update $tok "does "
% md4::MD4Update $tok "MD4"
% md4::Hex [md4::MD4Final $tok]
858da9b31f57648a032230447bd15f25
# <a name='section5'></a>REFERENCES
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes and S.A.
Vanstone, editors, Advances in Cryptology - CRYPTO '90 Proceedings, pages
303-311, Springer-Verlag, 1991.
1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data
Security, Inc, April 1992.
([http://www.rfc-editor.org/rfc/rfc1321.txt](http://www.rfc-editor.org/rfc/rfc1321.txt))
1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997.
([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *md4* 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.
# <a name='see-also'></a>SEE ALSO
[md5](../md5/md5.md), [sha1](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[hashing](../../../../index.md#hashing), [md4](../../../../index.md#md4),
[message-digest](../../../../index.md#message_digest), [rfc
1320](../../../../index.md#rfc_1320), [rfc 1321](../../../../index.md#rfc_1321),
[rfc 2104](../../../../index.md#rfc_2104),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/md5/md5.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
[//000000001]: # (md5 - MD5 Message-Digest Algorithm)
[//000000002]: # (Generated from file 'md5.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (md5(n) 2.0.7 tcllib "MD5 Message-Digest Algorithm")
# NAME
md5 - MD5 Message-Digest Algorithm
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require md5 ?2.0.7?
[__::md5::md5__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]](#1)
[__::md5::hmac__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]](#2)
[__::md5::MD5Init__](#3)
[__::md5::MD5Update__ *token* *data*](#4)
[__::md5::MD5Final__ *token*](#5)
[__::md5::HMACInit__ *key*](#6)
[__::md5::HMACUpdate__ *token* *data*](#7)
[__::md5::HMACFinal__ *token*](#8)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the MD5 message-digest algorithm as
described in RFC 1321 (1). This algorithm takes an arbitrary quantity of data
and generates a 128-bit message digest from the input. The MD5 algorithm is
related to the MD4 algorithm (2) but has been strengthened against certain types
of potential attack. MD5 should be used in preference to MD4 for new
applications.
If you have __critcl__ and have built the __tcllibc__ package then the
implementation of the hashing function will be performed by compiled code.
Alternatively if you have either __cryptkit__ or __Trf__ then either of these
can be used to accelerate the digest computation. If no suitable compiled
package is available then the pure-Tcl implementation wil be used. The
programming interface remains the same in all cases.
*Note* the previous version of this package always returned a hex encoded
string. This has been changed to simplify the programming interface and to make
this version more compatible with other implementations. To obtain the previous
usage, either explicitly specify package version 1 or use the *-hex* option to
the __md5__ command.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::md5::md5__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]
Calculate the MD5 digest of the data given in string. This is returned as a
binary string by default. Giving the *-hex* option will return a hexadecimal
encoded version of the digest.
The data to be hashed can be specified either as a string argument to the
__md5__ command, or as a filename or a pre-opened channel. If the
*-filename* argument is given then the file is opened, the data read and
hashed and the file is closed. If the *-channel* argument is given then data
is read from the channel until the end of file. The channel is not closed.
Only one of *-file*, *-channel* or *string* should be given.
- <a name='2'></a>__::md5::hmac__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]
Calculate an Hashed Message Authentication digest (HMAC) using the MD5
digest algorithm. HMACs are described in RFC 2104 (3) and provide an MD5
digest that includes a key. All options other than *-key* are as for the
__::md5::md5__ command.
# <a name='section3'></a>PROGRAMMING INTERFACE
For the programmer, the MD5 hash can be viewed as a bucket into which one pours
data. When you have finished, you extract a value that is derived from the data
that was poured into the bucket. The programming interface to the MD5 hash
operates on a token (equivalent to the bucket). You call __MD5Init__ to obtain a
token and then call __MD5Update__ as many times as required to add data to the
hash. To release any resources and obtain the hash value, you then call
__MD5Final__. An equivalent set of functions gives you a keyed digest (HMAC).
- <a name='3'></a>__::md5::MD5Init__
Begins a new MD5 hash. Returns a token ID that must be used for the
remaining functions.
- <a name='4'></a>__::md5::MD5Update__ *token* *data*
Add data to the hash identified by token. Calling *MD5Update $token "abcd"*
is equivalent to calling *MD5Update $token "ab"* followed by *MD5Update
$token "cb"*. See [EXAMPLES](#section4).
- <a name='5'></a>__::md5::MD5Final__ *token*
Returns the hash value and releases any resources held by this token. Once
this command completes the token will be invalid. The result is a binary
string of 16 bytes representing the 128 bit MD5 digest value.
- <a name='6'></a>__::md5::HMACInit__ *key*
This is equivalent to the __::md5::MD5Init__ command except that it requires
the key that will be included in the HMAC.
- <a name='7'></a>__::md5::HMACUpdate__ *token* *data*
- <a name='8'></a>__::md5::HMACFinal__ *token*
These commands are identical to the MD5 equivalent commands.
# <a name='section4'></a>EXAMPLES
% md5::md5 -hex "Tcl does MD5"
8AAC1EE01E20BB347104FABB90310433
% md5::hmac -hex -key Sekret "Tcl does MD5"
35BBA244FD56D3EDF5F3C47474DACB5D
% set tok [md5::MD5Init]
::md5::1
% md5::MD5Update $tok "Tcl "
% md5::MD5Update $tok "does "
% md5::MD5Update $tok "MD5"
% md5::Hex [md5::MD5Final $tok]
8AAC1EE01E20BB347104FABB90310433
# <a name='section5'></a>REFERENCES
1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data
Security, Inc, April 1992.
([http://www.rfc-editor.org/rfc/rfc1321.txt](http://www.rfc-editor.org/rfc/rfc1321.txt))
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997.
([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *md5* 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.
# <a name='see-also'></a>SEE ALSO
[md4](../md4/md4.md), [sha1](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[hashing](../../../../index.md#hashing), [md5](../../../../index.md#md5),
[message-digest](../../../../index.md#message_digest), [rfc
1320](../../../../index.md#rfc_1320), [rfc 1321](../../../../index.md#rfc_1321),
[rfc 2104](../../../../index.md#rfc_2104),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/md5crypt/md5crypt.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
[//000000001]: # (md5crypt - MD5-based password encryption)
[//000000002]: # (Generated from file 'md5crypt.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (md5crypt(n) 1.1.0 tcllib "MD5-based password encryption")
# NAME
md5crypt - MD5-based password encryption
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [SALT](#section3)
- [EXAMPLES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require md5 2.0
package require md5crypt ?1.1.0?
[__::md5crypt::md5crypt__ *password* *salt*](#1)
[__::md5crypt::aprcrypt__ *password* *salt*](#2)
[__::md5crypt::salt__ ?*length*?](#3)
# <a name='description'></a>DESCRIPTION
This package provides an implementation of the MD5-crypt password encryption
algorithm as pioneered by FreeBSD and currently in use as a replacement for the
unix crypt(3) function in many modern systems. An implementation of the closely
related Apache MD5-crypt is also available. The output of these commands are
compatible with the BSD and OpenSSL implementation of md5crypt and the Apache 2
htpasswd program.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::md5crypt::md5crypt__ *password* *salt*
Generate a BSD compatible md5-encoded password hash from the plaintext
password and a random salt (see SALT).
- <a name='2'></a>__::md5crypt::aprcrypt__ *password* *salt*
Generate an Apache compatible md5-encoded password hash from the plaintext
password and a random salt (see SALT).
- <a name='3'></a>__::md5crypt::salt__ ?*length*?
Generate a random salt string suitable for use with the __md5crypt__ and
__aprcrypt__ commands.
# <a name='section3'></a>SALT
The salt passed to either of the encryption schemes implemented here is checked
to see if it begins with the encryption scheme magic string (either "$1$" for
MD5-crypt or "$apr1$" for Apache crypt). If so, this is removed. The remaining
characters up to the next $ and up to a maximum of 8 characters are then used as
the salt. The salt text should probably be restricted the set of ASCII
alphanumeric characters plus "./" (dot and forward-slash) - this is to preserve
maximum compatability with the unix password file format.
If a password is being generated rather than checked from a password file then
the __salt__ command may be used to generate a random salt.
# <a name='section4'></a>EXAMPLES
% md5crypt::md5crypt password 01234567
$1$01234567$b5lh2mHyD2PdJjFfALlEz1
% md5crypt::aprcrypt password 01234567
$apr1$01234567$IXBaQywhAhc0d75ZbaSDp/
% md5crypt::md5crypt password [md5crypt::salt]
$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *md5crypt* 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.
# <a name='see-also'></a>SEE ALSO
[md5](../md5/md5.md)
# <a name='keywords'></a>KEYWORDS
[hashing](../../../../index.md#hashing), [md5](../../../../index.md#md5),
[md5crypt](../../../../index.md#md5crypt),
[message-digest](../../../../index.md#message_digest),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/mime/mime.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
|
[//000000001]: # (mime - Mime)
[//000000002]: # (Generated from file 'mime.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (mime(n) 1.6 tcllib "Mime")
# NAME
mime - Manipulation of MIME body parts
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [KNOWN BUGS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require mime ?1.6?
[__::mime::initialize__ ?__-canonical__ *type/subtype* ?__-param__ {*key value*}...? ?__-encoding__ *value*? ?__-header__ {*key value*}...?? (__-file__ *name* | __-string__ *value* | __-parts__ {*token1* ... *tokenN*})](#1)
[__::mime::finalize__ *token* ?__-subordinates__ __all__ | __dynamic__ | __none__?](#2)
[__::mime::getproperty__ *token* ?*property* | __-names__?](#3)
[__::mime::getheader__ *token* ?*key* | __-names__?](#4)
[__::mime::setheader__ *token* *key value* ?__-mode__ __write__ | __append__ | __delete__?](#5)
[__::mime::getbody__ *token* ?__-decode__? ?__-command__ *callback* ?__-blocksize__ *octets*??](#6)
[__::mime::copymessage__ *token* *channel*](#7)
[__::mime::buildmessage__ *token*](#8)
[__::mime::parseaddress__ *string*](#9)
[__::mime::parsedatetime__ (*string* | __-now__) *property*](#10)
[__::mime::mapencoding__ *encoding_name*](#11)
[__::mime::reversemapencoding__ *charset_type*](#12)
# <a name='description'></a>DESCRIPTION
The __mime__ library package provides the commands to create and manipulate MIME
body parts.
- <a name='1'></a>__::mime::initialize__ ?__-canonical__ *type/subtype* ?__-param__ {*key value*}...? ?__-encoding__ *value*? ?__-header__ {*key value*}...?? (__-file__ *name* | __-string__ *value* | __-parts__ {*token1* ... *tokenN*})
This command creates a MIME part and returns a token representing it.
If the __-canonical__ option is present, then the body is in canonical (raw)
form and is found by consulting either the __-file__, __-string__, or
__-parts__ option.
In addition, both the __-param__ and __-header__ options may occur zero or
more times to specify __Content-Type__ parameters (e.g., __charset__) and
header keyword/values (e.g., __Content-Disposition__), respectively.
Also, __-encoding__, if present, specifies the __Content-Transfer-Encoding__
when copying the body.
If the __-canonical__ option is not present, then the MIME part contained in
either the __-file__ or the __-string__ option is parsed, dynamically
generating subordinates as appropriate.
- <a name='2'></a>__::mime::finalize__ *token* ?__-subordinates__ __all__ | __dynamic__ | __none__?
This command destroys the MIME part represented by *token*. It returns an
empty string.
If the __-subordinates__ option is present, it specifies which subordinates
should also be destroyed. The default value is __dynamic__, destroying all
subordinates which were created by __::mime::initialize__ together with the
containing body part.
- <a name='3'></a>__::mime::getproperty__ *token* ?*property* | __-names__?
This command returns a string or a list of strings containing the properties
of a MIME part. If the command is invoked with the name of a specific
property, then the corresponding value is returned; instead, if __-names__
is specified, a list of all properties is returned; otherwise, a serialized
array of properties and values is returned.
The possible properties are:
* __content__
The type/subtype describing the content
* __encoding__
The "Content-Transfer-Encoding"
* __params__
A list of "Content-Type" parameters
* __parts__
A list of tokens for the part's subordinates. This property is present
only if the MIME part has subordinates.
* __size__
The approximate size of the content (unencoded)
- <a name='4'></a>__::mime::getheader__ *token* ?*key* | __-names__?
This command returns the header of a MIME part, as a list of strings.
A header consists of zero or more key/value pairs. Each value is a list
containing one or more strings.
If this command is invoked with the name of a specific *key*, then a list
containing the corresponding value(s) is returned; instead, if -names is
specified, a list of all keys is returned; otherwise, a serialized array of
keys and values is returned. Note that when a key is specified (e.g.,
"Subject"), the list returned usually contains exactly one string; however,
some keys (e.g., "Received") often occur more than once in the header,
accordingly the list returned usually contains more than one string.
- <a name='5'></a>__::mime::setheader__ *token* *key value* ?__-mode__ __write__ | __append__ | __delete__?
This command writes, appends to, or deletes the *value* associated with a
*key* in the header. It returns a list of strings containing the previous
value associated with the key.
The value for __-mode__ is one of:
* __write__
The *key*/*value* is either created or overwritten (the default).
* __append__
A new *value* is appended for the *key* (creating it as necessary).
* __delete__
All values associated with the key are removed (the *value* parameter is
ignored).
- <a name='6'></a>__::mime::getbody__ *token* ?__-decode__? ?__-command__ *callback* ?__-blocksize__ *octets*??
This command returns a string containing the body of the leaf MIME part
represented by *token* in canonical form.
If the __-command__ option is present, then it is repeatedly invoked with a
fragment of the body as this:
uplevel #0 $callback [list "data" $fragment]
(The __-blocksize__ option, if present, specifies the maximum size of each
fragment passed to the callback.)
When the end of the body is reached, the callback is invoked as:
uplevel #0 $callback "end"
Alternatively, if an error occurs, the callback is invoked as:
uplevel #0 $callback [list "error" reason]
Regardless, the return value of the final invocation of the callback is
propagated upwards by __::mime::getbody__.
If the __-command__ option is absent, then the return value of
__::mime::getbody__ is a string containing the MIME part's entire body.
If the option __-decode__ is absent the return value computed above is
returned as is. This means that it will be in the charset specified for the
token and not the usual utf-8. If the option __-decode__ is present however
the command will use the charset information associated with the token to
convert the string from its encoding into utf-8 before returning it.
- <a name='7'></a>__::mime::copymessage__ *token* *channel*
This command copies the MIME represented by *token* part to the specified
*channel*. The command operates synchronously, and uses fileevent to allow
asynchronous operations to proceed independently. It returns an empty
string.
- <a name='8'></a>__::mime::buildmessage__ *token*
This command returns the MIME part represented by *token* as a string. It is
similar to __::mime::copymessage__, only it returns the data as a return
string instead of writing to a channel.
- <a name='9'></a>__::mime::parseaddress__ *string*
This command takes a string containing one or more 822-style address
specifications and returns a list of serialized arrays, one element for each
address specified in the argument. If the string contains more than one
address they will be separated by commas.
Each serialized array contains the properties below. Note that one or more
of these properties may be empty.
* __address__
local@domain
* __comment__
822-style comment
* __domain__
the domain part (rhs)
* __error__
non-empty on a parse error
* __group__
this address begins a group
* __friendly__
user-friendly rendering
* __local__
the local part (lhs)
* __memberP__
this address belongs to a group
* __phrase__
the phrase part
* __proper__
822-style address specification
* __route__
822-style route specification (obsolete)
- <a name='10'></a>__::mime::parsedatetime__ (*string* | __-now__) *property*
This command takes a string containing an 822-style date-time specification
and returns the specified property as a serialized array.
The list of properties and their ranges are:
* __hour__
0 .. 23
* __lmonth__
January, February, ..., December
* __lweekday__
Sunday, Monday, ... Saturday
* __mday__
1 .. 31
* __min__
0 .. 59
* __mon__
1 .. 12
* __month__
Jan, Feb, ..., Dec
* __proper__
822-style date-time specification
* __rclock__
elapsed seconds between then and now
* __sec__
0 .. 59
* __wday__
0 .. 6 (Sun .. Mon)
* __weekday__
Sun, Mon, ..., Sat
* __yday__
1 .. 366
* __year__
1900 ...
* __zone__
-720 .. 720 (minutes east of GMT)
- <a name='11'></a>__::mime::mapencoding__ *encoding_name*
This commansd maps tcl encodings onto the proper names for their MIME
charset type. This is only done for encodings whose charset types were
known. The remaining encodings return "" for now.
- <a name='12'></a>__::mime::reversemapencoding__ *charset_type*
This command maps MIME charset types onto tcl encoding names. Those that are
unknown return "".
# <a name='section2'></a>KNOWN BUGS
- Tcllib Bug #447037
This problem affects only people which are using Tcl and Mime on a 64-bit
system. The currently recommended fix for this problem is to upgrade to Tcl
version 8.4. This version has extended 64 bit support and the bug does not
appear anymore.
The problem could have been generally solved by requiring the use of Tcl 8.4
for this package. We decided against this solution as it would force a large
number of unaffected users to upgrade their Tcl interpreter for no reason.
See [Ticket 447037](/tktview?name=447037) for additional information.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *mime* 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.
# <a name='see-also'></a>SEE ALSO
[ftp](../ftp/ftp.md), [http](../../../../index.md#http),
[pop3](../pop3/pop3.md), [smtp](smtp.md)
# <a name='keywords'></a>KEYWORDS
[email](../../../../index.md#email), [internet](../../../../index.md#internet),
[mail](../../../../index.md#mail), [mime](../../../../index.md#mime),
[net](../../../../index.md#net), [rfc 2045](../../../../index.md#rfc_2045), [rfc
2046](../../../../index.md#rfc_2046), [rfc 2049](../../../../index.md#rfc_2049),
[rfc 821](../../../../index.md#rfc_821), [rfc
822](../../../../index.md#rfc_822), [smtp](../../../../index.md#smtp)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 1999-2000 Marshall T. Rose
|
Added embedded/md/tcllib/files/modules/mime/smtp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
[//000000001]: # (smtp - smtp client)
[//000000002]: # (Generated from file 'smtp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (smtp(n) 1.5 tcllib "smtp client")
# NAME
smtp - Client-side tcl implementation of the smtp protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Authentication](#section2)
- [EXAMPLE](#section3)
- [TLS Security Considerations](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl
package require mime ?1.5.4?
package require smtp ?1.5?
[__::smtp::sendmessage__ *token* *option*...](#1)
# <a name='description'></a>DESCRIPTION
The __smtp__ library package provides the client side of the Simple Mail
Transfer Protocol (SMTP) (1) (2).
- <a name='1'></a>__::smtp::sendmessage__ *token* *option*...
This command sends the MIME part (see package __[mime](mime.md)__)
represented by *token* to an SMTP server. *options* is a list of options and
their associated values. The recognized options are:
* __-servers__
A list of SMTP servers. The default is __localhost__.
If multiple servers are specified they are tried in sequence. Note that
the __-ports__ are iterated over in tandem with the servers. If there
are not enough ports for the number of servers the default port (see
below) is used. If there are more ports than servers the superfluous
ports are ignored.
* __-ports__
A list of SMTP ports. The default is __25__.
See option __-servers__ above regardig the behaviour for then multiple
servers and ports are specified.
* __-client__
The name to use as our hostname when connecting to the server. By
default this is either localhost if one of the servers is localhost, or
is set to the string returned by __info hostname__.
* __-queue__
Indicates that the SMTP server should be asked to queue the message for
later processing. A boolean value.
* __-atleastone__
Indicates that the SMTP server must find at least one recipient
acceptable for the message to be sent. A boolean value.
* __-originator__
A string containing an 822-style address specification. If present the
header isn't examined for an originator address.
* __-recipients__
A string containing one or more 822-style address specifications. If
present the header isn't examined for recipient addresses). If the
string contains more than one address they will be separated by commas.
* __-header__
A list containing two elements, an smtp header and its associated value
(the -header option may occur zero or more times).
* __-usetls__
This package supports the RFC 3207 TLS extension (3) by default provided
the tls package is available. You can turn this off with this boolean
option.
* __-tlsimport__
This boolean flag is __false__ by default. When this flag is set the
package will import TLS on a sucessfully opened channel. This is needed
for connections using native TLS negotiation instead of __STARTTLS__.
The __[tls](../../../../index.md#tls)__ package is automatically
required when needed.
* __-tlspolicy__
This option lets you specify a command to be called if an error occurs
during TLS setup. The command is called with the SMTP code and
diagnostic message appended. The command should return 'secure' or
'insecure' where insecure will cause the package to continue on the
unencrypted channel. Returning 'secure' will cause the socket to be
closed and the next server in the __-servers__ list to be tried.
* __-username__
* __-password__
If your SMTP server requires authentication (RFC 2554 (4)) before
accepting mail you can use __-username__ and __-password__ to provide
your authentication details to the server. Currently this package
supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication methods.
The most secure method will be tried first and each method tried in turn
until we are either authorized or we run out of methods. Note that if
the server permits a TLS connection, then the authorization will occur
after we begin using the secure channel.
Please also read the section on [Authentication](#section2), it details
the necessary prequisites, i.e. packages needed to support these options
and authentication.
If the __-originator__ option is not present, the originator address is
taken from __From__ (or __Resent-From__); similarly, if the __-recipients__
option is not present, recipient addresses are taken from __To__, __cc__,
and __Bcc__ (or __Resent-To__, and so on). Note that the header key/values
supplied by the __-header__ option (not those present in the MIME part) are
consulted. Regardless, header key/values are added to the outgoing message
as necessary to ensure that a valid 822-style message is sent.
The command returns a list indicating which recipients were unacceptable to
the SMTP server. Each element of the list is another list, containing the
address, an SMTP error code, and a textual diagnostic. Depending on the
__-atleastone__ option and the intended recipients, a non-empty list may
still indicate that the message was accepted by the server.
# <a name='section2'></a>Authentication
Beware. SMTP authentication uses __[SASL](../sasl/sasl.md)__. I.e. if the user
has to authenticate a connection, i.e. use the options __-user__ and
__-password__ (see above) it is necessary to have the __sasl__ package available
so that __smtp__ can load it.
This is a soft dependency because not everybody requires authentication, and
__sasl__ depends on a lot of the cryptographic (secure) hashes, i.e. all of
__[md5](../md5/md5.md)__, __[otp](../otp/otp.md)__, __[md4](../md4/md4.md)__,
__[sha1](../sha1/sha1.md)__, and __[ripemd160](../ripemd/ripemd160.md)__.
# <a name='section3'></a>EXAMPLE
proc send_simple_message {recipient email_server subject body} {
package require smtp
package require mime
set token [mime::initialize -canonical text/plain \\
-string $body]
mime::setheader $token Subject $subject
smtp::sendmessage $token \\
-recipients $recipient -servers $email_server
mime::finalize $token
}
send_simple_message [email protected] localhost \\
"This is the subject." "This is the message."
# <a name='section4'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section5'></a>REFERENCES
1. Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982.
([http://www.rfc-editor.org/rfc/rfc821.txt](http://www.rfc-editor.org/rfc/rfc821.txt))
1. J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001.
([http://www.rfc-editor.org/rfc/rfc2821.txt](http://www.rfc-editor.org/rfc/rfc2821.txt))
1. P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport Layer
Security", RFC 3207, February 2002.
([http://www.rfc-editor.org/rfc/rfc3207.txt](http://www.rfc-editor.org/rfc/rfc3207.txt))
1. J. Myers, "SMTP Service Extension for Authentication", RFC 2554, March
1999.
([http://www.rfc-editor.org/rfc/rfc2554.txt](http://www.rfc-editor.org/rfc/rfc2554.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *smtp* 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.
# <a name='see-also'></a>SEE ALSO
[ftp](../ftp/ftp.md), [http](../../../../index.md#http), [mime](mime.md),
[pop3](../pop3/pop3.md)
# <a name='keywords'></a>KEYWORDS
[email](../../../../index.md#email), [internet](../../../../index.md#internet),
[mail](../../../../index.md#mail), [mime](../../../../index.md#mime),
[net](../../../../index.md#net), [rfc 2554](../../../../index.md#rfc_2554), [rfc
2821](../../../../index.md#rfc_2821), [rfc 3207](../../../../index.md#rfc_3207),
[rfc 821](../../../../index.md#rfc_821), [rfc
822](../../../../index.md#rfc_822), [smtp](../../../../index.md#smtp),
[tls](../../../../index.md#tls)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 1999-2000 Marshall T. Rose and others
|
Added embedded/md/tcllib/files/modules/multiplexer/multiplexer.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
[//000000001]: # (multiplexer - One-to-many communication with sockets.)
[//000000002]: # (Generated from file 'multiplexer.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (multiplexer(n) 0.2 tcllib "One-to-many communication with sockets.")
# NAME
multiplexer - One-to-many communication with sockets.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require logger
package require multiplexer ?0.2?
[__::multiplexer::create__](#1)
[__${multiplexer_instance}::Init__ *port*](#2)
[__${multiplexer_instance}::Config__ *key* *value*](#3)
[__${multiplexer_instance}::AddFilter__ *cmdprefix*](#4)
[__cmdprefix__ *data* *chan* *clientaddress* *clientport*](#5)
[__${multiplexer_instance}::AddAccessFilter__ *cmdprefix*](#6)
[__cmdprefix__ *chan* *clientaddress* *clientport*](#7)
[__${multiplexer_instance}::AddExitFilter__ *cmdprefix*](#8)
[__cmdprefix__ *chan* *clientaddress* *clientport*](#9)
# <a name='description'></a>DESCRIPTION
The __multiplexer__ package provides a generic system for one-to-many
communication utilizing sockets. For example, think of a chat system where one
user sends a message which is then broadcast to all the other connected users.
It is possible to have different multiplexers running concurrently.
- <a name='1'></a>__::multiplexer::create__
The __create__ command creates a new multiplexer 'instance'. For example:
set mp [::multiplexer::create]
This instance can then be manipulated like so:
${mp}::Init 35100
- <a name='2'></a>__${multiplexer_instance}::Init__ *port*
This starts the multiplexer listening on the specified port.
- <a name='3'></a>__${multiplexer_instance}::Config__ *key* *value*
Use __Config__ to configure the multiplexer instance. Configuration options
currently include:
* __sendtoorigin__
A boolean flag. If __true__, the sender will receive a copy of the sent
message. Defaults to __false__.
* __debuglevel__
Sets the debug level to use for the multiplexer instance, according to
those specified by the __[logger](../log/logger.md)__ package (debug,
info, notice, warn, error, critical).
- <a name='4'></a>__${multiplexer_instance}::AddFilter__ *cmdprefix*
Command to add a filter for data that passes through the multiplexer
instance. The registered *cmdprefix* is called when data arrives at a
multiplexer instance. If there is more than one filter command registered at
the instance they will be called in the order of registristation, and each
filter will get the result of the preceding filter as its argument. The
first filter gets the incoming data as its argument. The result returned by
the last filter is the data which will be broadcast to all clients of the
multiplexer instance. The command prefix is called as
* <a name='5'></a>__cmdprefix__ *data* *chan* *clientaddress* *clientport*
Takes the incoming *data*, modifies it, and returns that as its result.
The last three arguments contain information about the client which sent
the data to filter: The channel connecting us to the client, its
ip-address, and its ip-port.
- <a name='6'></a>__${multiplexer_instance}::AddAccessFilter__ *cmdprefix*
Command to add an access filter. The registered *cmdprefix* is called when a
new client socket tries to connect to the multixer instance. If there is
more than one access filter command registered at the instance they will be
called in the order of registristation. If any of the called commands
returns __-1__ the access to the multiplexer instance is denied and the
client channel is closed immediately. Any other result grants the client
access to the multiplexer instance. The command prefix is called as
* <a name='7'></a>__cmdprefix__ *chan* *clientaddress* *clientport*
The arguments contain information about the client which tries to
connected to the instance: The channel connecting us to the client, its
ip-address, and its ip-port.
- <a name='8'></a>__${multiplexer_instance}::AddExitFilter__ *cmdprefix*
Adds filter to be run when client socket generates an EOF condition. The
registered *cmdprefix* is called when a client socket of the multixer
signals EOF. If there is more than one exit filter command registered at the
instance they will be called in the order of registristation. Errors thrown
by an exit filter are ignored, but logged. Any result returned by an exit
filter is ignored. The command prefix is called as
* <a name='9'></a>__cmdprefix__ *chan* *clientaddress* *clientport*
The arguments contain information about the client which signaled the
EOF: The channel connecting us to the client, its ip-address, and its
ip-port.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *multiplexer* 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.
# <a name='keywords'></a>KEYWORDS
[chat](../../../../index.md#chat),
[multiplexer](../../../../index.md#multiplexer)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/namespacex/namespacex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
[//000000001]: # (namespacex - Namespace utility commands)
[//000000002]: # (Generated from file 'namespacex.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (namespacex(n) 0.2 tcllib "Namespace utility commands")
# NAME
namespacex - Namespace utility commands
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require namespacex ?0.2?
[__::namespacex hook add__ ?*namespace*? *cmdprefix*](#1)
[__::namespacex hook proc__ ?*namespace*? *arguments* *body*](#2)
[__::namespacex hook on__ ?*namespace*? *guardcmdprefix* *actioncmdprefix*](#3)
[__::namespacex hook next__ *arg*...](#4)
[__::namespacex import fromns__ *cmdname ?*newname* ...?*](#5)
[__::namespacex info allchildren__ *namespace*](#6)
[__::namespacex info allvars__ *namespace*](#7)
[__::namespacex normalize__ *namespace*](#8)
[__::namespacex info vars__ *namespace* ?*pattern*?](#9)
[__::namespacex state get__ *namespace*](#10)
[__::namespacex state set__ *namespace* *dict*](#11)
[__::namespacex state drop__ *namespace*](#12)
[__::namespacex strip__ *prefix* *namespaces*](#13)
# <a name='description'></a>DESCRIPTION
This package provides a number of utility commands for working with namespaces.
The commands fall into four categories:
1. Hook commands provide and manipulate a chain of commands which replaces the
single regular __[namespace
unknown](../../../../index.md#namespace_unknown)__ handler.
1. An import command provides the ability to import any command from another
namespace.
1. Information commands allow querying of variables and child namespaces.
1. State commands provide a means to serialize variable values in a namespace.
# <a name='section2'></a>Commands
- <a name='1'></a>__::namespacex hook add__ ?*namespace*? *cmdprefix*
Adds the *cmdprefix* to the chain of unknown command handlers that are
invoked when the *namespace* would otherwise invoke its unknown handler. If
*namespace* is not specified, then *cmdprefix* is added to the chain of
handlers for the namespace of the caller.
The chain of *cmdprefix* are executed in reverse order of addition, *i.e.*
the most recently added *cmdprefix* is executed first. When executed,
*cmdprefix* has additional arguments appended to it as would any namespace
unknown handler.
- <a name='2'></a>__::namespacex hook proc__ ?*namespace*? *arguments* *body*
Adds an anonymous procedure to the chain of namespace unknown handlers for
the *namespace*.
If *namespace* is not specified, then the handler is added to the chain of
handlers for the namespace of the caller.
The *arguments* and *body* are specified as for the core
__[proc](../../../../index.md#proc)__ command.
- <a name='3'></a>__::namespacex hook on__ ?*namespace*? *guardcmdprefix* *actioncmdprefix*
Adds a guarded action to the chain of namespace unknown handlers for the
*namespace*.
If *namespace* is not specified, then the handler is added to the chain of
handlers for the namespace of the caller.
The *guardcmdprefix* is executed first. If it returns a value that can be
interpreted as false, then the next unknown hander in the chain is executed.
Otherwise, *actioncmdprefix* is executed and the return value of the handler
is the value returned by *actioncmdprefix*.
When executed, both *guardcmdprefix* and *actioncmdprefix* have the same
additional arguments appended as for any namespace unknown handler.
- <a name='4'></a>__::namespacex hook next__ *arg*...
This command is available to namespace hooks to execute the next hook in the
chain of handlers for the namespace.
- <a name='5'></a>__::namespacex import fromns__ *cmdname ?*newname* ...?*
Imports the command *cmdname* from the *fromns* namespace into the namespace
of the caller. The *cmdname* command is imported even if the *fromns* did
not originally export the command.
If *newname* is specified, then the imported command will be known by that
name. Otherwise, the command retains is original name as given by *cmdname*.
Additional pairs of *cmdname* / *newname* arguments may also be specified.
- <a name='6'></a>__::namespacex info allchildren__ *namespace*
Returns a list containing the names of all child namespaces in the specified
*namespace* and its children. The names are all fully qualified.
- <a name='7'></a>__::namespacex info allvars__ *namespace*
Returns a list containing the names of all variables in the specified
*namespace* and its children. The names are all given relative to
*namespace*, and *not* fully qualified.
- <a name='8'></a>__::namespacex normalize__ *namespace*
Returns the absolute name of *namespace*, which is resolved relative to the
namespace of the caller, with all unneeded colon characters removed.
- <a name='9'></a>__::namespacex info vars__ *namespace* ?*pattern*?
Returns a list containing the names of all variables in the specified
*namespace*. If the *pattern* argument is specified, then only variables
matching *pattern* are returned. Matching is determined using the same rules
as for __string match__.
- <a name='10'></a>__::namespacex state get__ *namespace*
Returns a dictionary holding the names and values of all variables in the
specified *namespace* and its child namespaces.
Note that the names are all relative to *namespace*, and *not* fully
qualified.
- <a name='11'></a>__::namespacex state set__ *namespace* *dict*
Takes a dictionary holding the names and values for a set of variables and
replaces the current state of the specified *namespace* and its child
namespaces with this state. The result of the command is the empty string.
- <a name='12'></a>__::namespacex state drop__ *namespace*
Unsets all variables in the specified *namespace* and its child namespaces.
The result of the command is the empty string.
- <a name='13'></a>__::namespacex strip__ *prefix* *namespaces*
Each item in *namespaces* must be the absolute normalized name of a child
namespace of namespace *prefix*. Returns the corresponding list of relative
names of child namespaces.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *namespacex* 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.
# <a name='keywords'></a>KEYWORDS
[extended namespace](../../../../index.md#extended_namespace),
[info](../../../../index.md#info), [namespace
unknown](../../../../index.md#namespace_unknown), [namespace
utilities](../../../../index.md#namespace_utilities), [state
(de)serialization](../../../../index.md#state_de_serialization), [unknown
hooking](../../../../index.md#unknown_hooking),
[utilities](../../../../index.md#utilities)
# <a name='copyright'></a>COPYRIGHT
Copyright © 200? Neil Madden (http://wiki.tcl.tk/12790)
Copyright © 200? Various (http://wiki.tcl.tk/1489)
Copyright © 2010 Documentation, Andreas Kupries
|
Added embedded/md/tcllib/files/modules/ncgi/ncgi.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
|
[//000000001]: # (ncgi - CGI Support)
[//000000002]: # (Generated from file 'ncgi.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ncgi(n) 1.4.3 tcllib "CGI Support")
# NAME
ncgi - Procedures to manipulate CGI values.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require ncgi ?1.4.3?
[__::ncgi::cookie__ *cookie*](#1)
[__::ncgi::decode__ *str*](#2)
[__::ncgi::empty__ *name*](#3)
[__::ncgi::exists__ *name*](#4)
[__::ncgi::encode__ *string*](#5)
[__::ncgi::header__ ?*type*? *args*](#6)
[__::ncgi::import__ *cginame* ?*tclname*?](#7)
[__::ncgi::importAll__ *args*](#8)
[__::ncgi::importFile__ *cmd* *cginame* ?*filename*?](#9)
[__::ncgi::input__ ?*fakeinput*? ?*fakecookie*?](#10)
[__::ncgi::multipart__ *type query*](#11)
[__::ncgi::nvlist__](#12)
[__::ncgi::names__](#13)
[__::ncgi::parse__](#14)
[__::ncgi::parseMimeValue__ *value*](#15)
[__::ncgi::query__](#16)
[__::ncgi::redirect__ *url*](#17)
[__::ncgi::reset__ *query type*](#18)
[__::ncgi::setCookie__ *args*](#19)
[__::ncgi::setDefaultValue__ *key defvalue*](#20)
[__::ncgi::setDefaultValueList__ *key defvaluelist*](#21)
[__::ncgi::setValue__ *key value*](#22)
[__::ncgi::setValueList__ *key valuelist*](#23)
[__::ncgi::type__](#24)
[__::ncgi::urlStub__ ?*url*?](#25)
[__::ncgi::value__ *key* ?*default*?](#26)
[__::ncgi::valueList__ *key* ?*default*?](#27)
# <a name='description'></a>DESCRIPTION
The __ncgi__ package provides commands that manipulate CGI values. These are
values that come from Web forms and are processed either by CGI scripts or web
pages with embedded Tcl code. Use the __ncgi__ package to query these values,
set and get cookies, and encode and decode www-url-encoded values.
In the simplest case, a CGI script first calls __::ncgi::parse__ and then calls
__::ncgi::value__ to get different form values. If a CGI value is repeated, you
should use __::ncgi::valueList__ to get back the complete list of values.
An alternative to __::ncgi::parse__ is __::ncgi::input__, which has semantics
similar to Don Libes' __cgi_input__ procedure. __::ncgi::input__ restricts
repeated CGI values to have names that end with "List". In this case,
__::ncgi::value__ will return the complete list of values, and __::ncgi::input__
will raise errors if it find repeated form elements without the right name.
The __::ncgi::reset__ procedure can be used in test suites and Web servers to
initialize the source of the CGI values. Otherwise the values are read in from
the CGI environment.
The complete set of procedures is described below.
- <a name='1'></a>__::ncgi::cookie__ *cookie*
Return a list of values for *cookie*, if any. It is possible that more than
one cookie with the same name can be present, so this procedure returns a
list.
- <a name='2'></a>__::ncgi::decode__ *str*
Decode strings in www-url-encoding, which represents special characters with
a %xx sequence, where xx is the character code in hex.
- <a name='3'></a>__::ncgi::empty__ *name*
Returns 1 if the CGI variable *name* is not present or has the empty string
as its value.
- <a name='4'></a>__::ncgi::exists__ *name*
The return value is a boolean. It returns __0__ if the CGI variable *name*
is not present, and __1__ otherwise.
- <a name='5'></a>__::ncgi::encode__ *string*
Encode *string* into www-url-encoded format.
- <a name='6'></a>__::ncgi::header__ ?*type*? *args*
Output the CGI header to standard output. This emits a Content-Type: header
and additional headers based on *args*, which is a list of header names and
header values. The *type* defaults to "text/html".
- <a name='7'></a>__::ncgi::import__ *cginame* ?*tclname*?
This creates a variable in the current scope with the value of the CGI
variable *cginame*. The name of the variable is *tclname*, or *cginame* if
*tclname* is empty (default).
- <a name='8'></a>__::ncgi::importAll__ *args*
This imports several CGI variables as Tcl variables. If *args* is empty,
then every CGI value is imported. Otherwise each CGI variable listed in
*args* is imported.
- <a name='9'></a>__::ncgi::importFile__ *cmd* *cginame* ?*filename*?
This provides information about an uploaded file from a form input field of
type __file__ with name *cginame*. *cmd* can be one of __-server__
__-client__, __-type__ or __-data__.
* __-client__ *cginame*
returns the filename as sent by the client.
* __-type__ *cginame*
returns the mime type of the uploaded file.
* __-data__ *cginame*
returns the contents of the file.
* __-server__ *cginame* *filename*
writes the file contents to a local temporary file (or *filename* if
supplied) and returns the name of the file. The caller is responsible
for deleting this file after use.
- <a name='10'></a>__::ncgi::input__ ?*fakeinput*? ?*fakecookie*?
This reads and decodes the CGI values from the environment. It restricts
repeated form values to have a trailing "List" in their name. The CGI values
are obtained later with the __::ncgi::value__ procedure.
- <a name='11'></a>__::ncgi::multipart__ *type query*
This procedure parses a multipart/form-data *query*. This is used by
__::ncgi::nvlist__ and not normally called directly. It returns an
alternating list of names and structured values. Each structure value is in
turn a list of two elements. The first element is meta-data from the
multipart/form-data structure. The second element is the form value. If you
use __::ncgi::value__ you just get the form value. If you use
__::ncgi::valueList__ you get the structured value with meta data and the
value.
The *type* is the whole Content-Type, including the parameters like
*boundary*. This returns a list of names and values that describe the
multipart data. The values are a nested list structure that has some
descriptive information first, and the actual form value second. The
descriptive information is list of header names and values that describe the
content.
- <a name='12'></a>__::ncgi::nvlist__
This returns all the query data as a name, value list. In the case of
multipart/form-data, the values are structured as described in
__::ncgi::multipart__.
- <a name='13'></a>__::ncgi::names__
This returns all names found in the query data, as a list.
__::ncgi::multipart__.
- <a name='14'></a>__::ncgi::parse__
This reads and decodes the CGI values from the environment. The CGI values
are obtained later with the __::ncgi::value__ procedure. IF a CGI value is
repeated, then you should use __::ncgi::valueList__ to get the complete list
of values.
- <a name='15'></a>__::ncgi::parseMimeValue__ *value*
This decodes the Content-Type and other MIME headers that have the form of
"primary value; param=val; p2=v2" It returns a list, where the first element
is the primary value, and the second element is a list of parameter names
and values.
- <a name='16'></a>__::ncgi::query__
This returns the raw query data.
- <a name='17'></a>__::ncgi::redirect__ *url*
Generate a response that causes a 302 redirect by the Web server. The *url*
is the new URL that is the target of the redirect. The URL will be qualified
with the current server and current directory, if necessary, to convert it
into a full URL.
- <a name='18'></a>__::ncgi::reset__ *query type*
Set the query data and Content-Type for the current CGI session. This is
used by the test suite and by Web servers to initialize the ncgi module so
it does not try to read standard input or use environment variables to get
its data. If neither *query* or *type* are specified, then the __ncgi__
module will look in the standard CGI environment for its data.
- <a name='19'></a>__::ncgi::setCookie__ *args*
Set a cookie value that will be returned as part of the reply. This must be
done before __::ncgi::header__ or __::ncgi::redirect__ is called in order
for the cookie to be returned properly. The *args* are a set of flags and
values:
* __-name__ *name*
* __-value__ *value*
* __-expires__ *date*
* __-path__ *path restriction*
* __-domain__ *domain restriction*
- <a name='20'></a>__::ncgi::setDefaultValue__ *key defvalue*
Set a CGI value if it does not already exists. This affects future calls to
__::ncgi::value__ (but not future calls to __::ncgi::nvlist__). If the CGI
value already is present, then this procedure has no side effects.
- <a name='21'></a>__::ncgi::setDefaultValueList__ *key defvaluelist*
Like __::ncgi::setDefaultValue__ except that the value already has list
structure to represent multiple checkboxes or a multi-selection.
- <a name='22'></a>__::ncgi::setValue__ *key value*
Set a CGI value, overriding whatever was present in the CGI environment
already. This affects future calls to __::ncgi::value__ (but not future
calls to __::ncgi::nvlist__).
- <a name='23'></a>__::ncgi::setValueList__ *key valuelist*
Like __::ncgi::setValue__ except that the value already has list structure
to represent multiple checkboxes or a multi-selection.
- <a name='24'></a>__::ncgi::type__
Returns the Content-Type of the current CGI values.
- <a name='25'></a>__::ncgi::urlStub__ ?*url*?
Returns the current URL, but without the protocol, server, and port. If
*url* is specified, then it defines the URL for the current session. That
value will be returned by future calls to __::ncgi::urlStub__
- <a name='26'></a>__::ncgi::value__ *key* ?*default*?
Return the CGI value identified by *key*. If the CGI value is not present,
then the *default* value is returned instead. This value defaults to the
empty string.
If the form value *key* is repeated, then there are two cases: if
__::ncgi::parse__ was called, then __::ncgi::value__ only returns the first
value associated with *key*. If __::ncgi::input__ was called, then
__::ncgi::value__ returns a Tcl list value and *key* must end in "List"
(e.g., "skuList"). In the case of multipart/form-data, this procedure just
returns the value of the form element. If you want the meta-data associated
with each form value, then use __::ncgi::valueList__.
- <a name='27'></a>__::ncgi::valueList__ *key* ?*default*?
Like __::ncgi::value__, but this always returns a list of values (even if
there is only one value). In the case of multipart/form-data, this procedure
returns a list of two elements. The first element is meta-data in the form
of a parameter, value list. The second element is the form value.
# <a name='section2'></a>EXAMPLES
Uploading a file
HTML:
<html>
<form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
Path: <input type="file" name="filedata"><br>
Name: <input type="text" name="filedesc"><br>
<input type="submit">
</form>
</html>
TCL: upload.cgi
#!/usr/local/bin/tclsh
::ncgi::parse
set filedata [::ncgi::value filedata]
set filedesc [::ncgi::value filedesc]
puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"
set filename /www/images/$filedesc
set fh [open $filename w]
puts -nonewline $fh $filedata
close $fh
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ncgi* 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.
# <a name='see-also'></a>SEE ALSO
[html](../html/html.md)
# <a name='keywords'></a>KEYWORDS
[CGI](../../../../index.md#cgi), [cookie](../../../../index.md#cookie),
[form](../../../../index.md#form), [html](../../../../index.md#html)
# <a name='category'></a>CATEGORY
CGI programming
|
Added embedded/md/tcllib/files/modules/nettool/nettool.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
[//000000001]: # (nettool - nettool)
[//000000002]: # (Generated from file 'nettool.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nettool(n) 0.5.2 tcllib "nettool")
# NAME
nettool - Tools for networked applications
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require nettool ?0.5.2?
package require twapi 3.1
package require ip 0.1
package require platform 0.1
[__::cat__ *filename*](#1)
[__::nettool::allocate_port__ *startingport*](#2)
[__::nettool::arp_table__](#3)
[__::nettool::broadcast_list__](#4)
[__::nettool::claim_port__ *port* ?*protocol*?](#5)
[__::nettool::cpuinfo__ *args*](#6)
[__::nettool::find_port__ *startingport*](#7)
[__::nettool::hwid_list__](#8)
[__::nettool::ip_list__](#9)
[__::nettool::mac_list__](#10)
[__::nettool::network_list__](#11)
[__::nettool::port_busy__ *port*](#12)
[__::nettool::release_port__ *port* ?*protocol*?](#13)
[__::nettool::status__](#14)
[__::nettool::user_data_root__ *appname*](#15)
# <a name='description'></a>DESCRIPTION
The __nettool__ package consists of a Pure-tcl set of tools to perform common
network functions that would normally require different packages or calls to
exec, in a standard Tcl interface. At present nettool has reference
implementations for the following operating systems: Windows, MacOSX, and Linux
(debian).
# <a name='section2'></a>Commands
- <a name='1'></a>__::cat__ *filename*
Dump the contents of a file as a result.
- <a name='2'></a>__::nettool::allocate_port__ *startingport*
Attempt to allocate *startingport*, or, if busy, advance the port number
sequentially until a free port is found, and claim that port. This command
uses a built-in database of known ports to avoid returning a port which is
in common use. (For example: http (80))
- <a name='3'></a>__::nettool::arp_table__
Dump the contents of this computer's Address Resolution Protocol (ARP)
table. The result will be a Tcl formatted list: *macid* *ipaddrlist* ...
- <a name='4'></a>__::nettool::broadcast_list__
Returns a list of broadcast addresses (suitable for UDP multicast) that this
computer is associated with.
- <a name='5'></a>__::nettool::claim_port__ *port* ?*protocol*?
Mark *port* as busy, optionally as either __tcp__ (default) or __udp__.
- <a name='6'></a>__::nettool::cpuinfo__ *args*
If no arguments are given, return a key/value list describing the CPU of the
present machine. Included in the matrix is info on the number of
cores/processors that are available for parallel tasking, installed physical
RAM, and processor family.
The exact contents are platform specific.
For Linux, information is drawn from /proc/cpuinfo and /proc/meminfo.
For MacOSX, information is drawn from sysctl
For Windows, information is draw from TWAPI.
If arguments are given, the result with be a key/value list limited to the
fields requested.
Canonical fields for all platforms:
* cpus
Count of CPUs/cores/execution units
* speed
Clock speed of processor(s) in Mhz
* memory
Installed RAM (in MB)
* vendor
Manufacturer
- <a name='7'></a>__::nettool::find_port__ *startingport*
Return *startingport* if it is available, or the next free port after
*startingport*. Note: Unlike __::nettool::allocate_port__, this command does
not claim the port.
This command uses a built-in database of known ports to avoid returning a
port which is in common use. (For example: http (80))
- <a name='8'></a>__::nettool::hwid_list__
Return a list of hardware specific identifiers from this computer. The
source and content will vary by platform.
For MacOSX, the motherboard serial number and macids for all network devices
is returned.
For Windows, the volume serial number of C and macids for all network
devices is returned.
For Linux, macids for all network devices is returned.
- <a name='9'></a>__::nettool::ip_list__
Return a list of IP addresses associated with this computer.
- <a name='10'></a>__::nettool::mac_list__
Return a list of MACIDs for the network cards attached to this machine. The
MACID of the primary network card is returned first.
- <a name='11'></a>__::nettool::network_list__
Return a list of networks associated with this computer. Networks are
formated with __ip::nativeToPrefix__.
- <a name='12'></a>__::nettool::port_busy__ *port*
Return true if *port* is claimed, false otherwise.
- <a name='13'></a>__::nettool::release_port__ *port* ?*protocol*?
Mark *port* as not busy, optionally as either __tcp__ (default) or __udp__.
- <a name='14'></a>__::nettool::status__
Return a key/value list describing the status of the computer. The output is
designed to be comparable to the output of __top__ for all platforms.
Common fields include:
* load
Processes per processing unit
* memory_total
Total physical RAM (MB)
* memory_free
Total physical RAM unused (MB)
- <a name='15'></a>__::nettool::user_data_root__ *appname*
Return a fully qualified path to a folder where *appname* should store it's
data. The path is not created, only computed, by this command.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *odie* 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.
# <a name='keywords'></a>KEYWORDS
[nettool](../../../../index.md#nettool), [odie](../../../../index.md#odie)
# <a name='category'></a>CATEGORY
System
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015-2018 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/nmea/nmea.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
[//000000001]: # (nmea - NMEA protocol implementation)
[//000000002]: # (Generated from file 'nmea.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nmea(n) 1.0.0 tcllib "NMEA protocol implementation")
# NAME
nmea - Process NMEA data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require nmea ?1.0.0?
[__::nmea::input__ *sentence*](#1)
[__::nmea::open_port__ *port* ?speed?](#2)
[__::nmea::close_port__](#3)
[__::nmea::configure_port__ *settings*](#4)
[__::nmea::open_file__ *file* ?rate?](#5)
[__::nmea::close_file__](#6)
[__::nmea::do_line__](#7)
[__::nmea::rate__](#8)
[__::nmea::log__ ?file?](#9)
[__::nmea::checksum__ *data*](#10)
[__::nmea::write__ *sentence* *data*](#11)
[__::nmea::event__ *setence* ?command?](#12)
# <a name='description'></a>DESCRIPTION
This package provides a standard interface for writing software which recieves
NMEA standard input data. It allows for reading data from COM ports, files, or
programmatic input. It also supports the checksumming and logging of incoming
data. After parsing, input is dispatched to user defined handler commands for
processing. To define a handler, see the __[event](../../../../index.md#event)__
command. There are no GPS specific functions in this package. NMEA data consists
of a sentence type, followed by a list of data.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::nmea::input__ *sentence*
Processes and dispatches the supplied sentence. If *sentence* contains no
commas it is treated as a Tcl list, otherwise it must be standard comma
delimited NMEA data, with an optional checksum and leading __$__.
nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39}
nmea::input [list GPGSA A 3 04 05 09 12 "" "" 24 "" "" "" 2.5 1.3 2.1]
- <a name='2'></a>__::nmea::open_port__ *port* ?speed?
Open the specified COM port and read NMEA sentences when available. Port
speed is set to 4800bps by default or to *speed*.
- <a name='3'></a>__::nmea::close_port__
Close the com port connection if one is open.
- <a name='4'></a>__::nmea::configure_port__ *settings*
Changes the current port settings. *settings* has the same format as
fconfigure -mode.
- <a name='5'></a>__::nmea::open_file__ *file* ?rate?
Open file *file* and read NMEA sentences, one per line, at the rate
specified by ?rate? in milliseconds. The file format may omit the leading
__$__ and/or the checksum. If rate is <= 0 (the default) then lines will
only be processed when a call to __do_line__ is made.
- <a name='6'></a>__::nmea::close_file__
Close the open file if one exists.
- <a name='7'></a>__::nmea::do_line__
If there is a currently open file, this command will read and process a
single line from it. Returns the number of lines read.
- <a name='8'></a>__::nmea::rate__
Sets the rate at which lines are processed from the open file, in
milliseconds. The rate remains consistant across files, there does not need
to be a file currently open to use this command. Set to 0 to disable
automatic line processing.
- <a name='9'></a>__::nmea::log__ ?file?
Starts or stops input logging. If a file name is specified then all NMEA
data recieved on the open port will be logged to the ?file? in append mode.
If file is an empty string then any logging will be stopped. If no file is
specified then returns a boolean value indicating if logging is currently
enabled. Data written to the port by __write__, data read from files, or
input made using __input__, is not logged.
- <a name='10'></a>__::nmea::checksum__ *data*
Returns the checksum of the supplied data.
- <a name='11'></a>__::nmea::write__ *sentence* *data*
If there is a currently open port, this command will write the specified
sentence and data to the port in proper NMEA checksummed format.
- <a name='12'></a>__::nmea::event__ *setence* ?command?
Registers a handler proc for a given NMEA *sentence*. There may be at most
one handler per sentence, any existing handler is replaced. If no command is
specified, returns the name of the current handler for the given *setence*
or an empty string if none exists. In addition to the incoming sentences
there are 2 builtin types, EOF and DEFAULT. The handler for the DEFAULT
setence is invoked if there is not a specific handler for that sentence. The
EOF handler is invoked when End Of File is reached on the open file or port.
The handler procedures, with the exception of the builtin types,must take
exactly one argument, which is a list of the data values. The DEFAULT
handler should have two arguments, the sentence type and the data values.
The EOF handler has no arguments.
nmea::event gpgsa parse_sat_detail
nmea::event default handle_unknown
proc parse_sat_detail {data} {
puts [lindex $data 1]
}
proc handle_unknown {name data} {
puts "unknown data type $name"
}
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nmea* 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.
# <a name='keywords'></a>KEYWORDS
[gps](../../../../index.md#gps), [nmea](../../../../index.md#nmea)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2009, Aaron Faupell <[email protected]>
|
Added embedded/md/tcllib/files/modules/nns/nns_auto.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
[//000000001]: # (nameserv::auto - Name service facility)
[//000000002]: # (Generated from file 'nns_auto.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nameserv::auto(n) 0.3 tcllib "Name service facility")
# NAME
nameserv::auto - Name service facility, Client Extension
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [OPTIONS](#section3)
- [EVENTS](#section4)
- [DESIGN](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require nameserv::auto ?0.3?
package require nameserv
# <a name='description'></a>DESCRIPTION
Please read the document *[Name service facility, introduction](nns_intro.md)*
first.
This package provides the *exact* same API as is provided by package
__[nameserv](nns_client.md)__, i.e. the regular name service client. It differs
from the former by taking measures to ensure that longer-lived data, i.e. bound
names, continuous and unfullfilled async searches, survive the loss of the
connection to the name server as much as is possible.
This means that the bound names and continuous and unfullfilled async searches
are remembered client-side and automatically re-entered into the server when the
connection comes back after its loss. For bound names there is one important
limitation to such restoration: It is possible that a name of this client was
bound by a different client while the connection was gone. Such names are fully
lost, and the best the package can and will do is to inform the user of this.
# <a name='section2'></a>API
The user-visible API is mainly identical to the API of
__[nameserv](nns_client.md)__ and is therefore not described here. Please read
the documentation of __[nameserv](nns_client.md)__.
The differences are explained below, in the sections [OPTIONS](#section3) and
[EVENTS](#section4).
# <a name='section3'></a>OPTIONS
This package supports all the options of package __[nameserv](nns_client.md)__,
plus one more. The additional option allows the user to specify the time
interval between attempts to restore a lost connection.
- __-delay__ *milliseconds*
The value of this option is an integer value > 0 which specifies the
interval to wait between attempts to restore a lost connection, in
milliseconds. The default value is __1000__, i.e. one second.
# <a name='section4'></a>EVENTS
This package generates all of the events of package
__[nameserv](nns_client.md)__, plus two more. Both events are generated for the
tag *[nameserv](nns_client.md)*.
- *lost-name*
This event is generated when a bound name is truly lost, i.e. could not be
restored after the temporary loss of the connection to the name server. It
indicates that a different client took ownership of the name while this
client was out of contact.
The detail information of the event will be a Tcl dictionary containing two
keys, __name__, and __data__. Their values hold all the information about
the lost name.
- *re-connection*
This event is generated when the connection to the server is restored. The
remembered data has been restored when the event is posted.
The event has no detail information.
# <a name='section5'></a>DESIGN
The package is implemented on top of the regular nameservice client, i.e.
package __[nameserv](nns_client.md)__. It detects the loss of the connection by
listening for *lost-connection* events, on the tag *[nameserv](nns_client.md)*.
It reacts to such events by starting a periodic timer and trying to reconnect to
the server whenver this timer triggers. On success the timer is canceled, a
*re-connection* event generated, and the package proceeds to re-enter the
remembered bound names and continuous searches.
Another loss of the connection, be it during or after re-entering the remembered
information simply restarts the timer and subsequent reconnection attempts.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[nameserv(n)](nns_client.md)
# <a name='keywords'></a>KEYWORDS
[automatic](../../../../index.md#automatic),
[client](../../../../index.md#client), [name
service](../../../../index.md#name_service),
[reconnect](../../../../index.md#reconnect),
[restore](../../../../index.md#restore)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/nns/nns_client.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
[//000000001]: # (nameserv - Name service facility)
[//000000002]: # (Generated from file 'nns_client.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nameserv(n) 0.4.2 tcllib "Name service facility")
# NAME
nameserv - Name service facility, Client
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [CONNECTION HANDLING](#section3)
- [EVENTS](#section4)
- [OPTIONS](#section5)
- [ASYNCHRONOUS AND CONTINUOUS SEARCHES](#section6)
- [HISTORY](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require nameserv ?0.4.2?
package require comm
package require logger
[__::nameserv::bind__ *name* *data*](#1)
[__::nameserv::release__](#2)
[__::nameserv::search__ ?__-async__|__-continuous__? ?*pattern*?](#3)
[__::nameserv::protocol__](#4)
[__::nameserv::server_protocol__](#5)
[__::nameserv::server_features__](#6)
[__::nameserv::cget__ __-option__](#7)
[__::nameserv::configure__](#8)
[__::nameserv::configure__ __-option__](#9)
[__::nameserv::configure__ __-option__ *value*...](#10)
[__$result__ __destroy__](#11)
[__$result__ __filled__](#12)
[__$result__ __get__ *name*](#13)
[__$result__ __names__](#14)
[__$result__ __size__](#15)
[__$result__ __getall__ ?*pattern*?](#16)
# <a name='description'></a>DESCRIPTION
Please read *[Name service facility, introduction](nns_intro.md)* first.
This package provides a client for the name service facility implemented by the
package __[nameserv::server](nns_server.md)__.
This service is built in top of and for the package __[comm](../comm/comm.md)__.
It has nothing to do with the Internet's Domain Name System. If the reader is
looking for a package dealing with that please see Tcllib's packages
__[dns](../dns/tcllib_dns.md)__ and __resolv__.
# <a name='section2'></a>API
The package exports eight commands, as specified below:
- <a name='1'></a>__::nameserv::bind__ *name* *data*
The caller of this command registers the given *name* as its name in the
configured name service, and additionally associates a piece of *data* with
it. The service does nothing with this information beyond storing it and
delivering it as part of search results. The meaning is entirely up to the
applications using the name service.
A generally useful choice would for example be an identifier for a
communication endpoint managed by the package __[comm](../comm/comm.md)__.
Anybody retrieving the name becomes immediately able to talk to this
endpoint, i.e. the registering application.
Of further importance is that a caller can register itself under more than
one name, and each name can have its own piece of *data*.
Note that the name service, and thwerefore this command, will throw an error
if the chosen name is already registered.
- <a name='2'></a>__::nameserv::release__
Invoking this command releases all names (and their data) registered by all
previous calls to __::nameserv::bind__ of this client. Note that the name
service will run this command implicitly when it loses the connection to
this client.
- <a name='3'></a>__::nameserv::search__ ?__-async__|__-continuous__? ?*pattern*?
This command searches the name service for all registered names matching the
specified glob-*pattern*. If not specified the pattern defaults to __*__,
matching everything. The result of the command is a dictionary mapping the
matching names to the data associated with them at
*[bind](../../../../index.md#bind)*-time.
If either option __-async__ or __-continuous__ were specified the result of
this command changes and becomes the Tcl command of an object holding the
actual result. These two options are supported if and only if the service
the client is connected to supports the protocol feature
*Search/Continuous*.
For __-async__ the result object is asynchronously filled with the entries
matching the pattern at the time of the search and then not modified any
more. The option __-continuous__ extends this behaviour by additionally
continuously monitoring the service for the addition and removal of entries
which match the pattern, and updating the object's contents appropriately.
*Note* that the caller is responsible for configuring the object with a
callback for proper notification when the current result (or further
changes) arrive.
For more information about this object see section [ASYNCHRONOUS AND
CONTINUOUS SEARCHES](#section6).
- <a name='4'></a>__::nameserv::protocol__
This command returns the highest version of the name service protocol
supported by the package.
- <a name='5'></a>__::nameserv::server_protocol__
This command returns the highest version of the name service protocol
supported by the name service the client is currently connected to.
- <a name='6'></a>__::nameserv::server_features__
This command returns a list containing the names of the features of the name
service protocol which are supported by the name service the client is
currently connected to.
- <a name='7'></a>__::nameserv::cget__ __-option__
This command returns the currently configured value for the specified
__-option__. The list of supported options and their meaning can be found in
section [OPTIONS](#section5).
- <a name='8'></a>__::nameserv::configure__
In this form the command returns a dictionary of all supported options, and
their current values. The list of supported options and their meaning can be
found in section [OPTIONS](#section5).
- <a name='9'></a>__::nameserv::configure__ __-option__
In this form the command is an alias for "__::nameserv::cget__ __-option__".
The list of supported options and their meaning can be found in section
[OPTIONS](#section5).
- <a name='10'></a>__::nameserv::configure__ __-option__ *value*...
In this form the command is used to configure one or more of the supported
options. At least one option has to be specified, and each option is
followed by its new value. The list of supported options and their meaning
can be found in section [OPTIONS](#section5).
This form can be used only as long as the client has not contacted the name
service yet. After contact has been made reconfiguration is not possible
anymore. This means that this form of the command is for the initalization
of the client before it use. The command forcing a contact with the name
service are
* __[bind](../../../../index.md#bind)__
* __release__
* __search__
* __server_protocol__
* __server_features__
# <a name='section3'></a>CONNECTION HANDLING
The client automatically connects to the service when one of the commands below
is run for the first time, or whenever one of the commands is run after the
connection was lost, when it was lost.
- __[bind](../../../../index.md#bind)__
- __release__
- __search__
- __server_protocol__
- __server_features__
Since version 0.2 of the client it will generate an event when the connection is
lost, allowing higher layers to perform additional actions. This is done via the
support package __[uevent](../uev/uevent.md)__. This and all other name service
related packages hereby reserve the uevent-tag *nameserv*. All their events will
be posted to that tag.
# <a name='section4'></a>EVENTS
This package generates only one event, *lost-connection*. The detail information
provided to that event is a Tcl dictionary. The only key contained in the
dictionnary is __reason__, and its value will be a string describing why the
connection was lost. This string is supplied by the underlying communication
package, i.e. __[comm](../comm/comm.md)__.
# <a name='section5'></a>OPTIONS
The options supported by the client are for the specification of which name
service to contact, i.e. of the location of the name service. They are:
- __-host__ *name*|*ipaddress*
This option specifies the host name service to contact is running on, either
by *name*, or by *ipaddress*. The initial default is __localhost__, i.e. it
is expected to contact a name service running on the same host as the
application using this package.
- __-port__ *number*
This option specifies the port the name service to contact is listening on.
It has to be a positive integer number (> 0) not greater than 65536
(unsigned short). The initial default is the number returned by the command
__::nameserv::common::port__, as provided by the package
__::nameserv::common__.
# <a name='section6'></a>ASYNCHRONOUS AND CONTINUOUS SEARCHES
Asynchronous and continuous searches are invoked by using either option
__-async__ or __-continuous__ as argument to the command __::nameserv::search__.
*Note* that these two options are supported if and only if the service the
client is connected to supports the protocol feature *Search/Continuous*. The
service provided by the package __::nameserv::server__ does this since version
0.3.
For such searches the result of the search command is the Tcl command of an
object holding the actual result. The API provided by these objects is:
- Options:
* __-command__ *command_prefix*
This option has to be set if a user of the result object wishes to get
asynchronous notifications when the search result or changes to it
arrive.
*Note* that while it is possible to poll for the arrival of the initial
search result via the method __filled__, and for subsequent changes by
comparing the output of method __getall__ against a saved copy, this is
not the recommended behaviour. Setting the __-command__ callback and
processing the notifications as they arrive is much more efficient.
The *command_prefix* is called with two arguments, the type of change,
and the data of the change. The type is either __add__ or __remove__,
indicating new data, or deleted data, respectively. The data of the
change is always a dictionary listing the added/removed names and their
associated data.
The first change reported for a search is always the set of matching
entries at the time of the search.
- Methods:
* <a name='11'></a>__$result__ __destroy__
Destroys the object and cancels any continuous monitoring of the service
the object may have had active.
* <a name='12'></a>__$result__ __filled__
The result is a boolean value indicating whether the search result has
already arrived (__True__), or not (__False__).
* <a name='13'></a>__$result__ __get__ *name*
Returns the data associated with the given *name* at
*[bind](../../../../index.md#bind)*-time.
* <a name='14'></a>__$result__ __names__
Returns a list containing all names known to the object at the time of
the invokation.
* <a name='15'></a>__$result__ __size__
Returns an integer value specifying the size of the result at the time
of the invokation.
* <a name='16'></a>__$result__ __getall__ ?*pattern*?
Returns a dictionary containing the search result at the time of the
invokation, mapping the matching names to the data associated with them
at *[bind](../../../../index.md#bind)*-time.
# <a name='section7'></a>HISTORY
- 0.3.1
Fixed SF Bug 1954771.
- 0.3
Extended the client with the ability to perform asynchronous and continuous
searches.
- 0.2
Extended the client with the ability to generate events when it loses its
connection to the name service. Based on package
__[uevent](../uev/uevent.md)__.
- 0.1
Initial implementation of the client.
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[nameserv::common(n)](nns_common.md), [nameserv::server(n)](nns_server.md)
# <a name='keywords'></a>KEYWORDS
[client](../../../../index.md#client), [name
service](../../../../index.md#name_service)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/nns/nns_common.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (nameserv::common - Name service facility)
[//000000002]: # (Generated from file 'nns_common.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nameserv::common(n) 0.1 tcllib "Name service facility")
# NAME
nameserv::common - Name service facility, shared definitions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8
package require nameserv::common ?0.1?
[__::nameserv::common::port__](#1)
# <a name='description'></a>DESCRIPTION
Please read *[Name service facility, introduction](nns_intro.md)* first.
This package is internal and of no interest to users. It provides the commands
of the name service facility which are shared by the client and server
implemented by the packages __[nameserv::server](nns_server.md)__ and
__[nameserv](nns_client.md)__ (the client).
This service is built in top of and for the package __[comm](../comm/comm.md)__.
It has nothing to do with the Internet's Domain Name System. If the reader is
looking for a package dealing with that please see Tcllib's packages
__[dns](../dns/tcllib_dns.md)__ and __resolv__.
# <a name='section2'></a>API
The package exports a single command, as specified below:
- <a name='1'></a>__::nameserv::common::port__
The result returned by the command is the id of the default TCP/IP port a
nameservice server will listen on, and a name service client will try to
connect to.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
nameserv::client(n), [nameserv::server(n)](nns_server.md)
# <a name='keywords'></a>KEYWORDS
[client](../../../../index.md#client), [name
service](../../../../index.md#name_service),
[server](../../../../index.md#server)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/nns/nns_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
[//000000001]: # (nns_intro - Name service facility)
[//000000002]: # (Generated from file 'nns_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nns_intro(n) 1.0 tcllib "Name service facility")
# NAME
nns_intro - Name service facility, introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Applications](#section2)
- [Packages](#section3)
- [Internals](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[nns](../../apps/nns.md)* (short for *nano nameservice*) is a facility built
for the package __[comm](../comm/comm.md)__, adding a simple name service to it.
It is also built on top of __[comm](../comm/comm.md)__, using it for the
exchange of messages between the client and server parts.
This name service facility has nothing to do with the Internet's *Domain Name
System*, otherwise known as *[DNS](../../../../index.md#dns)*. If the reader is
looking for a package dealing with that please see either of the packages
__[dns](../dns/tcllib_dns.md)__ and __resolv__, both found in Tcllib too.
Tcllib provides 2 applications and 4 packages which are working together and
provide access to the facility at different levels.
# <a name='section2'></a>Applications
The application __[nnsd](../../apps/nnsd.md)__ provides a simple name server
which can be run by anybody anywhere on their system, as they see fit. It is
also an example on the use of the server-side package
__[nameserv::server](nns_server.md)__.
Complementing this server is the __[nns](../../apps/nns.md)__ client
application. A possible, but no very sensible use would be to enter name/port
bindings into a server from a shell script. Not sensible, as shell scripts
normally do not provide a __[comm](../comm/comm.md)__-based service.
The only case for this to make some sense would be in a shell script wrapped
around a Tcl script FOO which is using comm, to register the listening port used
by FOO. However even there it would much more sensible to extend FOO to use the
nameservice directly. And in regard on how to that __[nns](../../apps/nns.md)__
can be used as both example and template. Beyond that it may also be useful to
perform nameservice queries from shell scripts.
The third application, __[nnslog](../../apps/nnslog.md)__ is a stripped down
form of the __[nns](../../apps/nns.md)__ client application. It is reduced to
perform a continuous search for all changes and logs all received events to
stdout.
Both clients use the __[nameserv::auto](nns_auto.md)__ package to automatically
hande the loss and restoration of the connection to the server.
# <a name='section3'></a>Packages
The two main packages implementing the service are __[nameserv](nns_client.md)__
and __[nameserv::server](nns_server.md)__, i.e. client and server. The latter
has not much of an API, just enough to start, stop, and configure it. See the
application __[nnsd](../../apps/nnsd.md)__ on how to use it.
The basic client, in package __[nameserv](nns_client.md)__, provides the main
API to manipulate and query the service. An example of its use is the
application __[nns](../../apps/nns.md)__.
The second client package, __[nameserv::auto](nns_auto.md)__ is API compatible
to the basic client, but provides the additional functionality that it will
automatically restore data like bound names when the connection to the name
service was lost and then reestablished. I.e. it automatically detects the loss
of the server and re-enters the data when the server comes back.
The package __[nameserv::common](nns_common.md)__ is of no interest to users. It
is an internal package containing code and definitions common to the packages
__[nameserv](nns_client.md)__ and __[nameserv::server](nns_server.md)__.
All packages use the __[uevent](../uev/uevent.md)__ package for the reporting of
special circumstances via events, and reserve the uevent-tag
*[nameserv](nns_client.md)* for their exclusive use. All their events will be
posted to that tag.
# <a name='section4'></a>Internals
The document *[Name service facility, client/server protocol](nns_protocol.md)*
specifies the protocol used by the packages __[nameserv](nns_client.md)__ and
__[nameserv::server](nns_server.md)__ to talk to each other. It is of no
interest to users of either the packages or applications.
Developers wishing to modify and/or extend or to just understand the internals
of the nameservice facility however are strongly advised to read it.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[nameserv(n)](nns_client.md), [nameserv::auto(n)](nns_auto.md),
[nameserv::common(n)](nns_common.md), [nameserv::protocol(n)](nns_protocol.md),
[nameserv::server(n)](nns_server.md), [nnsd(n)](../../apps/nnsd.md), nss(n)
# <a name='keywords'></a>KEYWORDS
[client](../../../../index.md#client), [name
service](../../../../index.md#name_service),
[server](../../../../index.md#server)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/nns/nns_protocol.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
[//000000001]: # (nameserv::protocol - Name service facility)
[//000000002]: # (Generated from file 'nns_protocol.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nameserv::protocol(n) 0.1 tcllib "Name service facility")
# NAME
nameserv::protocol - Name service facility, client/server protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Nano Name Service Protocol Version 1](#section2)
- [Basic Layer](#subsection1)
- [Message Layer](#subsection2)
- [Nano Name Service Protocol Extension: Continuous Search](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__Bind__ *name* *data*](#1)
[__Release__](#2)
[__Search__ *pattern*](#3)
[__ProtocolVersion__](#4)
[__ProtocolFeatures__](#5)
[__Search/Continuous/Start__ *tag* *pattern*](#6)
[__Search/Continuous/Stop__ *tag*](#7)
[__Search/Continuous/Change__ *tag* __add__|__remove__ *response*](#8)
# <a name='description'></a>DESCRIPTION
The packages __[nameserv::server](nns_server.md)__,
__[nameserv](nns_client.md)__, and __[nameserv::common](nns_common.md)__ provide
a simple unprotected name service facility for use in small trusted
environments.
Please read *[Name service facility, introduction](nns_intro.md)* first.
This document contains the specification of the network protocol which is used
by client and server to talk to each other, enabling implementations of the same
protocol in other languages.
# <a name='section2'></a>Nano Name Service Protocol Version 1
This protocol defines the basic set of messages to be supported by a name
service, also called the *Core* feature.
## <a name='subsection1'></a>Basic Layer
The basic communication between client and server is done using the
remote-execution protocol specified by the Tcl package
__[comm](../comm/comm.md)__. The relevant document specifying its on-the-wire
protocol can be found in *[comm_wire](../comm/comm_wire.md)*.
All the scripts exchanged via this protocol are single commands in list form and
thus can be interpreted as plain messages instead of as Tcl commands. The
commands/messages specified in the next section are the only commands understood
by the server-side. Command and variable substitutions are not allowed within
the messages, i.e. arguments have to be literal values.
The protocol is synchronous. I.e. for each message sent a response is expected,
and has to be generated. All messages are sent by the client. The server does
not sent messages, only responses to messages.
## <a name='subsection2'></a>Message Layer
- <a name='1'></a>__Bind__ *name* *data*
The client sends this message when it registers itself at the service with a
*name* and some associated *data*. The server has to send an error response
if the *name* is already in use. Otherwise the response has to be an empty
string.
The server has to accept multiple names for the same client.
- <a name='2'></a>__Release__
The client sends this message to unregister all names it is known under at
the service. The response has to be an empty string, always.
- <a name='3'></a>__Search__ *pattern*
The client sends this message to search the service for names matching the
glob-*pattern*. The response has to be a dictionary containing the matching
names as keys, and mapping them to the data associated with it at
__Bind__-time.
- <a name='4'></a>__ProtocolVersion__
The client sends this message to query the service for the highest version
of the name service protocol it supports. The response has to be a positive
integer number.
Servers supporting only *Nano Name Service Protocol Version 1* have to
return __1__.
- <a name='5'></a>__ProtocolFeatures__
The client sends this message to query the service for the features of the
name service protocol it supports. The response has to be a list containing
feature names.
Servers supporting only *Nano Name Service Protocol Version 1* have to
return __{Core}__.
# <a name='section3'></a>Nano Name Service Protocol Extension: Continuous Search
This protocol defines an extended set of messages to be supported by a name
service, also called the *Search/Continuous* feature. This feature defines
additional messages between client and server, and is otherwise identical to
version 1 of the protocol. See the last section for the details of our
foundation.
A service supporting this feature has to put the feature name
__Search/Continuous__ into the list of features returned by the message
*ProtocolFeatures*.
For this extension the protocol is asynchronous. No direct response is expected
for any of the messages in the extension. Furthermore the server will start
sending messages on its own, instead of only responses to messages, and the
client has to be able to handle these notifications.
- <a name='6'></a>__Search/Continuous/Start__ *tag* *pattern*
The client sends this message to start searching the service for names
matching the glob-*pattern*. In contrast to the regular *Search* request
this one asks the server to continuously monitor the database for the
addition and removal of matching entries and to notify the client of all
such changes. The particular search is identified by the *tag*.
No direct response is expected, rather the clients expect to be notified of
changes via explicit *Search/Continuous/Result* messages generated by the
service.
It is further expected that the *tag* information is passed unchanged to the
*Search/Continuous/Result* messages. This tagging of the results enables
clients to start multiple searches and distinguish between the different
results.
- <a name='7'></a>__Search/Continuous/Stop__ *tag*
The client sends this message to stop the continuous search identified by
the *tag*.
- <a name='8'></a>__Search/Continuous/Change__ *tag* __add__|__remove__ *response*
This message is sent by the service to clients with active continuous
searches to transfer found changes. The first such message for a new
continuous search has to contains the current set of matching entries.
To ensure this a service has to generate an __add__-message with an empty
*response* if there were no matching entries at the time.
The *response* has to be a dictionary containing the matching names as keys,
and mapping them to the data associated with it at __Bind__-time. The
argument coming before the response tells the client whether the names in
the response were added or removed from the service.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
[comm_wire(n)](../comm/comm_wire.md), [nameserv(n)](nns_client.md),
[nameserv::server(n)](nns_server.md)
# <a name='keywords'></a>KEYWORDS
[comm](../../../../index.md#comm), [name
service](../../../../index.md#name_service),
[protocol](../../../../index.md#protocol)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/nns/nns_server.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
[//000000001]: # (nameserv::server - Name service facility)
[//000000002]: # (Generated from file 'nns_server.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nameserv::server(n) 0.3.2 tcllib "Name service facility")
# NAME
nameserv::server - Name service facility, Server
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [OPTIONS](#section3)
- [HISTORY](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require nameserv::server ?0.3.2?
package require comm
package require interp
package require logger
[__::nameserv::server::start__](#1)
[__::nameserv::server::stop__](#2)
[__::nameserv::server::active?__](#3)
[__::nameserv::server::cget__ __-option__](#4)
[__::nameserv::server::configure__](#5)
[__::nameserv::server::configure__ __-option__](#6)
[__::nameserv::server::configure__ __-option__ *value*...](#7)
# <a name='description'></a>DESCRIPTION
Please read *[Name service facility, introduction](nns_intro.md)* first.
This package provides an implementation of the serviver side of the name service
facility queried by the client provided by the package
__[nameserv](nns_client.md)__. All information required by the server will be
held in memory. There is no persistent state.
This service is built in top of and for the package __[comm](../comm/comm.md)__.
It has nothing to do with the Internet's Domain Name System. If the reader is
looking for a package dealing with that please see Tcllib's packages
__[dns](../dns/tcllib_dns.md)__ and __resolv__.
This server supports the *Core* protocol feature, and since version 0.3 the
*Search/Continuous* feature as well.
# <a name='section2'></a>API
The package exports five commands, as specified below:
- <a name='1'></a>__::nameserv::server::start__
This command starts the server and causes it to listen on the configured
port. From now on clients are able to connect and make requests. The result
of the command is the empty string.
Note that any incoming requests will only be handled if the application the
server is part of does enter an event loop after this command has been run.
- <a name='2'></a>__::nameserv::server::stop__
Invoking this command stops the server and releases all information it had.
Existing connections are shut down, and no new connections will be accepted
any longer. The result of the command is the empty string.
- <a name='3'></a>__::nameserv::server::active?__
This command returns a boolean value indicating the state of the server. The
result will be __true__ if the server is active, i.e. has been started, and
__false__ otherwise.
- <a name='4'></a>__::nameserv::server::cget__ __-option__
This command returns the currently configured value for the specified
__-option__. The list of supported options and their meaning can be found in
section [OPTIONS](#section3).
- <a name='5'></a>__::nameserv::server::configure__
In this form the command returns a dictionary of all supported options, and
their current values. The list of supported options and their meaning can be
found in section [OPTIONS](#section3).
- <a name='6'></a>__::nameserv::server::configure__ __-option__
In this form the command is an alias for "__::nameserv::server::cget__
__-option__". The list of supported options and their meaning can be found
in section [OPTIONS](#section3).
- <a name='7'></a>__::nameserv::server::configure__ __-option__ *value*...
In this form the command is used to configure one or more of the supported
options. At least one option has to be specified, and each option is
followed by its new value. The list of supported options and their meaning
can be found in section [OPTIONS](#section3).
This form can be used only if the server is not active, i.e. has not been
started yet, or has been stopped. While the server is active it cannot be
reconfigured.
# <a name='section3'></a>OPTIONS
The options supported by the server are for the specification of the TCP port to
listen on, and whether to accept non-local connections or not. They are:
- __-localonly__ *bool*
This option specifies whether to accept only local connections (-localonly
1) or remote connections as well (-localonly 0). The default is to accept
only local connections.
- __-port__ *number*
This option specifies the port the name service will listen on after it has
been started. It has to be a positive integer number (> 0) not greater than
65536 (unsigned short). The initial default is the number returned by the
command __::nameserv::server::common::port__, as provided by the package
__::nameserv::server::common__.
# <a name='section4'></a>HISTORY
- 0.3
Extended the server with the ability to perform asynchronous and continuous
searches.
- 0.2
Changed name of -local switch to -localonly.
- 0.1
Initial implementation of the server.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='see-also'></a>SEE ALSO
nameserv::client(n), [nameserv::common(n)](nns_common.md)
# <a name='keywords'></a>KEYWORDS
[name service](../../../../index.md#name_service),
[server](../../../../index.md#server)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/nntp/nntp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
|
[//000000001]: # (nntp - Tcl NNTP Client Library)
[//000000002]: # (Generated from file 'nntp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (nntp(n) 1.5.1 tcllib "Tcl NNTP Client Library")
# NAME
nntp - Tcl client for the NNTP protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLE](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require nntp ?0.2.1?
[__::nntp::nntp__ ?*host*? ?*port*? ?*nntpName*?](#1)
[*nntpName* __method__ ?*arg arg ...*?](#2)
[*nntpName* __article__ ?*msgid*?](#3)
[*nntpName* __authinfo__ ?*user*? ?*pass*?](#4)
[*nntpName* __body__ ?*msgid*?](#5)
[*nntpName* __configure__](#6)
[*nntpName* __configure__ *option*](#7)
[*nntpName* __configure__ *option* *value* ...](#8)
[*nntpName* __cget__ *option*](#9)
[*nntpName* __date__](#10)
[*nntpName* __group__ ?*group*?](#11)
[*nntpName* __head__ ?*msgid*?](#12)
[*nntpName* __help__](#13)
[*nntpName* __last__](#14)
[*nntpName* __list__](#15)
[*nntpName* __listgroup__ ?*group*?](#16)
[*nntpName* __mode_reader__](#17)
[*nntpName* __newgroups__ *since*](#18)
[*nntpName* __newnews__](#19)
[*nntpName* __newnews__ *since*](#20)
[*nntpName* __newnews__ *group* ?*since*?](#21)
[*nntpName* __next__](#22)
[*nntpName* __post__ *article*](#23)
[*nntpName* __slave__](#24)
[*nntpName* __stat__ ?*msgid*?](#25)
[*nntpName* __quit__](#26)
[*nntpName* __xgtitle__ ?*group_pattern*?](#27)
[*nntpName* __xhdr__ *field* ?*range*?](#28)
[*nntpName* __xover__ ?*range*?](#29)
[*nntpName* __xpat__ *field* *range* ?*pattern_list*?](#30)
# <a name='description'></a>DESCRIPTION
The package __nntp__ provides a simple Tcl-only client library for the NNTP
protocol. It works by opening the standard NNTP socket on the server, and then
providing a Tcl API to access the NNTP protocol commands. All server errors are
returned as Tcl errors (thrown) which must be caught with the Tcl __catch__
command.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::nntp::nntp__ ?*host*? ?*port*? ?*nntpName*?
The command opens a socket connection to the specified NNTP server and
creates a new nntp object with an associated global Tcl command whose name
is *nntpName*. This command may be used to access the various NNTP protocol
commands for the new connection. The default *port* number is "119" and the
default *host* is "news". These defaults can be overridden with the
environment variables __NNTPPORT__ and __NNTPHOST__ respectively.
Some of the commands supported by this package are not part of the nntp rfc
977
([http://www.rfc-editor.org/rfc/rfc977.txt](http://www.rfc-editor.org/rfc/rfc977.txt))
and will not be available (or implemented) on all nntp servers.
The access command *nntpName* has the following general form:
* <a name='2'></a>*nntpName* __method__ ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
- <a name='3'></a>*nntpName* __article__ ?*msgid*?
Query the server for article *msgid* from the current group. The article is
returned as a valid tcl list which contains the headers, followed by a blank
line, and then followed by the body of the article. Each element in the list
is one line of the article.
- <a name='4'></a>*nntpName* __authinfo__ ?*user*? ?*pass*?
Send authentication information (username and password) to the server.
- <a name='5'></a>*nntpName* __body__ ?*msgid*?
Query the server for the body of the article *msgid* from the current group.
The body of the article is returned as a valid tcl list. Each element in the
list is one line of the body of the article.
- <a name='6'></a>*nntpName* __configure__
- <a name='7'></a>*nntpName* __configure__ *option*
- <a name='8'></a>*nntpName* __configure__ *option* *value* ...
- <a name='9'></a>*nntpName* __cget__ *option*
Query and configure options of the nntp connection object. Currently only
one option is supported, __-binary__. When set articles are retrieved as
binary data instead of text. The only methods affected by this are
__article__ and __body__.
One application of this option would be the download of articles containing
yEnc encoded images. Although encoded the data is still mostly binary and
retrieving it as text will corrupt the information.
See package __[yencode](../base64/yencode.md)__ for both encoder and decoder
of such data.
- <a name='10'></a>*nntpName* __date__
Query the server for the servers current date. The date is returned in the
format *YYYYMMDDHHMMSS*.
- <a name='11'></a>*nntpName* __group__ ?*group*?
Optionally set the current group, and retrieve information about the
currently selected group. Returns the estimated number of articles in the
group followed by the number of the first article in the group, followed by
the last article in the group, followed by the name of the group.
- <a name='12'></a>*nntpName* __head__ ?*msgid*?
Query the server for the headers of the article *msgid* from the current
group. The headers of the article are returned as a valid tcl list. Each
element in the list is one line of the headers of the article.
- <a name='13'></a>*nntpName* __help__
Retrieves a list of the commands that are supported by the news server that
is currently attached to.
- <a name='14'></a>*nntpName* __last__
Sets the current article pointer to point to the previous message (if there
is one) and returns the msgid of that message.
- <a name='15'></a>*nntpName* __list__
Returns a tcl list of valid newsgroups and associated information. Each
newsgroup is returned as an element in the tcl list with the following
format:
group last first p
where <group> is the name of the newsgroup, <last> is the number of the last
known article currently in that newsgroup, <first> is the number of the
first article currently in the newsgroup, and <p> is either 'y' or 'n'
indicating whether posting to this newsgroup is allowed ('y') or prohibited
('n').
The <first> and <last> fields will always be numeric. They may have leading
zeros. If the <last> field evaluates to less than the <first> field, there
are no articles currently on file in the newsgroup.
- <a name='16'></a>*nntpName* __listgroup__ ?*group*?
Query the server for a list of all the messages (message numbers) in the
group specified by the argument *group* or by the current group if the
*group* argument was not passed.
- <a name='17'></a>*nntpName* __mode_reader__
Query the server for its nntp 'MODE READER' response string.
- <a name='18'></a>*nntpName* __newgroups__ *since*
Query the server for a list of all the new newsgroups created since the time
specified by the argument *since*. The argument *since* can be any time
string that is understood by __clock scan__. The tcl list of newsgroups is
returned in a similar form to the list of groups returned by the __nntpName
list__ command. Each element of the list has the form:
group last first p
where <group> is the name of the newsgroup, <last> is the number of the last
known article currently in that newsgroup, <first> is the number of the
first article currently in the newsgroup, and <p> is either 'y' or 'n'
indicating whether posting to this newsgroup is allowed ('y') or prohibited
('n').
- <a name='19'></a>*nntpName* __newnews__
Query the server for a list of new articles posted to the current group in
the last day.
- <a name='20'></a>*nntpName* __newnews__ *since*
Query the server for a list of new articles posted to the current group
since the time specified by the argument *since*. The argument *since* can
be any time string that is understood by __clock scan__.
- <a name='21'></a>*nntpName* __newnews__ *group* ?*since*?
Query the server for a list of new articles posted to the group specified by
the argument *group* since the time specified by the argument *since* (or in
the past day if no *since* argument is passed. The argument *since* can be
any time string that is understood by __clock scan__.
- <a name='22'></a>*nntpName* __next__
Sets the current article pointer to point to the next message (if there is
one) and returns the msgid of that message.
- <a name='23'></a>*nntpName* __post__ *article*
Posts an article of the form specified in RFC 1036
([http://www.rfc-editor.org/rfc/rfc1036.txt](http://www.rfc-editor.org/rfc/rfc1036.txt),
successor to RFC 850) to the current news group.
- <a name='24'></a>*nntpName* __slave__
Identifies a connection as being made from a slave nntp server. This might
be used to indicate that the connection is serving multiple people and
should be given priority. Actual use is entirely implementation dependent
and may vary from server to server.
- <a name='25'></a>*nntpName* __stat__ ?*msgid*?
The stat command is similar to the article command except that no text is
returned. When selecting by message number within a group, the stat command
serves to set the current article pointer without sending text. The returned
acknowledgment response will contain the message-id, which may be of some
value. Using the stat command to select by message-id is valid but of
questionable value, since a selection by message-id does NOT alter the
"current article pointer"
- <a name='26'></a>*nntpName* __quit__
Gracefully close the connection after sending a NNTP QUIT command down the
socket.
- <a name='27'></a>*nntpName* __xgtitle__ ?*group_pattern*?
Returns a tcl list where each element is of the form:
newsgroup description
If a *group_pattern* is specified then only newsgroups that match the
pattern will have their name and description returned.
- <a name='28'></a>*nntpName* __xhdr__ *field* ?*range*?
Returns the specified header field value for the current message or for a
list of messages from the current group. *field* is the title of a field in
the header such as from, subject, date, etc. If *range* is not specified or
is "" then the current message is queried. The command returns a list of
elements where each element has the form of:
msgid value
Where msgid is the number of the message and value is the value set for the
queried field. The *range* argument can be in any of the following forms:
* __""__
The current message is queried.
* *msgid1*-*msgid2*
All messages between *msgid1* and *msgid2* (including *msgid1* and
*msgid2*) are queried.
* *msgid1* *msgid2*
All messages between *msgid1* and *msgid2* (including *msgid1* and
*msgid2*) are queried.
- <a name='29'></a>*nntpName* __xover__ ?*range*?
Returns header information for the current message or for a range of
messages from the current group. The information is returned in a tcl list
where each element is of the form:
msgid subject from date idstring bodysize headersize xref
If *range* is not specified or is "" then the current message is queried.
The *range* argument can be in any of the following forms:
* __""__
The current message is queried.
* *msgid1*-*msgid2*
All messages between *msgid1* and *msgid2* (including *msgid1* and
*msgid2*) are queried.
* *msgid1* *msgid2*
All messages between *msgid1* and *msgid2* (including *msgid1* and
*msgid2*) are queried.
- <a name='30'></a>*nntpName* __xpat__ *field* *range* ?*pattern_list*?
Returns the specified header field value for a specified message or for a
list of messages from the current group where the messages match the
pattern(s) given in the pattern_list. *field* is the title of a field in the
header such as from, subject, date, etc. The information is returned in a
tcl list where each element is of the form:
msgid value
Where msgid is the number of the message and value is the value set for the
queried field. The *range* argument can be in any of the following forms:
* *msgid*
The message specified by *msgid* is queried.
* *msgid1*-*msgid2*
All messages between *msgid1* and *msgid2* (including *msgid1* and
*msgid2*) are queried.
* *msgid1* *msgid2*
All messages between *msgid1* and *msgid2* (including *msgid1* and
*msgid2*) are queried.
# <a name='section3'></a>EXAMPLE
A bigger example for posting a single article.
package require nntp
set n [nntp::nntp NNTP_SERVER]
$n post "From: [email protected] (USER_FULL)
Path: COMPUTERNAME!USERNAME
Newsgroups: alt.test
Subject: Tcl test post -ignore
Message-ID: <[pid][clock seconds]
@COMPUTERNAME>
Date: [clock format [clock seconds] -format "%a, %d %
b %y %H:%M:%S GMT" -gmt true]
Test message body"
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nntp* 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.
# <a name='keywords'></a>KEYWORDS
[news](../../../../index.md#news), [nntp](../../../../index.md#nntp),
[nntpclient](../../../../index.md#nntpclient), [rfc
1036](../../../../index.md#rfc_1036), [rfc 977](../../../../index.md#rfc_977)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/ntp/ntp_time.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
[//000000001]: # (ntp_time - Network Time Facilities)
[//000000002]: # (Generated from file 'ntp_time.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ntp_time(n) 1.2.1 tcllib "Network Time Facilities")
# NAME
ntp_time - Tcl Time Service Client
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.0
package require time ?1.2.1?
[__::time::gettime__ ?*options*? *timeserver* ?*port*?](#1)
[__::time::getsntp__ ?*options*? *timeserver* ?*port*?](#2)
[__::time::configure__ ?*options*?](#3)
[__::time::cget__ *name*](#4)
[__::time::unixtime__ *token*](#5)
[__::time::status__ *token*](#6)
[__::time::error__ *token*](#7)
[__::time::reset__ *token* *?reason?*](#8)
[__::time::wait__ *token*](#9)
[__::time::cleanup__ *token*](#10)
# <a name='description'></a>DESCRIPTION
This package implements a client for the RFC 868 TIME protocol
([http://www.rfc-editor.org/rfc/rfc868.txt](http://www.rfc-editor.org/rfc/rfc868.txt))
and also a minimal client for the RFC 2030 Simple Network Time Protocol
([http://www.rfc-editor.org/rfc/rfc2030.txt](http://www.rfc-editor.org/rfc/rfc2030.txt)).
RFC 868 returns the time in seconds since 1 January 1900 to either tcp or udp
clients. RFC 2030 also gives this time but also provides a fractional part which
is not used in this client.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::time::gettime__ ?*options*? *timeserver* ?*port*?
Get the time from *timeserver*. You may specify any of the options listed
for the __configure__ command here. This command returns a token which must
then be used with the remaining commands in this package. Once you have
finished, you should use __[cleanup](../../../../index.md#cleanup)__ to
release all resources. The default port is __37__.
- <a name='2'></a>__::time::getsntp__ ?*options*? *timeserver* ?*port*?
Get the time from an SNTP server. This accepts exactly the same arguments as
__::time::gettime__ except that the default port is __123__. The result is a
token as per __::time::gettime__ and should be handled in the same way.
Note that it is unlikely that any SNTP server will reply using tcp so you
will require the __tcludp__ or the __ceptcl__ package. If a suitable package
can be loaded then the udp protocol will be used by default.
- <a name='3'></a>__::time::configure__ ?*options*?
Called with no arguments this command returns all the current configuration
options and values. Otherwise it should be called with pairs of option name
and value.
* __-protocol__ *number*
Set the default network protocol. This defaults to udp if the tcludp
package is available. Otherwise it will use tcp.
* __-port__ *number*
Set the default port to use. RFC 868 uses port __37__, RFC 2030 uses
port __123__.
* __-timeout__ *number*
Set the default timeout value in milliseconds. The default is 10
seconds.
* __-command__ *number*
Set a command procedure to be run when a reply is received. The
procedure is called with the time token appended to the argument list.
* __-loglevel__ *number*
Set the logging level. The default is 'warning'.
- <a name='4'></a>__::time::cget__ *name*
Get the current value for the named configuration option.
- <a name='5'></a>__::time::unixtime__ *token*
Format the returned time for the unix epoch. RFC 868 time defines time 0 as
1 Jan 1900, while unix time defines time 0 as 1 Jan 1970. This command
converts the reply to unix time.
- <a name='6'></a>__::time::status__ *token*
Returns the status flag. For a successfully completed query this will be
*ok*. May be *error* or *timeout* or *eof*. See also __::time::error__
- <a name='7'></a>__::time::error__ *token*
Returns the error message provided for requests whose status is *error*. If
there is no error message then an empty string is returned.
- <a name='8'></a>__::time::reset__ *token* *?reason?*
Reset or cancel the query optionally specfying the reason to record for the
__[error](../../../../index.md#error)__ command.
- <a name='9'></a>__::time::wait__ *token*
Wait for a query to complete and return the status upon completion.
- <a name='10'></a>__::time::cleanup__ *token*
Remove all state variables associated with the request.
% set tok [::time::gettime ntp2a.mcc.ac.uk]
% set t [::time::unixtime $tok]
% ::time::cleanup $tok
% set tok [::time::getsntp pool.ntp.org]
% set t [::time::unixtime $tok]
% ::time::cleanup $tok
proc on_time {token} {
if {[time::status $token] eq "ok"} {
puts [clock format [time::unixtime $token]]
} else {
puts [time::error $token]
}
time::cleanup $token
}
time::getsntp -command on_time pool.ntp.org
# <a name='section3'></a>AUTHORS
Pat Thoyts
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ntp* 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.
# <a name='see-also'></a>SEE ALSO
ntp
# <a name='keywords'></a>KEYWORDS
[NTP](../../../../index.md#ntp), [SNTP](../../../../index.md#sntp), [rfc
2030](../../../../index.md#rfc_2030), [rfc 868](../../../../index.md#rfc_868),
[time](../../../../index.md#time)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/oauth/oauth.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
[//000000001]: # (oauth - oauth)
[//000000002]: # (Generated from file 'oauth.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (oauth(n) 1.0.2 tcllib "oauth")
# NAME
oauth - oauth API base signature
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TLS Security Considerations](#section2)
- [Commands](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require oauth ?1.0.2?
[__::oauth::config__](#1)
[__::oauth::config__ ?*options*...?](#2)
[__::oauth::header__ *baseURL* ?*postQuery*?](#3)
[__::oauth::query__ *baseURL* ?*postQuery*?](#4)
# <a name='description'></a>DESCRIPTION
The __oauth__ package provides a simple Tcl-only library for communication with
[oauth](http://oauth.net) APIs. This current version of the package supports the
Oauth 1.0 Protocol, as specified in [RFC
5849](http://tools.ietf.org/rfc/rfc5849.txt).
# <a name='section2'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section3'></a>Commands
- <a name='1'></a>__::oauth::config__
When this command is invoked without arguments it returns a dictionary
containing the current values of all options.
- <a name='2'></a>__::oauth::config__ ?*options*...?
When invoked with arguments, options followed by their values, it is used to
set and query various parameters of application and client, like proxy host
and user agent for the HTTP requests. The detailed list of options is below:
* __-accesstoken__ *string*
This is the user's token.
* __-accesstokensecret__ *string*
This is the user's secret token.
* __-consumerkey__ *string*
This is the public token of your app.
* __-consumersecret__ *string*
This is the private token of your app.
* __-debug__ *bool*
The default value is __off__. If you change this option to __on__, the
basic signature just created will be printed to stdout, among other
debug output.
* __-oauthversion__ *version*
This is the version of the OAuth protocol to use. At the moment only
__1.0__ is supported, the default.
* __-proxyhost__ *hostname*
You can set up a proxy host for send contact the oauth's api server.
* __-proxyport__ *port-number*
Port number of your proxy.
* __-signmethod__ *method*
The signature method to use. OAuth 1.0 only supports __HMAC-SHA1__, the
default.
* __-timeout__ *milliseconds*
Timeout in milliseconds for your query. The default value is __6000__,
i.e. 6 seconds.
* __-urlencoding__ *encoding*
The encoding used for creating the x-url-encoded URLs with
__::http::formatQuery__. The default is __utf-8__, as specified by [RFC
2718](http://tools.ietf.org/rfc/rfc2718.txt).
- <a name='3'></a>__::oauth::header__ *baseURL* ?*postQuery*?
This command is the base signature creator. With proper settings for various
tokens and secrets (See __::oauth::config__) the result is the base
authentication string to send to the server.
You do not need to call this procedure to create the query because
__::oauth::query__ (see below) will do for it for you. Doing so is useful
for debugging purposes, though.
* url *baseURL*
This argument is the URI path to the OAuth API server. If you plan send
a GET query, you should provide a full path.
HTTP GET
::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente}
* url-encoded-string *postQuery*
When you have to send a header in POST format, you have to put the query
string into this argument.
::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true}
- <a name='4'></a>__::oauth::query__ *baseURL* ?*postQuery*?
This procedure will use the settings made with __::oauth::config__ to create
the basic authentication and then send the command to the server API. It
takes the same arguments as __::oauth::header__.
The returned result will be a list containing 2 elements. The first element
will be a dictionary containing the HTTP header data response. This allows
you, for example, to check the X-Rate-Limit from OAuth. The second element
will be the raw data returned from API server. This string is usually a json
object which can be further decoded with the functions of package
__[json](../json/json.md)__, or any other json-parser for Tcl.
Here is an example of how it would work in Twitter. Do not forget to replace
the placeholder tokens and keys of the example with your own tokens and keys
when trying it out.
% package require oauth
% package require json
% oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret}
% set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente]
% set jsondata [lindex $response 1]
% set data [json::json2dict $jsondata]
$ set data [lindex $data 0]
% dict for {key val} $data {puts "$key => $val"}
id => 158812437
id_str => 158812437
name => Un Librepensador
screen_name => AbiertaMente
location => Explico mis tuits ahà →
description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mà me sobrarÃan 20 para contaros todo lo q
url => http://t.co/SGs3k9odBn
entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}}
protected => false
followers_count => 72705
friends_count => 53099
listed_count => 258
created_at => Wed Jun 23 18:29:58 +0000 2010
favourites_count => 297
utc_offset => 7200
time_zone => Madrid
geo_enabled => false
verified => false
statuses_count => 8996
lang => es
status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name ἙλÎνη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und
contributors_enabled => false
is_translator => true
is_translation_enabled => false
profile_background_color => 709397
profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
profile_background_tile => true
profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874
profile_link_color => FF3300
profile_sidebar_border_color => FFFFFF
profile_sidebar_fill_color => A0C5C7
profile_text_color => 333333
profile_use_background_image => true
default_profile => false
default_profile_image => false
following => true
follow_request_sent => false
notifications => false
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *oauth* 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.
# <a name='keywords'></a>KEYWORDS
[RFC 2718](../../../../index.md#rfc_2718), [RFC
5849](../../../../index.md#rfc_5849), [oauth](../../../../index.md#oauth),
[twitter](../../../../index.md#twitter)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2014 Javi P. <[email protected]>
|
Added embedded/md/tcllib/files/modules/oometa/oometa.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
[//000000001]: # (oometa - Data registry for TclOO frameworks)
[//000000002]: # (Generated from file 'oometa.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (oometa(n) 0.7.1 tcllib "Data registry for TclOO frameworks")
# NAME
oometa - oo::meta A data registry for classess
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Usage](#section2)
- [Concept](#section3)
- [COMMANDS](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
[__oo::meta::info__](#1)
[__oo::meta::info branchget__ ?*key*? ?...?](#2)
[__oo::meta::info branchset__ ?*key...*? *key* *value*](#3)
[__oo::meta::info dump__ *class*](#4)
[__oo::meta::info__ *class* __is__ *type* ?*args*?](#5)
[__oo::meta::info__ *class* __[merge](../../../../index.md#merge)__ ?*dict*? ?*dict*? ?*...*?](#6)
[__oo::meta::info__ *class* __rebuild__](#7)
[__oo::meta::metadata__ *class*](#8)
[__oo::define meta__](#9)
[__oo::class method meta__](#10)
[__oo::object method meta__](#11)
[__oo::object method meta cget__ ?*field*? ?*...*? *field*](#12)
# <a name='description'></a>DESCRIPTION
The __oo::meta__ package provides a data registry service for TclOO classes.
# <a name='section2'></a>Usage
oo::class create animal {
meta set biodata animal: 1
}
oo::class create mammal {
superclass animal
meta set biodata mammal: 1
}
oo::class create cat {
superclass mammal
meta set biodata diet: carnivore
}
cat create felix
puts [felix meta dump biodata]
> animal: 1 mammal: 1 diet: carnivore
felix meta set biodata likes: {birds mice}
puts [felix meta get biodata]
> animal: 1 mammal: 1 diet: carnivore likes: {bird mice}
# Modify a class
mammal meta set biodata metabolism: warm-blooded
puts [felix meta get biodata]
> animal: 1 mammal: 1 metabolism: warm-blooded diet: carnivore likes: {birds mice}
# Overwrite class info
felix meta set biodata mammal: yes
puts [felix meta get biodata]
> animal: 1 mammal: yes metabolism: warm-blooded diet: carnivore likes: {birds mice}
# <a name='section3'></a>Concept
The concept behind __oo::meta__ is that each class contributes a snippet of
*local* data. When __oo::meta::metadata__ is called, the system walks through
the linear ancestry produced by __oo::meta::ancestors__, and recursively
combines all of that local data for all of a class' ancestors into a single
dict. Instances of oo::object can also combine class data with a local dict
stored in the *meta* variable.
# <a name='section4'></a>COMMANDS
- <a name='1'></a>__oo::meta::info__
__oo::meta::info__ is intended to work on the metadata of a class in a
manner similar to if the aggregate pieces where assembled into a single
dict. The system mimics all of the standard dict commands, and addes the
following:
- <a name='2'></a>__oo::meta::info branchget__ ?*key*? ?...?
Returns a dict representation of the element at *args*, but with any
trailing : removed from field names.
::oo::meta::info $myclass set option color {default: green widget: colorselect}
puts [::oo::meta::info $myclass get option color]
> {default: green widget: color}
puts [::oo::meta::info $myclass branchget option color]
> {default green widget color}
- <a name='3'></a>__oo::meta::info branchset__ ?*key...*? *key* *value*
Merges *dict* with any other information contaned at node ?*key...*?, and
adding a trailing : to all field names.
::oo::meta::info $myclass branchset option color {default green widget colorselect}
puts [::oo::meta::info $myclass get option color]
> {default: green widget: color}
- <a name='4'></a>__oo::meta::info dump__ *class*
Returns the complete snapshot of a class metadata, as producted by
__oo::meta::metadata__
- <a name='5'></a>__oo::meta::info__ *class* __is__ *type* ?*args*?
Returns a boolean true or false if the element ?*args*? would match __string
is__ *type* *value*
::oo::meta::info $myclass set constant mammal 1
puts [::oo::meta::info $myclass is true constant mammal]
> 1
- <a name='6'></a>__oo::meta::info__ *class* __[merge](../../../../index.md#merge)__ ?*dict*? ?*dict*? ?*...*?
Combines all of the arguments into a single dict, which is then stored as
the new local representation for this class.
- <a name='7'></a>__oo::meta::info__ *class* __rebuild__
Forces the meta system to destroy any cached representation of a class'
metadata before the next access to __oo::meta::metadata__
- <a name='8'></a>__oo::meta::metadata__ *class*
Returns an aggregate picture of the metadata for *class*, combining its
*local* data with the *local* data from its ancestors.
- <a name='9'></a>__oo::define meta__
The package injects a command __oo::define::meta__ which works to provide a
class in the process of definition access to __oo::meta::info__, but without
having to look the name up.
oo::define myclass {
meta set foo bar: baz
}
- <a name='10'></a>__oo::class method meta__
The package injects a new method __meta__ into __oo::class__ which works to
provide a class instance access to __oo::meta::info__.
- <a name='11'></a>__oo::object method meta__
The package injects a new method __meta__ into __oo::object__.
__oo::object__ combines the data for its class (as provided by
__oo::meta::metadata__), with a local variable *meta* to produce a local
picture of metadata. This method provides the following additional commands:
- <a name='12'></a>__oo::object method meta cget__ ?*field*? ?*...*? *field*
Attempts to locate a singlar leaf, and return its value. For single option
lookups, this is faster than __my meta getnull__ ?*field*? ?*...*? *field*],
because it performs a search instead directly instead of producing the
recursive merge product between the class metadata, the local *meta*
variable, and THEN performing the search.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tcloo* 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.
# <a name='keywords'></a>KEYWORDS
[TOOL](../../../../index.md#tool), [TclOO](../../../../index.md#tcloo)
# <a name='category'></a>CATEGORY
TclOO
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/ooutil/ooutil.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
[//000000001]: # (oo::util - Utility commands for TclOO)
[//000000002]: # (Generated from file 'ooutil.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (oo::util(n) 1.2.2 tcllib "Utility commands for TclOO")
# NAME
oo::util - Utility commands for TclOO
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require oo::util ?1.2.2?
[__mymethod__ *method* ?*arg*...?](#1)
[__classmethod__ *name* *arguments* *body*](#2)
[__classvariable__ ?*arg*...?](#3)
[__link__ *method*...](#4)
[__link__ {*alias* *method*}...](#5)
[__ooutil::singleton__ ?*arg*...?](#6)
# <a name='description'></a>DESCRIPTION
This package provides a convenience command for the easy specification of
instance methods as callback commands, like timers, file events, Tk bindings,
etc.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__mymethod__ *method* ?*arg*...?
This command is available within instance methods. It takes a method name
and, possibly, arguments for the method and returns a command prefix which,
when executed, will invoke the named method of the object we are in, with
the provided arguments, and any others supplied at the time of actual
invokation.
Note: The command is equivalent to and named after the command provided by
the OO package __[snit](../snit/snit.md)__ for the same purpose.
- <a name='2'></a>__classmethod__ *name* *arguments* *body*
This command is available within class definitions. It takes a method name
and, possibly, arguments for the method and creates a method on the class,
available to a user of the class and of derived classes.
Note: The command is equivalent to the command __typemethod__ provided by
the OO package __[snit](../snit/snit.md)__ for the same purpose.
Example
oo::class create ActiveRecord {
classmethod find args { puts "[self] called with arguments: $args" }
}
oo::class create Table {
superclass ActiveRecord
}
puts [Table find foo bar]
# ======
# which will write
# ======
# ::Table called with arguments: foo bar
- <a name='3'></a>__classvariable__ ?*arg*...?
This command is available within instance methods. It takes a series of
variable names and makes them available in the method's scope. The
originating scope for the variables is the class (instance) the object
instance belongs to. In other words, the referenced variables are shared
between all instances of their class.
Note: The command is roughly equivalent to the command __typevariable__
provided by the OO package __[snit](../snit/snit.md)__ for the same purpose.
The difference is that it cannot be used in the class definition itself.
Example:
% oo::class create Foo {
method bar {z} {
classvariable x y
return [incr x $z],[incr y]
}
}
::Foo
% Foo create a
::a
% Foo create b
::b
% a bar 2
2,1
% a bar 3
5,2
% b bar 7
12,3
% b bar -1
11,4
% a bar 0
11,5
- <a name='4'></a>__link__ *method*...
- <a name='5'></a>__link__ {*alias* *method*}...
This command is available within instance methods. It takes a list of method
names and/or pairs of alias- and method-name and makes the named methods
available to all instance methods without requiring the __my__ command.
The alias name under which the method becomes available defaults to the
method name, except where explicitly specified through an alias/method pair.
Examples:
link foo
# The method foo is now directly accessible as foo instead of my foo.
link {bar foo}
# The method foo is now directly accessible as bar.
link a b c
# The methods a, b, and c all become directly acessible under their
# own names.
The main use of this command is expected to be in instance constructors, for
convenience, or to set up some methods for use in a mini DSL.
- <a name='6'></a>__ooutil::singleton__ ?*arg*...?
This command is a meta-class, i.e. a variant of the builtin __oo::class__
which ensures that it creates only a single instance of the classes defined
with it.
Syntax and results are like for __oo::class__.
Example:
% oo::class create example {
self mixin singleton
method foo {} {self}
}
::example
% [example new] foo
::oo::Obj22
% [example new] foo
::oo::Obj22
# <a name='section3'></a>AUTHORS
Donal Fellows, Andreas Kupries
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *oo::util* 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.
# <a name='see-also'></a>SEE ALSO
[snit(n)](../snit/snit.md)
# <a name='keywords'></a>KEYWORDS
[TclOO](../../../../index.md#tcloo), [callback](../../../../index.md#callback),
[class methods](../../../../index.md#class_methods), [class
variables](../../../../index.md#class_variables), [command
prefix](../../../../index.md#command_prefix),
[currying](../../../../index.md#currying), [method
reference](../../../../index.md#method_reference), [my
method](../../../../index.md#my_method),
[singleton](../../../../index.md#singleton)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011-2015 Andreas Kupries, BSD licensed
|
Added embedded/md/tcllib/files/modules/otp/otp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
[//000000001]: # (otp - RFC 2289 A One-Time Password System)
[//000000002]: # (Generated from file 'otp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (otp(n) 1.0.0 tcllib "RFC 2289 A One-Time Password System")
# NAME
otp - One-Time Passwords
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require otp ?1.0.0?
[__::otp::otp-md4__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#1)
[__::otp::otp-md5__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#2)
[__::otp::otp-sha1__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#3)
[__::otp::otp-rmd160__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*](#4)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the One-Time Password system as
described in RFC 2289 (1). This system uses message-digest algorithms to
sequentially hash a passphrase to create single-use passwords. The resulting
data is then provided to the user as either hexadecimal digits or encoded using
a dictionary of 2048 words. This system is used by OpenBSD for secure login and
can be used as a SASL mechanism for authenticating users.
In this implementation we provide support for four algorithms that are included
in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4) and SHA-1 (5).
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::otp::otp-md4__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*
- <a name='2'></a>__::otp::otp-md5__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*
- <a name='3'></a>__::otp::otp-sha1__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*
- <a name='4'></a>__::otp::otp-rmd160__ ?*-hex*? ?*-words*? *-seed seed* *-count count* *data*
# <a name='section3'></a>EXAMPLES
% otp::otp-md5 -count 99 -seed host67821 "My Secret Pass Phrase"
(binary gibberish)
% otp::otp-md5 -words -count 99 -seed host67821 "My Secret Pass Phrase"
SOON ARAB BURG LIMB FILE WAD
% otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase"
e249b58257c80087
# <a name='section4'></a>REFERENCES
1. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998.
[http://www.rfc-editor.org/rfc/rfc2289.txt](http://www.rfc-editor.org/rfc/rfc2289.txt)
1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data
Security, Inc, April 1992.
([http://www.rfc-editor.org/rfc/rfc1321.txt](http://www.rfc-editor.org/rfc/rfc1321.txt))
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened
version of RIPEMD"
[http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf](http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf)
1. "Secure Hash Standard", National Institute of Standards and Technology,
U.S. Department Of Commerce, April 1995.
([http://www.itl.nist.gov/fipspubs/fip180-1.htm](http://www.itl.nist.gov/fipspubs/fip180-1.htm))
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *otp* 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.
# <a name='see-also'></a>SEE ALSO
[SASL](../sasl/sasl.md), [md4](../md4/md4.md), [md5](../md5/md5.md),
[ripemd160](../ripemd/ripemd160.md), [sha1](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[hashing](../../../../index.md#hashing),
[message-digest](../../../../index.md#message_digest),
[password](../../../../index.md#password), [rfc
2289](../../../../index.md#rfc_2289), [security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_intro.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
[//000000001]: # (page_intro - Parser generator tools)
[//000000002]: # (Generated from file 'page_intro.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_intro(n) 1.0 tcllib "Parser generator tools")
# NAME
page_intro - page introduction
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
*[page](../../../../index.md#page)* (short for *parser generator*) stands for a
set of related packages which help in the construction of parser generators, and
other utilities doing text processing.
They are mainly geared towards supporting the Tcllib application
__[page](../../apps/page.md)__, with the package __page::pluginmgr__ in a
central role as the plugin management for the application. The other packages
are performing low-level text processing and utility tasks geared towards parser
generation and mainly accessed by __[page](../../apps/page.md)__ through
plugins.
The packages implementing the plugins are not documented as regular packages, as
they cannot be loaded into a general interpreter, like tclsh, without extensive
preparation of the interpreter. Preparation which is done for them by the plugin
manager.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[page](../../../../index.md#page), [parser
generator](../../../../index.md#parser_generator), [text
processing](../../../../index.md#text_processing)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_pluginmgr.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
|
[//000000001]: # (page_pluginmgr - Parser generator tools)
[//000000002]: # (Generated from file 'page_pluginmgr.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_pluginmgr(n) 1.0 tcllib "Parser generator tools")
# NAME
page_pluginmgr - page plugin manager
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [CONFIG PLUGIN API](#section3)
- [READER PLUGIN API](#section4)
- [WRITER PLUGIN API](#section5)
- [TRANSFORM PLUGIN API](#section6)
- [PREDEFINED PLUGINS](#section7)
- [FEATURES](#section8)
- [Bugs, Ideas, Feedback](#section9)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require page::pluginmgr ?0.2?
package require fileutil
[__::page::pluginmgr::reportvia__ *cmd*](#1)
[__::page::pluginmgr::report__ *level* *text* ?*from* ?*to*??](#2)
[__::page::pluginmgr::log__ *cmd*](#3)
[__::page::pluginmgr::configuration__ *name*](#4)
[__::page::pluginmgr::reader__ *name*](#5)
[__::page::pluginmgr::rconfigure__ *dict*](#6)
[__::page::pluginmgr::rtimeable__](#7)
[__::page::pluginmgr::rtime__](#8)
[__::page::pluginmgr::rgettime__](#9)
[__::page::pluginmgr::rhelp__](#10)
[__::page::pluginmgr::rlabel__](#11)
[__::page::pluginmgr::read__ *read* *eof* ?*complete*?](#12)
[*read* *num*](#13)
[*eof*](#14)
[*done*](#15)
[__::page::pluginmgr::writer__ *name*](#16)
[__::page::pluginmgr::wconfigure__ *dict*](#17)
[__::page::pluginmgr::wtimeable__](#18)
[__::page::pluginmgr::wtime__](#19)
[__::page::pluginmgr::wgettime__](#20)
[__::page::pluginmgr::whelp__](#21)
[__::page::pluginmgr::wlabel__](#22)
[__::page::pluginmgr::write__ *chan* *data*](#23)
[__::page::pluginmgr::transform__ *name*](#24)
[__::page::pluginmgr::tconfigure__ *id* *dict*](#25)
[__::page::pluginmgr::ttimeable__ *id*](#26)
[__::page::pluginmgr::ttime__ *id*](#27)
[__::page::pluginmgr::tgettime__ *id*](#28)
[__::page::pluginmgr::thelp__ *id*](#29)
[__::page::pluginmgr::tlabel__ *id*](#30)
[__::page::pluginmgr::transform_do__ *id* *data*](#31)
[__page_cdefinition__](#32)
[__page_rfeature__ *name*](#33)
[__page_rtime__](#34)
[__page_rgettime__](#35)
[__page_rlabel__](#36)
[__page_rhelp__](#37)
[__page_roptions__](#38)
[__page_rconfigure__ *option* *value*](#39)
[__page_rrun__](#40)
[__page_read__ *num*](#41)
[__page_read_done__](#42)
[__page_eof__](#43)
[__page_info__ *text* ?*from* ?*to*??](#44)
[__page_warning__ *text* ?*from* ?*to*??](#45)
[__page_error__ *text* ?*from* ?*to*??](#46)
[__page_log_info__ *text*](#47)
[__page_log_warning__ *text*](#48)
[__page_log_error__ *text*](#49)
[__page_wfeature__](#50)
[__page_wtime__](#51)
[__page_wgettime__](#52)
[__page_wlabel__](#53)
[__page_whelp__](#54)
[__page_woptions__](#55)
[__page_wconfigure__ *option* *value*](#56)
[__page_wrun__ *chan* *data*](#57)
[__page_info__ *text* ?*from* ?*to*??](#58)
[__page_warning__ *text* ?*from* ?*to*??](#59)
[__page_error__ *text* ?*from* ?*to*??](#60)
[__page_log_info__ *text*](#61)
[__page_log_warning__ *text*](#62)
[__page_log_error__ *text*](#63)
[__page_tfeature__](#64)
[__page_ttime__](#65)
[__page_tgettime__](#66)
[__page_tlabel__](#67)
[__page_thelp__](#68)
[__page_toptions__](#69)
[__page_tconfigure__ *option* *value*](#70)
[__page_trun__ *chan* *data*](#71)
[__page_info__ *text* ?*from* ?*to*??](#72)
[__page_warning__ *text* ?*from* ?*to*??](#73)
[__page_error__ *text* ?*from* ?*to*??](#74)
[__page_log_info__ *text*](#75)
[__page_log_warning__ *text*](#76)
[__page_log_error__ *text*](#77)
# <a name='description'></a>DESCRIPTION
This package provides the plugin manager central to the
__[page](../../apps/page.md)__ application. It manages the various reader,
writer, configuration, and transformation plugins which actually process the
text (read, transform, and write).
All plugins are loaded into slave interpreters specially prepared for them.
While implemented using packages they need this special environment and are not
usable in a plain interpreter, like tclsh. Because of that they are only
described in general terms in section [PREDEFINED PLUGINS](#section7), and not
documented as regular packages. It is expected that they follow the APIs
specified in the sections
1. [CONFIG PLUGIN API](#section3)
1. [READER PLUGIN API](#section4)
1. [WRITER PLUGIN API](#section5)
1. [TRANSFORM PLUGIN API](#section6)
as per their type.
# <a name='section2'></a>API
- <a name='1'></a>__::page::pluginmgr::reportvia__ *cmd*
This command defines the callback command used by
__::page::pluginmgr::report__ (see below) to report input errors and
warnings. The default is to write such reports to the standard error
channel.
- <a name='2'></a>__::page::pluginmgr::report__ *level* *text* ?*from* ?*to*??
This command is used to report input errors and warnings. By default such
reports are written to the standard error. This can be changed by setting a
user-specific callback command with __::page::pluginmgr::reportvia__ (see
above).
The arguments *level* and *text* specify both the importance of the message,
and the message itself. For the former see the package
__[logger](../log/logger.md)__ for the allowed values.
The optional argument *from* and *to* can be used by the caller to indicate
the location (or range) in the input where the reported problem occured.
Each is a list containing two elements, the line and the column in the
input, in this order.
- <a name='3'></a>__::page::pluginmgr::log__ *cmd*
This command defines a log callback command to be used by loaded plugins for
the reporting of internal errors, warnings, and general information.
Specifying the empty string as callback disables logging.
Note: The *cmd* has to be created by the __[logger](../log/logger.md)__
package, or follow the same API as such.
The command returns the empty string as its result.
- <a name='4'></a>__::page::pluginmgr::configuration__ *name*
This command loads the named configuration plugin, retrieves the options
encoded in it, and then immediately unloads it again.
If the *name* is the path to a file, then this files will be tried to be
loaded as a plugin first, and, if that fails, opened and its contents read
as a list of options and their arguments, separated by spaces, tabs and
newlines, possibly quotes with single and double quotes.
See section [CONFIG PLUGIN API](#section3) for the API expected of
configuration plugins.
The result of the command is the list of options retrieved.
- <a name='5'></a>__::page::pluginmgr::reader__ *name*
This command loads the named reader plugin and initializes it. The result of
the command is a list of options the plugin understands.
Only a single reader plugin can be loaded. Loading another reader plugin
causes the previously loaded reader plugin to be de-initialized and
unloaded.
See section [READER PLUGIN API](#section4) for the API expected of reader
plugins.
- <a name='6'></a>__::page::pluginmgr::rconfigure__ *dict*
This commands configures the loaded reader plugin. The options and their
values are provided as a Tcl dictionary. The result of the command is the
empty string.
- <a name='7'></a>__::page::pluginmgr::rtimeable__
This commands checks if the loaded reader plugin is able to collect timing
statistics. The result of the command is a boolean flag. The result is
__true__ if the plugin can be timed, and __false__ otherwise.
- <a name='8'></a>__::page::pluginmgr::rtime__
This command activates the collection of timing statistics in the loaded
reader plugin.
- <a name='9'></a>__::page::pluginmgr::rgettime__
This command retrieves the collected timing statistics of the loaded reader
plugin after it was executed.
- <a name='10'></a>__::page::pluginmgr::rhelp__
This command retrieves the help string of the loaded reader plugin. This is
expected to be in *[doctools](../../../../index.md#doctools)* format.
- <a name='11'></a>__::page::pluginmgr::rlabel__
This command retrieves the human-readable name of the loaded reader plugin.
- <a name='12'></a>__::page::pluginmgr::read__ *read* *eof* ?*complete*?
This command invokes the loaded reader plugin to process the input, and
returns the results of the plugin as its own result. The input is accessible
through the callback commands *read*, and *eof*. The optional *done* can be
used to intrecept when the plugin has completed its processing. All
arguments are command prefixes.
The plugin will invoke the various callbacks in the following situations:
* <a name='13'></a>*read* *num*
is invoked whenever input to process is needed, with the number of
characters/bytes it asks for. The result is expected to be the input the
plugin is in need of.
* <a name='14'></a>*eof*
is invoked by the plugin to check if the input has reached the of the
stream. The result is expected to be a boolean flag, __true__ when the
input has hit EOF, and __false__ otherwise.
* <a name='15'></a>*done*
is invoked when the plugin has completed the processing of the input.
- <a name='16'></a>__::page::pluginmgr::writer__ *name*
This command loads the named writer plugin and initializes it. The result of
the command is a list of options the plugin understands.
Only a single reader plugin can be loaded. Loading another reader plugin
causes the previously loaded reader plugin to be de-initialized and
unloaded.
See section [WRITER PLUGIN API](#section5) for the API expected of writer
plugins.
- <a name='17'></a>__::page::pluginmgr::wconfigure__ *dict*
This commands configures the loaded writer plugin. The options and their
values are provided as a Tcl dictionary. The result of the command is the
empty string.
- <a name='18'></a>__::page::pluginmgr::wtimeable__
This commands checks if the loaded writer plugin is able to measure
execution times. The result of the command is a boolean flag. The result is
__true__ if the plugin can be timed, and __false__ otherwise.
- <a name='19'></a>__::page::pluginmgr::wtime__
This command activates the collection of timing statistics in the loaded
writer plugin.
- <a name='20'></a>__::page::pluginmgr::wgettime__
This command retrieves the collected timing statistics of the loaded writer
plugin after it was executed.
- <a name='21'></a>__::page::pluginmgr::whelp__
This command retrieves the help string of the loaded writer plugin. This is
expected to be in *[doctools](../../../../index.md#doctools)* format.
- <a name='22'></a>__::page::pluginmgr::wlabel__
This command retrieves the human-readable name of the loaded writer plugin.
- <a name='23'></a>__::page::pluginmgr::write__ *chan* *data*
The loaded writer plugin is invoked to generate the output. It is given the
*data* to generate the outpout from, and the Tcl handle *chan* of the
channel to write the generated output to. The command returns th empty
string as its result.
- <a name='24'></a>__::page::pluginmgr::transform__ *name*
This command loads the named transformation plugin and initializes it. The
result of the command is a 2-element list containing the plugin id and a
list of options the plugin understands, in this order.
Multiple transformations plugins can be loaded and are identified by
handles.
See section [TRANSFORM PLUGIN API](#section6) for the API expected of
transformation plugins.
- <a name='25'></a>__::page::pluginmgr::tconfigure__ *id* *dict*
This commands configures the identified transformation plugin. The options
and their values are provided as a Tcl dictionary. The result of the command
is the empty string.
- <a name='26'></a>__::page::pluginmgr::ttimeable__ *id*
This commands checks if the identified transformation plugin is able to
collect timing statistics. The result of the command is a boolean flag. The
result is __true__ if the plugin can be timed, and __false__ otherwise.
- <a name='27'></a>__::page::pluginmgr::ttime__ *id*
This command activates the collection of timing statistics in the identified
transformation plugin.
- <a name='28'></a>__::page::pluginmgr::tgettime__ *id*
This command retrieves the collected timing statistics of the identified
transformation plugin after it was executed.
- <a name='29'></a>__::page::pluginmgr::thelp__ *id*
This command retrieves the help string of the identified transformation
plugin. This is expected to be in
*[doctools](../../../../index.md#doctools)* format.
- <a name='30'></a>__::page::pluginmgr::tlabel__ *id*
This command retrieves the human-readable name of the identified
transformation plugin.
- <a name='31'></a>__::page::pluginmgr::transform_do__ *id* *data*
The identified transformation plugin is invoked to process the specified
*data*. The result of the plugin is returned as the result of the command.
# <a name='section3'></a>CONFIG PLUGIN API
Configuration plugins are expected to provide a single command, described below.
- <a name='32'></a>__page_cdefinition__
This command of a configuration plugin is called by the plugin manager to
execute it. Its result has to be a list of options and values to process.
Configuration plugins do not expect the environment to provide any special
commands.
It is expected that a configuration plugin __FOO__ is implemented by the package
__page::config::__FOO____.
Configuration plugins are loaded, executed, and unloaded in one step, they are
not kept in memory. The command for doing this is
__::page::pluginmgr::configuration__.
# <a name='section4'></a>READER PLUGIN API
Reader plugins are expected to provide the following commands, described below.
- <a name='33'></a>__page_rfeature__ *name*
This command takes a feature *name* and returns a boolean flag indicating
whether the feature is supported by the plugin, or not. The result has to be
__true__ if the feature is supported, and __false__ otherwise.
See section [FEATURES](#section8) for the possible features the plugin
manager will ask for.
- <a name='34'></a>__page_rtime__
This command is invoked to activate the collection of timing statistics.
- <a name='35'></a>__page_rgettime__
This command is invoked to retrieve the collected timing statistics.
- <a name='36'></a>__page_rlabel__
This command is invoked to retrieve a human-readable label for the plugin.
- <a name='37'></a>__page_rhelp__
This command is invoked to retrieve a help text for plugin. The text is
expected to be in *[doctools](../../../../index.md#doctools)* format.
- <a name='38'></a>__page_roptions__
This command is invoked to retrieve the options understood by the plugin.
- <a name='39'></a>__page_rconfigure__ *option* *value*
This command is invoked to reconfigure the plugin, specifically the given
*option* is set to the new *value*.
- <a name='40'></a>__page_rrun__
This command is invoked to process the input stream per the current plugin
configuration. The result of the command is the result of the processing.
Reader plugins expect the environment to provide the following special commands.
- <a name='41'></a>__page_read__ *num*
This command is invoked to read *num* characters/bytes from the input. Its
result has to be read characters/bytes.
- <a name='42'></a>__page_read_done__
This command is invoked to signal that the plugin has completed the
processing of the input.
- <a name='43'></a>__page_eof__
This command is invoked to check if the input stream has reached its end.
Its result has to be a boolean flag, __true__ when the input has reached the
end, __false__ otherwise.
- <a name='44'></a>__page_info__ *text* ?*from* ?*to*??
Invoked to report some information to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a 2-element
list containing line and column numbers.
- <a name='45'></a>__page_warning__ *text* ?*from* ?*to*??
Invoked to report a warning to the user. May indicate a location or range in
the input. Each piece of location data, if provided, is a 2-element list
containing line and column numbers.
- <a name='46'></a>__page_error__ *text* ?*from* ?*to*??
Invoked to report an error to the user. May indicate a location or range in
the input. Each piece of location data, if provided, is a 2-element list
containing line and column numbers.
- <a name='47'></a>__page_log_info__ *text*
Invoked to report some internal information.
- <a name='48'></a>__page_log_warning__ *text*
Invoked to report an internal warning.
- <a name='49'></a>__page_log_error__ *text*
Invoked to report an internal error.
It is expected that a reader plugin __FOO__ is implemented by the package
__page::reader::__FOO____.
Reader plugins are loaded by the command __::page::pluginmgr::reader__. At most
one reader plugin can be kept in memory.
# <a name='section5'></a>WRITER PLUGIN API
Writer plugins are expected to provide the following commands, described below.
- <a name='50'></a>__page_wfeature__
This command takes a feature *name* and returns a boolean flag indicating
whether the feature is supported by the plugin, or not. The result has to be
__true__ if the feature is supported, and __false__ otherwise.
See section [FEATURES](#section8) for the possible features the plugin
manager will ask for.
- <a name='51'></a>__page_wtime__
This command is invoked to activate the collection of timing statistics.
- <a name='52'></a>__page_wgettime__
This command is invoked to retrieve the collected timing statistics.
- <a name='53'></a>__page_wlabel__
This command is invoked to retrieve a human-readable label for the plugin.
- <a name='54'></a>__page_whelp__
This command is invoked to retrieve a help text for plugin. The text is
expected to be in *[doctools](../../../../index.md#doctools)* format.
- <a name='55'></a>__page_woptions__
This command is invoked to retrieve the options understood by the plugin.
- <a name='56'></a>__page_wconfigure__ *option* *value*
This command is invoked to reconfigure the plugin, specifically the given
*option* is set to the new *value*.
- <a name='57'></a>__page_wrun__ *chan* *data*
This command is invoked to process the specified *data* and write it to the
output stream *chan*. The latter is a Tcl channel handle opened for writing.
The result of the command is the empty string.
Writer plugins expect the environment to provide the following special commands.
- <a name='58'></a>__page_info__ *text* ?*from* ?*to*??
Invoked to report some information to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a 2-element
list containing line and column numbers.
- <a name='59'></a>__page_warning__ *text* ?*from* ?*to*??
Invoked to report a warning to the user. May indicate a location or range in
the input. Each piece of location data, if provided, is a 2-element list
containing line and column numbers.
- <a name='60'></a>__page_error__ *text* ?*from* ?*to*??
Invoked to report an error to the user. May indicate a location or range in
the input. Each piece of location data, if provided, is a 2-element list
containing line and column numbers.
- <a name='61'></a>__page_log_info__ *text*
Invoked to report some internal information.
- <a name='62'></a>__page_log_warning__ *text*
Invoked to report an internal warning.
- <a name='63'></a>__page_log_error__ *text*
Invoked to report an internal error.
It is expected that a writer plugin __FOO__ is implemented by the package
__page::writer::__FOO____.
Writer plugins are loaded by the command __::page::pluginmgr::writer__. At most
one writer plugin can be kept in memory.
# <a name='section6'></a>TRANSFORM PLUGIN API
page::transform::* Transformation plugins are expected to provide the following
commands, described below.
- <a name='64'></a>__page_tfeature__
This command takes a feature *name* and returns a boolean flag indicating
whether the feature is supported by the plugin, or not. The result has to be
__true__ if the feature is supported, and __false__ otherwise.
See section [FEATURES](#section8) for the possible features the plugin
manager will ask for.
- <a name='65'></a>__page_ttime__
This command is invoked to activate the collection of timing statistics.
- <a name='66'></a>__page_tgettime__
This command is invoked to retrieve the collected timing statistics.
- <a name='67'></a>__page_tlabel__
This command is invoked to retrieve a human-readable label for the plugin.
- <a name='68'></a>__page_thelp__
This command is invoked to retrieve a help text for plugin. The text is
expected to be in *[doctools](../../../../index.md#doctools)* format.
- <a name='69'></a>__page_toptions__
This command is invoked to retrieve the options understood by the plugin.
- <a name='70'></a>__page_tconfigure__ *option* *value*
This command is invoked to reconfigure the plugin, specifically the given
*option* is set to the new *value*.
- <a name='71'></a>__page_trun__ *chan* *data*
This command is invoked to process the specified *data* and write it to the
output stream *chan*. The latter is a Tcl channel handle opened for writing.
The result of the command is the empty string.
Transformation plugins expect the environment to provide the following special
commands.
- <a name='72'></a>__page_info__ *text* ?*from* ?*to*??
Invoked to report some information to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a 2-element
list containing line and column numbers.
- <a name='73'></a>__page_warning__ *text* ?*from* ?*to*??
Invoked to report a warning to the user. May indicate a location or range in
the input. Each piece of location data, if provided, is a 2-element list
containing line and column numbers.
- <a name='74'></a>__page_error__ *text* ?*from* ?*to*??
Invoked to report an error to the user. May indicate a location or range in
the input. Each piece of location data, if provided, is a 2-element list
containing line and column numbers.
- <a name='75'></a>__page_log_info__ *text*
Invoked to report some internal information.
- <a name='76'></a>__page_log_warning__ *text*
Invoked to report an internal warning.
- <a name='77'></a>__page_log_error__ *text*
Invoked to report an internal error.
It is expected that a transformation plugin __FOO__ is implemented by the
package __page::transform::__FOO____.
Transformation plugins are loaded by the command
__::page::pluginmgr::transform__. More than one transformation plugin can be
kept in memory.
# <a name='section7'></a>PREDEFINED PLUGINS
The following predefined plugins are known, i.e. provided by the page module.
- Configuration
* peg
Returns a set of options to configure the __[page](../../apps/page.md)__
application for the processing of a PEG grammar and the generation of ME
code. See the packages __grammar_peg__, __grammar_me__ and relations for
more details.
- Reader
* hb
Expects a so-called *half-baked PEG container* as input and returns the
equivalent abstract syntax tree. See the writer plugin *hb* for the
plugin generating this type of input.
* lemon
Expects a grammar specification as understood by Richar Hipp's LEMON
parser generator and returns an abstract syntax tree for it.
* peg
Expects a grammar specification in the form of a parsing expression
grammar (PEG) and returns an abstract syntax tree for it.
* ser
Expect the serialized form of a parsing expression grammar as generated
by the package __[grammar::peg](../grammar_peg/peg.md)__ as input,
converts it into an equivalent abstract syntax tree and returns that.
* treeser
Expects the serialized form of a tree as generated by the package
__[struct::tree](../struct/struct_tree.md)__ as input and returns it,
after validation.
- Writer
* hb
Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out in the form of a so-called *half-baked PEG
container*.
* identity
Takes any input and writes it as is.
* mecpu
Expects symbolic assembler code for the MatchEngine CPU (See the package
__[grammar::me::cpu](../grammar_me/me_cpu.md)__ and relatives) and
writes it out as Tcl code for a parser.
* me
Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out as Tcl code for the MatchEngine (See the package
__grammar::me__ and relatives) which parses input in that grammar.
* null
Takes any input and writes nothing. The logical equivalent of /dev/null.
* peg
Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out in the form of a canonical PEG which can be read
by the reader plugin *peg*.
* ser
Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out as a serialized PEG container which can be read
by the reader plugin *ser*.
* tpc
Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out as Tcl code initializing a PEG container as
provided by the package __[grammar::peg](../grammar_peg/peg.md)__.
* tree
Takes any serialized tree (per package
__[struct::tree](../struct/struct_tree.md)__) as input and writes it out
in a generic indented format.
- Transformation
* mecpu
Takes an abstract syntax tree for a parsing expression grammer as input,
generates symbolic assembler code for the MatchEngine CPU, and returns
that as its result (See the package
__[grammar::me::cpu](../grammar_me/me_cpu.md)__ and relatives).
* reachable
Takes an abstract syntax tree for a parsing expression grammer as input,
performs a reachability analysis, and returns the modified and annotated
tree.
* realizable
Takes an abstract syntax tree for a parsing expression grammer as input,
performs an analysis of realizability, and returns the modified and
annotated tree.
# <a name='section8'></a>FEATURES
The plugin manager currently checks the plugins for only one feature,
__timeable__. A plugin supporting this feature is assumed to be able to collect
timing statistics on request.
# <a name='section9'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[page](../../../../index.md#page), [parser
generator](../../../../index.md#parser_generator), [text
processing](../../../../index.md#text_processing)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_util_flow.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
[//000000001]: # (page_util_flow - Parser generator tools)
[//000000002]: # (Generated from file 'page_util_flow.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_util_flow(n) 1.0 tcllib "Parser generator tools")
# NAME
page_util_flow - page dataflow/treewalker utility
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [FLOW API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require page::util::flow ?0.1?
package require snit
[__::page::util::flow__ *start* *flowvar* *nodevar* *script*](#1)
[*flow* __visit__ *node*](#2)
[*flow* __visitl__ *nodelist*](#3)
[*flow* __visita__ *node*...](#4)
# <a name='description'></a>DESCRIPTION
This package provides a single utility command for easy dataflow based
manipulation of arbitrary data structures, especially abstract syntax trees.
# <a name='section2'></a>API
- <a name='1'></a>__::page::util::flow__ *start* *flowvar* *nodevar* *script*
This command contains the core logic to drive the walking of an arbitrary
data structure which can partitioned into separate parts. Examples of such
structures are trees and graphs.
The command makes no assumptions at all about the API of the structure to be
walked, except that that its parts, here called *nodes*, are identified by
strings. These strings are taken as is, from the arguments, and the body,
and handed back to the body, without modification.
Access to the actual data structure, and all decisions regarding which nodes
to visit in what order are delegated to the body of the loop, i.e. the
*script*.
The body is invoked first for the nodes in the start-set specified via
*start*), and from then on for the nodes the body has requested to be
visited. The command stops when the set of nodes to visit becomes empty.
Note that a node can be visited more than once. The body has complete
control about this.
The body is invoked in the context of the caller. The variable named by
*nodevar* will be set to the current node, and the variable named by
*flowvar* will be set to the command of the flow object through which the
body can request the nodes to visit next. The API provided by this object is
described in the next section, [FLOW API](#section3).
Note that the command makes no promises regarding the order in which nodes
are visited, excpt that the nodes requested to be visited by the current
iteration will be visited afterward, in some order.
# <a name='section3'></a>FLOW API
This section describes the API provided by the flow object made accessible to
the body script of __::page::util::flow__.
- <a name='2'></a>*flow* __visit__ *node*
Invoking this method requests that the node *n* is visited after the current
iteration.
- <a name='3'></a>*flow* __visitl__ *nodelist*
Invoking this method requests that all the nodes found in the list
*nodelist* are visited after the current iteration.
- <a name='4'></a>*flow* __visita__ *node*...
This is the variadic arguments form of the method __visitl__, see above.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[dataflow](../../../../index.md#dataflow), [graph
walking](../../../../index.md#graph_walking), [page](../../../../index.md#page),
[parser generator](../../../../index.md#parser_generator), [text
processing](../../../../index.md#text_processing), [tree
walking](../../../../index.md#tree_walking)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
[//000000001]: # (page_util_norm_lemon - Parser generator tools)
[//000000002]: # (Generated from file 'page_util_norm_lemon.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_util_norm_lemon(n) 1.0 tcllib "Parser generator tools")
# NAME
page_util_norm_lemon - page AST normalization, LEMON
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require page::util::norm_lemon ?0.1?
package require snit
[__::page::util::norm::lemon__ *tree*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single utility command which takes an AST for a lemon
grammar and normalizes it in various ways. The result is called a *Normalized
Lemon Grammar Tree*.
*Note* that this package can only be used from within a plugin managed by the
package __page::pluginmgr__.
# <a name='section2'></a>API
- <a name='1'></a>__::page::util::norm::lemon__ *tree*
This command assumes the *tree* object contains for a lemon grammar. It
normalizes this tree in place. The result is called a *Normalized Lemon
Grammar Tree*.
The exact operations performed are left undocumented for the moment.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[graph walking](../../../../index.md#graph_walking),
[lemon](../../../../index.md#lemon),
[normalization](../../../../index.md#normalization),
[page](../../../../index.md#page), [parser
generator](../../../../index.md#parser_generator), [text
processing](../../../../index.md#text_processing), [tree
walking](../../../../index.md#tree_walking)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_util_norm_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
[//000000001]: # (page_util_norm_peg - Parser generator tools)
[//000000002]: # (Generated from file 'page_util_norm_peg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_util_norm_peg(n) 1.0 tcllib "Parser generator tools")
# NAME
page_util_norm_peg - page AST normalization, PEG
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require page::util::norm_peg ?0.1?
package require snit
[__::page::util::norm::peg__ *tree*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a single utility command which takes an AST for a parsing
expression grammar and normalizes it in various ways. The result is called a
*Normalized PE Grammar Tree*.
*Note* that this package can only be used from within a plugin managed by the
package __page::pluginmgr__.
# <a name='section2'></a>API
- <a name='1'></a>__::page::util::norm::peg__ *tree*
This command assumes the *tree* object contains for a parsing expression
grammar. It normalizes this tree in place. The result is called a
*Normalized PE Grammar Tree*.
The following operations are performd
The data for all terminals is stored in their grandparental nodes. The
terminal nodes and their parents are removed. Type information is dropped.
All nodes which have exactly one child are irrelevant and are removed, with
the exception of the root node. The immediate child of the root is
irrelevant as well, and removed as well.
The name of the grammar is moved from the tree node it is stored in to an
attribute of the root node, and the tree node removed.
The node keeping the start expression separate is removed as irrelevant and
the root node of the start expression tagged with a marker attribute, and
its handle saved in an attribute of the root node for quick access.
Nonterminal hint information is moved from nodes into attributes, and the
now irrelevant nodes are deleted.
*Note:* This transformation is dependent on the removal of all nodes with
exactly one child, as it removes the all 'Attribute' nodes already.
Otherwise this transformation would have to put the information into the
grandparental node.
The default mode given to the nonterminals is __value__.
Like with the global metadata definition specific information is moved out
out of nodes into attributes, the now irrelevant nodes are deleted, and the
root nodes of all definitions are tagged with marker attributes. This
provides us with a mapping from nonterminal names to their defining nodes as
well, which is saved in an attribute of the root node for quick reference.
At last the range in the input covered by a definition is computed. The left
extent comes from the terminal for the nonterminal symbol it defines. The
right extent comes from the rightmost child under the definition. While this
not an expression tree yet the location data is sound already.
The remaining nodes under all definitions are transformed into proper
expression trees. First character ranges, followed by unary operations,
characters, and nonterminals. At last the tree is flattened by the removal
of superfluous inner nodes.
The order matters, to shed as much nodes as possible early, and to avoid
unnecessary work later.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[PEG](../../../../index.md#peg), [graph
walking](../../../../index.md#graph_walking),
[normalization](../../../../index.md#normalization),
[page](../../../../index.md#page), [parser
generator](../../../../index.md#parser_generator), [text
processing](../../../../index.md#text_processing), [tree
walking](../../../../index.md#tree_walking)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_util_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
[//000000001]: # (page_util_peg - Parser generator tools)
[//000000002]: # (Generated from file 'page_util_peg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_util_peg(n) 1.0 tcllib "Parser generator tools")
# NAME
page_util_peg - page PEG transformation utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require page::util::peg ?0.1?
package require snit
[__::page::util::peg::symbolNodeOf__ *tree* *node*](#1)
[__::page::util::peg::symbolOf__ *tree* *node*](#2)
[__::page::util::peg::updateUndefinedDueRemoval__ *tree*](#3)
[__::page::util::peg::flatten__ *treequery* *tree*](#4)
[__::page::util::peg::getWarnings__ *tree*](#5)
[__::page::util::peg::printWarnings__ *msg*](#6)
[__::page::util::peg::peOf__ *tree* *eroot*](#7)
[__::page::util::peg::printTclExpr__ *pe*](#8)
# <a name='description'></a>DESCRIPTION
This package provides a few common operations to PEG transformations. They
assume a *Normalized PE Grammar Tree* as input, see the package
__page::util::norm::peg__, possibly augmented with attributes coming from
transformations not in conflict with the base definition.
# <a name='section2'></a>API
- <a name='1'></a>__::page::util::peg::symbolNodeOf__ *tree* *node*
Given an arbitrary expression *node* in the AST *tree* it determines the
node (itself or an ancestor) containing the name of the nonterminal symbol
the node belongs to, and returns its id. The result is either the root of
the tree (for the start expression), or a definition node.
- <a name='2'></a>__::page::util::peg::symbolOf__ *tree* *node*
As __::page::util::peg::symbolNodeOf__, but returns the symbol name instead
of the node.
- <a name='3'></a>__::page::util::peg::updateUndefinedDueRemoval__ *tree*
The removal of nodes in the AST *tree* can cause symbols to lose one or more
users.
A used by B and C,
B is reachable,
C is not,
so A now loses the node in the expression for C calling it,
or rather, not calling it anymore.
This command updates the cross-references and which nonterminals are now
undefined.
- <a name='4'></a>__::page::util::peg::flatten__ *treequery* *tree*
This commands flattens nested sequence and choice operators in the AST
*tree*, re-using the __[treeql](../treeql/treeql.md)__ object *treequery* to
run the query determining which nodes to cut.
- <a name='5'></a>__::page::util::peg::getWarnings__ *tree*
This command looks at the attributes of the AST *tree* for problems with the
grammar and issues warnings. They do not prevent us from writing the
grammar, but still represent problems with it the user should be made aware
of.
The result of the command is a dictionary mapping nonterminal names to their
associated warnings.
- <a name='6'></a>__::page::util::peg::printWarnings__ *msg*
The argument of the command is a dictionary mapping nonterminal names to
their associated warnings, as generated by, for example, the command
__::page::util::peg::getWarnings__.
The warnings contained therein are formatted and then printed via the log
command __page_info__. This means that this command can be used only from
within a plugin managed by the package __page::pluginmgr__.
- <a name='7'></a>__::page::util::peg::peOf__ *tree* *eroot*
This command converts the parsing expression starting at the node *eroot* in
the AST *tree* into a nested list. The exact syntax of this list specified
by the package __[grammar::peg](../grammar_peg/peg.md)__.
- <a name='8'></a>__::page::util::peg::printTclExpr__ *pe*
This command converts the parsing expression contained in the nested list
*pe* into a Tcl string which can be placed into a Tcl script. See the
package __[grammar::peg](../grammar_peg/peg.md)__ for the exact syntax of
*pe*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[PEG](../../../../index.md#peg), [page](../../../../index.md#page), [parser
generator](../../../../index.md#parser_generator), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [text
processing](../../../../index.md#text_processing),
[transformation](../../../../index.md#transformation)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/page/page_util_quote.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
[//000000001]: # (page_util_quote - Parser generator tools)
[//000000002]: # (Generated from file 'page_util_quote.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (page_util_quote(n) 1.0 tcllib "Parser generator tools")
# NAME
page_util_quote - page character quoting utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require page::util::quote ?0.1?
package require snit
[__::page::util::quote::unquote__ *char*](#1)
[__::page::util::quote::quote'tcl__ *char*](#2)
[__::page::util::quote::quote'tclstr__ *char*](#3)
[__::page::util::quote::quote'tclcom__ *char*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a few utility commands to convert characters into various
forms.
# <a name='section2'></a>API
- <a name='1'></a>__::page::util::quote::unquote__ *char*
A character, as stored in an abstract syntax tree by a PEG processor (See
the packages __grammar::peg::interpreter__, __grammar::me__, and their
relations), i.e. in some quoted form, is converted into the equivalent Tcl
character. The character is returned as the result of the command.
- <a name='2'></a>__::page::util::quote::quote'tcl__ *char*
This command takes a Tcl character (internal representation) and converts it
into a string which is accepted by the Tcl parser, will regenerate the
character in question and is 7bit ASCII. The string is returned as the
result of this command.
- <a name='3'></a>__::page::util::quote::quote'tclstr__ *char*
This command takes a Tcl character (internal representation) and converts it
into a string which is accepted by the Tcl parser and will generate a human
readable representation of the character in question. The string is returned
as the result of this command.
The string does not use any unprintable characters. It may use
backslash-quoting. High UTF characters are quoted to avoid problems with the
still prevalent ascii terminals. It is assumed that the string will be used
in a double-quoted environment.
- <a name='4'></a>__::page::util::quote::quote'tclcom__ *char*
This command takes a Tcl character (internal representation) and converts it
into a string which is accepted by the Tcl parser when used within a Tcl
comment. The string is returned as the result of this command.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *page* 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.
# <a name='keywords'></a>KEYWORDS
[page](../../../../index.md#page), [parser
generator](../../../../index.md#parser_generator),
[quoting](../../../../index.md#quoting), [text
processing](../../../../index.md#text_processing)
# <a name='category'></a>CATEGORY
Page Parser Generator
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pki/pki.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
[//000000001]: # (pki - public key encryption)
[//000000002]: # (Generated from file 'pki.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pki(n) 0.10 tcllib "public key encryption")
# NAME
pki - Implementation of the public key cipher
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pki ?0.10?
[__::pki::encrypt__ ?*-binary*? ?*-hex*? ?*-pad*? ?*-nopad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key*](#1)
[__::pki::decrypt__ ?*-binary*? ?*-hex*? ?*-unpad*? ?*-nounpad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key*](#2)
[__::pki::sign__ *input* *key* ?*algo*?](#3)
[__::pki::verify__ *signedmessage* *plaintext* *key* ?*algo*?](#4)
[__::pki::key__ *key* ?*password*? ?*encodePem*?](#5)
[__::pki::pkcs::parse_key__ *key* ?*password*?](#6)
[__::pki::x509::parse_cert__ *cert*](#7)
[__::pki::rsa::generate__ *bitlength* ?*exponent*?](#8)
[__::pki::x509::verify_cert__ *cert* *trustedcerts* ?*intermediatecerts*?](#9)
[__::pki::x509::validate_cert__ *cert* ?__-sign_message__ *dn_of_signer*? ?__-encrypt_message__ *dn_of_signer*? ?__-sign_cert__ *dn_to_be_signed* *ca_depth*? ?__-ssl__ *dn*?](#10)
[__::pki::pkcs::create_csr__ *keylist* *namelist* ?*encodePem*? ?*algo*?](#11)
[__::pki::pkcs::parse_csr__ *csr*](#12)
[__::pki::x509::create_cert__ *signreqlist* *cakeylist* *serial_number* *notBefore* *notAfter* *isCA* *extensions* ?*encodePem*? ?*algo*?](#13)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::pki::encrypt__ ?*-binary*? ?*-hex*? ?*-pad*? ?*-nopad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key*
Encrypt a message using PKI (probably RSA). Requires the caller to specify
either __-priv__ to encrypt with the private key or __-pub__ to encrypt with
the public key. The default option is to pad and return in hex. One of
__-pub__ or __-priv__ must be specified. The __-hex__ option causes the data
to be returned in encoded as a hexidecimal string, while the __-binary__
option causes the data to be returned as a binary string. If they are
specified multiple times, the last one specified is used. The __-pad__
option causes the data to be padded per PKCS#1 prior to being encrypted. The
__-nopad__ inhibits this behaviour. If they are specified multiple times,
the last one specified is used. The input to encrypt is specified as
*input*. The *key* parameter, holding the key to use, is a return value from
either __::pki::pkcs::parse_key__, __::pki::x509::parse_cert__, or
__::pki::rsa::generate__.
Mapping to OpenSSL's __openssl__ application:
"openssl rsautl -encrypt" == "::pki::encrypt -binary -pub"
"openssl rsautl -sign" == "::pki::encrypt -binary -priv"
- <a name='2'></a>__::pki::decrypt__ ?*-binary*? ?*-hex*? ?*-unpad*? ?*-nounpad*? ?*-priv*? ?*-pub*? ?*--*? *input* *key*
Decrypt a message using PKI (probably RSA). See __::pki::encrypt__ for
option handling.
Mapping to OpenSSL's __openssl__ application:
"openssl rsautl -decrypt" == "::pki::decrypt -binary -priv"
"openssl rsautl -verify" == "::pki::decrypt -binary -pub"
- <a name='3'></a>__::pki::sign__ *input* *key* ?*algo*?
Digitally sign message *input* using the private *key*. If *algo* is ommited
"sha1" is assumed. Possible values for *algo* include "md5", "sha1",
"sha256", and "raw". Specifyin "raw" for *algo* will inhibit the building of
an ASN.1 structure to encode which hashing algorithm was chosen. The *input*
should be the plain text, hashing will be performed on it. The *key* should
include the private key.
- <a name='4'></a>__::pki::verify__ *signedmessage* *plaintext* *key* ?*algo*?
Verify a digital signature using a public *key*. Returns true or false.
- <a name='5'></a>__::pki::key__ *key* ?*password*? ?*encodePem*?
Convert a key structure into a serialized PEM (default) or DER encoded
private key suitable for other applications. For RSA keys this means PKCS#1.
- <a name='6'></a>__::pki::pkcs::parse_key__ *key* ?*password*?
Convert a PKCS#1 private *key* into a usable key, i.e. one which can be used
as argument for __::pki::encrypt__, __::pki::decrypt__, __::pki::sign__, and
__::pki::verify__.
- <a name='7'></a>__::pki::x509::parse_cert__ *cert*
Convert an X.509 certificate to a usable (public) key, i.e. one which can be
used as argument for __::pki:encrypt__, __::pki::decrypt__, and
__::pki::verify__. The *cert* argument can be either PEM or DER encoded.
- <a name='8'></a>__::pki::rsa::generate__ *bitlength* ?*exponent*?
Generate a new RSA key pair, the parts of which can be used as argument for
__::pki::encrypt__, __::pki::decrypt__, __::pki::sign__, and
__::pki::verify__. The *bitlength* argument is the length of the public key
modulus. The *exponent* argument should generally not be specified unless
you really know what you are doing.
- <a name='9'></a>__::pki::x509::verify_cert__ *cert* *trustedcerts* ?*intermediatecerts*?
Verify that a trust can be found between the certificate specified in the
*cert* argument and one of the certificates specified in the list of
certificates in the *trustedcerts* argument. (Eventually the chain can be
through untrusted certificates listed in the *intermediatecerts* argument,
but this is currently unimplemented). The certificates specified in the
*cert* and *trustedcerts* option should be parsed (from
__::pki::x509::parse_cert__).
- <a name='10'></a>__::pki::x509::validate_cert__ *cert* ?__-sign_message__ *dn_of_signer*? ?__-encrypt_message__ *dn_of_signer*? ?__-sign_cert__ *dn_to_be_signed* *ca_depth*? ?__-ssl__ *dn*?
Validate that a certificate is valid to be used in some capacity. If
multiple options are specified they must all be met for this procedure to
return "true". Currently, only the __-sign_cert__ option is functional.
Arguments for the __-sign_cert__ option are *dn_to_be_signed* and
*ca_depth*. The *dn_to_be_signed* is the distinguished from the subject of a
certificate to verify that the certificate specified in the *cert* argument
can sign. The *ca_depth* argument is used to indicate at which depth the
verification should be done at. Some certificates are limited to how far
down the chain they can be used to verify a given certificate.
- <a name='11'></a>__::pki::pkcs::create_csr__ *keylist* *namelist* ?*encodePem*? ?*algo*?
Generate a certificate signing request from a key pair specified in the
*keylist* argument. The *namelist* argument is a list of "name" followed by
"value" pairs to encoding as the requested distinguished name in the CSR.
The *encodePem* option specifies whether or not the result should be PEM
encoded or DER encoded. A "true" value results in the result being PEM
encoded, while any other value 9results in the the result being DER encoded.
DER encoding is the default. The *algo* argument specifies the hashing
algorithm we should use to sign this certificate signing request with. The
default is "sha1". Other possible values include "md5" and "sha256".
- <a name='12'></a>__::pki::pkcs::parse_csr__ *csr*
Parse a Certificate Signing Request. The *csr* argument can be either PEM or
DER encoded.
- <a name='13'></a>__::pki::x509::create_cert__ *signreqlist* *cakeylist* *serial_number* *notBefore* *notAfter* *isCA* *extensions* ?*encodePem*? ?*algo*?
Sign a signing request (usually from __::pki::pkcs::create_csr__ or
__::pki::pkcs::parse_csr__) with a Certificate Authority (CA) certificate.
The *signreqlist* argument should be the parsed signing request. The
*cakeylist* argument should be the parsed CA certificate. The
*serial_number* argument should be a serial number unique to this
certificate from this certificate authority. The *notBefore* and *notAfter*
arguments should contain the time before and after which (respectively) the
certificate should be considered invalid. The time should be encoded as
something __clock format__ will accept (i.e., the results of __clock
seconds__ and __clock add__). The *isCA* argument is a boolean argumen
describing whether or not the signed certificate should be a a CA
certificate. If specified as true the "id-ce-basicConstraints" extension is
added with the arguments of "critical" being true, "allowCA" being true, and
caDepth being -1 (infinite). The *extensions* argument is a list of
extensions and their parameters that should be encoded into the created
certificate. Currently only one extension is understood
("id-ce-basicConstraints"). It accepts three arguments *critical* *allowCA*
*caDepth*. The *critical* argument to this extension (and any extension)
whether or not the validator should reject the certificate as invalid if it
does not understand the extension (if set to "true") or should ignore the
extension (if set to "false"). The *allowCA* argument is used to specify as
a boolean value whether or not we can be used a certificate authority (CA).
The *caDepth* argument indicates how many children CAs can be children of
this CA in a depth-wise fashion. A value of "0" for the *caDepth* argument
means that this CA cannot sign a CA certificate and have the result be
valid. A value of "-1" indicates infinite depth.
# <a name='section3'></a>EXAMPLES
# <a name='section4'></a>REFERENCES
# <a name='section5'></a>AUTHORS
Roy Keene
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *rsa* 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.
# <a name='see-also'></a>SEE ALSO
[aes(n)](../aes/aes.md), [blowfish(n)](../blowfish/blowfish.md),
[des(n)](../des/des.md), [md5(n)](../md5/md5.md), [sha1(n)](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[cipher](../../../../index.md#cipher), [data
integrity](../../../../index.md#data_integrity),
[encryption](../../../../index.md#encryption), [public key
cipher](../../../../index.md#public_key_cipher),
[rsa](../../../../index.md#rsa), [security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries
|
Added embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
|
[//000000001]: # (pluginmgr - Plugin management)
[//000000002]: # (Generated from file 'pluginmgr.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pluginmgr(n) 0.3 tcllib "Plugin management")
# NAME
pluginmgr - Manage a plugin
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PUBLIC API](#section2)
- [PACKAGE COMMANDS](#subsection1)
- [OBJECT COMMAND](#subsection2)
- [OBJECT METHODS](#subsection3)
- [OBJECT CONFIGURATION](#subsection4)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require pluginmgr ?0.3?
[__::pluginmgr__ *objectName* ?*option value*...?](#1)
[__::pluginmgr::paths__ *objectName* *name*...](#2)
[__objectName__ __method__ ?*arg arg ...*?](#3)
[*objectName* __clone__](#4)
[*objectName* __configure__](#5)
[*objectName* __configure__ *option*](#6)
[*objectName* __configure__ __-option__ *value*...](#7)
[*objectName* __cget__ __-option__](#8)
[*objectName* __destroy__](#9)
[*objectName* __do__ *arg*...](#10)
[*objectName* __interpreter__](#11)
[*objectName* __plugin__](#12)
[*objectName* __load__ *string*](#13)
[*objectName* __unload__](#14)
[*objectName* __list__](#15)
[*objectName* __path__ *path*](#16)
[*objectName* __paths__](#17)
# <a name='description'></a>DESCRIPTION
This package provides commands and objects for the generic management of plugins
which can be loaded into an application.
To avoid the implementation of yet another system to locate Tcl code the system
provides by this package is built on top of the regular package management
system. Each plugin is considered as a package and a simple invokation of
__package require__ is enough to locate and load it, if it exists. The only time
we will need additional paths is when a plugin manager is part of a wrapped
application and has to be able to search for plugins existing outside of that
application. For this situation the package provides a command to create a
general set of such paths based on names for the plugin manager and/or
application in question.
The main contribution of this package is a generic framework which allows the
easy declaration of
1. How to translate a plugin name to the name of the package implementing it,
and vice versa.
1. The list of commands a plugin has to provide as API, and also of more
complex checks as code.
1. The list of commands expected by the plugin from the environment.
This then allows the easy generation of plugin managers customized to particular
types of plugins for an application.
It should be noted that all plugin code is considered untrusted and will always
be executed within a safe interpreter. The interpreter is enabled enough to
allow plugins the loading of all additional packages they may need.
# <a name='section2'></a>PUBLIC API
## <a name='subsection1'></a>PACKAGE COMMANDS
- <a name='1'></a>__::pluginmgr__ *objectName* ?*option value*...?
This command creates a new plugin manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [OBJECT COMMAND](#subsection2) and [OBJECT
METHODS](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
The options and their values coming after the name of the object are used to
set the initial configuration of the mamager object, specifying the
applicable plugins and their API.
- <a name='2'></a>__::pluginmgr::paths__ *objectName* *name*...
This utility command adds a set of paths to the specified object, based on
the given *name*s. It will search for:
The environment variable __*name*_PLUGINS__. Its contents will be
interpreted as a list of package paths. The entries have to be separated by
either __:__ (unix) or __;__ (windows).
The name will be converted to upper-case letters.
The registry entry "HKEY_LOCAL_MACHINE\SOFTWARE\*name*\PLUGINS". Its
contents will be interpreted as a list of package paths. The entries have to
be separated by __;__. This item is considered only when on Windows (tm).
The casing of letters is not changed.
The registry entry "HKEY_CURRENT_USER\SOFTWARE\*name*\PLUGINS". Its contents
will be interpreted as a list of package paths. The entries have to be
separated by __;__. This item is considered only when on Windows (tm).
The casing of letters is not changed.
The directory "~/.*name*/plugin".
The directory "~/.*name*/plugins".
The casing of letters is not changed.
and add all the paths found that way to the list of package paths maintained
by the object.
If *name* is namespaced each item in the list will be repeated per prefix of
*name*, with conversion of :-sequences into the proper separator (underscore
for environment variables, backslash for registry entries, and / for
directories).
Examples:
::pluginmgr::paths ::obj docidx
=> env DOCIDX_PLUGINS
reg HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS
reg HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS
path ~/.docidx/plugins
::pluginmgr::paths ::obj doctools::idx
=> env DOCTOOLS_PLUGINS
env DOCTOOLS_IDX_PLUGINS
reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS
reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS
reg HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS
reg HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS
path ~/.doctools/plugin
path ~/.doctools/idx/plugin
## <a name='subsection2'></a>OBJECT COMMAND
All commands created by the command __::pluginmgr__ (See section [PACKAGE
COMMANDS](#subsection1)) have the following general form and may be used to
invoke various operations on their plugin manager object.
- <a name='3'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [OBJECT METHODS](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>OBJECT METHODS
- <a name='4'></a>*objectName* __clone__
This method creates a new plugin management object and returns the
associated object command. The generated object is a clone of the object the
method was invoked on. I.e. the new object will have the same configuration
as the current object. With regard to state, if the current object has a
plugin loaded then this plugin and all associated state is moved to the
generated clone and the current object is reset into the base state (no
plugin loaded). In this manner a configured plugin manager is also a factory
for loaded plugins.
- <a name='5'></a>*objectName* __configure__
The method returns a list of all known options and their current values when
called without any arguments.
- <a name='6'></a>*objectName* __configure__ *option*
The method behaves like the method __cget__ when called with a single
argument and returns the value of the option specified by said argument.
- <a name='7'></a>*objectName* __configure__ __-option__ *value*...
The method reconfigures the specified __option__s of the object, setting
them to the associated *value*s, when called with an even number of
arguments, at least two.
The legal options are described in the section [OBJECT
CONFIGURATION](#subsection4).
- <a name='8'></a>*objectName* __cget__ __-option__
This method expects a legal configuration option as argument and will return
the current value of that option for the object the method was invoked for.
The legal configuration options are described in section [OBJECT
CONFIGURATION](#subsection4).
- <a name='9'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='10'></a>*objectName* __do__ *arg*...
This method interprets its list of arguments as the words of a command and
invokes this command in the execution context of the plugin. The result of
the invoked command is made the result of the method. The call will fail
with an error if no valid plugin has been loaded into the manager object.
- <a name='11'></a>*objectName* __interpreter__
This method returns the handle of the safe interpreter the current plugin is
loaded into. An empty string as return value signals that the manager
currently has no valid plugin loaded.
- <a name='12'></a>*objectName* __plugin__
This method returns the name of the plugin currently loaded. An empty string
as return value signals that the manager currently has no valid plugin
loaded.
- <a name='13'></a>*objectName* __load__ *string*
This method loads, validates, and initializes a named plugin into the
manager object.
The algorithm to locate and load the plugin employed is:
If the *string* contains the path to an existing file then this file is
taken as the implementation of the plugin.
Otherwise the plugin name is translated into a package name via the value of
the option __-pattern__ and then loaded through the regular package
management.
The load fails.
The algorithm to validate and initialize the loaded code is:
If the option __-api__ is non-empty introspection commands are used to
ascertain that the plugin provides the listed commands.
If the option __-check__ is non-empty the specified command prefix is
called.
If either of the above fails the candidate plugin is unloaded again
Otherwise all the commands specified via the option __-cmds__ are installed
in the plugin.
A previously loaded plugin is discarded, but only if the new plugin was
found and sucessfully validated and initialized. Note that there will be no
intereference between old and new plugin as both will be put into separate
safe interpreters.
- <a name='14'></a>*objectName* __unload__
This method unloads the currently loaded plugin. It returns the empty
string. The call will be silently ignored if no plugin is loaded at all.
- <a name='15'></a>*objectName* __list__
This method uses the contents of the option __-pattern__ to find all
packages which can be plugins under the purview of this manager object. It
translates their names into plugin names and returns a list containing them.
- <a name='16'></a>*objectName* __path__ *path*
This methods adds the specified *path* to the list of additional package
paths to look at when searching for a plugin. It returns the empty string.
Duplicate paths are ignored, i.e. each path is added only once. Paths are
made absolute, but are not normalized.
- <a name='17'></a>*objectName* __paths__
This method returns a list containing all additional paths which have been
added to the plugin manager object since its creation.
## <a name='subsection4'></a>OBJECT CONFIGURATION
All plugin manager objects understand the following configuration options:
- __-pattern__ *string*
The value of this option is a glob pattern which has to contain exactly one
'*'-operator. All packages whose names match this pattern are the plugins
recognized by the manager object. And vice versa, the replacement of the
'*'-operator with a plugin name will yield the name of the package
implementing that plugin.
This option has no default, except if option __-name__ was set. It has to be
set before attempting to load a plugin, either directly, or through option
__-name__.
- __-api__ *list*
The value of this option is a list of command names, and any plugin loaded
has to provide these commands. Names which are not fully qualified are
considered to be rooted in the global namespace. If empty no expectations
are made on the plugin. The default value is the empty list.
- __-check__ *cmdprefix*
The value of this option is interpreted as a command prefix. Its purpose is
to perform complex checks on a loaded plugin package to validate it, which
go beyond a simple list of provided commands.
It is called with the manager object command as the only argument and has to
return a boolean value. A value of __true__ will be interpreted to mean that
the candidate plugin passed the test. The call will happen if and only if
the candidate plugin already passed the basic API check specified through
the option __-api__.
The default value is the empty list, which causes the manager object to
suppress the call and to assume the candidate plugin passes.
- __-cmds__ *dict*
The value of this option is a dictionary. It specifies the commands which
will be made available to the plugin (as keys), and the trusted commands in
the environment which implement them (as values). The trusted commands will
be executed in the interpreter specified by the option __-cmdip__. The
default value is the empty dictionary.
- __-cmdip__ *ipspec*
The value of this option is the path of the interpreter where the trusted
commands given to the plugin will be executed in. The default is the empty
string, referring to the current interpreter.
- __-setup__ *cmdprefix*
The value of this option is interpreted as a command prefix.
It is called whenever a new safe interpreter for a plugin has been created,
but before a plugin is loaded. It is provided with the manager object
command and the interpreter handle as its only arguments. Any return value
will be ignored.
Its purpose is give a user of the plugin management the ability to define
commands, packages, etc. a chosen plugin may need while being loaded.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pluginmgr* 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.
# <a name='keywords'></a>KEYWORDS
[plugin management](../../../../index.md#plugin_management), [plugin
search](../../../../index.md#plugin_search)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/png/png.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
[//000000001]: # (png - Image manipulation)
[//000000002]: # (Generated from file 'png.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (png(n) 0.3 tcllib "Image manipulation")
# NAME
png - PNG querying and manipulation of meta data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require crc32
package require png ?0.3?
[__::png::validate__ *file*](#1)
[__::png::isPNG__ *file*](#2)
[__::png::imageInfo__ *file*](#3)
[__::png::getTimestamp__ *file*](#4)
[__::png::setTimestamp__ *file* *time*](#5)
[__::png::getComments__ *file*](#6)
[__::png::removeComments__ *file*](#7)
[__::png::addComment__ *file* *keyword* *text*](#8)
[__::png::addComment__ *file* *keyword* *lang* *keyword2* *text*](#9)
[__::png::getPixelDimension__ *file*](#10)
[__::png::image__ *file*](#11)
[__::png::write__ *file* *data*](#12)
# <a name='description'></a>DESCRIPTION
This package provides commands to query and modify PNG images. PNG stands for
*Portable Network Graphics* and is specified at
[http://www.libpng.org/pub/png/spec/1.2](http://www.libpng.org/pub/png/spec/1.2).
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::png::validate__ *file*
Returns a value indicating if *file* is a valid PNG file. The file is
checked for PNG signature, each chunks checksum is verified, existence of a
data chunk is verified, first chunk is checked for header, last chunk is
checked for ending. Things *not* checked for are: validity of values within
a chunk, multiple header chunks, noncontiguous data chunks, end chunk before
actual eof. This procedure can take lots of time.
Possible return values:
* OK
File is a valid PNG file.
* SIG
no/broken PNG signature.
* BADLEN
corrupt chunk length.
* EOF
premature end of file.
* NOHDR
missing header chunk.
* CKSUM
crc mismatch.
* NODATA
missing data chunk(s).
* NOEND
missing end marker.
- <a name='2'></a>__::png::isPNG__ *file*
Returns a boolean value indicating if the file *file* starts with a PNG
signature. This is a much faster and less intensive check than
__::png::validate__ as it does not check if the PNG data is valid.
- <a name='3'></a>__::png::imageInfo__ *file*
Returns a dictionary with keys __width__, __height__, __depth__, __color__,
__compression__, __filter__, and __interlace__. The values are the
associated properties of the PNG image in *file*. Throws an error if file is
not a PNG image, or if the checksum of the header is invalid. For
information on interpreting the values for the returned properties see
[http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html](http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html).
- <a name='4'></a>__::png::getTimestamp__ *file*
Returns the epoch time if a timestamp chunk is found in the PNG image
contained in the *file*, otherwise returns the empty string. Does not
attempt to verify the checksum of the timestamp chunk. Throws an error if
the *file* is not a valid PNG image.
- <a name='5'></a>__::png::setTimestamp__ *file* *time*
Writes a new timestamp to the *file*, either replacing the old timestamp, or
adding one just before the data chunks if there was no previous timestamp.
*time* is the new time in the gmt epoch format. Throws an error if *file* is
not a valid PNG image.
- <a name='6'></a>__::png::getComments__ *file*
Currently supports only uncompressed comments. Does not attempt to verify
the checksums of the comment chunks. Returns a list where each element is a
comment. Each comment is itself a list. The list for a plain text comment
consists of 2 elements: the human readable keyword, and the text data. A
unicode (international) comment consists of 4 elements: the human readable
keyword, the language identifier, the translated keyword, and the unicode
text data. Throws an error if *file* is not a valid PNG image.
- <a name='7'></a>__::png::removeComments__ *file*
Removes all comments from the PNG image in *file*. Beware - This uses memory
equal to the file size minus comments, to hold the intermediate result.
Throws an error if *file* is not a valid PNG image.
- <a name='8'></a>__::png::addComment__ *file* *keyword* *text*
Adds a plain *text* comment to the PNG image in *file*, just before the
first data chunk. Will throw an error if no data chunk is found. *keyword*
has to be less than 80 characters long to conform to the PNG specification.
- <a name='9'></a>__::png::addComment__ *file* *keyword* *lang* *keyword2* *text*
Adds a unicode (international) comment to the PNG image in *file*, just
before the first data chunk. Will throw an error if no data chunk is found.
*keyword* has to be less than 80 characters long to conform to the PNG
specification. *keyword2* is the translated *keyword*, in the language
specified by the language identifier *lang*.
- <a name='10'></a>__::png::getPixelDimension__ *file*
Returns a dictionary with keys __ppux__, __ppuy__ and __unit__ if the
information is present. Otherwise, it returns the empty string.
The values of __ppux__ and __ppuy__ return the pixel per unit value in X or
Y direction.
The allowed values for key __unit__ are __meter__ and __unknown__. In the
case of meter, the dpi value can be calculated by multiplying with the
conversion factor __0.0254__.
- <a name='11'></a>__::png::image__ *file*
Given a PNG file returns the image in the list of scanlines format used by
Tk_GetColor.
- <a name='12'></a>__::png::write__ *file* *data*
Takes a list of scanlines in the Tk_GetColor format and writes the
represented image to *file*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *png* 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.
# <a name='keywords'></a>KEYWORDS
[comment](../../../../index.md#comment), [image](../../../../index.md#image),
[png](../../../../index.md#png), [timestamp](../../../../index.md#timestamp)
# <a name='category'></a>CATEGORY
File formats
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004, Code: Aaron Faupell <[email protected]>
Copyright © 2004, Doc: Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pop3/pop3.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
[//000000001]: # (pop3 - Tcl POP3 Client Library)
[//000000002]: # (Generated from file 'pop3.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pop3(n) 1.9 tcllib "Tcl POP3 Client Library")
# NAME
pop3 - Tcl client for POP3 email protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TLS Security Considerations](#section2)
- [API](#section3)
- [Secure mail transfer](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require pop3 ?1.9?
[__::pop3::open__ ?__-msex__ 0|1? ?__-retr-mode__ retr|list|slow? ?__-socketcmd__ cmdprefix? ?__-stls__ 0|1? ?__-tls-callback__ stls-callback-command? *host username password* ?*port*?](#1)
[__::pop3::config__ *chan*](#2)
[__::pop3::status__ *chan*](#3)
[__::pop3::last__ *chan*](#4)
[__::pop3::retrieve__ *chan startIndex* ?*endIndex*?](#5)
[__::pop3::delete__ *chan startIndex* ?*endIndex*?](#6)
[__::pop3::list__ *chan* ?*msg*?](#7)
[__::pop3::top__ *chan* *msg* *n*](#8)
[__::pop3::uidl__ *chan* ?*msg*?](#9)
[__::pop3::capa__ *chan*](#10)
[__::pop3::close__ *chan*](#11)
# <a name='description'></a>DESCRIPTION
The __pop3__ package provides a simple Tcl-only client library for the POP3
email protocol as specified in [RFC
1939](http://www.rfc-editor.org/rfc/rfc1939.txt). It works by opening the
standard POP3 socket on the server, transmitting the username and password, then
providing a Tcl API to access the POP3 protocol commands. All server errors are
returned as Tcl errors (thrown) which must be caught with the Tcl __catch__
command.
# <a name='section2'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section3'></a>API
- <a name='1'></a>__::pop3::open__ ?__-msex__ 0|1? ?__-retr-mode__ retr|list|slow? ?__-socketcmd__ cmdprefix? ?__-stls__ 0|1? ?__-tls-callback__ stls-callback-command? *host username password* ?*port*?
Open a socket connection to the server specified by *host*, transmit the
*username* and *password* as login information to the server. The default
port number is __110__, which can be overridden using the optional *port*
argument. The return value is a channel used by all of the other ::pop3
functions.
The command recognizes three options
* __-msex__ boolean
Setting this option tells the package that the server we are talking to
is an MS Exchange server (which has some oddities we have to work
around). The default is __False__.
* __-retr-mode__ retr|list|slow
The retrieval mode determines how exactly messages are read from the
server. The allowed values are __retr__, __list__ and __slow__. The
default is __retr__. See __::pop3::retrieve__ for more information.
* __-socketcmd__ cmdprefix
This option allows the user to overide the use of the builtin
__[socket](../../../../index.md#socket)__ command with any
API-compatible command. The envisioned main use is the securing of the
new connection via SSL, through the specification of the command
__tls::socket__. This command is specially recognized as well, changing
the default port of the connection to __995__.
* __-stls__ boolean
Setting this option tells the package to secure the connection using SSL
or TLS. It performs STARTTLS as described in IETF RFC 2595, it first
opens a normal, unencrypted connection and then negotiates a SSLv3 or
TLSv1 connection. If the connection cannot be secured, the connection
will be closed and an error will be returned
* __-tls-callback__ stls-callback-command
This option allows the user to overide the __tls::callback__ used during
the __-stls__ SSL/TLS handshake. See the TLS manual for details on how
to implement this callback.
- <a name='2'></a>__::pop3::config__ *chan*
Returns the configuration of the pop3 connection identified by the channel
handle *chan* as a serialized array.
- <a name='3'></a>__::pop3::status__ *chan*
Query the server for the status of the mail spool. The status is returned as
a list containing two elements, the first is the number of email messages on
the server and the second is the size (in octets, 8 bit blocks) of the
entire mail spool.
- <a name='4'></a>__::pop3::last__ *chan*
Query the server for the last email message read from the spool. This value
includes all messages read from all clients connecting to the login account.
This command may not be supported by the email server, in which case the
server may return 0 or an error.
- <a name='5'></a>__::pop3::retrieve__ *chan startIndex* ?*endIndex*?
Retrieve a range of messages from the server. If the *endIndex* is not
specified, only one message will be retrieved. The return value is a list
containing each message as a separate element. See the *startIndex* and
*endIndex* descriptions below.
The retrieval mode determines how exactly messages are read from the server.
The mode __retr__ assumes that the RETR command delivers the size of the
message as part of the command status and uses this to read the message
efficiently. In mode __list__ RETR does not deliver the size, but the LIST
command does and we use this to retrieve the message size before the actual
retrieval, which can then be done efficiently. In the last mode, __slow__,
the system is unable to obtain the size of the message to retrieve in any
manner and falls back to reading the message from the server line by line.
It should also be noted that the system checks upon the configured mode and
falls back to the slower modes if the above assumptions are not true.
- <a name='6'></a>__::pop3::delete__ *chan startIndex* ?*endIndex*?
Delete a range of messages from the server. If the *endIndex* is not
specified, only one message will be deleted. Note, the indices are not
reordered on the server, so if you delete message 1, then the first message
in the queue is message 2 (message index 1 is no longer valid). See the
*startIndex* and *endIndex* descriptions below.
* *startIndex*
The *startIndex* may be an index of a specific message starting with the
index 1, or it have any of the following values:
+ __start__
This is a logical value for the first message in the spool,
equivalent to the value 1.
+ __next__
The message immediately following the last message read, see
__::pop3::last__.
+ __end__
The most recent message in the spool (the end of the spool). This is
useful to retrieve only the most recent message.
* *endIndex*
The *endIndex* is an optional parameter and defaults to the value "-1",
which indicates to only retrieve the one message specified by
*startIndex*. If specified, it may be an index of a specific message
starting with the index "1", or it may have any of the following values:
+ __last__
The message is the last message read by a POP3 client, see
__::pop3::last__.
+ __end__
The most recent message in the spool (the end of the spool).
- <a name='7'></a>__::pop3::list__ *chan* ?*msg*?
Returns the scan listing of the mailbox. If parameter *msg* is given, then
the listing only for that message is returned.
- <a name='8'></a>__::pop3::top__ *chan* *msg* *n*
Optional POP3 command, not all servers may support this. __::pop3::top__
retrieves headers of a message, specified by parameter *msg*, and number of
*n* lines from the message body.
- <a name='9'></a>__::pop3::uidl__ *chan* ?*msg*?
Optional POP3 command, not all servers may support this. __::pop3::uidl__
returns the uid listing of the mailbox. If the parameter *msg* is specified,
then the listing only for that message is returned.
- <a name='10'></a>__::pop3::capa__ *chan*
Optional POP3 command, not all servers may support this. __::pop3::capa__
returns a list of the capabilities of the server. TOP, SASL, UIDL,
LOGIN-DELAY and STLS are typical capabilities. See IETF RFC 2449.
- <a name='11'></a>__::pop3::close__ *chan*
Gracefully close the connect after sending a POP3 QUIT command down the
socket.
# <a name='section4'></a>Secure mail transfer
A pop3 connection can be secured with SSL/TLS by requiring the package
__[TLS](../../../../index.md#tls)__ and then using either the option
__-socketcmd__ or the option __-stls__ of the command __pop3::open__. The first
method, option __-socketcmd__, will force the use of the __tls::socket__ command
when opening the connection. This is suitable for POP3 servers which expect SSL
connections only. These will generally be listening on port 995.
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured pop3 channel
pop3::open -socketcmd tls::socket \\
$thehost $theuser $thepassword
...
The second method, option __-stls__, will connect to the standard POP3 port and
then perform an STARTTLS handshake. This will only work for POP3 servers which
have this capability. The package will confirm that the server supports STARTTLS
and the handshake was performed correctly before proceeding with authentication.
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured pop3 channel
pop3::open -stls 1 \\
$thehost $theuser $thepassword
...
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pop3* 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.
# <a name='keywords'></a>KEYWORDS
[email](../../../../index.md#email), [mail](../../../../index.md#mail),
[pop](../../../../index.md#pop), [pop3](../../../../index.md#pop3), [rfc
1939](../../../../index.md#rfc_1939), [secure](../../../../index.md#secure),
[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/pop3d/pop3d.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
[//000000001]: # (pop3d - Tcl POP3 Server Package)
[//000000002]: # (Generated from file 'pop3d.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pop3d(n) 1.1.0 tcllib "Tcl POP3 Server Package")
# NAME
pop3d - Tcl POP3 server implementation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Options](#section2)
- [Authentication](#section3)
- [Mailboxes](#section4)
- [Secure mail transfer](#section5)
- [References](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require pop3d ?1.1.0?
[__::pop3d::new__ ?*serverName*?](#1)
[__serverName__ *option* ?*arg arg ...*?](#2)
[*serverName* __up__](#3)
[*serverName* __down__](#4)
[*serverName* __destroy__ ?*mode*?](#5)
[*serverName* __configure__](#6)
[*serverName* __configure__ *-option*](#7)
[*serverName* __configure__ *-option value*...](#8)
[*serverName* __cget__ *-option*](#9)
[*serverName* __conn__ list](#10)
[*serverName* __conn__ state *id*](#11)
[*authCmd* __exists__ *name*](#12)
[*authCmd* __lookup__ *name*](#13)
[*storageCmd* __dele__ *mbox* *msgList*](#14)
[*storageCmd* __lock__ *mbox*](#15)
[*storageCmd* __unlock__ *mbox*](#16)
[*storageCmd* __size__ *mbox* ?*msgId*?](#17)
[*storageCmd* __stat__ *mbox*](#18)
[*storageCmd* __get__ *mbox* *msgId*](#19)
# <a name='description'></a>DESCRIPTION
- <a name='1'></a>__::pop3d::new__ ?*serverName*?
This command creates a new server object with an associated global Tcl
command whose name is *serverName*.
The command __serverName__ may be used to invoke various operations on the
server. It has the following general form:
- <a name='2'></a>__serverName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
A pop3 server can be started on any port the caller has permission for from the
operating system. The default port will be 110, which is the port defined by the
standard specified in RFC 1939
([http://www.rfc-editor.org/rfc/rfc1939.txt](http://www.rfc-editor.org/rfc/rfc1939.txt)).
After creating, configuring and starting a the server object will listen for and
accept connections on that port and handle them according to the POP3 protocol.
*Note:* The server provided by this module will handle only the basic protocol
by itself. For the higher levels of user authentication and handling of the
actual mailbox contents callbacks will be invoked.
The following commands are possible for server objects:
- <a name='3'></a>*serverName* __up__
After this call the server will listen for connections on its configured
port.
- <a name='4'></a>*serverName* __down__
After this call the server will stop listening for connections. This does
not affect existing connections.
- <a name='5'></a>*serverName* __destroy__ ?*mode*?
Destroys the server object. Currently open connections are handled depending
on the chosen mode. The provided *mode*s are:
* __kill__
Destroys the server immediately, and forcefully closes all currently
open connections. This is the default mode.
* __defer__
Stops the server from accepting new connections and will actually
destroy it only after the last of the currently open connections for the
server is closed.
- <a name='6'></a>*serverName* __configure__
Returns a list containing all options and their current values in a format
suitable for use by the command __array set__. The options themselves are
described in section [Options](#section2).
- <a name='7'></a>*serverName* __configure__ *-option*
Returns the current value of the specified option. This is an alias for the
method __cget__. The options themselves are described in section
[Options](#section2).
- <a name='8'></a>*serverName* __configure__ *-option value*...
Sets the specified option to the provided value. The options themselves are
described in section [Options](#section2).
- <a name='9'></a>*serverName* __cget__ *-option*
Returns the current value of the specified option. The options themselves
are described in section [Options](#section2).
- <a name='10'></a>*serverName* __conn__ list
Returns a list containing the ids of all connections currently open.
- <a name='11'></a>*serverName* __conn__ state *id*
Returns a list suitable for [__array set__] containing the state of the
connection referenced by *id*.
# <a name='section2'></a>Options
The following options are available to pop3 server objects.
- __-port__ *port*
Defines the *port* to listen on for new connections. Default is 110. This
option is a bit special. If *port* is set to "0" the server, or rather the
operating system, will select a free port on its own. When querying
__-port__ the id of this chosen port will be returned. Changing the port
while the server is up will neither change the returned value, nor will it
change on which port the server is listening on. Only after resetting the
server via a call to __down__ followed by a call to __up__ will the new port
take effect. It is at that time that the value returned when querying
__-port__ will change too.
- __-auth__ *command*
Defines a *command* prefix to call whenever the authentication of a user is
required. If no such command is specified the server will reject all users.
The interface which has to be provided by the command prefix is described in
section [Authentication](#section3).
- __-storage__ *command*
Defines a *command* prefix to call whenever the handling of mailbox contents
is required. If no such command is specified the server will claim that all
mailboxes are empty. The interface which has to be provided by the command
prefix is described in section [Mailboxes](#section4).
- __-socket__ *command*
Defines a *command* prefix to call for opening the listening socket. This
can be used to make the pop3 server listen on a SSL socket as provided by
the __[tls](../../../../index.md#tls)__ package, see the command
__tls::socket__.
# <a name='section3'></a>Authentication
Here we describe the interface which has to be provided by the authentication
callback so that pop3 servers following the interface of this module are able to
use it.
- <a name='12'></a>*authCmd* __exists__ *name*
This method is given a user*name* and has to return a boolean value telling
whether or not the specified user exists.
- <a name='13'></a>*authCmd* __lookup__ *name*
This method is given a user*name* and has to return a two-element list
containing the password for this user and a storage reference, in this
order.
The storage reference is passed unchanged to the storage callback, see
sections [Options](#section2) and [Mailboxes](#section4) for either the
option defining it and or the interface to provide, respectively.
# <a name='section4'></a>Mailboxes
Here we describe the interface which has to be provided by the storage callback
so that pop3 servers following the interface of this module are able to use it.
The *mbox* argument is the storage reference as returned by the __lookup__
method of the authentication command, see section [Authentication](#section3).
- <a name='14'></a>*storageCmd* __dele__ *mbox* *msgList*
Deletes the messages whose numeric ids are contained in the *msgList* from
the mailbox specified via *mbox*.
- <a name='15'></a>*storageCmd* __lock__ *mbox*
This method locks the specified mailbox for use by a single connection to
the server. This is necessary to prevent havoc if several connections to the
same mailbox are open. The complementary method is __unlock__. The command
will return true if the lock could be set successfully or false if not.
- <a name='16'></a>*storageCmd* __unlock__ *mbox*
This is the complementary method to __lock__, it revokes the lock on the
specified mailbox.
- <a name='17'></a>*storageCmd* __size__ *mbox* ?*msgId*?
Determines the size of the message specified through its id in *msgId*, in
bytes, and returns this number. The command will return the size of the
whole maildrop if no message id was specified.
- <a name='18'></a>*storageCmd* __stat__ *mbox*
Determines the number of messages in the specified mailbox and returns this
number.
- <a name='19'></a>*storageCmd* __get__ *mbox* *msgId*
Returns a handle for the specified message. This handle is a mime token
following the interface described in the documentation of package
__[mime](../mime/mime.md)__. The pop3 server will use the functionality of
the mime token to send the mail to the requestor at the other end of a pop3
connection.
# <a name='section5'></a>Secure mail transfer
The option __-socket__ (see [Options](#section2)) enables users of the package
to override how the server opens its listening socket. The envisioned main use
is the specification of the __tls::socket__ command, see package
__[tls](../../../../index.md#tls)__, to secure the communication.
package require tls
tls::init \\
...
pop3d::new S -socket tls::socket
...
# <a name='section6'></a>References
1. [RFC 1939](http://www.rfc-editor.org/rfc/rfc1939.txt)
1. [RFC 2449](http://www.rfc-editor.org/rfc/rfc2449.txt)
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pop3d* 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.
# <a name='keywords'></a>KEYWORDS
[internet](../../../../index.md#internet),
[network](../../../../index.md#network), [pop3](../../../../index.md#pop3),
[protocol](../../../../index.md#protocol), [rfc
1939](../../../../index.md#rfc_1939), [secure](../../../../index.md#secure),
[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002-2009 Andreas Kupries <[email protected]>
Copyright © 2005 Reinhard Max <[email protected]>
|
Added embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
[//000000001]: # (pop3d::dbox - Tcl POP3 Server Package)
[//000000002]: # (Generated from file 'pop3d_dbox.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pop3d::dbox(n) 1.0.2 tcllib "Tcl POP3 Server Package")
# NAME
pop3d::dbox - Simple mailbox database for pop3d
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require pop3d::dbox ?1.0.2?
[__::pop3d::dbox::new__ ?*dbName*?](#1)
[__dbName__ *option* ?*arg arg ...*?](#2)
[*dbName* __destroy__](#3)
[*dbName* __base__ *base*](#4)
[*dbName* __add__ *mbox*](#5)
[*dbName* __remove__ *mbox*](#6)
[*dbName* __move__ *old new*](#7)
[*dbName* __list__](#8)
[*dbName* __exists__ *mbox*](#9)
[*dbName* __locked__ *mbox*](#10)
[*dbName* __lock__ *mbox*](#11)
[*dbName* __unlock__ *mbox*](#12)
[*dbName* __stat__ *mbox*](#13)
[*dbName* __size__ *mbox* ?*msgId*?](#14)
[*dbName* __dele__ *mbox msgList*](#15)
[*storageCmd* __get__ *mbox* *msgId*](#16)
# <a name='description'></a>DESCRIPTION
The package __pop3d::dbox__ provides simple/basic mailbox management facilities.
Each mailbox object manages a single base directory whose subdirectories
represent the managed mailboxes. Mails in a mailbox are represented by files in
a mailbox directory, where each of these files contains a single mail, both
headers and body, in RFC 822
([http://www.rfc-editor.org/rfc/rfc822.txt](http://www.rfc-editor.org/rfc/rfc822.txt))
conformant format.
Any mailbox object following the interface described below can be used in
conjunction with the pop3 server core provided by the package
__[pop3d](pop3d.md)__. It is especially possible to directly use the objects
created by this package in the storage callback of pop3 servers following the
same interface as servers created by the package __[pop3d](pop3d.md)__.
- <a name='1'></a>__::pop3d::dbox::new__ ?*dbName*?
This command creates a new database object with an associated global Tcl
command whose name is *dbName*.
The command __dbName__ may be used to invoke various operations on the database.
It has the following general form:
- <a name='2'></a>__dbName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
The following commands are possible for database objects:
- <a name='3'></a>*dbName* __destroy__
Destroys the mailbox database and all transient data. The directory
associated with the object is not destroyed.
- <a name='4'></a>*dbName* __base__ *base*
Defines the base directory containing the mailboxes to manage. If this
method is not called none of the following methods will work.
- <a name='5'></a>*dbName* __add__ *mbox*
Adds a mailbox of name *mbox* to the database. The name must be a valid path
component.
- <a name='6'></a>*dbName* __remove__ *mbox*
Removes the mailbox specified through *mbox*, and the mails contained
therein, from the database. This method will fail if the specified mailbox
is locked.
- <a name='7'></a>*dbName* __move__ *old new*
Changes the name of the mailbox *old* to *new*.
- <a name='8'></a>*dbName* __list__
Returns a list containing the names of all mailboxes in the directory
associated with the database.
- <a name='9'></a>*dbName* __exists__ *mbox*
Returns true if the mailbox with name *mbox* exists in the database, or
false if not.
- <a name='10'></a>*dbName* __locked__ *mbox*
Checks if the mailbox specified through *mbox* is currently locked.
- <a name='11'></a>*dbName* __lock__ *mbox*
This method locks the specified mailbox for use by a single connection to
the server. This is necessary to prevent havoc if several connections to the
same mailbox are open. The complementary method is __unlock__. The command
will return true if the lock could be set successfully or false if not.
- <a name='12'></a>*dbName* __unlock__ *mbox*
This is the complementary method to __lock__, it revokes the lock on the
specified mailbox.
- <a name='13'></a>*dbName* __stat__ *mbox*
Determines the number of messages in the specified mailbox and returns this
number. This method fails if the mailbox *mbox* is not locked.
- <a name='14'></a>*dbName* __size__ *mbox* ?*msgId*?
Determines the size of the message specified through its id in *msgId*, in
bytes, and returns this number. The command will return the size of the
whole maildrop if no message id was specified. If specified the *msgId* has
to be in the range "1 ... [*dbName* __stat__]" or this call will fail. If
__stat__ was not called before this call, __size__ will assume that there
are zero messages in the mailbox.
- <a name='15'></a>*dbName* __dele__ *mbox msgList*
Deletes the messages whose numeric ids are contained in the *msgList* from
the mailbox specified via *mbox*. The *msgList* must not be empty or this
call will fail. The numeric ids in *msgList* have to be in the range "1 ...
[*dbName* __stat__]" or this call will fail. If __stat__ was not called
before this call, __dele__ will assume that there are zero messages in the
mailbox.
- <a name='16'></a>*storageCmd* __get__ *mbox* *msgId*
Returns a handle for the specified message. This handle is a mime token
following the interface described in the documentation of package
__[mime](../mime/mime.md)__. The token is *read-only*. In other words, the
caller is allowed to do anything with the token except to modify it. The
*msgId* has to be in the range "1 ... [*dbName* __stat__]" or this call will
fail. If __stat__ was not called before this call, __get__ will assume that
there are zero messages in the mailbox.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pop3d* 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.
# <a name='keywords'></a>KEYWORDS
[internet](../../../../index.md#internet),
[network](../../../../index.md#network), [pop3](../../../../index.md#pop3),
[protocol](../../../../index.md#protocol), [rfc
822](../../../../index.md#rfc_822)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
[//000000001]: # (pop3d::udb - Tcl POP3 Server Package)
[//000000002]: # (Generated from file 'pop3d_udb.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pop3d::udb(n) 1.0.1 tcllib "Tcl POP3 Server Package")
# NAME
pop3d::udb - Simple user database for pop3d
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require pop3d::udb ?1.0.1?
[__::pop3d::udb::new__ ?*dbName*?](#1)
[__dbName__ *option* ?*arg arg ...*?](#2)
[*dbName* __destroy__](#3)
[*dbName* __add__ *user pwd storage*](#4)
[*dbName* __remove__ *user*](#5)
[*dbName* __rename__ *user newName*](#6)
[*dbName* __lookup__ *user*](#7)
[*dbName* __exists__ *user*](#8)
[*dbName* __who__](#9)
[*dbName* __save__ ?*file*?](#10)
[*dbName* __read__ *file*](#11)
# <a name='description'></a>DESCRIPTION
The package __pop3d::udb__ provides simple in memory databases which can be used
in conjunction with the pop3 server core provided by the package
__[pop3d](pop3d.md)__. The databases will use the names of users as keys and
associates passwords and storage references with them.
Objects created by this package can be directly used in the authentication
callback of pop3 servers following the same interface as servers created by the
package __[pop3d](pop3d.md)__.
- <a name='1'></a>__::pop3d::udb::new__ ?*dbName*?
This command creates a new database object with an associated global Tcl
command whose name is *dbName*.
The command __dbName__ may be used to invoke various operations on the database.
It has the following general form:
- <a name='2'></a>__dbName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
The following commands are possible for database objects:
- <a name='3'></a>*dbName* __destroy__
Destroys the database object.
- <a name='4'></a>*dbName* __add__ *user pwd storage*
Add a new user or changes the data of an existing user. Stores *password*
and *storage* reference for the given *user*.
- <a name='5'></a>*dbName* __remove__ *user*
Removes the specified *user* from the database.
- <a name='6'></a>*dbName* __rename__ *user newName*
Changes the name of the specified *user* to *newName*.
- <a name='7'></a>*dbName* __lookup__ *user*
Searches the database for the specified *user* and returns a two-element
list containing the associated password and storage reference, in this
order. Throws an error if the user could not be found. This is the interface
as expected by the authentication callback of package __[pop3d](pop3d.md)__.
- <a name='8'></a>*dbName* __exists__ *user*
Returns true if the specified *user* is known to the database, else false.
- <a name='9'></a>*dbName* __who__
Returns a list of users known to the database.
- <a name='10'></a>*dbName* __save__ ?*file*?
Saves the contents of the database into the given *file*. If the file is not
specified the system will use the path last used in a call to *dbName*
__read__. The generated file can be read by the __read__ method.
- <a name='11'></a>*dbName* __read__ *file*
Reads the specified *file* and adds the contained user definitions to the
database. As the file is actually
__[source](../../../../index.md#source)__'d a safe interpreter is employed
to safeguard against malicious code. This interpreter knows the __add__
command for adding users and their associated data to this database. This
command has the same argument signature as the method __add__. The path of
the *file* is remembered internally so that it can be used in the next call
of *dbName* __save__ without an argument.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pop3d* 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.
# <a name='keywords'></a>KEYWORDS
[internet](../../../../index.md#internet),
[network](../../../../index.md#network), [pop3](../../../../index.md#pop3),
[protocol](../../../../index.md#protocol)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/practcl/practcl.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
[//000000001]: # (practcl - The The Proper Rational API for C to Tool Command Language Module)
[//000000002]: # (Generated from file 'practcl.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (practcl(n) 0.11 tcllib "The The Proper Rational API for C to Tool Command Language Module")
# NAME
practcl - The Practcl Module
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require TclOO 1.0
package require practcl 0.11
[__CPUTS__ *varname* *body* ?*body*...?](#1)
[__practcl::_isdirectory__ *path*](#2)
[__practcl::object__ *parent* ?*keyvaluelist*?](#3)
[__practcl::library__ ?*keyvaluelist*?](#4)
[__practcl::exe__ ?*keyvaluelist*?](#5)
[__practcl::product__ *parent* ?*keyvaluelist*?](#6)
[__practcl::cheader__ *parent* ?*keyvaluelist*?](#7)
[__practcl::csource__ *parent* ?*keyvaluelist*?](#8)
[__practcl::module__ *parent* ?*keyvaluelist*?](#9)
[__practcl::submodule__ *parent* ?*keyvaluelist*?](#10)
# <a name='description'></a>DESCRIPTION
The Practcl module is a tool for integrating large modules for C API Tcl code
that requires custom Tcl types and TclOO objects.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__CPUTS__ *varname* *body* ?*body*...?
Appends blocks of text to a buffer. This command tries to reduce the number
of line breaks between bodies.
- <a name='2'></a>__practcl::_isdirectory__ *path*
Returns true if *path* is a directory, using the test
- <a name='3'></a>__practcl::object__ *parent* ?*keyvaluelist*?
A generic Practcl object
- <a name='4'></a>__practcl::library__ ?*keyvaluelist*?
A Practcl object representing a library container
- <a name='5'></a>__practcl::exe__ ?*keyvaluelist*?
A Practcl object representing a wrapped executable
- <a name='6'></a>__practcl::product__ *parent* ?*keyvaluelist*?
A Practcl object representing a compiled product
- <a name='7'></a>__practcl::cheader__ *parent* ?*keyvaluelist*?
A Practcl object representing an externally generated c header
- <a name='8'></a>__practcl::csource__ *parent* ?*keyvaluelist*?
A Practcl object representing an externally generated c source file
- <a name='9'></a>__practcl::module__ *parent* ?*keyvaluelist*?
A Practcl object representing a dynamically generated C/H/Tcl suite
- <a name='10'></a>__practcl::submodule__ *parent* ?*keyvaluelist*?
A Practcl object representing a dynamically generated C/H/Tcl suite,
subordinate to a module
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *practcl* 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.
# <a name='keywords'></a>KEYWORDS
[practcl](../../../../index.md#practcl)
# <a name='category'></a>CATEGORY
TclOO
# <a name='copyright'></a>COPYRIGHT
Copyright © 2016-2018 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/processman/processman.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
[//000000001]: # (processman - processman)
[//000000002]: # (Generated from file 'processman.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (processman(n) 0.1 tcllib "processman")
# NAME
processman - Tool for automating the period callback of commands
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Commands](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require twapi 3.1
package require cron 1.1
package require processman ?0.1?
[__::processman::find_exe__ *name*](#1)
[__::processman::kill__ *id*](#2)
[__::processman::kill_all__](#3)
[__::processman::killexe__ *name*](#4)
[__::processman::onexit__ *id* *cmd*](#5)
[__::processman::priority__ *id* *level*](#6)
[__::processman::process_list__](#7)
[__::processman::process_list__ *id*](#8)
[__::processman::spawn__ *id* *cmd* *args*](#9)
# <a name='description'></a>DESCRIPTION
The __processman__ package provides a Pure-tcl set of utilities to manage child
processes in a platform-generic nature.
# <a name='section2'></a>Commands
- <a name='1'></a>__::processman::find_exe__ *name*
Locate an executable by the name of *name* in the system path. On windows,
also add the .exe extention if not given.
- <a name='2'></a>__::processman::kill__ *id*
Kill a child process *id*.
- <a name='3'></a>__::processman::kill_all__
Kill all processes spawned by this program
- <a name='4'></a>__::processman::killexe__ *name*
Kill a process identified by the executable. On Unix, this triggers a
killall. On windows, __twapi::get_process_ids__ is used to map a name one or
more IDs, which are then killed.
- <a name='5'></a>__::processman::onexit__ *id* *cmd*
Arrange to execute the script *cmd* when this programe detects that process
*id* as terminated.
- <a name='6'></a>__::processman::priority__ *id* *level*
Mark process *id* with the priorty *level*. Valid levels: low, high,
default.
On Unix, the process is tagged using the __nice__ command.
On Windows, the process is modifed via the __twapi::set_priority_class__
- <a name='7'></a>__::processman::process_list__
Return a list of processes that have been triggered by this program, as well
as a boolean flag to indicate if the process is still running.
- <a name='8'></a>__::processman::process_list__ *id*
Return true if process *id* is still running, false otherwise.
- <a name='9'></a>__::processman::spawn__ *id* *cmd* *args*
Start a child process, identified by *id*. *cmd* is the name of the command
to execute. *args* are arguments to pass to that command.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *odie* 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.
# <a name='keywords'></a>KEYWORDS
[odie](../../../../index.md#odie), [processman](../../../../index.md#processman)
# <a name='category'></a>CATEGORY
System
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/profiler/profiler.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
[//000000001]: # (profiler - Tcl Profiler)
[//000000002]: # (Generated from file 'profiler.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (profiler(n) 0.3 tcllib "Tcl Profiler")
# NAME
profiler - Tcl source code profiler
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require profiler ?0.3?
[__::profiler::init__](#1)
[__::profiler::dump__ *pattern*](#2)
[__::profiler::print__ ?*pattern*?](#3)
[__::profiler::reset__ ?*pattern*?](#4)
[__::profiler::suspend__ ?*pattern*?](#5)
[__::profiler::resume__ ?*pattern*?](#6)
[__::profiler::sortFunctions__ *key*](#7)
# <a name='description'></a>DESCRIPTION
The __profiler__ package provides a simple Tcl source code profiler. It is a
function-level profiler; that is, it collects only function-level information,
not the more detailed line-level information. It operates by redefining the Tcl
__[proc](../../../../index.md#proc)__ command. Profiling is initiated via the
__::profiler::init__ command.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::profiler::init__
Initiate profiling. All procedures created after this command is called will
be profiled. To profile an entire application, this command must be called
before any other commands.
- <a name='2'></a>__::profiler::dump__ *pattern*
Dump profiling information for the all functions matching *pattern*. If no
pattern is specified, information for all functions will be returned. The
result is a list of key/value pairs that maps function names to information
about that function. The information about each function is in turn a list
of key/value pairs. The keys used and their values are:
* __totalCalls__
The total number of times *functionName* was called.
* __callerDist__
A list of key/value pairs mapping each calling function that called
*functionName* to the number of times it called *functionName*.
* __compileTime__
The runtime, in clock clicks, of *functionName* the first time that it
was called.
* __totalRuntime__
The sum of the runtimes of all calls of *functionName*.
* __averageRuntime__
Average runtime of *functionName*.
* __descendantTime__
Sum of the time spent in descendants of *functionName*.
* __averageDescendantTime__
Average time spent in descendants of *functionName*.
- <a name='3'></a>__::profiler::print__ ?*pattern*?
Print profiling information for all functions matching *pattern*. If no
pattern is specified, information about all functions will be displayed. The
return result is a human readable display of the profiling information.
- <a name='4'></a>__::profiler::reset__ ?*pattern*?
Reset profiling information for all functions matching *pattern*. If no
pattern is specified, information will be reset for all functions.
- <a name='5'></a>__::profiler::suspend__ ?*pattern*?
Suspend profiling for all functions matching *pattern*. If no pattern is
specified, profiling will be suspended for all functions. It stops gathering
profiling information after this command is issued. However, it does not
erase any profiling information that has been gathered previously. Use
resume command to re-enable profiling.
- <a name='6'></a>__::profiler::resume__ ?*pattern*?
Resume profiling for all functions matching *pattern*. If no pattern is
specified, profiling will be resumed for all functions. This command should
be invoked after suspending the profiler in the code.
- <a name='7'></a>__::profiler::sortFunctions__ *key*
Return a list of functions sorted by a particular profiling statistic.
Supported values for *key* are: __calls__, __exclusiveTime__,
__compileTime__, __nonCompileTime__, __totalRuntime__, __avgExclusiveTime__,
and __avgRuntime__. The return result is a list of lists, where each sublist
consists of a function name and the value of *key* for that function.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *profiler* 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.
# <a name='keywords'></a>KEYWORDS
[performance](../../../../index.md#performance),
[profile](../../../../index.md#profile), [speed](../../../../index.md#speed)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/pt/pt_astree.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
|
[//000000001]: # (pt::ast - Parser Tools)
[//000000002]: # (Generated from file 'pt_astree.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::ast(n) 1.1 tcllib "Parser Tools")
# NAME
pt::ast - Abstract Syntax Tree Serialization
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [AST serialization format](#section3)
- [Example](#subsection1)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::ast ?1.1?
[__::pt::ast__ __verify__ *serial* ?*canonvar*?](#1)
[__::pt::ast__ __verify-as-canonical__ *serial*](#2)
[__::pt::ast__ __canonicalize__ *serial*](#3)
[__::pt::ast__ __print__ *serial*](#4)
[__::pt::ast__ __bottomup__ *cmdprefix* *ast*](#5)
[__cmdprefix__ *ast*](#6)
[__::pt::ast__ __topdown__ *cmdprefix* *pe*](#7)
[__::pt::ast__ __equal__ *seriala* *serialb*](#8)
[__::pt::ast__ __new0__ *s* *loc* ?*child*...?](#9)
[__::pt::ast__ __new__ *s* *start* *end* ?*child*...?](#10)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides commands to work with the serializations of abstract
syntax trees as managed by the Parser Tools, and specified in section [AST
serialization format](#section3).
This is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::ast__ __verify__ *serial* ?*canonvar*?
This command verifies that the content of *serial* is a valid serialization
of an abstract syntax tree and will throw an error if that is not the case.
The result of the command is the empty string.
If the argument *canonvar* is specified it is interpreted as the name of a
variable in the calling context. This variable will be written to if and
only if *serial* is a valid regular serialization. Its value will be a
boolean, with __True__ indicating that the serialization is not only valid,
but also *canonical*. __False__ will be written for a valid, but
non-canonical serialization.
For the specification of serializations see the section [AST serialization
format](#section3).
- <a name='2'></a>__::pt::ast__ __verify-as-canonical__ *serial*
This command verifies that the content of *serial* is a valid *canonical*
serialization of an abstract syntax tree and will throw an error if that is
not the case. The result of the command is the empty string.
For the specification of canonical serializations see the section [AST
serialization format](#section3).
- <a name='3'></a>__::pt::ast__ __canonicalize__ *serial*
This command assumes that the content of *serial* is a valid *regular*
serialization of an abstract syntax and will throw an error if that is not
the case.
It will then convert the input into the *canonical* serialization of the
contained tree and return it as its result. If the input is already
canonical it will be returned unchanged.
For the specification of regular and canonical serializations see the
section [AST serialization format](#section3).
- <a name='4'></a>__::pt::ast__ __print__ *serial*
This command assumes that the argument *serial* contains a valid
serialization of an abstract syntax tree and returns a string containing
that tree in a human readable form.
The exact format of this form is not specified and cannot be relied on for
parsing or other machine-based activities.
For the specification of serializations see the section [AST serialization
format](#section3).
- <a name='5'></a>__::pt::ast__ __bottomup__ *cmdprefix* *ast*
This command walks the abstract syntax tree *ast* from the bottom up to the
root, invoking the command prefix *cmdprefix* for each node. This implies
that the children of a node N are handled before N.
The command prefix has the signature
* <a name='6'></a>__cmdprefix__ *ast*
I.e. it is invoked with the ast node the walk is currently at.
The result returned by the command prefix replaces *ast* in the node it
was a child of, allowing transformations of the tree.
This also means that for all inner node the contents of the children
elements are the results of the command prefix invoked for the children
of this node.
- <a name='7'></a>__::pt::ast__ __topdown__ *cmdprefix* *pe*
This command walks the abstract syntax tree *ast* from the root down to the
leaves, invoking the command prefix *cmdprefix* for each node. This implies
that the children of a node N are handled after N.
The command prefix has the same signature as for __bottomup__, see above.
The result returned by the command prefix is *ignored*.
- <a name='8'></a>__::pt::ast__ __equal__ *seriala* *serialb*
This command tests the two sbstract syntax trees *seriala* and *serialb* for
structural equality. The result of the command is a boolean value. It will
be set to __true__ if the trees are identical, and __false__ otherwise.
String equality is usable only if we can assume that the two trees are pure
Tcl lists.
- <a name='9'></a>__::pt::ast__ __new0__ *s* *loc* ?*child*...?
This command command constructs the ast for a nonterminal node refering
refering to the symbol *s* at position *loc* in the input, and the set of
child nodes *child* ..., from left right. The latter may be empty. The
constructed node is returned as the result of the command. The end position
is *loc*-1, i.e. one character before the start. This type of node is
possible for rules containing optional parts.
- <a name='10'></a>__::pt::ast__ __new__ *s* *start* *end* ?*child*...?
This command command constructs the ast for a nonterminal node refering to
the symbol *s* covering the range of positions *start* to *end* in the
input, and the set of child nodes *child* ..., from left right. The latter
may be empty. The constructed node is returned as the result of the command.
# <a name='section3'></a>AST serialization format
Here we specify the format used by the Parser Tools to serialize Abstract Syntax
Trees (ASTs) as immutable values for transport, comparison, etc.
Each node in an AST represents a nonterminal symbol of a grammar, and the range
of tokens/characters in the input covered by it. ASTs do not contain terminal
symbols, i.e. tokens/characters. These can be recovered from the input given a
symbol's location.
We distinguish between *regular* and *canonical* serializations. While a tree
may have more than one regular serialization only exactly one of them will be
*canonical*.
- Regular serialization
The serialization of any AST is the serialization of its root node.
The serialization of any node is a Tcl list containing at least three
elements.
The first element is the name of the nonterminal symbol stored in the node.
The second and third element are the locations of the first and last token
in the token stream the node represents (covers).
Locations are provided as non-negative integer offsets from the beginning of
the token stream, with the first token found in the stream located at offset
0 (zero).
The end location has to be equal to or larger than the start location.
All elements after the first three represent the children of the node, which
are themselves nodes. This means that the serializations of nodes without
children, i.e. leaf nodes, have exactly three elements. The children are
stored in the list with the leftmost child first, and the rightmost child
last.
- Canonical serialization
The canonical serialization of an abstract syntax tree has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this tree.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
## <a name='subsection1'></a>Example
Assuming the parsing expression grammar below
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
and the input string
120+5
then a parser should deliver the abstract syntax tree below (except for
whitespace)
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
Or, more graphical
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
[//000000001]: # (pt::cparam::configuration::critcl - Parser Tools)
[//000000002]: # (Generated from file 'pt_cparam_config_critcl.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::cparam::configuration::critcl(n) 1.0.2 tcllib "Parser Tools")
# NAME
pt::cparam::configuration::critcl - C/PARAM, Canned configuration, Critcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::cparam::configuration::critcl ?1.0.2?
[__::pt::cparam::configuration::critcl__ __def__ *name* *pkg* *version* *cmdprefix*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package is an adjunct to __[pt::peg::to::cparam](pt_peg_to_cparam.md)__, to
make the use of this highly configurable package easier by providing a canned
configuration. When applied this configuration causes the package
__[pt::peg::to::cparam](pt_peg_to_cparam.md)__ to generate __critcl__-based
parser packages.
It is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::cparam::configuration::critcl__ __def__ *name* *pkg* *version* *cmdprefix*
The command applies the configuration provided by this package to the
*cmdprefix*, causing the creation of __critcl__-based parsers whose class is
*name*, in package *pkg* with *version*.
The use of a command prefix as API allows application of the configuration
to not only __[pt::peg::to::cparam](pt_peg_to_cparam.md)__
(__pt::peg::to::cparam configure__), but also export manager instances and
PEG containers (__$export configuration set__ and __[$container exporter]
configuration set__ respectively).
Or anything other command prefix accepting two arguments, option and value.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
[//000000001]: # (pt::cparam::configuration::tea - Parser Tools)
[//000000002]: # (Generated from file 'pt_cparam_config_tea.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::cparam::configuration::tea(n) 0.1 tcllib "Parser Tools")
# NAME
pt::cparam::configuration::tea - C/PARAM, Canned configuration, TEA
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::cparam::configuration::tea ?0.1?
[__::pt::cparam::configuration::tea__ __def__ *name* *pkg* *version* *cmdprefix*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package is an adjunct to __[pt::peg::to::cparam](pt_peg_to_cparam.md)__, to
make the use of this highly configurable package easier by providing a canned
configuration. When applied this configuration causes the package
__[pt::peg::to::cparam](pt_peg_to_cparam.md)__ to generate plain parser code
ready for inclusion into a *TEA*-based C extension.
It is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::cparam::configuration::tea__ __def__ *name* *pkg* *version* *cmdprefix*
The command applies the configuration provided by this package to the
*cmdprefix*, causing the creation of __tea__-based parsers whose class is
*name*, in package *pkg* with *version*.
The use of a command prefix as API allows application of the configuration
to not only __[pt::peg::to::cparam](pt_peg_to_cparam.md)__
(__pt::peg::to::cparam configure__), but also export manager instances and
PEG containers (__$export configuration set__ and __[$container exporter]
configuration set__ respectively).
Or anything other command prefix accepting two arguments, option and value.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_from_api.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
|
[//000000001]: # (pt_import_api - Parser Tools)
[//000000002]: # (Generated from file 'pt_from_api.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt_import_api(i) 1 tcllib "Parser Tools")
# NAME
pt_import_api - Parser Tools Import API
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Converter API](#section2)
- [Plugin API](#section3)
- [Usage](#section4)
- [PEG serialization format](#section5)
- [Example](#subsection1)
- [PE serialization format](#section6)
- [Example](#subsection2)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
[__CONVERTER__ __convert__ *text*](#1)
[__IncludeFile__ *currentfile* *path*](#2)
[__::import__ *text*](#3)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This document describes two APIs. First the API shared by all packages for the
conversion of some other format into Parsing Expression Grammars , and then the
API shared by the packages which implement the import plugins sitting on top of
the conversion packages.
Its intended audience are people who wish to create their own converter for some
type of input, and/or an import plugin for their or some other converter.
It resides in the Import section of the Core Layer of Parser Tools.
# <a name='section2'></a>Converter API
Any (grammar) import converter has to follow the rules set out below:
1. A converter is a package. Its name is arbitrary, however it is recommended
to put it under the __::pt::peg::from__ namespace.
1. The package provides either a single Tcl command following the API outlined
below, or a class command whose instances follow the same API. The commands
which follow the API are called *converter commands*.
1. A converter command has to provide the following single method with the
given signature and semantic. Converter commands are allowed to provide
more methods of their own, but not less, and they may not provide different
semantics for the standardized method.
- <a name='1'></a>__CONVERTER__ __convert__ *text*
This method has to accept some *text*, a parsing expression grammar in
some format. The result of the method has to be the canonical
serialization of a parsing expression grammar, as specified in section
[PEG serialization format](#section5), the result of reading and
converting the input text.
# <a name='section3'></a>Plugin API
Any (grammar) import plugin has to follow the rules set out below:
1. A plugin is a package.
1. The name of a plugin package has the form pt::peg::import::__FOO__, where
__FOO__ is the name of the format the plugin will accept input for.
1. The plugin can expect that the package __pt::peg::import::plugin__ is
present, as indicator that it was invoked from a genuine plugin manager.
It is recommended that a plugin does check for the presence of this
package.
1. The plugin can expect that a command named __IncludeFile__ is present, with
the signature
- <a name='2'></a>__IncludeFile__ *currentfile* *path*
This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such.
The plugin has to supply the following arguments
* string *currentfile*
The path of the file it is currently processing. This may be the
empty string if no such is known.
* string *path*
The path of the include file as specified in the include directive
being processed.
The result of the command will be a 5-element list containing
A boolean flag indicating the success (__True__) or failure (__False__)
of the operation.
In case of success the contents of the included file, and the empty
string otherwise.
The resolved, i.e. absolute path of the included file, if possible, or
the unchanged *path* argument. This is for display in an error message,
or as the *currentfile* argument of another call to __IncludeFile__
should this file contain more files.
In case of success an empty string, and for failure a code indicating
the reason for it, one of
* notfound
The specified file could not be found.
* notread
The specified file was found, but not be read into memory.
An empty string in case of success of a __notfound__ failure, and an
additional error message describing the reason for a __notread__ error
in more detail.
1. A plugin has to provide a single command, in the global namespace, with the
signature shown below. Plugins are allowed to provide more commands of
their own, but not less, and they may not provide different semantics for
the standardized command.
- <a name='3'></a>__::import__ *text*
This command has to accept the a text containing a parsing expression
grammar in some format. The result of the command has to be the result
of the converter invoked by the plugin for the input grammar, the
canonical serialization of the parsing expression grammar contained in
the input.
* string *text*
This argument will contain the parsing expression grammar for which
to generate the serialization. The specification of what a
*canonical* serialization is can be found in the section [PEG
serialization format](#section5).
1. A single usage cycle of a plugin consists of an invokation of the command
__[import](../../../../index.md#import)__. This call has to leave the
plugin in a state where another usage cycle can be run without problems.
# <a name='section4'></a>Usage
To use a converter do
# Get the converter (single command here, not class)
package require the-converter-package
# Perform the conversion
set serial [theconverter convert $thegrammartext]
... process the result ...
To use a plugin __FOO__ do
# Get an import plugin manager
package require pt::peg::import
pt::peg::import I
# Run the plugin, and the converter inside.
set serial [I import serial $thegrammartext FOO]
... process the result ...
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection2'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_introduction.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
[//000000001]: # (pt_introduction - Parser Tools)
[//000000002]: # (Generated from file 'pt_introduction.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt_introduction(n) 1 tcllib "Parser Tools")
# NAME
pt_introduction - Introduction to Parser Tools
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Parser Tools Architecture](#section2)
- [User Packages](#subsection1)
- [Core Packages](#subsection2)
- [Support Packages](#subsection3)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Welcome to the Parser Tools, a system for the creation and manipulation of
parsers and the grammars driving them.
What are your goals which drove you here ?
1. Do you simply wish to create a parser for some language ?
In that case have a look at our parser generator application,
__[pt](../../apps/pt.md)__, or, for a slightly deeper access, the package
underneath it, __[pt::pgen](pt_pgen.md)__.
1. Do you wish to know more about the architecture of the system ?
This is described in the section [Parser Tools Architecture](#section2),
below
1. Is your interest in the theoretical background upon which the packages and
tools are build ?
See the *[Introduction to Parsing Expression
Grammars](pt_peg_introduction.md)*.
# <a name='section2'></a>Parser Tools Architecture
The system can be split into roughly three layers, as seen in the figure below
 These layers are, from high to low:
1. At the top we have the application and the packages using the packages of
the layer below to implement common usecases. One example is the
aforementioned __[pt::pgen](pt_pgen.md)__ which provides a parser
generator.
The list of packages belonging to this layer can be found in section [User
Packages](#subsection1)
1. In this layer we have the packages which provide the core of the
functionality for the whole system. They are, in essence, a set of blocks
which can be combined in myriad ways, like Lego (tm). The packages in the
previous level are 'just' pre-fabricated combinations to cover the most
important use cases.
The list of packages belonging to this layer can be found in section [Core
Packages](#subsection2)
1. Last, but not least is the layer containing support packages providing
generic functionality which not necessarily belong into the module.
The list of packages belonging to this layer can be found in section
[Support Packages](#subsection3)
## <a name='subsection1'></a>User Packages
- __[pt::pgen](pt_pgen.md)__
## <a name='subsection2'></a>Core Packages
This layer is further split into six sections handling the storage, import,
export, transformation, and execution of grammars, plus grammar specific support
packages.
- Storage
* __[pt::peg::container](pt_peg_container.md)__
- Export
* __[pt::peg::export](pt_peg_export.md)__
* __[pt::peg::export::container](pt_peg_export_container.md)__
* __[pt::peg::export::json](pt_peg_export_json.md)__
* __[pt::peg::export::peg](pt_peg_export_peg.md)__
* __[pt::peg::to::container](pt_peg_to_container.md)__
* __[pt::peg::to::json](pt_peg_to_json.md)__
* __[pt::peg::to::peg](pt_peg_to_peg.md)__
* __[pt::peg::to::param](pt_peg_to_param.md)__
* __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__
* __[pt::peg::to::cparam](pt_peg_to_cparam.md)__
- Import
* __[pt::peg::import](pt_peg_import.md)__
* __[pt::peg::import::container](pt_peg_import_container.md)__
* __[pt::peg::import::json](pt_peg_import_json.md)__
* __[pt::peg::import::peg](pt_peg_import_peg.md)__
* __[pt::peg::from::container](pt_peg_from_container.md)__
* __[pt::peg::from::json](pt_peg_from_json.md)__
* __[pt::peg::from::peg](pt_peg_from_peg.md)__
- Transformation
- Execution
* __[pt::peg::interp](pt_peg_interp.md)__
* __[pt::rde](pt_rdengine.md)__
- Support
* __[pt::tclparam::configuration::snit](pt_tclparam_config_snit.md)__
* __[pt::tclparam::configuration::tcloo](pt_tclparam_config_tcloo.md)__
* __[pt::cparam::configuration::critcl](pt_cparam_config_critcl.md)__
* __[pt::ast](pt_astree.md)__
* __[pt::pe](pt_pexpression.md)__
* __[pt::peg](pt_pegrammar.md)__
## <a name='subsection3'></a>Support Packages
- __[pt::peg::container::peg](pt_peg_container_peg.md)__
- __text::write__
- __configuration__
- __paths__
- __char__
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_json_language.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
|
[//000000001]: # (pt::json_language - Parser Tools)
[//000000002]: # (Generated from file 'pt_json_language.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::json_language(n) 1 tcllib "Parser Tools")
# NAME
pt::json_language - The JSON Grammar Exchange Format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Example](#subsection1)
- [PEG serialization format](#section2)
- [Example](#subsection2)
- [PE serialization format](#section3)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
The __json__ format for parsing expression grammars was written as a data
exchange format not bound to Tcl. It was defined to allow the exchange of
grammars with PackRat/PEG based parser generators for other languages.
It is formally specified by the rules below:
1. The JSON of any PEG is a JSON object.
1. This object holds a single key, __pt::grammar::peg__, and its value. This
value holds the contents of the grammar.
1. The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are
- __rules__
The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a JSON object itself. The relevant keys
and their values in this dictionary are
* __is__
The value is a JSON string holding the Tcl serialization of
the parsing expression describing the symbols sentennial
structure, as specified in the section [PE serialization
format](#section3).
* __mode__
The value is a JSON holding holding one of three values
specifying how a parser should handle the semantic value
produced by the symbol.
+ __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal itself, which has the ASTs of the symbol's
right hand side as its children.
+ __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal, without any children. Any ASTs generated
by the symbol's right hand side are discarded.
+ __void__
The nonterminal has no semantic value. Any ASTs generated
by the symbol's right hand side are discarded (as well).
- __start__
The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section [PE
serialization format](#section3).
1. The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
As an aside to the advanced reader, this is pretty much the same as the Tcl
serialization of PE grammars, as specified in section [PEG serialization
format](#section2), except that the Tcl dictionaries and lists of that format
are mapped to JSON objects and arrays. Only the parsing expressions themselves
are not translated further, but kept as JSON strings containing a nested Tcl
list, and there is no concept of canonicity for the JSON either.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
a JSON serialization for it is
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
and a Tcl serialization of the same is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
The similarity of the latter to the JSON should be quite obvious.
# <a name='section2'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section3).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section3).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section3'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_param.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
|
[//000000001]: # (pt::param - Parser Tools)
[//000000002]: # (Generated from file 'pt_param.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::param(n) 1 tcllib "Parser Tools")
# NAME
pt::param - PackRat Machine Specification
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Architectural State](#section2)
- [Instruction Set](#section3)
- [Input Handling](#subsection1)
- [Character Processing](#subsection2)
- [Error Handling](#subsection3)
- [Status Control](#subsection4)
- [Location Handling](#subsection5)
- [Nonterminal Execution](#subsection6)
- [Value Construction](#subsection7)
- [AST Construction](#subsection8)
- [Control Flow](#subsection9)
- [Interaction of the Instructions with the Architectural State](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
Welcome to the PackRat Machine (short: *[PARAM](../../../../index.md#param)*), a
virtual machine geared towards the support of recursive descent parsers,
especially packrat parsers. Towards this end it has features like the caching
and reuse of partial results, the caching of the encountered input, and the
ability to backtrack in both input and AST creation.
This document specifies the machine in terms of its architectural state and
instruction set.
# <a name='section2'></a>Architectural State
Any PARAM implementation has to manage at least the following state:
- *Input* (IN)
This is the channel the characters to process are read from.
This part of the machine's state is used and modified by the instructions
defined in the section [Input Handling](#subsection1).
- *Current Character* (CC)
The character from the *input* currently tested against its possible
alternatives.
This part of the machine's state is used and modified by the instructions
defined in the section [Character Processing](#subsection2).
- *Current Location* (CL)
The location of the *current character* in the *input*, as offset relative
to the beginning of the input. Character offsets are counted from __0__.
This part of the machine's state is used and modified by the instructions
defined in the sections [Character Processing](#subsection2), [Location
Handling](#subsection5), and [Nonterminal Execution](#subsection6).
- *Location Stack* (LS)
A stack of locations in the *input*, saved for possible backtracking.
This part of the machine's state is used and modified by the instructions
defined in the sections [Character Processing](#subsection2), [Location
Handling](#subsection5), and [Nonterminal Execution](#subsection6).
- *Status* (ST)
The status of the last attempt of testing the *input*, indicating either
success or failure.
This part of the machine's state is used and modified by the instructions
defined in the sections [Status Control](#subsection4), [Character
Processing](#subsection2), and [Nonterminal Execution](#subsection6).
- *Semantic Value* (SV)
The current semantic value, either empty, or a node for AST constructed from
the input.
This part of the machine's state is used and modified by the instructions
defined in the sections [Value Construction](#subsection7), and [AST
Construction](#subsection8).
- *AST Reduction Stack* (ARS)
The stack of partial ASTs constructed during the processing of nonterminal
symbols.
This part of the machine's state is used and modified by the instructions
defined in the sections [Value Construction](#subsection7), and [AST
Construction](#subsection8).
- *AST Stack* (AS)
The stack of reduction stacks, saved for possible backtracking.
This part of the machine's state is used and modified by the instructions
defined in the sections [Value Construction](#subsection7), and [AST
Construction](#subsection8).
- *Error Status* (ER)
The machine's current knowledge of errors. This is either empty, or set to a
pair of location in the input and the set of messages for that location.
*Note* that this part of the machine's state can be set even if the last
test of the *current character* was successful. For example, the *-operator
(matching a sub-expression zero or more times) in a PEG is always
successful, even if it encounters a problem further in the input and has to
backtrack. Such problems must not be forgotten when continuing the parsing.
This part of the machine's state is used and modified by the instructions
defined in the sections [Error Handling](#subsection3), [Character
Processing](#subsection2), and [Nonterminal Execution](#subsection6).
- *Error Stack* (ES)
The stack of error stati, saved for backtracking. This enables the machine
to merge current and older error stati when performing backtracking in
choices after an failed match.
This part of the machine's state is used and modified by the instructions
defined in the sections [Error Handling](#subsection3), [Character
Processing](#subsection2), and [Nonterminal Execution](#subsection6).
- *Nonterminal Cache* (NC)
A cache of machine states keyed by pairs name of nonterminal symbol and
location in the input. Each pair (N, L) is associated with a 4-tuple holding
the values to use for CL, ST, SV, and ER after the nonterminal N was parsed
starting from the location L. It is a performance aid for backtracking
parsers, allowing them to avoid an expensive reparsing of complex
nonterminal symbols if they have been encountered before at a given
location.
The key location is where machine started the attempt to match the named
nonterminal symbol, and the location in the saved 4-tuple is where machine
ended up after the attempt completed, independent of the success of the
attempt.
This part of the machine's state is used and modified by the instructions
defined in the section [Nonterminal Execution](#subsection6).
- *Terminal Cache* (TC)
A cache of characters read from IN, with their location in IN as pair of
line and column, keyed by the location in IN, this time as character offset
from the beginning of IN. It is a performance aid for backtracking parsers,
allowing them to avoid a possibly expensive rereading of characters from IN,
or even enabling backtracking at, i.e. in the case of IN not randomly
seekable.
This part of the machine's state is used and modified by the instructions
defined in the section [Input Handling](#subsection1).
# <a name='section3'></a>Instruction Set
With the machine's architectural state specified it is now possible to specify
the instruction set operating on that state and to be implemented by any
realization of the PARAM. The 37 instructions are grouped roughly by the state
they influence and/or query during their execution.
## <a name='subsection1'></a>Input Handling
The instructions in this section mainly access IN, pulling the characters to
process into the machine.
- __input_next__ *msg*
This method reads the next character, i.e. the character after CL, from IN.
If successful this character becomes CC, CL is advanced by one, ES is
cleared, and the operation is recorded as a success in ST.
The operation may read the character from IN if the next character is not
yet known to TC. If successful the new character is stored in TC, with its
location (line, column), and the operation otherwise behaves as specified
above. Future reads from the same location, possible due to backtracking,
will then be satisfied from TC instead of IN.
If, on the other hand, the end of IN was reached, the operation is recorded
as failed in ST, CL is left unchanged, and the pair of CL and *msg* becomes
the new ES.
## <a name='subsection2'></a>Character Processing
The instructions in this section mainly access CC, testing it against character
classes, ranges, and individual characters.
- __test_alnum__
This instruction implements the special PE operator "alnum", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_alpha__
This instruction implements the special PE operator "alpha", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_ascii__
This instruction implements the special PE operator "ascii", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_char__ *char*
This instruction implements the character matching operator, i.e. it checks
if CC is *char*.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_ddigit__
This instruction implements the special PE operator "ddigit", which checks
if CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_digit__
This instruction implements the special PE operator "digit", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_graph__
This instruction implements the special PE operator "graph", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_lower__
This instruction implements the special PE operator "lower", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_print__
This instruction implements the special PE operator "print", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_punct__
This instruction implements the special PE operator "punct", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_range__ *chars* *chare*
This instruction implements the range matching operator, i.e. it checks if
CC falls into the interval of characters spanned up by the two characters
from *chars* to *chare*, both inclusive.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_space__
This instruction implements the special PE operator "space", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_upper__
This instruction implements the special PE operator "upper", which checks if
CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_wordchar__
This instruction implements the special PE operator "wordchar", which checks
if CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
- __test_xdigit__
This instruction implements the special PE operator "xdigit", which checks
if CC falls into the character class of the same name, or not.
Success and failure of the test are both recorded directly in ST. Success
further clears ES, wheras failure sets the pair of CL and expected input
(encoded as a leaf parsing expression) as the new ES and then rewinds CL by
one character, preparing the machine for another parse attempt by a possible
alternative.
## <a name='subsection3'></a>Error Handling
The instructions in this section mainly access ER and ES.
- __error_clear__
This instruction clears ER.
- __error_push__
This instruction makes a copy of ER and pushes it on ES.
- __error_pop_merge__
This instruction takes the topmost entry of ES and merges the error status
it contains with ES, making the result the new ES.
The merge is governed by four rules, with the merge result
Empty if both states are empty.
The non-empty state if only one of the two states is non-empty.
The state with the larger location, if the two states specify different
locations.
The pair of the location shared by the two states, and the set-union of
their messages for states at the same location.
- __error_nonterminal__ *symbol*
This is a guarded instruction. It does nothing if either ES is empty, or if
the location in ES is not just past the last location saved in LS. Otherwise
it sets the pair of that location and the nonterminal *symbol* as the new
ES.
*Note*: In the above "just past" means "that location plus one", or also
"the location of the next character after that location".
## <a name='subsection4'></a>Status Control
The instructions in this section directly manipulate ST.
- __status_ok__
This instruction sets ST to __true__, recording a success.
- __status_fail__
This instruction sets ST to __false__, recording a failure.
- __status_negate__
This instruction negates ST, turning a failure into a success and vice
versa.
## <a name='subsection5'></a>Location Handling
The instructions in this section access CL and LS.
- __loc_push__
This instruction makes a copy of CL and pushes it on LS.
- __loc_pop_discard__
This instructions pops the last saved location from LS.
- __loc_pop_rewind__
This instruction pops the last saved location from LS and restores it as CL.
## <a name='subsection6'></a>Nonterminal Execution
The instructions in this section access and manipulate NC.
- __symbol_restore__ *symbol*
This instruction checks if NC contains data for the nonterminal *symbol* at
CL, or not. The result of the instruction is a boolean flag, with __True__
indicating that data was found in the cache. In that case the instruction
has further updated the architectural state of the machine with the cached
information, namely CL, ST, ER, and SV.
The method with which the instruction's result is transformed into control
flow is left undefined and the responsibility of the implementation.
- __symbol_save__ *symbol*
This instructions saves the current settings of CL, ST, ER, and SV in NC,
using the pair of nonterminal *symbol* and the last location saved in LS as
key.
## <a name='subsection7'></a>Value Construction
The instructions in this section manipulate SV.
- __value_clear__
This instruction clears SV.
- __value_leaf__ *symbol*
This instruction constructs an AST node for *symbol* covering the range of
IN from one character after the last location saved on LS to CL and stores
it in SV. ...
- __value_reduce__ *symbol*
This instruction generally behaves like __value_nonterminal_leaf__, except
that it takes all AST nodes on ARS, if any, and makes them the children of
the new node, with the last node saved on ARS becoming the right-most / last
child. Note that ARS is not modfied by this operation.
## <a name='subsection8'></a>AST Construction
The instructions in this section manipulate ARS and AS.
- __ast_value_push__
This instruction makes a copy of SV and pushes it on ARS.
- __ast_push__
This instruction pushes the current state of ARS on AS and then clears ARS.
- __ast_pop_rewind__
This instruction pops the last entry saved on AS and restores it as the new
state of ARS.
- __ast_pop_discard__
This instruction pops the last entry saved on AS.
## <a name='subsection9'></a>Control Flow
Normally this section would contain the specifications of the control flow
instructions of the PARAM, i.e. (un)conditional jumps and the like. However,
this part of the PARAM is intentionally left unspecified. This allows the
implementations to freely choose how to implement control flow.
The implementation of this machine in Parser Tools, i.e the package
__[pt::rde](pt_rdengine.md)__, is not only coded in Tcl, but also relies on Tcl
commands to provide it with control flow (instructions).
# <a name='section4'></a>Interaction of the Instructions with the Architectural State
Instruction Inputs Outputs
======================= ======================= ====================
ast_pop_discard AS -> AS
ast_pop_rewind AS -> AS, ARS
ast_push ARS, AS -> AS
ast_value_push SV, ARS -> ARS
======================= ======================= ====================
error_clear - -> ER
error_nonterminal sym ER, LS -> ER
error_pop_merge ES, ER -> ER
error_push ES, ER -> ES
======================= ======================= ====================
input_next msg IN -> TC, CL, CC, ST, ER
======================= ======================= ====================
loc_pop_discard LS -> LS
loc_pop_rewind LS -> LS, CL
loc_push CL, LS -> LS
======================= ======================= ====================
status_fail - -> ST
status_negate ST -> ST
status_ok - -> ST
======================= ======================= ====================
symbol_restore sym NC -> CL, ST, ER, SV
symbol_save sym CL, ST, ER, SV LS -> NC
======================= ======================= ====================
test_alnum CC -> ST, ER
test_alpha CC -> ST, ER
test_ascii CC -> ST, ER
test_char char CC -> ST, ER
test_ddigit CC -> ST, ER
test_digit CC -> ST, ER
test_graph CC -> ST, ER
test_lower CC -> ST, ER
test_print CC -> ST, ER
test_punct CC -> ST, ER
test_range chars chare CC -> ST, ER
test_space CC -> ST, ER
test_upper CC -> ST, ER
test_wordchar CC -> ST, ER
test_xdigit CC -> ST, ER
======================= ======================= ====================
value_clear - -> SV
value_leaf symbol LS, CL -> SV
value_reduce symbol ARS, LS, CL -> SV
======================= ======================= ====================
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer), [virtual
machine](../../../../index.md#virtual_machine)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_parse_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
[//000000001]: # (pt_parse_peg - Parser Tools)
[//000000002]: # (Generated from file 'pt_parse_peg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt_parse_peg(i) 1 tcllib "Parser Tools")
# NAME
pt_parse_peg - Parser Tools PEG Parser
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Instances API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::parse::peg 1
[__pt::parse::peg__ ?*objectName*?](#1)
[*objectName* __destroy__](#2)
[*objectName* __parse__ *chan*](#3)
[*objectName* __parset__ *text*](#4)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a class whose instances are parsers for parsing expression
grammars in textual form.
# <a name='section2'></a>Class API
- <a name='1'></a>__pt::parse::peg__ ?*objectName*?
The class command constructs parser instances, i.e. objects. The result of
the command is the fully-qualified name of the instance command.
If no *objectName* is specified the class will generate and use an automatic
name. If the *objectName* was specified, but is not fully qualified the
command will be created in the current namespace.
# <a name='section3'></a>Instances API
All parser instances provide at least the methods shown below:
- <a name='2'></a>*objectName* __destroy__
This method destroys the parser instance, releasing all claimed memory and
other resources, and deleting the instance command.
The result of the command is the empty string.
- <a name='3'></a>*objectName* __parse__ *chan*
This method runs the parser using the contents of *chan* as input (starting
at the current location in the channel), until parsing is not possible
anymore, either because parsing has completed, or run into a syntax error.
Note here that the Parser Tools are based on Tcl 8.5+. In other words, the
channel argument is not restricted to files, sockets, etc. We have the full
power of *reflected channels* available.
It should also be noted that the parser pulls the characters from the input
stream as it needs them. If a parser created by this package has to be
operated in a push aka event-driven manner it will be necessary to go to Tcl
8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it
into a coroutine where __[read](../../../../index.md#read)__ is properly
changed for push-operation.
Upon successful completion the command returns an abstract syntax tree as
its result. This AST is in the form specified in section __AST serialization
format__. As a plain nested Tcl-list it can then be processed with any Tcl
commands the user likes, doing transformations, semantic checks, etc. To
help in this the package __[pt::ast](pt_astree.md)__ provides a set of
convenience commands for validation of the tree's basic structure, printing
it for debugging, and walking it either from the bottom up, or top down.
When encountering a syntax error the command will throw an error instead.
This error will be a 4-element Tcl-list, containing, in the order listed
below:
The string __pt::rde__ identifying it as parser runtime error.
The location of the parse error, as character offset from the beginning of
the parsed input.
The location of parse error, now as a 2-element list containing line-number
and column in the line.
A set of atomic parsing expressions indicating encoding the characters
and/or nonterminal symbols the parser expected to see at the location of the
parse error, but did not get. For the specification of atomic parsing
expressions please see the section __PE serialization format__.
- <a name='4'></a>*objectName* __parset__ *text*
This method runs the parser using the string in *text* as input. In all
other ways it behaves like the method __parse__, shown above.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_parser_api.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
|
[//000000001]: # (pt_parser_api - Parser Tools)
[//000000002]: # (Generated from file 'pt_parser_api.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt_parser_api(i) 1 tcllib "Parser Tools")
# NAME
pt_parser_api - Parser API
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Instance API](#section3)
- [Usage](#section4)
- [AST serialization format](#section5)
- [Example](#subsection1)
- [PE serialization format](#section6)
- [Example](#subsection2)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
[__className__ ?*objectName*?](#1)
[*objectName* __destroy__](#2)
[*objectName* __parse__ *chan*](#3)
[*objectName* __parset__ *text*](#4)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This document describes the API shared by the grammar interpreter provided by
the package __[pt::peg::interp](pt_peg_interp.md)__ and the parsers generated by
the __[pt](../../apps/pt.md)__ application for the result formats __critcl__,
__snit__, and __oo__ regarding access to the actual parsing functionality.
Its intended audience are people who wish to create a parser for some language
of theirs and then use that parser within a Tcl-based package or application.
It resides in the User Layer of Parser Tools.
# <a name='section2'></a>Class API
- <a name='1'></a>__className__ ?*objectName*?
The class command constructs parser instances, i.e. objects. The result of
the command is the fully-qualified name of the instance command.
If no *objectName* is specified the class will generate and use an automatic
name. If the *objectName* was specified, but is not fully qualified the
command will be created in the current namespace.
# <a name='section3'></a>Instance API
All parser instances provide at least the methods shown below:
- <a name='2'></a>*objectName* __destroy__
This method destroys the parser instance, releasing all claimed memory and
other resources, and deleting the instance command.
The result of the command is the empty string.
- <a name='3'></a>*objectName* __parse__ *chan*
This method runs the parser using the contents of *chan* as input (starting
at the current location in the channel), until parsing is not possible
anymore, either because parsing has completed, or run into a syntax error.
Note here that the Parser Tools are based on Tcl 8.5+. In other words, the
channel argument is not restricted to files, sockets, etc. We have the full
power of *reflected channels* available.
It should also be noted that the parser pulls the characters from the input
stream as it needs them. If a parser created by this package has to be
operated in a push aka event-driven manner it will be necessary to go to Tcl
8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it
into a coroutine where __[read](../../../../index.md#read)__ is properly
changed for push-operation.
Upon successful completion the command returns an abstract syntax tree as
its result. This AST is in the form specified in section [AST serialization
format](#section5). As a plain nested Tcl-list it can then be processed with
any Tcl commands the user likes, doing transformations, semantic checks,
etc. To help in this the package __[pt::ast](pt_astree.md)__ provides a set
of convenience commands for validation of the tree's basic structure,
printing it for debugging, and walking it either from the bottom up, or top
down.
When encountering a syntax error the command will throw an error instead.
This error will be a 4-element Tcl-list, containing, in the order listed
below:
The string __pt::rde__ identifying it as parser runtime error.
The location of the parse error, as character offset from the beginning of
the parsed input.
The location of parse error, now as a 2-element list containing line-number
and column in the line.
A set of atomic parsing expressions indicating encoding the characters
and/or nonterminal symbols the parser expected to see at the location of the
parse error, but did not get. For the specification of atomic parsing
expressions please see the section [PE serialization format](#section6).
- <a name='4'></a>*objectName* __parset__ *text*
This method runs the parser using the string in *text* as input. In all
other ways it behaves like the method __parse__, shown above.
# <a name='section4'></a>Usage
A generated parser is used like this
package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'.
set parser [the-parser-class]
set ast [$parser parse $channel]
... process the abstract syntax tree ...
When using a grammar interpreter for parsing some differences creep in
package require the-grammar-package ;# Generated by result-format 'container' of 'pt'.
set grammar [the-grammar-class]
package require pt::peg::interp
set parser [pt::peg::interp]
$parser use $grammar
set ast [$parser parse $channel]
$parser destroy
... process the abstract syntax tree ...
# <a name='section5'></a>AST serialization format
Here we specify the format used by the Parser Tools to serialize Abstract Syntax
Trees (ASTs) as immutable values for transport, comparison, etc.
Each node in an AST represents a nonterminal symbol of a grammar, and the range
of tokens/characters in the input covered by it. ASTs do not contain terminal
symbols, i.e. tokens/characters. These can be recovered from the input given a
symbol's location.
We distinguish between *regular* and *canonical* serializations. While a tree
may have more than one regular serialization only exactly one of them will be
*canonical*.
- Regular serialization
The serialization of any AST is the serialization of its root node.
The serialization of any node is a Tcl list containing at least three
elements.
The first element is the name of the nonterminal symbol stored in the node.
The second and third element are the locations of the first and last token
in the token stream the node represents (covers).
Locations are provided as non-negative integer offsets from the beginning of
the token stream, with the first token found in the stream located at offset
0 (zero).
The end location has to be equal to or larger than the start location.
All elements after the first three represent the children of the node, which
are themselves nodes. This means that the serializations of nodes without
children, i.e. leaf nodes, have exactly three elements. The children are
stored in the list with the leftmost child first, and the rightmost child
last.
- Canonical serialization
The canonical serialization of an abstract syntax tree has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this tree.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
## <a name='subsection1'></a>Example
Assuming the parsing expression grammar below
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
and the input string
120+5
then a parser should deliver the abstract syntax tree below (except for
whitespace)
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
Or, more graphical
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection2'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
|
[//000000001]: # (pt::peg::container - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_container.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::container(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::container - PEG Storage
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#subsection1)
- [Object API](#subsection2)
- [PEG serialization format](#section2)
- [Example](#subsection3)
- [PE serialization format](#section3)
- [Example](#subsection4)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit
package require pt::peg::container ?1?
[__::pt::peg__ *objectName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*?](#1)
[*objectName* __destroy__](#2)
[*objectName* __clear__](#3)
[*objectName* __importer__](#4)
[*objectName* __importer__ *object*](#5)
[*objectName* __exporter__](#6)
[*objectName* __exporter__ *object*](#7)
[*objectName* __=__ *source*](#8)
[*objectName* __-->__ *destination*](#9)
[*objectName* __serialize__ ?*format*?](#10)
[*objectName* __deserialize =__ *data* ?*format*?](#11)
[*objectName* __deserialize +=__ *data* ?*format*?](#12)
[*objectName* __start__](#13)
[*objectName* __start__ *pe*](#14)
[*objectName* __nonterminals__](#15)
[*objectName* __modes__](#16)
[*objectName* __modes__ *dict*](#17)
[*objectName* __rules__](#18)
[*objectName* __rules__ *dict*](#19)
[*objectName* __add__ ?*nt*...?](#20)
[*objectName* __remove__ ?*nt*...?](#21)
[*objectName* __exists__ *nt*](#22)
[*objectName* __rename__ *ntold* *ntnew*](#23)
[*objectName* __mode__ *nt*](#24)
[*objectName* __mode__ *nt* *mode*](#25)
[*objectName* __rule__ *nt*](#26)
[*objectName* __rule__ *nt* *pe*](#27)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a container class for parsing expression grammars, with
each instance storing a single grammar and allowing the user to manipulate and
query its definition.
It resides in the Storage section of the Core Layer of Parser Tools, and is one
of the three pillars the management of parsing expression grammars resides on.
 The other two pillars are, as
shown above
1. *[PEG Import](pt_peg_import.md)*, and
1. *[PEG Export](pt_peg_export.md)*
Packages related to this are:
- __[pt::rde](pt_rdengine.md)__
This package provides an implementation of PARAM, a virtual machine for the
parsing of a channel, geared towards the needs of handling PEGs.
- __[pt::peg::interp](pt_peg_interp.md)__
This package implements an interpreter for PEGs on top of the virtual
machine provided by __pt::peg::rde__
## <a name='subsection1'></a>Class API
The package exports the API described here.
- <a name='1'></a>__::pt::peg__ *objectName* ?__=__|__:=__|__<--__|__as__|__deserialize__ *src*?
The command creates a new container object for a parsing expression grammar
and returns the fully qualified name of the object command as its result.
The API of this object command is described in the section [Object
API](#subsection2). It may be used to invoke various operations on the
object.
The new container will be empty if no *src* is specified. Otherwise it will
contain a copy of the grammar contained in the *src*. All operators except
__deserialize__ interpret *src* as a container object command. The
__deserialize__ operator interprets *src* as the serialization of a parsing
expression grammar instead, as specified in section [PEG serialization
format](#section2).
An empty grammar has no nonterminal symbols, and the start expression is the
empty expression, i.e. epsilon. It is *valid*, but not *useful*.
## <a name='subsection2'></a>Object API
All objects created by this package provide the following methods for the
manipulation and querying of their contents:
- <a name='2'></a>*objectName* __destroy__
This method destroys the object, releasing all claimed memory, and deleting
the associated object command.
- <a name='3'></a>*objectName* __clear__
This method resets the object to contain the empty grammar. It does *not*
destroy the object itself.
- <a name='4'></a>*objectName* __importer__
This method returns the import manager object currently attached to the
container, if any.
- <a name='5'></a>*objectName* __importer__ *object*
This method attaches the *object* as import manager to the container, and
returns it as the result of the command. Note that the *object* is *not* put
into ownership of the container. I.e., destruction of the container will
*not* destroy the *object*.
It is expected that *object* provides a method named __import text__ which
takes a text and a format name, and returns the canonical serialization of
the table of contents contained in the text, assuming the given format.
- <a name='6'></a>*objectName* __exporter__
This method returns the export manager object currently attached to the
container, if any.
- <a name='7'></a>*objectName* __exporter__ *object*
This method attaches the *object* as export manager to the container, and
returns it as the result of the command. Note that the *object* is *not* put
into ownership of the container. I.e., destruction of the container will
*not* destroy the *object*.
It is expected that *object* provides a method named __export object__ which
takes the container and a format name, and returns a text encoding table of
contents stored in the container, in the given format. It is further
expected that the *object* will use the container's method __serialize__ to
obtain the serialization of the table of contents from which to generate the
text.
- <a name='8'></a>*objectName* __=__ *source*
This method assigns the contents of the PEG object *source* to ourselves,
overwriting the existing definition. This is the assignment operator for
grammars.
This operation is in effect equivalent to
*objectName* __deserialize =__ [*source* __serialize__]
- <a name='9'></a>*objectName* __-->__ *destination*
This method assigns our contents to the PEG object *destination*,
overwriting the existing definition. This is the reverse assignment operator
for grammars.
This operation is in effect equivalent to
*destination* __deserialize =__ [*objectName* __serialize__]
- <a name='10'></a>*objectName* __serialize__ ?*format*?
This method returns our grammar in some textual form usable for transfer,
persistent storage, etc. If no *format* is not specified the returned result
is the canonical serialization of the grammar, as specified in the section
[PEG serialization format](#section2).
Otherwise the object will use the attached export manager to convert the
data to the specified format. In that case the method will fail with an
error if the container has no export manager attached to it.
- <a name='11'></a>*objectName* __deserialize =__ *data* ?*format*?
This is the complementary method to __serialize__. It replaces the current
definition with the grammar contained in the *data*. If no *format* was
specified it is assumed to be the regular serialization of a grammar, as
specified in the section [PEG serialization format](#section2)
Otherwise the object will use the attached import manager to convert the
data from the specified format to a serialization it can handle. In that
case the method will fail with an error if the container has no import
manager attached to it.
The result of the method is the empty string.
- <a name='12'></a>*objectName* __deserialize +=__ *data* ?*format*?
This method behaves like __deserialize =__ in its essentials, except that it
merges the grammar in the *data* to its contents instead of replacing it.
The method will fail with an error and leave the grammar unchanged if
merging is not possible, i.e. would produce an invalid grammar.
The result of the method is the empty string.
- <a name='13'></a>*objectName* __start__
This method returns the current start expression of the grammar.
- <a name='14'></a>*objectName* __start__ *pe*
This method defines the *start expression* of the grammar. It replaces the
current start expression with the parsing expression *pe*, and returns the
new start expression.
The method will fail with an error and leave the grammar unchanged if *pe*
does not contain a valid parsing expression as specified in the section [PE
serialization format](#section3).
- <a name='15'></a>*objectName* __nonterminals__
This method returns the set of all nonterminal symbols known to the grammar.
- <a name='16'></a>*objectName* __modes__
This method returns a dictionary mapping the set of all nonterminal symbols
known to the grammar to their semantic modes.
- <a name='17'></a>*objectName* __modes__ *dict*
This method takes a dictionary mapping a set of nonterminal symbols known to
the grammar to their semantic modes, and returns the new full mapping of
nonterminal symbols to semantic modes.
The method will fail with an error if any of the nonterminal symbols in the
dictionary is not known to the grammar, or the empty string, i.e. an invalid
nonterminal symbol, or if any the chosen *mode*s is not one of the legal
values.
- <a name='18'></a>*objectName* __rules__
This method returns a dictionary mapping the set of all nonterminal symbols
known to the grammar to their parsing expressions (right-hand sides).
- <a name='19'></a>*objectName* __rules__ *dict*
This method takes a dictionary mapping a set of nonterminal symbols known to
the grammar to their parsing expressions (right-hand sides), and returns the
new full mapping of nonterminal symbols to parsing expressions.
The method will fail with an error any of the nonterminal symbols in the
dictionary is not known to the grammar, or the empty string, i.e. an invalid
nonterminal symbol, or any of the chosen parsing expressions is not a valid
parsing expression as specified in the section [PE serialization
format](#section3).
- <a name='20'></a>*objectName* __add__ ?*nt*...?
This method adds the nonterminal symbols *nt*, etc. to the grammar, and
defines default semantic mode and expression for it (__value__ and
__epsilon__ respectively). The method returns the empty string as its
result.
The method will fail with an error and leaves the grammar unchanged if any
of the nonterminal symbols are either already defined in our grammar, or are
the empty string (an invalid nonterminal symbol).
The method does nothing if no symbol was specified as argument.
- <a name='21'></a>*objectName* __remove__ ?*nt*...?
This method removes the named nonterminal symbols *nt*, etc. from the set of
nonterminal symbols known to our grammar. The method returns the empty
string as its result.
The method will fail with an error and leave the grammar unchanged if any of
the nonterminal symbols is not known to the grammar, or is the empty string,
i.e. an invalid nonterminal symbol.
- <a name='22'></a>*objectName* __exists__ *nt*
This method tests whether the nonterminal symbol *nt* is known to our
grammar or not. The result is a boolean value. It will be set to __true__ if
*nt* is known, and __false__ otherwise.
The method will fail with an error if *nt* is the empty string, i.e. an
invalid nonterminal symbol.
- <a name='23'></a>*objectName* __rename__ *ntold* *ntnew*
This method renames the nonterminal symbol *ntold* to *ntnew*. The method
returns the empty string as its result.
The method will fail with an error and leave the grammar unchanged if either
*ntold* is not known to the grammar, or *ntnew* is already known, or any of
them is the empty string, i.e. an invalid nonterminal symbol.
- <a name='24'></a>*objectName* __mode__ *nt*
This method returns the current semantic mode for the nonterminal symbol
*nt*.
The method will fail with an error if *nt* is not known to the grammar, or
the empty string, i.e. an invalid nonterminal symbol.
- <a name='25'></a>*objectName* __mode__ *nt* *mode*
This mode sets the semantic mode for the nonterminal symbol *nt*, and
returns the new mode. The method will fail with an error if *nt* is not
known to the grammar, or the empty string, i.e. an invalid nonterminal
symbol, or the chosen *mode* is not one of the legal values.
The following modes are legal:
* __value__
The semantic value of the nonterminal symbol is an abstract syntax tree
consisting of a single node node for the nonterminal itself, which has
the ASTs of the symbol's right hand side as its children.
* __leaf__
The semantic value of the nonterminal symbol is an abstract syntax tree
consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.
* __void__
The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).
- <a name='26'></a>*objectName* __rule__ *nt*
This method returns the current parsing expression (right-hand side) for the
nonterminal symbol *nt*.
The method will fail with an error if *nt* is not known to the grammar, or
the empty string, i.e. an invalid nonterminal symbol.
- <a name='27'></a>*objectName* __rule__ *nt* *pe*
This method set the parsing expression (right-hand side) of the nonterminal
*nt* to *pe*, and returns the new parsing expression.
The method will fail with an error if *nt* is not known to the grammar, or
the empty string, i.e. an invalid nonterminal symbol, or *pe* does not
contain a valid parsing expression as specified in the section [PE
serialization format](#section3).
# <a name='section2'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section3).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section3).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection3'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section3'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection4'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
[//000000001]: # (pt::peg::container::peg - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_container_peg.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::container::peg(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::container::peg - PEG Storage. Canned PEG grammar specification
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit
package require pt::peg::container::peg ?1?
package require pt::peg::container
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a sub-type of
__[pt::peg::container](pt_peg_container.md)__ which is preloaded with a parsing
expression grammar describing a textual format for parsing expression grammars.
The sub-type provides the exact same API as
__[pt::peg::container](pt_peg_container.md)__. Instead of duplicating its
contents the reader is asked to read the referenced document.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_export.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
|
[//000000001]: # (pt::peg::export - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_export.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::export(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::export - PEG Export
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [PEG serialization format](#section3)
- [Example](#subsection4)
- [PE serialization format](#section4)
- [Example](#subsection5)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit
package require configuration
package require pt::peg
package require pluginmgr
package require pt::peg::export ?1?
[__::pt::peg::export__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __export serial__ *serial* ?*format*?](#4)
[*objectName* __export object__ *object* ?*format*?](#5)
[*objectName* __configuration names__](#6)
[*objectName* __configuration get__](#7)
[*objectName* __configuration set__ *name* ?*value*?](#8)
[*objectName* __configuration unset__ *pattern*...](#9)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a manager for parsing expression grammars, with each
instance handling a set of plugins for the export of them to other formats, i.e.
their conversion to, for example *[nroff](../../../../index.md#nroff)*,
*[HTML](../../../../index.md#html)*, etc.
It resides in the Export section of the Core Layer of Parser Tools, and is one
of the three pillars the management of parsing expression grammars resides on.
 The other two pillars are, as shown
above
1. *[PEG Import](pt_peg_import.md)*, and
1. *[PEG Storage](pt_peg_container.md)*
For information about the data structure which is the major input to the manager
objects provided by this package see the section [PEG serialization
format](#section3).
The plugin system of this class is based on the package
__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins
using
1. the environment variable __GRAMMAR_PEG_EXPORT_PLUGINS__,
1. the environment variable __GRAMMAR_PEG_PLUGINS__,
1. the environment variable __GRAMMAR_PLUGINS__,
1. the path "~/.grammar/peg/export/plugin"
1. the path "~/.grammar/peg/plugin"
1. the path "~/.grammar/plugin"
1. the path "~/.grammar/peg/export/plugins"
1. the path "~/.grammar/peg/plugins"
1. the path "~/.grammar/plugins"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\EXPORT\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"
The last three are used only when the package is run on a machine using the
Windows(tm) operating system.
The whole system is delivered with three predefined export plugins, namely
- container
See *PEG Export Plugin. To CONTAINER format* for details.
- json
See *PEG Export Plugin. To JSON format* for details.
- peg
See *PEG Export Plugin. To PEG format* for details.
For readers wishing to write their own export plugin for some format, i.e.
*plugin writer*s, reading and understanding the *[Parser Tools Export
API](pt_to_api.md)* specification is an absolute necessity, as it documents the
interaction between this package and its plugins in detail.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::pt::peg::export__ *objectName*
This command creates a new export manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::pt::peg::export__ command have the following
general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __export serial__ *serial* ?*format*?
This method takes the canonical serialization of a parsing expression
grammar stored in *serial* and converts it to the specified *format*, using
the export plugin for the format. This will fail with an error if no plugin
could be found for the format. The string generated by the conversion
process is returned as the result of this method.
If no format is specified the method defaults to __text__.
The specification of what a *canonical* serialization is can be found in the
section [PEG serialization format](#section3).
The plugin has to conform to the interface documented in the *[Parser Tools
Export API](pt_to_api.md)* specification.
- <a name='5'></a>*objectName* __export object__ *object* ?*format*?
This method is a convenient wrapper around the __export serial__ method
described by the previous item. It expects that *object* is an object
command supporting a __serialize__ method returning the canonical
serialization of a parsing expression grammar. It invokes that method, feeds
the result into __export serial__ and returns the resulting string as its
own result.
- <a name='6'></a>*objectName* __configuration names__
This method returns a list containing the names of all configuration options
currently known to the object.
- <a name='7'></a>*objectName* __configuration get__
This method returns a dictionary containing the names and values of all
configuration options currently known to the object.
- <a name='8'></a>*objectName* __configuration set__ *name* ?*value*?
This method sets the configuration option *name* to the specified *value*
and returns the new value of the option.
If no value is specified it simply returns the current value, without
changing it.
Note that these configuration options and their values are simply passed to
a plugin when the actual export is performed. It is the plugin which checks
the validity, not the manager.
- <a name='9'></a>*objectName* __configuration unset__ *pattern*...
This method unsets all configuration options matching the specified glob
*pattern*s. If no pattern is specified it will unset all currently defined
configuration options.
# <a name='section3'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section4).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section4).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection4'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section4'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection5'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
|
[//000000001]: # (pt::peg::export::container - Parser Tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::export::container(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::export::container - PEG Export Plugin. Write CONTAINER format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [Grammar Container](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::export::container ?1?
package require pt::peg::to::container
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the parsing expression grammar export plugin for the
generation of CONTAINER markup.
It resides in the Export section of the Core Layer of Parser Tools and is
intended to be used by __[pt::peg::export](pt_peg_export.md)__, the export
manager, sitting between it and the corresponding core conversion functionality
provided by __[pt::peg::to::container](pt_peg_to_container.md)__.
While the direct use of this package with a regular interpreter is possible,
this is strongly disrecommended and requires a number of contortions to provide
the expected environment. The proper way to use this functionality depends on
the situation:
1. In an untrusted environment the proper access is through the package
__[pt::peg::export](pt_peg_export.md)__ and the export manager objects it
provides.
1. In a trusted environment however simply use the package
__[pt::peg::to::container](pt_peg_to_container.md)__ and access the core
conversion functionality directly.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Plugin API
found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, the *configuration*, a dictionary, and generates
CONTAINER markup encoding the grammar. The created string is then returned
as the result of the command.
# <a name='section3'></a>Configuration
The CONTAINER export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- enum *mode*
The value of this configuration variable controls which methods of
__[pt::peg](pt_pegrammar.md)__ instances the plugin will use to specify the
grammar. There are two legal values
* __bulk__
In this mode the methods __start__, __add__, __modes__, and __rules__
are used to specify the grammar in a bulk manner, i.e. as a set of
nonterminal symbols, and two dictionaries mapping from the symbols to
their semantic modes and parsing expressions.
This mode is the default.
* __incremental__
In this mode the methods __start__, __add__, __mode__, and __rule__ are
used to specify the grammar piecemal, with each nonterminal having its
own block of defining commands.
- string *template*
If this configuration variable is set it is assumed to contain a string into
which to put the generated code and other configuration data. The various
locations are expected to be specified with the following placeholders:
* __@user@__
To be replaced with the value of the configuration variable __user__.
* __@format@__
To be replaced with the the constant __CONTAINER__.
* __@file@__
To be replaced with the value of the configuration variable __file__.
* __@name@__
To be replaced with the value of the configuration variable __name__.
* __@mode@__
To be replaced with the value of the configuration variable __mode__.
* __@code@__
To be replaced with the generated code.
If this configuration variable is not set, or empty, then the plugin falls
back to a standard template, which is defined as "__@code@__".
*Note* that this plugin may ignore the standard configuration variables
__user__, __format__, __file__, and their values, depending on the chosen
template.
The content of the standard configuration variable __name__, if set, is used as
name of the grammar in the output. Otherwise the plugin falls back to the
default name __a_pe_grammar__.
# <a name='section4'></a>Grammar Container
The __container__ format is another form of describing parsing expression
grammars. While data in this format is executable it does not constitute a
parser for the grammar. It always has to be used in conjunction with the package
__[pt::peg::interp](pt_peg_interp.md)__, a grammar interpreter.
The format represents grammars by a __snit::type__, i.e. class, whose instances
are API-compatible to the instances of the
__[pt::peg::container](pt_peg_container.md)__ package, and which are preloaded
with the grammar in question.
It has no direct formal specification beyond what was said above.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
one possible CONTAINER serialization for it is
snit::type a_pe_grammar {
constructor {} {
install myg using pt::peg::container ${selfns}::G
$myg start {n Expression}
$myg add AddOp Digit Expression Factor MulOp Number Sign Term
$myg modes {
AddOp value
Digit value
Expression value
Factor value
MulOp value
Number value
Sign value
Term value
}
$myg rules {
AddOp {/ {t -} {t +}}
Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
Factor {x {n Term} {* {x {n AddOp} {n Term}}}}
MulOp {/ {t *} {t /}}
Number {x {? {n Sign}} {+ {n Digit}}}
Sign {/ {t -} {t +}}
Term {n Number}
}
return
}
component myg
delegate method * to myg
}
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[CONTAINER](../../../../index.md#container), [EBNF](../../../../index.md#ebnf),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[export](../../../../index.md#export),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar),
[plugin](../../../../index.md#plugin), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
|
[//000000001]: # (pt::peg::export::json - Parser Tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::export::json(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::export::json - PEG Export Plugin. Write JSON format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [JSON Grammar Exchange Format](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::export::json ?1?
package require pt::peg::to::json
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the parsing expression grammar export plugin for the
generation of JSON markup.
It resides in the Export section of the Core Layer of Parser Tools and is
intended to be used by __[pt::peg::export](pt_peg_export.md)__, the export
manager, sitting between it and the corresponding core conversion functionality
provided by __[pt::peg::to::json](pt_peg_to_json.md)__.
While the direct use of this package with a regular interpreter is possible,
this is strongly disrecommended and requires a number of contortions to provide
the expected environment. The proper way to use this functionality depends on
the situation:
1. In an untrusted environment the proper access is through the package
__[pt::peg::export](pt_peg_export.md)__ and the export manager objects it
provides.
1. In a trusted environment however simply use the package
__[pt::peg::to::json](pt_peg_to_json.md)__ and access the core conversion
functionality directly.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Plugin API
found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, the *configuration*, a dictionary, and generates JSON
markup encoding the grammar. The created string is then returned as the
result of the command.
# <a name='section3'></a>Configuration
The JSON export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- boolean *indented*
If this flag is set the plugin will break the generated JSON code across
lines and indent it according to its inner structure, with each key of a
dictionary on a separate line.
If this flag is not set (the default), the whole JSON object will be written
on a single line, with minimum spacing between all elements.
- boolean *aligned*
If this flag is set the generator ensures that the values for the keys in a
dictionary are vertically aligned with each other, for a nice table effect.
To make this work this also implies that __indented__ is set.
If this flag is not set (the default), the output is formatted as per the
value of __indented__, without trying to align the values for dictionary
keys.
*Note* that this plugin ignores the standard configuration variables __user__,
__format__, __file__, and __name__, and their values.
# <a name='section4'></a>JSON Grammar Exchange Format
The __json__ format for parsing expression grammars was written as a data
exchange format not bound to Tcl. It was defined to allow the exchange of
grammars with PackRat/PEG based parser generators for other languages.
It is formally specified by the rules below:
1. The JSON of any PEG is a JSON object.
1. This object holds a single key, __pt::grammar::peg__, and its value. This
value holds the contents of the grammar.
1. The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are
- __rules__
The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a JSON object itself. The relevant keys
and their values in this dictionary are
* __is__
The value is a JSON string holding the Tcl serialization of
the parsing expression describing the symbols sentennial
structure, as specified in the section [PE serialization
format](#section6).
* __mode__
The value is a JSON holding holding one of three values
specifying how a parser should handle the semantic value
produced by the symbol.
+ __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal itself, which has the ASTs of the symbol's
right hand side as its children.
+ __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal, without any children. Any ASTs generated
by the symbol's right hand side are discarded.
+ __void__
The nonterminal has no semantic value. Any ASTs generated
by the symbol's right hand side are discarded (as well).
- __start__
The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section [PE
serialization format](#section6).
1. The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
As an aside to the advanced reader, this is pretty much the same as the Tcl
serialization of PE grammars, as specified in section [PEG serialization
format](#section5), except that the Tcl dictionaries and lists of that format
are mapped to JSON objects and arrays. Only the parsing expressions themselves
are not translated further, but kept as JSON strings containing a nested Tcl
list, and there is no concept of canonicity for the JSON either.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
a JSON serialization for it is
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
and a Tcl serialization of the same is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
The similarity of the latter to the JSON should be quite obvious.
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[export](../../../../index.md#export),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar),
[plugin](../../../../index.md#plugin), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
|
[//000000001]: # (pt::peg::export::peg - Parser Tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::export::peg(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::export::peg - PEG Export Plugin. Write PEG format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Configuration](#section3)
- [PEG Specification Language](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::export::peg ?1?
package require pt::peg::to::peg
[__[export](../../../../index.md#export)__ *serial* *configuration*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the parsing expression grammar export plugin for the
generation of PEG markup.
It resides in the Export section of the Core Layer of Parser Tools and is
intended to be used by __[pt::peg::export](pt_peg_export.md)__, the export
manager, sitting between it and the corresponding core conversion functionality
provided by __[pt::peg::to::peg](pt_peg_to_peg.md)__.
While the direct use of this package with a regular interpreter is possible,
this is strongly disrecommended and requires a number of contortions to provide
the expected environment. The proper way to use this functionality depends on
the situation:
1. In an untrusted environment the proper access is through the package
__[pt::peg::export](pt_peg_export.md)__ and the export manager objects it
provides.
1. In a trusted environment however simply use the package
__[pt::peg::to::peg](pt_peg_to_peg.md)__ and access the core conversion
functionality directly.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Plugin API
found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__[export](../../../../index.md#export)__ *serial* *configuration*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, the *configuration*, a dictionary, and generates PEG
markup encoding the grammar. The created string is then returned as the
result of the command.
# <a name='section3'></a>Configuration
The PEG export plugin recognizes the following configuration variables and
changes its behaviour as they specify.
- string *template*
If this configuration variable is set it is assumed to contain a string into
which to put the generated text and other configuration data. The various
locations are expected to be specified with the following placeholders:
* __@user@__
To be replaced with the value of the configuration variable __user__.
* __@format@__
To be replaced with the the constant __PEG__.
* __@file@__
To be replaced with the value of the configuration variable __file__.
* __@name@__
To be replaced with the value of the configuration variable __name__.
* __@code@__
To be replaced with the generated text.
If this configuration variable is not set, or empty, then the plugin falls
back to a standard template, which is defined as "__@code@__".
*Note* that this plugin may ignore the standard configuration variables
__user__, __format__, __file__, and their values, depending on the chosen
template.
The content of the standard configuration variable __name__, if set, is used as
name of the grammar in the output. Otherwise the plugin falls back to the
default name __a_pe_grammar__.
# <a name='section4'></a>PEG Specification Language
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
It is formally specified by the grammar shown below, written in itself. For a
tutorial / introduction to the language please go and read the *[PEG Language
Tutorial](pt_peg_language.md)*.
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
## <a name='subsection1'></a>Example
Our example specifies the grammar for a basic 4-operation calculator.
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
Using higher-level features of the notation, i.e. the character classes
(predefined and custom), this example can be rewritten as
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[export](../../../../index.md#export),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar),
[plugin](../../../../index.md#plugin), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
[//000000001]: # (pt::peg::from::container - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_from_container.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::from::container(n) 0 tcllib "Parser Tools")
# NAME
pt::peg::from::container - PEG Conversion. From CONTAINER format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package does not exist. There is no need for it. The CONTAINER format for
parsing expression grammars is a piece of Tcl code which, then sourced, provides
a class whose instances have the grammar we wish to import loaded. Another way
of looking at this is, the CONTAINER output is its own import package.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
|
[//000000001]: # (pt::peg::from::json - Parser Tools)
[//000000002]: # (Generated from file 'from.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::from::json(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::from::json - PEG Conversion. Read JSON format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [JSON Grammar Exchange Format](#section3)
- [Example](#subsection1)
- [PEG serialization format](#section4)
- [Example](#subsection2)
- [PE serialization format](#section5)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::from::json ?1?
package require pt::peg
package require json
[__pt::peg::from::json__ __convert__ *text*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from JSON markup to parsing expression
grammars.
It resides in the Import section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the import manager provided by __[pt::peg::import](pt_peg_import.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding import plugin __[pt::peg::import::json](pt_peg_import_json.md)__
sitting between converter and import manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Import API](pt_from_api.md)* specification.
- <a name='1'></a>__pt::peg::from::json__ __convert__ *text*
This command takes the JSON markup encoding a parsing expression grammar and
contained in *text*, and generates the canonical serialization of said
grammar, as specified in section [PEG serialization format](#section4). The
created value is then returned as the result of the command.
# <a name='section3'></a>JSON Grammar Exchange Format
The __json__ format for parsing expression grammars was written as a data
exchange format not bound to Tcl. It was defined to allow the exchange of
grammars with PackRat/PEG based parser generators for other languages.
It is formally specified by the rules below:
1. The JSON of any PEG is a JSON object.
1. This object holds a single key, __pt::grammar::peg__, and its value. This
value holds the contents of the grammar.
1. The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are
- __rules__
The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a JSON object itself. The relevant keys
and their values in this dictionary are
* __is__
The value is a JSON string holding the Tcl serialization of
the parsing expression describing the symbols sentennial
structure, as specified in the section [PE serialization
format](#section5).
* __mode__
The value is a JSON holding holding one of three values
specifying how a parser should handle the semantic value
produced by the symbol.
+ __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal itself, which has the ASTs of the symbol's
right hand side as its children.
+ __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal, without any children. Any ASTs generated
by the symbol's right hand side are discarded.
+ __void__
The nonterminal has no semantic value. Any ASTs generated
by the symbol's right hand side are discarded (as well).
- __start__
The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section [PE
serialization format](#section5).
1. The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
As an aside to the advanced reader, this is pretty much the same as the Tcl
serialization of PE grammars, as specified in section [PEG serialization
format](#section4), except that the Tcl dictionaries and lists of that format
are mapped to JSON objects and arrays. Only the parsing expressions themselves
are not translated further, but kept as JSON strings containing a nested Tcl
list, and there is no concept of canonicity for the JSON either.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
a JSON serialization for it is
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
and a Tcl serialization of the same is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
The similarity of the latter to the JSON should be quite obvious.
# <a name='section4'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section5).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section5).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section5'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
|
[//000000001]: # (pt::peg::from::peg - Parser Tools)
[//000000002]: # (Generated from file 'from.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::from::peg(n) 1.0.3 tcllib "Parser Tools")
# NAME
pt::peg::from::peg - PEG Conversion. Read PEG format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [PEG Specification Language](#section3)
- [Example](#subsection1)
- [PEG serialization format](#section4)
- [Example](#subsection2)
- [PE serialization format](#section5)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::from::peg ?1.0.3?
[__pt::peg::from::peg__ __convert__ *text*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from PEG markup to parsing expression
grammars.
It resides in the Import section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the import manager provided by __[pt::peg::import](pt_peg_import.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding import plugin __[pt::peg::import::peg](pt_peg_import_peg.md)__
sitting between converter and import manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Import API](pt_from_api.md)* specification.
- <a name='1'></a>__pt::peg::from::peg__ __convert__ *text*
This command takes the PEG markup encoding a parsing expression grammar and
contained in *text*, and generates the canonical serialization of said
grammar, as specified in section [PEG serialization format](#section4). The
created value is then returned as the result of the command.
# <a name='section3'></a>PEG Specification Language
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
It is formally specified by the grammar shown below, written in itself. For a
tutorial / introduction to the language please go and read the *[PEG Language
Tutorial](pt_peg_language.md)*.
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
## <a name='subsection1'></a>Example
Our example specifies the grammar for a basic 4-operation calculator.
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
Using higher-level features of the notation, i.e. the character classes
(predefined and custom), this example can be rewritten as
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
# <a name='section4'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section5).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section5).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section5'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_import.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
|
[//000000001]: # (pt::peg::import - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_import.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::import(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::import - PEG Import
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [PEG serialization format](#section3)
- [Example](#subsection4)
- [PE serialization format](#section4)
- [Example](#subsection5)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit
package require configuration
package require pt::peg
package require pluginmgr
package require pt::peg::import ?1?
[__::pt::peg::import__ *objectName*](#1)
[__objectName__ __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __import text__ *text* ?*format*?](#4)
[*objectName* __import file__ *path* ?*format*?](#5)
[*objectName* __import object text__ *object* *text* ?*format*?](#6)
[*objectName* __import object file__ *object* *path* ?*format*?](#7)
[*objectName* __includes__](#8)
[*objectName* __include add__ *path*](#9)
[*objectName* __include remove__ *path*](#10)
[*objectName* __include clear__](#11)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a manager for parsing expression grammars, with each
instance handling a set of plugins for the import of them from other formats,
i.e. their conversion from, for example *peg*, *container*,
*[json](../../../../index.md#json)*, etc.
It resides in the Import section of the Core Layer of Parser Tools, and is one
of the three pillars the management of parsing expression grammars resides on.
 The other two pillars are, as shown
above
1. *[PEG Export](pt_peg_export.md)*, and
1. *[PEG Storage](pt_peg_container.md)*
For information about the data structure which is the major output of the
manager objects provided by this package see the section [PEG serialization
format](#section3).
The plugin system of our class is based on the package
__[pluginmgr](../pluginmgr/pluginmgr.md)__, and configured to look for plugins
using
1. the environment variable __GRAMMAR_PEG_IMPORT_PLUGINS__,
1. the environment variable __GRAMMAR_PEG_PLUGINS__,
1. the environment variable __GRAMMAR_PLUGINS__,
1. the path "~/.grammar/peg/import/plugin"
1. the path "~/.grammar/peg/plugin"
1. the path "~/.grammar/plugin"
1. the path "~/.grammar/peg/import/plugins"
1. the path "~/.grammar/peg/plugins"
1. the path "~/.grammar/plugins"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\IMPORT\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"
1. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"
The last three are used only when the package is run on a machine using the
Windows(tm) operating system.
The whole system is delivered with three predefined import plugins, namely
- container
See *[PEG Import Plugin. From CONTAINER format](pt_peg_import_container.md)*
for details.
- json
See *PEG Import Plugin. From JSON format* for details.
- peg
See *PEG Import Plugin. From PEG format* for details.
For readers wishing to write their own import plugin for some format, i.e.
*plugin writer*s, reading and understanding the *Parser Tools Impport API*
specification is an absolute necessity, as it documents the interaction between
this package and its plugins in detail.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__::pt::peg::import__ *objectName*
This command creates a new import manager object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The object command will be created under the current
namespace if the *objectName* is not fully qualified, and in the specified
namespace otherwise.
## <a name='subsection2'></a>Object command
All objects created by the __::pt::peg::import__ command have the following
general form:
- <a name='2'></a>__objectName__ __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object it is invoked for.
- <a name='4'></a>*objectName* __import text__ *text* ?*format*?
This method takes the *text* and converts it from the specified *format* to
the canonical serialization of a parsing expression grammar using the import
plugin for the format. An error is thrown if no plugin could be found for
the format. The serialization generated by the conversion process is
returned as the result of this method.
If no format is specified the method defaults to __text__.
The specification of what a *canonical* serialization is can be found in the
section [PEG serialization format](#section3).
The plugin has to conform to the interface documented in the *[Parser Tools
Import API](pt_from_api.md)* specification.
- <a name='5'></a>*objectName* __import file__ *path* ?*format*?
This method is a convenient wrapper around the __import text__ method
described by the previous item. It reads the contents of the specified file
into memory, feeds the result into __import text__ and returns the resulting
serialization as its own result.
- <a name='6'></a>*objectName* __import object text__ *object* *text* ?*format*?
This method is a convenient wrapper around the __import text__ method
described by the previous item. It expects that *object* is an object
command supporting a __deserialize__ method expecting the canonical
serialization of a parsing expression grammar. It imports the text using
__import text__ and then feeds the resulting serialization into the *object*
via __deserialize__. This method returns the empty string as it result.
- <a name='7'></a>*objectName* __import object file__ *object* *path* ?*format*?
This method behaves like __import object text__, except that it reads the
text to convert from the specified file instead of being given it as
argument.
- <a name='8'></a>*objectName* __includes__
This method returns a list containing the currently specified paths to use
to search for include files when processing input. The order of paths in the
list corresponds to the order in which they are used, from first to last,
and also corresponds to the order in which they were added to the object.
- <a name='9'></a>*objectName* __include add__ *path*
This methods adds the specified *path* to the list of paths to use to search
for include files when processing input. The path is added to the end of the
list, causing it to be searched after all previously added paths. The result
of the command is the empty string.
The method does nothing if the path is already known.
- <a name='10'></a>*objectName* __include remove__ *path*
This methods removes the specified *path* from the list of paths to use to
search for include files when processing input. The result of the command is
the empty string.
The method does nothing if the path is not known.
- <a name='11'></a>*objectName* __include clear__
This method clears the list of paths to use to search for include files when
processing input. The result of the command is the empty string.
# <a name='section3'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section4).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section4).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection4'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section4'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection5'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
[//000000001]: # (pt::peg::import::container - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_import_container.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::import::container(n) 0 tcllib "Parser Tools")
# NAME
pt::peg::import::container - PEG Import Plugin. From CONTAINER format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package does not exist. There is no need for it. The CONTAINER format for
parsing expression grammars is a piece of Tcl code which, then sourced, provides
a class whose instances have the grammar we wish to import loaded. Another way
of looking at this is, the CONTAINER output is its own import package.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
|
[//000000001]: # (pt::peg::import::json - Parser Tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::import::json(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::import::json - PEG Import Plugin. Read JSON format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [JSON Grammar Exchange Format](#section3)
- [Example](#subsection1)
- [PEG serialization format](#section4)
- [Example](#subsection2)
- [PE serialization format](#section5)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::import::json ?1?
package require pt::peg::to::json
[__[import](../../../../index.md#import)__ *text*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the parsing expression grammar import plugin processing
JSON markup.
It resides in the Import section of the Core Layer of Parser Tools and is
intended to be used by __[pt::peg::import](pt_peg_import.md)__, the import
manager, sitting between it and the corresponding core conversion functionality
provided by __[pt::peg::from::json](pt_peg_from_json.md)__.
While the direct use of this package with a regular interpreter is possible,
this is strongly disrecommended and requires a number of contortions to provide
the expected environment. The proper way to use this functionality depends on
the situation:
1. In an untrusted environment the proper access is through the package
__[pt::peg::import](pt_peg_import.md)__ and the import manager objects it
provides.
1. In a trusted environment however simply use the package
__[pt::peg::from::json](pt_peg_from_json.md)__ and access the core
conversion functionality directly.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Plugin API
found in the *[Parser Tools Import API](pt_from_api.md)* specification.
- <a name='1'></a>__[import](../../../../index.md#import)__ *text*
This command takes the JSON markup encoding a parsing expression grammar and
contained in *text*, and generates the canonical serialization of said
grammar, as specified in section [PEG serialization format](#section4). The
created value is then returned as the result of the command.
# <a name='section3'></a>JSON Grammar Exchange Format
The __json__ format for parsing expression grammars was written as a data
exchange format not bound to Tcl. It was defined to allow the exchange of
grammars with PackRat/PEG based parser generators for other languages.
It is formally specified by the rules below:
1. The JSON of any PEG is a JSON object.
1. This object holds a single key, __pt::grammar::peg__, and its value. This
value holds the contents of the grammar.
1. The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are
- __rules__
The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a JSON object itself. The relevant keys
and their values in this dictionary are
* __is__
The value is a JSON string holding the Tcl serialization of
the parsing expression describing the symbols sentennial
structure, as specified in the section [PE serialization
format](#section5).
* __mode__
The value is a JSON holding holding one of three values
specifying how a parser should handle the semantic value
produced by the symbol.
+ __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal itself, which has the ASTs of the symbol's
right hand side as its children.
+ __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal, without any children. Any ASTs generated
by the symbol's right hand side are discarded.
+ __void__
The nonterminal has no semantic value. Any ASTs generated
by the symbol's right hand side are discarded (as well).
- __start__
The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section [PE
serialization format](#section5).
1. The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
As an aside to the advanced reader, this is pretty much the same as the Tcl
serialization of PE grammars, as specified in section [PEG serialization
format](#section4), except that the Tcl dictionaries and lists of that format
are mapped to JSON objects and arrays. Only the parsing expressions themselves
are not translated further, but kept as JSON strings containing a nested Tcl
list, and there is no concept of canonicity for the JSON either.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
a JSON serialization for it is
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
and a Tcl serialization of the same is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
The similarity of the latter to the JSON should be quite obvious.
# <a name='section4'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section5).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section5).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section5'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar), [import](../../../../index.md#import),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar),
[plugin](../../../../index.md#plugin), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
|
[//000000001]: # (pt::peg::import::peg - Parser Tools)
[//000000002]: # (Generated from file 'plugin.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::import::peg(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::import::peg - PEG Import Plugin. Read PEG format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [PEG Specification Language](#section3)
- [Example](#subsection1)
- [PEG serialization format](#section4)
- [Example](#subsection2)
- [PE serialization format](#section5)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::import::peg ?1?
package require pt::peg::to::peg
[__[import](../../../../index.md#import)__ *text*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the parsing expression grammar import plugin processing
PEG markup.
It resides in the Import section of the Core Layer of Parser Tools and is
intended to be used by __[pt::peg::import](pt_peg_import.md)__, the import
manager, sitting between it and the corresponding core conversion functionality
provided by __[pt::peg::from::peg](pt_peg_from_peg.md)__.
While the direct use of this package with a regular interpreter is possible,
this is strongly disrecommended and requires a number of contortions to provide
the expected environment. The proper way to use this functionality depends on
the situation:
1. In an untrusted environment the proper access is through the package
__[pt::peg::import](pt_peg_import.md)__ and the import manager objects it
provides.
1. In a trusted environment however simply use the package
__[pt::peg::from::peg](pt_peg_from_peg.md)__ and access the core conversion
functionality directly.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Plugin API
found in the *[Parser Tools Import API](pt_from_api.md)* specification.
- <a name='1'></a>__[import](../../../../index.md#import)__ *text*
This command takes the PEG markup encoding a parsing expression grammar and
contained in *text*, and generates the canonical serialization of said
grammar, as specified in section [PEG serialization format](#section4). The
created value is then returned as the result of the command.
# <a name='section3'></a>PEG Specification Language
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
It is formally specified by the grammar shown below, written in itself. For a
tutorial / introduction to the language please go and read the *[PEG Language
Tutorial](pt_peg_language.md)*.
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
## <a name='subsection1'></a>Example
Our example specifies the grammar for a basic 4-operation calculator.
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
Using higher-level features of the notation, i.e. the character classes
(predefined and custom), this example can be rewritten as
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
# <a name='section4'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section5).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section5).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section5'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar), [import](../../../../index.md#import),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar),
[plugin](../../../../index.md#plugin), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_interp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
[//000000001]: # (pt::peg::interp - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_interp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::interp(n) 1.0.1 tcllib "Parser Tools")
# NAME
pt::peg::interp - Interpreter for parsing expression grammars
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#subsection1)
- [Object API](#subsection2)
- [AST serialization format](#section2)
- [Example](#subsection3)
- [PE serialization format](#section3)
- [Example](#subsection4)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::interp ?1.0.1?
package require pt::rde ?1?
package require snit
[__::pt::peg::interp__ *objectName* *grammar*](#1)
[*objectName* __use__ *grammar*](#2)
[*objectName* __destroy__](#3)
[*objectName* __parse__ *chan*](#4)
[*objectName* __parset__ *text*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a class whose instances are Packrat parsers configurable
with a parsing expression grammar. The grammar is executed directly, i.e.
interpreted, with the underlying runtime provided by the package
__[pt::rde](pt_rdengine.md)__, basing everything on the PARAM.
Like the supporting runtime this package resides in the Execution section of the
Core Layer of Parser Tools.
The interpreted grammar is copied from an instance of
__[pt::peg::container](pt_peg_container.md)__, or anything providing the same
API, like the container classes created by
__[pt::peg::to::container](pt_peg_to_container.md)__ or the associated export
plugin __[pt::peg::export::container](pt_peg_export_container.md)__.
## <a name='subsection1'></a>Class API
The package exports the API described here.
- <a name='1'></a>__::pt::peg::interp__ *objectName* *grammar*
The command creates a new parser object and returns the fully qualified name
of the object command as its result. The API of this object command is
described in the section [Object API](#subsection2). It may be used to
invoke various operations on the object.
This new parser is configured for the execution of an empty PEG. To
configure the object for any other PEG use the method __use__ of the [Object
API](#subsection2).
## <a name='subsection2'></a>Object API
All objects created by this package provide the following methods.
- <a name='2'></a>*objectName* __use__ *grammar*
This method configures the grammar interpreter / parser for the execution of
the PEG stored in *grammar*, an object which is API-compatible to instances
of __[pt::peg::container](pt_peg_container.md)__. The parser copies the
relevant information of the grammar, and does *not* take ownership of the
object.
The information of any previously used grammar is overwritten.
The result of the method the empty string.
- <a name='3'></a>*objectName* __destroy__
This method destroys the parser instance, releasing all claimed memory and
other resources, and deleting the instance command.
The result of the command is the empty string.
- <a name='4'></a>*objectName* __parse__ *chan*
This method runs the parser using the contents of *chan* as input (starting
at the current location in the channel), until parsing is not possible
anymore, either because parsing has completed, or run into a syntax error.
Note here that the Parser Tools are based on Tcl 8.5+. In other words, the
channel argument is not restricted to files, sockets, etc. We have the full
power of *reflected channels* available.
It should also be noted that the parser pulls the characters from the input
stream as it needs them. If a parser created by this package has to be
operated in a push aka event-driven manner it will be necessary to go to Tcl
8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it
into a coroutine where __[read](../../../../index.md#read)__ is properly
changed for push-operation.
Upon successful completion the command returns an abstract syntax tree as
its result. This AST is in the form specified in section [AST serialization
format](#section2). As a plain nested Tcl-list it can then be processed with
any Tcl commands the user likes, doing transformations, semantic checks,
etc. To help in this the package __[pt::ast](pt_astree.md)__ provides a set
of convenience commands for validation of the tree's basic structure,
printing it for debugging, and walking it either from the bottom up, or top
down.
When encountering a syntax error the command will throw an error instead.
This error will be a 4-element Tcl-list, containing, in the order listed
below:
The string __pt::rde__ identifying it as parser runtime error.
The location of the parse error, as character offset from the beginning of
the parsed input.
The location of parse error, now as a 2-element list containing line-number
and column in the line.
A set of atomic parsing expressions indicating encoding the characters
and/or nonterminal symbols the parser expected to see at the location of the
parse error, but did not get. For the specification of atomic parsing
expressions please see the section [PE serialization format](#section3).
- <a name='5'></a>*objectName* __parset__ *text*
This method runs the parser using the string in *text* as input. In all
other ways it behaves like the method __parse__, shown above.
# <a name='section2'></a>AST serialization format
Here we specify the format used by the Parser Tools to serialize Abstract Syntax
Trees (ASTs) as immutable values for transport, comparison, etc.
Each node in an AST represents a nonterminal symbol of a grammar, and the range
of tokens/characters in the input covered by it. ASTs do not contain terminal
symbols, i.e. tokens/characters. These can be recovered from the input given a
symbol's location.
We distinguish between *regular* and *canonical* serializations. While a tree
may have more than one regular serialization only exactly one of them will be
*canonical*.
- Regular serialization
The serialization of any AST is the serialization of its root node.
The serialization of any node is a Tcl list containing at least three
elements.
The first element is the name of the nonterminal symbol stored in the node.
The second and third element are the locations of the first and last token
in the token stream the node represents (covers).
Locations are provided as non-negative integer offsets from the beginning of
the token stream, with the first token found in the stream located at offset
0 (zero).
The end location has to be equal to or larger than the start location.
All elements after the first three represent the children of the node, which
are themselves nodes. This means that the serializations of nodes without
children, i.e. leaf nodes, have exactly three elements. The children are
stored in the list with the leftmost child first, and the rightmost child
last.
- Canonical serialization
The canonical serialization of an abstract syntax tree has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this tree.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
## <a name='subsection3'></a>Example
Assuming the parsing expression grammar below
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
and the input string
120+5
then a parser should deliver the abstract syntax tree below (except for
whitespace)
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
Or, more graphical
# <a name='section3'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection4'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
[//000000001]: # (pt::pegrammar - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_introduction.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::pegrammar(n) 1 tcllib "Parser Tools")
# NAME
pt::pegrammar - Introduction to Parsing Expression Grammars
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Formal definition](#section2)
- [References](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
Welcome to the introduction to *[Parsing Expression
Grammar](../../../../index.md#parsing_expression_grammar)*s (short:
*[PEG](../../../../index.md#peg)*), the formalism used by the Parser Tools. It
is assumed that the reader has a basic knowledge of parsing theory, i.e.
*Context-Free Grammars* (short: *[CFG](../../../../index.md#cfg)*), *languages*,
and associated terms like *[LL(k)](../../../../index.md#ll_k_)*, *LR(k)*,
*[terminal](../../../../index.md#terminal)* and *nonterminal* *symbols*, etc. We
do not intend to recapitulate such basic definitions or terms like *useful*,
*reachable*, (left/right) *recursive*, *nullable*, first/last/follow sets, etc.
Please see the [References](#section3) at the end instead if you are in need of
places and books which provide such background information.
PEGs are formally very similar to CFGs, with terminal and nonterminal symbols,
start symbol, and rules defining the structure of each nonterminal symbol. The
main difference lies in the choice(sic!) of *choice* operators. Where CFGs use
an *unordered choice* to represent alternatives PEGs use *prioritized choice*.
Which is fancy way of saying that a parser has to try the first alternative
first and can try the other alternatives if only if it fails for the first, and
so on.
On the CFG side this gives rise to LL(k) and LR(k) for making the choice
*deterministic* with a bounded *lookahead* of k terminal symbols, where LL is in
essence *topdown* aka *[recursive
descent](../../../../index.md#recursive_descent)* parsing, and LR *bottomup* aka
*shift reduce* parsing.
On the PEG side we can parse input with recursive descent and *backtracking* of
failed choices, the latter of which amounts to unlimited lookahead. By
additionally recording the success or failure of nonterminals at the specific
locations they were tried at and reusing this information after backtracking we
can avoid the exponential blowup of running time usually associated with
backtracking and keep the parsing linear. The memory requirements are of course
higher due to this cache, as we are trading space for time.
This is the basic concept behind *packrat parsers*.
A limitation pure PEGs share with LL(k) CFGs is that *left-recursive* grammars
cannot be parsed, with the associated recursive descent parser entering an
infinite recursion. This limitation is usually overcome by extending pure PEGs
with explicit operators to specify repetition, zero or more, and one or more,
or, formally spoken, for the *kleene closure* and *positive kleene closure*.
This is what the Parser Tools are doing.
Another extension, specific to Parser Tools, is a set of operators which map
more or less directly to various character classes built into Tcl, i.e. the
classes reachable via __string is__.
The remainder of this document consists of the formal definition of PEGs for the
mathematically inclined, and an appendix listing references to places with more
information on PEGs specifically, and parsing in general.
# <a name='section2'></a>Formal definition
For the mathematically inclined, a Parsing Expression Grammar is a 4-tuple
(VN,VT,R,eS) where
- VN is a set of *nonterminal symbols*,
- VT is a set of *terminal symbols*,
- R is a finite set of rules, where each rule is a pair (A,e), A in VN, and
*[e](../../../../index.md#e)* a *[parsing
expression](../../../../index.md#parsing_expression)*.
- eS is a parsing expression, the *start expression*.
Further constraints are
- The intersection of VN and VT is empty.
- For all A in VT exists exactly one pair (A,e) in R. In other words, R is a
function from nonterminal symbols to parsing expressions.
Parsing expressions are inductively defined via
- The empty string (epsilon) is a parsing expression.
- A terminal symbol *a* is a parsing expression.
- A nonterminal symbol *A* is a parsing expression.
- *e1**e2* is a parsing expression for parsing expressions *e1* and *2*. This
is called *sequence*.
- *e1*/*e2* is a parsing expression for parsing expressions *e1* and *2*. This
is called *ordered choice*.
- *[e](../../../../index.md#e)** is a parsing expression for parsing
expression *[e](../../../../index.md#e)*. This is called *zero-or-more
repetitions*, also known as *kleene closure*.
- *[e](../../../../index.md#e)*+ is a parsing expression for parsing
expression *[e](../../../../index.md#e)*. This is called *one-or-more
repetitions*, also known as *positive kleene closure*.
- !*[e](../../../../index.md#e)* is a parsing expression for parsing
expression *e1*. This is called a *not lookahead predicate*.
- &*[e](../../../../index.md#e)* is a parsing expression for parsing
expression *e1*. This is called an *and lookahead predicate*.
PEGs are used to define a grammatical structure for streams of symbols over VT.
They are a modern phrasing of older formalisms invented by Alexander Birham.
These formalisms were called TS (TMG recognition scheme), and gTS (generalized
TS). Later they were renamed to TPDL (Top-Down Parsing Languages) and gTPDL
(generalized TPDL).
They can be easily implemented by recursive descent parsers with backtracking.
This makes them relatives of LL(k) Context-Free Grammars.
# <a name='section3'></a>References
1. [The Packrat Parsing and Parsing Expression Grammars
Page](http://www.pdos.lcs.mit.edu/~baford/packrat/), by Bryan Ford,
Massachusetts Institute of Technology. This is the main entry page to PEGs,
and their realization through Packrat Parsers.
1. [http://en.wikipedia.org/wiki/Parsing_expression_grammar](http://en.wikipedia.org/wiki/Parsing_expression_grammar)
Wikipedia's entry about Parsing Expression Grammars.
1. [Parsing Techniques - A Practical Guide
](http://www.cs.vu.nl/~dick/PTAPG.html), an online book offering a clear,
accessible, and thorough discussion of many different parsing techniques
with their interrelations and applicabilities, including error recovery
techniques.
1. [Compilers and Compiler Generators](http://scifac.ru.ac.za/compilers/), an
online book using CoCo/R, a generator for recursive descent parsers.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_language.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
|
[//000000001]: # (pt::peg_language - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_language.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg_language(n) 1 tcllib "Parser Tools")
# NAME
pt::peg_language - PEG Language Tutorial
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [What is it?](#section2)
- [The elements of the language](#section3)
- [Basic structure](#subsection1)
- [Names](#subsection2)
- [Rules](#subsection3)
- [Expressions](#subsection4)
- [Whitespace and comments](#subsection5)
- [Nonterminal attributes](#subsection6)
- [PEG Specification Language](#section4)
- [Example](#subsection7)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
Welcome to the tutorial / introduction for the [PEG Specification
Language](#section4). If you are already familiar with the language we are about
to discuss, and only wish to refresh your memory you can, of course, skip ahead
to the aforementioned section and just read the full formal specification.
# <a name='section2'></a>What is it?
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
# <a name='section3'></a>The elements of the language
## <a name='subsection1'></a>Basic structure
The general outline of a textual PEG is
PEG <<name>> (<<start-expression>>)
<<rules>>
END;
*Note*: We are using text in double angle-brackets as place-holders for things
not yet explained.
## <a name='subsection2'></a>Names
Names are mostly used to identify the nonterminal symbols of the grammar, i.e.
that which occurs on the left-hand side of a <rule>. The exception to that is
the name given after the keyword __PEG__ (see previous section), which is the
name of the whole grammar itself.
The structure of a name is simple:
1. It begins with a letter, underscore, or colon, followed by
1. zero or more letters, digits, underscores, or colons.
Or, in formal textual notation:
([_:] / <alpha>) ([_:] / <alnum>)*
Examples of names:
Hello
::world
_:submarine55_
Examples of text which are *not* names:
12
.bogus
0wrong
@location
## <a name='subsection3'></a>Rules
The main body of the text of a grammar specification is taken up by the rules.
Each rule defines the sentence structure of one nonterminal symbol. Their basic
structure is
<<name>> <- <<expression>> ;
The <name> specifies the nonterminal symbol to be defined, the <expression>
after the arrow (<-) then declares its structure.
Note that each rule ends in a single semicolon, even the last. I.e. the
semicolon is a rule *terminator*, not a separator.
We can have as many rules as we like, as long as we define each nonterminal
symbol at most once, and have at least one rule for each nonterminal symbol
which occured in an expression, i.e. in either the start expression of the
grammar, or the right-hande side of a rule.
## <a name='subsection4'></a>Expressions
The *parsing* expressions are the meat of any specification. They declare the
structure of the whole document (<<start-expression>>), and of all nonterminal
symbols.
All expressions are made up out of *atomic expressions* and *operators*
combining them. We have operators for choosing between alternatives, repetition
of parts, and for look-ahead constraints. There is no explicit operator for the
sequencing (also known as *concatenation*) of parts however. This is specified
by simply placing the parts adjacent to each other.
Here are the operators, from highest to lowest priority (i.e. strength of
binding):
# Binary operators.
<<expression-1>> <<expression-2>> # sequence. parse 1, then 2.
<<expression-1>> / <<expression-2>> # alternative. try to parse 1, and parse 2 if 1 failed to parse.
# Prefix operators. Lookahead constraints. Same priority.
& <<expression>> # Parse expression, ok on successful parse.
! <<expression>> # Ditto, except ok on failure to parse.
# Suffix operators. Repetition. Same priority.
<<expression>> ? # Parse expression none, or once (repeat 0 or 1).
<<expression>> * # Parse expression zero or more times.
<<expression>> + # Parse expression one or more times.
# Expression nesting
( <<expression>> ) # Put an expression in parens to change its priority.
With this we can now deconstruct the formal expression for names given in
section [Names](#subsection2):
([_:] / <alpha>) ([_:] / <alnum>)*
It is a sequence of two parts,
[_:] / <alpha>
and
([_:] / <alnum>)*
The parentheses around the parts kept their inner alternatives bound together
against the normally higher priority of the sequence. Each of the two parts is
an alternative, with the second part additionally repeated zero or more times,
leaving us with the three atomic expressions
[_:]
<alpha>
<alnum>
And *atomic expressions* are our next topic. They fall into three classes:
1. names, i.e. nonterminal symbols,
1. string literals, and
1. character classes.
Names we know about already, or see section [Names](#subsection2) for a
refresher.
String literals are simple. They are delimited by (i.e. start and end with)
either a single or double-apostroph, and in between the delimiters we can have
any character but the delimiter itself. They can be empty as well. Examples of
strings are
''
""
'hello'
"umbra"
"'"
'"'
The last two examples show how to place any of the delimiters into a string.
For the last, but not least of our atomic expressions, character classes, we
have a number of predefined classes, shown below, and the ability to construct
or own. The predefined classes are:
<alnum> # Any unicode alphabet or digit character (string is alnum).
<alpha> # Any unicode alphabet character (string is alpha).
<ascii> # Any unicode character below codepoint 0x80 (string is ascii).
<control> # Any unicode control character (string is control).
<ddigit> # The digit characters [0-9].
<digit> # Any unicode digit character (string is digit).
<graph> # Any unicode printing character, except space (string is graph).
<lower> # Any unicode lower-case alphabet character (string is lower).
<print> # Any unicode printing character, incl. space (string is print).
<punct> # Any unicode punctuation character (string is punct).
<space> # Any unicode space character (string is space).
<upper> # Any unicode upper-case alphabet character (string is upper).
<wordchar> # Any unicode word character (string is wordchar).
<xdigit> # The hexadecimal digit characters [0-9a-fA-F].
. # Any character, except end of input.
And the syntax of custom-defined character classes is
[ <<range>>* ]
where each range is either a single character, or of the form
<<character>> - <character>>
Examples for character classes we have seen already in the course of this
introduction are
[_:]
[0-9]
[0-9a-fA-F]
We are nearly done with expressions. The only piece left is to tell how the
characters in character classes and string literals are specified.
Basically characters in the input stand for themselves, and in addition to that
we several types of escape syntax to to repesent control characters, or
characters outside of the encoding the text is in.
All the escaped forms are started with a backslash character ('\', unicode
codepoint 0x5C). This is then followed by a series of octal digits, or 'u' and
hexedecimal digits, or a regular character from a fixed set for various control
characters. Some examples:
\n \r \t \' \" \[ \] \\ #
\000 up to \277 # octal escape, all ascii character, leading 0's can be removed.
\u2CA7 # hexadecimal escape, all unicode characters.
# # Here 2ca7 <=> Koptic Small Letter Tau
## <a name='subsection5'></a>Whitespace and comments
One issue not touched upon so far is whitespace and comments.
Whitespace is any unicode space character, i.e. anything in the character class
<space>, and comments. The latter are sequences of characters starting with a
'#' (hash, unicode codepoint 0x23) and ending at the next end-of-line.
Whitespace can be freely used between all syntactical elements of a grammar
specification. It cannot be used inside of syntactical elements, like names,
string literals, predefined character classes, etc.
## <a name='subsection6'></a>Nonterminal attributes
Lastly, a more advanced topic. In the section [Rules](#subsection3) we gave the
structure of a rule as
<<name>> <- <<expression>> ;
This is not quite true. It is possible to associate a semantic mode with the
nonterminal in the rule, by writing it before the name, separated from it by a
colon, i.e. writing
<<mode>> : <<name>> <- <<expression>> ;
is also allowed. This mode is optional. The known modes and their meanings are:
- __value__
The semantic value of the nonterminal symbol is an abstract syntax tree
consisting of a single node node for the nonterminal itself, which has the
ASTs of the symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an abstract syntax tree
consisting of a single node node for the nonterminal, without any children.
Any ASTs generated by the symbol's right hand side are discarded.
- __void__
The nonterminal has no semantic value. Any ASTs generated by the symbol's
right hand side are discarded (as well).
Of these three modes only __leaf__ and __void__ can be specified directly.
__value__ is implicitly specified by the absence of a mode before the
nonterminal.
Now, with all the above under our belt it should be possible to not only read,
but understand the formal specification of the text representation shown in the
next section, written in itself.
# <a name='section4'></a>PEG Specification Language
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
It is formally specified by the grammar shown below, written in itself. For a
tutorial / introduction to the language please go and read the *PEG Language
Tutorial*.
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
## <a name='subsection7'></a>Example
Our example specifies the grammar for a basic 4-operation calculator.
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
Using higher-level features of the notation, i.e. the character classes
(predefined and custom), this example can be rewritten as
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_op.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
[//000000001]: # (pt_peg_op - Parser Tools)
[//000000002]: # (Generated from file 'pt_peg_op.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt_peg_op(i) 1.1.0 tcllib "Parser Tools")
# NAME
pt_peg_op - Parser Tools PE Grammar Utility Operations
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::op ?1.1.0?
[__::peg::peg::op__ __called__ *container*](#1)
[__::peg::peg::op__ __dechain__ *container*](#2)
[__::peg::peg::op__ __drop unreachable__ *container*](#3)
[__::peg::peg::op__ __drop unrealizable__ *container*](#4)
[__::peg::peg::op__ __flatten__ *container*](#5)
[__::peg::peg::op__ __minimize__ *container*](#6)
[__::peg::peg::op__ __modeopt__ *container*](#7)
[__::peg::peg::op__ __reachable__ *container*](#8)
[__::peg::peg::op__ __realizable__ *container*](#9)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a number of utility commands manipulating a PE grammar
(container) in various ways.
# <a name='section2'></a>API
- <a name='1'></a>__::peg::peg::op__ __called__ *container*
This command determines the static call structure for the nonterminal
symbols of the grammar stored in the *container*.
The result of the command is a dictionary mapping from each symbol to the
symbols it calls. The empty string is the key used to represent the start
expression of the grammar.
The grammar in the container is not modified.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='2'></a>__::peg::peg::op__ __dechain__ *container*
This command simplifies all symbols which just chain to a different symbol
by inlining the right hand side of the called symbol in its callers. This
works if and only the modes match properly, per the decision table below.
caller called | dechain | notes
--------------+---------+-----------------------
value value | yes | value is passed
value leaf | yes | value is passed
value void | yes | caller is implied void
leaf value | no | generated value was discarded, inlined would not. called may be implied void.
leaf leaf | no | s.a.
leaf void | no | s.a.
void value | no | caller drops value, inlined would not.
void leaf | no | s.a.
void void | yes |
The result of the command is the empty string.
The grammar in the container is directly modified. If that is not wanted, a
copy of the original container has to be used.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='3'></a>__::peg::peg::op__ __drop unreachable__ *container*
This command removes all symbols from the grammar which are not
__reachable__.
The result of the command is the empty string.
The grammar in the container is directly modified. If that is not wanted, a
copy of the original container has to be used.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='4'></a>__::peg::peg::op__ __drop unrealizable__ *container*
This command removes all symbols from the grammar which are not
__realizable__.
The result of the command is the empty string.
The grammar in the container is directly modified. If that is not wanted, a
copy of the original container has to be used.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='5'></a>__::peg::peg::op__ __flatten__ *container*
This command flattens (see __[pt::pe::op](pt_pexpr_op.md)__) all expressions
in the grammar, i.e. the start expression and the right hand sides of all
nonterminal symbols.
The result of the command is the empty string.
The grammar in the container is directly modified. If that is not wanted, a
copy of the original container has to be used.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='6'></a>__::peg::peg::op__ __minimize__ *container*
This command reduces the provided grammar by applying most of the other
methods of this package.
After flattening the expressions it removes unreachable and unrealizable
symbols, flattens the expressions again, then optimizes the symbol modes
before collapsing symbol chains as much as possible.
The result of the command is the empty string.
The grammar in the container is directly modified. If that is not wanted, a
copy of the original container has to be used.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='7'></a>__::peg::peg::op__ __modeopt__ *container*
This command optimizes the semantic modes of non-terminal symbols according
to the two rules below.
If a symbol X with mode __value__ calls no other symbols, i.e. uses only
terminal symbols in whatever combination, then this can be represented
simpler by using mode __leaf__.
If a symbol X is only called from symbols with modes __leaf__ or __void__
then this symbol should have mode __void__ also, as any AST it could
generate will be discarded anyway.
The result of the command is the empty string.
The grammar in the container is directly modified. If that is not wanted, a
copy of the original container has to be used.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='8'></a>__::peg::peg::op__ __reachable__ *container*
This command computes the set of all nonterminal symbols which are reachable
from the start expression of the grammar. This is essentially the transitive
closure over __called__ and the symbol's right hand sides, beginning with
the start expression.
The result of the command is the list of reachable symbols.
The grammar in the container is not modified.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
- <a name='9'></a>__::peg::peg::op__ __realizable__ *container*
This command computes the set of all nonterminal symbols which are
realizable, i.e. can derive pure terminal phrases. This is done iteratively,
starting with state unrealizable for all and any, and then updating all
symbols which are realizable, propagating changes, until nothing changes any
more.
The result of the command is the list of realizable symbols.
The grammar in the container is not modified.
The *container* instance has to expose a method API as is provided by the
package __[pt::peg::container](pt_peg_container.md)__.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
|
[//000000001]: # (pt::peg::to::container - Parser Tools)
[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::to::container(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::to::container - PEG Conversion. Write CONTAINER format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [Grammar Container](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::to::container ?1?
package require pt::peg
package require text::write
package require char
[__pt::peg::to::container__ __reset__](#1)
[__pt::peg::to::container__ __configure__](#2)
[__pt::peg::to::container__ __configure__ *option*](#3)
[__pt::peg::to::container__ __configure__ *option* *value*...](#4)
[__pt::peg::to::container__ __convert__ *serial*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from parsing expression grammars to
CONTAINER markup.
It resides in the Export section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the export manager provided by __[pt::peg::export](pt_peg_export.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding export plugin
__[pt::peg::export::container](pt_peg_export_container.md)__ sitting between
converter and export manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__pt::peg::to::container__ __reset__
This command resets the configuration of the package to its default
settings.
- <a name='2'></a>__pt::peg::to::container__ __configure__
This command returns a dictionary containing the current configuration of
the package.
- <a name='3'></a>__pt::peg::to::container__ __configure__ *option*
This command returns the current value of the specified configuration
*option* of the package. For the set of legal options, please read the
section [Options](#section3).
- <a name='4'></a>__pt::peg::to::container__ __configure__ *option* *value*...
This command sets the given configuration *option*s of the package, to the
specified *value*s. For the set of legal options, please read the section
[Options](#section3).
- <a name='5'></a>__pt::peg::to::container__ __convert__ *serial*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, and generates CONTAINER markup encoding the grammar,
per the current package configuration. The created string is then returned
as the result of the command.
# <a name='section3'></a>Options
The converter to the CONTAINER format recognizes the following options and
changes its behaviour as they specify.
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-mode__ __bulk__|__incremental__
The value of this option controls which methods of
__[pt::peg::container](pt_peg_container.md)__ instances are used to specify
the grammar, i.e. preload it into the container. There are two legal values,
as listed below. The default is __bulk__.
* __bulk__
In this mode the methods __start__, __add__, __modes__, and __rules__
are used to specify the grammar in a bulk manner, i.e. as a set of
nonterminal symbols, and two dictionaries mapping from the symbols to
their semantic modes and parsing expressions.
This mode is the default.
* __incremental__
In this mode the methods __start__, __add__, __mode__, and __rule__ are
used to specify the grammar piecemal, with each nonterminal having its
own block of defining commands.
- __-template__ string
The value of this option is a string into which to put the generated code
and the other configuration settings. The various locations for user-data
are expected to be specified with the placeholders listed below. The default
value is "__@code@__".
* __@user@__
To be replaced with the value of the option __-user__.
* __@format@__
To be replaced with the the constant __CONTAINER__.
* __@file@__
To be replaced with the value of the option __-file__.
* __@name@__
To be replaced with the value of the option __-name__.
* __@mode@__
To be replaced with the value of the option __-mode__.
* __@code@__
To be replaced with the generated code.
# <a name='section4'></a>Grammar Container
The __container__ format is another form of describing parsing expression
grammars. While data in this format is executable it does not constitute a
parser for the grammar. It always has to be used in conjunction with the package
__[pt::peg::interp](pt_peg_interp.md)__, a grammar interpreter.
The format represents grammars by a __snit::type__, i.e. class, whose instances
are API-compatible to the instances of the
__[pt::peg::container](pt_peg_container.md)__ package, and which are preloaded
with the grammar in question.
It has no direct formal specification beyond what was said above.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
one possible CONTAINER serialization for it is
snit::type a_pe_grammar {
constructor {} {
install myg using pt::peg::container ${selfns}::G
$myg start {n Expression}
$myg add AddOp Digit Expression Factor MulOp Number Sign Term
$myg modes {
AddOp value
Digit value
Expression value
Factor value
MulOp value
Number value
Sign value
Term value
}
$myg rules {
AddOp {/ {t -} {t +}}
Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
Factor {x {n Term} {* {x {n AddOp} {n Term}}}}
MulOp {/ {t *} {t /}}
Number {x {? {n Sign}} {+ {n Digit}}}
Sign {/ {t -} {t +}}
Term {n Number}
}
return
}
component myg
delegate method * to myg
}
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[CONTAINER](../../../../index.md#container), [EBNF](../../../../index.md#ebnf),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
|
[//000000001]: # (pt::peg::to::cparam - Parser Tools)
[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::to::cparam(n) 1.1.2 tcllib "Parser Tools")
# NAME
pt::peg::to::cparam - PEG Conversion. Write CPARAM format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [C/PARAM code representation of parsing expression grammars](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::to::cparam ?1.1.2?
[__pt::peg::to::cparam__ __reset__](#1)
[__pt::peg::to::cparam__ __configure__](#2)
[__pt::peg::to::cparam__ __configure__ *option*](#3)
[__pt::peg::to::cparam__ __configure__ *option* *value*...](#4)
[__pt::peg::to::cparam__ __convert__ *serial*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from parsing expression grammars to CPARAM
markup.
It resides in the Export section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the export manager provided by __[pt::peg::export](pt_peg_export.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding export plugin __pt::peg::export::cparam__ sitting between
converter and export manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__pt::peg::to::cparam__ __reset__
This command resets the configuration of the package to its default
settings.
- <a name='2'></a>__pt::peg::to::cparam__ __configure__
This command returns a dictionary containing the current configuration of
the package.
- <a name='3'></a>__pt::peg::to::cparam__ __configure__ *option*
This command returns the current value of the specified configuration
*option* of the package. For the set of legal options, please read the
section [Options](#section3).
- <a name='4'></a>__pt::peg::to::cparam__ __configure__ *option* *value*...
This command sets the given configuration *option*s of the package, to the
specified *value*s. For the set of legal options, please read the section
[Options](#section3).
- <a name='5'></a>__pt::peg::to::cparam__ __convert__ *serial*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, and generates CPARAM markup encoding the grammar, per
the current package configuration. The created string is then returned as
the result of the command.
# <a name='section3'></a>Options
The converter to C code recognizes the following configuration variables and
changes its behaviour as they specify.
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-template__ string
The value of this option is a string into which to put the generated text
and the other configuration settings. The various locations for user-data
are expected to be specified with the placeholders listed below. The default
value is "__@code@__".
* __@user@__
To be replaced with the value of the option __-user__.
* __@format@__
To be replaced with the the constant __C/PARAM__.
* __@file@__
To be replaced with the value of the option __-file__.
* __@name@__
To be replaced with the value of the option __-name__.
* __@code@__
To be replaced with the generated Tcl code.
The following options are special, in that they will occur within the
generated code, and are replaced there as well.
* __@statedecl@__
To be replaced with the value of the option __state-decl__.
* __@stateref@__
To be replaced with the value of the option __state-ref__.
* __@strings@__
To be replaced with the value of the option __string-varname__.
* __@self@__
To be replaced with the value of the option __self-command__.
* __@def@__
To be replaced with the value of the option __fun-qualifier__.
* __@ns@__
To be replaced with the value of the option __namespace__.
* __@main@__
To be replaced with the value of the option __main__.
* __@prelude@__
To be replaced with the value of the option __prelude__.
- __-state-decl__ string
A C string representing the argument declaration to use in the generated
parsing functions to refer to the parsing state. In essence type and
argument name. The default value is the string __RDE_PARAM p__.
- __-state-ref__ string
A C string representing the argument named used in the generated parsing
functions to refer to the parsing state. The default value is the string
__p__.
- __-self-command__ string
A C string representing the reference needed to call the generated parser
function (methods ...) from another parser fonction, per the chosen
framework (template). The default value is the empty string.
- __-fun-qualifier__ string
A C string containing the attributes to give to the generated functions
(methods ...), per the chosen framework (template). The default value is
__static__.
- __-namespace__ string
The name of the C namespace the parser functions (methods, ...) shall reside
in, or a general prefix to add to the function names. The default value is
the empty string.
- __-main__ string
The name of the main function (method, ...) to be called by the chosen
framework (template) to start parsing input. The default value is
____main__.
- __-string-varname__ string
The name of the variable used for the table of strings used by the generated
parser, i.e. error messages, symbol names, etc. The default value is
__p_string__.
- __-prelude__ string
A snippet of code to be inserted at the head of each generated parsing
function. The default value is the empty string.
- __-indent__ integer
The number of characters to indent each line of the generated code by. The
default value is __0__.
- __-comments__ boolean
A flag controlling the generation of code comments containing the original
parsing expression a parsing function is for. The default value is __on__.
While the high parameterizability of this converter, as shown by the multitude
of options it supports, is an advantage to the advanced user, allowing her to
customize the output of the converter as needed, a novice user will likely not
see the forest for the trees.
To help these latter users an adjunct package is provided, containing a canned
configuration which will generate immediately useful full parsers. It is
- __[pt::cparam::configuration::critcl](pt_cparam_config_critcl.md)__
Generated parsers are embedded into a __Critcl__-based framework.
# <a name='section4'></a>C/PARAM code representation of parsing expression grammars
The __c__ format is executable code, a parser for the grammar. The parser
implementation is written in C and can be tweaked to the users' needs through a
multitude of options.
The __critcl__ format, for example, is implemented as a canned configuration of
these options on top of the generator for __c__.
The bulk of such a framework has to be specified through the option
__-template__. The additional options
- __-fun-qualifier__ string
- __-main__ string
- __-namespace__ string
- __-prelude__ string
- __-self-command__ string
- __-state-decl__ string
- __-state-ref__ string
- __-string-varname__ string
provide code snippets which help to glue framework and generated code together.
Their placeholders are in the *generated* code. Further the options
- __-indent__ integer
- __-comments__ boolean
allow for the customization of the code indent (default none), and whether to
generate comments showing the parsing expressions a function is for (default
on).
## <a name='subsection1'></a>Example
We are forgoing an example of this representation, with apologies. It would be
way to large for this document.
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[CPARAM](../../../../index.md#cparam), [EBNF](../../../../index.md#ebnf),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
|
[//000000001]: # (pt::peg::to::json - Parser Tools)
[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::to::json(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::to::json - PEG Conversion. Write JSON format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [JSON Grammar Exchange Format](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::to::json ?1?
package require pt::peg
package require json::write
[__pt::peg::to::json__ __reset__](#1)
[__pt::peg::to::json__ __configure__](#2)
[__pt::peg::to::json__ __configure__ *option*](#3)
[__pt::peg::to::json__ __configure__ *option* *value*...](#4)
[__pt::peg::to::json__ __convert__ *serial*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from parsing expression grammars to JSON
markup.
It resides in the Export section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the export manager provided by __[pt::peg::export](pt_peg_export.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding export plugin __[pt::peg::export::json](pt_peg_export_json.md)__
sitting between converter and export manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__pt::peg::to::json__ __reset__
This command resets the configuration of the package to its default
settings.
- <a name='2'></a>__pt::peg::to::json__ __configure__
This command returns a dictionary containing the current configuration of
the package.
- <a name='3'></a>__pt::peg::to::json__ __configure__ *option*
This command returns the current value of the specified configuration
*option* of the package. For the set of legal options, please read the
section [Options](#section3).
- <a name='4'></a>__pt::peg::to::json__ __configure__ *option* *value*...
This command sets the given configuration *option*s of the package, to the
specified *value*s. For the set of legal options, please read the section
[Options](#section3).
- <a name='5'></a>__pt::peg::to::json__ __convert__ *serial*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, and generates JSON markup encoding the grammar, per
the current package configuration. The created string is then returned as
the result of the command.
# <a name='section3'></a>Options
The converter to the JSON grammar exchange format recognizes the following
configuration variables and changes its behaviour as they specify.
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-indented__ boolean
If this option is set the system will break the generated JSON across lines
and indent it according to its inner structure, with each key of a
dictionary on a separate line.
If the option is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.
- __-aligned__ boolean
If this option is set the system will ensure that the values for the keys in
a dictionary are vertically aligned with each other, for a nice table
effect. To make this work this also implies that __-indented__ is set.
If the option is not set (the default), the output is formatted as per the
value of __indented__, without trying to align the values for dictionary
keys.
# <a name='section4'></a>JSON Grammar Exchange Format
The __json__ format for parsing expression grammars was written as a data
exchange format not bound to Tcl. It was defined to allow the exchange of
grammars with PackRat/PEG based parser generators for other languages.
It is formally specified by the rules below:
1. The JSON of any PEG is a JSON object.
1. This object holds a single key, __pt::grammar::peg__, and its value. This
value holds the contents of the grammar.
1. The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are
- __rules__
The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a JSON object itself. The relevant keys
and their values in this dictionary are
* __is__
The value is a JSON string holding the Tcl serialization of
the parsing expression describing the symbols sentennial
structure, as specified in the section [PE serialization
format](#section6).
* __mode__
The value is a JSON holding holding one of three values
specifying how a parser should handle the semantic value
produced by the symbol.
+ __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal itself, which has the ASTs of the symbol's
right hand side as its children.
+ __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node for
the nonterminal, without any children. Any ASTs generated
by the symbol's right hand side are discarded.
+ __void__
The nonterminal has no semantic value. Any ASTs generated
by the symbol's right hand side are discarded (as well).
- __start__
The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section [PE
serialization format](#section6).
1. The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
As an aside to the advanced reader, this is pretty much the same as the Tcl
serialization of PE grammars, as specified in section [PEG serialization
format](#section5), except that the Tcl dictionaries and lists of that format
are mapped to JSON objects and arrays. Only the parsing expressions themselves
are not translated further, but kept as JSON strings containing a nested Tcl
list, and there is no concept of canonicity for the JSON either.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
a JSON serialization for it is
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
and a Tcl serialization of the same is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
The similarity of the latter to the JSON should be quite obvious.
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [JSON](../../../../index.md#json),
[LL(k)](../../../../index.md#ll_k_), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
|
[//000000001]: # (pt::peg::to::param - Parser Tools)
[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::to::param(n) 1 tcllib "Parser Tools")
# NAME
pt::peg::to::param - PEG Conversion. Write PARAM format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [PARAM code representation of parsing expression grammars](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::to::param ?1?
package require pt::peg
package require pt::pe
[__pt::peg::to::param__ __reset__](#1)
[__pt::peg::to::param__ __configure__](#2)
[__pt::peg::to::param__ __configure__ *option*](#3)
[__pt::peg::to::param__ __configure__ *option* *value*...](#4)
[__pt::peg::to::param__ __convert__ *serial*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from parsing expression grammars to PARAM
markup.
It resides in the Export section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the export manager provided by __[pt::peg::export](pt_peg_export.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding export plugin __pt::peg::export::param__ sitting between converter
and export manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__pt::peg::to::param__ __reset__
This command resets the configuration of the package to its default
settings.
- <a name='2'></a>__pt::peg::to::param__ __configure__
This command returns a dictionary containing the current configuration of
the package.
- <a name='3'></a>__pt::peg::to::param__ __configure__ *option*
This command returns the current value of the specified configuration
*option* of the package. For the set of legal options, please read the
section [Options](#section3).
- <a name='4'></a>__pt::peg::to::param__ __configure__ *option* *value*...
This command sets the given configuration *option*s of the package, to the
specified *value*s. For the set of legal options, please read the section
[Options](#section3).
- <a name='5'></a>__pt::peg::to::param__ __convert__ *serial*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, and generates PARAM markup encoding the grammar, per
the current package configuration. The created string is then returned as
the result of the command.
# <a name='section3'></a>Options
The converter to PARAM markup recognizes the following configuration variables
and changes its behaviour as they specify.
- __-template__ string
The value of this configuration variable is a string into which to put the
generated text and the other configuration settings. The various locations
for user-data are expected to be specified with the placeholders listed
below. The default value is "__@code@__".
* __@user@__
To be replaced with the value of the configuration variable __-user__.
* __@format@__
To be replaced with the the constant __PARAM__.
* __@file@__
To be replaced with the value of the configuration variable __-file__.
* __@name@__
To be replaced with the value of the configuration variable __-name__.
* __@code@__
To be replaced with the generated text.
- __-name__ string
The value of this configuration variable is the name of the grammar for
which the conversion is run. The default value is __a_pe_grammar__.
- __-user__ string
The value of this configuration variable is the name of the user for which
the conversion is run. The default value is __unknown__.
- __-file__ string
The value of this configuration variable is the name of the file or other
entity from which the grammar came, for which the conversion is run. The
default value is __unknown__.
# <a name='section4'></a>PARAM code representation of parsing expression grammars
The PARAM code representation of parsing expression grammars is assembler-like
text using the instructions of the virtual machine documented in the *[PackRat
Machine Specification](pt_param.md)*, plus a few more for control flow (jump ok,
jump fail, call symbol, return).
It is not really useful, except possibly as a tool demonstrating how a grammar
is compiled in general, without getting distracted by the incidentials of a
framework, i.e. like the supporting C and Tcl code generated by the other
PARAM-derived formats.
It has no direct formal specification beyond what was said above.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
one possible PARAM serialization for it is
# -*- text -*-
# Parsing Expression Grammar 'TEMPLATE'.
# Generated for unknown, from file 'TEST'
#
# Grammar Start Expression
#
<<MAIN>>:
call sym_Expression
halt
#
# value Symbol 'AddOp'
#
sym_AddOp:
# /
# '-'
# '+'
symbol_restore AddOp
found! jump found_7
loc_push
call choice_5
fail! value_clear
ok! value_leaf AddOp
symbol_save AddOp
error_nonterminal AddOp
loc_pop_discard
found_7:
ok! ast_value_push
return
choice_5:
# /
# '-'
# '+'
error_clear
loc_push
error_push
input_next "t -"
ok! test_char "-"
error_pop_merge
ok! jump oknoast_4
loc_pop_rewind
loc_push
error_push
input_next "t +"
ok! test_char "+"
error_pop_merge
ok! jump oknoast_4
loc_pop_rewind
status_fail
return
oknoast_4:
loc_pop_discard
return
#
# value Symbol 'Digit'
#
sym_Digit:
# /
# '0'
# '1'
# '2'
# '3'
# '4'
# '5'
# '6'
# '7'
# '8'
# '9'
symbol_restore Digit
found! jump found_22
loc_push
call choice_20
fail! value_clear
ok! value_leaf Digit
symbol_save Digit
error_nonterminal Digit
loc_pop_discard
found_22:
ok! ast_value_push
return
choice_20:
# /
# '0'
# '1'
# '2'
# '3'
# '4'
# '5'
# '6'
# '7'
# '8'
# '9'
error_clear
loc_push
error_push
input_next "t 0"
ok! test_char "0"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 1"
ok! test_char "1"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 2"
ok! test_char "2"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 3"
ok! test_char "3"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 4"
ok! test_char "4"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 5"
ok! test_char "5"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 6"
ok! test_char "6"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 7"
ok! test_char "7"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 8"
ok! test_char "8"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 9"
ok! test_char "9"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
status_fail
return
oknoast_19:
loc_pop_discard
return
#
# value Symbol 'Expression'
#
sym_Expression:
# /
# x
# '\('
# (Expression)
# '\)'
# x
# (Factor)
# *
# x
# (MulOp)
# (Factor)
symbol_restore Expression
found! jump found_46
loc_push
ast_push
call choice_44
fail! value_clear
ok! value_reduce Expression
symbol_save Expression
error_nonterminal Expression
ast_pop_rewind
loc_pop_discard
found_46:
ok! ast_value_push
return
choice_44:
# /
# x
# '\('
# (Expression)
# '\)'
# x
# (Factor)
# *
# x
# (MulOp)
# (Factor)
error_clear
ast_push
loc_push
error_push
call sequence_27
error_pop_merge
ok! jump ok_43
ast_pop_rewind
loc_pop_rewind
ast_push
loc_push
error_push
call sequence_40
error_pop_merge
ok! jump ok_43
ast_pop_rewind
loc_pop_rewind
status_fail
return
ok_43:
ast_pop_discard
loc_pop_discard
return
sequence_27:
# x
# '\('
# (Expression)
# '\)'
loc_push
error_clear
error_push
input_next "t ("
ok! test_char "("
error_pop_merge
fail! jump failednoast_29
ast_push
error_push
call sym_Expression
error_pop_merge
fail! jump failed_28
error_push
input_next "t )"
ok! test_char ")"
error_pop_merge
fail! jump failed_28
ast_pop_discard
loc_pop_discard
return
failed_28:
ast_pop_rewind
failednoast_29:
loc_pop_rewind
return
sequence_40:
# x
# (Factor)
# *
# x
# (MulOp)
# (Factor)
ast_push
loc_push
error_clear
error_push
call sym_Factor
error_pop_merge
fail! jump failed_41
error_push
call kleene_37
error_pop_merge
fail! jump failed_41
ast_pop_discard
loc_pop_discard
return
failed_41:
ast_pop_rewind
loc_pop_rewind
return
kleene_37:
# *
# x
# (MulOp)
# (Factor)
loc_push
error_push
call sequence_34
error_pop_merge
fail! jump failed_38
loc_pop_discard
jump kleene_37
failed_38:
loc_pop_rewind
status_ok
return
sequence_34:
# x
# (MulOp)
# (Factor)
ast_push
loc_push
error_clear
error_push
call sym_MulOp
error_pop_merge
fail! jump failed_35
error_push
call sym_Factor
error_pop_merge
fail! jump failed_35
ast_pop_discard
loc_pop_discard
return
failed_35:
ast_pop_rewind
loc_pop_rewind
return
#
# value Symbol 'Factor'
#
sym_Factor:
# x
# (Term)
# *
# x
# (AddOp)
# (Term)
symbol_restore Factor
found! jump found_60
loc_push
ast_push
call sequence_57
fail! value_clear
ok! value_reduce Factor
symbol_save Factor
error_nonterminal Factor
ast_pop_rewind
loc_pop_discard
found_60:
ok! ast_value_push
return
sequence_57:
# x
# (Term)
# *
# x
# (AddOp)
# (Term)
ast_push
loc_push
error_clear
error_push
call sym_Term
error_pop_merge
fail! jump failed_58
error_push
call kleene_54
error_pop_merge
fail! jump failed_58
ast_pop_discard
loc_pop_discard
return
failed_58:
ast_pop_rewind
loc_pop_rewind
return
kleene_54:
# *
# x
# (AddOp)
# (Term)
loc_push
error_push
call sequence_51
error_pop_merge
fail! jump failed_55
loc_pop_discard
jump kleene_54
failed_55:
loc_pop_rewind
status_ok
return
sequence_51:
# x
# (AddOp)
# (Term)
ast_push
loc_push
error_clear
error_push
call sym_AddOp
error_pop_merge
fail! jump failed_52
error_push
call sym_Term
error_pop_merge
fail! jump failed_52
ast_pop_discard
loc_pop_discard
return
failed_52:
ast_pop_rewind
loc_pop_rewind
return
#
# value Symbol 'MulOp'
#
sym_MulOp:
# /
# '*'
# '/'
symbol_restore MulOp
found! jump found_67
loc_push
call choice_65
fail! value_clear
ok! value_leaf MulOp
symbol_save MulOp
error_nonterminal MulOp
loc_pop_discard
found_67:
ok! ast_value_push
return
choice_65:
# /
# '*'
# '/'
error_clear
loc_push
error_push
input_next "t *"
ok! test_char "*"
error_pop_merge
ok! jump oknoast_64
loc_pop_rewind
loc_push
error_push
input_next "t /"
ok! test_char "/"
error_pop_merge
ok! jump oknoast_64
loc_pop_rewind
status_fail
return
oknoast_64:
loc_pop_discard
return
#
# value Symbol 'Number'
#
sym_Number:
# x
# ?
# (Sign)
# +
# (Digit)
symbol_restore Number
found! jump found_80
loc_push
ast_push
call sequence_77
fail! value_clear
ok! value_reduce Number
symbol_save Number
error_nonterminal Number
ast_pop_rewind
loc_pop_discard
found_80:
ok! ast_value_push
return
sequence_77:
# x
# ?
# (Sign)
# +
# (Digit)
ast_push
loc_push
error_clear
error_push
call optional_70
error_pop_merge
fail! jump failed_78
error_push
call poskleene_73
error_pop_merge
fail! jump failed_78
ast_pop_discard
loc_pop_discard
return
failed_78:
ast_pop_rewind
loc_pop_rewind
return
optional_70:
# ?
# (Sign)
loc_push
error_push
call sym_Sign
error_pop_merge
fail! loc_pop_rewind
ok! loc_pop_discard
status_ok
return
poskleene_73:
# +
# (Digit)
loc_push
call sym_Digit
fail! jump failed_74
loop_75:
loc_pop_discard
loc_push
error_push
call sym_Digit
error_pop_merge
ok! jump loop_75
status_ok
failed_74:
loc_pop_rewind
return
#
# value Symbol 'Sign'
#
sym_Sign:
# /
# '-'
# '+'
symbol_restore Sign
found! jump found_86
loc_push
call choice_5
fail! value_clear
ok! value_leaf Sign
symbol_save Sign
error_nonterminal Sign
loc_pop_discard
found_86:
ok! ast_value_push
return
#
# value Symbol 'Term'
#
sym_Term:
# (Number)
symbol_restore Term
found! jump found_89
loc_push
ast_push
call sym_Number
fail! value_clear
ok! value_reduce Term
symbol_save Term
error_nonterminal Term
ast_pop_rewind
loc_pop_discard
found_89:
ok! ast_value_push
return
#
#
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PARAM](../../../../index.md#param), [PEG](../../../../index.md#peg),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
|
[//000000001]: # (pt::peg::to::peg - Parser Tools)
[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::to::peg(n) 1.0.2 tcllib "Parser Tools")
# NAME
pt::peg::to::peg - PEG Conversion. Write PEG format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [PEG Specification Language](#section4)
- [Example](#subsection1)
- [PEG serialization format](#section5)
- [Example](#subsection2)
- [PE serialization format](#section6)
- [Example](#subsection3)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::to::peg ?1.0.2?
package require pt::peg
package require pt::pe
package require text::write
[__pt::peg::to::peg__ __reset__](#1)
[__pt::peg::to::peg__ __configure__](#2)
[__pt::peg::to::peg__ __configure__ *option*](#3)
[__pt::peg::to::peg__ __configure__ *option* *value*...](#4)
[__pt::peg::to::peg__ __convert__ *serial*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from parsing expression grammars to PEG
markup.
It resides in the Export section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the export manager provided by __[pt::peg::export](pt_peg_export.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding export plugin __[pt::peg::export::peg](pt_peg_export_peg.md)__
sitting between converter and export manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__pt::peg::to::peg__ __reset__
This command resets the configuration of the package to its default
settings.
- <a name='2'></a>__pt::peg::to::peg__ __configure__
This command returns a dictionary containing the current configuration of
the package.
- <a name='3'></a>__pt::peg::to::peg__ __configure__ *option*
This command returns the current value of the specified configuration
*option* of the package. For the set of legal options, please read the
section [Options](#section3).
- <a name='4'></a>__pt::peg::to::peg__ __configure__ *option* *value*...
This command sets the given configuration *option*s of the package, to the
specified *value*s. For the set of legal options, please read the section
[Options](#section3).
- <a name='5'></a>__pt::peg::to::peg__ __convert__ *serial*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, and generates PEG markup encoding the grammar, per
the current package configuration. The created string is then returned as
the result of the command.
# <a name='section3'></a>Options
The converter to the PEG language recognizes the following options and changes
its behaviour as they specify.
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
- __-template__ string
The value of this option is a string into which to put the generated text
and the values of the other options. The various locations for user-data are
expected to be specified with the placeholders listed below. The default
value is "__@code@__".
* __@user@__
To be replaced with the value of the option __-user__.
* __@format@__
To be replaced with the the constant __PEG__.
* __@file@__
To be replaced with the value of the option __-file__.
* __@name@__
To be replaced with the value of the option __-name__.
* __@code@__
To be replaced with the generated text.
# <a name='section4'></a>PEG Specification Language
__peg__, a language for the specification of parsing expression grammars is
meant to be human readable, and writable as well, yet strict enough to allow its
processing by machine. Like any computer language. It was defined to make
writing the specification of a grammar easy, something the other formats found
in the Parser Tools do not lend themselves too.
It is formally specified by the grammar shown below, written in itself. For a
tutorial / introduction to the language please go and read the *[PEG Language
Tutorial](pt_peg_language.md)*.
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
## <a name='subsection1'></a>Example
Our example specifies the grammar for a basic 4-operation calculator.
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
Using higher-level features of the notation, i.e. the character classes
(predefined and custom), this example can be rewritten as
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection2'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection3'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
|
[//000000001]: # (pt::peg::to::tclparam - Parser Tools)
[//000000002]: # (Generated from file 'to.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg::to::tclparam(n) 1.0.3 tcllib "Parser Tools")
# NAME
pt::peg::to::tclparam - PEG Conversion. Write TCLPARAM format
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [Tcl/PARAM code representation of parsing expression grammars](#section4)
- [PEG serialization format](#section5)
- [Example](#subsection1)
- [PE serialization format](#section6)
- [Example](#subsection2)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg::to::tclparam ?1.0.3?
[__pt::peg::to::tclparam__ __reset__](#1)
[__pt::peg::to::tclparam__ __configure__](#2)
[__pt::peg::to::tclparam__ __configure__ *option*](#3)
[__pt::peg::to::tclparam__ __configure__ *option* *value*...](#4)
[__pt::peg::to::tclparam__ __convert__ *serial*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package implements the converter from parsing expression grammars to
TCLPARAM markup.
It resides in the Export section of the Core Layer of Parser Tools, and can be
used either directly with the other packages of this layer, or indirectly
through the export manager provided by __[pt::peg::export](pt_peg_export.md)__.
The latter is intented for use in untrusted environments and done through the
corresponding export plugin __pt::peg::export::tclparam__ sitting between
converter and export manager.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of the Converter
API found in the *[Parser Tools Export API](pt_to_api.md)* specification.
- <a name='1'></a>__pt::peg::to::tclparam__ __reset__
This command resets the configuration of the package to its default
settings.
- <a name='2'></a>__pt::peg::to::tclparam__ __configure__
This command returns a dictionary containing the current configuration of
the package.
- <a name='3'></a>__pt::peg::to::tclparam__ __configure__ *option*
This command returns the current value of the specified configuration
*option* of the package. For the set of legal options, please read the
section [Options](#section3).
- <a name='4'></a>__pt::peg::to::tclparam__ __configure__ *option* *value*...
This command sets the given configuration *option*s of the package, to the
specified *value*s. For the set of legal options, please read the section
[Options](#section3).
- <a name='5'></a>__pt::peg::to::tclparam__ __convert__ *serial*
This command takes the canonical serialization of a parsing expression
grammar, as specified in section [PEG serialization format](#section5), and
contained in *serial*, and generates TCLPARAM markup encoding the grammar,
per the current package configuration. The created string is then returned
as the result of the command.
# <a name='section3'></a>Options
The converter to Tcl/PARAM markup recognizes the following configuration
variables and changes its behaviour as they specify.
- __-template__ string
The value of this configuration variable is a string into which to put the
generated text and the other configuration settings. The various locations
for user-data are expected to be specified with the placeholders listed
below. The default value is "__@code@__".
* __@user@__
To be replaced with the value of the configuration variable __-user__.
* __@format@__
To be replaced with the the constant __Tcl/PARAM__.
* __@file@__
To be replaced with the value of the configuration variable __-file__.
* __@name@__
To be replaced with the value of the configuration variable __-name__.
* __@code@__
To be replaced with the generated Tcl code.
The following configuration variables are special, in that they will occur
within the generated code, and are replaced there as well.
* __@runtime@__
To be replaced with the value of the configuration variable
__runtime-command__.
* __@self@__
To be replaced with the value of the configuration variable
__self-command__.
* __@def@__
To be replaced with the value of the configuration variable
__proc-command__.
* __@ns@__
To be replaced with the value of the configuration variable
__namespace__.
* __@main@__
To be replaced with the value of the configuration variable __main__.
* __@prelude@__
To be replaced with the value of the configuration variable __prelude__.
- __-name__ string
The value of this configuration variable is the name of the grammar for
which the conversion is run. The default value is __a_pe_grammar__.
- __-user__ string
The value of this configuration variable is the name of the user for which
the conversion is run. The default value is __unknown__.
- __-file__ string
The value of this configuration variable is the name of the file or other
entity from which the grammar came, for which the conversion is run. The
default value is __unknown__.
- __-runtime-command__ string
A Tcl string representing the Tcl command or reference to it used to call
PARAM instruction from parser procedures, per the chosen framework
(template). The default value is the empty string.
- __-self-command__ string
A Tcl string representing the Tcl command or reference to it used to call
the parser procedures (methods ...) from another parser procedure, per the
chosen framework (template). The default value is the empty string.
- __-proc-command__ string
The name of the Tcl command used to define procedures (methods ...), per the
chosen framework (template). The default value is __proc__.
- __-namespace__ string
The name of the namespace the parser procedures (methods, ...) shall reside
in, including the trailing '::' needed to separate it from the actual
procedure name. The default value is __::__.
- __-main__ string
The name of the main procedure (method, ...) to be called by the chosen
framework (template) to start parsing input. The default value is
____main__.
- __-prelude__ string
A snippet of code to be insert at the head of each generated parsing
command. The default value is the empty string.
- __-indent__ integer
The number of characters to indent each line of the generated code by. The
default value is __0__.
While the high parameterizability of this converter, as shown by the multitude
of options it supports, is an advantage to the advanced user, allowing her to
customize the output of the converter as needed, a novice user will likely not
see the forest for the trees.
To help these latter users two adjunct packages are provided, each containing a
canned configuration which will generate immediately useful full parsers. These
are
- __[pt::tclparam::configuration::snit](pt_tclparam_config_snit.md)__
Generated parsers are classes based on the __[snit](../snit/snit.md)__
package, i.e. snit::type's.
- __[pt::tclparam::configuration::tcloo](pt_tclparam_config_tcloo.md)__
Generated parsers are classes based on the __OO__ package.
# <a name='section4'></a>Tcl/PARAM code representation of parsing expression grammars
The Tcl/PARAM representation of parsing expression grammars is Tcl code whose
execution will parse input per the grammar. The code is based on the virtual
machine documented in the *[PackRat Machine Specification](pt_param.md)*, using
its instructions and a few more to handle control flow.
Note that the generated code by itself is not functional. It expects to be
embedded into a framework which provides services like the PARAM state,
implementations for the PARAM instructions, etc. The bulk of such a framework
has to be specified through the option __-template__. The additional options
- __-indent__ integer
- __-main__ string
- __-namespace__ string
- __-prelude__ string
- __-proc-command__ string
- __-runtime-command__ string
- __-self-command__ string
provide code snippets which help to glue framework and generated code together.
Their placeholders are in the *generated* code.
# <a name='section5'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section6).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section6).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section6'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection2'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TCLPARAM](../../../../index.md#tclparam),
[TDPL](../../../../index.md#tdpl), [context-free
languages](../../../../index.md#context_free_languages),
[conversion](../../../../index.md#conversion),
[expression](../../../../index.md#expression), [format
conversion](../../../../index.md#format_conversion),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[serialization](../../../../index.md#serialization),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_pegrammar.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
|
[//000000001]: # (pt::peg - Parser Tools)
[//000000002]: # (Generated from file 'pt_pegrammar.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::peg(n) 1 tcllib "Parser Tools")
# NAME
pt::peg - Parsing Expression Grammar Serialization
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [PEG serialization format](#section3)
- [Example](#subsection1)
- [PE serialization format](#section4)
- [Example](#subsection2)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::peg ?1?
package require pt::pe
[__::pt::peg__ __verify__ *serial* ?*canonvar*?](#1)
[__::pt::peg__ __verify-as-canonical__ *serial*](#2)
[__::pt::peg__ __canonicalize__ *serial*](#3)
[__::pt::peg__ __print__ *serial*](#4)
[__::pt::peg__ __merge__ *seriala* *serialb*](#5)
[__::pt::peg__ __equal__ *seriala* *serialb*](#6)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides commands to work with the serializations of parsing
expression grammars as managed by the Parser Tools, and specified in section
[PEG serialization format](#section3).
This is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::peg__ __verify__ *serial* ?*canonvar*?
This command verifies that the content of *serial* is a valid serialization
of a parsing expression and will throw an error if that is not the case. The
result of the command is the empty string.
If the argument *canonvar* is specified it is interpreted as the name of a
variable in the calling context. This variable will be written to if and
only if *serial* is a valid regular serialization. Its value will be a
boolean, with __True__ indicating that the serialization is not only valid,
but also *canonical*. __False__ will be written for a valid, but
non-canonical serialization.
For the specification of serializations see the section [PE serialization
format](#section4).
- <a name='2'></a>__::pt::peg__ __verify-as-canonical__ *serial*
This command verifies that the content of *serial* is a valid *canonical*
serialization of a PEG and will throw an error if that is not the case. The
result of the command is the empty string.
For the specification of canonical serializations see the section [PEG
serialization format](#section3).
- <a name='3'></a>__::pt::peg__ __canonicalize__ *serial*
This command assumes that the content of *serial* is a valid *regular*
serialization of a PEG and will throw an error if that is not the case.
It will then convert the input into the *canonical* serialization of the
contained PEG and return it as its result. If the input is already canonical
it will be returned unchanged.
For the specification of regular and canonical serializations see the
section [PEG serialization format](#section3).
- <a name='4'></a>__::pt::peg__ __print__ *serial*
This command assumes that the argument *serial* contains a valid
serialization of a parsing expression and returns a string containing that
PE in a human readable form.
The exact format of this form is not specified and cannot be relied on for
parsing or other machine-based activities.
For the specification of serializations see the section [PEG serialization
format](#section3).
- <a name='5'></a>__::pt::peg__ __merge__ *seriala* *serialb*
This command accepts the regular serializations of two grammars and uses
them to create their union. The result of the command is the canonical
serialization of this unified grammar.
A merge errors occurs if for any nonterminal symbol S occuring in both input
grammars the two input grammars specify different semantic modes.
The semantic mode of each nonterminal symbol S is the semantic mode of S in
any of its input grammars. The previous rule made sure that for symbols
occuring in both grammars these values are identical.
The right-hand side of each nonterminal symbol S occuring in both input
grammars is the choice between the right-hand sides of S in the input
grammars, with the parsing expression of S in *seriala* coming first, except
if both expressions are identical. In that case the first expression is
taken.
The right-hand side of each nonterminal symbol S occuring in only one of the
input grammars is the right-hand side of S in its input grammar.
The start expression of the unified grammar is the choice between the start
expressions of the input grammars, with the start expression of *seriala*
coming first, except if both expressions are identical. In that case the
first expression is taken
- <a name='6'></a>__::pt::peg__ __equal__ *seriala* *serialb*
This command tests the two grammars *seriala* and *serialb* for structural
equality. The result of the command is a boolean value. It will be set to
__true__ if the expressions are identical, and __false__ otherwise.
String equality is usable only if we can assume that the two grammars are
pure Tcl lists and dictionaries.
# <a name='section3'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section4).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section4).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section4'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection2'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
[//000000001]: # (pt::pe::op - Parser Tools)
[//000000002]: # (Generated from file 'pt_pexpr_op.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::pe::op(n) 1.0.1 tcllib "Parser Tools")
# NAME
pt::pe::op - Parsing Expression Utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [PE serialization format](#section3)
- [Example](#subsection1)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::pe::op ?1.0.1?
package require pt::pe ?1?
package require struct::set
[__::pt::pe::op__ __drop__ *dropset* *pe*](#1)
[__::pt::pe::op__ __rename__ *nt* *ntnew* *pe*](#2)
[__::pt::pe::op__ __called__ *pe*](#3)
[__::pt::pe::op__ __flatten__ *pe*](#4)
[__::pt::pe::op__ __fusechars__ *pe*](#5)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides additional commands to work with the serializations of
parsing expressions as managed by the PEG and related packages, and specified in
section [PE serialization format](#section3).
This is an internal package, for use by the higher level packages handling PEGs,
their conversion into and out of various other formats, or other uses.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::pe::op__ __drop__ *dropset* *pe*
This command removes all occurences of any of the nonterminals symbols in
the set *dropset* from the parsing expression *pe*, and simplifies it. This
may result in the expression becoming "epsilon", i.e. matching nothing.
- <a name='2'></a>__::pt::pe::op__ __rename__ *nt* *ntnew* *pe*
This command renames all occurences of the nonterminal *nt* in the parsing
expression *pe* into *ntnew*.
- <a name='3'></a>__::pt::pe::op__ __called__ *pe*
This command extracts the set of all nonterminal symbols used, i.e.
'called', in the parsing expression *pe*.
- <a name='4'></a>__::pt::pe::op__ __flatten__ *pe*
This command transforms the parsing expression by eliminating sequences
nested in sequences, and choices in choices, lifting the children of the
nested expression into the parent. It further eliminates all sequences and
choices with only one child, as these are redundant.
The resulting parsing expression is returned as the result of the command.
- <a name='5'></a>__::pt::pe::op__ __fusechars__ *pe*
This command transforms the parsing expression by fusing adjacent terminals
in sequences and adjacent terminals and ranges in choices, it (re)constructs
highlevel *strings* and *character classes*.
The resulting pseudo-parsing expression is returned as the result of the
command and may contain the pseudo-operators __str__ for character
sequences, aka strings, and __cl__ for character choices, aka character
classes.
The result is called a *pseudo-parsing expression* because it is not a true
parsing expression anymore, and will fail a check with __::pt::peg verify__
if the new pseudo-operators are present in the result, but is otherwise of
sound structure for a parsing expression. Notably, the commands __::pt::peg
bottomup__ and __::pt::peg topdown__ will process them without trouble.
# <a name='section3'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection1'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_pexpression.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
|
[//000000001]: # (pt::pe - Parser Tools)
[//000000002]: # (Generated from file 'pt_pexpression.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::pe(n) 1.0.1 tcllib "Parser Tools")
# NAME
pt::pe - Parsing Expression Serialization
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [PE serialization format](#section3)
- [Example](#subsection1)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::pe ?1.0.1?
package require char
[__::pt::pe__ __verify__ *serial* ?*canonvar*?](#1)
[__::pt::pe__ __verify-as-canonical__ *serial*](#2)
[__::pt::pe__ __canonicalize__ *serial*](#3)
[__::pt::pe__ __print__ *serial*](#4)
[__::pt::pe__ __bottomup__ *cmdprefix* *pe*](#5)
[__cmdprefix__ *pe* *op* *arguments*](#6)
[__::pt::pe__ __topdown__ *cmdprefix* *pe*](#7)
[__::pt::pe__ __equal__ *seriala* *serialb*](#8)
[__::pt::pe__ __epsilon__](#9)
[__::pt::pe__ __dot__](#10)
[__::pt::pe__ __alnum__](#11)
[__::pt::pe__ __alpha__](#12)
[__::pt::pe__ __ascii__](#13)
[__::pt::pe__ __control__](#14)
[__::pt::pe__ __digit__](#15)
[__::pt::pe__ __graph__](#16)
[__::pt::pe__ __lower__](#17)
[__::pt::pe__ __print__](#18)
[__::pt::pe__ __punct__](#19)
[__::pt::pe__ __space__](#20)
[__::pt::pe__ __upper__](#21)
[__::pt::pe__ __wordchar__](#22)
[__::pt::pe__ __xdigit__](#23)
[__::pt::pe__ __ddigit__](#24)
[__::pt::pe__ __terminal__ *t*](#25)
[__::pt::pe__ __range__ *ta* *tb*](#26)
[__::pt::pe__ __nonterminal__ *nt*](#27)
[__::pt::pe__ __choice__ *pe*...](#28)
[__::pt::pe__ __sequence__ *pe*...](#29)
[__::pt::pe__ __repeat0__ *pe*](#30)
[__::pt::pe__ __repeat1__ *pe*](#31)
[__::pt::pe__ __optional__ *pe*](#32)
[__::pt::pe__ __ahead__ *pe*](#33)
[__::pt::pe__ __notahead__ *pe*](#34)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides commands to work with the serializations of parsing
expressions as managed by the Parser Tools, and specified in section [PE
serialization format](#section3).
This is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::pe__ __verify__ *serial* ?*canonvar*?
This command verifies that the content of *serial* is a valid serialization
of a parsing expression and will throw an error if that is not the case. The
result of the command is the empty string.
If the argument *canonvar* is specified it is interpreted as the name of a
variable in the calling context. This variable will be written to if and
only if *serial* is a valid regular serialization. Its value will be a
boolean, with __True__ indicating that the serialization is not only valid,
but also *canonical*. __False__ will be written for a valid, but
non-canonical serialization.
For the specification of serializations see the section [PE serialization
format](#section3).
- <a name='2'></a>__::pt::pe__ __verify-as-canonical__ *serial*
This command verifies that the content of *serial* is a valid *canonical*
serialization of a parsing expression and will throw an error if that is not
the case. The result of the command is the empty string.
For the specification of canonical serializations see the section [PE
serialization format](#section3).
- <a name='3'></a>__::pt::pe__ __canonicalize__ *serial*
This command assumes that the content of *serial* is a valid *regular*
serialization of a parsing expression and will throw an error if that is not
the case.
It will then convert the input into the *canonical* serialization of this
parsing expression and return it as its result. If the input is already
canonical it will be returned unchanged.
For the specification of regular and canonical serializations see the
section [PE serialization format](#section3).
- <a name='4'></a>__::pt::pe__ __print__ *serial*
This command assumes that the argument *serial* contains a valid
serialization of a parsing expression and returns a string containing that
PE in a human readable form.
The exact format of this form is not specified and cannot be relied on for
parsing or other machine-based activities.
For the specification of serializations see the section [PE serialization
format](#section3).
- <a name='5'></a>__::pt::pe__ __bottomup__ *cmdprefix* *pe*
This command walks the parsing expression *pe* from the bottom up to the
root, invoking the command prefix *cmdprefix* for each partial expression.
This implies that the children of a parsing expression PE are handled before
PE.
The command prefix has the signature
* <a name='6'></a>__cmdprefix__ *pe* *op* *arguments*
I.e. it is invoked with the parsing expression *pe* the walk is
currently at, the *op*'erator in the *pe*, and the operator's
*arguments*.
The result returned by the command prefix replaces *pe* in the parsing
expression it was a child of, allowing transformations of the expression
tree.
This also means that for all inner parsing expressions the contents of
*arguments* are the results of the command prefix invoked for the
children of this inner parsing expression.
- <a name='7'></a>__::pt::pe__ __topdown__ *cmdprefix* *pe*
This command walks the parsing expression *pe* from the root down to the
leaves, invoking the command prefix *cmdprefix* for each partial expression.
This implies that the children of a parsing expression PE are handled after
PE.
The command prefix has the same signature as for __bottomup__, see above.
The result returned by the command prefix is *ignored*.
- <a name='8'></a>__::pt::pe__ __equal__ *seriala* *serialb*
This command tests the two parsing expressions *seriala* and *serialb* for
structural equality. The result of the command is a boolean value. It will
be set to __true__ if the expressions are identical, and __false__
otherwise.
String equality is usable only if we can assume that the two parsing
expressions are pure Tcl lists.
- <a name='9'></a>__::pt::pe__ __epsilon__
This command constructs the atomic parsing expression for epsilon.
- <a name='10'></a>__::pt::pe__ __dot__
This command constructs the atomic parsing expression for dot.
- <a name='11'></a>__::pt::pe__ __alnum__
This command constructs the atomic parsing expression for alnum.
- <a name='12'></a>__::pt::pe__ __alpha__
This command constructs the atomic parsing expression for alpha.
- <a name='13'></a>__::pt::pe__ __ascii__
This command constructs the atomic parsing expression for ascii.
- <a name='14'></a>__::pt::pe__ __control__
This command constructs the atomic parsing expression for control.
- <a name='15'></a>__::pt::pe__ __digit__
This command constructs the atomic parsing expression for digit.
- <a name='16'></a>__::pt::pe__ __graph__
This command constructs the atomic parsing expression for graph.
- <a name='17'></a>__::pt::pe__ __lower__
This command constructs the atomic parsing expression for lower.
- <a name='18'></a>__::pt::pe__ __print__
This command constructs the atomic parsing expression for print.
- <a name='19'></a>__::pt::pe__ __punct__
This command constructs the atomic parsing expression for punct.
- <a name='20'></a>__::pt::pe__ __space__
This command constructs the atomic parsing expression for space.
- <a name='21'></a>__::pt::pe__ __upper__
This command constructs the atomic parsing expression for upper.
- <a name='22'></a>__::pt::pe__ __wordchar__
This command constructs the atomic parsing expression for wordchar.
- <a name='23'></a>__::pt::pe__ __xdigit__
This command constructs the atomic parsing expression for xdigit.
- <a name='24'></a>__::pt::pe__ __ddigit__
This command constructs the atomic parsing expression for ddigit.
- <a name='25'></a>__::pt::pe__ __terminal__ *t*
This command constructs the atomic parsing expression for the terminal
symbol *t*.
- <a name='26'></a>__::pt::pe__ __range__ *ta* *tb*
This command constructs the atomic parsing expression for the range of
terminal symbols *ta* ... *tb*.
- <a name='27'></a>__::pt::pe__ __nonterminal__ *nt*
This command constructs the atomic parsing expression for the nonterminal
symbol *nt*.
- <a name='28'></a>__::pt::pe__ __choice__ *pe*...
This command constructs the parsing expression representing the ordered or
prioritized choice between the argument parsing expressions. The first
argument has the highest priority.
- <a name='29'></a>__::pt::pe__ __sequence__ *pe*...
This command constructs the parsing expression representing the sequence of
the argument parsing expression. The first argument is the first element of
the sequence.
- <a name='30'></a>__::pt::pe__ __repeat0__ *pe*
This command constructs the parsing expression representing the zero or more
repetition of the argument parsing expression *pe*, also known as the kleene
closure.
- <a name='31'></a>__::pt::pe__ __repeat1__ *pe*
This command constructs the parsing expression representing the one or more
repetition of the argument parsing expression *pe*, also known as the
positive kleene closure.
- <a name='32'></a>__::pt::pe__ __optional__ *pe*
This command constructs the parsing expression representing the optionality
of the argument parsing expression *pe*.
- <a name='33'></a>__::pt::pe__ __ahead__ *pe*
This command constructs the parsing expression representing the positive
lookahead of the argument parsing expression *pe*.
- <a name='34'></a>__::pt::pe__ __notahead__ *pe*
This command constructs the parsing expression representing the negative
lookahead of the argument parsing expression *pe*.
# <a name='section3'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection1'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_pgen.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
[//000000001]: # (pt::pgen - Parser Tools)
[//000000002]: # (Generated from file 'pt_pgen.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::pgen(n) 1.1 tcllib "Parser Tools")
# NAME
pt::pgen - Parser Generator
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Example](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::pgen ?1.1?
[__::pt::pgen__ *inputformat* *text* *resultformat* ?*options...*?](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a command implementing a *[parser
generator](../../../../index.md#parser_generator)* taking parsing expression
grammars as input.
It is the implementation of method __generate__ of __[pt](../../apps/pt.md)__,
the *[Parser Tools Application](../../apps/pt.md)*.
As such the intended audience of this document are people wishing to modify
and/or extend this part of __[pt](../../apps/pt.md)__'s functionality. Users of
__[pt](../../apps/pt.md)__ on the other hand are hereby refered to the
applications' manpage, i.e. *[Parser Tools Application](../../apps/pt.md)*.
It resides in the User Package Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::pgen__ *inputformat* *text* *resultformat* ?*options...*?
This command takes the parsing expression grammar in *text* (in the format
specified by *inputformat*), and returns the same grammar in the format
*resultformat* as the result of the command.
The two known input formats are __peg__ and __json__. Introductions to them,
including their formal specifications, can be found in the *[PEG Language
Tutorial](pt_peg_language.md)* and *[The JSON Grammar Exchange
Format](pt_json_language.md)*. The packages used to parse these formats are
* __peg__
__[pt::peg::from::peg](pt_peg_from_peg.md)__
* __json__
__[pt::peg::from::json](pt_peg_from_json.md)__
On the output side the known formats, and the packages used to generate them
are
* __c__
__[pt::peg::to::cparam](pt_peg_to_cparam.md)__
* __container__
__[pt::peg::to::container](pt_peg_to_container.md)__
* __critcl__
__[pt::peg::to::cparam](pt_peg_to_cparam.md)__ +
__[pt::cparam::configuration::critcl](pt_cparam_config_critcl.md)__
* __json__
__[pt::peg::to::json](pt_peg_to_json.md)__
* __oo__
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ +
__[pt::tclparam::configuration::tcloo](pt_tclparam_config_tcloo.md)__
* __peg__
__[pt::peg::to::peg](pt_peg_to_peg.md)__
* __snit__
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ +
__[pt::tclparam::configuration::snit](pt_tclparam_config_snit.md)__
The options supported by each of these formats are documented with their
respective packages.
# <a name='section3'></a>Example
In this section we are working a complete example, starting with a PEG grammar
and ending with running the parser generated from it over some input, following
the outline shown in the figure below:
 Our grammar, assumed to the stored in the file
"calculator.peg" is
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
From this we create a snit-based parser using the script "gen"
package require Tcl 8.5
package require fileutil
package require pt::pgen
lassign $argv name
set grammar [fileutil::cat $name.peg]
set pclass [pt::pgen peg $gr snit -class $name -file $name.peg -name $name]
fileutil::writeFile $name.tcl $pclass
exit 0
calling it like
tclsh8.5 gen calculator
which leaves us with the parser package and class written to the file
"calculator.tcl". Assuming that this package is then properly installed in a
place where Tcl can find it we can now use this class via a script like
package require calculator
lassign $argv input
set channel [open $input r]
set parser [calculator]
set ast [$parser parse $channel]
$parser destroy
close $channel
... now process the returned abstract syntax tree ...
where the abstract syntax tree stored in the variable will look like
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
assuming that the input file and channel contained the text
120+5
A more graphical representation of the tree would be
 Regardless, at this point it is the user's
responsibility to work with the tree to reach whatever goal she desires. I.e.
analyze it, transform it, etc. The package __[pt::ast](pt_astree.md)__ should be
of help here, providing commands to walk such ASTs structures in various ways.
One important thing to note is that the parsers used here return a data
structure representing the structure of the input per the grammar underlying the
parser. There are *no* callbacks during the parsing process, i.e. no *parsing
actions*, as most other parsers will have.
Going back to the last snippet of code, the execution of the parser for some
input, note how the parser instance follows the specified *[Parser
API](pt_parser_api.md)*.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_rdengine.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
|
[//000000001]: # (pt::rde - Parser Tools)
[//000000002]: # (Generated from file 'pt_rdengine.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::rde(n) 1.1 tcllib "Parser Tools")
# NAME
pt::rde - Parsing Runtime Support, PARAM based
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#subsection1)
- [Object API](#subsection2)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::rde ?1.1?
package require snit
package require struct::stack 1.5
package require pt::ast 1.1
[__::pt::rde__ *objectName*](#1)
[*objectName* __destroy__](#2)
[*objectName* __reset__ *chan*](#3)
[*objectName* __complete__](#4)
[*objectName* __chan__](#5)
[*objectName* __line__](#6)
[*objectName* __column__](#7)
[*objectName* __current__](#8)
[*objectName* __location__](#9)
[*objectName* __locations__](#10)
[*objectName* __ok__](#11)
[*objectName* __value__](#12)
[*objectName* __error__](#13)
[*objectName* __errors__](#14)
[*objectName* __tokens__ ?*from* ?*to*??](#15)
[*objectName* __symbols__](#16)
[*objectName* __known__](#17)
[*objectName* __reducible__](#18)
[*objectName* __asts__](#19)
[*objectName* __ast__](#20)
[*objectName* __position__ *loc*](#21)
[*objectName* __i_input_next__ *msg*](#22)
[*objectName* __i_test_alnum__](#23)
[*objectName* __i_test_alpha__](#24)
[*objectName* __i_test_ascii__](#25)
[*objectName* __i_test_char__ *char*](#26)
[*objectName* __i_test_ddigit__](#27)
[*objectName* __i_test_digit__](#28)
[*objectName* __i_test_graph__](#29)
[*objectName* __i_test_lower__](#30)
[*objectName* __i_test_print__](#31)
[*objectName* __i_test_punct__](#32)
[*objectName* __i_test_range__ *chars* *chare*](#33)
[*objectName* __i_test_space__](#34)
[*objectName* __i_test_upper__](#35)
[*objectName* __i_test_wordchar__](#36)
[*objectName* __i_test_xdigit__](#37)
[*objectName* __i_error_clear__](#38)
[*objectName* __i_error_push__](#39)
[*objectName* __i_error_pop_merge__](#40)
[*objectName* __i_error_nonterminal__ *symbol*](#41)
[*objectName* __i_status_ok__](#42)
[*objectName* __i_status_fail__](#43)
[*objectName* __i_status_negate__](#44)
[*objectName* __i_loc_push__](#45)
[*objectName* __i_loc_pop_discard__](#46)
[*objectName* __i_loc_pop_rewind__](#47)
[*objectName* __i:ok_loc_pop_rewind__](#48)
[*objectName* __i_loc_pop_rewind/discard__](#49)
[*objectName* __i_symbol_restore__ *symbol*](#50)
[*objectName* __i_symbol_save__ *symbol*](#51)
[*objectName* __i_value_clear__](#52)
[*objectName* __i_value_clear/leaf__](#53)
[*objectName* __i_value_clear/reduce__](#54)
[*objectName* __i:ok_ast_value_push__](#55)
[*objectName* __i_ast_push__](#56)
[*objectName* __i_ast_pop_rewind__](#57)
[*objectName* __i:fail_ast_pop_rewind__](#58)
[*objectName* __i_ast_pop_rewind/discard__](#59)
[*objectName* __i_ast_pop_discard__](#60)
[*objectName* __i_ast_pop_discard/rewind__](#61)
[*objectName* __i:ok_continue__](#62)
[*objectName* __i:fail_continue__](#63)
[*objectName* __i:fail_return__](#64)
[*objectName* __i:ok_return__](#65)
[*objectName* __si:void_state_push__](#66)
[*objectName* __si:void2_state_push__](#67)
[*objectName* __si:value_state_push__](#68)
[*objectName* __si:void_state_merge__](#69)
[*objectName* __si:void_state_merge_ok__](#70)
[*objectName* __si:value_state_merge__](#71)
[*objectName* __si:value_notahead_start__](#72)
[*objectName* __si:void_notahead_exit__](#73)
[*objectName* __si:value_notahead_exit__](#74)
[*objectName* __si:kleene_abort__](#75)
[*objectName* __si:kleene_close__](#76)
[*objectName* __si:voidvoid_branch__](#77)
[*objectName* __si:voidvalue_branch__](#78)
[*objectName* __si:valuevoid_branch__](#79)
[*objectName* __si:valuevalue_branch__](#80)
[*objectName* __si:voidvoid_part__](#81)
[*objectName* __si:voidvalue_part__](#82)
[*objectName* __si:valuevalue_part__](#83)
[*objectName* __si:value_symbol_start__ *symbol*](#84)
[*objectName* __si:value_void_symbol_start__ *symbol*](#85)
[*objectName* __si:void_symbol_start__ *symbol*](#86)
[*objectName* __si:void_void_symbol_start__ *symbol*](#87)
[*objectName* __si:reduce_symbol_end__ *symbol*](#88)
[*objectName* __si:void_leaf_symbol_end__ *symbol*](#89)
[*objectName* __si:value_leaf_symbol_end__ *symbol*](#90)
[*objectName* __si:value_clear_symbol_end__ *symbol*](#91)
[*objectName* __si:void_clear_symbol_end__ *symbol*](#92)
[*objectName* __si:next_char__ *tok*](#93)
[*objectName* __si:next_range__ *toks* *toke*](#94)
[*objectName* __si:next_alnum__](#95)
[*objectName* __si:next_alpha__](#96)
[*objectName* __si:next_ascii__](#97)
[*objectName* __si:next_ddigit__](#98)
[*objectName* __si:next_digit__](#99)
[*objectName* __si:next_graph__](#100)
[*objectName* __si:next_lower__](#101)
[*objectName* __si:next_print__](#102)
[*objectName* __si:next_punct__](#103)
[*objectName* __si:next_space__](#104)
[*objectName* __si:next_upper__](#105)
[*objectName* __si:next_wordchar__](#106)
[*objectName* __si:next_xdigit__](#107)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides a class whose instances provide the runtime support for
recursive descent parsers with backtracking, as is needed for the execution of,
for example, parsing expression grammars. It implements the *[PackRat Machine
Specification](pt_param.md)*, as such that document is *required* reading to
understand both this manpage, and the package itself. The description below does
make numerous shorthand references to the PARAM's instructions and the various
parts of its architectural state.
The package resides in the Execution section of the Core Layer of Parser Tools.
Note: This package not only has the standard Tcl implementation, but also an
accelerator, i.e. a C implementation, based on Critcl.
## <a name='subsection1'></a>Class API
The package exports the API described here.
- <a name='1'></a>__::pt::rde__ *objectName*
The command creates a new runtime object for a recursive descent parser with
backtracking and returns the fully qualified name of the object command as
its result. The API of this object command is described in the section
[Object API](#subsection2). It may be used to invoke various operations on
the object.
## <a name='subsection2'></a>Object API
All objects created by this package provide the following 63 methods for the
manipulation and querying of their state, which is, in essence the architectural
state of a PARAM.
First some general methods and the state accessors.
- <a name='2'></a>*objectName* __destroy__
This method destroys the object, releasing all claimed memory, and deleting
the associated object command.
- <a name='3'></a>*objectName* __reset__ *chan*
This method resets the state of the runtme to its defaults, preparing it for
the parsing of the character in the channel *chan*, which becomes IN.
Note here that the Parser Tools are based on Tcl 8.5+. In other words, the
channel argument is not restricted to files, sockets, etc. We have the full
power of *reflected channels* available.
It should also be noted that the parser pulls the characters from the input
stream as it needs them. If a parser created by this package has to be
operated in a push aka event-driven manner it will be necessary to go to Tcl
8.6+ and use the __[coroutine::auto](../coroutine/coro_auto.md)__ to wrap it
into a coroutine where __[read](../../../../index.md#read)__ is properly
changed for push-operation.
- <a name='4'></a>*objectName* __complete__
This method completes parsing, either returning the AST made from the
elements of ARS, or throwing an error containing the current ER.
- <a name='5'></a>*objectName* __chan__
This method returns the handle of the channel which is IN.
- <a name='6'></a>*objectName* __line__
This method returns the line number for the position IN is currently at.
Note that this may not match with the line number for CL, due to
backtracking.
- <a name='7'></a>*objectName* __column__
This method returns the column for the position IN is currently at. Note
that this may not match with the column for CL, due to backtracking.
- <a name='8'></a>*objectName* __current__
This method returns CC.
- <a name='9'></a>*objectName* __location__
This method returns CL.
- <a name='10'></a>*objectName* __locations__
This method returns the LS. The topmost entry of the stack will be the first
element of the returned list.
- <a name='11'></a>*objectName* __ok__
This method returns ST.
- <a name='12'></a>*objectName* __value__
This method returns SV.
- <a name='13'></a>*objectName* __error__
This method returns ER. This is either the empty string for an empty ER, or
a list of 2 elements, the location the error is for, and a set of messages
which specify which symbols were expected at the location. The messages are
encoded as one of the possible atomic parsing expressions (special
operators, terminal, range, and nonterminal operator).
- <a name='14'></a>*objectName* __errors__
This method returns ES. The topmost entry of the stack will be the first
element of the returned list. Each entry is encoded as described for
__error__.
- <a name='15'></a>*objectName* __tokens__ ?*from* ?*to*??
This method returns the part of TC for the range of locations of IN starting
at *from* and ending at *to*. If *to* is not specified it is taken as
identical to *from*. If neither argument is specified the whole of TC is
returned.
Each token in the returned list is a list of three elements itself,
containing the character at the location, and the associated line and column
numbers, in this order.
- <a name='16'></a>*objectName* __symbols__
This method returns a dictionary containing NC. Keys are two-element lists
containing nonterminal symbol and location, in this order. The values are
4-tuples containing CL, ST, ER, and SV, in this order. ER is encoded as
specified for the method __error__.
- <a name='17'></a>*objectName* __known__
This method returns a list containing the keys of SC. They are encoded in
the same manner as is done by method __symbols__.
- <a name='18'></a>*objectName* __reducible__
This method returns ARS. The topmost entry of the stack will be the first
element of the returned list
- <a name='19'></a>*objectName* __asts__
This method returns AS. The topmost entry of the stack will be the first
element of the returned list
- <a name='20'></a>*objectName* __ast__
This is a convenience method returning the topmost element of ARS.
- <a name='21'></a>*objectName* __position__ *loc*
This method returns the line and column numbers for the specified location
of IN, assuming that this location has already been reached during the
parsing process.
The following methods implement all PARAM instructions. They all have the prefix
"i_".
The control flow is mainly provided by Tcl's builtin commands, like __if__,
__while__, etc., plus a few guarded variants of PARAM instructions and Tcl
commands.. That means that these instruction variants will do nothing if their
guard condition is not fulfilled. They can be recognized by the prefix "i:ok_"
and "i:fail_", which denote the value ST has to have for the instruction to
execute.
The instructions are listed in the same order they occur in the *[PackRat
Machine Specification](pt_param.md)*, with the guard variants listed after their
regular implementation, if any, or in their place.
- <a name='22'></a>*objectName* __i_input_next__ *msg*
This method implements the PARAM instruction __input_next__.
- <a name='23'></a>*objectName* __i_test_alnum__
This method implements the PARAM instruction __test_alnum__.
- <a name='24'></a>*objectName* __i_test_alpha__
This method implements the PARAM instruction __test_alpha__.
- <a name='25'></a>*objectName* __i_test_ascii__
This method implements the PARAM instruction __test_ascii__.
- <a name='26'></a>*objectName* __i_test_char__ *char*
This method implements the PARAM instruction __test_char__.
- <a name='27'></a>*objectName* __i_test_ddigit__
This method implements the PARAM instruction __test_ddigit__.
- <a name='28'></a>*objectName* __i_test_digit__
This method implements the PARAM instruction __test_digit__.
- <a name='29'></a>*objectName* __i_test_graph__
This method implements the PARAM instruction __test_graph__.
- <a name='30'></a>*objectName* __i_test_lower__
This method implements the PARAM instruction __test_lower__.
- <a name='31'></a>*objectName* __i_test_print__
This method implements the PARAM instruction __test_print__.
- <a name='32'></a>*objectName* __i_test_punct__
This method implements the PARAM instruction __test_punct__.
- <a name='33'></a>*objectName* __i_test_range__ *chars* *chare*
This method implements the PARAM instruction __test_range__.
- <a name='34'></a>*objectName* __i_test_space__
This method implements the PARAM instruction __test_space__.
- <a name='35'></a>*objectName* __i_test_upper__
This method implements the PARAM instruction __test_upper__.
- <a name='36'></a>*objectName* __i_test_wordchar__
This method implements the PARAM instruction __test_wordchar__.
- <a name='37'></a>*objectName* __i_test_xdigit__
This method implements the PARAM instruction __test_xdigit__.
- <a name='38'></a>*objectName* __i_error_clear__
This method implements the PARAM instruction __error_clear__.
- <a name='39'></a>*objectName* __i_error_push__
This method implements the PARAM instruction __error_push__.
- <a name='40'></a>*objectName* __i_error_pop_merge__
This method implements the PARAM instruction __error_pop_merge__.
- <a name='41'></a>*objectName* __i_error_nonterminal__ *symbol*
This method implements the PARAM instruction __error_nonterminal__.
- <a name='42'></a>*objectName* __i_status_ok__
This method implements the PARAM instruction __status_ok__.
- <a name='43'></a>*objectName* __i_status_fail__
This method implements the PARAM instruction __status_fail__.
- <a name='44'></a>*objectName* __i_status_negate__
This method implements the PARAM instruction __status_negate__.
- <a name='45'></a>*objectName* __i_loc_push__
This method implements the PARAM instruction __loc_push__.
- <a name='46'></a>*objectName* __i_loc_pop_discard__
This method implements the PARAM instruction __loc_pop_discard__.
- <a name='47'></a>*objectName* __i_loc_pop_rewind__
This method implements the PARAM instruction __loc_pop_rewind__.
- <a name='48'></a>*objectName* __i:ok_loc_pop_rewind__
This guarded method, a variant of __i_loc_pop_rewind__, executes only for
"ST == ok".
- <a name='49'></a>*objectName* __i_loc_pop_rewind/discard__
This method is a convenient combination of control flow and the two PARAM
instructions __loc_pop_rewind__ and __loc_pop_discard__. The former is
executed for "ST == fail", the latter for "ST == ok".
- <a name='50'></a>*objectName* __i_symbol_restore__ *symbol*
This method implements the PARAM instruction __symbol_restore__.
The boolean result of the check is returned as the result of the method and
can be used with standard Tcl control flow commands.
- <a name='51'></a>*objectName* __i_symbol_save__ *symbol*
This method implements the PARAM instruction __symbol_save__.
- <a name='52'></a>*objectName* __i_value_clear__
This method implements the PARAM instruction __value_clear__.
- <a name='53'></a>*objectName* __i_value_clear/leaf__
This method is a convenient combination of control flow and the two PARAM
instructions __value_clear__ and __value_leaf__. The former is executed for
"ST == fail", the latter for "ST == ok".
- <a name='54'></a>*objectName* __i_value_clear/reduce__
This method is a convenient combination of control flow and the two PARAM
instructions __value_clear__ and __value_reduce__. The former is executed
for "ST == fail", the latter for "ST == ok".
- <a name='55'></a>*objectName* __i:ok_ast_value_push__
This method implements a guarded variant of the the PARAM instruction
__ast_value_push__, which executes only for "ST == ok".
- <a name='56'></a>*objectName* __i_ast_push__
This method implements the PARAM instruction __ast_push__.
- <a name='57'></a>*objectName* __i_ast_pop_rewind__
This method implements the PARAM instruction __ast_pop_rewind__.
- <a name='58'></a>*objectName* __i:fail_ast_pop_rewind__
This guarded method, a variant of __i_ast_pop_rewind__, executes only for
"ST == fail".
- <a name='59'></a>*objectName* __i_ast_pop_rewind/discard__
This method is a convenient combination of control flow and the two PARAM
instructions __ast_pop_rewind__ and __ast_pop_discard__. The former is
executed for "ST == fail", the latter for "ST == ok".
- <a name='60'></a>*objectName* __i_ast_pop_discard__
This method implements the PARAM instruction __ast_pop_discard__.
- <a name='61'></a>*objectName* __i_ast_pop_discard/rewind__
This method is a convenient combination of control flow and the two PARAM
instructions __ast_pop_discard__ and __ast_pop_rewind__. The former is
executed for "ST == fail", the latter for "ST == ok".
- <a name='62'></a>*objectName* __i:ok_continue__
This guarded method executes only for "ST == ok". Then it aborts the current
iteration of the innermost loop in the calling Tcl procedure.
- <a name='63'></a>*objectName* __i:fail_continue__
This guarded method executes only for "ST == fail". Then it aborts the
current iteration of the innermost loop in the calling Tcl procedure.
- <a name='64'></a>*objectName* __i:fail_return__
This guarded method executes only for "ST == fail". Then it aborts the
calling Tcl procedure.
- <a name='65'></a>*objectName* __i:ok_return__
This guarded method executes only for "ST == ok". Then it aborts the calling
Tcl procedure.
The next set of methods are *super instructions*, meaning that each implements a
longer sequence of instructions commonly used in parsers. The combinated
instructions of the previous set, i.e. those with names matching the pattern
"i_*/*", are actually super instructions as well, albeit with limited scope,
handling 2 instructions with their control flow. The upcoming set is much
broader in scope, folding as much as six or more PARAM instructions into a
single method call.
In this we can see the reasoning behind their use well:
1. By using less instructions the generated parsers become smaller, as the
common parts are now truly part of the common runtime, and not explicitly
written in the parser's code over and over again.
1. Using less instructions additionally reduces the overhead associated with
calls into the runtime, i.e. the cost of method dispatch and of setting up
the variable context.
1. Another effect of the super instructions is that their internals can be
optimized as well, especially regarding control flow, and stack use, as the
runtime internals are accessible to all instructions folded into the
sequence.
- <a name='66'></a>*objectName* __si:void_state_push__
This method combines
i_loc_push
i_error_clear
i_error_push
Parsers use it at the beginning of *void* sequences and choices with a
*void* initial branch.
- <a name='67'></a>*objectName* __si:void2_state_push__
This method combines
i_loc_push
i_error_clear
i_error_push
Parsers use it at the beginning of optional and repeated expressions.
- <a name='68'></a>*objectName* __si:value_state_push__
This method combines
i_ast_push
i_loc_push
i_error_clear
i_error_push
Parsers use it at the beginning of sequences generating an AST and choices
with an initial branch generating an AST.
- <a name='69'></a>*objectName* __si:void_state_merge__
This method combines
i_error_pop_merge
i_loc_pop_rewind/discard
Parsers use it at the end of void sequences and choices whose last branch is
void.
- <a name='70'></a>*objectName* __si:void_state_merge_ok__
This method combines
i_error_pop_merge
i_loc_pop_rewind/discard
i_status_ok
Parsers use it at the end of optional expressions
- <a name='71'></a>*objectName* __si:value_state_merge__
This method combines
i_error_pop_merge
i_ast_pop_rewind/discard
i_loc_pop_rewind/discard
Parsers use it at the end of sequences generating ASTs and choices whose
last branch generates an AST
- <a name='72'></a>*objectName* __si:value_notahead_start__
This method combines
i_loc_push
i_ast_push
Parsers use it at the beginning of negative lookahead predicates which
generate ASTs.
- <a name='73'></a>*objectName* __si:void_notahead_exit__
This method combines
i_loc_pop_rewind
i_status_negate
Parsers use it at the end of void negative lookahead predicates.
- <a name='74'></a>*objectName* __si:value_notahead_exit__
This method combines
i_ast_pop_discard/rewind
i_loc_pop_rewind
i_status_negate
Parsers use it at the end of negative lookahead predicates which generate
ASTs.
- <a name='75'></a>*objectName* __si:kleene_abort__
This method combines
i_loc_pop_rewind/discard
i:fail_return
Parsers use it to stop a positive repetition when its first, required,
expression fails.
- <a name='76'></a>*objectName* __si:kleene_close__
This method combines
i_error_pop_merge
i_loc_pop_rewind/discard
i:fail_status_ok
i:fail_return
Parsers use it at the end of repetitions.
- <a name='77'></a>*objectName* __si:voidvoid_branch__
This method combines
i_error_pop_merge
i:ok_loc_pop_discard
i:ok_return
i_loc_rewind
i_error_push
Parsers use it when transiting between branches of a choice when both are
void.
- <a name='78'></a>*objectName* __si:voidvalue_branch__
This method combines
i_error_pop_merge
i:ok_loc_pop_discard
i:ok_return
i_ast_push
i_loc_rewind
i_error_push
Parsers use it when transiting between branches of a choice when the failing
branch is void, and the next to test generates an AST.
- <a name='79'></a>*objectName* __si:valuevoid_branch__
This method combines
i_error_pop_merge
i_ast_pop_rewind/discard
i:ok_loc_pop_discard
i:ok_return
i_loc_rewind
i_error_push
Parsers use it when transiting between branches of a choice when the failing
branch generates an AST, and the next to test is void.
- <a name='80'></a>*objectName* __si:valuevalue_branch__
This method combines
i_error_pop_merge
i_ast_pop_discard
i:ok_loc_pop_discard
i:ok_return
i_ast_rewind
i_loc_rewind
i_error_push
Parsers use it when transiting between branches of a choice when both
generate ASTs.
- <a name='81'></a>*objectName* __si:voidvoid_part__
This method combines
i_error_pop_merge
i:fail_loc_pop_rewind
i:fail_return
i_error_push
Parsers use it when transiting between parts of a sequence and both are
void.
- <a name='82'></a>*objectName* __si:voidvalue_part__
This method combines
i_error_pop_merge
i:fail_loc_pop_rewind
i:fail_return
i_ast_push
i_error_push
Parsers use it when transiting between parts of a sequence and the
sucessfully matched part is void, and after it an AST is generated.
- <a name='83'></a>*objectName* __si:valuevalue_part__
This method combines
i_error_pop_merge
i:fail_ast_pop_rewind
i:fail_loc_pop_rewind
i:fail_return
i_error_push
Parsers use it when transiting between parts of a sequence and both parts
generate ASTs.
- <a name='84'></a>*objectName* __si:value_symbol_start__ *symbol*
This method combines
if/found? i_symbol_restore $symbol
i:found:ok_ast_value_push
i:found_return
i_loc_push
i_ast_push
Parsers use it at the beginning of a nonterminal symbol generating an AST,
whose right-hand side may have generated an AST as well.
- <a name='85'></a>*objectName* __si:value_void_symbol_start__ *symbol*
This method combines
if/found? i_symbol_restore $symbol
i:found:ok_ast_value_push
i:found_return
i_loc_push
i_ast_push
Parsers use it at the beginning of a void nonterminal symbol whose
right-hand side may generate an AST.
- <a name='86'></a>*objectName* __si:void_symbol_start__ *symbol*
This method combines
if/found? i_symbol_restore $symbol
i:found_return
i_loc_push
i_ast_push
Parsers use it at the beginning of a nonterminal symbol generating an AST
whose right-hand side is void.
- <a name='87'></a>*objectName* __si:void_void_symbol_start__ *symbol*
This method combines
if/found? i_symbol_restore $symbol
i:found_return
i_loc_push
Parsers use it at the beginning of a void nonterminal symbol whose
right-hand side is void as well.
- <a name='88'></a>*objectName* __si:reduce_symbol_end__ *symbol*
This method combines
i_value_clear/reduce $symbol
i_symbol_save $symbol
i_error_nonterminal $symbol
i_ast_pop_rewind
i_loc_pop_discard
i:ok_ast_value_push
Parsers use it at the end of a non-terminal symbol generating an AST using
the AST generated by the right-hand side as child.
- <a name='89'></a>*objectName* __si:void_leaf_symbol_end__ *symbol*
This method combines
i_value_clear/leaf $symbol
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
i:ok_ast_value_push
Parsers use it at the end of a non-terminal symbol generating an AST whose
right-hand side is void.
- <a name='90'></a>*objectName* __si:value_leaf_symbol_end__ *symbol*
This method combines
i_value_clear/leaf $symbol
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
i_ast_pop_rewind
i:ok_ast_value_push
Parsers use it at the end of a non-terminal symbol generating an AST
discarding the AST generated by the right-hand side.
- <a name='91'></a>*objectName* __si:value_clear_symbol_end__ *symbol*
This method combines
i_value_clear
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
i_ast_pop_rewind
Parsers use it at the end of a void non-terminal symbol, discarding the AST
generated by the right-hand side.
- <a name='92'></a>*objectName* __si:void_clear_symbol_end__ *symbol*
This method combines
i_value_clear
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
Parsers use it at the end of a void non-terminal symbol with a void
right-hand side.
- <a name='93'></a>*objectName* __si:next_char__ *tok*
- <a name='94'></a>*objectName* __si:next_range__ *toks* *toke*
- <a name='95'></a>*objectName* __si:next_alnum__
- <a name='96'></a>*objectName* __si:next_alpha__
- <a name='97'></a>*objectName* __si:next_ascii__
- <a name='98'></a>*objectName* __si:next_ddigit__
- <a name='99'></a>*objectName* __si:next_digit__
- <a name='100'></a>*objectName* __si:next_graph__
- <a name='101'></a>*objectName* __si:next_lower__
- <a name='102'></a>*objectName* __si:next_print__
- <a name='103'></a>*objectName* __si:next_punct__
- <a name='104'></a>*objectName* __si:next_space__
- <a name='105'></a>*objectName* __si:next_upper__
- <a name='106'></a>*objectName* __si:next_wordchar__
- <a name='107'></a>*objectName* __si:next_xdigit__
These methods all combine
i_input_next $msg
i:fail_return
with the appropriate __i_test_xxx__ instruction. Parsers use them for
handling atomic expressions.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
[//000000001]: # (pt::tclparam::configuration::nx - Parser Tools)
[//000000002]: # (Generated from file 'pt_tclparam_config_nx.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::tclparam::configuration::nx(n) 1.0.1 tcllib "Parser Tools")
# NAME
pt::tclparam::configuration::nx - Tcl/PARAM, Canned configuration, NX
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::tclparam::configuration::nx ?1.0.1?
[__::pt::tclparam::configuration::nx__ __def__ *name* *pkg* *version* *cmdprefix*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package is an adjunct to
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__, to make the use of this
highly configurable package easier by providing a canned configuration. When
applied this configuration causes the package
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ to generate __NX__-based
parser packages.
It is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::tclparam::configuration::nx__ __def__ *name* *pkg* *version* *cmdprefix*
The command applies the configuration provided by this package to the
*cmdprefix*, causing the creation of __NX__-based parsers whose class is
*name*, in package *pkg* with *version*.
The use of a command prefix as API allows application of the configuration
to not only __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__
(__pt::peg::to::tclparam configure__), but also export manager instances and
PEG containers (__$export configuration set__ and __[$container exporter]
configuration set__ respectively).
Or anything other command prefix accepting two arguments, option and value.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
[//000000001]: # (pt::tclparam::configuration::snit - Parser Tools)
[//000000002]: # (Generated from file 'pt_tclparam_config_snit.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::tclparam::configuration::snit(n) 1.0.2 tcllib "Parser Tools")
# NAME
pt::tclparam::configuration::snit - Tcl/PARAM, Canned configuration, Snit
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::tclparam::configuration::snit ?1.0.2?
[__::pt::tclparam::configuration::snit__ __def__ *name* *pkg* *version* *cmdprefix*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package is an adjunct to
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__, to make the use of this
highly configurable package easier by providing a canned configuration. When
applied this configuration causes the package
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ to generate
__[snit](../snit/snit.md)__-based parser packages.
It is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::tclparam::configuration::snit__ __def__ *name* *pkg* *version* *cmdprefix*
The command applies the configuration provided by this package to the
*cmdprefix*, causing the creation of __[snit](../snit/snit.md)__-based
parsers whose class is *name*, in package *pkg* with *version*.
The use of a command prefix as API allows application of the configuration
to not only __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__
(__pt::peg::to::tclparam configure__), but also export manager instances and
PEG containers (__$export configuration set__ and __[$container exporter]
configuration set__ respectively).
Or anything other command prefix accepting two arguments, option and value.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
[//000000001]: # (pt::tclparam::configuration::tcloo - Parser Tools)
[//000000002]: # (Generated from file 'pt_tclparam_config_tcloo.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::tclparam::configuration::tcloo(n) 1.0.4 tcllib "Parser Tools")
# NAME
pt::tclparam::configuration::tcloo - Tcl/PARAM, Canned configuration, Tcloo
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::tclparam::configuration::tcloo ?1.0.4?
[__::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix*](#1)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package is an adjunct to
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__, to make the use of this
highly configurable package easier by providing a canned configuration. When
applied this configuration causes the package
__[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__ to generate __OO__-based
parser packages.
It is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix*
The command applies the configuration provided by this package to the
*cmdprefix*, causing the creation of __OO__-based parsers whose class is
*name*, in package *pkg* with *version*.
The use of a command prefix as API allows application of the configuration
to not only __[pt::peg::to::tclparam](pt_peg_to_tclparam.md)__
(__pt::peg::to::tclparam configure__), but also export manager instances and
PEG containers (__$export configuration set__ and __[$container exporter]
configuration set__ respectively).
Or anything other command prefix accepting two arguments, option and value.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_to_api.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
|
[//000000001]: # (pt_export_api - Parser Tools)
[//000000002]: # (Generated from file 'pt_to_api.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt_export_api(i) 1 tcllib "Parser Tools")
# NAME
pt_export_api - Parser Tools Export API
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Converter API](#section2)
- [Plugin API](#section3)
- [Options](#section4)
- [Usage](#section5)
- [PEG serialization format](#section6)
- [Example](#subsection1)
- [PE serialization format](#section7)
- [Example](#subsection2)
- [Bugs, Ideas, Feedback](#section8)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
[__CONVERTER__ __reset__](#1)
[__CONVERTER__ __configure__](#2)
[__CONVERTER__ __configure__ *option*](#3)
[__CONVERTER__ __configure__ *option* *value*...](#4)
[__CONVERTER__ __convert__ *serial*](#5)
[__::export__ *serial* *configuration*](#6)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This document describes two APIs. First the API shared by all packages for the
conversion of Parsing Expression Grammars into some other format, and then the
API shared by the packages which implement the export plugins sitting on top of
the conversion packages.
Its intended audience are people who wish to create their own converter for some
type of output, and/or an export plugin for their or some other converter.
It resides in the Export section of the Core Layer of Parser Tools.
# <a name='section2'></a>Converter API
Any (grammar) export converter has to follow the rules set out below:
1. A converter is a package. Its name is arbitrary, however it is recommended
to put it under the __::pt::peg::to__ namespace.
1. The package provides either a single Tcl command following the API outlined
below, or a class command whose instances follow the same API. The commands
which follow the API are called *converter commands*.
1. A converter command has to provide the following three methods with the
given signatures and semantics. Converter commands are allowed to provide
more methods of their own, but not less, and they may not provide different
semantics for the standardized methods.
- <a name='1'></a>__CONVERTER__ __reset__
This method has to reset the configuration of the converter to its
default settings. The result of the method has to be the empty string.
- <a name='2'></a>__CONVERTER__ __configure__
This method, in this form, has to return a dictionary containing the
current configuration of the converter.
- <a name='3'></a>__CONVERTER__ __configure__ *option*
This method, in this form, has to return the current value of the
specified configuration *option* of the converter.
Please read the section [Options](#section4) for the set of standard
options any converter has to accept. Any other options accepted by a
specific converter will be described in its manpage.
- <a name='4'></a>__CONVERTER__ __configure__ *option* *value*...
This command, in this form, sets the specified *option*s of the
converter to the given *value*s.
Please read the section [Options](#section4) for the set of standard
options a converter has to accept. Any other options accepted by a
specific converter will be described in its manpage.
- <a name='5'></a>__CONVERTER__ __convert__ *serial*
This method has to accept the canonical serialization of a parsing
expression grammar, as specified in section [PEG serialization
format](#section6), and contained in *serial*. The result of the method
has to be the result of converting the input grammar into whatever the
converter is for, per its configuration.
# <a name='section3'></a>Plugin API
Any (grammar) export plugin has to follow the rules set out below:
1. A plugin is a package.
1. The name of a plugin package has the form pt::peg::export::__FOO__, where
__FOO__ is the name of the format the plugin will generate output for.
1. The plugin can expect that the package __pt::peg::export::plugin__ is
present, as indicator that it was invoked from a genuine plugin manager.
It is recommended that a plugin does check for the presence of this
package.
1. A plugin has to provide a single command, in the global namespace, with the
signature shown below. Plugins are allowed to provide more command of their
own, but not less, and they may not provide different semantics for the
standardized command.
- <a name='6'></a>__::export__ *serial* *configuration*
This command has to accept the canonical serialization of a parsing
expression grammar and the configuration for the converter invoked by
the plugin. The result of the command has to be the result of the
converter invoked by the plugin for th input grammar and configuration.
* string *serial*
This argument will contain the *canonical* serialization of the
parsing expression grammar for which to generate the output. The
specification of what a *canonical* serialization is can be found
in the section [PEG serialization format](#section6).
* dictionary *configuration*
This argument will contain the configuration to configure the
converter with before invoking it, as a dictionary mapping from
options to values.
Please read the section [Options](#section4) for the set of
standard options any converter has to accept, and thus any plugin
as well. Any other options accepted by a specific plugin will be
described in its manpage.
1. A single usage cycle of a plugin consists of an invokation of the command
__[export](../../../../index.md#export)__. This call has to leave the
plugin in a state where another usage cycle can be run without problems.
# <a name='section4'></a>Options
Each export converter and plugin for an export converter has to accept the
options below in their __configure__ method. Converters are allowed to ignore
the contents of these options when performing a conversion, but they must not
reject them. Plugins are expected to pass the options given to them to the
converter they are invoking.
- __-file__ string
The value of this option is the name of the file or other entity from which
the grammar came, for which the command is run. The default value is
__unknown__.
- __-name__ string
The value of this option is the name of the grammar we are processing. The
default value is __a_pe_grammar__.
- __-user__ string
The value of this option is the name of the user for which the command is
run. The default value is __unknown__.
# <a name='section5'></a>Usage
To use a converter do
# Get the converter (single command here, not class)
package require the-converter-package
# Provide a configuration
theconverter configure ...
# Perform the conversion
set result [theconverter convert $thegrammarserial]
... process the result ...
To use a plugin __FOO__ do
# Get an export plugin manager
package require pt::peg::export
pt::peg::export E
# Provide a configuration
E configuration set ...
# Run the plugin, and the converter inside.
set result [E export serial $grammarserial FOO]
... process the result ...
# <a name='section6'></a>PEG serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expression Grammars as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a PEG may
have more than one regular serialization only exactly one of them will be
*canonical*.
- regular serialization
The serialization of any PEG is a nested Tcl dictionary.
This dictionary holds a single key, __pt::grammar::peg__, and its value.
This value holds the contents of the grammar.
The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and their
values are
* __rules__
The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.
Each nonterminal symbol may occur only once.
The empty string is not a legal nonterminal symbol.
The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are
+ __is__
The value is the serialization of the parsing expression
describing the symbols sentennial structure, as specified
in the section [PE serialization format](#section7).
+ __mode__
The value can be one of three values specifying how a
parser should handle the semantic value produced by the
symbol.
- __value__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal itself, which has the ASTs of the
symbol's right hand side as its children.
- __leaf__
The semantic value of the nonterminal symbol is an
abstract syntax tree consisting of a single node node
for the nonterminal, without any children. Any ASTs
generated by the symbol's right hand side are
discarded.
- __void__
The nonterminal has no semantic value. Any ASTs
generated by the symbol's right hand side are
discarded (as well).
* __start__
The value is the serialization of the start parsing expression of
the grammar, as specified in the section [PE serialization
format](#section7).
The terminal symbols of the grammar are specified implicitly as the set of
all terminal symbols used in the start expression and on the RHS of the
grammar rules.
- canonical serialization
The canonical serialization of a grammar has the format as specified in the
previous item, and then additionally satisfies the constraints below, which
make it unique among all the possible serializations of this grammar.
The keys found in all the nested Tcl dictionaries are sorted in ascending
dictionary order, as generated by Tcl's builtin command __lsort -increasing
-dict__.
The string representation of the value is the canonical representation of a
Tcl dictionary. I.e. it does not contain superfluous whitespace.
## <a name='subsection1'></a>Example
Assuming the following PEG for simple mathematical expressions
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
then its canonical serialization (except for whitespace) is
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
# <a name='section7'></a>PE serialization format
Here we specify the format used by the Parser Tools to serialize Parsing
Expressions as immutable values for transport, comparison, etc.
We distinguish between *regular* and *canonical* serializations. While a parsing
expression may have more than one regular serialization only exactly one of them
will be *canonical*.
- Regular serialization
* __Atomic Parsing Expressions__
The string __epsilon__ is an atomic parsing expression. It matches the
empty string.
The string __dot__ is an atomic parsing expression. It matches any
character.
The string __alnum__ is an atomic parsing expression. It matches any
Unicode alphabet or digit character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __alpha__ is an atomic parsing expression. It matches any
Unicode alphabet character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ascii__ is an atomic parsing expression. It matches any
Unicode character below U0080. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __control__ is an atomic parsing expression. It matches any
Unicode control character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __digit__ is an atomic parsing expression. It matches any
Unicode digit character. Note that this includes characters outside of
the [0..9] range. This is a custom extension of PEs based on Tcl's
builtin command __string is__.
The string __graph__ is an atomic parsing expression. It matches any
Unicode printing character, except for space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __lower__ is an atomic parsing expression. It matches any
Unicode lower-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __print__ is an atomic parsing expression. It matches any
Unicode printing character, including space. This is a custom extension
of PEs based on Tcl's builtin command __string is__.
The string __punct__ is an atomic parsing expression. It matches any
Unicode punctuation character. This is a custom extension of PEs based
on Tcl's builtin command __string is__.
The string __space__ is an atomic parsing expression. It matches any
Unicode space character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __upper__ is an atomic parsing expression. It matches any
Unicode upper-case alphabet character. This is a custom extension of PEs
based on Tcl's builtin command __string is__.
The string __wordchar__ is an atomic parsing expression. It matches any
Unicode word character. This is any alphanumeric character (see alnum),
and any connector punctuation characters (e.g. underscore). This is a
custom extension of PEs based on Tcl's builtin command __string is__.
The string __xdigit__ is an atomic parsing expression. It matches any
hexadecimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __string is__.
The string __ddigit__ is an atomic parsing expression. It matches any
decimal digit character. This is a custom extension of PEs based on
Tcl's builtin command __regexp__.
The expression [list t __x__] is an atomic parsing expression. It
matches the terminal string __x__.
The expression [list n __A__] is an atomic parsing expression. It
matches the nonterminal __A__.
* __Combined Parsing Expressions__
For parsing expressions __e1__, __e2__, ... the result of [list / __e1__
__e2__ ... ] is a parsing expression as well. This is the *ordered
choice*, aka *prioritized choice*.
For parsing expressions __e1__, __e2__, ... the result of [list x __e1__
__e2__ ... ] is a parsing expression as well. This is the *sequence*.
For a parsing expression __e__ the result of [list * __e__] is a parsing
expression as well. This is the *kleene closure*, describing zero or
more repetitions.
For a parsing expression __e__ the result of [list + __e__] is a parsing
expression as well. This is the *positive kleene closure*, describing
one or more repetitions.
For a parsing expression __e__ the result of [list & __e__] is a parsing
expression as well. This is the *and lookahead predicate*.
For a parsing expression __e__ the result of [list ! __e__] is a parsing
expression as well. This is the *not lookahead predicate*.
For a parsing expression __e__ the result of [list ? __e__] is a parsing
expression as well. This is the *optional input*.
- Canonical serialization
The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.
The string representation of the value is the canonical representation of a
pure Tcl list. I.e. it does not contain superfluous whitespace.
Terminals are *not* encoded as ranges (where start and end of the range are
identical).
## <a name='subsection2'></a>Example
Assuming the parsing expression shown on the right-hand side of the rule
Expression <- Term (AddOp Term)*
then its canonical serialization (except for whitespace) is
{x {n Term} {* {x {n AddOp} {n Term}}}}
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/pt/pt_util.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
[//000000001]: # (pt::util - Parser Tools)
[//000000002]: # (Generated from file 'pt_util.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (pt::util(n) 1.1 tcllib "Parser Tools")
# NAME
pt::util - General utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require pt::ast ?1.1?
[__::pt::util__ __error2readable__ *error* *text*](#1)
[__::pt::util__ __error2position__ *error* *text*](#2)
[__::pt::util__ __error2text__ *error*](#3)
# <a name='description'></a>DESCRIPTION
Are you lost ? Do you have trouble understanding this document ? In that case
please read the overview provided by the *[Introduction to Parser
Tools](pt_introduction.md)*. This document is the entrypoint to the whole system
the current package is a part of.
This package provides general utility commands.
This is a supporting package in the Core Layer of Parser Tools.
# <a name='section2'></a>API
- <a name='1'></a>__::pt::util__ __error2readable__ *error* *text*
This command takes the structured form of a syntax *error* as thrown by
parser runtimes and the input *text* to the parser which caused that error
and returns a string describing the error in a human-readable form.
The input *text* is required to convert the character position of the error
into a more readable line/column format, and to provide excerpts of the
input around the error position.
- <a name='2'></a>__::pt::util__ __error2position__ *error* *text*
This command takes the structured form of a syntax *error* as thrown by
parser runtimes and the input *text* to the parser which caused that error
and returns a 2-element list containing the line number and column index for
the error's character position in the input, in this order.
- <a name='3'></a>__::pt::util__ __error2text__ *error*
This command takes the structured form of a syntax *error* as thrown by
parser runtimes and returns a list of strings, each describing a possible
expected input in a human-readable form.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *pt* 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.
# <a name='keywords'></a>KEYWORDS
[EBNF](../../../../index.md#ebnf), [LL(k)](../../../../index.md#ll_k_),
[PEG](../../../../index.md#peg), [TDPL](../../../../index.md#tdpl),
[context-free languages](../../../../index.md#context_free_languages),
[expression](../../../../index.md#expression),
[grammar](../../../../index.md#grammar),
[matching](../../../../index.md#matching),
[parser](../../../../index.md#parser), [parsing
expression](../../../../index.md#parsing_expression), [parsing expression
grammar](../../../../index.md#parsing_expression_grammar), [push down
automaton](../../../../index.md#push_down_automaton), [recursive
descent](../../../../index.md#recursive_descent),
[state](../../../../index.md#state), [top-down parsing
languages](../../../../index.md#top_down_parsing_languages),
[transducer](../../../../index.md#transducer)
# <a name='category'></a>CATEGORY
Parsing and Grammars
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/rc4/rc4.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
[//000000001]: # (rc4 - RC4 Stream Cipher)
[//000000002]: # (Generated from file 'rc4.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (rc4(n) 1.1.0 tcllib "RC4 Stream Cipher")
# NAME
rc4 - Implementation of the RC4 stream cipher
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require rc4 ?1.1.0?
[__::rc4::rc4__ ?*-hex*? *-key keyvalue* ?*-command lst*? ?*-out channel*? [ *-in channel* | *-infile filename* | *string* ]](#1)
[__::rc4::RC4Init__ *keydata*](#2)
[__::rc4::RC4__ *Key* *data*](#3)
[__::rc4::RC4Final__ *Key*](#4)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the RC4 stream cipher developed by
Ron Rivest of RSA Data Security Inc. The cipher was a trade secret of RSA but
was reverse-engineered and published to the internet in 1994. It is used in a
number of network protocols for securing communications. To evade trademark
restrictions this cipher is sometimes known as ARCFOUR.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::rc4::rc4__ ?*-hex*? *-key keyvalue* ?*-command lst*? ?*-out channel*? [ *-in channel* | *-infile filename* | *string* ]
Perform the RC4 algorithm on either the data provided by the argument or on
the data read from the *-in* channel. If an *-out* channel is given then the
result will be written to this channel. Giving the *-hex* option will return
a hexadecimal encoded version of the result if not using an *-out* channel.
The data to be processes can be specified either as a string argument to the
rc4 command, or as a filename or a pre-opened channel. If the *-infile*
argument is given then the file is opened, the data read and processed and
the file is closed. If the *-in* argument is given then data is read from
the channel until the end of file. The channel is not closed. If the *-out*
argument is given then the processing result is written to this channel.
If *-command* is provided then the rc4 command does not return anything.
Instead the command provided is called with the rc4 result data appended as
the final parameter. This is most useful when reading from Tcl channels as a
fileevent is setup on the channel and the data processed in chunks
Only one of *-infile*, *-in* or *string* should be given.
# <a name='section3'></a>PROGRAMMING INTERFACE
- <a name='2'></a>__::rc4::RC4Init__ *keydata*
Initialize a new RC4 key. The *keydata* is any amount of binary data and is
used to initialize the cipher internal state.
- <a name='3'></a>__::rc4::RC4__ *Key* *data*
Encrypt or decrypt the input data using the key obtained by calling
__RC4Init__.
- <a name='4'></a>__::rc4::RC4Final__ *Key*
This should be called to clean up resources associated with *Key*. Once this
function has been called the key is destroyed.
# <a name='section4'></a>EXAMPLES
% set keydata [binary format H* 0123456789abcdef]
% rc4::rc4 -hex -key $keydata HelloWorld
3cf1ae8b7f1c670b612f
% rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f]
HelloWorld
set Key [rc4::RC4Init "key data"]
append ciphertext [rc4::RC4 $Key $plaintext]
append ciphertext [rc4::RC4 $Key $additional_plaintext]
rc4::RC4Final $Key
proc ::Finish {myState data} {
DoStuffWith $myState $data
}
rc4::rc4 -in $socket -command [list ::Finish $ApplicationState]
# <a name='section5'></a>AUTHORS
Pat Thoyts
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *rc4* 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.
# <a name='see-also'></a>SEE ALSO
[aes(n)](../aes/aes.md), [blowfish(n)](../blowfish/blowfish.md),
[des(n)](../des/des.md)
# <a name='keywords'></a>KEYWORDS
[arcfour](../../../../index.md#arcfour), [data
integrity](../../../../index.md#data_integrity),
[encryption](../../../../index.md#encryption), [rc4](../../../../index.md#rc4),
[security](../../../../index.md#security), [stream
cipher](../../../../index.md#stream_cipher)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/rcs/rcs.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
|
[//000000001]: # (rcs - RCS low level utilities)
[//000000002]: # (Generated from file 'rcs.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (rcs(n) 2.0.2 tcllib "RCS low level utilities")
# NAME
rcs - RCS low level utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [TEXT DICT DATA STRUCTURE](#section3)
- [RCS PATCH FORMAT](#section4)
- [RCS PATCH COMMAND LIST](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require rcs ?0.1?
[__::rcs::text2dict__ *text*](#1)
[__::rcs::dict2text__ *dict*](#2)
[__::rcs::file2dict__ *filename*](#3)
[__::rcs::dict2file__ *filename* *dict*](#4)
[__::rcs::decodeRcsPatch__ *text*](#5)
[__::rcs::encodeRcsPatch__ *pcmds*](#6)
[__::rcs::applyRcsPatch__ *text* *pcmds*](#7)
# <a name='description'></a>DESCRIPTION
The *Revision Control System*, short *[RCS](../../../../index.md#rcs)*, is a set
of applications and related data formats which allow a system to persist the
history of changes to a text. It, and its relative SCCS are the basis for many
other such systems, like *[CVS](../../../../index.md#cvs)*, etc.
This package *does not* implement RCS.
It only provides a number of low level commands which should be useful in the
implementation of any revision management system, namely:
1. The conversion of texts into and out of a data structures which allow the
easy modification of such text by *patches*, i.e. sequences of instructions
for the transformation of one text into an other.
1. And the conversion of one particular format for patches, the so-called *RCS
patches*, into and out of data structures which allow their easy
application to texts.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::rcs::text2dict__ *text*
Converts the argument *text* into a dictionary containing and representing
the same text in an indexed form and returns that dictionary as its result.
More information about the format of the result can be found in section
[TEXT DICT DATA STRUCTURE](#section3). This command returns the *canonical*
representation of the input.
- <a name='2'></a>__::rcs::dict2text__ *dict*
This command provides the complementary operation to __::rcs::text2dict__.
It converts a dictionary in the form described in section [TEXT DICT DATA
STRUCTURE](#section3) back into a text and returns that text as its result.
The command does accept non-canonical representations of the text as its
input.
- <a name='3'></a>__::rcs::file2dict__ *filename*
This command is identical to __::rcs::text2dict__, except that it reads the
text to convert from the file with path *filename*. The file has to exist
and must be readable as well.
- <a name='4'></a>__::rcs::dict2file__ *filename* *dict*
This command is identical to __::rcs::2dict2text__, except that it stores
the resulting text in the file with path *filename*. The file is created if
it did not exist, and must be writable. The result of the command is the
empty string.
- <a name='5'></a>__::rcs::decodeRcsPatch__ *text*
Converts the *text* argument into a patch command list (PCL) as specified in
the section [RCS PATCH COMMAND LIST](#section5) and returns this list as its
result. It is assumed that the input text is in *[diff -n
format](../../../../index.md#diff_n_format)*, also known as *[RCS
patch](../../../../index.md#rcs_patch)* format, as specified in the section
[RCS PATCH FORMAT](#section4). Please note that the command ignores no-ops
in the input, in other words the resulting PCL contains only instructions
doing something.
- <a name='6'></a>__::rcs::encodeRcsPatch__ *pcmds*
This command provides the complementary operation to
__::rcs::decodeRcsPatch__. It convert a patch comand list (PCL) list as
specified in the section [RCS PATCH COMMAND LIST](#section5) back into a
text in [RCS PATCH FORMAT](#section4) and returns that text as its result.
Note that this command and __::rcs::decodeRcsPatch__ are not exactly
complementary, as the latter strips no-ops from its input, which the encoder
cannot put back anymore into the generated RCS patch. In other words, the
result of a decode/encode step may not match the original input at the
character level, but it will match it at the functional level.
- <a name='7'></a>__::rcs::applyRcsPatch__ *text* *pcmds*
This operation applies a patch in the form of a PCL to a text given in the
form of a dictionary and returns the modified text, again as dictionary, as
its result.
To handle actual text use the commands __::rcs::text2dict__ (or equivalent)
and __::rcs::decodeRcsPatch__ to transform the inputs into data structures
acceptable to this command. Analogously use the command __::rcs::dict2text__
(or equivalent) to transform the result of this command into actuall text as
required.
# <a name='section3'></a>TEXT DICT DATA STRUCTURE
A text dictionary is a dictionary whose keys are integer numbers and text
strings as the associated values. The keys represent the line numbers of a text
and the values the text of that line. Note that one text can have many
representations as a dictionary, as the index values only have to be properly
ordered for reconstruction, their exact values do not matter. Similarly the
strings may actually span multiple physical lines.
The text
Hello World,
how are you ?
Fine, and you ?
for example can be represented by
{{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}}
or
{{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}}
or
{{-1 {Hello World,
how are you ?}} {4 {Fine, and you ?}}}
The first dictionary is the *canonical* representation of the text, with line
numbers starting at __1__, increasing in steps of __1__ and without gaps, and
each value representing exactly one physical line.
All the commands creating dictionaries from text will return the canonical
representation of their input text. The commands taking a dictionary and
returning text will generally accept all representations, canonical or not.
The result of applying a patch to a text dictionary will in general cause the
dictionary to become non-canonical.
# <a name='section4'></a>RCS PATCH FORMAT
A *[patch](../../../../index.md#patch)* is in general a series of instructions
how to transform an input text T into a different text T', and also encoded in
text form as well.
The text format for patches understood by this package is a very simple one,
known under the names *[RCS patch](../../../../index.md#rcs_patch)* or *[diff -n
format](../../../../index.md#diff_n_format)*.
Patches in this format contain only two different commands, for the deletion of
old text, and addition of new text. The replacement of some text by a different
text is handled as combination of a deletion following by an addition.
The format is line oriented, with each line containing either a command or text
data associated with the preceding command. The first line of a *[RCS
patch](../../../../index.md#rcs_patch)* is always a command line.
The commands are:
- ""
The empty line is a command which does nothing.
- "a__start__ __n__"
A line starting with the character __a__ is a command for the addition of
text to the output. It is followed by __n__ lines of text data. When
applying the patch the data is added just between the lines __start__ and
__start__+1. The same effect is had by appending the data to the existing
text on line __start__. A non-existing line __start__ is created.
- "d__start__ __n__"
A line starting with the character __d__ is a command for the deletion of
text from the output. When applied it deletes __n__ lines of text, and the
first line deleted is at index __start__.
Note that the line indices __start__ always refer to the text which is
transformed as it is in its original state, without taking the precending
changes into account.
Note also that the instruction have to be applied in the order they occur in the
patch, or in a manner which produces the same result as in-order application.
This is the format of results returned by the command __::rcs::decodeRcsPatch__
and accepted by the commands __::rcs::encodeRcsPatch__ and
__::rcs::appplyRcsPatch__ resp. Note however that the decoder will strip no-op
commands, and the encoder will not generate no-ops, making them not fully
complementary at the textual level, only at the functional level.
And example of a RCS patch is
d1 2
d4 1
a4 2
The named is the mother of all things.
a11 3
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
# <a name='section5'></a>RCS PATCH COMMAND LIST
Patch command lists (sort: PCL's) are the data structures generated by patch
decoder command and accepted by the patch encoder and applicator commands. They
represent RCS patches in the form of Tcl data structures.
A PCL is a list where each element represents a single patch instruction, either
an addition, or a deletion. The elements are lists themselves, where the first
item specifies the command and the remainder represent the arguments of the
command.
- a
This is the instruction for the addition of text. It has two arguments, the
index of the line where to add the text, and the text to add, in this order.
- d
This is the instruction for the deletion of text. It has two arguments, the
index of the line where to start deleting text, and the number of lines to
delete, in this order.
This is the format returned by the patch decoder command and accepted as input
by the patch encoder and applicator commands.
An example for a patch command is shown below, it represents the example RCS
patch found in section [RCS PATCH FORMAT](#section4).
{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.
}} {a 11 {They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!}}}
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *rcs* 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.
# <a name='see-also'></a>SEE ALSO
[struct](../../../../index.md#struct), [textutil](../textutil/textutil.md)
# <a name='keywords'></a>KEYWORDS
[CVS](../../../../index.md#cvs), [RCS](../../../../index.md#rcs), [RCS
patch](../../../../index.md#rcs_patch), [SCCS](../../../../index.md#sccs), [diff
-n format](../../../../index.md#diff_n_format),
[patching](../../../../index.md#patching), [text
conversion](../../../../index.md#text_conversion), [text
differences](../../../../index.md#text_differences)
# <a name='category'></a>CATEGORY
Text processing
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005, Andreas Kupries <[email protected]>
Copyright © 2005, Colin McCormack <[email protected]>
|
Added embedded/md/tcllib/files/modules/report/report.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
|
[//000000001]: # (report - Matrix reports)
[//000000002]: # (Generated from file 'report.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (report(n) 0.3.2 tcllib "Matrix reports")
# NAME
report - Create and manipulate report objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [REGIONS](#section2)
- [LINES](#section3)
- [TEMPLATES](#section4)
- [STYLES](#section5)
- [REPORT METHODS](#section6)
- [EXAMPLES](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require report ?0.3.2?
[__::report::report__ *reportName* *columns* ?__style__ *style arg...*?](#1)
[__reportName__ *option* ?*arg arg ...*?](#2)
[__::report::defstyle__ *styleName arguments script*](#3)
[__::report::rmstyle__ *styleName*](#4)
[__::report::stylearguments__ *styleName*](#5)
[__::report::stylebody__ *styleName*](#6)
[__::report::styles__](#7)
[*reportName* __destroy__](#8)
[*reportName* *templatecode* __disable__|__enable__](#9)
[*reportName* *templatecode* __enabled__](#10)
[*reportName* *templatecode* __get__](#11)
[*reportName* *templatecode* __set__ *templatedata*](#12)
[*reportName* __tcaption__ ?*size*?](#13)
[*reportName* __bcaption__ *size*](#14)
[*reportName* __size__ *column* ?*number*|__dyn__?](#15)
[*reportName* __sizes__ ?*size-list*?](#16)
[*reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*??](#17)
[*reportName* __justify__ *column* ?__left__|__right__|__center__?](#18)
[*reportName* __printmatrix__ *matrix*](#19)
[*reportName* __printmatrix2channel__ *matrix chan*](#20)
[*reportName* __[columns](../../../../index.md#columns)__](#21)
# <a name='description'></a>DESCRIPTION
This package provides report objects which can be used by the formatting methods
of matrix objects to generate tabular reports of the matrix in various forms.
The report objects defined here break each report down into three
[REGIONS](#section2) and ten classes of *[lines](../../../../index.md#lines)*
(various separator- and data-lines). See the following section for more detailed
explanations.
- <a name='1'></a>__::report::report__ *reportName* *columns* ?__style__ *style arg...*?
Creates a new report object for a report having *columns* columns with an
associated global Tcl command whose name is *reportName*. This command may
be used to invoke various configuration operations on the report. It has the
following general form:
* <a name='2'></a>__reportName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. See
section [REPORT METHODS](#section6) for more explanations. If no
__style__ is specified the report will use the builtin style __plain__
as its default configuration.
- <a name='3'></a>__::report::defstyle__ *styleName arguments script*
Defines the new style *styleName*. See section [STYLES](#section5) for more
information.
- <a name='4'></a>__::report::rmstyle__ *styleName*
Deletes the style *styleName*. Trying to delete an unknown or builtin style
will result in an error. Beware, this command will not check that there are
no other styles depending on the deleted one. Deleting a style which is
still used by another style FOO will result in a runtime error when FOO is
applied to a newly instantiated report.
- <a name='5'></a>__::report::stylearguments__ *styleName*
This introspection command returns the list of arguments associated with the
style *styleName*.
- <a name='6'></a>__::report::stylebody__ *styleName*
This introspection command returns the script associated with the style
*styleName*.
- <a name='7'></a>__::report::styles__
This introspection command returns a list containing the names of all styles
known to the package at the time of the call. The order of the names in the
list reflects the order in which the styles were created. In other words,
the first item is the predefined style __plain__, followed by the first
style defined by the user, and so on.
# <a name='section2'></a>REGIONS
The three regions are the *top caption*, *data area* and *bottom caption*. These
are, roughly speaking, the title, the values to report and a title at the
bottom. The size of the caption regions can be specified by the user as the
number of rows they occupy in the matrix to format. The size of the data area is
specified implicitly.
# <a name='section3'></a>LINES
[TEMPLATES](#section4) are associated with each of the ten line classes,
defining the formatting for this kind of line. The user is able to enable and
disable the separator lines at will, but not the data lines. Their usage is
solely determined by the number of rows contained in the three regions. Data
lines and all enabled separators must have a template associated with them.
Note that the data-lines in a report and the rows in the matrix the report was
generated from are *not* in a 1:1 relationship if any row in the matrix has a
height greater than one.
The different kinds of lines and the codes used by the report methods to address
them are:
- __top__
The topmost line of a report. Separates the report from anything which came
before it. The user can enable the usage of this line at will.
- __topdatasep__
This line is used to separate the data rows in the top caption region, if it
contains more than one row and the user enabled its usage.
- __topcapsep__
This line is used to separate the top caption and data regions, if the top
caption is not empty and the user enabled its usage.
- __datasep__
This line is used to separate the data rows in the data region, if it
contains more than one row and the user enabled its usage.
- __botcapsep__
This line is used to separate the data and bottom caption regions, if the
bottom caption is not empty and the user enabled its usage.
- __botdatasep__
This line is used to separate the data rows in the bottom caption region, if
it contains more than one row and the user enabled its usage.
- __bottom__
The bottommost line of a report. Separates the report from anything which
comes after it. The user can enable the usage of this line at will.
- __topdata__
This line defines the format of data lines in the top caption region of the
report.
- __data__
This line defines the format of data lines in the data region of the report.
- __botdata__
This line defines the format of data lines in the bottom caption region of
the report.
# <a name='section4'></a>TEMPLATES
Each template is a list of strings used to format the line it is associated
with. For a report containing __n__ columns a template for a data line has to
contain "__n__+1" items and a template for a separator line "2*__n__+1" items.
The items in a data template specify the strings used to separate the column
information. Together with the corresponding items in the separator templates
they form the vertical lines in the report.
*Note* that the corresponding items in all defined templates have to be of equal
length. This will be checked by the report object. The first item defines the
leftmost vertical line and the last item defines the rightmost vertical line.
The item at index __k__ ("1",...,"__n__-2") separates the information in the
columns "__k__-1" and "__k__".
The items in a separator template having an even-numbered index ("0","2",...)
specify the column separators. The item at index "2*__k__"
("0","2",...,"2*__n__") corresponds to the items at index "__k__" in the data
templates.
The items in a separator template having an odd-numbered index ("1","3",...)
specify the strings used to form the horizontal lines in the separator lines.
The item at index "2*__k__+1" ("1","3",...,"2*__n__+1") corresponds to column
"__k__". When generating the horizontal lines the items are replicated to be at
least as long as the size of their column and then cut to the exact size.
# <a name='section5'></a>STYLES
Styles are a way for the user of this package to define common configurations
for report objects and then use them later during the actual instantiation of
report objects. They are defined as tcl scripts which when executed configure
the report object into the requested configuration.
The command to define styles is __::report::defstyle__. Its last argument is the
tcl __script__ performing the actual reconfiguration of the report object to
obtain the requested style.
In this script the names of all previously defined styles are available as
commands, as are all commands found in a safe interpreter and the configuration
methods of report objects. The latter implicitly operate on the object currently
executing the style script. The __arguments__ declared here are available in the
__script__ as variables. When calling the command of a previously declared style
all the arguments expected by it have to be defined in the call.
# <a name='section6'></a>REPORT METHODS
The following commands are possible for report objects:
- <a name='8'></a>*reportName* __destroy__
Destroys the report, including its storage space and associated command.
- <a name='9'></a>*reportName* *templatecode* __disable__|__enable__
Enables or disables the usage of the template addressed by the
*templatecode*. Only the codes for separator lines are allowed here. It is
not possible to enable or disable data lines.
Enabling a template causes the report to check all used templates for
inconsistencies in the definition of the vertical lines (See section
[TEMPLATES](#section4)).
- <a name='10'></a>*reportName* *templatecode* __enabled__
Returns the whether the template addressed by the *templatecode* is
currently enabled or not.
- <a name='11'></a>*reportName* *templatecode* __get__
Returns the template currently associated with the kind of line addressed by
the *templatecode*. All known templatecodes are allowed here.
- <a name='12'></a>*reportName* *templatecode* __set__ *templatedata*
Sets the template associated with the kind of line addressed by the
*templatecode* to the new value in *templatedata*. See section
[TEMPLATES](#section4) for constraints on the length of templates.
- <a name='13'></a>*reportName* __tcaption__ ?*size*?
Specifies the *size* of the top caption region as the number rows it
occupies in the matrix to be formatted. Only numbers greater than or equal
to zero are allowed. If no *size* is specified the command will return the
current size instead.
Setting the size of the top caption to a value greater than zero enables the
corresponding data template and causes the report to check all used
templates for inconsistencies in the definition of the vertical lines (See
section [TEMPLATES](#section4)).
- <a name='14'></a>*reportName* __bcaption__ *size*
Specifies the *size* of the bottom caption region as the number rows it
occupies in the matrix to be formatted. Only numbers greater than or equal
to zero are allowed. If no *size* is specified the command will return the
current size instead.
Setting the size of the bottom caption to a value greater than zero enables
the corresponding data template and causes the report to check all used
templates for inconsistencies in the definition of the vertical lines (See
section [TEMPLATES](#section4)).
- <a name='15'></a>*reportName* __size__ *column* ?*number*|__dyn__?
Specifies the size of the *column* in the output. The value __dyn__ means
that the columnwidth returned by the matrix to be formatted for the
specified column shall be used. The formatting of the column is dynamic. If
a fixed *number* is used instead of __dyn__ it means that the column has a
width of that many characters (padding excluded). Only numbers greater than
zero are allowed here.
If no size specification is given the command will return the current size
of the *column* instead.
- <a name='16'></a>*reportName* __sizes__ ?*size-list*?
This method allows the user to specify the sizes of all columns in one call.
Its argument is a list containing the sizes to associate with the columns.
The first item is associated with column 0, the next with column 1, and so
on.
If no *size-list* is specified the command will return a list containing the
currently set sizes instead.
- <a name='17'></a>*reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*??
This method allows the user to specify padding on the left, right or both
sides of a *column*. If the *padstring* is not specified it defaults to a
single space character. *Note*: An alternative way of specifying the padding
is to use vertical separator strings longer than one character in the
templates (See section [TEMPLATES](#section4)).
If no pad specification is given at all the command will return the current
state of padding for the column instead. This will be a list containing two
elements, the first element the left padding, the second describing the
right padding.
- <a name='18'></a>*reportName* __justify__ *column* ?__left__|__right__|__center__?
Declares how the cell values for a *column* are filled into the report given
the specified size of a column in the report.
For __left__ and __right__ justification a cell value shorter than the width
of the column is bound with its named edge to the same edge of the column.
The other side is filled with spaces. In the case of __center__ the spaces
are placed to both sides of the value and the left number of spaces is at
most one higher than the right number of spaces.
For a value longer than the width of the column the value is cut at the
named edge. This means for __left__ justification that the *tail* (i.e. the
__right__ part) of the value is made visible in the output. For __center__
the value is cut at both sides to fit into the column and the number of
characters cut at the left side of the value is at most one less than the
number of characters cut from the right side.
If no justification was specified the command will return the current
justification for the column instead.
- <a name='19'></a>*reportName* __printmatrix__ *matrix*
Formats the *matrix* according to the configuration of the report and
returns the resulting string. The matrix has to have the same number of
columns as the report. The matrix also has to have enough rows so that the
top and bottom caption regions do not overlap. The data region is allowed to
be empty.
- <a name='20'></a>*reportName* __printmatrix2channel__ *matrix chan*
Formats the *matrix* according to the configuration of the report and writes
the result into the channel *chan*. The matrix has to have the same number
of columns as the report. The matrix also has to have enough rows so that
the top and bottom caption regions do not overlap. The data region is
allowed to be empty.
- <a name='21'></a>*reportName* __[columns](../../../../index.md#columns)__
Returns the number of columns in the report.
The methods __size__, __pad__ and __justify__ all take a column index as their
first argument. This index is allowed to use all the forms of an index as
accepted by the __lindex__ command. The allowed range for indices is
"0,...,[__reportName__ columns]-1".
# <a name='section7'></a>EXAMPLES
Our examples define some generally useful report styles.
A simple table with lines surrounding all information and vertical separators,
but without internal horizontal separators.
::report::defstyle simpletable {} {
data set [split "[string repeat "| " [columns]]|"]
top set [split "[string repeat "+ - " [columns]]+"]
bottom set [top get]
top enable
bottom enable
}
An extension of a __simpletable__, see above, with a title area.
::report::defstyle captionedtable {{n 1}} {
simpletable
topdata set [data get]
topcapsep set [top get]
topcapsep enable
tcaption $n
}
Given the definitions above now an example which actually formats a matrix into
a tabular report. It assumes that the matrix actually contains useful data.
% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% r printmatrix m
+---+-------------------+-------+-------+--------+
|000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok |7 |13 |53.85 |
|002|CATCH return error |68 |91 |74.73 |
|003|CATCH no catch used|7 |14 |50.00 |
|004|IF if true numeric |12 |33 |36.36 |
|005|IF elseif |15 |47 |31.91 |
| |true numeric | | | |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% m format 2string r
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *report* 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.
# <a name='keywords'></a>KEYWORDS
[matrix](../../../../index.md#matrix), [report](../../../../index.md#report),
[table](../../../../index.md#table)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002-2014 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/rest/rest.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
|
[//000000001]: # (rest - A framework for RESTful web services)
[//000000002]: # (Generated from file 'rest.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (rest(n) 1.3.1 tcllib "A framework for RESTful web services")
# NAME
rest - define REST web APIs and call them inline or asychronously
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Simple usage](#section2)
- [Interface usage](#section3)
- [Examples](#section4)
- [INCLUDED](#section5)
- [TLS](#section6)
- [TLS Security Considerations](#section7)
- [Bugs, Ideas, Feedback](#section8)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require rest ?1.3.1?
[__::rest::simple__ *url* *query* ?*config*? ?*body*?](#1)
[__::rest::get__ *url* *query* ?*config*? ?*body*?](#2)
[__::rest::post__ *url* *query* ?*config*? ?*body*?](#3)
[__::rest::patch__ *url* *query* ?*config*? ?*body*?](#4)
[__::rest::head__ *url* *query* ?*config*? ?*body*?](#5)
[__::rest::put__ *url* *query* ?*config*? ?*body*?](#6)
[__::rest::delete__ *url* *query* ?*config*? ?*body*?](#7)
[__::rest::save__ *name* *file*](#8)
[__::rest::describe__ *name*](#9)
[__::rest::parameters__ *url* ?*key*?](#10)
[__::rest::parse_opts__ *static* *required* *optional* *words*](#11)
[__::rest::substitute__ *string* *var*](#12)
[__::rest::create_interface__ *name*](#13)
# <a name='description'></a>DESCRIPTION
There are two types of usage this package supports: *simple calls*, and complete
*interfaces*. In an *interface* you specify a set of rules and then the package
builds the commands which correspond to the REST methods. These commands can
have many options such as input and output transformations and data type
specific formatting. This results in a cleaner and simpler script. On the other
hand, while a *simple call* is easier and quicker to implement it is also less
featureful. It takes the url and a few options about the command and returns the
result directly. Any formatting or checking is up to rest of the script.
# <a name='section2'></a>Simple usage
In simple usage you make calls using the http method procedures and then check
or process the returned data yourself
- <a name='1'></a>__::rest::simple__ *url* *query* ?*config*? ?*body*?
- <a name='2'></a>__::rest::get__ *url* *query* ?*config*? ?*body*?
- <a name='3'></a>__::rest::post__ *url* *query* ?*config*? ?*body*?
- <a name='4'></a>__::rest::patch__ *url* *query* ?*config*? ?*body*?
- <a name='5'></a>__::rest::head__ *url* *query* ?*config*? ?*body*?
- <a name='6'></a>__::rest::put__ *url* *query* ?*config*? ?*body*?
- <a name='7'></a>__::rest::delete__ *url* *query* ?*config*? ?*body*?
These commands are all equivalent except for the http method used. If you
use __simple__ then the method should be specified as an option in the
*config* dictionary. If that is not done it defaults to __get__. If a *body*
is needed then the *config* dictionary must be present, however it is
allowed to be empty.
The *config* dictionary supports the following keys
* __auth__
* __content-type__
* __cookie__
* __error-body__
* __format__
* __headers__
* __method__
Two quick examples:
Example 1, Yahoo Boss:
set appid APPID
set search tcl
set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]]
set res [rest::format_json $res]
Example 2, Twitter:
set url http://twitter.com/statuses/update.json
set query [list status $text]
set res [rest::simple $url $query {
method post
auth {basic user password}
format json
}]
# <a name='section3'></a>Interface usage
An interface to a REST API consists of a series of definitions of REST calls
contained in an array. The name of that array becomes a namespace containing the
defined commands. Each key of the array specifies the name of the call, with the
associated configuration a dictionary, i.e. key/value pairs. The acceptable
keys, i.e. legal configuration options are described below. After creating the
definitions in the array simply calling __rest::create_interface__ with the
array as argument will then create the desired commands.
Example, Yahoo Weather:
package require rest
set yweather(forecast) {
url http://weather.yahooapis.com/forecastrss
req_args { p: }
opt_args { u: }
}
rest::create_interface yweather
puts [yweather::forecast -p 94089]
- <a name='8'></a>__::rest::save__ *name* *file*
This command saves a copy of the dynamically created procedures for all the
API calls specified in the array variable *name* to the *file*, for later
loading.
The result of the command is the empty string
- <a name='9'></a>__::rest::describe__ *name*
This command prints a description of all API calls specified in the array
variable *name* to the channel __stdout__.
The result of the command is the empty string.
- <a name='10'></a>__::rest::parameters__ *url* ?*key*?
This command parses an *url* query string into a dictionary and returns said
dictionary as its result.
If *key* is specified the command will not return the entire dictionary, but
only the value of that *key*.
- <a name='11'></a>__::rest::parse_opts__ *static* *required* *optional* *words*
This command implements a custom parserfor command options.
* dict *static*
A dictionary of options and their values that are always present in the
output.
* list *required*
A list of options that must be supplied by *words*
* list *optional*
A list of options that may appear in the *words*, but are not required.
The elements must be in one of three forms:
+ name
The option may be present or not, no default.
+ name:
When present the option requires an argument.
+ name:value
When not present use __value__ as default.
* list *words*
The words to parse into options and values.
The result of the command is a list containing two elements. The first
element is a dictionary containing the parsed options and their values. The
second element is a list of the remaining words.
- <a name='12'></a>__::rest::substitute__ *string* *var*
This command takes a *string*, substitutes values for any option identifiers
found inside and returns the modified string as its results.
The values to substitute are found in the variable *var*, which is expected
to contain a dictionary mapping from the option identifiers to replace to
their values. *Note* that option identifiers which have no key in *var* are
replaced with the empty string.
The option identifiers in *string* have to follow the syntax __%...%__ where
__...__ may contain any combination of lower-case alphanumeric characters,
plus underscore, colon and dash.
- <a name='13'></a>__::rest::create_interface__ *name*
This command creates procedures for all the API calls specified in the array
variable *name*.
The name of that array becomes a namespace containing the defined commands.
Each key of the array specifies the name of the call, with the associated
configuration a dictionary, i.e. key/value pairs. The legal keys and their
meanings are:
* __url__
The value of this *required* option must be the target of the http
request.
* __description__
The value of this option must be a short string describing the call.
Default to the empty string, if not specified. Used only by
__::rest::describe__.
* __body__
The value of this option indicates if arguments are required for the
call's request body or not. The acceptable values are listed below.
Defaults to __optional__ if not specified.
+ __none__
The call has no request body, none must be supplied.
+ __optional__
A request body can be supplied, but is not required.
+ __required__
A request body must be supplied.
+ __argument__
This value must be followed by the name of an option, treating the
entire string as a list. The request body will be used as the value
of that option.
+ __mime_multipart__
A request body must be supplied and will be interpreted as each
argument representing one part of a mime/multipart document.
Arguments must be lists containing 2 elements, a list of header keys
and values, and the mime part body, in this order.
* __method__
The value of this option must be the name of the HTTP method to call on
the url. Defaults to GET, if not specified. The acceptable values are
__GET__, __POST__, and __PUT__, regardless of letter-case.
* __copy__
When present the value of this option specifies the name of a previously
defined call. The definition of that call is copied to the current call,
except for the options specified by the current call itself.
* __unset__
When present the value of this option contains a list of options in the
current call. These options are removed from the definition. Use this
after __copy__ing an existing definition to remove options, instead of
overriding their value.
* __headers__
Specification of additional header fields. The value of this option must
be a dictionary, interpreted to contain the new header fields and their
values. The default is to not add any additional headers.
* __content-type__
The value of this option specifies the content type for the request
data.
* __req_args__
The value of this option is a list naming the required arguments of the
call. Names ending in a colon will require a value.
* __opt_args__
The value of this option a list naming the arguments that may be present
for a call but are not required.
* __static_args__
The value of this option a list naming the arguments that are always the
same. No sense in troubling the user with these. A leading dash (__-__)
is allowed but not required to maintain consistency with the command
line.
* __auth__
The value of this option specifies how to authenticate the calls. No
authentication is done if the option is not specified.
+ __basic__
The user may configure the *basic authentication* by overriding the
procedure __basic_auth__ in the namespace of interface. This
procedure takes two arguments, the username and password, in this
order.
+ __sign__
The value must actually be a list with the second element the name
of a procedure which will be called to perform request signing.
* __callback__
If this option is present then the method will be created as an *async*
call. Such calls will return immediately with the value of the
associated http token instead of the call's result. The event loop must
be active to use this option.
The value of this option is treated as a command prefix which is invoked
when the HTTP call is complete. The prefix will receive at least two
additional arguments, the name of the calling procedure and the status
of the result (one of __OK__ or __ERROR__), in this order.
In case of __OK__ a third argument is added, the data associated with
the result.
If and only if the __ERROR__ is a redirection, the location redirected
to will be added as argument. Further, if the configuration key
__error-body__ is set to __true__ the data associated with the result
will be added as argument as well.
The http request header will be available in that procedure via __upvar
token token__.
* __cookie__
The value of this option is a list of cookies to be passed in the http
header. This is a shortcut to the __headers__ option.
* __input_transform__
The value of this option is a command prefix or script to perform a
transformation on the query before invoking the call. A script transform
is wrapped into an automatically generated internal procedure.
If not specified no transformation is done.
The command (prefix) must accept a single argument, the query (a
dictionary) to transform, and must return the modified query (again as
dictionary) as its result. The request body is accessible in the
transform command via __upvar body body__.
* __format__
* __result__
The value of this option specifies the format of the returned data.
Defaults to __auto__ if not specified. The acceptable values are:
+ __auto__
Auto detect between __xml__ and __json__.
+ __discard__
+ __json__
+ __raw__
+ __rss__
This is formatted as a special case of __xml__.
+ __tdom__
+ __xml__
* __pre_transform__
The value of this option is a command prefix or script to perform a
transformation on the result of a call (*before* the application of the
output transform as per __format__). A script transform is wrapped into
an automatically generated internal procedure.
If not specified no transformation is done.
The command (prefix) must accept a single argument, the result to
transform, and must return the modified result as its result.
The http request header is accessible in the transform command via
__upvar token token__
* __post_transform__
The value of this option is a command prefix or script to perform a
transformation on the result of a call (*after* the application of the
output transform as per __format__). A script transform is wrapped into
an automatically generated internal procedure.
If not specified no transformation is done.
The command (prefix) must accept a single argument, the result to
transform, and must return the modified result as its result.
The http request header is accessible in the transform command via
__upvar token token__
* __check_result__
The value of this option must be list of two expressions, either of
which may be empty.
The first expression is checks the OK condition, it must return __true__
when the result is satisfactory, and __false__ otherwise.
The second expression is the ERROR condition, it must return __false__
unless there is an error, then it has to return __true__.
* __error_body__
The value of this option determines whether to return the response when
encountering an HTTP error, or not. The default is to not return the
response body on error.
See __callback__ above for more information.
# <a name='section4'></a>Examples
Yahoo Geo:
set ygeo(parse) {
url http://wherein.yahooapis.com/v1/document
method post
body { arg documentContent }
}
ygeo::parse "san jose ca"
# "san jose ca" will be interpreted as if it were specified as the -documentContent option
Google Docs:
set gdocs(upload) {
url http://docs.google.com/feeds/default/private/full
body mime_multipart
}
gdocs::upload [list {Content-Type application/atom+xml} $xml] [list {Content-Type image/jpeg} $filedata]
Delicious:
set delicious(updated) {
url https://api.del.icio.us/v1/posts/update
auth basic
}
rest::create_interface flickr
flickr::basic_auth username password
Flickr:
set flickr(auth.getToken) {
url http://api.flickr.com/services/rest/
req_args { api_key: secret: }
auth { sign do_signature }
}
rest::create_interface flickr
proc ::flickr::do_signature {query} {
# perform some operations on the query here
return $query
}
# <a name='section5'></a>INCLUDED
The package provides functional but incomplete implementations for the following
services:
- __del.icio.us__
- __facebook__
- __flickr__
- __twitter__
- __google calendar__
- __yahoo boss__
- __yahoo weather__
Please either read the package's implementation, or use __rest::describe__ after
loading it for their details.
Do not forget developers' documentation on the respective sites either.
# <a name='section6'></a>TLS
The __rest__ package can be used with
*[https](../../../../index.md#https)*-secured services, by requiring the
__[TLS](../../../../index.md#tls)__ package and then registering it with the
__[http](../../../../index.md#http)__ package it is sitting on top of. Example
package require tls
http::register https 443 ::tls::socket
# <a name='section7'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *rest* 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.
|
Added embedded/md/tcllib/files/modules/ripemd/ripemd128.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
[//000000001]: # (ripemd128 - RIPEMD Message-Digest Algorithm)
[//000000002]: # (Generated from file 'ripemd128.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ripemd128(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm")
# NAME
ripemd128 - RIPEMD-128 Message-Digest Algorithm
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require ripemd128 ?1.0.5?
[__::ripemd::ripemd128__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]](#1)
[__::ripemd::hmac128__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]](#2)
[__::ripemd::RIPEMD128Init__](#3)
[__::ripemd::RIPEMD128Update__ *token* *data*](#4)
[__::ripemd::RIPEMD128Final__ *token*](#5)
[__::ripemd::RIPEHMAC128Init__ *key*](#6)
[__::ripemd::RIPEHMAC128Update__ *token* *data*](#7)
[__::ripemd::RIPEHMAC128Final__ *token*](#8)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the RIPEMD-128 message-digest
algorithm (1). This algorithm takes an arbitrary quantity of data and generates
a 128-bit message digest from the input. The RIPEMD-128 algorithm is based upon
the MD4 algorithm (2, 4) but has been cryptographically strengthened against
weaknesses that have been found in MD4 (4). RIPEMD-128 has been designed to be a
drop-in replacement for MD4 and MD5 (5). If security is the major consideration,
then RIPEMD-160 or SHA1 should be considered.
This package will use __Trf__ to accelerate the digest computation if available.
In the absence of an accelerator package the pure-Tcl implementation will be
used.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::ripemd::ripemd128__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]
Calculate the RIPEMD-128 digest of the data given in string. This is
returned as a binary string by default. Giving the *-hex* option will return
a hexadecimal encoded version of the digest.
The data to be hashed can be specified either as a string argument to the
ripemd128 command, or as a filename or a pre-opened channel. If the
*-filename* argument is given then the file is opened, the data read and
hashed and the file is closed. If the *-channel* argument is given then data
is read from the channel until the end of file. The channel is not closed.
Only one of *-file*, *-channel* or *string* should be given.
- <a name='2'></a>__::ripemd::hmac128__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]
Calculate an Hashed Message Authentication digest (HMAC) using the
RIPEMD-128 digest algorithm. HMACs are described in RFC 2104 (6) and provide
a RIPEMD-128 digest that includes a key. All options other than *-key* are
as for the __::ripemd::ripemd128__ command.
# <a name='section3'></a>PROGRAMMING INTERFACE
For the programmer, hash functions can be viewed as a bucket into which one
pours data. When you have finished, you extract a value that is uniquely derived
from the data that was poured into the bucket. The programming interface to the
hash operates on a token (equivalent to the bucket). You call __RIPEMD128Init__
to obtain a token and then call __RIPEMD128Update__ as many times as required to
add data to the hash. To release any resources and obtain the hash value, you
then call __RIPEMD128Final__. An equivalent set of functions gives you a keyed
digest (HMAC).
If you have __critcl__ and have built the __tcllibc__ package then the
implementation of the hashing function will be performed by compiled code.
Alternatively if both the Trf and Memchan extensions are available then these
will be used. Finally the package will revert to a pure-Tcl implementation. The
programming interface remains the same, however.
- <a name='3'></a>__::ripemd::RIPEMD128Init__
Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the
remaining functions.
- <a name='4'></a>__::ripemd::RIPEMD128Update__ *token* *data*
Add data to the hash identified by token. Calling *RIPEMD128Update $token
"abcd"* is equivalent to calling *RIPEMD128Update $token "ab"* followed by
*RIPEMD128Update $token "cb"*. See [EXAMPLES](#section4).
- <a name='5'></a>__::ripemd::RIPEMD128Final__ *token*
Returns the hash value and releases any resources held by this token. Once
this command completes the token will be invalid. The result is a binary
string of 16 bytes representing the 128 bit RIPEMD-128 digest value.
- <a name='6'></a>__::ripemd::RIPEHMAC128Init__ *key*
This is equivalent to the __::ripemd::RIPEMD128Init__ command except that it
requires the key that will be included in the HMAC.
- <a name='7'></a>__::ripemd::RIPEHMAC128Update__ *token* *data*
- <a name='8'></a>__::ripemd::RIPEHMAC128Final__ *token*
These commands are identical to the RIPEMD128 equivalent commands.
# <a name='section4'></a>EXAMPLES
% ripemd::ripemd128 -hex "Tcl does RIPEMD-128"
3cab177bae65205d81e7978f63556c63
% ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128"
b359dc5971a05beea0be7b106b30e389
% set tok [ripemd::RIPEMD128Init]
::ripemd::1
% ripemd::RIPEMD128Update $tok "Tcl "
% ripemd::RIPEMD128Update $tok "does "
% ripemd::RIPEMD128Update $tok "RIPEMD-128"
% ripemd::Hex [ripemd::RIPEMD128Final $tok]
3cab177bae65205d81e7978f63556c63
# <a name='section5'></a>REFERENCES
1. H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened
version of RIPEMD"
[http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf](http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf)
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes and S.A.
Vanstone, editors, Advances in Cryptology - CRYPTO '90 Proceedings, pages
303-311, Springer-Verlag, 1991.
1. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology vol 11 (4),
pp. 253-271 (1998)
1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data
Security, Inc, April 1992.
([http://www.rfc-editor.org/rfc/rfc1321.txt](http://www.rfc-editor.org/rfc/rfc1321.txt))
1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997.
([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ripemd* 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.
# <a name='see-also'></a>SEE ALSO
[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd160](ripemd160.md),
[sha1](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[RIPEMD](../../../../index.md#ripemd), [hashing](../../../../index.md#hashing),
[md4](../../../../index.md#md4),
[message-digest](../../../../index.md#message_digest), [rfc
1320](../../../../index.md#rfc_1320), [rfc 1321](../../../../index.md#rfc_1321),
[rfc 2104](../../../../index.md#rfc_2104),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/ripemd/ripemd160.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
[//000000001]: # (ripemd160 - RIPEMD Message-Digest Algorithm)
[//000000002]: # (Generated from file 'ripemd160.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (ripemd160(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm")
# NAME
ripemd160 - RIPEMD-160 Message-Digest Algorithm
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require ripemd160 ?1.0.5?
[__::ripemd::ripemd160__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]](#1)
[__::ripemd::hmac160__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]](#2)
[__::ripemd::RIPEMD160Init__](#3)
[__::ripemd::RIPEMD160Update__ *token* *data*](#4)
[__::ripemd::RIPEMD160Final__ *token*](#5)
[__::ripemd::RIPEHMAC160Init__ *key*](#6)
[__::ripemd::RIPEHMAC160Update__ *token* *data*](#7)
[__::ripemd::RIPEHMAC160Final__ *token*](#8)
# <a name='description'></a>DESCRIPTION
This package is an implementation in Tcl of the RIPEMD-160 message-digest
algorithm (1). This algorithm takes an arbitrary quantity of data and generates
a 160-bit message digest from the input. The RIPEMD-160 algorithm is based upon
the MD4 algorithm (2, 4) but has been cryptographically strengthened against
weaknesses that have been found in MD4 (4).
This package will use __cryptkit__ or __Trf__ to accelerate the digest
computation if either package is available. In the absence of an accelerator
package the pure-Tcl implementation will be used.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::ripemd::ripemd160__ ?*-hex*? [ *-channel channel* | *-file filename* | *string* ]
Calculate the RIPEMD-160 digest of the data given in string. This is
returned as a binary string by default. Giving the *-hex* option will return
a hexadecimal encoded version of the digest.
The data to be hashed can be specified either as a string argument to the
ripemd160 command, or as a filename or a pre-opened channel. If the
*-filename* argument is given then the file is opened, the data read and
hashed and the file is closed. If the *-channel* argument is given then data
is read from the channel until the end of file. The channel is not closed.
Only one of *-file*, *-channel* or *string* should be given.
- <a name='2'></a>__::ripemd::hmac160__ ?*-hex*? *-key key* [ *-channel channel* | *-file filename* | *string* ]
Calculate an Hashed Message Authentication digest (HMAC) using the
RIPEMD-160 digest algorithm. HMACs are described in RFC 2104 (5) and provide
a RIPEMD-160 digest that includes a key. All options other than *-key* are
as for the __::ripemd::ripemd160__ command.
# <a name='section3'></a>PROGRAMMING INTERFACE
For the programmer, hash functions can be viewed as a bucket into which one
pours data. When you have finished, you extract a value that is uniquely derived
from the data that was poured into the bucket. The programming interface to the
hash operates on a token (equivalent to the bucket). You call __RIPEMD160Init__
to obtain a token and then call __RIPEMD160Update__ as many times as required to
add data to the hash. To release any resources and obtain the hash value, you
then call __RIPEMD160Final__. An equivalent set of functions gives you a keyed
digest (HMAC).
- <a name='3'></a>__::ripemd::RIPEMD160Init__
Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the
remaining functions.
- <a name='4'></a>__::ripemd::RIPEMD160Update__ *token* *data*
Add data to the hash identified by token. Calling *RIPEMD160Update $token
"abcd"* is equivalent to calling *RIPEMD160Update $token "ab"* followed by
*RIPEMD160Update $token "cb"*. See [EXAMPLES](#section4).
- <a name='5'></a>__::ripemd::RIPEMD160Final__ *token*
Returns the hash value and releases any resources held by this token. Once
this command completes the token will be invalid. The result is a binary
string of 16 bytes representing the 160 bit RIPEMD-160 digest value.
- <a name='6'></a>__::ripemd::RIPEHMAC160Init__ *key*
This is equivalent to the __::ripemd::RIPEMD160Init__ command except that it
requires the key that will be included in the HMAC.
- <a name='7'></a>__::ripemd::RIPEHMAC160Update__ *token* *data*
- <a name='8'></a>__::ripemd::RIPEHMAC160Final__ *token*
These commands are identical to the RIPEMD160 equivalent commands.
# <a name='section4'></a>EXAMPLES
% ripemd::ripemd160 -hex "Tcl does RIPEMD-160"
0829dea75a1a7074c702896723fe37763481a0a7
% ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160"
bf0c927231733686731dddb470b64a9c23f7f53b
% set tok [ripemd::RIPEMD160Init]
::ripemd::1
% ripemd::RIPEMD160Update $tok "Tcl "
% ripemd::RIPEMD160Update $tok "does "
% ripemd::RIPEMD160Update $tok "RIPEMD-160"
% ripemd::Hex [ripemd::RIPEMD160Final $tok]
0829dea75a1a7074c702896723fe37763481a0a7
# <a name='section5'></a>REFERENCES
1. H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened
version of RIPEMD"
[http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf](http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf)
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes and S.A.
Vanstone, editors, Advances in Cryptology - CRYPTO '90 Proceedings, pages
303-311, Springer-Verlag, 1991.
1. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology vol 11 (4),
pp. 253-271 (1998)
1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997.
([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *ripemd* 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.
# <a name='see-also'></a>SEE ALSO
[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd128](ripemd128.md),
[sha1](../sha1/sha1.md)
# <a name='keywords'></a>KEYWORDS
[RIPEMD](../../../../index.md#ripemd), [hashing](../../../../index.md#hashing),
[md4](../../../../index.md#md4),
[message-digest](../../../../index.md#message_digest), [rfc
1320](../../../../index.md#rfc_1320), [rfc 1321](../../../../index.md#rfc_1321),
[rfc 2104](../../../../index.md#rfc_2104),
[security](../../../../index.md#security)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/sasl/gtoken.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
[//000000001]: # (SASL::XGoogleToken - Simple Authentication and Security Layer (SASL))
[//000000002]: # (Generated from file 'gtoken.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (SASL::XGoogleToken(n) 1.0.1 tcllib "Simple Authentication and Security Layer (SASL)")
# NAME
SASL::XGoogleToken - Implementation of SASL NTLM mechanism for Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TLS Security Considerations](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require SASL::XGoogleToken ?1.0.1?
# <a name='description'></a>DESCRIPTION
This package provides the XGoogleToken authentication mechanism for the Simple
Authentication and Security Layer (SASL).
Please read the documentation for package __sasl__ for details.
# <a name='section2'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section3'></a>AUTHORS
Pat Thoyts
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *sasl* 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.
# <a name='keywords'></a>KEYWORDS
[SASL](../../../../index.md#sasl),
[XGoogleToken](../../../../index.md#xgoogletoken),
[authentication](../../../../index.md#authentication)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/sasl/ntlm.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
[//000000001]: # (SASL::NTLM - Simple Authentication and Security Layer (SASL))
[//000000002]: # (Generated from file 'ntlm.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (SASL::NTLM(n) 1.1.2 tcllib "Simple Authentication and Security Layer (SASL)")
# NAME
SASL::NTLM - Implementation of SASL NTLM mechanism for Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [REFERENCES](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require SASL::NTLM ?1.1.2?
# <a name='description'></a>DESCRIPTION
This package provides the NTLM authentication mechanism for the Simple
Authentication and Security Layer (SASL).
Please read the documentation for package __sasl__ for details.
# <a name='section2'></a>REFERENCES
1. No official specification is available. However,
[http://davenport.sourceforge.net/ntlm.html](http://davenport.sourceforge.net/ntlm.html)
provides a good description.
# <a name='section3'></a>AUTHORS
Pat Thoyts
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *sasl* 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.
# <a name='keywords'></a>KEYWORDS
[NTLM](../../../../index.md#ntlm), [SASL](../../../../index.md#sasl),
[authentication](../../../../index.md#authentication)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005-2006, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/sasl/sasl.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
|
[//000000001]: # (SASL - Simple Authentication and Security Layer (SASL))
[//000000002]: # (Generated from file 'sasl.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (SASL(n) 1.3.3 tcllib "Simple Authentication and Security Layer (SASL)")
# NAME
SASL - Implementation of SASL mechanisms for Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [OPTIONS](#section3)
- [CALLBACK PROCEDURE](#section4)
- [MECHANISMS](#section5)
- [EXAMPLES](#section6)
- [REFERENCES](#section7)
- [AUTHORS](#section8)
- [Bugs, Ideas, Feedback](#section9)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require SASL ?1.3.3?
[__::SASL::new__ *option value ?...?*](#1)
[__::SASL::configure__ *option value* ?*...*?](#2)
[__::SASL::step__ *context* *challenge* ?*...*?](#3)
[__::SASL::response__ *context*](#4)
[__::SASL::reset__ *context*](#5)
[__::SASL::cleanup__ *context*](#6)
[__::SASL::mechanisms__ ?*type*? ?*minimum*?](#7)
[__::SASL::register__ *mechanism* *preference* *clientproc* ?*serverproc*?](#8)
# <a name='description'></a>DESCRIPTION
The Simple Authentication and Security Layer (SASL) is a framework for providing
authentication and authorization to comunications protocols. The SASL framework
is structured to permit negotiation among a number of authentication mechanisms.
SASL may be used in SMTP, IMAP and HTTP authentication. It is also in use in
XMPP, LDAP and BEEP. See [MECHANISMS](#section5) for the set of available SASL
mechanisms provided with tcllib.
The SASL framework operates using a simple multi-step challenge response
mechanism. All the mechanisms work the same way although the number of steps may
vary. In this implementation a callback procedure must be provided from which
the SASL framework will obtain users details. See [CALLBACK
PROCEDURE](#section4) for details of this procedure.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::SASL::new__ *option value ?...?*
Contruct a new SASL context. See [OPTIONS](#section3) for details of the
possible options to this command. A context token is required for most of
the SASL procedures.
- <a name='2'></a>__::SASL::configure__ *option value* ?*...*?
Modify and inspect the SASL context option. See [OPTIONS](#section3) for
further details.
- <a name='3'></a>__::SASL::step__ *context* *challenge* ?*...*?
This is the core procedure for using the SASL framework. The __step__
procedure should be called until it returns 0. Each step takes a server
challenge string and the response is calculated and stored in the context.
Each mechanism may require one or more steps. For some steps there may be no
server challenge required in which case an empty string should be provided
for this parameter. All mechanisms should accept an initial empty challenge.
- <a name='4'></a>__::SASL::response__ *context*
Returns the next response string that should be sent to the server.
- <a name='5'></a>__::SASL::reset__ *context*
Re-initialize the SASL context. Discards any internal state and permits the
token to be reused.
- <a name='6'></a>__::SASL::cleanup__ *context*
Release all resources associated with the SASL context. The context token
may not be used again after this procedure has been called.
- <a name='7'></a>__::SASL::mechanisms__ ?*type*? ?*minimum*?
Returns a list of all the available SASL mechanisms. The list is sorted by
the mechanism preference value (see __register__) with the preferred
mechanisms and the head of the list. Any mechanism with a preference value
less than the*minimum* (which defaults to 0) is removed from the returned
list. This permits a security threshold to be set. Mechanisms with a
preference less that 25 transmit authentication are particularly susceptible
to eavesdropping and should not be provided unless a secure channel is in
use (eg: tls).
The *type* parameter may be one of *client* or *server* and defaults to
*client*. Only mechanisms that have an implementation matching the *type*
are returned (this permits servers to correctly declare support only for
mechanisms that actually provide a server implementation).
- <a name='8'></a>__::SASL::register__ *mechanism* *preference* *clientproc* ?*serverproc*?
New mechanisms can be added to the package by registering the mechanism name
and the implementing procedures. The server procedure is optional. The
preference value is an integer that is used to order the list returned by
the __mechanisms__ command. Higher values indicate a preferred mechanism. If
the mechanism is already registered then the recorded values are updated.
# <a name='section3'></a>OPTIONS
- __-callback__
Specify a command to be evaluated when the SASL mechanism requires
information about the user. The command is called with the current SASL
context and a name specifying the information desired. See
[EXAMPLES](#section6).
- __-mechanism__
Set the SASL mechanism to be used. See __mechanisms__ for a list of
supported authentication mechanisms.
- __-service__
Set the service type for this context. Some mechanisms may make use of this
parameter (eg DIGEST-MD5, GSSAPI and Kerberos). If not set it defaults to an
empty string. If the __-type__ is set to 'server' then this option should be
set to a valid service identity. Some examples of valid service names are
smtp, ldap, beep and xmpp.
- __-server__
This option is used to set the server name used in SASL challenges when
operating as a SASL server.
- __-type__
The context type may be one of 'client' or 'server'. The default is to
operate as a client application and respond to server challenges. Mechanisms
may be written to support server-side SASL and setting this option will
cause each __step__ to issue the next challenge. A new context must be
created for each incoming client connection when in server mode.
# <a name='section4'></a>CALLBACK PROCEDURE
When the SASL framework requires any user details it will call the procedure
provided when the context was created with an argument that specfies the item of
information required.
In all cases a single response string should be returned.
- login
The callback procedure should return the users authorization identity.
Return an empty string unless this is to be different to the authentication
identity. Read [1] for a discussion about the specific meaning of
authorization and authentication identities within SASL.
- username
The callback procedure should return the users authentication identity. Read
[1] for a discussion about the specific meaning of authorization and
authentication identities within SASL.
- password
The callback procedure should return the password that matches the
authentication identity as used within the current realm.
For server mechanisms the password callback should always be called with the
authentication identity and the realm as the first two parameters.
- realm
Some SASL mechanisms use realms to partition authentication identities. The
realm string is protocol dependent and is often the current DNS domain or in
the case of the NTLM mechanism it is the Windows NT domain name.
- hostname
Returns the client host name - typically [info host].
# <a name='section5'></a>MECHANISMS
- ANONYMOUS
As used in FTP this mechanism only passes an email address for
authentication. The ANONYMOUS mechanism is specified in [2].
- PLAIN
This is the simplest mechanism. The users authentication details are
transmitted in plain text. This mechanism should not be provided unless an
encrypted link is in use - typically after SSL or TLS has been negotiated.
- LOGIN
The LOGIN [1] mechanism transmits the users details with base64 encoding.
This is no more secure than PLAIN and likewise should not be used without a
secure link.
- CRAM-MD5
This mechanism avoids sending the users password over the network in plain
text by hashing the password with a server provided random value (known as a
nonce). A disadvantage of this mechanism is that the server must maintain a
database of plaintext passwords for comparison. CRAM-MD5 was defined in [4].
- DIGEST-MD5
This mechanism improves upon the CRAM-MD5 mechanism by avoiding the need for
the server to store plaintext passwords. With digest authentication the
server needs to store the MD5 digest of the users password which helps to
make the system more secure. As in CRAM-MD5 the password is hashed with a
server nonce and other data before being transmitted across the network.
Specified in [3].
- OTP
OTP is the One-Time Password system described in RFC 2289 [6]. This
mechanism is secure against replay attacks and also avoids storing password
or password equivalents on the server. Only a digest of a seed and a
passphrase is ever transmitted across the network. Requires the
__[otp](../otp/otp.md)__ package from tcllib and one or more of the
cryptographic digest packages (md5 or sha-1 are the most commonly used).
- NTLM
This is a proprietary protocol developed by Microsoft [5] and is in common
use for authenticating users in a Windows network environment. NTLM uses DES
encryption and MD4 digests of the users password to authenticate a
connection. Certain weaknesses have been found in NTLM and thus there are a
number of versions of the protocol. As this mechanism has additional
dependencies it is made available as a separate sub-package. To enable this
mechanism your application must load the __[SASL::NTLM](ntlm.md)__ package.
- X-GOOGLE-TOKEN
This is a proprietary protocol developed by Google and used for
authenticating users for the Google Talk service. This mechanism makes a
pair of HTTP requests over an SSL channel and so this mechanism depends upon
the availability of the tls and http packages. To enable this mechanism your
application must load the __[SASL::XGoogleToken](gtoken.md)__ package. In
addition you are recommended to make use of the autoproxy package to handle
HTTP proxies reasonably transparently.
- SCRAM
This is a protocol specified in RFC 5802 [7]. To enable this mechanism your
application must load the __[SASL::SCRAM](scram.md)__ package.
# <a name='section6'></a>EXAMPLES
See the examples subdirectory for more complete samples using SASL with network
protocols. The following should give an idea how the SASL commands are to be
used. In reality this should be event driven. Each time the __step__ command is
called, the last server response should be provided as the command argument so
that the SASL mechanism can take appropriate action.
proc ClientCallback {context command args} {
switch -exact -- $command {
login { return "" }
username { return $::tcl_platform(user) }
password { return "SecRet" }
realm { return "" }
hostname { return [info host] }
default { return -code error unxpected }
}
}
proc Demo {{mech PLAIN}} {
set ctx [SASL::new -mechanism $mech -callback ClientCallback]
set challenge ""
while {1} {
set more_steps [SASL::step $ctx challenge]
puts "Send '[SASL::response $ctx]'"
puts "Read server response into challenge var"
if {!$more_steps} {break}
}
SASL::cleanup $ctx
}
# <a name='section7'></a>REFERENCES
1. Myers, J. "Simple Authentication and Security Layer (SASL)", RFC 2222,
October 1997.
([http://www.ietf.org/rfc/rfc2222.txt](http://www.ietf.org/rfc/rfc2222.txt))
1. Newman, C. "Anonymous SASL Mechanism", RFC 2245, November 1997.
([http://www.ietf.org/rfc/rfc2245.txt](http://www.ietf.org/rfc/rfc2245.txt))
1. Leach, P., Newman, C. "Using Digest Authentication as a SASL Mechanism",
RFC 2831, May 2000,
([http://www.ietf.org/rfc/rfc2831.txt](http://www.ietf.org/rfc/rfc2831.txt))
1. Klensin, J., Catoe, R. and Krumviede, P., "IMAP/POP AUTHorize Extension for
Simple Challenge/Response" RFC 2195, September 1997.
([http://www.ietf.org/rfc/rfc2195.txt](http://www.ietf.org/rfc/rfc2195.txt))
1. No official specification is available. However,
[http://davenport.sourceforge.net/ntlm.html](http://davenport.sourceforge.net/ntlm.html)
provides a good description.
1. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998,
([http://www.ieft.org/rfc/rfc2289.txt](http://www.ieft.org/rfc/rfc2289.txt))
1. Newman, C. et al., "Salted Challenge Response Authentication Mechanism
(SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010,
([http://www.ieft.org/rfc/rfc5802.txt](http://www.ieft.org/rfc/rfc5802.txt))
# <a name='section8'></a>AUTHORS
Pat Thoyts
# <a name='section9'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *sasl* 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.
# <a name='keywords'></a>KEYWORDS
[SASL](../../../../index.md#sasl),
[authentication](../../../../index.md#authentication)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005-2006, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/sasl/scram.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
[//000000001]: # (SASL::SCRAM - Simple Authentication and Security Layer (SASL))
[//000000002]: # (Generated from file 'scram.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (SASL::SCRAM(n) 0.1 tcllib "Simple Authentication and Security Layer (SASL)")
# NAME
SASL::SCRAM - Implementation of SASL SCRAM mechanism for Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [REFERENCES](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require SASL::SCRAM ?0.1?
# <a name='description'></a>DESCRIPTION
This package provides the SCRAM authentication mechanism for the Simple
Authentication and Security Layer (SASL).
Please read the documentation for package __sasl__ for details.
# <a name='section2'></a>REFERENCES
1. Newman, C. et al., "Salted Challenge Response Authentication Mechanism
(SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010,
([http://www.ieft.org/rfc/rfc5802.txt](http://www.ieft.org/rfc/rfc5802.txt))
# <a name='section3'></a>AUTHORS
Sergei Golovan
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *sasl* 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.
# <a name='keywords'></a>KEYWORDS
[SASL](../../../../index.md#sasl), [SCRAM](../../../../index.md#scram),
[authentication](../../../../index.md#authentication)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2013 Sergei Golovan <[email protected]>
|
Added embedded/md/tcllib/files/modules/sha1/sha1.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
[//000000001]: # (sha1 - SHA-x Message-Digest Algorithm)
[//000000002]: # (Generated from file 'sha1.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (sha1(n) 2.0.3 tcllib "SHA-x Message-Digest Algorithm")
# NAME
sha1 - SHA1 Message-Digest Algorithm
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require sha1 ?2.0.3?
[__::sha1::sha1__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#1)
[__::sha1::hmac__ *key* *string*](#2)
[__::sha1::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#3)
[__::sha1::SHA1Init__](#4)
[__::sha1::SHA1Update__ *token* *data*](#5)
[__::sha1::SHA1Final__ *token*](#6)
[__::sha1::HMACInit__ *key*](#7)
[__::sha1::HMACUpdate__ *token* *data*](#8)
[__::sha1::HMACFinal__ *token*](#9)
# <a name='description'></a>DESCRIPTION
This package provides an implementation in Tcl of the SHA1 message-digest
algorithm as specified by FIPS PUB 180-1 (1). This algorithm takes a message and
generates a 160-bit digest from the input. The SHA1 algorithm is related to the
MD4 algorithm (2) but has been strengthend against certain types of
cryptographic attack. SHA1 should be used in preference to MD4 or MD5 in new
applications.
This package also includes support for creating keyed message-digests using the
HMAC algorithm from RFC 2104 (3) with SHA1 as the message-digest.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::sha1::sha1__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]
The command takes a message and returns the SHA1 digest of this message as a
hexadecimal string. You may request the result as binary data by giving
*-bin*.
The data to be hashed can be specified either as a string argument to the
__sha1__ command, or as a filename or a pre-opened channel. If the
*-filename* argument is given then the file is opened, the data read and
hashed and the file is closed. If the *-channel* argument is given then data
is read from the channel until the end of file. The channel is not closed.
*NOTE* use of the channel or filename options results in the internal use of
__[vwait](../../../../index.md#vwait)__. To avoid nested event loops in Tk
or tclhttpd applications you should use the incremental programming API (see
below).
Only one of *-file*, *-channel* or *string* should be given.
If the *string* to hash can be mistaken for an option (leading dash "-"),
use the option __--__ before it to terminate option processing and force
interpretation as a string.
- <a name='2'></a>__::sha1::hmac__ *key* *string*
- <a name='3'></a>__::sha1::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]
Calculate an Hashed Message Authentication digest (HMAC) using the SHA1
digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA1
digest that includes a key. All options other than *-key* are as for the
__::sha1::sha1__ command.
If the *string* to hash can be mistaken for an option (leading dash "-"),
use the option __--__ before it to terminate option processing and force
interpretation as a string.
# <a name='section3'></a>PROGRAMMING INTERFACE
For the programmer, the SHA1 hash can be viewed as a bucket into which one pours
data. When you have finished, you extract a value that is derived from the data
that was poured into the bucket. The programming interface to the SHA1 hash
operates on a token (equivalent to the bucket). You call __SHA1Init__ to obtain
a token and then call __SHA1Update__ as many times as required to add data to
the hash. To release any resources and obtain the hash value, you then call
__SHA1Final__. An equivalent set of functions gives you a keyed digest (HMAC).
If you have __critcl__ and have built the __tcllibc__ package then the
implementation of the hashing function will be performed by compiled code.
Failing that if you have the __Trf__ package then this can be used otherwise
there is a pure-tcl equivalent. The programming interface remains the same in
all cases.
- <a name='4'></a>__::sha1::SHA1Init__
Begins a new SHA1 hash. Returns a token ID that must be used for the
remaining functions.
- <a name='5'></a>__::sha1::SHA1Update__ *token* *data*
Add data to the hash identified by token. Calling *SHA1Update $token "abcd"*
is equivalent to calling *SHA1Update $token "ab"* followed by *SHA1Update
$token "cb"*. See [EXAMPLES](#section4).
- <a name='6'></a>__::sha1::SHA1Final__ *token*
Returns the hash value and releases any resources held by this token. Once
this command completes the token will be invalid. The result is a binary
string of 20 bytes representing the 160 bit SHA1 digest value.
- <a name='7'></a>__::sha1::HMACInit__ *key*
This is equivalent to the __::sha1::SHA1Init__ command except that it
requires the key that will be included in the HMAC.
- <a name='8'></a>__::sha1::HMACUpdate__ *token* *data*
- <a name='9'></a>__::sha1::HMACFinal__ *token*
These commands are identical to the SHA1 equivalent commands.
# <a name='section4'></a>EXAMPLES
% sha1::sha1 "Tcl does SHA1"
285a6a91c45a9066bf39fcf24425796ef0b2a8bf
% sha1::hmac Sekret "Tcl does SHA1"
ae6251fa51b95b18cba2be95eb031d07475ff03c
% set tok [sha1::SHA1Init]
::sha1::1
% sha1::SHA1Update $tok "Tcl "
% sha1::SHA1Update $tok "does "
% sha1::SHA1Update $tok "SHA1"
% sha1::Hex [sha1::SHA1Final $tok]
285a6a91c45a9066bf39fcf24425796ef0b2a8bf
# <a name='section5'></a>REFERENCES
1. "Secure Hash Standard", National Institute of Standards and Technology,
U.S. Department Of Commerce, April 1995.
([http://www.itl.nist.gov/fipspubs/fip180-1.htm](http://www.itl.nist.gov/fipspubs/fip180-1.htm))
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997.
([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *sha1* 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.
# <a name='see-also'></a>SEE ALSO
[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd128](../ripemd/ripemd128.md),
[ripemd160](../ripemd/ripemd160.md)
# <a name='keywords'></a>KEYWORDS
[FIPS 180-1](../../../../index.md#fips_180_1),
[hashing](../../../../index.md#hashing),
[message-digest](../../../../index.md#message_digest), [rfc
2104](../../../../index.md#rfc_2104), [security](../../../../index.md#security),
[sha1](../../../../index.md#sha1)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/sha1/sha256.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
[//000000001]: # (sha256 - SHA-x Message-Digest Algorithm)
[//000000002]: # (Generated from file 'sha256.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (sha256(n) 1.0.3 tcllib "SHA-x Message-Digest Algorithm")
# NAME
sha256 - SHA256 Message-Digest Algorithm
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [PROGRAMMING INTERFACE](#section3)
- [EXAMPLES](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require sha256 ?1.0.3?
[__::sha2::sha256__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#1)
[__::sha2::sha224__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#2)
[__::sha2::hmac__ *key* *string*](#3)
[__::sha2::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]](#4)
[__::sha2::SHA256Init__](#5)
[__::sha2::SHA224Init__](#6)
[__::sha2::SHA256Update__ *token* *data*](#7)
[__::sha2::SHA256Final__ *token*](#8)
[__::sha2::SHA224Final__ *token*](#9)
[__::sha2::HMACInit__ *key*](#10)
[__::sha2::HMACUpdate__ *token* *data*](#11)
[__::sha2::HMACFinal__ *token*](#12)
# <a name='description'></a>DESCRIPTION
This package provides an implementation in Tcl of the SHA256 and SHA224
message-digest algorithms as specified by FIPS PUB 180-1 (1). These algorithms
take a message and generates a 256-bit (224-bit) digest from the input. The SHA2
algorithms are related to the SHA1 algorithm.
This package also includes support for creating keyed message-digests using the
HMAC algorithm from RFC 2104 (3) with SHA256 as the message-digest.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::sha2::sha256__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]
The command takes a message and returns the SHA256 digest of this message as
a hexadecimal string. You may request the result as binary data by giving
*-bin*.
The data to be hashed can be specified either as a string argument to the
__sha256__ command, or as a filename or a pre-opened channel. If the
*-filename* argument is given then the file is opened, the data read and
hashed and the file is closed. If the *-channel* argument is given then data
is read from the channel until the end of file. The channel is not closed.
*NOTE* use of the channel or filename options results in the internal use of
__[vwait](../../../../index.md#vwait)__. To avoid nested event loops in Tk
or tclhttpd applications you should use the incremental programming API (see
below).
Only one of *-file*, *-channel* or *string* should be given.
If the *string* to hash can be mistaken for an option (leading dash "-"),
use the option __--__ before it to terminate option processing and force
interpretation as a string.
- <a name='2'></a>__::sha2::sha224__ ?__-hex|-bin__? [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]
Like __::sha2::sha256__, except that the SHA224 digest is returned.
- <a name='3'></a>__::sha2::hmac__ *key* *string*
- <a name='4'></a>__::sha2::hmac__ ?__-hex|-bin__? __-key key__ [ __-channel channel__ | __-file filename__ | ?__--__? *string* ]
Calculate an Hashed Message Authentication digest (HMAC) using the SHA256
digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA256
digest that includes a key. All options other than *-key* are as for the
__::sha2::sha256__ command.
If the *string* to hash can be mistaken for an option (leading dash "-"),
use the option __--__ before it to terminate option processing and force
interpretation as a string.
# <a name='section3'></a>PROGRAMMING INTERFACE
For the programmer, the SHA256 hash can be viewed as a bucket into which one
pours data. When you have finished, you extract a value that is derived from the
data that was poured into the bucket. The programming interface to the SHA256
hash operates on a token (equivalent to the bucket). You call __SHA256Init__ to
obtain a token and then call __SHA256Update__ as many times as required to add
data to the hash. To release any resources and obtain the hash value, you then
call __SHA256Final__. An equivalent set of functions gives you a keyed digest
(HMAC).
If you have __critcl__ and have built the __tcllibc__ package then the
implementation of the hashing function will be performed by compiled code.
Failing that there is a pure-tcl equivalent. The programming interface remains
the same in all cases.
- <a name='5'></a>__::sha2::SHA256Init__
- <a name='6'></a>__::sha2::SHA224Init__
Begins a new SHA256/SHA224 hash. Returns a token ID that must be used for
the remaining functions.
- <a name='7'></a>__::sha2::SHA256Update__ *token* *data*
Add data to the hash identified by token. Calling *SHA256Update $token
"abcd"* is equivalent to calling *SHA256Update $token "ab"* followed by
*SHA256Update $token "cb"*. See [EXAMPLES](#section4). Note that this
command is used for both SHA256 and SHA224. Only the initialization and
finalization commands of both hashes differ.
- <a name='8'></a>__::sha2::SHA256Final__ *token*
- <a name='9'></a>__::sha2::SHA224Final__ *token*
Returns the hash value and releases any resources held by this token. Once
this command completes the token will be invalid. The result is a binary
string of 32/28 bytes representing the 256/224 bit SHA256 / SHA224 digest
value.
- <a name='10'></a>__::sha2::HMACInit__ *key*
This is equivalent to the __::sha2::SHA256Init__ command except that it
requires the key that will be included in the HMAC.
- <a name='11'></a>__::sha2::HMACUpdate__ *token* *data*
- <a name='12'></a>__::sha2::HMACFinal__ *token*
These commands are identical to the SHA256 equivalent commands.
# <a name='section4'></a>EXAMPLES
% sha2::sha256 "Tcl does SHA256"
0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
% sha2::hmac Sekret "Tcl does SHA256"
4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0
% set tok [sha2::SHA256Init]
::sha2::1
% sha2::SHA256Update $tok "Tcl "
% sha2::SHA256Update $tok "does "
% sha2::SHA256Update $tok "SHA256"
% sha2::Hex [sha2::SHA256Final $tok]
0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
# <a name='section5'></a>REFERENCES
1. "Secure Hash Standard", National Institute of Standards and Technology,
U.S. Department Of Commerce, April 1995.
([http://www.itl.nist.gov/fipspubs/fip180-1.htm](http://www.itl.nist.gov/fipspubs/fip180-1.htm))
1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992.
([http://www.rfc-editor.org/rfc/rfc1320.txt](http://www.rfc-editor.org/rfc/rfc1320.txt))
1. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997.
([http://www.rfc-editor.org/rfc/rfc2104.txt](http://www.rfc-editor.org/rfc/rfc2104.txt))
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *sha1* 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.
# <a name='see-also'></a>SEE ALSO
[md4](../md4/md4.md), [md5](../md5/md5.md), [ripemd128](../ripemd/ripemd128.md),
[ripemd160](../ripemd/ripemd160.md), [sha1](sha1.md)
# <a name='keywords'></a>KEYWORDS
[FIPS 180-1](../../../../index.md#fips_180_1),
[hashing](../../../../index.md#hashing),
[message-digest](../../../../index.md#message_digest), [rfc
2104](../../../../index.md#rfc_2104), [security](../../../../index.md#security),
[sha256](../../../../index.md#sha256)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008, Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/simulation/annealing.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
[//000000001]: # (simulation::annealing - Tcl Simulation Tools)
[//000000002]: # (Generated from file 'annealing.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (simulation::annealing(n) 0.2 tcllib "Tcl Simulation Tools")
# NAME
simulation::annealing - Simulated annealing
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [TIPS](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require simulation::annealing 0.2
[__::simulation::annealing::getOption__ *keyword*](#1)
[__::simulation::annealing::hasOption__ *keyword*](#2)
[__::simulation::annealing::setOption__ *keyword* *value*](#3)
[__::simulation::annealing::findMinimum__ *args*](#4)
[__::simulation::annealing::findCombinatorialMinimum__ *args*](#5)
# <a name='description'></a>DESCRIPTION
The technique of *simulated annealing* provides methods to estimate the global
optimum of a function. It is described in some detail on the Wiki
[http://wiki.tcl.tk/...](http://wiki.tcl.tk/...). The idea is simple:
- randomly select points within a given search space
- evaluate the function to be optimised for each of these points and select
the point that has the lowest (or highest) function value or - sometimes -
accept a point that has a less optimal value. The chance by which such a
non-optimal point is accepted diminishes over time.
- Accepting less optimal points means the method does not necessarily get
stuck in a local optimum and theoretically it is capable of finding the
global optimum within the search space.
The method resembles the cooling of material, hence the name.
The package *simulation::annealing* offers the command *findMinimum*:
puts [::simulation::annealing::findMinimum -trials 300 -parameters {x -5.0 5.0 y -5.0 5.0} -function {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
prints the estimated minimum value of the function f(x,y) =
*x**2+y**2+sin(10*x)+4*cos(20*y)* and the values of x and y where the minimum
was attained:
result -4.9112922923 x -0.181647676593 y 0.155743646974
# <a name='section2'></a>PROCEDURES
The package defines the following auxiliary procedures:
- <a name='1'></a>__::simulation::annealing::getOption__ *keyword*
Get the value of an option given as part of the *findMinimum* command.
* string *keyword*
Given keyword (without leading minus)
- <a name='2'></a>__::simulation::annealing::hasOption__ *keyword*
Returns 1 if the option is available, 0 if not.
* string *keyword*
Given keyword (without leading minus)
- <a name='3'></a>__::simulation::annealing::setOption__ *keyword* *value*
Set the value of the given option.
* string *keyword*
Given keyword (without leading minus)
* string *value*
(New) value for the option
The main procedures are *findMinimum* and *findCombinatorialMinimum*:
- <a name='4'></a>__::simulation::annealing::findMinimum__ *args*
Find the minimum of a function using simulated annealing. The function and
the method's parameters is given via a list of keyword-value pairs.
* int *n*
List of keyword-value pairs, all of which are available during the
execution via the *getOption* command.
- <a name='5'></a>__::simulation::annealing::findCombinatorialMinimum__ *args*
Find the minimum of a function of discrete variables using simulated
annealing. The function and the method's parameters is given via a list of
keyword-value pairs.
* int *n*
List of keyword-value pairs, all of which are available during the
execution via the *getOption* command.
The *findMinimum* command predefines the following options:
- *-parameters list*: triples defining parameters and ranges
- *-function expr*: expression defining the function
- *-code body*: body of code to define the function (takes precedence over
*-function*). The code should set the variable "result"
- *-init code*: code to be run at start up *-final code*: code to be run at
the end *-trials n*: number of trials before reducing the temperature
*-reduce factor*: reduce the temperature by this factor (between 0 and 1)
*-initial-temp t*: initial temperature *-scale s*: scale of the function
(order of magnitude of the values) *-estimate-scale y/n*: estimate the scale
(only if *-scale* is not present) *-verbose y/n*: print detailed information
on progress to the report file (1) or not (0) *-reportfile file*: opened
file to print to (defaults to stdout)
Any other options can be used via the getOption procedure in the body. The
*findCombinatorialMinimum* command predefines the following options:
- *-number-params n*: number of binary parameters (the solution space consists
of lists of 1s and 0s). This is a required option.
- *-initial-values*: list of 1s and 0s constituting the start of the search.
The other predefined options are identical to those of *findMinimum*.
# <a name='section3'></a>TIPS
The procedure *findMinimum* works by constructing a temporary procedure that
does the actual work. It loops until the point representing the estimated
optimum does not change anymore within the given number of trials. As the
temperature gets lower and lower the chance of accepting a point with a higher
value becomes lower too, so the procedure will in practice terminate.
It is possible to optimise over a non-rectangular region, but some care must be
taken:
- If the point is outside the region of interest, you can specify a very high
value.
- This does mean that the automatic determination of a scale factor is out of
the question - the high function values that force the point inside the
region would distort the estimation.
Here is an example of finding an optimum inside a circle:
puts [::simulation::annealing::findMinimum -trials 3000 -reduce 0.98 -parameters {x -5.0 5.0 y -5.0 5.0} -code {
if { hypot($x-5.0,$y-5.0) < 4.0 } {
set result [expr {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
} else {
set result 1.0e100
}
}]
The method is theoretically capable of determining the global optimum, but often
you need to use a large number of trials and a slow reduction of temperature to
get reliable and repeatable estimates.
You can use the *-final* option to use a deterministic optimization method, once
you are sure you are near the required optimum.
The *findCombinatorialMinimum* procedure is suited for situations where the
parameters have the values 0 or 1 (and there can be many of them). Here is an
example:
- We have a function that attains an absolute minimum if the first ten numbers
are 1 and the rest is 0:
proc cost {params} {
set cost 0
foreach p [lrange $params 0 9] {
if { $p == 0 } {
incr cost
}
}
foreach p [lrange $params 10 end] {
if { $p == 1 } {
incr cost
}
}
return $cost
}
- We want to find the solution that gives this minimum for various lengths of
the solution vector *params*:
foreach n {100 1000 10000} {
break
puts "Problem size: $n"
puts [::simulation::annealing::findCombinatorialMinimum -trials 300 -verbose 0 -number-params $n -code {set result [cost $params]}]
}
- As the vector grows, the computation time increases, but the procedure will
stop if some kind of equilibrium is reached. To achieve a useful solution
you may want to try different values of the trials parameter for instance.
Also ensure that the function to be minimized depends on all or most
parameters - see the source code for a counter example and run that.
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math),
[optimization](../../../../index.md#optimization), [simulated
annealing](../../../../index.md#simulated_annealing)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/simulation/montecarlo.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
[//000000001]: # (simulation::montecarlo - Tcl Simulation Tools)
[//000000002]: # (Generated from file 'montecarlo.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (simulation::montecarlo(n) 0.1 tcllib "Tcl Simulation Tools")
# NAME
simulation::montecarlo - Monte Carlo simulations
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [TIPS](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require simulation::montecarlo 0.1
package require simulation::random
package require math::statistics
[__::simulation::montecarlo::getOption__ *keyword*](#1)
[__::simulation::montecarlo::hasOption__ *keyword*](#2)
[__::simulation::montecarlo::setOption__ *keyword* *value*](#3)
[__::simulation::montecarlo::setTrialResult__ *values*](#4)
[__::simulation::montecarlo::setExpResult__ *values*](#5)
[__::simulation::montecarlo::getTrialResults__](#6)
[__::simulation::montecarlo::getExpResult__](#7)
[__::simulation::montecarlo::transposeData__ *values*](#8)
[__::simulation::montecarlo::integral2D__ *...*](#9)
[__::simulation::montecarlo::singleExperiment__ *args*](#10)
# <a name='description'></a>DESCRIPTION
The technique of *Monte Carlo simulations* is basically simple:
- generate random values for one or more parameters.
- evaluate the model of some system you are interested in and record the
interesting results for each realisation of these parameters.
- after a suitable number of such trials, deduce an overall characteristic of
the model.
You can think of a model of a network of computers, an ecosystem of some kind or
in fact anything that can be quantitatively described and has some stochastic
element in it.
The package *simulation::montecarlo* offers a basic framework for such a
modelling technique:
#
# MC experiments:
# Determine the mean and median of a set of points and compare them
#
::simulation::montecarlo::singleExperiment -init {
package require math::statistics
set prng [::simulation::random::prng_Normal 0.0 1.0]
} -loop {
set numbers {}
for { set i 0 } { $i < [getOption samples] } { incr i } {
lappend numbers [$prng]
}
set mean [::math::statistics::mean $numbers]
set median [::math::statistics::median $numbers] ;# ? Exists?
setTrialResult [list $mean $median]
} -final {
set result [getTrialResults]
set means {}
set medians {}
foreach r $result {
foreach {m M} $r break
lappend means $m
lappend medians $M
}
puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]"
} -trials 100 -samples 10 -verbose 1 -columns {Mean Median}
This example attemps to find out how well the median value and the mean value of
a random set of numbers correlate. Sometimes a median value is a more robust
characteristic than a mean value - especially if you have a statistical
distribution with "fat" tails.
# <a name='section2'></a>PROCEDURES
The package defines the following auxiliary procedures:
- <a name='1'></a>__::simulation::montecarlo::getOption__ *keyword*
Get the value of an option given as part of the *singeExperiment* command.
* string *keyword*
Given keyword (without leading minus)
- <a name='2'></a>__::simulation::montecarlo::hasOption__ *keyword*
Returns 1 if the option is available, 0 if not.
* string *keyword*
Given keyword (without leading minus)
- <a name='3'></a>__::simulation::montecarlo::setOption__ *keyword* *value*
Set the value of the given option.
* string *keyword*
Given keyword (without leading minus)
* string *value*
(New) value for the option
- <a name='4'></a>__::simulation::montecarlo::setTrialResult__ *values*
Store the results of the trial for later analysis
* list *values*
List of values to be stored
- <a name='5'></a>__::simulation::montecarlo::setExpResult__ *values*
Set the results of the entire experiment (typically used in the final
phase).
* list *values*
List of values to be stored
- <a name='6'></a>__::simulation::montecarlo::getTrialResults__
Get the results of all individual trials for analysis (typically used in the
final phase or after completion of the command).
- <a name='7'></a>__::simulation::montecarlo::getExpResult__
Get the results of the entire experiment (typically used in the final phase
or even after completion of the *singleExperiment* command).
- <a name='8'></a>__::simulation::montecarlo::transposeData__ *values*
Interchange columns and rows of a list of lists and return the result.
* list *values*
List of lists of values
There are two main procedures: *integral2D* and *singleExperiment*.
- <a name='9'></a>__::simulation::montecarlo::integral2D__ *...*
Integrate a function over a two-dimensional region using a Monte Carlo
approach.
Arguments PM
- <a name='10'></a>__::simulation::montecarlo::singleExperiment__ *args*
Iterate code over a number of trials and store the results. The iteration is
gouverned by parameters given via a list of keyword-value pairs.
* int *n*
List of keyword-value pairs, all of which are available during the
execution via the *getOption* command.
The *singleExperiment* command predefines the following options:
- *-init code*: code to be run at start up
- *-loop body*: body of code that defines the computation to be run time and
again. The code should use *setTrialResult* to store the results of each
trial (typically a list of numbers, but the interpretation is up to the
implementation). Note: Required keyword.
- *-final code*: code to be run at the end
- *-trials n*: number of trials in the experiment (required)
- *-reportfile file*: opened file to send the output to (default: stdout)
- *-verbose*: write the intermediate results (1) or not (0) (default: 0)
- *-analysis proc*: either "none" (no automatic analysis), standard (basic
statistics of the trial results and a correlation matrix) or the name of a
procedure that will take care of the analysis.
- *-columns list*: list of column names, useful for verbose output and the
analysis
Any other options can be used via the getOption procedure in the body.
# <a name='section3'></a>TIPS
The procedure *singleExperiment* works by constructing a temporary procedure
that does the actual work. It loops for the given number of trials.
As it constructs a temporary procedure, local variables defined at the start
continue to exist in the loop.
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math), [montecarlo
simulation](../../../../index.md#montecarlo_simulation), [stochastic
modelling](../../../../index.md#stochastic_modelling)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/simulation/simulation_random.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
[//000000001]: # (simulation::random - Tcl Simulation Tools)
[//000000002]: # (Generated from file 'simulation_random.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (simulation::random(n) 0.1 tcllib "Tcl Simulation Tools")
# NAME
simulation::random - Pseudo-random number generators
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [PROCEDURES](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl ?8.4?
package require simulation::random 0.1
[__::simulation::random::prng_Bernoulli__ *p*](#1)
[__::simulation::random::prng_Discrete__ *n*](#2)
[__::simulation::random::prng_Poisson__ *lambda*](#3)
[__::simulation::random::prng_Uniform__ *min* *max*](#4)
[__::simulation::random::prng_Exponential__ *min* *mean*](#5)
[__::simulation::random::prng_Normal__ *mean* *stdev*](#6)
[__::simulation::random::prng_Pareto__ *min* *steep*](#7)
[__::simulation::random::prng_Gumbel__ *min* *f*](#8)
[__::simulation::random::prng_chiSquared__ *df*](#9)
[__::simulation::random::prng_Disk__ *rad*](#10)
[__::simulation::random::prng_Sphere__ *rad*](#11)
[__::simulation::random::prng_Ball__ *rad*](#12)
[__::simulation::random::prng_Rectangle__ *length* *width*](#13)
[__::simulation::random::prng_Block__ *length* *width* *depth*](#14)
# <a name='description'></a>DESCRIPTION
This package consists of commands to generate pseudo-random number generators.
These new commands deliver
- numbers that are distributed normally, uniformly, according to a Pareto or
Gumbel distribution and so on
- coordinates of points uniformly spread inside a sphere or a rectangle
For example:
set p [::simulation::random::prng_Normal -1.0 10.0]
produces a new command (whose name is stored in the variable "p") that generates
normally distributed numbers with a mean of -1.0 and a standard deviation of
10.0.
# <a name='section2'></a>PROCEDURES
The package defines the following public procedures for *discrete*
distributions:
- <a name='1'></a>__::simulation::random::prng_Bernoulli__ *p*
Create a command (PRNG) that generates numbers with a Bernoulli
distribution: the value is either 1 or 0, with a chance p to be 1
* float *p*
Chance the outcome is 1
- <a name='2'></a>__::simulation::random::prng_Discrete__ *n*
Create a command (PRNG) that generates numbers 0 to n-1 with equal
probability.
* int *n*
Number of different values (ranging from 0 to n-1)
- <a name='3'></a>__::simulation::random::prng_Poisson__ *lambda*
Create a command (PRNG) that generates numbers according to the Poisson
distribution.
* float *lambda*
Mean number per time interval
The package defines the following public procedures for *continuous*
distributions:
- <a name='4'></a>__::simulation::random::prng_Uniform__ *min* *max*
Create a command (PRNG) that generates uniformly distributed numbers between
"min" and "max".
* float *min*
Minimum number that will be generated
* float *max*
Maximum number that will be generated
- <a name='5'></a>__::simulation::random::prng_Exponential__ *min* *mean*
Create a command (PRNG) that generates exponentially distributed numbers
with a given minimum value and a given mean value.
* float *min*
Minimum number that will be generated
* float *mean*
Mean value for the numbers
- <a name='6'></a>__::simulation::random::prng_Normal__ *mean* *stdev*
Create a command (PRNG) that generates normally distributed numbers with a
given mean value and a given standard deviation.
* float *mean*
Mean value for the numbers
* float *stdev*
Standard deviation
- <a name='7'></a>__::simulation::random::prng_Pareto__ *min* *steep*
Create a command (PRNG) that generates numbers distributed according to
Pareto with a given minimum value and a given distribution steepness.
* float *min*
Minimum number that will be generated
* float *steep*
Steepness of the distribution
- <a name='8'></a>__::simulation::random::prng_Gumbel__ *min* *f*
Create a command (PRNG) that generates numbers distributed according to
Gumbel with a given minimum value and a given scale factor. The probability
density function is:
P(v) = exp( -exp(f*(v-min)))
* float *min*
Minimum number that will be generated
* float *f*
Scale factor for the values
- <a name='9'></a>__::simulation::random::prng_chiSquared__ *df*
Create a command (PRNG) that generates numbers distributed according to the
chi-squared distribution with df degrees of freedom. The mean is 0 and the
standard deviation is 1.
* float *df*
Degrees of freedom
The package defines the following public procedures for random point sets:
- <a name='10'></a>__::simulation::random::prng_Disk__ *rad*
Create a command (PRNG) that generates (x,y)-coordinates for points
uniformly spread over a disk of given radius.
* float *rad*
Radius of the disk
- <a name='11'></a>__::simulation::random::prng_Sphere__ *rad*
Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread over the surface of a sphere of given radius.
* float *rad*
Radius of the disk
- <a name='12'></a>__::simulation::random::prng_Ball__ *rad*
Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread within a ball of given radius.
* float *rad*
Radius of the ball
- <a name='13'></a>__::simulation::random::prng_Rectangle__ *length* *width*
Create a command (PRNG) that generates (x,y)-coordinates for points
uniformly spread over a rectangle.
* float *length*
Length of the rectangle (x-direction)
* float *width*
Width of the rectangle (y-direction)
- <a name='14'></a>__::simulation::random::prng_Block__ *length* *width* *depth*
Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread over a block
* float *length*
Length of the block (x-direction)
* float *width*
Width of the block (y-direction)
* float *depth*
Depth of the block (z-direction)
# <a name='keywords'></a>KEYWORDS
[math](../../../../index.md#math), [random
numbers](../../../../index.md#random_numbers),
[simulation](../../../../index.md#simulation), [statistical
distribution](../../../../index.md#statistical_distribution)
# <a name='category'></a>CATEGORY
Mathematics
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Arjen Markus <[email protected]>
|
Added embedded/md/tcllib/files/modules/smtpd/smtpd.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
|
[//000000001]: # (smtpd - Tcl SMTP Server Package)
[//000000002]: # (Generated from file 'smtpd.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (smtpd(n) 1.5 tcllib "Tcl SMTP Server Package")
# NAME
smtpd - Tcl SMTP server implementation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [SECURITY](#section2)
- [TLS Security Considerations](#section3)
- [COMMANDS](#section4)
- [CALLBACKS](#section5)
- [VARIABLES](#section6)
- [AUTHOR](#section7)
- [LICENSE](#section8)
- [Bugs, Ideas, Feedback](#section9)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require smtpd ?1.5?
[__::smtpd::start__ ?*myaddr*? ?*port*?](#1)
[__::smtpd::stop__](#2)
[__::smptd::configure__ ?*option* *value*? ?*option* *value* *...*?](#3)
[__::smtpd::cget__ ?*option*?](#4)
# <a name='description'></a>DESCRIPTION
The __smtpd__ package provides a simple Tcl-only server library for the Simple
Mail Transfer Protocol as described in RFC 821
([http://www.rfc-editor.org/rfc/rfc821.txt](http://www.rfc-editor.org/rfc/rfc821.txt))
and RFC 2821
([http://www.rfc-editor.org/rfc/rfc2821.txt](http://www.rfc-editor.org/rfc/rfc2821.txt)).
By default the server will bind to the default network address and the standard
SMTP port (25).
This package was designed to permit testing of Mail User Agent code from a
developers workstation. *It does not attempt to deliver mail to your mailbox.*
Instead users of this package are expected to write a procedure that will be
called when mail arrives. Once this procedure returns, the server has nothing
further to do with the mail.
# <a name='section2'></a>SECURITY
On Unix platforms binding to the SMTP port requires root privileges. I would not
recommend running any script-based server as root unless there is some method
for dropping root privileges immediately after the socket is bound. Under
Windows platforms, it is not necessary to have root or administrator privileges
to bind low numbered sockets. However, security on these platforms is weak
anyway.
In short, this code should probably not be used as a permanently running Mail
Transfer Agent on an Internet connected server, even though we are careful not
to evaluate remote user input. There are many other well tested and security
audited programs that can be used as mail servers for internet connected hosts.
# <a name='section3'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section4'></a>COMMANDS
- <a name='1'></a>__::smtpd::start__ ?*myaddr*? ?*port*?
Start the service listening on *port* or the default port 25. If *myaddr* is
given as a domain-style name or numerical dotted-quad IP address then the
server socket will be bound to that network interface. By default the server
is bound to all network interfaces. For example:
set sock [::smtpd::start [info hostname] 0]
will bind to the hosts internet interface on the first available port.
At present the package only supports a single instance of a SMTP server.
This could be changed if required at the cost of making the package a little
more complicated to read. If there is a good reason for running multiple
SMTP services then it will only be necessary to fix the __options__ array
and the __::smtpd::stopped__ variable usage.
As the server code uses __fileevent__(n) handlers to process the input on
sockets you will need to run the event loop. This means either you should be
running from within __wish__(1) or you should
__[vwait](../../../../index.md#vwait)__(n) on the __::smtpd::stopped__
variable which is set when the server is stopped.
- <a name='2'></a>__::smtpd::stop__
Halt the server and release the listening socket. If the server has not been
started then this command does nothing. The __::smtpd::stopped__ variable is
set for use with __[vwait](../../../../index.md#vwait)__(n).
It should be noted that stopping the server does not disconnect any
currently active sessions as these are operating over an independent
channel. Only explicitly tracking and closing these sessions, or exiting the
server process will close down all the running sessions. This is similar to
the usual unix daemon practice where the server performs a __fork__(2) and
the client session continues on the child process.
- <a name='3'></a>__::smptd::configure__ ?*option* *value*? ?*option* *value* *...*?
Set configuration options for the SMTP server. Most values are the name of a
callback procedure to be called at various points in the SMTP protocol. See
the [CALLBACKS](#section5) section for details of the procedures.
* __-banner__ *text*
Text of a custom banner message. The default banner is "tcllib smtpd
1.5". Note that changing the banner does not affect the bracketing text
in the full greeting, printing status 220, server-address, and
timestamp.
* __-validate_host__ *proc*
Callback to authenticate new connections based on the ip-address of the
client.
* __-validate_sender__ *proc*
Callback to authenticate new connections based on the senders email
address.
* __-validate_recipient__ *proc*
Callback to validate and authorize a recipient email address
* __-deliverMIME__ *proc*
Callback used to deliver mail as a mime token created by the tcllib
__[mime](../mime/mime.md)__ package.
* __-deliver__ *proc*
Callback used to deliver email. This option has no effect if the
__-deliverMIME__ option has been set.
- <a name='4'></a>__::smtpd::cget__ ?*option*?
If no *option* is specified the command will return a list of all options
and their current values. If an option is specified it will return the value
of that option.
# <a name='section5'></a>CALLBACKS
- __validate_host__ callback
This procedure is called with the clients ip address as soon as a connection
request has been accepted and before any protocol commands are processed. If
you wish to deny access to a specific host then an error should be returned
by this callback. For example:
proc validate_host {ipnum} {
if {[string match "192.168.1.*" $ipnum]} {
error "go away!"
}
}
If access is denied the client will receive a standard message that includes
the text of your error, such as:
550 Access denied: I hate you.
As per the SMTP protocol, the connection is not closed but we wait for the
client to send a QUIT command. Any other commands cause a __503 Bad
Sequence__ error.
- __validate_sender__ callback
The validate_sender callback is called with the senders mail address during
processing of a MAIL command to allow you to accept or reject mail based
upon the declared sender. To reject mail you should throw an error. For
example, to reject mail from user "denied":
proc validate_sender {address} {
eval array set addr [mime::parseaddress $address]
if {[string match "denied" $addr(local)]} {
error "mailbox $addr(local) denied"
}
return
}
The content of any error message will not be passed back to the client.
- __validate_recipient__ callback
The validate_recipient callback is similar to the validate_sender callback
and permits you to verify a local mailbox and accept mail for a local user
address during RCPT command handling. To reject mail, throw an error as
above. The error message is ignored.
- __deliverMIME__ callback
The deliverMIME callback is called once a mail message has been successfully
passed to the server. A mime token is constructed from the sender,
recipients and data and the users procedure it called with this single
argument. When the call returns, the mime token is cleaned up so if the user
wishes to preserve the data she must make a copy.
proc deliverMIME {token} {
set sender [lindex [mime::getheader $token From] 0]
set recipients [lindex [mime::getheader $token To] 0]
set mail "From $sender [clock format [clock seconds]]"
append mail "\n" [mime::buildmessage $token]
puts $mail
}
- __deliver__ callback
The deliver callback is called once a mail message has been successfully
passed to the server and there is no -deliverMIME option set. The procedure
is called with the sender, a list of recipients and the text of the mail as
a list of lines. For example:
proc deliver {sender recipients data} {
set mail "From $sender [clock format [clock seconds]]"
append mail "\n" [join $data "\n"]
puts "$mail"
}
Note that the DATA command will return an error if no sender or recipient
has yet been defined.
# <a name='section6'></a>VARIABLES
- __::smtpd::stopped__
This variable is set to __true__ during the __::smtpd::stop__ command to
permit the use of the __[vwait](../../../../index.md#vwait)__(n) command.
# <a name='section7'></a>AUTHOR
Written by Pat Thoyts
[mailto:[email protected]](mailto:[email protected]).
# <a name='section8'></a>LICENSE
This software is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the file "license.terms" for more details.
# <a name='section9'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *smtpd* 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.
# <a name='keywords'></a>KEYWORDS
[rfc 2821](../../../../index.md#rfc_2821), [rfc
821](../../../../index.md#rfc_821), [services](../../../../index.md#services),
[smtp](../../../../index.md#smtp), [smtpd](../../../../index.md#smtpd),
[socket](../../../../index.md#socket), [vwait](../../../../index.md#vwait)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/snit/snit.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
|
[//000000001]: # (snit - Snit's Not Incr Tcl, OO system)
[//000000002]: # (Generated from file 'snit.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (snit(n) 2.3.2 tcllib "Snit's Not Incr Tcl, OO system")
# NAME
snit - Snit's Not Incr Tcl
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [SNIT VERSIONS](#section2)
- [REFERENCE](#section3)
- [Type and Widget Definitions](#subsection1)
- [The Type Command](#subsection2)
- [Standard Type Methods](#subsection3)
- [The Instance Command](#subsection4)
- [Standard Instance Methods](#subsection5)
- [Commands for use in Object Code](#subsection6)
- [Components and Delegation](#subsection7)
- [Type Components and Delegation](#subsection8)
- [The Tk Option Database](#subsection9)
- [Macros and Meta-programming](#subsection10)
- [Validation Types](#subsection11)
- [Defining Validation Types](#subsection12)
- [CAVEATS](#section4)
- [KNOWN BUGS](#section5)
- [HISTORY](#section6)
- [CREDITS](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit ?2.3.2?
[__snit::type__ *name* *definition*](#1)
[__typevariable__ *name* ?__-array__? ?*value*?](#2)
[__typemethod__ *name* *arglist* *body*](#3)
[__typeconstructor__ *body*](#4)
[__variable__ *name* ?__-array__? ?*value*?](#5)
[__[method](../../../../index.md#method)__ *name* *arglist* *body*](#6)
[__option__ *namespec* ?*defaultValue*?](#7)
[__option__ *namespec* ?*options...*?](#8)
[__constructor__ *arglist* *body*](#9)
[__destructor__ *body*](#10)
[__[proc](../../../../index.md#proc)__ *name* *args* *body*](#11)
[__delegate__ __method__ *name* __to__ *comp* ?__as__ *target*?](#12)
[__delegate__ __method__ *name* ?__to__ *comp*? __using__ *pattern*](#13)
[__delegate__ __method__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?](#14)
[__delegate__ __option__ *namespec* __to__ *comp*](#15)
[__delegate__ __option__ *namespec* __to__ *comp* __as__ *target*](#16)
[__delegate__ __option__ __*__ __to__ *comp*](#17)
[__delegate__ __option__ __*__ __to__ *comp* __except__ *exceptions*](#18)
[__component__ *comp* ?__-public__ *method*? ?__-inherit__ *flag*?](#19)
[__delegate__ __typemethod__ *name* __to__ *comp* ?__as__ *target*?](#20)
[__delegate__ __typemethod__ *name* ?__to__ *comp*? __using__ *pattern*](#21)
[__delegate__ __typemethod__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?](#22)
[__typecomponent__ *comp* ?__-public__ *typemethod*? ?__-inherit__ *flag*?](#23)
[__pragma__ ?*options...*?](#24)
[__expose__ *comp*](#25)
[__expose__ *comp* __as__ *method*](#26)
[__onconfigure__ *name* *arglist* *body*](#27)
[__oncget__ *name* *body*](#28)
[__snit::widget__ *name* *definition*](#29)
[__widgetclass__ *name*](#30)
[__hulltype__ *type*](#31)
[__snit::widgetadaptor__ *name* *definition*](#32)
[__snit::typemethod__ *type* *name* *arglist* *body*](#33)
[__snit::method__ *type* *name* *arglist* *body*](#34)
[__snit::macro__ *name* *arglist* *body*](#35)
[__snit::compile__ *which* *type* *body*](#36)
[__$type__ *typemethod* *args*...](#37)
[__$type__ __create__ *name* ?*option* *value* ...?](#38)
[__$type__ __info typevars__ ?*pattern*?](#39)
[__$type__ __info typemethods__ ?*pattern*?](#40)
[__$type__ __info args__ *method*](#41)
[__$type__ __info body__ *method*](#42)
[__$type__ __info default__ *method* *aname* *varname*](#43)
[__$type__ __info instances__ ?*pattern*?](#44)
[__$type__ __destroy__](#45)
[__$object__ *method* *args...*](#46)
[__$object__ __configure__ ?*option*? ?*value*? ...](#47)
[__$object__ __configurelist__ *optionlist*](#48)
[__$object__ __cget__ *option*](#49)
[__$object__ __destroy__](#50)
[__$object__ __info type__](#51)
[__$object__ __info vars__ ?*pattern*?](#52)
[__$object__ __info typevars__ ?*pattern*?](#53)
[__$object__ __info typemethods__ ?*pattern*?](#54)
[__$object__ __info options__ ?*pattern*?](#55)
[__$object__ __info methods__ ?*pattern*?](#56)
[__$object__ __info args__ *method*](#57)
[__$object__ __info body__ *method*](#58)
[__$object__ __info default__ *method* *aname* *varname*](#59)
[__mymethod__ *name* ?*args...*?](#60)
[__mytypemethod__ *name* ?*args...*?](#61)
[__myproc__ *name* ?*args...*?](#62)
[__myvar__ *name*](#63)
[__mytypevar__ *name*](#64)
[__from__ *argvName* *option* ?*defvalue*?](#65)
[__install__ *compName* __using__ *objType* *objName* *args...*](#66)
[__installhull__ __using__ *widgetType* *args...*](#67)
[__installhull__ *name*](#68)
[__variable__ *name*](#69)
[__typevariable__ *name*](#70)
[__varname__ *name*](#71)
[__typevarname__ *name*](#72)
[__codename__ *name*](#73)
[__snit::boolean__ __validate__ ?*value*?](#74)
[__snit::boolean__ *name*](#75)
[__snit::double__ __validate__ ?*value*?](#76)
[__snit::double__ *name* ?*option* *value*...?](#77)
[__snit::enum__ __validate__ ?*value*?](#78)
[__snit::enum__ *name* ?*option* *value*...?](#79)
[__snit::fpixels__ __validate__ ?*value*?](#80)
[__snit::fpixels__ *name* ?*option* *value*...?](#81)
[__snit::integer__ __validate__ ?*value*?](#82)
[__snit::integer__ *name* ?*option* *value*...?](#83)
[__snit::listtype__ __validate__ ?*value*?](#84)
[__snit::listtype__ *name* ?*option* *value*...?](#85)
[__snit::pixels__ __validate__ ?*value*?](#86)
[__snit::pixels__ *name* ?*option* *value*...?](#87)
[__snit::stringtype__ __validate__ ?*value*?](#88)
[__snit::stringtype__ *name* ?*option* *value*...?](#89)
[__snit::window__ __validate__ ?*value*?](#90)
[__snit::window__ *name*](#91)
# <a name='description'></a>DESCRIPTION
Snit is a pure Tcl object and megawidget system. It's unique among Tcl object
systems in that it's based not on inheritance but on delegation. Object systems
based on inheritance only allow you to inherit from classes defined using the
same system, which is limiting. In Tcl, an object is anything that acts like an
object; it shouldn't matter how the object was implemented. Snit is intended to
help you build applications out of the materials at hand; thus, Snit is designed
to be able to incorporate and build on any object, whether it's a hand-coded
object, a __[Tk](../../../../index.md#tk)__ widget, an __[Incr
Tcl](../../../../index.md#incr_tcl)__ object, a
__[BWidget](../../../../index.md#bwidget)__ or almost anything else.
This man page is intended to be a reference only; see the accompanying
__[snitfaq](snitfaq.md)__ for a gentler, more tutorial introduction to Snit
concepts.
# <a name='section2'></a>SNIT VERSIONS
This man page covers both Snit 2.2 and Snit 1.3. The primary difference between
the two versions is simply that Snit 2.2 contains speed optimizations based on
new features of Tcl 8.5; Snit 1.3 supports all of Tcl 8.3, 8.4 and Tcl 8.5.
There are a few minor inconsistencies; they are flagged in the body of the man
page with the label "Snit 1.x Incompatibility"; they are also discussed in the
__[snitfaq](snitfaq.md)__.
# <a name='section3'></a>REFERENCE
## <a name='subsection1'></a>Type and Widget Definitions
Snit provides the following commands for defining new types:
- <a name='1'></a>__snit::type__ *name* *definition*
Defines a new abstract data type called *name*. If *name* is not a fully
qualified command name, it is assumed to be a name in the namespace in which
the __snit::type__ command was called (usually the global namespace). It
returns the fully qualified name of the new type.
The type name is then a command that is used to create objects of the new
type, along with other activities.
The __snit::type__ *definition* block is a script that may contain the
following definitions:
* <a name='2'></a>__typevariable__ *name* ?__-array__? ?*value*?
Defines a type variable with the specified *name*, and optionally the
specified *value*. Type variables are shared by all instances of the
type. If the __-array__ option is included, then *value* should be a
dictionary; it will be assigned to the variable using __array set__.
* <a name='3'></a>__typemethod__ *name* *arglist* *body*
Defines a type method, a subcommand of the new type command, with the
specified name, argument list, and body. The *arglist* is a normal Tcl
argument list and may contain default arguments and the __args__
argument; however, it may not contain the argument names __type__,
__self__, __selfns__, or __win__.
The variable __type__ is automatically defined in the *body* to the
type's fully-qualified name. In addition, type variables are
automatically visible in the *body* of every type method.
If the *name* consists of two or more tokens, Snit handles it specially:
typemethod {a b} {arg} { puts "Got $arg" }
This statement implicitly defines a type method called __a__ which has a
subcommand __b__. __b__ is called like this:
$type a b "Hello, world!"
__a__ may have any number of subcommands. This makes it possible to
define a hierarchical command structure; see
__[method](../../../../index.md#method)__, below, for more examples.
Type methods can call commands from the namespace in which the type is
defined without importing them, e.g., if the type name is
__::parentns::typename__, then the type's type methods can call
__::parentns::someproc__ just as __someproc__. *Snit 1.x
Incompatibility:* This does not work in Snit 1.x, as it depends on
__namespace path__, a new command in Tcl 8.5.
*Snit 1.x Incompatibility:* In Snit 1.x, the following following two
calls to this type method are equivalent:
$type a b "Hello, world!"
$type {a b} "Hello, world!"
In Snit 2.2, the second form is invalid.
* <a name='4'></a>__typeconstructor__ *body*
The type constructor's *body* is executed once when the type is first
defined; it is typically used to initialize array-valued type variables
and to add entries to [The Tk Option Database](#subsection9).
The variable __type__ is automatically defined in the *body*, and
contains the type's fully-qualified name. In addition, type variables
are automatically visible in the *body* of the type constructor.
A type may define at most one type constructor.
The type constructor can call commands from the namespace in which the
type is defined without importing them, e.g., if the type name is
__::parentns::typename__, then the type constructor can call
__::parentns::someproc__ just as __someproc__. *Snit 1.x
Incompatibility:* This does not work in Snit 1.x, as it depends on
__namespace path__, a new command in Tcl 8.5.
* <a name='5'></a>__variable__ *name* ?__-array__? ?*value*?
Defines an instance variable, a private variable associated with each
instance of this type, and optionally its initial value. If the
__-array__ option is included, then *value* should be a dictionary; it
will be assigned to the variable using __array set__.
* <a name='6'></a>__[method](../../../../index.md#method)__ *name* *arglist* *body*
Defines an instance method, a subcommand of each instance of this type,
with the specified name, argument list and body. The *arglist* is a
normal Tcl argument list and may contain default arguments and the
__args__ argument.
The method is implicitly passed the following arguments as well:
__type__, which contains the fully-qualified type name; __self__, which
contains the current instance command name; __selfns__, which contains
the name of the instance's private namespace; and __win__, which
contains the original instance name. Consequently, the *arglist* may not
contain the argument names __type__, __self__, __selfns__, or __win__.
An instance method defined in this way is said to be *locally defined*.
Type and instance variables are automatically visible in all instance
methods. If the type has locally defined options, the __options__ array
is also visible.
If the *name* consists of two or more tokens, Snit handles it specially:
method {a b} {} { ... }
This statement implicitly defines a method called __a__ which has a
subcommand __b__. __b__ is called like this:
$self a b "Hello, world!"
__a__ may have any number of subcommands. This makes it possible to
define a hierarchical command structure:
% snit::type dog {
method {tail wag} {} {return "Wag, wag"}
method {tail droop} {} {return "Droop, droop"}
}
::dog
% dog spot
::spot
% spot tail wag
Wag, wag
% spot tail droop
Droop, droop
%
What we've done is implicitly defined a "tail" method with subcommands
"wag" and "droop". Consequently, it's an error to define "tail"
explicitly.
Methods can call commands from the namespace in which the type is
defined without importing them, e.g., if the type name is
__::parentns::typename__, then the type's methods can call
__::parentns::someproc__ just as __someproc__. *Snit 1.x
Incompatibility:* This does not work in Snit 1.x, as it depends on
__namespace path__, a new command in Tcl 8.5.
*Snit 1.x Incompatibility:* In Snit 1.x, the following following two
calls to this method are equivalent:
$self a b "Hello, world!"
$self {a b} "Hello, world!"
In Snit 2.2, the second form is invalid.
* <a name='7'></a>__option__ *namespec* ?*defaultValue*?
* <a name='8'></a>__option__ *namespec* ?*options...*?
Defines an option for instances of this type, and optionally gives it an
initial value. The initial value defaults to the empty string if no
*defaultValue* is specified.
An option defined in this way is said to be *locally defined*.
The *namespec* is a list defining the option's name, resource name, and
class name, e.g.:
option {-font font Font} {Courier 12}
The option name must begin with a hyphen, and must not contain any upper
case letters. The resource name and class name are optional; if not
specified, the resource name defaults to the option name, minus the
hyphen, and the class name defaults to the resource name with the first
letter capitalized. Thus, the following statement is equivalent to the
previous example:
option -font {Courier 12}
See [The Tk Option Database](#subsection9) for more information about
resource and class names.
Options are normally set and retrieved using the standard instance
methods __configure__ and __cget__; within instance code (method bodies,
etc.), option values are available through the __options__ array:
set myfont $options(-font)
If the type defines any option handlers (e.g., __-configuremethod__),
then it should probably use __configure__ and __cget__ to access its
options to avoid subtle errors.
The __option__ statement may include the following options:
+ __-default__ *defvalue*
Defines the option's default value; the option's default value will
be "" otherwise.
+ __-readonly__ *flag*
The *flag* can be any Boolean value recognized by Tcl. If *flag* is
true, then the option is read-only--it can only be set using
__configure__ or __configurelist__ at creation time, i.e., in the
type's constructor.
+ __-type__ *type*
Every locally-defined option may define its validation type, which
may be either the name of a validation type or a specification for a
validation subtype
For example, an option may declare that its value must be an integer
by specifying __snit::integer__ as its validation type:
option -number -type snit::integer
It may also declare that its value is an integer between 1 and 10 by
specifying a validation subtype:
option -number -type {snit::integer -min 1 -max 10}
If a validation type or subtype is defined for an option, then it
will be used to validate the option's value whenever it is changed
by the object's __configure__ or __configurelist__ methods. In
addition, all such options will have their values validated
automatically immediately after the constructor executes.
Snit defines a family of validation types and subtypes, and it's
quite simple to define new ones. See [Validation
Types](#subsection11) for the complete list, and [Defining
Validation Types](#subsection12) for an explanation of how to define
your own.
+ __-cgetmethod__ *methodName*
Every locally-defined option may define a __-cgetmethod__; it is
called when the option's value is retrieved using the __cget__
method. Whatever the method's *body* returns will be the return
value of the call to __cget__.
The named method must take one argument, the option name. For
example, this code is equivalent to (though slower than) Snit's
default handling of __cget__:
option -font -cgetmethod GetOption
method GetOption {option} {
return $options($option)
}
Note that it's possible for any number of options to share a
__-cgetmethod__.
+ __-configuremethod__ *methodName*
Every locally-defined option may define a __-configuremethod__; it
is called when the option's value is set using the __configure__ or
__configurelist__ methods. It is the named method's responsibility
to save the option's value; in other words, the value will not be
saved to the __options()__ array unless the method saves it there.
The named method must take two arguments, the option name and its
new value. For example, this code is equivalent to (though slower
than) Snit's default handling of __configure__:
option -font -configuremethod SetOption
method SetOption {option value} {
set options($option) $value
}
Note that it's possible for any number of options to share a single
__-configuremethod__.
+ __-validatemethod__ *methodName*
Every locally-defined option may define a __-validatemethod__; it is
called when the option's value is set using the __configure__ or
__configurelist__ methods, just before the __-configuremethod__ (if
any). It is the named method's responsibility to validate the
option's new value, and to throw an error if the value is invalid.
The named method must take two arguments, the option name and its
new value. For example, this code verifies that __-flag__'s value is
a valid Boolean value:
option -font -validatemethod CheckBoolean
method CheckBoolean {option value} {
if {![string is boolean -strict $value]} {
error "option $option must have a boolean value."
}
}
Note that it's possible for any number of options to share a single
__-validatemethod__.
* <a name='9'></a>__constructor__ *arglist* *body*
The constructor definition specifies a *body* of code to be executed
when a new instance is created. The *arglist* is a normal Tcl argument
list and may contain default arguments and the __args__ argument.
As with methods, the arguments __type__, __self__, __selfns__, and
__win__ are defined implicitly, and all type and instance variables are
automatically visible in its *body*.
If the *definition* doesn't explicitly define the constructor, Snit
defines one implicitly. If the type declares at least one option
(whether locally or by delegation), the default constructor will be
defined as follows:
constructor {args} {
$self configurelist $args
}
For standard Tk widget behavior, the argument list should be the single
name __args__, as shown.
If the *definition* defines neither a constructor nor any options, the
default constructor is defined as follows:
constructor {} {}
As with methods, the constructor can call commands from the namespace in
which the type is defined without importing them, e.g., if the type name
is __::parentns::typename__, then the constructor can call
__::parentns::someproc__ just as __someproc__. *Snit 1.x
Incompatibility:* This does not work in Snit 1.x, as it depends on
__namespace path__, a new command in Tcl 8.5.
* <a name='10'></a>__destructor__ *body*
The destructor is used to code any actions that must take place when an
instance of the type is destroyed: typically, the destruction of
anything created in the constructor.
The destructor takes no explicit arguments; as with methods, the
arguments __type__, __self__, __selfns__, and __win__, are defined
implicitly, and all type and instance variables are automatically
visible in its *body*. As with methods, the destructor can call commands
from the namespace in which the type is defined without importing them,
e.g., if the type name is __::parentns::typename__, then the destructor
can call __::parentns::someproc__ just as __someproc__. *Snit 1.x
Incompatibility:* This does not work in Snit 1.x, as it depends on
__namespace path__, a new command in Tcl 8.5.
* <a name='11'></a>__[proc](../../../../index.md#proc)__ *name* *args* *body*
Defines a new Tcl procedure in the type's namespace.
The defined proc differs from a normal Tcl proc in that all type
variables are automatically visible. The proc can access instance
variables as well, provided that it is passed __selfns__ (with precisely
that name) as one of its arguments.
Although they are not implicitly defined for procs, the argument names
__type__, __self__, and __win__ should be avoided.
As with methods and typemethods, procs can call commands from the
namespace in which the type is defined without importing them, e.g., if
the type name is __::parentns::typename__, then the proc can call
__::parentns::someproc__ just as __someproc__. *Snit 1.x
Incompatibility:* This does not work in Snit 1.x, as it depends on
__namespace path__, a new command in Tcl 8.5.
* <a name='12'></a>__delegate__ __method__ *name* __to__ *comp* ?__as__ *target*?
Delegates method *name* to component *comp*. That is, when method *name*
is called on an instance of this type, the method and its arguments will
be passed to the named component's command instead. That is, the
following statement
delegate method wag to tail
is roughly equivalent to this explicitly defined method:
method wag {args} {
uplevel $tail wag $args
}
As with methods, the *name* may have multiple tokens; in this case, the
last token of the name is assumed to be the name of the component's
method.
The optional __as__ clause allows you to specify the delegated method
name and possibly add some arguments:
delegate method wagtail to tail as "wag briskly"
A method cannot be both locally defined and delegated.
__Note:__ All forms of __delegate method__ can delegate to both instance
components and type components.
* <a name='13'></a>__delegate__ __method__ *name* ?__to__ *comp*? __using__ *pattern*
In this form of the __delegate__ statement, the __using__ clause is used
to specify the precise form of the command to which method *name* name
is delegated. In this form, the __to__ clause is optional, since the
chosen command might not involve any particular component.
The value of the __using__ clause is a list that may contain any or all
of the following substitution codes; these codes are substituted with
the described value to build the delegated command prefix. Note that the
following two statements are equivalent:
delegate method wag to tail
delegate method wag to tail using "%c %m"
Each element of the list becomes a single element of the delegated
command--it is never reparsed as a string.
Substitutions:
+ __%%__
This is replaced with a single "%". Thus, to pass the string "%c" to
the command as an argument, you'd write "%%c".
+ __%c__
This is replaced with the named component's command.
+ __%m__
This is replaced with the final token of the method *name*; if the
method *name* has one token, this is identical to __%M__.
+ __%M__
This is replaced by the method *name*; if the *name* consists of
multiple tokens, they are joined by space characters.
+ __%j__
This is replaced by the method *name*; if the *name* consists of
multiple tokens, they are joined by underscores ("_").
+ __%t__
This is replaced with the fully qualified type name.
+ __%n__
This is replaced with the name of the instance's private namespace.
+ __%s__
This is replaced with the name of the instance command.
+ __%w__
This is replaced with the original name of the instance command; for
Snit widgets and widget adaptors, it will be the Tk window name. It
remains constant, even if the instance command is renamed.
* <a name='14'></a>__delegate__ __method__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?
The form __delegate method *__ delegates all unknown method names to the
specified *comp*onent. The __except__ clause can be used to specify a
list of *exceptions*, i.e., method names that will not be so delegated.
The __using__ clause is defined as given above. In this form, the
statement must contain the __to__ clause, the __using__ clause, or both.
In fact, the "*" can be a list of two or more tokens whose last element
is "*", as in the following example:
delegate method {tail *} to tail
This implicitly defines the method __tail__ whose subcommands will be
delegated to the __tail__ component.
* <a name='15'></a>__delegate__ __option__ *namespec* __to__ *comp*
* <a name='16'></a>__delegate__ __option__ *namespec* __to__ *comp* __as__ *target*
* <a name='17'></a>__delegate__ __option__ __*__ __to__ *comp*
* <a name='18'></a>__delegate__ __option__ __*__ __to__ *comp* __except__ *exceptions*
Defines a delegated option; the *namespec* is defined as for the
__option__ statement. When the __configure__, __configurelist__, or
__cget__ instance method is used to set or retrieve the option's value,
the equivalent __configure__ or __cget__ command will be applied to the
component as though the option was defined with the following
__-configuremethod__ and __-cgetmethod__:
method ConfigureMethod {option value} {
$comp configure $option $value
}
method CgetMethod {option} {
return [$comp cget $option]
}
Note that delegated options never appear in the __options__ array.
If the __as__ clause is specified, then the *target* option name is used
in place of *name*.
The form __delegate option *__ delegates all unknown options to the
specified *comp*onent. The __except__ clause can be used to specify a
list of *exceptions*, i.e., option names that will not be so delegated.
Warning: options can only be delegated to a component if it supports the
__configure__ and __cget__ instance methods.
An option cannot be both locally defined and delegated. TBD: Continue
from here.
* <a name='19'></a>__component__ *comp* ?__-public__ *method*? ?__-inherit__ *flag*?
Explicitly declares a component called *comp*, and automatically defines
the component's instance variable.
If the __-public__ option is specified, then the option is made public
by defining a *method* whose subcommands are delegated to the component
e.g., specifying __-public mycomp__ is equivalent to the following:
component mycomp
delegate method {mymethod *} to mycomp
If the __-inherit__ option is specified, then *flag* must be a Boolean
value; if *flag* is true then all unknown methods and options will be
delegated to this component. The name __-inherit__ implies that
instances of this new type inherit, in a sense, the methods and options
of the component. That is, __-inherit yes__ is equivalent to:
component mycomp
delegate option * to mycomp
delegate method * to mycomp
* <a name='20'></a>__delegate__ __typemethod__ *name* __to__ *comp* ?__as__ *target*?
Delegates type method *name* to type component *comp*. That is, when
type method *name* is called on this type, the type method and its
arguments will be passed to the named type component's command instead.
That is, the following statement
delegate typemethod lostdogs to pound
is roughly equivalent to this explicitly defined method:
typemethod lostdogs {args} {
uplevel $pound lostdogs $args
}
As with type methods, the *name* may have multiple tokens; in this case,
the last token of the name is assumed to be the name of the component's
method.
The optional __as__ clause allows you to specify the delegated method
name and possibly add some arguments:
delegate typemethod lostdogs to pound as "get lostdogs"
A type method cannot be both locally defined and delegated.
* <a name='21'></a>__delegate__ __typemethod__ *name* ?__to__ *comp*? __using__ *pattern*
In this form of the __delegate__ statement, the __using__ clause is used
to specify the precise form of the command to which type method *name*
name is delegated. In this form, the __to__ clause is optional, since
the chosen command might not involve any particular type component.
The value of the __using__ clause is a list that may contain any or all
of the following substitution codes; these codes are substituted with
the described value to build the delegated command prefix. Note that the
following two statements are equivalent:
delegate typemethod lostdogs to pound
delegate typemethod lostdogs to pound using "%c %m"
Each element of the list becomes a single element of the delegated
command--it is never reparsed as a string.
Substitutions:
+ __%%__
This is replaced with a single "%". Thus, to pass the string "%c" to
the command as an argument, you'd write "%%c".
+ __%c__
This is replaced with the named type component's command.
+ __%m__
This is replaced with the final token of the type method *name*; if
the type method *name* has one token, this is identical to __%M__.
+ __%M__
This is replaced by the type method *name*; if the *name* consists
of multiple tokens, they are joined by space characters.
+ __%j__
This is replaced by the type method *name*; if the *name* consists
of multiple tokens, they are joined by underscores ("_").
+ __%t__
This is replaced with the fully qualified type name.
* <a name='22'></a>__delegate__ __typemethod__ __*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?
The form __delegate typemethod *__ delegates all unknown type method
names to the specified type component. The __except__ clause can be used
to specify a list of *exceptions*, i.e., type method names that will not
be so delegated. The __using__ clause is defined as given above. In this
form, the statement must contain the __to__ clause, the __using__
clause, or both.
__Note:__ By default, Snit interprets __$type foo__, where __foo__ is
not a defined type method, as equivalent to __$type create foo__, where
__foo__ is the name of a new instance of the type. If you use __delegate
typemethod *__, then the __create__ type method must always be used
explicitly.
The "*" can be a list of two or more tokens whose last element is "*",
as in the following example:
delegate typemethod {tail *} to tail
This implicitly defines the type method __tail__ whose subcommands will
be delegated to the __tail__ type component.
* <a name='23'></a>__typecomponent__ *comp* ?__-public__ *typemethod*? ?__-inherit__ *flag*?
Explicitly declares a type component called *comp*, and automatically
defines the component's type variable. A type component is an arbitrary
command to which type methods and instance methods can be delegated; the
command's name is stored in a type variable.
If the __-public__ option is specified, then the type component is made
public by defining a *typemethod* whose subcommands are delegated to the
type component, e.g., specifying __-public mytypemethod__ is equivalent
to the following:
typecomponent mycomp
delegate typemethod {mytypemethod *} to mycomp
If the __-inherit__ option is specified, then *flag* must be a Boolean
value; if *flag* is true then all unknown type methods will be delegated
to this type component. (See the note on "delegate typemethod *",
above.) The name __-inherit__ implies that this type inherits, in a
sense, the behavior of the type component. That is, __-inherit yes__ is
equivalent to:
typecomponent mycomp
delegate typemethod * to mycomp
* <a name='24'></a>__pragma__ ?*options...*?
The __pragma__ statement provides control over how Snit generates a
type. It takes the following options; in each case, *flag* must be a
Boolean value recognized by Tcl, e.g., __0__, __1__, __yes__, __no__,
and so on.
By setting the __-hastypeinfo__, __-hastypedestroy__, and
__-hasinstances__ pragmas to false and defining appropriate type
methods, you can create an ensemble command without any extraneous
behavior.
+ __-canreplace__ *flag*
If false (the default) Snit will not create an instance of a
__snit::type__ that has the same name as an existing command; this
prevents subtle errors. Setting this pragma to true restores the
behavior of Snit V0.93 and earlier versions.
+ __-hastypeinfo__ *flag*
If true (the default), the generated type will have a type method
called __[info](../../../../index.md#info)__ that is used for type
introspection; the __[info](../../../../index.md#info)__ type method
is documented below. If false, it will not.
+ __-hastypedestroy__ *flag*
If true (the default), the generated type will have a type method
called __destroy__ that is used to destroy the type and all of its
instances. The __destroy__ type method is documented below. If
false, it will not.
+ __-hastypemethods__ *flag*
If true (the default), the generated type's type command will have
subcommands (type methods) as usual. If false, the type command will
serve only to create instances of the type; the first argument is
the instance name.
This pragma and __-hasinstances__ cannot both be set false.
+ __-hasinstances__ *flag*
If true (the default), the generated type will have a type method
called __create__ that is used to create instances of the type,
along with a variety of instance-related features. If false, it will
not.
This pragma and __-hastypemethods__ cannot both be set false.
+ __-hasinfo__ *flag*
If true (the default), instances of the generated type will have an
instance method called __info__ that is used for instance
introspection; the __info__ method is documented below. If false, it
will not.
+ __-simpledispatch__ *flag*
This pragma is intended to make simple, heavily-used abstract data
types (e.g., stacks and queues) more efficient.
If false (the default), instance methods are dispatched normally. If
true, a faster dispatching scheme is used instead. The speed comes
at a price; with __-simpledispatch yes__ you get the following
limitations:
Methods cannot be delegated.
__uplevel__ and __upvar__ do not work as expected: the caller's
scope is two levels up rather than one.
The option-handling methods (__cget__, __configure__, and
__configurelist__) are very slightly slower.
* <a name='25'></a>__expose__ *comp*
* <a name='26'></a>__expose__ *comp* __as__ *method*
__Deprecated.__ To expose component *comp* publicly, use __component__'s
__-public__ option.
* <a name='27'></a>__onconfigure__ *name* *arglist* *body*
__Deprecated.__ Define __option__'s __-configuremethod__ option instead.
As of version 0.95, the following definitions,
option -myoption
onconfigure -myoption {value} {
# Code to save the option's value
}
are implemented as follows:
option -myoption -configuremethod _configure-myoption
method _configure-myoption {_option value} {
# Code to save the option's value
}
* <a name='28'></a>__oncget__ *name* *body*
__Deprecated.__ Define __option__'s __-cgetmethod__ option instead.
As of version 0.95, the following definitions,
option -myoption
oncget -myoption {
# Code to return the option's value
}
are implemented as follows:
option -myoption -cgetmethod _cget-myoption
method _cget-myoption {_option} {
# Code to return the option's value
}
- <a name='29'></a>__snit::widget__ *name* *definition*
This command defines a Snit megawidget type with the specified *name*. The
*definition* is defined as for __snit::type__. A __snit::widget__ differs
from a __snit::type__ in these ways:
Every instance of a __snit::widget__ has an automatically-created component
called __hull__, which is normally a Tk frame widget. Other widgets created
as part of the megawidget will be created within this widget.
The hull component is initially created with the requested widget name; then
Snit does some magic, renaming the hull component and installing its own
instance command in its place. The hull component's new name is saved in an
instance variable called __hull__.
The name of an instance must be valid Tk window name, and the parent window
must exist.
A __snit::widget__ definition can include any of statements allowed in a
__snit::type__ definition, and may also include the following:
* <a name='30'></a>__widgetclass__ *name*
Sets the __snit::widget__'s widget class to *name*, overriding the
default. See [The Tk Option Database](#subsection9) for more
information.
* <a name='31'></a>__hulltype__ *type*
Determines the kind of widget used as the __snit::widget__'s hull. The
*type* may be __frame__ (the default), __toplevel__, __labelframe__; the
qualified equivalents of these, __tk::frame__, __tk::toplevel__, and
__tk::labelframe__; or, if available, the equivalent Tile widgets:
__ttk::frame__, __ttk::toplevel__, and __ttk::labelframe__. In practice,
any widget that supports the __-class__ option can be used as a hull
widget by __lappend__'ing its name to the variable __snit::hulltypes__.
- <a name='32'></a>__snit::widgetadaptor__ *name* *definition*
This command defines a Snit megawidget type with the specified name. It
differs from __snit::widget__ in that the instance's __hull__ component is
not created automatically, but is created in the constructor and installed
using the __installhull__ command. Once the hull is installed, its instance
command is renamed and replaced as with normal __snit::widget__s. The
original command is again accessible in the instance variable __hull__.
Note that in general it is not possible to change the *widget class* of a
__snit::widgetadaptor__'s hull widget.
See [The Tk Option Database](#subsection9) for information on how
__snit::widgetadaptor__s interact with the option database.
- <a name='33'></a>__snit::typemethod__ *type* *name* *arglist* *body*
Defines a new type method (or redefines an existing type method) for a
previously existing *type*.
- <a name='34'></a>__snit::method__ *type* *name* *arglist* *body*
Defines a new instance method (or redefines an existing instance method) for
a previously existing *type*. Note that delegated instance methods can't be
redefined.
- <a name='35'></a>__snit::macro__ *name* *arglist* *body*
Defines a Snit macro with the specified *name*, *arglist*, and *body*.
Macros are used to define new type and widget definition statements in terms
of the statements defined in this man page.
A macro is simply a Tcl proc that is defined in the slave interpreter used
to compile type and widget definitions. Thus, macros have access to all of
the type and widget definition statements. See [Macros and
Meta-programming](#subsection10) for more details.
The macro *name* cannot be the same as any standard Tcl command, or any Snit
type or widget definition statement, e.g., you can't redefine the
__[method](../../../../index.md#method)__ or __delegate__ statements, or the
standard __[set](../../../../index.md#set)__,
__[list](../../../../index.md#list)__, or
__[string](../../../../index.md#string)__ commands.
- <a name='36'></a>__snit::compile__ *which* *type* *body*
Snit defines a type, widget, or widgetadaptor by "compiling" the definition
into a Tcl script; this script is then evaluated in the Tcl interpreter,
which actually defines the new type.
This command exposes the "compiler". Given a definition *body* for the named
*type*, where *which* is __type__, __widget__, or __widgetadaptor__,
__snit::compile__ returns a list of two elements. The first element is the
fully qualified type name; the second element is the definition script.
__snit::compile__ is useful when additional processing must be done on the
Snit-generated code--if it must be instrumented, for example, or run through
the TclDevKit compiler. In addition, the returned script could be saved in a
".tcl" file and used to define the type as part of an application or
library, thus saving the compilation overhead at application start-up. Note
that the same version of Snit must be used at run-time as at compile-time.
## <a name='subsection2'></a>The Type Command
A type or widget definition creates a type command, which is used to create
instances of the type. The type command has this form:
- <a name='37'></a>__$type__ *typemethod* *args*...
The *typemethod* can be any of the [Standard Type Methods](#subsection3)
(e.g., __create__), or any type method defined in the type definition. The
subsequent *args* depend on the specific *typemethod* chosen.
The type command is most often used to create new instances of the type;
hence, the __create__ method is assumed if the first argument to the type
command doesn't name a valid type method, unless the type definition
includes __delegate typemethod *__ or the __-hasinstances__ pragma is set to
false.
Furthermore, if the __-hastypemethods__ pragma is false, then Snit type
commands can be called with no arguments at all; in this case, the type
command creates an instance with an automatically generated name. In other
words, provided that the __-hastypemethods__ pragma is false and the type
has instances, the following commands are equivalent:
snit::type dog { ... }
set mydog [dog create %AUTO%]
set mydog [dog %AUTO%]
set mydog [dog]
This doesn't work for Snit widgets, for obvious reasons.
*Snit 1.x Incompatibility:* In Snit 1.x, the above behavior is available
whether __-hastypemethods__ is true (the default) or false.
## <a name='subsection3'></a>Standard Type Methods
In addition to any type methods in the type's definition, all type and widget
commands will usually have at least the following subcommands:
- <a name='38'></a>__$type__ __create__ *name* ?*option* *value* ...?
Creates a new instance of the type, giving it the specified *name* and
calling the type's constructor.
For __snit::type__s, if *name* is not a fully-qualified command name, it is
assumed to be a name in the namespace in which the call to __snit::type__
appears. The method returns the fully-qualified instance name.
For __snit::widget__s and __snit::widgetadaptor__s, *name* must be a valid
widget name; the method returns the widget name.
So long as *name* does not conflict with any defined type method name the
__create__ keyword may be omitted, unless the type definition includes
__delegate typemethod *__ or the __-hasinstances__ pragma is set to false.
If the *name* includes the string __%AUTO%__, it will be replaced with the
string __$type$counter__ where __$type__ is the type name and __$counter__
is a counter that increments each time __%AUTO%__ is used for this type.
By default, any arguments following the *name* will be a list of *option*
names and their *value*s; however, a type's constructor can specify a
different argument list.
As of Snit V0.95, __create__ will throw an error if the *name* is the same
as any existing command--note that this was always true for
__snit::widget__s and __snit::widgetadaptor__s. You can restore the previous
behavior using the __-canreplace__ pragma.
- <a name='39'></a>__$type__ __info typevars__ ?*pattern*?
Returns a list of the type's type variables (excluding Snit internal
variables); all variable names are fully-qualified.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
- <a name='40'></a>__$type__ __info typemethods__ ?*pattern*?
Returns a list of the names of the type's type methods. If the type has
hierarchical type methods, whether locally-defined or delegated, only the
first word of each will be included in the list.
If the type definition includes __delegate typemethod *__, the list will
include only the names of those implicitly delegated type methods that have
been called at least once and are still in the type method cache.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
- <a name='41'></a>__$type__ __info args__ *method*
Returns a list containing the names of the arguments to the type's *method*,
in order. This method cannot be applied to delegated type methods.
- <a name='42'></a>__$type__ __info body__ *method*
Returns the body of typemethod *method*. This method cannot be applied to
delegated type methods.
- <a name='43'></a>__$type__ __info default__ *method* *aname* *varname*
Returns a boolean value indicating whether the argument *aname* of the
type's *method* has a default value (__true__) or not (__false__). If the
argument has a default its value is placed into the variable *varname*.
- <a name='44'></a>__$type__ __info instances__ ?*pattern*?
Returns a list of the type's instances. For __snit::type__s, it will be a
list of fully-qualified instance names; for __snit::widget__s, it will be a
list of Tk widget names.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
*Snit 1.x Incompatibility:* In Snit 1.x, the full multi-word names of
hierarchical type methods are included in the return value.
- <a name='45'></a>__$type__ __destroy__
Destroys the type's instances, the type's namespace, and the type command
itself.
## <a name='subsection4'></a>The Instance Command
A Snit type or widget's __create__ type method creates objects of the type; each
object has a unique name that is also a Tcl command. This command is used to
access the object's methods and data, and has this form:
- <a name='46'></a>__$object__ *method* *args...*
The *method* can be any of the [Standard Instance Methods](#subsection5), or
any instance method defined in the type definition. The subsequent *args*
depend on the specific *method* chosen.
## <a name='subsection5'></a>Standard Instance Methods
In addition to any delegated or locally-defined instance methods in the type's
definition, all Snit objects will have at least the following subcommands:
- <a name='47'></a>__$object__ __configure__ ?*option*? ?*value*? ...
Assigns new values to one or more options. If called with one argument, an
*option* name, returns a list describing the option, as Tk widgets do; if
called with no arguments, returns a list of lists describing all options, as
Tk widgets do.
Warning: This information will be available for delegated options only if
the component to which they are delegated has a __configure__ method that
returns this same kind of information.
Note: Snit defines this method only if the type has at least one option.
- <a name='48'></a>__$object__ __configurelist__ *optionlist*
Like __configure__, but takes one argument, a list of options and their
values. It's mostly useful in the type constructor, but can be used
anywhere.
Note: Snit defines this method only if the type has at least one option.
- <a name='49'></a>__$object__ __cget__ *option*
Returns the option's value.
Note: Snit defines this method only if the type has at least one option.
- <a name='50'></a>__$object__ __destroy__
Destroys the object, calling the __destructor__ and freeing all related
memory.
*Note:* The __destroy__ method isn't defined for __snit::widget__ or
__snit::widgetadaptor__ objects; instances of these are destroyed by calling
__[Tk](../../../../index.md#tk)__'s __destroy__ command, just as normal
widgets are.
- <a name='51'></a>__$object__ __info type__
Returns the instance's type.
- <a name='52'></a>__$object__ __info vars__ ?*pattern*?
Returns a list of the object's instance variables (excluding Snit internal
variables). The names are fully qualified.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
- <a name='53'></a>__$object__ __info typevars__ ?*pattern*?
Returns a list of the object's type's type variables (excluding Snit
internal variables). The names are fully qualified.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
- <a name='54'></a>__$object__ __info typemethods__ ?*pattern*?
Returns a list of the names of the type's type methods. If the type has
hierarchical type methods, whether locally-defined or delegated, only the
first word of each will be included in the list.
If the type definition includes __delegate typemethod *__, the list will
include only the names of those implicitly delegated type methods that have
been called at least once and are still in the type method cache.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
*Snit 1.x Incompatibility:* In Snit 1.x, the full multi-word names of
hierarchical type methods are included in the return value.
- <a name='55'></a>__$object__ __info options__ ?*pattern*?
Returns a list of the object's option names. This always includes local
options and explicitly delegated options. If unknown options are delegated
as well, and if the component to which they are delegated responds to
__$object configure__ like Tk widgets do, then the result will include all
possible unknown options that can be delegated to the component.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
Note that the return value might be different for different instances of the
same type, if component object types can vary from one instance to another.
- <a name='56'></a>__$object__ __info methods__ ?*pattern*?
Returns a list of the names of the instance's methods. If the type has
hierarchical methods, whether locally-defined or delegated, only the first
word of each will be included in the list.
If the type definition includes __delegate method *__, the list will include
only the names of those implicitly delegated methods that have been called
at least once and are still in the method cache.
If *pattern* is given, it's used as a __string match__ pattern; only names
that match the pattern are returned.
*Snit 1.x Incompatibility:* In Snit 1.x, the full multi-word names of
hierarchical type methods are included in the return value.
- <a name='57'></a>__$object__ __info args__ *method*
Returns a list containing the names of the arguments to the instance's
*method*, in order. This method cannot be applied to delegated methods.
- <a name='58'></a>__$object__ __info body__ *method*
Returns the body of the instance's method *method*. This method cannot be
applied to delegated methods.
- <a name='59'></a>__$object__ __info default__ *method* *aname* *varname*
Returns a boolean value indicating whether the argument *aname* of the
instance's *method* has a default value (__true__) or not (__false__). If
the argument has a default its value is placed into the variable *varname*.
## <a name='subsection6'></a>Commands for use in Object Code
Snit defines the following commands for use in your object code: that is, for
use in type methods, instance methods, constructors, destructors, onconfigure
handlers, oncget handlers, and procs. They do not reside in the ::snit::
namespace; instead, they are created with the type, and can be used without
qualification.
- <a name='60'></a>__mymethod__ *name* ?*args...*?
The __mymethod__ command is used for formatting callback commands to be
passed to other objects. It returns a command that when called will invoke
method *name* with the specified arguments, plus of course any arguments
added by the caller. In other words, both of the following commands will
cause the object's __dosomething__ method to be called when the __$button__
is pressed:
$button configure -command [list $self dosomething myargument]
$button configure -command [mymethod dosomething myargument]
The chief distinction between the two is that the latter form will not break
if the object's command is renamed.
- <a name='61'></a>__mytypemethod__ *name* ?*args...*?
The __mytypemethod__ command is used for formatting callback commands to be
passed to other objects. It returns a command that when called will invoke
type method *name* with the specified arguments, plus of course any
arguments added by the caller. In other words, both of the following
commands will cause the object's __dosomething__ type method to be called
when __$button__ is pressed:
$button configure -command [list $type dosomething myargument]
$button configure -command [mytypemethod dosomething myargument]
Type commands cannot be renamed, so in practice there's little difference
between the two forms. __mytypemethod__ is provided for parallelism with
__mymethod__.
- <a name='62'></a>__myproc__ *name* ?*args...*?
The __myproc__ command is used for formatting callback commands to be passed
to other objects. It returns a command that when called will invoke the type
proc *name* with the specified arguments, plus of course any arguments added
by the caller. In other words, both of the following commands will cause the
object's __dosomething__ proc to be called when __$button__ is pressed:
$button configure -command [list ${type}::dosomething myargument]
$button configure -command [myproc dosomething myargument]
- <a name='63'></a>__myvar__ *name*
Given an instance variable name, returns the fully qualified name. Use this
if you're passing the variable to some other object, e.g., as a
__-textvariable__ to a Tk label widget.
- <a name='64'></a>__mytypevar__ *name*
Given an type variable name, returns the fully qualified name. Use this if
you're passing the variable to some other object, e.g., as a
__-textvariable__ to a Tk label widget.
- <a name='65'></a>__from__ *argvName* *option* ?*defvalue*?
The __from__ command plucks an option value from a list of options and their
values, such as is passed into a type's __constructor__. *argvName* must be
the name of a variable containing such a list; *option* is the name of the
specific option.
__from__ looks for *option* in the option list. If it is found, it and its
value are removed from the list, and the value is returned. If *option*
doesn't appear in the list, then the *defvalue* is returned. If the option
is locally-defined option, and *defvalue* is not specified, then the
option's default value as specified in the type definition will be returned
instead.
- <a name='66'></a>__install__ *compName* __using__ *objType* *objName* *args...*
Creates a new object of type *objType* called *objName* and installs it as
component *compName*, as described in [Components and
Delegation](#subsection7). Any additional *args...* are passed along with
the name to the *objType* command. If this is a __snit::type__, then the
following two commands are equivalent:
install myComp using myObjType $self.myComp args...
set myComp [myObjType $self.myComp args...]
Note that whichever method is used, *compName* must still be declared in the
type definition using __component__, or must be referenced in at least one
__delegate__ statement.
If this is a __snit::widget__ or __snit::widgetadaptor__, and if options
have been delegated to component *compName*, then those options will receive
default values from the Tk option database. Note that it doesn't matter
whether the component to be installed is a widget or not. See [The Tk Option
Database](#subsection9) for more information.
__install__ cannot be used to install type components; just assign the type
component's command name to the type component's variable instead.
- <a name='67'></a>__installhull__ __using__ *widgetType* *args...*
- <a name='68'></a>__installhull__ *name*
The constructor of a __snit::widgetadaptor__ must create a widget to be the
object's hull component; the widget is installed as the hull component using
this command. Note that the installed widget's name must be __$win__. This
command has two forms.
The first form specifies the *widgetType* and the *args...* (that is, the
hardcoded option list) to use in creating the hull. Given this form,
__installhull__ creates the hull widget, and initializes any options
delegated to the hull from the Tk option database.
In the second form, the hull widget has already been created; note that its
name must be "$win". In this case, the Tk option database is *not* queried
for any options delegated to the hull. The longer form is preferred;
however, the shorter form allows the programmer to adapt a widget created
elsewhere, which is sometimes useful. For example, it can be used to adapt a
"page" widget created by a __BWidgets__ tabbed notebook or pages manager
widget.
See [The Tk Option Database](#subsection9) for more information about
__snit::widgetadaptor__s and the option database.
- <a name='69'></a>__variable__ *name*
Normally, instance variables are defined in the type definition along with
the options, methods, and so forth; such instance variables are
automatically visible in all instance code (e.g., method bodies). However,
instance code can use the __variable__ command to declare instance variables
that don't appear in the type definition, and also to bring variables from
other namespaces into scope in the usual way.
It's generally clearest to define all instance variables in the type
definition, and omit declaring them in methods and so forth.
Note that this is an instance-specific version of the standard Tcl
__::variable__ command.
- <a name='70'></a>__typevariable__ *name*
Normally, type variables are defined in the type definition, along with the
instance variables; such type variables are automatically visible in all of
the type's code. However, type methods, instance methods and so forth can
use __typevariable__ to declare type variables that don't appear in the type
definition.
It's generally clearest to declare all type variables in the type
definition, and omit declaring them in methods, type methods, etc.
- <a name='71'></a>__varname__ *name*
__Deprecated.__ Use __myvar__ instead.
Given an instance variable name, returns the fully qualified name. Use this
if you're passing the variable to some other object, e.g., as a
__-textvariable__ to a Tk label widget.
- <a name='72'></a>__typevarname__ *name*
__Deprecated.__ Use __mytypevar__ instead.
Given a type variable name, returns the fully qualified name. Use this if
you're passing the type variable to some other object, e.g., as a
__-textvariable__ to a Tk label widget.
- <a name='73'></a>__codename__ *name*
__Deprecated.__ Use __myproc__ instead. Given the name of a proc (but not a
type or instance method), returns the fully-qualified command name, suitable
for passing as a callback.
## <a name='subsection7'></a>Components and Delegation
When an object includes other objects, as when a toolbar contains buttons or a
GUI object contains an object that references a database, the included object is
called a component. The standard way to handle component objects owned by a Snit
object is to declare them using __component__, which creates a component
instance variable. In the following example, a __dog__ object has a __tail__
object:
snit::type dog {
component mytail
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
method wag {} {
$mytail wag
}
}
snit::type tail {
option -length 5
option -partof
method wag {} { return "Wag, wag, wag."}
}
Because the __tail__ object's name is stored in an instance variable, it's
easily accessible in any method.
The __install__ command provides an alternate way to create and install the
component:
snit::type dog {
component mytail
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
method wag {} {
$mytail wag
}
}
For __snit::type__s, the two methods are equivalent; for __snit::widget__s and
__snit::widgetadaptor__s, the __install__ command properly initializes the
widget's options by querying [The Tk Option Database](#subsection9).
In the above examples, the __dog__ object's __wag__ method simply calls the
__tail__ component's __wag__ method. In OO jargon, this is called delegation.
Snit provides an easier way to do this:
snit::type dog {
delegate method wag to mytail
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
The __delegate__ statement in the type definition implicitly defines the
instance variable __mytail__ to hold the component's name (though it's good form
to use __component__ to declare it explicitly); it also defines the __dog__
object's __wag__ method, delegating it to the __mytail__ component.
If desired, all otherwise unknown methods can be delegated to a specific
component:
snit::type dog {
delegate method * to mytail
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
method bark { return "Bark, bark, bark!" }
}
In this case, a __dog__ object will handle its own __bark__ method; but __wag__
will be passed along to __mytail__. Any other method, being recognized by
neither __dog__ nor __tail__, will simply raise an error.
Option delegation is similar to method delegation, except for the interactions
with the Tk option database; this is described in [The Tk Option
Database](#subsection9).
## <a name='subsection8'></a>Type Components and Delegation
The relationship between type components and instance components is identical to
that between type variables and instance variables, and that between type
methods and instance methods. Just as an instance component is an instance
variable that holds the name of a command, so a type component is a type
variable that holds the name of a command. In essence, a type component is a
component that's shared by every instance of the type.
Just as __delegate method__ can be used to delegate methods to instance
components, as described in [Components and Delegation](#subsection7), so
__delegate typemethod__ can be used to delegate type methods to type components.
Note also that as of Snit 0.95 __delegate method__ can delegate methods to both
instance components and type components.
## <a name='subsection9'></a>The Tk Option Database
This section describes how Snit interacts with the Tk option database, and
assumes the reader has a working knowledge of the option database and its uses.
The book *Practical Programming in Tcl and Tk* by Welch et al has a good
introduction to the option database, as does *Effective Tcl/Tk Programming*.
Snit is implemented so that most of the time it will simply do the right thing
with respect to the option database, provided that the widget developer does the
right thing by Snit. The body of this section goes into great deal about what
Snit requires. The following is a brief statement of the requirements, for
reference.
- If the __snit::widget__'s default widget class is not what is desired, set
it explicitly using __widgetclass__ in the widget definition.
- When defining or delegating options, specify the resource and class names
explicitly when if the defaults aren't what you want.
- Use __installhull using__ to install the hull for __snit::widgetadaptor__s.
- Use __install__ to install all other components.
The interaction of Tk widgets with the option database is a complex thing; the
interaction of Snit with the option database is even more so, and repays
attention to detail.
__Setting the widget class:__ Every Tk widget has a widget class. For Tk
widgets, the widget class name is the just the widget type name with an initial
capital letter, e.g., the widget class for __button__ widgets is "Button".
Similarly, the widget class of a __snit::widget__ defaults to the unqualified
type name with the first letter capitalized. For example, the widget class of
snit::widget ::mylibrary::scrolledText { ... }
is "ScrolledText". The widget class can also be set explicitly using the
__widgetclass__ statement within the __snit::widget__ definition.
Any widget can be used as the __hulltype__ provided that it supports the
__-class__ option for changing its widget class name. See the discussion of the
__hulltype__ command, above. The user may pass __-class__ to the widget at
instantion.
The widget class of a __snit::widgetadaptor__ is just the widget class of its
hull widget; this cannot be changed unless the hull widget supports __-class__,
in which case it will usually make more sense to use __snit::widget__ rather
than __snit::widgetadaptor__.
__Setting option resource names and classes:__ In Tk, every option has three
names: the option name, the resource name, and the class name. The option name
begins with a hyphen and is all lowercase; it's used when creating widgets, and
with the __configure__ and __cget__ commands.
The resource and class names are used to initialize option default values by
querying the Tk option database. The resource name is usually just the option
name minus the hyphen, but may contain uppercase letters at word boundaries; the
class name is usually just the resource name with an initial capital, but not
always. For example, here are the option, resource, and class names for several
__[text](../../../../index.md#text)__ widget options:
-background background Background
-borderwidth borderWidth BorderWidth
-insertborderwidth insertBorderWidth BorderWidth
-padx padX Pad
As is easily seen, sometimes the resource and class names can be inferred from
the option name, but not always.
Snit options also have a resource name and a class name. By default, these names
follow the rule given above: the resource name is the option name without the
hyphen, and the class name is the resource name with an initial capital. This is
true for both locally-defined options and explicitly delegated options:
snit::widget mywidget {
option -background
delegate option -borderwidth to hull
delegate option * to text
# ...
}
In this case, the widget class name is "Mywidget". The widget has the following
options: __-background__, which is locally defined, and __-borderwidth__, which
is explicitly delegated; all other widgets are delegated to a component called
"text", which is probably a Tk __[text](../../../../index.md#text)__ widget. If
so, __mywidget__ has all the same options as a
__[text](../../../../index.md#text)__ widget. The option, resource, and class
names are as follows:
-background background Background
-borderwidth borderwidth Borderwidth
-padx padX Pad
Note that the locally defined option, __-background__, happens to have the same
three names as the standard Tk __-background__ option; and __-pad__, which is
delegated implicitly to the __text__ component, has the same three names for
__mywidget__ as it does for the __[text](../../../../index.md#text)__ widget.
__-borderwidth__, on the other hand, has different resource and class names than
usual, because the internal word "width" isn't capitalized. For consistency, it
should be; this is done as follows:
snit::widget mywidget {
option -background
delegate option {-borderwidth borderWidth} to hull
delegate option * to text
# ...
}
The class name will default to "BorderWidth", as expected.
Suppose, however, that __mywidget__ also delegated __-padx__ and __-pady__ to
the hull. In this case, both the resource name and the class name must be
specified explicitly:
snit::widget mywidget {
option -background
delegate option {-borderwidth borderWidth} to hull
delegate option {-padx padX Pad} to hull
delegate option {-pady padY Pad} to hull
delegate option * to text
# ...
}
__Querying the option database:__ If you set your widgetclass and option names
as described above, Snit will query the option database when each instance is
created, and will generally do the right thing when it comes to querying the
option database. The remainder of this section goes into the gory details.
__Initializing locally defined options:__ When an instance of a snit::widget is
created, its locally defined options are initialized as follows: each option's
resource and class names are used to query the Tk option database. If the result
is non-empty, it is used as the option's default; otherwise, the default
hardcoded in the type definition is used. In either case, the default can be
overridden by the caller. For example,
option add *Mywidget.texture pebbled
snit::widget mywidget {
option -texture smooth
# ...
}
mywidget .mywidget -texture greasy
Here, __-texture__ would normally default to "smooth", but because of the entry
added to the option database it defaults to "pebbled". However, the caller has
explicitly overridden the default, and so the new widget will be "greasy".
__Initializing options delegated to the hull:__ A __snit::widget__'s hull is a
widget, and given that its class has been set it is expected to query the option
database for itself. The only exception concerns options that are delegated to
it with a different name. Consider the following code:
option add *Mywidget.borderWidth 5
option add *Mywidget.relief sunken
option add *Mywidget.hullbackground red
option add *Mywidget.background green
snit::widget mywidget {
delegate option -borderwidth to hull
delegate option -hullbackground to hull as -background
delegate option * to hull
# ...
}
mywidget .mywidget
set A [.mywidget cget -relief]
set B [.mywidget cget -hullbackground]
set C [.mywidget cget -background]
set D [.mywidget cget -borderwidth]
The question is, what are the values of variables A, B, C and D?
The value of A is "sunken". The hull is a Tk frame that has been given the
widget class "Mywidget"; it will automatically query the option database and
pick up this value. Since the __-relief__ option is implicitly delegated to the
hull, Snit takes no action.
The value of B is "red". The hull will automatically pick up the value "green"
for its __-background__ option, just as it picked up the __-relief__ value.
However, Snit knows that __-hullbackground__ is mapped to the hull's
__-background__ option; hence, it queries the option database for
__-hullbackground__ and gets "red" and updates the hull accordingly.
The value of C is also "red", because __-background__ is implicitly delegated to
the hull; thus, retrieving it is the same as retrieving __-hullbackground__.
Note that this case is unusual; in practice, __-background__ would probably be
explicitly delegated to some other component.
The value of D is "5", but not for the reason you think. Note that as it is
defined above, the resource name for __-borderwidth__ defaults to "borderwidth",
whereas the option database entry is "borderWidth". As with __-relief__, the
hull picks up its own __-borderwidth__ option before Snit does anything. Because
the option is delegated under its own name, Snit assumes that the correct thing
has happened, and doesn't worry about it any further.
For __snit::widgetadaptor__s, the case is somewhat altered. Widget adaptors
retain the widget class of their hull, and the hull is not created automatically
by Snit. Instead, the __snit::widgetadaptor__ must call __installhull__ in its
constructor. The normal way to do this is as follows:
snit::widgetadaptor mywidget {
# ...
constructor {args} {
# ...
installhull using text -foreground white
#
}
#...
}
In this case, the __installhull__ command will create the hull using a command
like this:
set hull [text $win -foreground white]
The hull is a __[text](../../../../index.md#text)__ widget, so its widget class
is "Text". Just as with __snit::widget__ hulls, Snit assumes that it will pick
up all of its normal option values automatically; options delegated from a
different name are initialized from the option database in the same way.
__Initializing options delegated to other components:__ Non-hull components are
matched against the option database in two ways. First, a component widget
remains a widget still, and therefore is initialized from the option database in
the usual way. Second, the option database is queried for all options delegated
to the component, and the component is initialized accordingly--provided that
the __install__ command is used to create it.
Before option database support was added to Snit, the usual way to create a
component was to simply create it in the constructor and assign its command name
to the component variable:
snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
set myComp [text $win.text -foreground black]
}
}
The drawback of this method is that Snit has no opportunity to initialize the
component properly. Hence, the following approach is now used:
snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
install myComp using text $win.text -foreground black
}
}
The __install__ command does the following:
- Builds a list of the options explicitly included in the __install__ command
-- in this case, __-foreground__.
- Queries the option database for all options delegated explicitly to the
named component.
- Creates the component using the specified command, after inserting into it a
list of options and values read from the option database. Thus, the
explicitly included options (__-foreground__) will override anything read
from the option database.
- If the widget definition implicitly delegated options to the component using
__delegate option *__, then Snit calls the newly created component's
__configure__ method to receive a list of all of the component's options.
From this Snit builds a list of options implicitly delegated to the
component that were not explicitly included in the __install__ command. For
all such options, Snit queries the option database and configures the
component accordingly.
__Non-widget components:__ The option database is never queried for
__snit::type__s, since it can only be queried given a Tk widget name. However,
__snit::widget__s can have non-widget components. And if options are delegated
to those components, and if the __install__ command is used to install those
components, then they will be initialized from the option database just as
widget components are.
## <a name='subsection10'></a>Macros and Meta-programming
The __snit::macro__ command enables a certain amount of meta-programming with
Snit classes. For example, suppose you like to define properties: instance
variables that have set/get methods. Your code might look like this:
snit::type dog {
variable mood happy
method getmood {} {
return $mood
}
method setmood {newmood} {
set mood $newmood
}
}
That's nine lines of text per property. Or, you could define the following
__snit::macro__:
snit::macro property {name initValue} {
variable $name $initValue
method get$name {} "return $name"
method set$name {value} "set $name \$value"
}
Note that a __snit::macro__ is just a normal Tcl proc defined in the slave
interpreter used to compile type and widget definitions; as a result, it has
access to all the commands used to define types and widgets.
Given this new macro, you can define a property in one line of code:
snit::type dog {
property mood happy
}
Within a macro, the commands __variable__ and
__[proc](../../../../index.md#proc)__ refer to the Snit type-definition
commands, not the standard Tcl commands. To get the standard Tcl commands, use
___variable__ and ___proc__.
Because a single slave interpreter is used for compiling all Snit types and
widgets in the application, there's the possibility of macro name collisions. If
you're writing a reuseable package using Snit, and you use some
__snit::macro__s, define them in your package namespace:
snit::macro mypkg::property {name initValue} { ... }
snit::type dog {
mypkg::property mood happy
}
This leaves the global namespace open for application authors.
## <a name='subsection11'></a>Validation Types
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__ is used to validate that a Tcl
value is an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
snit::integer validate 5 ;# Does nothing
snit::integer validate 5.0 ;# Throws an error (not an integer!)
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error.
Snit defines a family of validation types, all of which are implemented as
__snit::type__'s. They can be used as is; in addition, their instances serve as
parameterized subtypes. For example, a probability is a number between 0.0 and
1.0 inclusive:
snit::double probability -min 0.0 -max 1.0
The example above creates an instance of __snit::double__--a validation
subtype--called __probability__, which can be used to validate probability
values:
probability validate 0.5 ;# Does nothing
probability validate 7.9 ;# Throws an error
Validation subtypes can be defined explicitly, as in the above example; when a
locally-defined option's __-type__ is specified, they may also be created on the
fly:
snit::enum ::dog::breed -values {mutt retriever sheepdog}
snit::type dog {
# Define subtypes on the fly...
option -breed -type {
snit::enum -values {mutt retriever sheepdog}
}
# Or use predefined subtypes...
option -breed -type ::dog::breed
}
Any object that has a __validate__ method with the semantics described above can
be used as a validation type; see [Defining Validation Types](#subsection12) for
information on how to define new ones.
Snit defines the following validation types:
- <a name='74'></a>__snit::boolean__ __validate__ ?*value*?
- <a name='75'></a>__snit::boolean__ *name*
Validates Tcl boolean values: 1, 0, __on__, __off__, __yes__, __no__,
__true__, __false__. It's possible to define subtypes--that is,
instances--of __snit::boolean__, but as it has no options there's no reason
to do so.
- <a name='76'></a>__snit::double__ __validate__ ?*value*?
- <a name='77'></a>__snit::double__ *name* ?*option* *value*...?
Validates floating-point values. Subtypes may be created with the following
options:
* __-min__ *min*
Specifies a floating-point minimum bound; a value is invalid if it is
strictly less than *min*.
* __-max__ *max*
Specifies a floating-point maximum bound; a value is invalid if it is
strictly greater than *max*.
- <a name='78'></a>__snit::enum__ __validate__ ?*value*?
- <a name='79'></a>__snit::enum__ *name* ?*option* *value*...?
Validates that a value comes from an enumerated list. The base type is of
little use by itself, as only subtypes actually have an enumerated list to
validate against. Subtypes may be created with the following options:
* __-values__ *list*
Specifies a list of valid values. A value is valid if and only if it's
included in the list.
- <a name='80'></a>__snit::fpixels__ __validate__ ?*value*?
- <a name='81'></a>__snit::fpixels__ *name* ?*option* *value*...?
*Tk programs only.* Validates screen distances, in any of the forms accepted
by __winfo fpixels__. Subtypes may be created with the following options:
* __-min__ *min*
Specifies a minimum bound; a value is invalid if it is strictly less
than *min*. The bound may be expressed in any of the forms accepted by
__winfo fpixels__.
* __-max__ *max*
Specifies a maximum bound; a value is invalid if it is strictly greater
than *max*. The bound may be expressed in any of the forms accepted by
__winfo fpixels__.
- <a name='82'></a>__snit::integer__ __validate__ ?*value*?
- <a name='83'></a>__snit::integer__ *name* ?*option* *value*...?
Validates integer values. Subtypes may be created with the following
options:
* __-min__ *min*
Specifies an integer minimum bound; a value is invalid if it is strictly
less than *min*.
* __-max__ *max*
Specifies an integer maximum bound; a value is invalid if it is strictly
greater than *max*.
- <a name='84'></a>__snit::listtype__ __validate__ ?*value*?
- <a name='85'></a>__snit::listtype__ *name* ?*option* *value*...?
Validates Tcl lists. Subtypes may be created with the following options:
* __-minlen__ *min*
Specifies a minimum list length; the value is invalid if it has fewer
than *min* elements. Defaults to 0.
* __-maxlen__ *max*
Specifies a maximum list length; the value is invalid if it more than
*max* elements.
* __-type__ *type*
Specifies the type of the list elements; *type* must be the name of a
validation type or subtype. In the following example, the value of
__-numbers__ must be a list of integers.
option -numbers -type {snit::listtype -type snit::integer}
Note that this option doesn't support defining new validation subtypes
on the fly; that is, the following code will not work (yet, anyway):
option -numbers -type {
snit::listtype -type {snit::integer -min 5}
}
Instead, define the subtype explicitly:
snit::integer gt4 -min 5
snit::type mytype {
option -numbers -type {snit::listtype -type gt4}
}
- <a name='86'></a>__snit::pixels__ __validate__ ?*value*?
- <a name='87'></a>__snit::pixels__ *name* ?*option* *value*...?
*Tk programs only.* Validates screen distances, in any of the forms accepted
by __winfo pixels__. Subtypes may be created with the following options:
* __-min__ *min*
Specifies a minimum bound; a value is invalid if it is strictly less
than *min*. The bound may be expressed in any of the forms accepted by
__winfo pixels__.
* __-max__ *max*
Specifies a maximum bound; a value is invalid if it is strictly greater
than *max*. The bound may be expressed in any of the forms accepted by
__winfo pixels__.
- <a name='88'></a>__snit::stringtype__ __validate__ ?*value*?
- <a name='89'></a>__snit::stringtype__ *name* ?*option* *value*...?
Validates Tcl strings. The base type is of little use by itself, since very
Tcl value is also a valid string. Subtypes may be created with the following
options:
* __-minlen__ *min*
Specifies a minimum string length; the value is invalid if it has fewer
than *min* characters. Defaults to 0.
* __-maxlen__ *max*
Specifies a maximum string length; the value is invalid if it has more
than *max* characters.
* __-glob__ *pattern*
Specifies a __string match__ pattern; the value is invalid if it doesn't
match the pattern.
* __-regexp__ *regexp*
Specifies a regular expression; the value is invalid if it doesn't match
the regular expression.
* __-nocase__ *flag*
By default, both __-glob__ and __-regexp__ matches are case-sensitive.
If __-nocase__ is set to true, then both __-glob__ and __-regexp__
matches are case-insensitive.
- <a name='90'></a>__snit::window__ __validate__ ?*value*?
- <a name='91'></a>__snit::window__ *name*
*Tk programs only.* Validates Tk window names. The value must cause __winfo
exists__ to return true; otherwise, the value is invalid. It's possible to
define subtypes--that is, instances--of __snit::window__, but as it has no
options at present there's no reason to do so.
## <a name='subsection12'></a>Defining Validation Types
There are three ways to define a new validation type: as a subtype of one of
Snit's validation types, as a validation type command, and as a full-fledged
validation type similar to those provided by Snit. Defining subtypes of Snit's
validation types is described above, under [Validation Types](#subsection11).
The next simplest way to create a new validation type is as a validation type
command. A validation type is simply an object that has a __validate__ method;
the __validate__ method must take one argument, a value, return the value if it
is valid, and throw an error with __-errorcode__ INVALID if the value is
invalid. This can be done with a simple __[proc](../../../../index.md#proc)__.
For example, the __snit::boolean__ validate type could have been implemented
like this:
proc ::snit::boolean {"validate" value} {
if {![string is boolean -strict $value]} {
return -code error -errorcode INVALID "invalid boolean \"$value\", should be one of: 1, 0, ..."
}
return $value
}
A validation type defined in this way cannot be subtyped, of course; but for
many applications this will be sufficient.
Finally, one can define a full-fledged, subtype-able validation type as a
__snit::type__. Here's a skeleton to get you started:
snit::type myinteger {
# First, define any options you'd like to use to define
# subtypes. Give them defaults such that they won't take
# effect if they aren't used, and marked them "read-only".
# After all, you shouldn't be changing their values after
# a subtype is defined.
#
# For example:
option -min -default "" -readonly 1
option -max -default "" -readonly 1
# Next, define a "validate" type method which should do the
# validation in the basic case. This will allow the
# type command to be used as a validation type.
typemethod validate {value} {
if {![string is integer -strict $value]} {
return -code error -errorcode INVALID "invalid value \"$value\", expected integer"
}
return $value
}
# Next, the constructor should validate the subtype options,
# if any. Since they are all readonly, we don't need to worry
# about validating the options on change.
constructor {args} {
# FIRST, get the options
$self configurelist $args
# NEXT, validate them.
# I'll leave this to your imagination.
}
# Next, define a "validate" instance method; its job is to
# validate values for subtypes.
method validate {value} {
# First, call the type method to do the basic validation.
$type validate $value
# Now we know it's a valid integer.
if {("" != $options(-min) && $value < $options(-min)) ||
("" != $options(-max) && $value > $options(-max))} {
# It's out of range; format a detailed message about
# the error, and throw it.
set msg "...."
return -code error -errorcode INVALID $msg
}
# Otherwise, if it's valid just return it.
return $valid
}
}
And now you have a type that can be subtyped.
The file "validate.tcl" in the Snit distribution defines all of Snit's
validation types; you can find the complete implementation for __snit::integer__
and the other types there, to use as examples for your own types.
# <a name='section4'></a>CAVEATS
If you have problems, find bugs, or new ideas you are hereby cordially invited
to submit a report of your problem, bug, or idea as explained in the section
[Bugs, Ideas, Feedback](#section8) below.
Additionally, you might wish to join the Snit mailing list; see
[http://www.wjduquette.com/snit](http://www.wjduquette.com/snit) for details.
One particular area to watch is using __snit::widgetadaptor__ to adapt
megawidgets created by other megawidget packages; correct widget destruction
depends on the order of the <Destroy> bindings. The wisest course is simply not
to do this.
# <a name='section5'></a>KNOWN BUGS
- Error stack traces returned by Snit 1.x are extremely ugly and typically
contain far too much information about Snit internals. The error messages
are much improved in Snit 2.2.
- Also see the Project Trackers as explained in the section [Bugs, Ideas,
Feedback](#section8) below.
# <a name='section6'></a>HISTORY
During the course of developing Notebook (See
[http://www.wjduquette.com/notebook](http://www.wjduquette.com/notebook)), my
Tcl-based personal notebook application, I found I was writing it as a
collection of objects. I wasn't using any particular object-oriented framework;
I was just writing objects in pure Tcl following the guidelines in my Guide to
Object Commands (see
[http://www.wjduquette.com/tcl/objects.html](http://www.wjduquette.com/tcl/objects.html)),
along with a few other tricks I'd picked up since. And though it was working
well, it quickly became tiresome because of the amount of boilerplate code
associated with each new object type.
So that was one thing--tedium is a powerful motivator. But the other thing I
noticed is that I wasn't using inheritance at all, and I wasn't missing it.
Instead, I was using delegation: objects that created other objects and
delegated methods to them.
And I said to myself, "This is getting tedious...there has got to be a better
way." And one afternoon, on a whim, I started working on Snit, an object system
that works the way Tcl works. Snit doesn't support inheritance, but it's great
at delegation, and it makes creating megawidgets easy.
If you have any comments or suggestions (or bug reports!) don't hesitate to send
me e-mail at [[email protected]]([email protected]). In addition, there's a
Snit mailing list; you can find out more about it at the Snit home page (see
[http://www.wjduquette.com/snit](http://www.wjduquette.com/snit)).
# <a name='section7'></a>CREDITS
Snit has been designed and implemented from the very beginning by William H.
Duquette. However, much credit belongs to the following people for using Snit
and providing me with valuable feedback: Rolf Ade, Colin McCormack, Jose
Nazario, Jeff Godfrey, Maurice Diamanti, Egon Pasztor, David S. Cargo, Tom
Krehbiel, Michael Cleverly, Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs,
Brian Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, and Anton Kovalenko.
If I've forgotten anyone, my apologies; let me know and I'll add your name to
the list.
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *snit* 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.
# <a name='keywords'></a>KEYWORDS
[BWidget](../../../../index.md#bwidget), [C++](../../../../index.md#c_), [Incr
Tcl](../../../../index.md#incr_tcl), [Snit](../../../../index.md#snit),
[adaptors](../../../../index.md#adaptors), [class](../../../../index.md#class),
[mega widget](../../../../index.md#mega_widget),
[object](../../../../index.md#object), [object
oriented](../../../../index.md#object_oriented),
[type](../../../../index.md#type), [widget](../../../../index.md#widget),
[widget adaptors](../../../../index.md#widget_adaptors)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2009, by William H. Duquette
|
Added embedded/md/tcllib/files/modules/snit/snitfaq.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
|
[//000000001]: # (snitfaq - Snit's Not Incr Tcl, OO system)
[//000000002]: # (Generated from file 'snitfaq.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (snitfaq(n) 2.2 tcllib "Snit's Not Incr Tcl, OO system")
# NAME
snitfaq - Snit Frequently Asked Questions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [OVERVIEW](#section2)
- [What is this document?](#subsection1)
- [What is Snit?](#subsection2)
- [What version of Tcl does Snit require?](#subsection3)
- [Where can I download Snit?](#subsection4)
- [What are Snit's goals?](#subsection5)
- [How is Snit different from other OO frameworks?](#subsection6)
- [What can I do with Snit?](#subsection7)
- [SNIT VERSIONS](#section3)
- [Which version of Snit should I use?](#subsection8)
- [How do I select the version of Snit I want to use?](#subsection9)
- [How are Snit 1.3 and Snit 2.2 incompatible?](#subsection10)
- [Are there other differences between Snit 1.x and Snit
2.2?](#subsection11)
- [OBJECTS](#section4)
- [What is an object?](#subsection12)
- [What is an abstract data type?](#subsection13)
- [What kinds of abstract data types does Snit provide?](#subsection14)
- [What is a snit::type?](#subsection15)
- [What is a snit::widget?, the short story](#subsection16)
- [What is a snit::widgetadaptor?, the short story](#subsection17)
- [How do I create an instance of a snit::type?](#subsection18)
- [How do I refer to an object indirectly?](#subsection19)
- [How can I generate the object name automatically?](#subsection20)
- [Can types be renamed?](#subsection21)
- [Can objects be renamed?](#subsection22)
- [How do I destroy a Snit object?](#subsection23)
- [INSTANCE METHODS](#section5)
- [What is an instance method?](#subsection24)
- [How do I define an instance method?](#subsection25)
- [How does a client call an instance method?](#subsection26)
- [How does an instance method call another instance
method?](#subsection27)
- [Are there any limitations on instance method names?](#subsection28)
- [What is a hierarchical method?](#subsection29)
- [How do I define a hierarchical method?](#subsection30)
- [How do I call hierarchical methods?](#subsection31)
- [How do I make an instance method private?](#subsection32)
- [Are there any limitations on instance method
arguments?](#subsection33)
- [What implicit arguments are passed to each instance
method?](#subsection34)
- [What is $type?](#subsection35)
- [What is $self?](#subsection36)
- [What is $selfns?](#subsection37)
- [What is $win?](#subsection38)
- [How do I pass an instance method as a callback?](#subsection39)
- [How do I delegate instance methods to a component?](#subsection40)
- [INSTANCE VARIABLES](#section6)
- [What is an instance variable?](#subsection41)
- [How is a scalar instance variable defined?](#subsection42)
- [How is an array instance variable defined?](#subsection43)
- [What happens if I don't initialize an instance
variable?](#subsection44)
- [Are there any limitations on instance variable names?](#subsection45)
- [Do I need to declare my instance variables in my
methods?](#subsection46)
- [How do I pass an instance variable's name to another
object?](#subsection47)
- [How do I make an instance variable public?](#subsection48)
- [OPTIONS](#section7)
- [What is an option?](#subsection49)
- [How do I define an option?](#subsection50)
- [How can a client set options at object creation?](#subsection51)
- [How can a client retrieve an option's value?](#subsection52)
- [How can a client set options after object creation?](#subsection53)
- [How should an instance method access an option value?](#subsection54)
- [How can I make an option read-only?](#subsection55)
- [How can I catch accesses to an option's value?](#subsection56)
- [What is a -cgetmethod?](#subsection57)
- [How can I catch changes to an option's value?](#subsection58)
- [What is a -configuremethod?](#subsection59)
- [How can I validate an option's value?](#subsection60)
- [What is a -validatemethod?](#subsection61)
- [TYPE VARIABLES](#section8)
- [What is a type variable?](#subsection62)
- [How is a scalar type variable defined?](#subsection63)
- [How is an array-valued type variable defined?](#subsection64)
- [What happens if I don't initialize a type variable?](#subsection65)
- [Are there any limitations on type variable names?](#subsection66)
- [Do I need to declare my type variables in my methods?](#subsection67)
- [How do I pass a type variable's name to another
object?](#subsection68)
- [How do I make a type variable public?](#subsection69)
- [TYPE METHODS](#section9)
- [What is a type method?](#subsection70)
- [How do I define a type method?](#subsection71)
- [How does a client call a type method?](#subsection72)
- [Are there any limitations on type method names?](#subsection73)
- [How do I make a type method private?](#subsection74)
- [Are there any limitations on type method arguments?](#subsection75)
- [How does an instance or type method call a type
method?](#subsection76)
- [How do I pass a type method as a callback?](#subsection77)
- [Can type methods be hierarchical?](#subsection78)
- [PROCS](#section10)
- [What is a proc?](#subsection79)
- [How do I define a proc?](#subsection80)
- [Are there any limitations on proc names?](#subsection81)
- [How does a method call a proc?](#subsection82)
- [How can I pass a proc to another object as a callback?](#subsection83)
- [TYPE CONSTRUCTORS](#section11)
- [What is a type constructor?](#subsection84)
- [How do I define a type constructor?](#subsection85)
- [CONSTRUCTORS](#section12)
- [What is a constructor?](#subsection86)
- [How do I define a constructor?](#subsection87)
- [What does the default constructor do?](#subsection88)
- [Can I choose a different set of arguments for the
constructor?](#subsection89)
- [Are there any limitations on constructor arguments?](#subsection90)
- [Is there anything special about writing the
constructor?](#subsection91)
- [DESTRUCTORS](#section13)
- [What is a destructor?](#subsection92)
- [How do I define a destructor?](#subsection93)
- [Are there any limitations on destructor arguments?](#subsection94)
- [What implicit arguments are passed to the destructor?](#subsection95)
- [Must components be destroyed explicitly?](#subsection96)
- [Is there any special about writing a destructor?](#subsection97)
- [COMPONENTS](#section14)
- [What is a component?](#subsection98)
- [How do I declare a component?](#subsection99)
- [How is a component named?](#subsection100)
- [Are there any limitations on component names?](#subsection101)
- [What is an owned component?](#subsection102)
- [What does the install command do?](#subsection103)
- [Must owned components be created in the constructor?](#subsection104)
- [Are there any limitations on component object names?](#subsection105)
- [Must I destroy the components I own?](#subsection106)
- [Can I expose a component's object command as part of my
interface?](#subsection107)
- [How do I expose a component's object command?](#subsection108)
- [TYPE COMPONENTS](#section15)
- [What is a type component?](#subsection109)
- [How do I declare a type component?](#subsection110)
- [How do I install a type component?](#subsection111)
- [Are there any limitations on type component names?](#subsection112)
- [DELEGATION](#section16)
- [What is delegation?](#subsection113)
- [How can I delegate a method to a component object?](#subsection114)
- [Can I delegate to a method with a different name?](#subsection115)
- [Can I delegate to a method with additional arguments?](#subsection116)
- [Can I delegate a method to something other than an
object?](#subsection117)
- [How can I delegate a method to a type component
object?](#subsection118)
- [How can I delegate a type method to a type component
object?](#subsection119)
- [How can I delegate an option to a component object?](#subsection120)
- [Can I delegate to an option with a different name?](#subsection121)
- [How can I delegate any unrecognized method or option to a component
object?](#subsection122)
- [How can I delegate all but certain methods or options to a
component?](#subsection123)
- [Can a hierarchical method be delegated?](#subsection124)
- [WIDGETS](#section17)
- [What is a snit::widget?](#subsection125)
- [How do I define a snit::widget?](#subsection126)
- [How do snit::widgets differ from snit::types?](#subsection127)
- [What is a hull component?](#subsection128)
- [How can I set the hull type for a snit::widget?](#subsection129)
- [How should I name widgets which are components of a
snit::widget?](#subsection130)
- [WIDGET ADAPTORS](#section18)
- [What is a snit::widgetadaptor?](#subsection131)
- [How do I define a snit::widgetadaptor?](#subsection132)
- [Can I adapt a widget created elsewhere in the
program?](#subsection133)
- [Can I adapt another megawidget?](#subsection134)
- [THE TK OPTION DATABASE](#section19)
- [What is the Tk option database?](#subsection135)
- [Do snit::types use the Tk option database?](#subsection136)
- [What is my snit::widget's widget class?](#subsection137)
- [What is my snit::widgetadaptor's widget class?](#subsection138)
- [What are option resource and class names?](#subsection139)
- [What are the resource and class names for my megawidget's
options?](#subsection140)
- [How does Snit initialize my megawidget's locally-defined
options?](#subsection141)
- [How does Snit initialize delegated options?](#subsection142)
- [How does Snit initialize options delegated to the
hull?](#subsection143)
- [How does Snit initialize options delegated to other
components?](#subsection144)
- [What happens if I install a non-widget as a component of
widget?](#subsection145)
- [ENSEMBLE COMMANDS](#section20)
- [What is an ensemble command?](#subsection146)
- [How can I create an ensemble command using Snit?](#subsection147)
- [How can I create an ensemble command using an instance of a
snit::type?](#subsection148)
- [How can I create an ensemble command using a
snit::type?](#subsection149)
- [PRAGMAS](#section21)
- [What is a pragma?](#subsection150)
- [How do I set a pragma?](#subsection151)
- [How can I get rid of the "info" type method?](#subsection152)
- [How can I get rid of the "destroy" type method?](#subsection153)
- [How can I get rid of the "create" type method?](#subsection154)
- [How can I get rid of type methods altogether?](#subsection155)
- [Why can't I create an object that replaces an old object with the same
name?](#subsection156)
- [How can I make my simple type run faster?](#subsection157)
- [MACROS](#section22)
- [What is a macro?](#subsection158)
- [What are macros good for?](#subsection159)
- [How do I do conditional compilation?](#subsection160)
- [How do I define new type definition syntax?](#subsection161)
- [Are there are restrictions on macro names?](#subsection162)
- [Bugs, Ideas, Feedback](#section23)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>OVERVIEW
## <a name='subsection1'></a>What is this document?
This is an atypical FAQ list, in that few of the questions are frequently asked.
Rather, these are the questions I think a newcomer to Snit should be asking.
This file is not a complete reference to Snit, however; that information is in
the __[snit](snit.md)__ man page.
## <a name='subsection2'></a>What is Snit?
Snit is a framework for defining abstract data types and megawidgets in pure
Tcl. The name "Snit" stands for "Snit's Not Incr Tcl", signifying that Snit
takes a different approach to defining objects than does Incr Tcl, the best
known object framework for Tcl. Had I realized that Snit would become at all
popular, I'd probably have chosen something else.
The primary purpose of Snit is to be *object glue*--to help you compose diverse
objects from diverse sources into types and megawidgets with clean, convenient
interfaces so that you can more easily build your application.
Snit isn't about theoretical purity or minimalist design; it's about being able
to do powerful things easily and consistently without having to think about
them--so that you can concentrate on building your application.
Snit isn't about implementing thousands of nearly identical carefully-specified
lightweight thingamajigs--not as individual Snit objects. Traditional Tcl
methods will be much faster, and not much more complicated. But Snit *is* about
implementing a clean interface to manage a collection of thousands of nearly
identical carefully-specified lightweight thingamajigs (e.g., think of the text
widget and text tags, or the canvas widget and canvas objects). Snit lets you
hide the details of just how those thingamajigs are stored--so that you can
ignore it, and concentrate on building your application.
Snit isn't a way of life, a silver bullet, or the Fountain of Youth. It's just a
way of managing complexity--and of managing some of the complexity of managing
complexity--so that you can concentrate on building your application.
## <a name='subsection3'></a>What version of Tcl does Snit require?
Snit 1.3 requires Tcl 8.3 or later; Snit 2.2 requires Tcl 8.5 or later. See
[SNIT VERSIONS](#section3) for the differences between Snit 1.3 and Snit 2.2.
## <a name='subsection4'></a>Where can I download Snit?
Snit is part of Tcllib, the standard Tcl library, so you might already have it.
It's also available at the Snit Home Page,
[http://www.wjduquette.com/snit](http://www.wjduquette.com/snit).
## <a name='subsection5'></a>What are Snit's goals?
- A Snit object should be at least as efficient as a hand-coded Tcl object
(see
[http://www.wjduquette.com/tcl/objects.html](http://www.wjduquette.com/tcl/objects.html)).
- The fact that Snit was used in an object's implementation should be
transparent (and irrelevant) to clients of that object.
- Snit should be able to encapsulate objects from other sources, particularly
Tk widgets.
- Snit megawidgets should be (to the extent possible) indistinguishable in
interface from Tk widgets.
- Snit should be Tclish--that is, rather than trying to emulate C++,
Smalltalk, or anything else, it should try to emulate Tcl itself.
- It should have a simple, easy-to-use, easy-to-remember syntax.
## <a name='subsection6'></a>How is Snit different from other OO frameworks?
Snit is unique among Tcl object systems in that it is based not on inheritance
but on delegation. Object systems based on inheritance only allow you to inherit
from classes defined using the same system, and that's a shame. In Tcl, an
object is anything that acts like an object; it shouldn't matter how the object
was implemented. I designed Snit to help me build applications out of the
materials at hand; thus, Snit is designed to be able to incorporate and build on
any object, whether it's a hand-coded object, a Tk widget, an Incr Tcl object, a
BWidget or almost anything else.
Note that you can achieve the effect of inheritance using
[COMPONENTS](#section14) and [DELEGATION](#section16)--and you can inherit from
anything that looks like a Tcl object.
## <a name='subsection7'></a>What can I do with Snit?
Using Snit, a programmer can:
- Create abstract data types and Tk megawidgets.
- Define instance variables, type variables, and Tk-style options.
- Define constructors, destructors, instance methods, type methods, procs.
- Assemble a type out of component types. Instance methods and options can be
delegated to the component types automatically.
# <a name='section3'></a>SNIT VERSIONS
## <a name='subsection8'></a>Which version of Snit should I use?
The current Snit distribution includes two versions, Snit 1.3 and Snit 2.2. The
reason that both are included is that Snit 2.2 takes advantage of a number of
new features of Tcl 8.5 to improve run-time efficiency; as a side-effect, the
ugliness of Snit's error messages and stack traces has been reduced
considerably. The cost of using Snit 2.2, of course, is that you must target Tcl
8.5.
Snit 1.3, on the other hand, lacks Snit 2.2's optimizations, but requires only
Tcl 8.3 and later.
In short, if you're targetting Tcl 8.3 or 8.4 you should use Snit 1.3. If you
can afford to target Tcl 8.5, you should definitely use Snit 2.2. If you will be
targetting both, you can use Snit 1.3 exclusively, or (if your code is
unaffected by the minor incompatibilities between the two versions) you can use
Snit 1.3 for Tcl 8.4 and Snit 2.2 for Tcl 8.5.
## <a name='subsection9'></a>How do I select the version of Snit I want to use?
To always use Snit 1.3 (or a later version of Snit 1.x), invoke Snit as follows:
package require snit 1.3
To always use Snit 2.2 (or a later version of Snit 2.x), say this instead:
package require snit 2.2
Note that if you request Snit 2.2 explicitly, your application will halt with
Tcl 8.4, since Snit 2.2 is unavailable for Tcl 8.4.
If you wish your application to always use the latest available version of Snit,
don't specify a version number:
package require snit
Tcl will find and load the latest version that's available relative to the
version of Tcl being used. In this case, be careful to avoid using any
incompatible features.
## <a name='subsection10'></a>How are Snit 1.3 and Snit 2.2 incompatible?
To the extent possible, Snit 2.2 is intended to be a drop-in replacement for
Snit 1.3. Unfortunately, some incompatibilities were inevitable because Snit 2.2
uses Tcl 8.5's new __namespace ensemble__ mechanism to implement subcommand
dispatch. This approach is much faster than the mechanism used in Snit 1.3, and
also results in much better error messages; however, it also places new
constraints on the implementation.
There are four specific incompatibilities between Snit 1.3 and Snit 2.2.
- Snit 1.3 supports implicit naming of objects. Suppose you define a new
__snit::type__ called __dog__. You can create instances of __dog__ in three
ways:
dog spot ;# Explicit naming
set obj1 [dog %AUTO%] ;# Automatic naming
set obj2 [dog] ;# Implicit naming
In Snit 2.2, type commands are defined using the __namespace ensemble__
mechanism; and __namespace ensemble__ doesn't allow an ensemble command to
be called without a subcommand. In short, using __namespace ensemble__
there's no way to support implicit naming.
All is not lost, however. If the type has no type methods, then the type
command is a simple command rather than an ensemble, and __namespace
ensemble__ is not used. In this case, implicit naming is still possible.
In short, you can have implicit naming if you're willing to do without type
methods (including the standard type methods, like __$type info__). To do
so, use the __-hastypemethods__ pragma:
pragma -hastypemethods 0
- Hierarchical methods and type methods are implemented differently in Snit
2.2.
A hierarchical method is an instance method which has subcommands; these
subcommands are themselves methods. The Tk text widget's __tag__ command and
its subcommands are examples of hierarchical methods. You can implement such
subcommands in Snit simply by including multiple words in the method names:
method {tag configure} {tag args} { ... }
method {tag cget} {tag option} {...}
Here we've implicitly defined a __tag__ method which has two subcommands,
__configure__ and __cget__.
In Snit 1.3, hierarchical methods could be called in two ways:
$obj tag cget -myoption ;# The good way
$obj {tag cget} -myoption ;# The weird way
In the second call, we see that a hierarchical method or type method is
simply one whose name contains multiple words.
In Snit 2.2 this is no longer the case, and the "weird" way of calling
hierarchical methods and type methods no longer works.
- The third incompatibility derives from the second. In Snit 1.3, hierarchical
methods were also simply methods whose name contains multiple words. As a
result, __$obj info methods__ returned the full names of all hierarchical
methods. In the example above, the list returned by __$obj info methods__
would include __tag configure__ and __tag cget__ but not __tag__, since
__tag__ is defined only implicitly.
In Snit 2.2, hierarchical methods and type methods are no longer simply ones
whose name contains multiple words; in the above example, the list returned
by __$obj info methods__ would include __tag__ but not __tag configure__ or
__tag cget__.
- The fourth incompatibility is due to a new feature. Snit 2.2 uses the new
__namespace path__ command so that a type's code can call any command
defined in the type's parent namespace without qualification or importation.
For example, suppose you have a package called __mypackage__ which defines a
number of commands including a type, __::mypackage::mytype__. Thanks to
__namespace path__, the type's code can call any of the other commands
defined in __::mypackage::__.
This is extremely convenient. However, it also means that commands defined
in the parent namespace, __::mypackage::__ can block the type's access to
identically named commands in the global namespace. This can lead to bugs.
For example, Tcllib includes a type called __::tie::std::file__. This type's
code calls the standard __[file](../../../../index.md#file)__ command. When
run with Snit 2.2, the code broke-- the type's command,
__::tie::std::file__, is itself a command in the type's parent namespace,
and so instead of calling the standard __[file](../../../../index.md#file)__
command, the type found itself calling itself.
## <a name='subsection11'></a>Are there other differences between Snit 1.x and Snit 2.2?
Yes.
- Method dispatch is considerably faster.
- Many error messages and stack traces are cleaner.
- The __-simpledispatch__ pragma is obsolete, and ignored if present. In Snit
1.x, __-simpledispatch__ substitutes a faster mechanism for method dispatch,
at the cost of losing certain features. Snit 2.2 method dispatch is faster
still in all cases, so __-simpledispatch__ is no longer needed.
- In Snit 2.2, a type's code (methods, type methods, etc.) can call commands
from the type's parent namespace without qualifying or importing them, i.e.,
type __::parentns::mytype__'s code can call __::parentns::someproc__ as just
__someproc__.
This is extremely useful when a type is defined as part of a larger package,
and shares a parent namespace with the rest of the package; it means that
the type can call other commands defined by the package without any extra
work.
This feature depends on the new Tcl 8.5 __namespace path__ command, which is
why it hasn't been implemented for V1.x. V1.x code can achieve something
similar by placing
namespace import [namespace parent]::*
in a type constructor. This is less useful, however, as it picks up only
those commands which have already been exported by the parent namespace at
the time the type is defined.
# <a name='section4'></a>OBJECTS
## <a name='subsection12'></a>What is an object?
A full description of object-oriented programming is beyond the scope of this
FAQ, obviously. In simple terms, an object is an instance of an abstract data
type--a coherent bundle of code and data. There are many ways to represent
objects in Tcl/Tk; the best known examples are the Tk widgets.
A Tk widget is an object; it is represented by a Tcl command. The object's
methods are subcommands of the Tcl command. The object's properties are options
accessed using the __configure__ and __cget__ methods. Snit uses the same
conventions as Tk widgets do.
## <a name='subsection13'></a>What is an abstract data type?
In computer science terms, an abstract data type is a complex data structure
along with a set of operations--a stack, a queue, a binary tree, etc--that is to
say, in modern terms, an object. In systems that include some form of
inheritance the word *[class](../../../../index.md#class)* is usually used
instead of *abstract data type*, but as Snit doesn't implement inheritance as
it's ordinarily understood the older term seems more appropriate. Sometimes this
is called *object-based* programming as opposed to object-oriented programming.
Note that you can easily create the effect of inheritance using
[COMPONENTS](#section14) and [DELEGATION](#section16).
In Snit, as in Tk, a *[type](../../../../index.md#type)* is a command that
creates instances -- objects -- which belong to the type. Most types define some
number of *options* which can be set at creation time, and usually can be
changed later.
Further, an *instance* is also a Tcl command--a command that gives access to the
operations which are defined for that abstract data type. Conventionally, the
operations are defined as subcommands of the instance command. For example, to
insert text into a Tk text widget, you use the text widget's __insert__
subcommand:
# Create a text widget and insert some text in it.
text .mytext -width 80 -height 24
.mytext insert end "Howdy!"
In this example, __[text](../../../../index.md#text)__ is the
*[type](../../../../index.md#type)* command and __.mytext__ is the *instance*
command.
In Snit, object subcommands are generally called [INSTANCE METHODS](#section5).
## <a name='subsection14'></a>What kinds of abstract data types does Snit provide?
Snit allows you to define three kinds of abstract data type:
- __snit::type__
- __snit::widget__
- __snit::widgetadaptor__
## <a name='subsection15'></a>What is a snit::type?
A __snit::type__ is a non-GUI abstract data type, e.g., a stack or a queue.
__snit::type__s are defined using the __snit::type__ command. For example, if
you were designing a kennel management system for a dog breeder, you'd need a
dog type.
% snit::type dog {
# ...
}
::dog
%
This definition defines a new command (__::dog__, in this case) that can be used
to define dog objects.
An instance of a __snit::type__ can have [INSTANCE METHODS](#section5),
[INSTANCE VARIABLES](#section6), [OPTIONS](#section7), and
[COMPONENTS](#section14). The type itself can have [TYPE METHODS](#section9),
[TYPE VARIABLES](#section8), [TYPE COMPONENTS](#section15), and
[PROCS](#section10).
## <a name='subsection16'></a>What is a snit::widget?, the short story
A __snit::widget__ is a Tk megawidget built using Snit; it is very similar to a
__snit::type__. See [WIDGETS](#section17).
## <a name='subsection17'></a>What is a snit::widgetadaptor?, the short story
A __snit::widgetadaptor__ uses Snit to wrap an existing widget type (e.g., a Tk
label), modifying its interface to a lesser or greater extent. It is very
similar to a __snit::widget__. See [WIDGET ADAPTORS](#section18).
## <a name='subsection18'></a>How do I create an instance of a snit::type?
You create an instance of a __snit::type__ by passing the new instance's name to
the type's create method. In the following example, we create a __dog__ object
called __spot__.
% snit::type dog {
# ....
}
::dog
% dog create spot
::spot
%
In general, the __create__ method name can be omitted so long as the instance
name doesn't conflict with any defined [TYPE METHODS](#section9). (See [TYPE
COMPONENTS](#section15) for the special case in which this doesn't work.) So the
following example is identical to the previous example:
% snit::type dog {
# ....
}
::dog
% dog spot
::spot
%
This document generally uses the shorter form.
If the __dog__ type defines [OPTIONS](#section7), these can usually be given
defaults at creation time:
% snit::type dog {
option -breed mongrel
option -color brown
method bark {} { return "$self barks." }
}
::dog
% dog create spot -breed dalmation -color spotted
::spot
% spot cget -breed
dalmation
% spot cget -color
spotted
%
Once created, the instance name now names a new Tcl command that is used to
manipulate the object. For example, the following code makes the dog bark:
% spot bark
::spot barks.
%
## <a name='subsection19'></a>How do I refer to an object indirectly?
Some programmers prefer to save the object name in a variable, and reference it
that way. For example,
% snit::type dog { ... }
::dog
% set d [dog spot -breed dalmation -color spotted]
::spot
% $d cget -breed
dalmation
% $d bark
::spot barks.
%
If you prefer this style, you might prefer to have Snit generate the instance's
name automatically.
## <a name='subsection20'></a>How can I generate the object name automatically?
If you'd like Snit to generate an object name for you, use the __%AUTO%__
keyword as the requested name:
% snit::type dog { ... }
::dog
% set d [dog %AUTO%]
::dog2
% $d bark
::dog2 barks.
%
The __%AUTO%__ keyword can be embedded in a longer string:
% set d [dog obj_%AUTO%]
::obj_dog4
% $d bark
::obj_dog4 barks.
%
## <a name='subsection21'></a>Can types be renamed?
Tcl's __rename__ command renames other commands. It's a common technique in Tcl
to modify an existing command by renaming it and defining a new command with the
original name; the new command usually calls the renamed command.
__snit::type__ commands, however, should never be renamed; to do so breaks the
connection between the type and its objects.
## <a name='subsection22'></a>Can objects be renamed?
Tcl's __rename__ command renames other commands. It's a common technique in Tcl
to modify an existing command by renaming it and defining a new command with the
original name; the new command usually calls the renamed command.
All Snit objects (including *widgets* and *widgetadaptors*) can be renamed,
though this flexibility has some consequences:
- In an instance method, the implicit argument __self__ will always contain
the object's current name, so instance methods can always call other
instance methods using __$self__.
- If the object is renamed, however, then __$self__'s value will change.
Therefore, don't use __$self__ for anything that will break if __$self__
changes. For example, don't pass a callback command to another object like
this:
.btn configure -command [list $self ButtonPress]
You'll get an error if __.btn__ calls your command after your object is
renamed.
- Instead, your object should define its callback command like this:
.btn configure -command [mymethod ButtonPress]
The __mymethod__ command returns code that will call the desired method
safely; the caller of the callback can add additional arguments to the end
of the command as usual.
- Every object has a private namespace; the name of this namespace is
available in method bodies, etc., as the value of the implicit argument
__selfns__. This value is constant for the life of the object. Use
__$selfns__ instead of __$self__ if you need a unique token to identify the
object.
- When a __snit::widget__'s instance command is renamed, its Tk window name
remains the same -- and is still extremely important. Consequently, the Tk
window name is available in method bodies as the value of the implicit
argument __win__. This value is constant for the life of the object. When
creating child windows, it's best to use __$win.child__ rather than
__$self.child__ as the name of the child window.
## <a name='subsection23'></a>How do I destroy a Snit object?
Any Snit object of any type can be destroyed by renaming it to the empty string
using the Tcl __rename__ command.
Snit megawidgets (i.e., instances of __snit::widget__ and
__snit::widgetadaptor__) can be destroyed like any other widget: by using the Tk
__destroy__ command on the widget or on one of its ancestors in the window
hierarchy.
Every instance of a __snit::type__ has a __destroy__ method:
% snit::type dog { ... }
::dog
% dog spot
::spot
% spot bark
::spot barks.
% spot destroy
% spot barks
invalid command name "spot"
%
Finally, every Snit type has a type method called __destroy__; calling it
destroys the type and all of its instances:
% snit::type dog { ... }
::dog
% dog spot
::spot
% spot bark
::spot barks.
% dog destroy
% spot bark
invalid command name "spot"
% dog fido
invalid command name "dog"
%
# <a name='section5'></a>INSTANCE METHODS
## <a name='subsection24'></a>What is an instance method?
An instance method is a procedure associated with a specific object and called
as a subcommand of the object's command. It is given free access to all of the
object's type variables, instance variables, and so forth.
## <a name='subsection25'></a>How do I define an instance method?
Instance methods are defined in the type definition using the
__[method](../../../../index.md#method)__ statement. Consider the following code
that might be used to add dogs to a computer simulation:
% snit::type dog {
method bark {} {
return "$self barks."
}
method chase {thing} {
return "$self chases $thing."
}
}
::dog
%
A dog can bark, and it can chase things.
The __[method](../../../../index.md#method)__ statement looks just like a normal
Tcl __[proc](../../../../index.md#proc)__, except that it appears in a
__snit::type__ definition. Notice that every instance method gets an implicit
argument called __self__; this argument contains the object's name. (There's
more on implicit method arguments below.)
## <a name='subsection26'></a>How does a client call an instance method?
The method name becomes a subcommand of the object. For example, let's put a
simulated dog through its paces:
% dog spot
::spot
% spot bark
::spot barks.
% spot chase cat
::spot chases cat.
%
## <a name='subsection27'></a>How does an instance method call another instance method?
If method A needs to call method B on the same object, it does so just as a
client does: it calls method B as a subcommand of the object itself, using the
object name stored in the implicit argument __self__.
Suppose, for example, that our dogs never chase anything without barking at
them:
% snit::type dog {
method bark {} {
return "$self barks."
}
method chase {thing} {
return "$self chases $thing. [$self bark]"
}
}
::dog
% dog spot
::spot
% spot bark
::spot barks.
% spot chase cat
::spot chases cat. ::spot barks.
%
## <a name='subsection28'></a>Are there any limitations on instance method names?
Not really, so long as you avoid the standard instance method names:
__configure__, __configurelist__, __cget__, __destroy__, and __info__. Also,
method names consisting of multiple words define hierarchical methods.
## <a name='subsection29'></a>What is a hierarchical method?
An object's methods are subcommands of the object's instance command.
Hierarchical methods allow an object's methods to have subcommands of their own;
and these can in turn have subcommands, and so on. This allows the programmer to
define a tree-shaped command structure, such as is used by many of the Tk
widgets--the subcommands of the Tk __[text](../../../../index.md#text)__
widget's __tag__ method are hierarchical methods.
## <a name='subsection30'></a>How do I define a hierarchical method?
Define methods whose names consist of multiple words. These words define the
hierarchy implicitly. For example, the following code defines a __tag__ method
with subcommands __cget__ and __configure__:
snit::widget mytext {
method {tag configure} {tag args} { ... }
method {tag cget} {tag option} {...}
}
Note that there is no explicit definition for the __tag__ method; it is implicit
in the definition of __tag configure__ and __tag cget__. If you tried to define
__tag__ explicitly in this example, you'd get an error.
## <a name='subsection31'></a>How do I call hierarchical methods?
As subcommands of subcommands.
% mytext .text
.text
% .text tag configure redtext -foreground red -background black
% .text tag cget redtext -foreground
red
%
## <a name='subsection32'></a>How do I make an instance method private?
It's often useful to define private methods, that is, instance methods intended
to be called only by other methods of the same object.
Snit doesn't implement any access control on instance methods, so all methods
are *de facto* public. Conventionally, though, the names of public methods begin
with a lower-case letter, and the names of private methods begin with an
upper-case letter.
For example, suppose our simulated dogs only bark in response to other stimuli;
they never bark just for fun. So the __bark__ method becomes __Bark__ to
indicate that it is private:
% snit::type dog {
# Private by convention: begins with uppercase letter.
method Bark {} {
return "$self barks."
}
method chase {thing} {
return "$self chases $thing. [$self Bark]"
}
}
::dog
% dog fido
::fido
% fido chase cat
::fido chases cat. ::fido barks.
%
## <a name='subsection33'></a>Are there any limitations on instance method arguments?
Method argument lists are defined just like normal Tcl
__[proc](../../../../index.md#proc)__ argument lists; in particular, they can
include arguments with default values and the __args__ argument.
However, every method also has a number of implicit arguments provided by Snit
in addition to those explicitly defined. The names of these implicit arguments
may not used to name explicit arguments.
## <a name='subsection34'></a>What implicit arguments are passed to each instance method?
The arguments implicitly passed to every method are __type__, __selfns__,
__win__, and __self__.
## <a name='subsection35'></a>What is $type?
The implicit argument __type__ contains the fully qualified name of the object's
type:
% snit::type thing {
method mytype {} {
return $type
}
}
::thing
% thing something
::something
% something mytype
::thing
%
## <a name='subsection36'></a>What is $self?
The implicit argument __self__ contains the object's fully qualified name.
If the object's command is renamed, then __$self__ will change to match in
subsequent calls. Thus, your code should not assume that __$self__ is constant
unless you know for sure that the object will never be renamed.
% snit::type thing {
method myself {} {
return $self
}
}
::thing
% thing mutt
::mutt
% mutt myself
::mutt
% rename mutt jeff
% jeff myself
::jeff
%
## <a name='subsection37'></a>What is $selfns?
Each Snit object has a private namespace in which to store its [INSTANCE
VARIABLES](#section6) and [OPTIONS](#section7). The implicit argument __selfns__
contains the name of this namespace; its value never changes, and is constant
for the life of the object, even if the object's name changes:
% snit::type thing {
method myNameSpace {} {
return $selfns
}
}
::thing
% thing jeff
::jeff
% jeff myNameSpace
::thing::Snit_inst3
% rename jeff mutt
% mutt myNameSpace
::thing::Snit_inst3
%
The above example reveals how Snit names an instance's private namespace;
however, you should not write code that depends on the specific naming
convention, as it might change in future releases.
## <a name='subsection38'></a>What is $win?
The implicit argument __win__ is defined for all Snit methods, though it really
makes sense only for those of [WIDGETS](#section17) and [WIDGET
ADAPTORS](#section18). __$win__ is simply the original name of the object,
whether it's been renamed or not. For widgets and widgetadaptors, it is also
therefore the name of a Tk window.
When a __snit::widgetadaptor__ is used to modify the interface of a widget or
megawidget, it must rename the widget's original command and replace it with its
own.
Thus, using __win__ whenever the Tk window name is called for means that a
__snit::widget__ or __snit::widgetadaptor__ can be adapted by a
__snit::widgetadaptor__. See [WIDGETS](#section17) for more information.
## <a name='subsection39'></a>How do I pass an instance method as a callback?
It depends on the context.
Suppose in my application I have a __dog__ object named __fido__, and I want
__fido__ to bark when a Tk button called __.bark__ is pressed. In this case, I
create the callback command in the usual way, using
__[list](../../../../index.md#list)__:
button .bark -text "Bark!" -command [list fido bark]
In typical Tcl style, we use a callback to hook two independent components
together. But suppose that the __dog__ object has a graphical interface and owns
the button itself? In this case, the __dog__ must pass one of its own instance
methods to the button it owns. The obvious thing to do is this:
% snit::widget dog {
constructor {args} {
#...
button $win.barkbtn -text "Bark!" -command [list $self bark]
#...
}
}
::dog
%
(Note that in this example, our __dog__ becomes a __snit::widget__, because it
has GUI behavior. See [WIDGETS](#section17) for more.) Thus, if we create a
__dog__ called __.spot__, it will create a Tk button called __.spot.barkbtn__;
when pressed, the button will call __$self bark__.
Now, this will work--provided that __.spot__ is never renamed to something else.
But surely renaming widgets is abnormal? And so it is--unless __.spot__ is the
hull component of a __snit::widgetadaptor__. If it is, then it will be renamed,
and __.spot__ will become the name of the __snit::widgetadaptor__ object. When
the button is pressed, the command __$self bark__ will be handled by the
__snit::widgetadaptor__, which might or might not do the right thing.
There's a safer way to do it, and it looks like this:
% snit::widget dog {
constructor {args} {
#...
button $win.barkbtn -text "Bark!" -command [mymethod bark]
#...
}
}
::dog
%
The command __mymethod__ takes any number of arguments, and can be used like
__[list](../../../../index.md#list)__ to build up a callback command; the only
difference is that __mymethod__ returns a form of the command that won't change
even if the instance's name changes.
On the other hand, you might prefer to allow a widgetadaptor to override a
method such that your renamed widget will call the widgetadaptor's method
instead of its own. In this case, using __[list $self bark]__ will do what you
want...but this is a technique which should be used only in carefully controlled
circumstances.
## <a name='subsection40'></a>How do I delegate instance methods to a component?
See [DELEGATION](#section16).
# <a name='section6'></a>INSTANCE VARIABLES
## <a name='subsection41'></a>What is an instance variable?
An instance variable is a private variable associated with some particular Snit
object. Instance variables can be scalars or arrays.
## <a name='subsection42'></a>How is a scalar instance variable defined?
Scalar instance variables are defined in the type definition using the
__variable__ statement. You can simply name it, or you can initialize it with a
value:
snit::type mytype {
# Define variable "greeting" and initialize it with "Howdy!"
variable greeting "Howdy!"
}
## <a name='subsection43'></a>How is an array instance variable defined?
Array instance variables are also defined in the type definition using the
__variable__ command. You can initialize them at the same time by specifying the
__-array__ option:
snit::type mytype {
# Define array variable "greetings"
variable greetings -array {
formal "Good Evening"
casual "Howdy!"
}
}
## <a name='subsection44'></a>What happens if I don't initialize an instance variable?
Variables do not really exist until they are given values. If you do not
initialize a variable when you define it, then you must be sure to assign a
value to it (in the constructor, say, or in some method) before you reference
it.
## <a name='subsection45'></a>Are there any limitations on instance variable names?
Just a few.
First, every Snit object has a built-in instance variable called __options__,
which should never be redefined.
Second, all names beginning with "Snit_" are reserved for use by Snit internal
code.
Third, instance variable names containing the namespace delimiter (__::__) are
likely to cause great confusion.
## <a name='subsection46'></a>Do I need to declare my instance variables in my methods?
No. Once you've defined an instance variable in the type definition, it can be
used in any instance code (instance methods, the constructor, and the
destructor) without declaration. This differs from normal Tcl practice, in which
all non-local variables in a proc need to be declared.
There is a speed penalty to having all instance variables implicitly available
in all instance code. Even though your code need not declare the variables
explicitly, Snit must still declare them, and that takes time. If you have ten
instance variables, a method that uses none of them must still pay the
declaration penalty for all ten. In most cases, the additional runtime cost is
negligible. If extreme cases, you might wish to avoid it; there are two methods
for doing so.
The first is to define a single instance variable, an array, and store all of
your instance data in the array. This way, you're only paying the declaration
penalty for one variable--and you probably need the variable most of the time
anyway. This method breaks down if your instance variables include multiple
arrays; in Tcl 8.5, however, the __[dict](../../../../index.md#dict)__ command
might come to your rescue.
The second method is to declare your instance variables explicitly in your
instance code, while *not* including them in the type definition:
snit::type dog {
constructor {} {
variable mood
set mood happy
}
method setmood {newMood} {
variable mood
set mood $newMood
}
method getmood {} {
variable mood
return $mood
}
}
This allows you to ensure that only the required variables are included in each
method, at the cost of longer code and run-time errors when you forget to
declare a variable you need.
## <a name='subsection47'></a>How do I pass an instance variable's name to another object?
In Tk, it's common to pass a widget a variable name; for example, Tk label
widgets have a __-textvariable__ option which names the variable which will
contain the widget's text. This allows the program to update the label's value
just by assigning a new value to the variable.
If you naively pass the instance variable name to the label widget, you'll be
confused by the result; Tk will assume that the name names a global variable.
Instead, you need to provide a fully-qualified variable name. From within an
instance method or a constructor, you can fully qualify the variable's name
using the __myvar__ command:
snit::widget mywidget {
variable labeltext ""
constructor {args} {
# ...
label $win.label -textvariable [myvar labeltext]
# ...
}
}
## <a name='subsection48'></a>How do I make an instance variable public?
Practically speaking, you don't. Instead, you'll implement public variables as
[OPTIONS](#section7). Alternatively, you can write [INSTANCE METHODS](#section5)
to set and get the variable's value.
# <a name='section7'></a>OPTIONS
## <a name='subsection49'></a>What is an option?
A type's options are the equivalent of what other object-oriented languages
would call public member variables or properties: they are data values which can
be retrieved and (usually) set by the clients of an object.
Snit's implementation of options follows the Tk model fairly exactly, except
that __snit::type__ objects usually don't interact with [THE TK OPTION
DATABASE](#section19); __snit::widget__ and __snit::widgetadaptor__ objects, on
the other hand, always do.
## <a name='subsection50'></a>How do I define an option?
Options are defined in the type definition using the __option__ statement.
Consider the following type, to be used in an application that manages a list of
dogs for a pet store:
snit::type dog {
option -breed -default mongrel
option -color -default brown
option -akc -default 0
option -shots -default 0
}
According to this, a dog has four notable properties: a breed, a color, a flag
that says whether it's pedigreed with the American Kennel Club, and another flag
that says whether it has had its shots. The default dog, evidently, is a brown
mutt.
There are a number of options you can specify when defining an option; if
__-default__ is the only one, you can omit the word __-default__ as follows:
snit::type dog {
option -breed mongrel
option -color brown
option -akc 0
option -shots 0
}
If no __-default__ value is specified, the option's default value will be the
empty string (but see [THE TK OPTION DATABASE](#section19)).
The Snit man page refers to options like these as "locally defined" options.
## <a name='subsection51'></a>How can a client set options at object creation?
The normal convention is that the client may pass any number of options and
their values after the object's name at object creation. For example, the
__::dog__ command defined in the previous answer can now be used to create
individual dogs. Any or all of the options may be set at creation time.
% dog spot -breed beagle -color "mottled" -akc 1 -shots 1
::spot
% dog fido -shots 1
::fido
%
So __::spot__ is a pedigreed beagle; __::fido__ is a typical mutt, but his
owners evidently take care of him, because he's had his shots.
*Note:* If the type defines a constructor, it can specify a different
object-creation syntax. See [CONSTRUCTORS](#section12) for more information.
## <a name='subsection52'></a>How can a client retrieve an option's value?
Retrieve option values using the __cget__ method:
% spot cget -color
mottled
% fido cget -breed
mongrel
%
## <a name='subsection53'></a>How can a client set options after object creation?
Any number of options may be set at one time using the __configure__ instance
method. Suppose that closer inspection shows that ::fido is not a brown mongrel,
but rather a rare Arctic Boar Hound of a lovely dun color:
% fido configure -color dun -breed "Arctic Boar Hound"
% fido cget -color
dun
% fido cget -breed
Arctic Boar Hound
Alternatively, the __configurelist__ method takes a list of options and values;
occasionally this is more convenient:
% set features [list -color dun -breed "Arctic Boar Hound"]
-color dun -breed {Arctic Boar Hound}
% fido configurelist $features
% fido cget -color
dun
% fido cget -breed
Arctic Boar Hound
%
In Tcl 8.5, the __*__ keyword can be used with __configure__ in this case:
% set features [list -color dun -breed "Arctic Boar Hound"]
-color dun -breed {Arctic Boar Hound}
% fido configure {*}$features
% fido cget -color
dun
% fido cget -breed
Arctic Boar Hound
%
The results are the same.
## <a name='subsection54'></a>How should an instance method access an option value?
There are two ways an instance method can set and retrieve an option's value.
One is to use the __configure__ and __cget__ methods, as shown below.
% snit::type dog {
option -weight 10
method gainWeight {} {
set wt [$self cget -weight]
incr wt
$self configure -weight $wt
}
}
::dog
% dog fido
::fido
% fido cget -weight
10
% fido gainWeight
% fido cget -weight
11
%
Alternatively, Snit provides a built-in array instance variable called
__options__. The indices are the option names; the values are the option values.
The method __gainWeight__ can thus be rewritten as follows:
method gainWeight {} {
incr options(-weight)
}
As you can see, using the __options__ variable involves considerably less typing
and is the usual way to do it. But if you use __-configuremethod__ or
__-cgetmethod__ (described in the following answers), you might wish to use the
__configure__ and __cget__ methods anyway, just so that any special processing
you've implemented is sure to get done. Also, if the option is delegated to a
component then __configure__ and __cget__ are the only way to access it without
accessing the component directly. See [DELEGATION](#section16) for more
information.
## <a name='subsection55'></a>How can I make an option read-only?
Define the option with __-readonly yes__.
Suppose you've got an option that determines how instances of your type are
constructed; it must be set at creation time, after which it's constant. For
example, a dog never changes its breed; it might or might not have had its
shots, and if not can have them at a later time. __-breed__ should be read-only,
but __-shots__ should not be.
% snit::type dog {
option -breed -default mongrel -readonly yes
option -shots -default no
}
::dog
% dog fido -breed retriever
::fido
% fido configure -shots yes
% fido configure -breed terrier
option -breed can only be set at instance creation
%
## <a name='subsection56'></a>How can I catch accesses to an option's value?
Define a __-cgetmethod__ for the option.
## <a name='subsection57'></a>What is a -cgetmethod?
A __-cgetmethod__ is a method that's called whenever the related option's value
is queried via the __cget__ instance method. The handler can compute the
option's value, retrieve it from a database, or do anything else you'd like it
to do.
Here's what the default behavior would look like if written using a
__-cgetmethod__:
snit::type dog {
option -color -default brown -cgetmethod GetOption
method GetOption {option} {
return $options($option)
}
}
Any instance method can be used, provided that it takes one argument, the name
of the option whose value is to be retrieved.
## <a name='subsection58'></a>How can I catch changes to an option's value?
Define a __-configuremethod__ for the option.
## <a name='subsection59'></a>What is a -configuremethod?
A __-configuremethod__ is a method that's called whenever the related option is
given a new value via the __configure__ or __configurelist__ instance methods.
The method can pass the value on to some other object, store it in a database,
or do anything else you'd like it to do.
Here's what the default configuration behavior would look like if written using
a __-configuremethod__:
snit::type dog {
option -color -default brown -configuremethod SetOption
method SetOption {option value} {
set options($option) $value
}
}
Any instance method can be used, provided that it takes two arguments, the name
of the option and the new value.
Note that if your method doesn't store the value in the __options__ array, the
__options__ array won't get updated.
## <a name='subsection60'></a>How can I validate an option's value?
Define a __-validatemethod__.
## <a name='subsection61'></a>What is a -validatemethod?
A __-validatemethod__ is a method that's called whenever the related option is
given a new value via the __configure__ or __configurelist__ instance methods.
It's the method's responsibility to determine whether the new value is valid,
and throw an error if it isn't. The __-validatemethod__, if any, is called
before the value is stored in the __options__ array; in particular, it's called
before the __-configuremethod__, if any.
For example, suppose an option always takes a Boolean value. You can ensure that
the value is in fact a valid Boolean like this:
% snit::type dog {
option -shots -default no -validatemethod BooleanOption
method BooleanOption {option value} {
if {![string is boolean -strict $value]} {
error "expected a boolean value, got \"$value\""
}
}
}
::dog
% dog fido
% fido configure -shots yes
% fido configure -shots NotABooleanValue
expected a boolean value, got "NotABooleanValue"
%
Note that the same __-validatemethod__ can be used to validate any number of
boolean options.
Any method can be a __-validatemethod__ provided that it takes two arguments,
the option name and the new option value.
# <a name='section8'></a>TYPE VARIABLES
## <a name='subsection62'></a>What is a type variable?
A type variable is a private variable associated with a Snit type rather than
with a particular instance of the type. In C++ and Java, the term *static member
variable* is used for the same notion. Type variables can be scalars or arrays.
## <a name='subsection63'></a>How is a scalar type variable defined?
Scalar type variables are defined in the type definition using the
__typevariable__ statement. You can simply name it, or you can initialize it
with a value:
snit::type mytype {
# Define variable "greeting" and initialize it with "Howdy!"
typevariable greeting "Howdy!"
}
Every object of type __mytype__ now has access to a single variable called
__greeting__.
## <a name='subsection64'></a>How is an array-valued type variable defined?
Array-valued type variables are also defined using the __typevariable__ command;
to initialize them, include the __-array__ option:
snit::type mytype {
# Define typearray variable "greetings"
typevariable greetings -array {
formal "Good Evening"
casual "Howdy!"
}
}
## <a name='subsection65'></a>What happens if I don't initialize a type variable?
Variables do not really exist until they are given values. If you do not
initialize a variable when you define it, then you must be sure to assign a
value to it (in the type constructor, say) before you reference it.
## <a name='subsection66'></a>Are there any limitations on type variable names?
Type variable names have the same restrictions as the names of [INSTANCE
VARIABLES](#section6) do.
## <a name='subsection67'></a>Do I need to declare my type variables in my methods?
No. Once you've defined a type variable in the type definition, it can be used
in [INSTANCE METHODS](#section5) or [TYPE METHODS](#section9) without
declaration. This differs from normal Tcl practice, in which all non-local
variables in a proc need to be declared.
Type variables are subject to the same speed/readability tradeoffs as instance
variables; see [Do I need to declare my instance variables in my
methods?](#subsection46)
## <a name='subsection68'></a>How do I pass a type variable's name to another object?
In Tk, it's common to pass a widget a variable name; for example, Tk label
widgets have a __-textvariable__ option which names the variable which will
contain the widget's text. This allows the program to update the label's value
just by assigning a new value to the variable.
If you naively pass a type variable name to the label widget, you'll be confused
by the result; Tk will assume that the name names a global variable. Instead,
you need to provide a fully-qualified variable name. From within an instance
method or a constructor, you can fully qualify the type variable's name using
the __mytypevar__ command:
snit::widget mywidget {
typevariable labeltext ""
constructor {args} {
# ...
label $win.label -textvariable [mytypevar labeltext]
# ...
}
}
## <a name='subsection69'></a>How do I make a type variable public?
There are two ways to do this. The preferred way is to write a pair of [TYPE
METHODS](#section9) to set and query the type variable's value.
Type variables are stored in the type's namespace, which has the same name as
the type itself. Thus, you can also publicize the type variable's name in your
documentation so that clients can access it directly. For example,
snit::type mytype {
typevariable myvariable
}
set ::mytype::myvariable "New Value"
# <a name='section9'></a>TYPE METHODS
## <a name='subsection70'></a>What is a type method?
A type method is a procedure associated with the type itself rather than with
any specific instance of the type, and called as a subcommand of the type
command.
## <a name='subsection71'></a>How do I define a type method?
Type methods are defined in the type definition using the __typemethod__
statement:
snit::type dog {
# List of pedigreed dogs
typevariable pedigreed
typemethod pedigreedDogs {} {
return $pedigreed
}
}
Suppose the __dog__ type maintains a list of the names of the dogs that have
pedigrees. The __pedigreedDogs__ type method returns this list.
The __typemethod__ statement looks just like a normal Tcl
__[proc](../../../../index.md#proc)__, except that it appears in a
__snit::type__ definition. Notice that every type method gets an implicit
argument called __type__, which contains the fully-qualified type name.
## <a name='subsection72'></a>How does a client call a type method?
The type method name becomes a subcommand of the type's command. For example,
assuming that the constructor adds each pedigreed dog to the list of
__pedigreedDogs__,
snit::type dog {
option -pedigreed 0
# List of pedigreed dogs
typevariable pedigreed
typemethod pedigreedDogs {} {
return $pedigreed
}
# ...
}
dog spot -pedigreed 1
dog fido
foreach dog [dog pedigreedDogs] { ... }
## <a name='subsection73'></a>Are there any limitations on type method names?
Not really, so long as you avoid the standard type method names: __create__,
__destroy__, and __info__.
## <a name='subsection74'></a>How do I make a type method private?
It's sometimes useful to define private type methods, that is, type methods
intended to be called only by other type or instance methods of the same object.
Snit doesn't implement any access control on type methods; by convention, the
names of public methods begin with a lower-case letter, and the names of private
methods begin with an upper-case letter.
Alternatively, a Snit __[proc](../../../../index.md#proc)__ can be used as a
private type method; see [PROCS](#section10).
## <a name='subsection75'></a>Are there any limitations on type method arguments?
Method argument lists are defined just like normal Tcl proc argument lists; in
particular, they can include arguments with default values and the __args__
argument.
However, every type method is called with an implicit argument called __type__
that contains the name of the type command. In addition, type methods should by
convention avoid using the names of the arguments implicitly defined for
[INSTANCE METHODS](#section5).
## <a name='subsection76'></a>How does an instance or type method call a type method?
If an instance or type method needs to call a type method, it should use
__$type__ to do so:
snit::type dog {
typemethod pedigreedDogs {} { ... }
typemethod printPedigrees {} {
foreach obj [$type pedigreedDogs] { ... }
}
}
## <a name='subsection77'></a>How do I pass a type method as a callback?
It's common in Tcl to pass a snippet of code to another object, for it to call
later. Because types cannot be renamed, you can just use the type name, or, if
the callback is registered from within a type method, __type__. For example,
suppose we want to print a list of pedigreed dogs when a Tk button is pushed:
button .btn -text "Pedigrees" -command [list dog printPedigrees]
pack .btn
Alternatively, from a method or type method you can use the __mytypemethod__
command, just as you would use __mymethod__ to define a callback command for
[INSTANCE METHODS](#section5).
## <a name='subsection78'></a>Can type methods be hierarchical?
Yes, you can define hierarchical type methods in just the same way as you can
define hierarchical instance methods. See [INSTANCE METHODS](#section5) for
more.
# <a name='section10'></a>PROCS
## <a name='subsection79'></a>What is a proc?
A Snit __[proc](../../../../index.md#proc)__ is really just a Tcl proc defined
within the type's namespace. You can use procs for private code that isn't
related to any particular instance.
## <a name='subsection80'></a>How do I define a proc?
Procs are defined by including a __[proc](../../../../index.md#proc)__ statement
in the type definition:
snit::type mytype {
# Pops and returns the first item from the list stored in the
# listvar, updating the listvar
proc pop {listvar} { ... }
# ...
}
## <a name='subsection81'></a>Are there any limitations on proc names?
Any name can be used, so long as it does not begin with __Snit___; names
beginning with __Snit___ are reserved for Snit's own use. However, the wise
programmer will avoid __[proc](../../../../index.md#proc)__ names
(__[set](../../../../index.md#set)__, __[list](../../../../index.md#list)__,
__if__, etc.) that would shadow standard Tcl command names.
__[proc](../../../../index.md#proc)__ names, being private, should begin with a
capital letter according to convention; however, as there are typically no
public __[proc](../../../../index.md#proc)__s in the type's namespace it doesn't
matter much either way.
## <a name='subsection82'></a>How does a method call a proc?
Just like it calls any Tcl command. For example,
snit::type mytype {
# Pops and returns the first item from the list stored in the
# listvar, updating the listvar
proc pop {listvar} { ... }
variable requestQueue {}
# Get one request from the queue and process it.
method processRequest {} {
set req [pop requestQueue]
}
}
## <a name='subsection83'></a>How can I pass a proc to another object as a callback?
The __myproc__ command returns a callback command for the
__[proc](../../../../index.md#proc)__, just as __mymethod__ does for a method.
# <a name='section11'></a>TYPE CONSTRUCTORS
## <a name='subsection84'></a>What is a type constructor?
A type constructor is a body of code that initializes the type as a whole,
rather like a C++ static initializer. The body of a type constructor is executed
once when the type is defined, and never again.
A type can have at most one type constructor.
## <a name='subsection85'></a>How do I define a type constructor?
A type constructor is defined by using the __typeconstructor__ statement in the
type definition. For example, suppose the type uses an array-valued type
variable as a look-up table, and the values in the array have to be computed at
start-up.
% snit::type mytype {
typevariable lookupTable
typeconstructor {
array set lookupTable {key value...}
}
}
# <a name='section12'></a>CONSTRUCTORS
## <a name='subsection86'></a>What is a constructor?
In object-oriented programming, an object's constructor is responsible for
initializing the object completely at creation time. The constructor receives
the list of options passed to the __snit::type__ command's __create__ method and
can then do whatever it likes. That might include computing instance variable
values, reading data from files, creating other objects, updating type and
instance variables, and so forth.
The constructor's return value is ignored (unless it's an error, of course).
## <a name='subsection87'></a>How do I define a constructor?
A constructor is defined by using the __constructor__ statement in the type
definition. Suppose that it's desired to keep a list of all pedigreed dogs. The
list can be maintained in a type variable and retrieved by a type method.
Whenever a dog is created, it can add itself to the list--provided that it's
registered with the American Kennel Club.
% snit::type dog {
option -akc 0
typevariable akcList {}
constructor {args} {
$self configurelist $args
if {$options(-akc)} {
lappend akcList $self
}
}
typemethod akclist {} {
return $akcList
}
}
::dog
% dog spot -akc 1
::spot
% dog fido
::fido
% dog akclist
::spot
%
## <a name='subsection88'></a>What does the default constructor do?
If you don't provide a constructor explicitly, you get the default constructor,
which is identical to the explicitly-defined constructor shown here:
snit::type dog {
constructor {args} {
$self configurelist $args
}
}
When the constructor is called, __args__ will be set to the list of arguments
that follow the object's name. The constructor is allowed to interpret this list
any way it chooses; the normal convention is to assume that it's a list of
option names and values, as shown in the example above. If you simply want to
save the option values, you should use the __configurelist__ method, as shown.
## <a name='subsection89'></a>Can I choose a different set of arguments for the constructor?
Yes, you can. For example, suppose we wanted to be sure that the breed was
explicitly stated for every dog at creation time, and couldn't be changed
thereafter. One way to do that is as follows:
% snit::type dog {
variable breed
option -color brown
option -akc 0
constructor {theBreed args} {
set breed $theBreed
$self configurelist $args
}
method breed {} { return $breed }
}
::dog
% dog spot dalmatian -color spotted -akc 1
::spot
% spot breed
dalmatian
The drawback is that this syntax is non-standard, and may limit the
compatibility of your new type with other people's code. For example, Snit
assumes that it can create [COMPONENTS](#section14) using the standard creation
syntax.
## <a name='subsection90'></a>Are there any limitations on constructor arguments?
Constructor argument lists are subject to the same limitations as those on
instance method argument lists. It has the same implicit arguments, and can
contain default values and the __args__ argument.
## <a name='subsection91'></a>Is there anything special about writing the constructor?
Yes. Writing the constructor can be tricky if you're delegating options to
components, and there are specific issues relating to __snit::widget__s and
__snit::widgetadaptor__s. See [DELEGATION](#section16), [WIDGETS](#section17),
[WIDGET ADAPTORS](#section18), and [THE TK OPTION DATABASE](#section19).
# <a name='section13'></a>DESTRUCTORS
## <a name='subsection92'></a>What is a destructor?
A destructor is a special kind of method that's called when an object is
destroyed. It's responsible for doing any necessary clean-up when the object
goes away: destroying [COMPONENTS](#section14), closing files, and so forth.
## <a name='subsection93'></a>How do I define a destructor?
Destructors are defined by using the __destructor__ statement in the type
definition.
Suppose we're maintaining a list of pedigreed dogs; then we'll want to remove
dogs from it when they are destroyed.
snit::type dog {
option -akc 0
typevariable akcList {}
constructor {args} {
$self configurelist $args
if {$options(-akc)} {
lappend akcList $self
}
}
destructor {
set ndx [lsearch $akcList $self]
if {$ndx != -1} {
set akcList [lreplace $akcList $ndx $ndx]
}
}
typemethod akclist {} {
return $akcList
}
}
## <a name='subsection94'></a>Are there any limitations on destructor arguments?
Yes; a destructor has no explicit arguments.
## <a name='subsection95'></a>What implicit arguments are passed to the destructor?
The destructor gets the same implicit arguments that are passed to [INSTANCE
METHODS](#section5): __type__, __selfns__, __win__, and __self__.
## <a name='subsection96'></a>Must components be destroyed explicitly?
Yes and no.
Any Tk widgets created by a __snit::widget__ or __snit::widgetadaptor__ will be
destroyed automatically by Tk when the megawidget is destroyed, in keeping with
normal Tk behavior (destroying a parent widget destroys the whole tree).
Components of normal __snit::types__, on the other hand, are never destroyed
automatically, nor are non-widget components of Snit megawidgets. If your object
creates them in its constructor, then it should generally destroy them in its
destructor.
## <a name='subsection97'></a>Is there any special about writing a destructor?
Yes. If an object's constructor throws an error, the object's destructor will be
called to clean up; this means that the object might not be completely
constructed when the destructor is called. This can cause the destructor to
throw its own error; the result is usually misleading, confusing, and unhelpful.
Consequently, it's important to write your destructor so that it's fail-safe.
For example, a __dog__ might create a __tail__ component; the component will
need to be destroyed. But suppose there's an error while processing the creation
options--the destructor will be called, and there will be no __tail__ to
destroy. The simplest solution is generally to catch and ignore any errors while
destroying components.
snit::type dog {
component tail
constructor {args} {
$self configurelist $args
set tail [tail %AUTO%]
}
destructor {
catch {$tail destroy}
}
}
# <a name='section14'></a>COMPONENTS
## <a name='subsection98'></a>What is a component?
Often an object will create and manage a number of other objects. A Snit
megawidget, for example, will often create a number of Tk widgets. These objects
are part of the main object; it is composed of them, so they are called
components of the object.
But Snit also has a more precise meaning for [COMPONENT](#section14). The
components of a Snit object are those objects to which methods or options can be
delegated. (See [DELEGATION](#section16) for more information about delegation.)
## <a name='subsection99'></a>How do I declare a component?
First, you must decide what role a component plays within your object, and give
the role a name. Then, you declare the component using its role name and the
__component__ statement. The __component__ statement declares an *instance
variable* which is used to store the component's command name when the component
is created.
For example, suppose your __dog__ object creates a __tail__ object (the better
to wag with, no doubt):
snit::type dog {
component mytail
constructor {args} {
# Create and save the component's command
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
method wag {} {
$mytail wag
}
}
As shown here, it doesn't matter what the __tail__ object's real name is; the
__dog__ object refers to it by its component name.
The above example shows one way to delegate the __wag__ method to the __mytail__
component; see [DELEGATION](#section16) for an easier way.
## <a name='subsection100'></a>How is a component named?
A component has two names. The first name is that of the component variable;
this represents the role the component object plays within the Snit object. This
is the component name proper, and is the name used to refer to the component
within Snit code. The second name is the name of the actual component object
created by the Snit object's constructor. This second name is always a Tcl
command name, and is referred to as the component's object name.
In the example in the previous question, the component name is __mytail__; the
__mytail__ component's object name is chosen automatically by Snit since
__%AUTO%__ was used when the component object was created.
## <a name='subsection101'></a>Are there any limitations on component names?
Yes. __snit::widget__ and __snit::widgetadaptor__ objects have a special
component called the __hull__ component; thus, the name __hull__ should be used
for no other purpose.
Otherwise, since component names are in fact instance variable names they must
follow the rules for [INSTANCE VARIABLES](#section6).
## <a name='subsection102'></a>What is an owned component?
An *owned* component is a component whose object command's lifetime is
controlled by the __snit::type__ or __snit::widget__.
As stated above, a component is an object to which our object can delegate
methods or options. Under this definition, our object will usually create its
component objects, but not necessarily. Consider the following: a dog object has
a tail component; but tail knows that it's part of the dog:
snit::type dog {
component mytail
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
destructor {
catch {$mytail destroy}
}
delegate method wagtail to mytail as wag
method bark {} {
return "$self barked."
}
}
snit::type tail {
component mydog
option -partof -readonly yes
constructor {args} {
$self configurelist $args
set mydog $options(-partof)
}
method wag {} {
return "Wag, wag."
}
method pull {} {
$mydog bark
}
}
Thus, if you ask a dog to wag its tail, it tells its tail to wag; and if you
pull the dog's tail, the tail tells the dog to bark. In this scenario, the tail
is a component of the dog, and the dog is a component of the tail, but the dog
owns the tail and not the other way around.
## <a name='subsection103'></a>What does the install command do?
The __install__ command creates an owned component using a specified command,
and assigns the result to the component's instance variable. For example:
snit::type dog {
component mytail
constructor {args} {
# set mytail [tail %AUTO% -partof $self]
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
In a __snit::type__'s code, the __install__ command shown above is equivalent to
the __set mytail__ command that's commented out. In a __snit::widget__'s or
__snit::widgetadaptor__'s, code, however, the __install__ command also queries
[THE TK OPTION DATABASE](#section19) and initializes the new component's options
accordingly. For consistency, it's a good idea to get in the habit of using
__install__ for all owned components.
## <a name='subsection104'></a>Must owned components be created in the constructor?
No, not necessarily. In fact, there's no reason why an object can't destroy and
recreate a component multiple times over its own lifetime.
## <a name='subsection105'></a>Are there any limitations on component object names?
Yes.
Component objects which are Tk widgets or megawidgets must have valid Tk window
names.
Component objects which are not widgets or megawidgets must have fully-qualified
command names, i.e., names which include the full namespace of the command. Note
that Snit always creates objects with fully qualified names.
Next, the object names of components and owned by your object must be unique.
This is no problem for widget components, since widget names are always unique;
but consider the following code:
snit::type tail { ... }
snit::type dog {
delegate method wag to mytail
constructor {} {
install mytail using tail mytail
}
}
This code uses the component name, __mytail__, as the component object name.
This is not good, and here's why: Snit instance code executes in the Snit type's
namespace. In this case, the __mytail__ component is created in the __::dog::__
namespace, and will thus have the name __::dog::mytail__.
Now, suppose you create two dogs. Both dogs will attempt to create a tail called
__::dog::mytail__. The first will succeed, and the second will fail, since Snit
won't let you create an object if its name is already a command. Here are two
ways to avoid this situation:
First, if the component type is a __snit::type__ you can specify __%AUTO%__ as
its name, and be guaranteed to get a unique name. This is the safest thing to
do:
install mytail using tail %AUTO%
If the component type isn't a __snit::type__ you can create the component in the
object's instance namespace:
install mytail using tail ${selfns}::mytail
Make sure you pick a unique name within the instance namespace.
## <a name='subsection106'></a>Must I destroy the components I own?
That depends. When a parent widget is destroyed, all child widgets are destroyed
automatically. Thus, if your object is a __snit::widget__ or
__snit::widgetadaptor__ you don't need to destroy any components that are
widgets, because they will generally be children or descendants of your
megawidget.
If your object is an instance of __snit::type__, though, none of its owned
components will be destroyed automatically, nor will be non-widget components of
a __snit::widget__ be destroyed automatically. All such owned components must be
destroyed explicitly, or they won't be destroyed at all.
## <a name='subsection107'></a>Can I expose a component's object command as part of my interface?
Yes, and there are two ways to do it. The most appropriate way is usually to use
[DELEGATION](#section16). Delegation allows you to pass the options and methods
you specify along to particular components. This effectively hides the
components from the users of your type, and ensures good encapsulation.
However, there are times when it's appropriate, not to mention simpler, just to
make the entire component part of your type's public interface.
## <a name='subsection108'></a>How do I expose a component's object command?
When you declare the component, specify the __component__ statement's
__-public__ option. The value of this option is the name of a method which will
be delegated to your component's object command.
For example, supposed you've written a combobox megawidget which owns a listbox
widget, and you want to make the listbox's entire interface public. You can do
it like this:
snit::widget combobox {
component listbox -public listbox
constructor {args} {
install listbox using listbox $win.listbox ....
}
}
combobox .mycombo
.mycombo listbox configure -width 30
Your comobox widget, __.mycombo__, now has a __listbox__ method which has all of
the same subcommands as the listbox widget itself. Thus, the above code sets the
listbox component's width to 30.
Usually you'll let the method name be the same as the component name; however,
you can name it anything you like.
# <a name='section15'></a>TYPE COMPONENTS
## <a name='subsection109'></a>What is a type component?
A type component is a component that belongs to the type itself instead of to a
particular instance of the type. The relationship between components and type
components is the same as the relationship between [INSTANCE
VARIABLES](#section6) and [TYPE VARIABLES](#section8). Both [INSTANCE
METHODS](#section5) and [TYPE METHODS](#section9) can be delegated to type
components.
Once you understand [COMPONENTS](#section14) and [DELEGATION](#section16), type
components are just more of the same.
## <a name='subsection110'></a>How do I declare a type component?
Declare a type component using the __typecomponent__ statement. It takes the
same options (__-inherit__ and __-public__) as the __component__ statement does,
and defines a type variable to hold the type component's object command.
Suppose in your model you've got many dogs, but only one veterinarian. You might
make the veterinarian a type component.
snit::type veterinarian { ... }
snit::type dog {
typecomponent vet
# ...
}
## <a name='subsection111'></a>How do I install a type component?
Just use the __[set](../../../../index.md#set)__ command to assign the
component's object command to the type component. Because types (even
__snit::widget__ types) are not widgets, and do not have options anyway, the
extra features of the __install__ command are not needed.
You'll usually install type components in the type constructor, as shown here:
snit::type veterinarian { ... }
snit::type dog {
typecomponent vet
typeconstructor {
set vet [veterinarian %AUTO%]
}
}
## <a name='subsection112'></a>Are there any limitations on type component names?
Yes, the same as on [INSTANCE VARIABLES](#section6), [TYPE
VARIABLES](#section8), and normal [COMPONENTS](#section14).
# <a name='section16'></a>DELEGATION
## <a name='subsection113'></a>What is delegation?
Delegation, simply put, is when you pass a task you've been given to one of your
assistants. (You do have assistants, don't you?) Snit objects can do the same
thing. The following example shows one way in which the __dog__ object can
delegate its __wag__ method and its __-taillength__ option to its __tail__
component.
snit::type dog {
variable mytail
option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption
method SetTailOption {option value} {
$mytail configure $option $value
}
method GetTailOption {option} {
$mytail cget $option
}
method wag {} {
$mytail wag
}
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
This is the hard way to do it, by it demonstrates what delegation is all about.
See the following answers for the easy way to do it.
Note that the constructor calls the __configurelist__ method
__[after](../../../../index.md#after)__ it creates its __tail__; otherwise, if
__-taillength__ appeared in the list of __args__ we'd get an error.
## <a name='subsection114'></a>How can I delegate a method to a component object?
Delegation occurs frequently enough that Snit makes it easy. Any method can be
delegated to any component or type component by placing a single __delegate__
statement in the type definition. (See [COMPONENTS](#section14) and [TYPE
COMPONENTS](#section15) for more information about component names.)
For example, here's a much better way to delegate the __dog__ object's __wag__
method:
% snit::type dog {
delegate method wag to mytail
constructor {} {
install mytail using tail %AUTO%
}
}
::dog
% snit::type tail {
method wag {} { return "Wag, wag, wag."}
}
::tail
% dog spot
::spot
% spot wag
Wag, wag, wag.
This code has the same effect as the code shown under the previous question:
when a __dog__'s __wag__ method is called, the call and its arguments are passed
along automatically to the __tail__ object.
Note that when a component is mentioned in a __delegate__ statement, the
component's instance variable is defined implicitly. However, it's still good
practice to declare it explicitly using the __component__ statement.
Note also that you can define a method name using the
__[method](../../../../index.md#method)__ statement, or you can define it using
__delegate__; you can't do both.
## <a name='subsection115'></a>Can I delegate to a method with a different name?
Suppose you wanted to delegate the __dog__'s __wagtail__ method to the
__tail__'s __wag__ method. After all you wag the tail, not the dog. It's easily
done:
snit::type dog {
delegate method wagtail to mytail as wag
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
## <a name='subsection116'></a>Can I delegate to a method with additional arguments?
Suppose the __tail__'s __wag__ method takes as an argument the number of times
the tail should be wagged. You want to delegate the __dog__'s __wagtail__ method
to the __tail__'s __wag__ method, specifying that the tail should be wagged
exactly three times. This is easily done, too:
snit::type dog {
delegate method wagtail to mytail as {wag 3}
# ...
}
snit::type tail {
method wag {count} {
return [string repeat "Wag " $count]
}
# ...
}
## <a name='subsection117'></a>Can I delegate a method to something other than an object?
Normal method delegation assumes that you're delegating a method (a subcommand
of an object command) to a method of another object (a subcommand of a different
object command). But not all Tcl objects follow Tk conventions, and not
everything you'd to which you'd like to delegate a method is necessary an
object. Consequently, Snit makes it easy to delegate a method to pretty much
anything you like using the __delegate__ statement's __using__ clause.
Suppose your dog simulation stores dogs in a database, each dog as a single
record. The database API you're using provides a number of commands to manage
records; each takes the record ID (a string you choose) as its first argument.
For example, __saverec__ saves a record. If you let the record ID be the name of
the dog object, you can delegate the dog's __save__ method to the __saverec__
command as follows:
snit::type dog {
delegate method save using {saverec %s}
}
The __%s__ is replaced with the instance name when the __save__ method is
called; any additional arguments are the appended to the resulting command.
The __using__ clause understands a number of other %-conversions; in addition to
the instance name, you can substitute in the method name (__%m__), the type name
(__%t__), the instance namespace (__%n__), the Tk window name (__%w__), and, if
a component or typecomponent name was given in the __delegate__ statement, the
component's object command (__%c__).
## <a name='subsection118'></a>How can I delegate a method to a type component object?
Just exactly as you would to a component object. The __delegate method__
statement accepts both component and type component names in its __to__ clause.
## <a name='subsection119'></a>How can I delegate a type method to a type component object?
Use the __delegate typemethod__ statement. It works like __delegate method__,
with these differences: first, it defines a type method instead of an instance
method; second, the __using__ clause ignores the __%s__, __%n__, and __%w__
%-conversions.
Naturally, you can't delegate a type method to an instance component...Snit
wouldn't know which instance should receive it.
## <a name='subsection120'></a>How can I delegate an option to a component object?
The first question in this section (see [DELEGATION](#section16)) shows one way
to delegate an option to a component; but this pattern occurs often enough that
Snit makes it easy. For example, every __tail__ object has a __-length__ option;
we want to allow the creator of a __dog__ object to set the tail's length. We
can do this:
% snit::type dog {
delegate option -length to mytail
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
::dog
% snit::type tail {
option -partof
option -length 5
}
::tail
% dog spot -length 7
::spot
% spot cget -length
7
This produces nearly the same result as the __-configuremethod__ and
__-cgetmethod__ shown under the first question in this section: whenever a
__dog__ object's __-length__ option is set or retrieved, the underlying __tail__
object's option is set or retrieved in turn.
Note that you can define an option name using the __option__ statement, or you
can define it using __delegate__; you can't do both.
## <a name='subsection121'></a>Can I delegate to an option with a different name?
In the previous answer we delegated the __dog__'s __-length__ option down to its
__tail__. This is, of course, wrong. The dog has a length, and the tail has a
length, and they are different. What we'd really like to do is give the __dog__
a __-taillength__ option, but delegate it to the __tail__'s __-length__ option:
snit::type dog {
delegate option -taillength to mytail as -length
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
}
## <a name='subsection122'></a>How can I delegate any unrecognized method or option to a component object?
It may happen that a Snit object gets most of its behavior from one of its
components. This often happens with __snit::widgetadaptors__, for example, where
we wish to slightly the modify the behavior of an existing widget. To carry on
with our __dog__ example, however, suppose that we have a __snit::type__ called
__animal__ that implements a variety of animal behaviors--moving, eating,
sleeping, and so forth. We want our __dog__ objects to inherit these same
behaviors, while adding dog-like behaviors of its own. Here's how we can give a
__dog__ methods and options of its own while delegating all other methods and
options to its __animal__ component:
snit::type dog {
delegate option * to animal
delegate method * to animal
option -akc 0
constructor {args} {
install animal using animal %AUTO% -name $self
$self configurelist $args
}
method wag {} {
return "$self wags its tail"
}
}
That's it. A __dog__ is now an __animal__ that has a __-akc__ option and can
__wag__ its tail.
Note that we don't need to specify the full list of method names or option names
that __animal__ will receive. It gets anything __dog__ doesn't recognize--and if
it doesn't recognize it either, it will simply throw an error, just as it
should.
You can also delegate all unknown type methods to a type component using
__delegate typemethod *__.
## <a name='subsection123'></a>How can I delegate all but certain methods or options to a component?
In the previous answer, we said that every __dog__ is an __animal__ by
delegating all unknown methods and options to the __animal__ component. But what
if the __animal__ type has some methods or options that we'd like to suppress?
One solution is to explicitly delegate all the options and methods, and forgo
the convenience of __delegate method *__ and __delegate option *__. But if we
wish to suppress only a few options or methods, there's an easier way:
snit::type dog {
delegate option * to animal except -numlegs
delegate method * to animal except {fly climb}
# ...
constructor {args} {
install animal using animal %AUTO% -name $self -numlegs 4
$self configurelist $args
}
# ...
}
Dogs have four legs, so we specify that explicitly when we create the __animal__
component, and explicitly exclude __-numlegs__ from the set of delegated
options. Similarly, dogs can neither __fly__ nor __climb__, so we exclude those
__animal__ methods as shown.
## <a name='subsection124'></a>Can a hierarchical method be delegated?
Yes; just specify multiple words in the delegated method's name:
snit::type tail {
method wag {} {return "Wag, wag"}
method droop {} {return "Droop, droop"}
}
snit::type dog {
delegate method {tail wag} to mytail
delegate method {tail droop} to mytail
# ...
constructor {args} {
install mytail using tail %AUTO%
$self configurelist $args
}
# ...
}
Unrecognized hierarchical methods can also be delegated; the following code
delegates all subcommands of the "tail" method to the "mytail" component:
snit::type dog {
delegate method {tail *} to mytail
# ...
}
# <a name='section17'></a>WIDGETS
## <a name='subsection125'></a>What is a snit::widget?
A __snit::widget__ is the Snit version of what Tcl programmers usually call a
*megawidget*: a widget-like object usually consisting of one or more Tk widgets
all contained within a Tk frame.
A __snit::widget__ is also a special kind of __snit::type__. Just about
everything in this FAQ list that relates to __snit::types__ also applies to
__snit::widgets__.
## <a name='subsection126'></a>How do I define a snit::widget?
__snit::widgets__ are defined using the __snit::widget__ command, just as
__snit::types__ are defined by the __snit::type__ command.
The body of the definition can contain all of the same kinds of statements, plus
a couple of others which will be mentioned below.
## <a name='subsection127'></a>How do snit::widgets differ from snit::types?
- The name of an instance of a __snit::type__ can be any valid Tcl command
name, in any namespace. The name of an instance of a __snit::widget__ must
be a valid Tk widget name, and its parent widget must already exist.
- An instance of a __snit::type__ can be destroyed by calling its __destroy__
method. Instances of a __snit::widget__ have no destroy method; use the Tk
__destroy__ command instead.
- Every instance of a __snit::widget__ has one predefined component called its
__hull__ component. The hull is usually a Tk
__[frame](../../../../index.md#frame)__ or __toplevel__ widget; any other
widgets created as part of the __snit::widget__ will usually be contained
within the hull.
- __snit::widget__s can have their options receive default values from [THE TK
OPTION DATABASE](#section19).
## <a name='subsection128'></a>What is a hull component?
Snit can't create a Tk widget object; only Tk can do that. Thus, every instance
of a __snit::widget__ must be wrapped around a genuine Tk widget; this Tk widget
is called the *hull component*. Snit effectively piggybacks the behavior you
define (methods, options, and so forth) on top of the hull component so that the
whole thing behaves like a standard Tk widget.
For __snit::widget__s the hull component must be a Tk widget that defines the
__-class__ option.
__snit::widgetadaptor__s differ from __snit::widget__s chiefly in that any kind
of widget can be used as the hull component; see [WIDGET ADAPTORS](#section18).
## <a name='subsection129'></a>How can I set the hull type for a snit::widget?
A __snit::widget__'s hull component will usually be a Tk
__[frame](../../../../index.md#frame)__ widget; however, it may be any Tk widget
that defines the __-class__ option. You can explicitly choose the hull type you
prefer by including the __hulltype__ command in the widget definition:
snit::widget mytoplevel {
hulltype toplevel
# ...
}
If no __hulltype__ command appears, the hull will be a
__[frame](../../../../index.md#frame)__.
By default, Snit recognizes the following hull types: the Tk widgets
__[frame](../../../../index.md#frame)__, __labelframe__, __toplevel__, and the
Tile widgets __ttk::frame__, __ttk::labelframe__, and __ttk::toplevel__. To
enable the use of some other kind of widget as the hull type, you can
__lappend__ the widget command to the variable __snit::hulltypes__ (always
provided the widget defines the __-class__ option. For example, suppose Tk gets
a new widget type called a __prettyframe__:
lappend snit::hulltypes prettyframe
snit::widget mywidget {
hulltype prettyframe
# ...
}
## <a name='subsection130'></a>How should I name widgets which are components of a snit::widget?
Every widget, whether a genuine Tk widget or a Snit megawidget, has to have a
valid Tk window name. When a __snit::widget__ is first created, its instance
name, __self__, is a Tk window name; however, if the __snit::widget__ is used as
the hull component by a __snit::widgetadaptor__ its instance name will be
changed to something else. For this reason, every __snit::widget__ method,
constructor, destructor, and so forth is passed another implicit argument,
__win__, which is the window name of the megawidget. Any children should be
named using __win__ as the root.
Thus, suppose you're writing a toolbar widget, a frame consisting of a number of
buttons placed side-by-side. It might look something like this:
snit::widget toolbar {
delegate option * to hull
constructor {args} {
button $win.open -text Open -command [mymethod open]
button $win.save -text Save -command [mymethod save]
# ....
$self configurelist $args
}
}
See also the question on renaming objects, toward the top of this file.
# <a name='section18'></a>WIDGET ADAPTORS
## <a name='subsection131'></a>What is a snit::widgetadaptor?
A __snit::widgetadaptor__ is a kind of __snit::widget__. Whereas a
__snit::widget__'s hull is automatically created and is always a Tk frame, a
__snit::widgetadaptor__ can be based on any Tk widget--or on any Snit
megawidget, or even (with luck) on megawidgets defined using some other package.
It's called a *widget adaptor* because it allows you to take an existing widget
and customize its behavior.
## <a name='subsection132'></a>How do I define a snit::widgetadaptor?
Use the __snit::widgetadaptor__ command. The definition for a
__snit::widgetadaptor__ looks just like that for a __snit::type__ or
__snit::widget__, except that the constructor must create and install the hull
component.
For example, the following code creates a read-only text widget by the simple
device of turning its __insert__ and __delete__ methods into no-ops. Then, we
define new methods, __ins__ and __del__, which get delegated to the hull
component as __insert__ and __delete__. Thus, we've adapted the text widget and
given it new behavior while still leaving it fundamentally a text widget.
::snit::widgetadaptor rotext {
constructor {args} {
# Create the text widget; turn off its insert cursor
installhull using text -insertwidth 0
# Apply any options passed at creation time.
$self configurelist $args
}
# Disable the text widget's insert and delete methods, to
# make this readonly.
method insert {args} {}
method delete {args} {}
# Enable ins and del as synonyms, so the program can insert and
# delete.
delegate method ins to hull as insert
delegate method del to hull as delete
# Pass all other methods and options to the real text widget, so
# that the remaining behavior is as expected.
delegate method * to hull
delegate option * to hull
}
The most important part is in the constructor. Whereas __snit::widget__ creates
the hull for you, __snit::widgetadaptor__ cannot -- it doesn't know what kind of
widget you want. So the first thing the constructor does is create the hull
component (a Tk text widget in this case), and then installs it using the
__installhull__ command.
*Note:* There is no instance command until you create one by installing a hull
component. Any attempt to pass methods to __$self__ prior to calling
__installhull__ will fail.
## <a name='subsection133'></a>Can I adapt a widget created elsewhere in the program?
Yes.
At times, it can be convenient to adapt a pre-existing widget instead of
creating your own. For example, the Bwidget __PagesManager__ widget manages a
set of __[frame](../../../../index.md#frame)__ widgets, only one of which is
visible at a time. The application chooses which
__[frame](../../../../index.md#frame)__ is visible. All of the These
__[frame](../../../../index.md#frame)__s are created by the __PagesManager__
itself, using its __add__ method. It's convenient to adapt these frames to do
what we'd like them to do.
In a case like this, the Tk widget will already exist when the
__snit::widgetadaptor__ is created. Snit provides an alternate form of the
__installhull__ command for this purpose:
snit::widgetadaptor pageadaptor {
constructor {args} {
# The widget already exists; just install it.
installhull $win
# ...
}
}
## <a name='subsection134'></a>Can I adapt another megawidget?
Maybe. If the other megawidget is a __snit::widget__ or __snit::widgetadaptor__,
then yes. If it isn't then, again, maybe. You'll have to try it and see. You're
most likely to have trouble with widget destruction--you have to make sure that
your megawidget code receives the __<Destroy>__ event before the megawidget
you're adapting does.
# <a name='section19'></a>THE TK OPTION DATABASE
## <a name='subsection135'></a>What is the Tk option database?
The Tk option database is a database of default option values maintained by Tk
itself; every Tk application has one. The concept of the option database derives
from something called the X Windows resource database; however, the option
database is available in every Tk implementation, including those which do not
use the X Windows system (e.g., Microsoft Windows).
Full details about the Tk option database are beyond the scope of this document;
both *Practical Programming in Tcl and Tk* by Welch, Jones, and Hobbs, and
*Effective Tcl/Tk Programming* by Harrison and McClennan., have good
introductions to it.
Snit is implemented so that most of the time it will simply do the right thing
with respect to the option database, provided that the widget developer does the
right thing by Snit. The body of this section goes into great deal about what
Snit requires. The following is a brief statement of the requirements, for
reference.
- If the widget's default widget class is not what is desired, set it
explicitly using the __widgetclass__ statement in the widget definition.
- When defining or delegating options, specify the resource and class names
explicitly when necessary.
- Use the __installhull using__ command to create and install the hull for
__snit::widgetadaptor__s.
- Use the __install__ command to create and install all components which are
widgets.
- Use the __install__ command to create and install components which aren't
widgets if you'd like them to receive option values from the option
database.
The interaction of Tk widgets with the option database is a complex thing; the
interaction of Snit with the option database is even more so, and repays
attention to detail.
## <a name='subsection136'></a>Do snit::types use the Tk option database?
No, they don't; querying the option database requires a Tk window name, and
__snit::type__s don't have one.
If you create an instance of a __snit::type__ as a component of a
__snit::widget__ or __snit::widgetadaptor__, on the other hand, and if any
options are delegated to the component, and if you use __install__ to create and
install it, then the megawidget will query the option database on the
__snit::type__'s behalf. This might or might not be what you want, so take care.
## <a name='subsection137'></a>What is my snit::widget's widget class?
Every Tk widget has a "widget class": a name that is used when adding option
settings to the database. For Tk widgets, the widget class is the same as the
widget command name with an initial capital. For example, the widget class of
the Tk __button__ widget is __Button__.
Similarly, the widget class of a __snit::widget__ defaults to the unqualified
type name with the first letter capitalized. For example, the widget class of
snit::widget ::mylibrary::scrolledText { ... }
is __ScrolledText__.
The widget class can also be set explicitly using the __widgetclass__ statement
within the __snit::widget__ definition:
snit::widget ::mylibrary::scrolledText {
widgetclass Text
# ...
}
The above definition says that a __scrolledText__ megawidget has the same widget
class as an ordinary __[text](../../../../index.md#text)__ widget. This might or
might not be a good idea, depending on how the rest of the megawidget is
defined, and how its options are delegated.
## <a name='subsection138'></a>What is my snit::widgetadaptor's widget class?
The widget class of a __snit::widgetadaptor__ is just the widget class of its
hull widget; Snit has no control over this.
Note that the widget class can be changed only for
__[frame](../../../../index.md#frame)__ and __toplevel__ widgets, which is why
these are the valid hull types for __snit::widget__s.
Try to use __snit::widgetadaptor__s only to make small modifications to another
widget's behavior. Then, it will usually not make sense to change the widget's
widget class anyway.
## <a name='subsection139'></a>What are option resource and class names?
Every Tk widget option has three names: the option name, the resource name, and
the class name. The option name begins with a hyphen and is all lowercase; it's
used when creating widgets, and with the __configure__ and __cget__ commands.
The resource and class names are used to initialize option default values by
querying the option database. The resource name is usually just the option name
minus the hyphen, but may contain uppercase letters at word boundaries; the
class name is usually just the resource name with an initial capital, but not
always. For example, here are the option, resource, and class names for several
Tk __[text](../../../../index.md#text)__ widget options:
-background background Background
-borderwidth borderWidth BorderWidth
-insertborderwidth insertBorderWidth BorderWidth
-padx padX Pad
As is easily seen, sometimes the resource and class names can be inferred from
the option name, but not always.
## <a name='subsection140'></a>What are the resource and class names for my megawidget's options?
For options implicitly delegated to a component using __delegate option *__, the
resource and class names will be exactly those defined by the component. The
__configure__ method returns these names, along with the option's default and
current values:
% snit::widget mytext {
delegate option * to text
constructor {args} {
install text using text .text
# ...
}
# ...
}
::mytext
% mytext .text
.text
% .text configure -padx
-padx padX Pad 1 1
%
For all other options (whether locally defined or explicitly delegated), the
resource and class names can be defined explicitly, or they can be allowed to
have default values.
By default, the resource name is just the option name minus the hyphen; the the
class name is just the option name with an initial capital letter. For example,
suppose we explicitly delegate "-padx":
% snit::widget mytext {
option -myvalue 5
delegate option -padx to text
delegate option * to text
constructor {args} {
install text using text .text
# ...
}
# ...
}
::mytext
% mytext .text
.text
% .text configure -myvalue
-myvalue myvalue Myvalue 5 5
% .text configure -padx
-padx padx Padx 1 1
%
Here the resource and class names are chosen using the default rules. Often
these rules are sufficient, but in the case of "-padx" we'd most likely prefer
that the option's resource and class names are the same as for the built-in Tk
widgets. This is easily done:
% snit::widget mytext {
delegate option {-padx padX Pad} to text
# ...
}
::mytext
% mytext .text
.text
% .text configure -padx
-padx padX Pad 1 1
%
## <a name='subsection141'></a>How does Snit initialize my megawidget's locally-defined options?
The option database is queried for each of the megawidget's locally-defined
options, using the option's resource and class name. If the result isn't "",
then it replaces the default value given in widget definition. In either case,
the default can be overridden by the caller. For example,
option add *Mywidget.texture pebbled
snit::widget mywidget {
option -texture smooth
# ...
}
mywidget .mywidget -texture greasy
Here, __-texture__ would normally default to "smooth", but because of the entry
added to the option database it defaults to "pebbled". However, the caller has
explicitly overridden the default, and so the new widget will be "greasy".
## <a name='subsection142'></a>How does Snit initialize delegated options?
That depends on whether the options are delegated to the hull, or to some other
component.
## <a name='subsection143'></a>How does Snit initialize options delegated to the hull?
A __snit::widget__'s hull is a widget, and given that its class has been set it
is expected to query the option database for itself. The only exception concerns
options that are delegated to it with a different name. Consider the following
code:
option add *Mywidget.borderWidth 5
option add *Mywidget.relief sunken
option add *Mywidget.hullbackground red
option add *Mywidget.background green
snit::widget mywidget {
delegate option -borderwidth to hull
delegate option -hullbackground to hull as -background
delegate option * to hull
# ...
}
mywidget .mywidget
set A [.mywidget cget -relief]
set B [.mywidget cget -hullbackground]
set C [.mywidget cget -background]
set D [.mywidget cget -borderwidth]
The question is, what are the values of variables A, B, C and D?
The value of A is "sunken". The hull is a Tk frame which has been given the
widget class __Mywidget__; it will automatically query the option database and
pick up this value. Since the __-relief__ option is implicitly delegated to the
hull, Snit takes no action.
The value of B is "red". The hull will automatically pick up the value "green"
for its __-background__ option, just as it picked up the __-relief__ value.
However, Snit knows that __-hullbackground__ is mapped to the hull's
__-background__ option; hence, it queries the option database for
__-hullbackground__ and gets "red" and updates the hull accordingly.
The value of C is also "red", because __-background__ is implicitly delegated to
the hull; thus, retrieving it is the same as retrieving __-hullbackground__.
Note that this case is unusual; the __-background__ option should probably have
been excluded using the delegate statement's __except__ clause, or (more likely)
delegated to some other component.
The value of D is "5", but not for the reason you think. Note that as it is
defined above, the resource name for __-borderwidth__ defaults to
__borderwidth__, whereas the option database entry is __borderWidth__, in
accordance with the standard Tk naming for this option. As with __-relief__, the
hull picks up its own __-borderwidth__ option before Snit does anything. Because
the option is delegated under its own name, Snit assumes that the correct thing
has happened, and doesn't worry about it any further. To avoid confusion, the
__-borderwidth__ option should have been delegated like this:
delegate option {-borderwidth borderWidth BorderWidth} to hull
For __snit::widgetadaptor__s, the case is somewhat altered. Widget adaptors
retain the widget class of their hull, and the hull is not created automatically
by Snit. Instead, the __snit::widgetadaptor__ must call __installhull__ in its
constructor. The normal way to do this is as follows:
snit::widgetadaptor mywidget {
# ...
constructor {args} {
# ...
installhull using text -foreground white
# ...
}
# ...
}
In this case, the __installhull__ command will create the hull using a command
like this:
set hull [text $win -foreground white]
The hull is a __[text](../../../../index.md#text)__ widget, so its widget class
is __Text__. Just as with __snit::widget__ hulls, Snit assumes that it will pick
up all of its normal option values automatically, without help from Snit.
Options delegated from a different name are initialized from the option database
in the same way as described above.
In earlier versions of Snit, __snit::widgetadaptor__s were expected to call
__installhull__ like this:
installhull [text $win -foreground white]
This form still works--but Snit will not query the option database as described
above.
## <a name='subsection144'></a>How does Snit initialize options delegated to other components?
For hull components, Snit assumes that Tk will do most of the work
automatically. Non-hull components are somewhat more complicated, because they
are matched against the option database twice.
A component widget remains a widget still, and is therefore initialized from the
option database in the usual way. A __[text](../../../../index.md#text)__ widget
remains a __[text](../../../../index.md#text)__ widget whether it is a component
of a megawidget or not, and will be created as such.
But then, the option database is queried for all options delegated to the
component, and the component is initialized accordingly--provided that the
__install__ command is used to create it.
Before option database support was added to Snit, the usual way to create a
component was to simply create it in the constructor and assign its command name
to the component variable:
snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
set myComp [text $win.text -foreground black]
}
}
The drawback of this method is that Snit has no opportunity to initialize the
component properly. Hence, the following approach is now used:
snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
install myComp using text $win.text -foreground black
}
}
The __install__ command does the following:
- Builds a list of the options explicitly included in the __install__
command--in this case, __-foreground__.
- Queries the option database for all options delegated explicitly to the
named component.
- Creates the component using the specified command, after inserting into it a
list of options and values read from the option database. Thus, the
explicitly included options (like __-foreground__) will override anything
read from the option database.
- If the widget definition implicitly delegated options to the component using
__delegate option *__, then Snit calls the newly created component's
__configure__ method to receive a list of all of the component's options.
From this Snit builds a list of options implicitly delegated to the
component which were not explicitly included in the __install__ command. For
all such options, Snit queries the option database and configures the
component accordingly.
You don't really need to know all of this; just use __install__ to install your
components, and Snit will try to do the right thing.
## <a name='subsection145'></a>What happens if I install a non-widget as a component of widget?
A __snit::type__ never queries the option database. However, a __snit::widget__
can have non-widget components. And if options are delegated to those
components, and if the __install__ command is used to install those components,
then they will be initialized from the option database just as widget components
are.
However, when used within a megawidget, __install__ assumes that the created
component uses a reasonably standard widget-like creation syntax. If it doesn't,
don't use __install__.
# <a name='section20'></a>ENSEMBLE COMMANDS
## <a name='subsection146'></a>What is an ensemble command?
An ensemble command is a command with subcommands. Snit objects are all ensemble
commands; however, the term more usually refers to commands like the standard
Tcl commands __[string](../../../../index.md#string)__,
__[file](../../../../index.md#file)__, and __clock__. In a sense, these are
singleton objects--there's only one instance of them.
## <a name='subsection147'></a>How can I create an ensemble command using Snit?
There are two ways--as a __snit::type__, or as an instance of a __snit::type__.
## <a name='subsection148'></a>How can I create an ensemble command using an instance of a snit::type?
Define a type whose [INSTANCE METHODS](#section5) are the subcommands of your
ensemble command. Then, create an instance of the type with the desired name.
For example, the following code uses [DELEGATION](#section16) to create a
work-alike for the standard __[string](../../../../index.md#string)__ command:
snit::type ::mynamespace::mystringtype {
delegate method * to stringhandler
constructor {} {
set stringhandler string
}
}
::mynamespace::mystringtype mystring
We create the type in a namespace, so that the type command is hidden; then we
create a single instance with the desired name-- __mystring__, in this case.
This method has two drawbacks. First, it leaves the type command floating about.
More seriously, your shiny new ensemble command will have __info__ and
__destroy__ subcommands that you probably have no use for. But read on.
## <a name='subsection149'></a>How can I create an ensemble command using a snit::type?
Define a type whose [TYPE METHODS](#section9) are the subcommands of your
ensemble command.
For example, the following code uses [DELEGATION](#section16) to create a
work-alike for the standard __[string](../../../../index.md#string)__ command:
snit::type mystring {
delegate typemethod * to stringhandler
typeconstructor {
set stringhandler string
}
}
Now the type command itself is your ensemble command.
This method has only one drawback, and though it's major, it's also
surmountable. Your new ensemble command will have __create__, __info__ and
__destroy__ subcommands you don't want. And worse yet, since the __create__
method can be implicit, users of your command will accidentally be creating
instances of your __mystring__ type if they should mispell one of the
subcommands. The command will succeed--the first time--but won't do what's
wanted. This is very bad.
The work around is to set some [PRAGMAS](#section21), as shown here:
snit::type mystring {
pragma -hastypeinfo no
pragma -hastypedestroy no
pragma -hasinstances no
delegate typemethod * to stringhandler
typeconstructor {
set stringhandler string
}
}
Here we've used the __pragma__ statement to tell Snit that we don't want the
__info__ typemethod or the __destroy__ typemethod, and that our type has no
instances; this eliminates the __create__ typemethod and all related code. As a
result, our ensemble command will be well-behaved, with no unexpected
subcommands.
# <a name='section21'></a>PRAGMAS
## <a name='subsection150'></a>What is a pragma?
A pragma is an option you can set in your type definitions that affects how the
type is defined and how it works once it is defined.
## <a name='subsection151'></a>How do I set a pragma?
Use the __pragma__ statement. Each pragma is an option with a value; each time
you use the __pragma__ statement you can set one or more of them.
## <a name='subsection152'></a>How can I get rid of the "info" type method?
Set the __-hastypeinfo__ pragma to __no__:
snit::type dog {
pragma -hastypeinfo no
# ...
}
Snit will refrain from defining the __info__ type method.
## <a name='subsection153'></a>How can I get rid of the "destroy" type method?
Set the __-hastypedestroy__ pragma to __no__:
snit::type dog {
pragma -hastypedestroy no
# ...
}
Snit will refrain from defining the __destroy__ type method.
## <a name='subsection154'></a>How can I get rid of the "create" type method?
Set the __-hasinstances__ pragma to __no__:
snit::type dog {
pragma -hasinstances no
# ...
}
Snit will refrain from defining the __create__ type method; if you call the type
command with an unknown method name, you'll get an error instead of a new
instance of the type.
This is useful if you wish to use a __snit::type__ to define an ensemble command
rather than a type with instances.
Pragmas __-hastypemethods__ and __-hasinstances__ cannot both be false (or
there'd be nothing left).
## <a name='subsection155'></a>How can I get rid of type methods altogether?
Normal Tk widget type commands don't have subcommands; all they do is create
widgets--in Snit terms, the type command calls the __create__ type method
directly. To get the same behavior from Snit, set the __-hastypemethods__ pragma
to __no__:
snit::type dog {
pragma -hastypemethods no
#...
}
# Creates ::spot
dog spot
# Tries to create an instance called ::create
dog create spot
Pragmas __-hastypemethods__ and __-hasinstances__ cannot both be false (or
there'd be nothing left).
## <a name='subsection156'></a>Why can't I create an object that replaces an old object with the same name?
Up until Snit 0.95, you could use any name for an instance of a __snit::type__,
even if the name was already in use by some other object or command. You could
do the following, for example:
snit::type dog { ... }
dog proc
You now have a new dog named "proc", which is probably not something that you
really wanted to do. As a result, Snit now throws an error if your chosen
instance name names an existing command. To restore the old behavior, set the
__-canreplace__ pragma to __yes__:
snit::type dog {
pragma -canreplace yes
# ...
}
## <a name='subsection157'></a>How can I make my simple type run faster?
In Snit 1.x, you can set the __-simpledispatch__ pragma to __yes__.
Snit 1.x method dispatch is both flexible and fast, but the flexibility comes
with a price. If your type doesn't require the flexibility, the
__-simpledispatch__ pragma allows you to substitute a simpler dispatch mechanism
that runs quite a bit faster. The limitations are these:
- Methods cannot be delegated.
- __uplevel__ and __upvar__ do not work as expected: the caller's scope is two
levels up rather than one.
- The option-handling methods (__cget__, __configure__, and __configurelist__)
are very slightly slower.
In Snit 2.2, the __-simpledispatch__ macro is obsolete, and ignored; all Snit
2.2 method dispatch is faster than Snit 1.x's __-simpledispatch__.
# <a name='section22'></a>MACROS
## <a name='subsection158'></a>What is a macro?
A Snit macro is nothing more than a Tcl proc that's defined in the Tcl
interpreter used to compile Snit type definitions.
## <a name='subsection159'></a>What are macros good for?
You can use Snit macros to define new type definition syntax, and to support
conditional compilation.
## <a name='subsection160'></a>How do I do conditional compilation?
Suppose you want your type to use a fast C extension if it's available;
otherwise, you'll fallback to a slower Tcl implementation. You want to define
one set of methods in the first case, and another set in the second case. But
how can your type definition know whether the fast C extension is available or
not?
It's easily done. Outside of any type definition, define a macro that returns 1
if the extension is available, and 0 otherwise:
if {$gotFastExtension} {
snit::macro fastcode {} {return 1}
} else {
snit::macro fastcode {} {return 0}
}
Then, use your macro in your type definition:
snit::type dog {
if {[fastcode]} {
# Fast methods
method bark {} {...}
method wagtail {} {...}
} else {
# Slow methods
method bark {} {...}
method wagtail {} {...}
}
}
## <a name='subsection161'></a>How do I define new type definition syntax?
Use a macro. For example, your __snit::widget__'s __-background__ option should
be propagated to a number of component widgets. You could implement that like
this:
snit::widget mywidget {
option -background -default white -configuremethod PropagateBackground
method PropagateBackground {option value} {
$comp1 configure $option $value
$comp2 configure $option $value
$comp3 configure $option $value
}
}
For one option, this is fine; if you've got a number of options, it becomes
tedious and error prone. So package it as a macro:
snit::macro propagate {option "to" components} {
option $option -configuremethod Propagate$option
set body "\n"
foreach comp $components {
append body "\$$comp configure $option \$value\n"
}
method Propagate$option {option value} $body
}
Then you can use it like this:
snit::widget mywidget {
option -background default -white
option -foreground default -black
propagate -background to {comp1 comp2 comp3}
propagate -foreground to {comp1 comp2 comp3}
}
## <a name='subsection162'></a>Are there are restrictions on macro names?
Yes, there are. You can't redefine any standard Tcl commands or Snit type
definition statements. You can use any other command name, including the name of
a previously defined macro.
If you're using Snit macros in your application, go ahead and name them in the
global namespace, as shown above. But if you're using them to define types or
widgets for use by others, you should define your macros in the same namespace
as your types or widgets. That way, they won't conflict with other people's
macros.
If my fancy __snit::widget__ is called __::mylib::mywidget__, for example, then
I should define my __propagate__ macro as __::mylib::propagate__:
snit::macro mylib::propagate {option "to" components} { ... }
snit::widget ::mylib::mywidget {
option -background default -white
option -foreground default -black
mylib::propagate -background to {comp1 comp2 comp3}
mylib::propagate -foreground to {comp1 comp2 comp3}
}
# <a name='section23'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *snit* 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.
# <a name='keywords'></a>KEYWORDS
[BWidget](../../../../index.md#bwidget), [C++](../../../../index.md#c_), [Incr
Tcl](../../../../index.md#incr_tcl), [adaptors](../../../../index.md#adaptors),
[class](../../../../index.md#class), [mega
widget](../../../../index.md#mega_widget),
[object](../../../../index.md#object), [object
oriented](../../../../index.md#object_oriented),
[widget](../../../../index.md#widget), [widget
adaptors](../../../../index.md#widget_adaptors)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2006, by William H. Duquette
|
Added embedded/md/tcllib/files/modules/soundex/soundex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
[//000000001]: # (soundex - Soundex)
[//000000002]: # (Generated from file 'soundex.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (soundex(n) 1.0 tcllib "Soundex")
# NAME
soundex - Soundex
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require soundex ?1.0?
[__::soundex::knuth__ *string*](#1)
# <a name='description'></a>DESCRIPTION
This package provides soundex algorithms which allow the comparison of words
based on their phonetic likeness.
Currently only an algorithm by Knuth is provided, which is tuned to english
names and words.
- <a name='1'></a>__::soundex::knuth__ *string*
Computes the soundex code of the input *string* using Knuth's algorithm and
returns it as the result of the command.
# <a name='section2'></a>EXAMPLES
% ::soundex::knuth Knuth
K530
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *soundex* 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.
# <a name='keywords'></a>KEYWORDS
[knuth](../../../../index.md#knuth), [soundex](../../../../index.md#soundex),
[text comparison](../../../../index.md#text_comparison), [text
likeness](../../../../index.md#text_likeness)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © ????, Algorithm: Donald E. Knuth
Copyright © 2003, Documentation: Andreas Kupries <[email protected]>
Copyright © 1998, Tcl port: Evan Rempel <[email protected]>
|
Added embedded/md/tcllib/files/modules/stooop/stooop.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
[//000000001]: # (stooop - Simple Tcl Only Object Oriented Programming)
[//000000002]: # (Generated from file 'stooop.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (stooop(n) 4.4.1 tcllib "Simple Tcl Only Object Oriented Programming")
# NAME
stooop - Object oriented extension.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [DEBUGGING](#section2)
- [EXAMPLES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require stooop ?4.4.1?
[__::stooop::class__ *name body*](#1)
[__::stooop::new__ *class* ?*arg arg ...*?](#2)
[__::stooop::delete__ *object* ?*object ...*?](#3)
[__::stooop::virtual__ __proc__ *name* {__this__ ?*arg arg ...*?} ?*body*?](#4)
[__::stooop::classof__ *object*](#5)
[__::stooop::new__ *object*](#6)
[__::stooop::printObjects__ ?*pattern*?](#7)
[__::stooop::record__](#8)
[__::stooop::report__ ?*pattern*?](#9)
# <a name='description'></a>DESCRIPTION
This package provides commands to extend Tcl in an object oriented manner, using
a familiar C++ like syntax and behaviour. Stooop only introduces a few new
commands: __[class](../../../../index.md#class)__, __new__, __delete__,
__virtual__ and __classof__. Along with a few coding conventions, that is
basically all you need to know to use stooop. Stooop is meant to be as simple to
use as possible.
This manual is very succinct and is to be used as a quick reminder for the
programmer, who should have read the thorough [stooop_man.html](stooop_man.html)
HTML documentation at this point.
- <a name='1'></a>__::stooop::class__ *name body*
This command creates a class. The body, similar in contents to a Tcl
namespace (which a class actually also is), contains member procedure
definitions. Member procedures can also be defined outside the class body,
by prefixing their name with __class::__, as you would proceed with
namespace procedures.
* __[proc](../../../../index.md#proc)__ *class* {__this__ ?*arg arg ...*?} ?*base* {?*arg arg ...*?} ...? *body*
This is the constructor procedure for the class. It is invoked following
a __new__ invocation on the class. It must have the same name as the
class and a first argument named __this__. Any number of base classes
specifications, including arguments to be passed to their constructor,
are allowed before the actual body of the procedure.
* __[proc](../../../../index.md#proc)__ ~*class* {__this__} *body*
This is the destructor procedure for the class. It is invoked following
a __delete__ invocation. Its name must be the concatenation of a single
__~__ character followed by the class name (as in C++). It must have a
single argument named __this__.
* __[proc](../../../../index.md#proc)__ *name* {__this__ ?*arg arg ...*?} *body*
This is a member procedure of the class, as its first argument is named
__this__. It allows a simple access of member data for the object
referenced by __this__ inside the procedure. For example:
set ($this,data) 0
* __[proc](../../../../index.md#proc)__ *name* {?*arg arg ...*?} *body*
This is a static (as in C++) member procedure of the class, as its first
argument is not named __this__. Static (global) class data can be
accessed as in:
set (data) 0
* __[proc](../../../../index.md#proc)__ *class* {__this copy__} *body*
This is the optional copy procedure for the class. It must have the same
name as the class and exactly 2 arguments named __this__ and __copy__.
It is invoked following a __new__ invocation on an existing object of
the class.
- <a name='2'></a>__::stooop::new__ *class* ?*arg arg ...*?
This command is used to create an object. The first argument is the class
name and is followed by the arguments needed by the corresponding class
constructor. A unique identifier for the object just created is returned.
- <a name='3'></a>__::stooop::delete__ *object* ?*object ...*?
This command is used to delete one or several objects. It takes one or more
object identifiers as argument(s).
- <a name='4'></a>__::stooop::virtual__ __proc__ *name* {__this__ ?*arg arg ...*?} ?*body*?
The __virtual__ specifier may be used on member procedures to achieve
dynamic binding. A procedure in a base class can then be redefined
(overloaded) in the derived class(es). If the base class procedure is
invoked on an object, it is actually the derived class procedure which is
invoked, if it exists. If the base class procedure has no body, then it is
considered to be a pure virtual and the derived class procedure is always
invoked.
- <a name='5'></a>__::stooop::classof__ *object*
This command returns the class of the existing object passed as single
parameter.
- <a name='6'></a>__::stooop::new__ *object*
This command is used to create an object by copying an existing object. The
copy constructor of the corresponding class is invoked if it exists,
otherwise a simple copy of the copied object data members is performed.
# <a name='section2'></a>DEBUGGING
- Environment variables
* __STOOOPCHECKDATA__
Setting this variable to any true value will cause stooop to check for
invalid member or class data access.
* __STOOOPCHECKPROCEDURES__
Setting this variable to any true value will cause stooop to check for
invalid member procedure arguments and pure interface classes
instanciation.
* __STOOOPCHECKALL__
Setting this variable to any true value will cause stooop to activate
both procedure and data member checking.
* __STOOOPCHECKOBJECTS__
Setting this variable to any true value will cause stooop to activate
object checking. The following stooop namespace procedures then become
available for debugging: __printObjects__,
__[record](../../../../index.md#record)__ and
__[report](../report/report.md)__.
* __STOOOPTRACEPROCEDURES__
Setting this environment variable to either __stdout__, __stderr__ or a
file name, activates procedure tracing. The stooop library will then
output to the specified channel 1 line of informational text for each
member procedure invocation.
* __STOOOPTRACEPROCEDURESFORMAT__
Defines the trace procedures output format. Defaults to __"class: %C,
procedure: %p, object: %O, arguments: %a"__.
* __STOOOPTRACEDATA__
Setting this environment variable to either __stdout__, __stderr__ or a
file name, activates data tracing. The stooop library will then output
to the specified channel 1 line of informational text for each member
data access.
* __STOOOPTRACEDATAFORMAT__
Defines the trace data output format. Defaults to __"class: %C,
procedure: %p, array: %A, object: %O, member: %m, operation: %o, value:
%v"__.
* __STOOOPTRACEDATAOPERATIONS__
When tracing data output, by default, all read, write and unsetting
accesses are reported, but the user can set this variable to any
combination of the letters __r__, __w__, and __u__ for more specific
tracing (please refer to the __[trace](../../../../index.md#trace)__ Tcl
manual page for more information).
* __STOOOPTRACEALL__
Setting this environment variable to either __stdout__, __stderr__ or a
file name, enables both procedure and data tracing.
- <a name='7'></a>__::stooop::printObjects__ ?*pattern*?
Prints an ordered list of existing objects, in creation order, oldest first.
Each output line contains the class name, object identifier and the
procedure within which the creation occurred. The optional pattern argument
(as in the Tcl __string match__ command) can be used to limit the output to
matching class names.
- <a name='8'></a>__::stooop::record__
When invoked, a snapshot of all existing stooop objects is taken. Reporting
can then be used at a later time to see which objects were created or
deleted in the interval.
- <a name='9'></a>__::stooop::report__ ?*pattern*?
Prints the created and deleted objects since the __::stooop::record__
procedure was invoked last. If present, the pattern argument limits the
output to matching class names.
# <a name='section3'></a>EXAMPLES
Please see the full HTML documentation in [stooop_man.html](stooop_man.html).
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *stooop* 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.
# <a name='keywords'></a>KEYWORDS
[C++](../../../../index.md#c_), [class](../../../../index.md#class),
[object](../../../../index.md#object), [object
oriented](../../../../index.md#object_oriented)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/stooop/switched.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
[//000000001]: # (switched - Simple Tcl Only Object Oriented Programming)
[//000000002]: # (Generated from file 'switched.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (switched(n) 2.2.1 tcllib "Simple Tcl Only Object Oriented Programming")
# NAME
switched - switch/option management.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require switched ?2.2.1?
[__<switched>__ __complete__ *this*](#1)
[__<switched>__ __options__ *this*](#2)
[__<switched>__ __set-__option____ *this* *value*](#3)
# <a name='description'></a>DESCRIPTION
The __switched__ class serves as base class for user classes with switch /
option configuration procedures. It provides facilities for managing options
through a simple interface.
For example:
set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel]
puts "my car was running on [switched::cget $vehicle -fuel]"
switched::configure $vehicle -power 40 -fuel electricity
puts "but is now running on clean [switched::cget $vehicle -fuel]"
Of course, as you might have guessed, the __car__ class is derived from the
__switched__ class. Let us see how it works:
class car {
proc car {this args} switched {$args} {
# car specific initialization code here
switched::complete $this
}
...
}
The switched class constructor takes the optional configuration option / value
pairs as parameters. The switched class layer then completely manages the
switched options: it checks their validity, stores their values and provides a
clean interface to the user layer configuration setting procedures.
The switched class members available to the programmer are:
- <a name='1'></a>__<switched>__ __complete__ *this*
This procedure is used to tell the switched layer that the derived class
object (a car in the examples) is completely built. At that time, the
initial configuration of the switched object occurs, using default option
values (see procedure __options__) eventually overridden by construction
time values, passed at the time of the __new__ operator invocation. This
procedure must be called only once, usually around or at the end of the
derived class constructor. (*Note*: Also check the __complete__ data member
later in this chapter).
- <a name='2'></a>__<switched>__ __options__ *this*
This procedure must return the configuration description for *all* options
that the switched object will accept. It is a pure virtual member procedure
and therefore its implementation is *mandatory* in the derived class layer.
The procedure must return a list of lists. Each list pertains to a single
option and is composed of the switch name, the default value for the option
and an optional initial value. For example:
class car {
...
proc options {this} {
return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ]
}
proc set-fuel {this value} {
...
}
...
}
In this case, 4 options are specified: __fuel__, __length__, __power__ and
__width__. The default and initial values for the __fuel__ option are
identical and set to __petrol__. For the other options, values are all
empty.
For each option, there must be a corresponding __set-__option____ procedure
defined in the derived class layer. For example, since we defined a __fuel__
option, there is a __set-fuel__ procedure in the car class. The parameters
always are the object identifier (since this is not a static procedure, but
rather a dynamically defined virtual one), followed by the new value for the
option. A __set-__option____ procedure is only invoked if the new value
differs from the current one (a caching scheme for improving performance),
or if there is no initial value set in the __options__ procedure for that
option.
In this procedure, if the initial value differs from the default value or is
omitted, then initial configuration is forced and the corresponding
__set-__option____ procedure is invoked by the switched __complete__
procedure located at the end of the derived class constructor. For example:
class car {
...
proc options {this} {
return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ]
}
...
}
In this case, configuration is forced on the __fuel__ and __power__ options,
that is the corresponding __set-__option____ procedures will be invoked when
the switched object is constructed (see __set-__option____ procedures
documentation below).
For the __fuel__ option, since there is no initial value, the
__set-__fuel____ procedure is called with the default value (__petrol__) as
argument. For the __power__ option, since the initial value differs from the
default value, the __set-__power____ procedure is called with the initial
value as argument (__50__).
For the other options, since the initial values (last elements of the option
lists) are identical to their default values, the corresponding
__set-__option____ procedures will not be invoked. It is the programmer's
responsibility to insure that the initial option values are correct.
- <a name='3'></a>__<switched>__ __set-__option____ *this* *value*
These procedures may be viewed as dynamic virtual functions. There must be
one implementation per supported option, as returned by the __options__
procedure. For example:
class car {
...
proc options {this} {
return [list ...
[list -width {} {}] ]
}
...
proc set-width {this value} {
...
}
...
}
Since the __-width__ option was listed in the __options__ procedure, a
__set-width__ procedure implementation is provided, which of course would
proceed to set the width of the car (and would modify the looks of a
graphical representation, for example).
As you add a supported __option__ in the list returned by the __options__
procedure, the corresponding __set-__option____ procedure may be called as
soon as the switched object is complete, which occurs when the switched
level __complete__ procedure is invoked. For example:
class car {
proc car {this args} switched {args} {
...
switched::complete $this
}
...
proc options {this} {
return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ]
}
proc set-fuel {this value} {
...
}
proc set-length {this value} {
...
}
proc set-power {this value} {
...
}
proc set-width {this value} {
...
}
}
new car
In this case, a new car is created with no options, which causes the car
constructor to be called, which in turns calls the switched level
__complete__ procedure after the car object layer is completely initialized.
At this point, since there are no initial values in any option list in the
options procedure, the __set-fuel__ procedure is called with its default
value of __petrol__ as parameter, followed by the __set-length__ call with
__4.5__ value, __set-power__ with __350__ value and finally with
__set-width__ with __1.8__ as parameter. This is a good way to test the
__set-__option____ procedures when debugging, and when done, just fill-in
the initial option values.
The switched layer checks that an option is valid (that is, listed in the
__options__ procedure) but obviously does not check the validity of the
value passed to the __set-__option____ procedure, which should throw an
error (for example by using the Tcl error command) if the value is invalid.
The switched layer also keeps track of the options current values, so that a
__set-__option____ procedure is called only when the corresponding option
value passed as parameter is different from the current value (see
__-option__ data members description).
- __-option__
The __-option__ data member is an options current value. There is one for
each option listed in the options procedure. It is a read-only value which
the switched layer checks against when an option is changed. It is rarely
used at the layer derived from switched, except in the few cases, such as in
the following example:
...
proc car::options {this} {
return {
...
{-manufacturer {} {}}
...
}
}
proc car::set-manufacturer {this value} {}
proc car::printData {this} {
puts "manufacturer: $switched::($this,-manufacturer)"
...
}
In this case, the manufacturer's name is stored at the switched layer level
(this is why the set-manufacturer procedure has nothing to do) and later
retrieved in the printData procedure.
- __complete__
The __complete__ data member (not to be confused with the __complete__
procedure) is a boolean. Its initial value is __false__ and it is set to
__true__ at the very end of the switched __complete__ procedure. It becomes
useful when some options should be set at construction time only and not
dynamically, as the following example shows:
proc car::set-width {this value} {
if {$switched::($this,complete)} {
error {option -width cannot be set dynamically}
}
...
}
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *stooop* 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.
# <a name='keywords'></a>KEYWORDS
[C++](../../../../index.md#c_), [class](../../../../index.md#class),
[object](../../../../index.md#object), [object
oriented](../../../../index.md#object_oriented)
# <a name='category'></a>CATEGORY
Programming tools
|
Added embedded/md/tcllib/files/modules/string/token.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
[//000000001]: # (string::token - Text and string utilities)
[//000000002]: # (Generated from file 'token.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (string::token(n) 1 tcllib "Text and string utilities")
# NAME
string::token - Regex based iterative lexing
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require string::token ?1?
package require fileutil
[__::string token text__ *lex* *string*](#1)
[__::string token file__ *lex* *path*](#2)
[__::string token chomp__ *lex* *startvar* *string* *resultvar*](#3)
# <a name='description'></a>DESCRIPTION
This package provides commands for regular expression based lexing
(tokenization) of strings.
The complete set of procedures is described below.
- <a name='1'></a>__::string token text__ *lex* *string*
This command takes an ordered dictionary *lex* mapping regular expressions
to labels, and tokenizes the *string* according to this dictionary.
The result of the command is a list of tokens, where each token is a
3-element list of label, start- and end-index in the *string*.
The command will throw an error if it is not able to tokenize the whole
string.
- <a name='2'></a>__::string token file__ *lex* *path*
This command is a convenience wrapper around __::string token text__ above,
and __fileutil::cat__, enabling the easy tokenization of whole files. *Note*
that this command loads the file wholly into memory before starting to
process it.
If the file is too large for this mode of operation a command directly based
on __::string token chomp__ below will be necessary.
- <a name='3'></a>__::string token chomp__ *lex* *startvar* *string* *resultvar*
This command is the work horse underlying __::string token text__ above. It
is exposed to enable users to write their own lexers, which, for example may
apply different lexing dictionaries according to some internal state, etc.
The command takes an ordered dictionary *lex* mapping regular expressions to
labels, a variable *startvar* which indicates where to start lexing in the
input *string*, and a result variable *resultvar* to extend.
The result of the command is a tri-state numeric code indicating one of
* __0__
No token found.
* __1__
Token found.
* __2__
End of string reached.
Note that recognition of a token from *lex* is started at the character
index in *startvar*.
If a token was recognized (status __1__) the command will update the index
in *startvar* to point to the first character of the *string* past the
recognized token, and it will further extend the *resultvar* with a
3-element list containing the label associated with the regular expression
of the token, and the start- and end-character-indices of the token in
*string*.
Neither *startvar* nor *resultvar* will be updated if no token is recognized
at all.
Note that the regular expressions are applied (tested) in the order they are
specified in *lex*, and the first matching pattern stops the process.
Because of this it is recommended to specify the patterns to lex with from
the most specific to the most general.
Further note that all regex patterns are implicitly prefixed with the
constraint escape __A__ to ensure that a match starts exactly at the
character index found in *startvar*.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='keywords'></a>KEYWORDS
[lexing](../../../../index.md#lexing), [regex](../../../../index.md#regex),
[string](../../../../index.md#string),
[tokenization](../../../../index.md#tokenization)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/string/token_shell.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
[//000000001]: # (string::token::shell - Text and string utilities)
[//000000002]: # (Generated from file 'token_shell.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (string::token::shell(n) 1.2 tcllib "Text and string utilities")
# NAME
string::token::shell - Parsing of shell command line
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require string::token::shell ?1.2?
package require string::token ?1?
package require fileutil
[__::string token shell__ ?__-indices__? ?__-partial__? ?--? *string*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a command which parses a line of text using basic
__sh__-syntax into a list of words.
The complete set of procedures is described below.
- <a name='1'></a>__::string token shell__ ?__-indices__? ?__-partial__? ?--? *string*
This command parses the input *string* under the assumption of it following
basic __sh__-syntax. The result of the command is a list of words in the
*string*. An error is thrown if the input does not follow the allowed
syntax. The behaviour can be modified by specifying any of the two options
__-indices__ and __-partial__.
* __--__
When specified option parsing stops at this point. This option is needed
if the input *string* may start with dash. In other words, this is
pretty much required if *string* is user input.
* __-indices__
When specified the output is not a list of words, but a list of 4-tuples
describing the words. Each tuple contains the type of the word, its
start- and end-indices in the input, and the actual text of the word.
Note that the length of the word as given by the indices can differ from
the length of the word found in the last element of the tuple. The
indices describe the words extent in the input, including delimiters,
intra-word quoting, etc. whereas for the actual text of the word
delimiters are stripped, intra-word quoting decoded, etc.
The possible token types are
+ __PLAIN__
Plain word, not quoted.
+ __D:QUOTED__
Word is delimited by double-quotes.
+ __S:QUOTED__
Word is delimited by single-quotes.
+ __D:QUOTED:PART__
+ __S:QUOTED:PART__
Like the previous types, but the word has no closing quote, i.e. is
incomplete. These token types can occur if and only if the option
__-partial__ was specified, and only for the last word of the
result. If the option __-partial__ was not specified such incomplete
words cause the command to thrown an error instead.
* __-partial__
When specified the parser will accept an incomplete quoted word (i.e.
without closing quote) at the end of the line as valid instead of
throwing an error.
The basic shell syntax accepted here are unquoted, single- and double-quoted
words, separated by whitespace. Leading and trailing whitespace are possible
too, and stripped. Shell variables in their various forms are *not*
recognized, nor are sub-shells. As for the recognized forms of words, see
below for the detailed specification.
* __single-quoted word__
A single-quoted word begins with a single-quote character, i.e. __'__
(ASCII 39) followed by zero or more unicode characters not a
single-quote, and then closed by a single-quote.
The word must be followed by either the end of the string, or
whitespace. A word cannot directly follow the word.
* __double-quoted word__
A double-quoted word begins with a double-quote character, i.e. __"__
(ASCII 34) followed by zero or more unicode characters not a
double-quote, and then closed by a double-quote.
Contrary to single-quoted words a double-quote can be embedded into the
word, by prefacing, i.e. escaping, i.e. quoting it with a backslash
character __\__ (ASCII 92). Similarly a backslash character must be
quoted with itself to be inserted literally.
* __unquoted word__
Unquoted words are not delimited by quotes and thus cannot contain
whitespace or single-quote characters. Double-quote and backslash
characters can be put into unquoted words, by quting them like for
double-quoted words.
* __whitespace__
Whitespace is any unicode space character. This is equivalent to
__string is space__, or the regular expression \\s.
Whitespace may occur before the first word, or after the last word.
Whitespace must occur between adjacent words.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='keywords'></a>KEYWORDS
[bash](../../../../index.md#bash), [lexing](../../../../index.md#lexing),
[parsing](../../../../index.md#parsing), [shell](../../../../index.md#shell),
[string](../../../../index.md#string),
[tokenization](../../../../index.md#tokenization)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/stringprep/stringprep.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
[//000000001]: # (stringprep - Preparation of Internationalized Strings)
[//000000002]: # (Generated from file 'stringprep.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (stringprep(n) 1.0.1 tcllib "Preparation of Internationalized Strings")
# NAME
stringprep - Implementation of stringprep
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require stringprep 1.0.1
[__::stringprep::register__ *profile* ?*-mapping list*? ?*-normalization form*? ?*-prohibited list*? ?*-prohibitedList list*? ?*-prohibitedCommand command*? ?*-prohibitedBidi boolean*?](#1)
[__::stringprep::stringprep__ *profile* *string*](#2)
[__::stringprep::compare__ *profile* *string1* *string2*](#3)
# <a name='description'></a>DESCRIPTION
This is an implementation in Tcl of the Preparation of Internationalized Strings
("stringprep"). It allows to define stringprep profiles and use them to prepare
Unicode strings for comparison as defined in RFC-3454.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::stringprep::register__ *profile* ?*-mapping list*? ?*-normalization form*? ?*-prohibited list*? ?*-prohibitedList list*? ?*-prohibitedCommand command*? ?*-prohibitedBidi boolean*?
Register the __stringprep__ profile named *profile*. Options are the
following.
Option *-mapping* specifies __stringprep__ mapping tables. This parameter
takes list of tables from appendix B of RFC-3454. The usual list values are
{B.1 B.2} or {B.1 B.3} where B.1 contains characters which commonly map to
nothing, B.3 specifies case folding, and B.2 is used in profiles with
unicode normalization form KC. Defult value is {} which means no mapping.
Option *-normalization* takes a string and if it is nonempty then it uses as
a name of Unicode normalization form. Any value of "D", "C", "KD" or "KC"
may be used, though RFC-3454 defines only two options: no normalization or
normalization using form KC.
Option *-prohibited* takes a list of RFC-3454 tables with prohibited
characters. Current version does allow to prohibit either all tables from
C.3 to C.9 or neither of them. An example of this list for RFC-3491 is {A.1
C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}.
Option *-prohibitedList* specifies a list of additional prohibited
characters. The list contains not characters themselves but their Unicode
numbers. For example, Nodeprep specification from RFC-3920 forbids the
following codes: {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} (\" \& \' / : < >
@).
Option *-prohibitedCommand* specifies a command which is called for every
character code in mapped and normalized string. If the command returns true
then the character is considered prohibited. This option is useful when a
list for *-prohibitedList* is too large.
Option *-prohibitedBidi* takes boolean value and if it is true then the
bidirectional character processing rules defined in section 6 of RFC-3454
are used.
- <a name='2'></a>__::stringprep::stringprep__ *profile* *string*
Performs __stringprep__ operations defined in profile *profile* to string
*string*. Result is a prepared string or one of the following errors:
*invalid_profile* (profile *profile* is not defined), *prohibited_character*
(string *string* contains a prohibited character) or *prohibited_bidi*
(string *string* contains a prohibited bidirectional sequence).
- <a name='3'></a>__::stringprep::compare__ *profile* *string1* *string2*
Compares two unicode strings prepared accordingly to __stringprep__ profile
*profile*. The command returns 0 if prepared strings are equal, -1 if
*string1* is lexicographically less than *string2*, or 1 if *string1* is
lexicographically greater than *string2*.
# <a name='section3'></a>EXAMPLES
Nameprep profile definition (see RFC-3491):
::stringprep::register nameprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1
Nodeprep and resourceprep profile definitions (see RFC-3920):
::stringprep::register nodeprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedList {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} -prohibitedBidi 1
::stringprep::register resourceprep -mapping {B.1} -normalization KC -prohibited {A.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1
# <a name='section4'></a>REFERENCES
1. "Preparation of Internationalized Strings ('stringprep')",
([http://www.ietf.org/rfc/rfc3454.txt](http://www.ietf.org/rfc/rfc3454.txt))
1. "Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)",
([http://www.ietf.org/rfc/rfc3491.txt](http://www.ietf.org/rfc/rfc3491.txt))
1. "Extensible Messaging and Presence Protocol (XMPP): Core",
([http://www.ietf.org/rfc/rfc3920.txt](http://www.ietf.org/rfc/rfc3920.txt))
# <a name='section5'></a>AUTHORS
Sergei Golovan
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *stringprep* 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.
# <a name='see-also'></a>SEE ALSO
[unicode(n)](unicode.md)
# <a name='keywords'></a>KEYWORDS
[stringprep](../../../../index.md#stringprep),
[unicode](../../../../index.md#unicode)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2009, Sergei Golovan <[email protected]>
|
Added embedded/md/tcllib/files/modules/stringprep/stringprep_data.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
|
[//000000001]: # (stringprep::data - Preparation of Internationalized Strings)
[//000000002]: # (Generated from file 'stringprep_data.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (stringprep::data(n) 1.0.1 tcllib "Preparation of Internationalized Strings")
# NAME
stringprep::data - stringprep data tables, generated, internal
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require stringprep::data 1.0.1
# <a name='description'></a>DESCRIPTION
The __stringprep::data__ package is a helper for
__[stringprep](stringprep.md)__, providing it with the data tables needed to
perform its functions. It is an *internal* package which should not be accessed
on its own. Because of that it has no publicly documented API either. Its
implementation is generated by a script.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *stringprep* 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.
# <a name='keywords'></a>KEYWORDS
[stringprep](../../../../index.md#stringprep),
[unicode](../../../../index.md#unicode)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2009, Sergei Golovan <[email protected]>
|
Added embedded/md/tcllib/files/modules/stringprep/unicode.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
[//000000001]: # (unicode - Unicode normalization)
[//000000002]: # (Generated from file 'unicode.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (unicode(n) 1.0.0 tcllib "Unicode normalization")
# NAME
unicode - Implementation of Unicode normalization
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require unicode 1.0
[__::unicode::fromstring__ *string*](#1)
[__::unicode::tostring__ *uclist*](#2)
[__::unicode::normalize__ *form* *uclist*](#3)
[__::unicode::normalizeS__ *form* *string*](#4)
# <a name='description'></a>DESCRIPTION
This is an implementation in Tcl of the Unicode normalization forms.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::unicode::fromstring__ *string*
Converts *string* to list of integer Unicode character codes which is used
in __unicode__ for internal string representation.
- <a name='2'></a>__::unicode::tostring__ *uclist*
Converts list of integers *uclist* back to Tcl string.
- <a name='3'></a>__::unicode::normalize__ *form* *uclist*
Normalizes Unicode characters list *ulist* according to *form* and returns
the normalized list. Form *form* takes one of the following values: *D*
(canonical decomposition), *C* (canonical decomposition, followed by
canonical composition), *KD* (compatibility decomposition), or *KC*
(compatibility decomposition, followed by canonical composition).
- <a name='4'></a>__::unicode::normalizeS__ *form* *string*
A shortcut to ::unicode::tostring [unicode::normalize \$form
[::unicode::fromstring \$string]]. Normalizes Tcl string and returns
normalized string.
# <a name='section3'></a>EXAMPLES
% ::unicode::fromstring "\u0410\u0411\u0412\u0413"
1040 1041 1042 1043
% ::unicode::tostring {49 50 51 52 53}
12345
%
% ::unicode::normalize D {7692 775}
68 803 775
% ::unicode::normalizeS KD "\u1d2c"
A
%
# <a name='section4'></a>REFERENCES
1. "Unicode Standard Annex #15: Unicode Normalization Forms",
([http://unicode.org/reports/tr15/](http://unicode.org/reports/tr15/))
# <a name='section5'></a>AUTHORS
Sergei Golovan
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *stringprep* 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.
# <a name='see-also'></a>SEE ALSO
[stringprep(n)](stringprep.md)
# <a name='keywords'></a>KEYWORDS
[normalization](../../../../index.md#normalization),
[unicode](../../../../index.md#unicode)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007, Sergei Golovan <[email protected]>
|
Added embedded/md/tcllib/files/modules/stringprep/unicode_data.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
|
[//000000001]: # (unicode::data - Preparation of Internationalized Strings)
[//000000002]: # (Generated from file 'unicode_data.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (unicode::data(n) 1.0.0 tcllib "Preparation of Internationalized Strings")
# NAME
unicode::data - unicode data tables, generated, internal
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require unicode::data 1.0.0
# <a name='description'></a>DESCRIPTION
The __unicode::data__ package is a helper for __[unicode](unicode.md)__,
providing it with the data tables needed to perform its functions. It is an
*internal* package which should not be accessed on its own. Because of that it
has no publicly documented API either. Its implementation is generated by a
script.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *stringprep* 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.
# <a name='keywords'></a>KEYWORDS
[stringprep](../../../../index.md#stringprep),
[unicode](../../../../index.md#unicode)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007, Sergei Golovan <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/disjointset.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
[//000000001]: # (struct::disjointset - Tcl Data Structures)
[//000000002]: # (Generated from file 'disjointset.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::disjointset(n) 1.1 tcllib "Tcl Data Structures")
# NAME
struct::disjointset - Disjoint set data structure
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require struct::disjointset ?1.1?
[__::struct::disjointset__ *disjointsetName*](#1)
[*disjointsetName* *option* ?*arg arg ...*?](#2)
[*disjointsetName* __add-element__ *item*](#3)
[*disjointsetName* __add-partition__ *elements*](#4)
[*disjointsetName* __partitions__](#5)
[*disjointsetName* __num-partitions__](#6)
[*disjointsetName* __equal__ *a* *b*](#7)
[*disjointsetName* __merge__ *a* *b*](#8)
[*disjointsetName* __find__ *e*](#9)
[*disjointsetName* __exemplars__](#10)
[*disjointsetName* __find-exemplar__ *e*](#11)
[*disjointsetName* __destroy__](#12)
# <a name='description'></a>DESCRIPTION
This package provides *disjoint sets*. An alternative name for this kind of
structure is *merge-find*.
Normally when dealing with sets and their elements the question is "Is this
element E contained in this set S?", with both E and S known.
Here the question is "Which of several sets contains the element E?". I.e. while
the element is known, the set is not, and we wish to find it quickly. It is not
quite the inverse of the original question, but close. Another operation which
is often wanted is that of quickly merging two sets into one, with the result
still fast for finding elements. Hence the alternative term *merge-find* for
this.
Why now is this named a *disjoint-set* ? Because another way of describing the
whole situation is that we have
- a finite *[set](../../../../index.md#set)* S, containing
- a number of *elements* E, split into
- a set of *partitions* P. The latter term applies, because the intersection
of each pair P, P' of partitions is empty, with the union of all partitions
covering the whole set.
- An alternative name for the *partitions* would be *equvalence classes*, and
all elements in the same class are considered as equal.
Here is a pictorial representation of the concepts listed above:
+-----------------+ The outer lines are the boundaries of the set S.
| / | The inner regions delineated by the skewed lines
| * / * | are the partitions P. The *'s denote the elements
| * / \ | E in the set, each in a single partition, their
|* / \ | equivalence class.
| / * \ |
| / * / |
| * /\ * / |
| / \ / |
| / \/ * |
| / * \ |
| / * \ |
+-----------------+
For more information see
[http://en.wikipedia.org/wiki/Disjoint_set_data_structure](http://en.wikipedia.org/wiki/Disjoint_set_data_structure).
# <a name='section2'></a>API
The package exports a single command, __::struct::disjointset__. All
functionality provided here can be reached through a subcommand of this command.
- <a name='1'></a>__::struct::disjointset__ *disjointsetName*
Creates a new disjoint set object with an associated global Tcl command
whose name is *disjointsetName*. This command may be used to invoke various
operations on the disjointset. It has the following general form:
* <a name='2'></a>*disjointsetName* *option* ?*arg arg ...*?
The __option__ and the *arg*s determine the exact behavior of the
command. The following commands are possible for disjointset objects:
- <a name='3'></a>*disjointsetName* __add-element__ *item*
Creates a new partition in the specified disjoint set, and fills it with the
single item *item*. The command maintains the integrity of the disjoint set,
i.e. it verifies that none of the *elements* are already part of the
disjoint set and throws an error otherwise.
The result of this method is the empty string.
This method runs in constant time.
- <a name='4'></a>*disjointsetName* __add-partition__ *elements*
Creates a new partition in specified disjoint set, and fills it with the
values found in the set of *elements*. The command maintains the integrity
of the disjoint set, i.e. it verifies that none of the *elements* are
already part of the disjoint set and throws an error otherwise.
The result of the command is the empty string.
This method runs in time proportional to the size of *elements*].
- <a name='5'></a>*disjointsetName* __partitions__
Returns the set of partitions the named disjoint set currently consists of.
The form of the result is a list of lists; the inner lists contain the
elements of the partitions.
This method runs in time O(N*alpha(N)), where N is the number of elements in
the disjoint set and alpha is the inverse Ackermann function.
- <a name='6'></a>*disjointsetName* __num-partitions__
Returns the number of partitions the named disjoint set currently consists
of.
This method runs in constant time.
- <a name='7'></a>*disjointsetName* __equal__ *a* *b*
Determines if the two elements *a* and *b* of the disjoint set belong to the
same partition. The result of the method is a boolean value, __True__ if the
two elements are contained in the same partition, and __False__ otherwise.
An error will be thrown if either *a* or *b* are not elements of the
disjoint set.
This method runs in amortized time O(alpha(N)), where N is the number of
elements in the larger partition and alpha is the inverse Ackermann
function.
- <a name='8'></a>*disjointsetName* __merge__ *a* *b*
Determines the partitions the elements *a* and *b* are contained in and
merges them into a single partition. If the two elements were already
contained in the same partition nothing will change.
The result of the method is the empty string.
This method runs in amortized time O(alpha(N)), where N is the number of
items in the larger of the partitions being merged. The worst case time is
O(N).
- <a name='9'></a>*disjointsetName* __find__ *e*
Returns a list of the members of the partition of the disjoint set which
contains the element *e*.
This method runs in O(N*alpha(N)) time, where N is the total number of items
in the disjoint set and alpha is the inverse Ackermann function, See
__find-exemplar__ for a faster method, if all that is needed is a unique
identifier for the partition, rather than an enumeration of all its
elements.
- <a name='10'></a>*disjointsetName* __exemplars__
Returns a list containing an exemplar of each partition in the disjoint set.
The exemplar is a member of the partition, chosen arbitrarily.
This method runs in O(N*alpha(N)) time, where N is the total number of items
in the disjoint set and alpha is the inverse Ackermann function.
- <a name='11'></a>*disjointsetName* __find-exemplar__ *e*
Returns the exemplar of the partition of the disjoint set containing the
element *e*. Throws an error if *e* is not found in the disjoint set. The
exemplar is an arbitrarily chosen member of the partition. The only
operation that will change the exemplar of any partition is __merge__.
This method runs in O(alpha(N)) time, where N is the number of items in the
partition containing E, and alpha is the inverse Ackermann function.
- <a name='12'></a>*disjointsetName* __destroy__
Destroys the disjoint set object and all associated memory.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: disjointset* 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.
# <a name='keywords'></a>KEYWORDS
[disjoint set](../../../../index.md#disjoint_set), [equivalence
class](../../../../index.md#equivalence_class),
[find](../../../../index.md#find), [merge
find](../../../../index.md#merge_find),
[partition](../../../../index.md#partition), [partitioned
set](../../../../index.md#partitioned_set), [union](../../../../index.md#union)
# <a name='category'></a>CATEGORY
Data structures
|
Added embedded/md/tcllib/files/modules/struct/graph.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
|
[//000000001]: # (struct::graph - Tcl Data Structures)
[//000000002]: # (Generated from file 'graph.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::graph(n) 2.4.1 tcllib "Tcl Data Structures")
# NAME
struct::graph - Create and manipulate directed graph objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Changes for 2.0](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require struct::graph ?2.4.1?
package require struct::list ?1.5?
package require struct::set ?2.2.3?
[__::struct::graph__ ?*graphName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1)
[__graphName__ *option* ?*arg arg ...*?](#2)
[*graphName* __=__ *sourcegraph*](#3)
[*graphName* __-->__ *destgraph*](#4)
[*graphName* __append__ *key* *value*](#5)
[*graphName* __deserialize__ *serialization*](#6)
[*graphName* __destroy__](#7)
[*graphName* __arc append__ *arc* *key* *value*](#8)
[*graphName* __arc attr__ *key*](#9)
[*graphName* __arc attr__ *key* __-arcs__ *list*](#10)
[*graphName* __arc attr__ *key* __-glob__ *globpattern*](#11)
[*graphName* __arc attr__ *key* __-regexp__ *repattern*](#12)
[*graphName* __arc delete__ *arc* ?*arc* ...?](#13)
[*graphName* __arc exists__ *arc*](#14)
[*graphName* __arc flip__ *arc*](#15)
[*graphName* __arc get__ *arc* *key*](#16)
[*graphName* __arc getall__ *arc* ?*pattern*?](#17)
[*graphName* __arc getunweighted__](#18)
[*graphName* __arc getweight__ *arc*](#19)
[*graphName* __arc keys__ *arc* ?*pattern*?](#20)
[*graphName* __arc keyexists__ *arc* *key*](#21)
[*graphName* __arc insert__ *start* *end* ?*child*?](#22)
[*graphName* __arc lappend__ *arc* *key* *value*](#23)
[*graphName* __arc rename__ *arc* *newname*](#24)
[*graphName* __arc set__ *arc* *key* ?*value*?](#25)
[*graphName* __arc setunweighted__ ?*weight*?](#26)
[*graphName* __arc setweight__ *arc* *weight*](#27)
[*graphName* __arc unsetweight__ *arc*](#28)
[*graphName* __arc hasweight__ *arc*](#29)
[*graphName* __arc source__ *arc*](#30)
[*graphName* __arc target__ *arc*](#31)
[*graphName* __arc nodes__ *arc*](#32)
[*graphName* __arc move-source__ *arc* *newsource*](#33)
[*graphName* __arc move-target__ *arc* *newtarget*](#34)
[*graphName* __arc move__ *arc* *newsource* *newtarget*](#35)
[*graphName* __arc unset__ *arc* *key*](#36)
[*graphName* __arc weights__](#37)
[*graphName* __arcs__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node node...*?](#38)
[*graphName* __lappend__ *key* *value*](#39)
[*graphName* __node append__ *node* *key* *value*](#40)
[*graphName* __node attr__ *key*](#41)
[*graphName* __node attr__ *key* __-nodes__ *list*](#42)
[*graphName* __node attr__ *key* __-glob__ *globpattern*](#43)
[*graphName* __node attr__ *key* __-regexp__ *repattern*](#44)
[*graphName* __node degree__ ?-in|-out? *node*](#45)
[*graphName* __node delete__ *node* ?*node*...?](#46)
[*graphName* __node exists__ *node*](#47)
[*graphName* __node get__ *node* *key*](#48)
[*graphName* __node getall__ *node* ?*pattern*?](#49)
[*graphName* __node keys__ *node* ?*pattern*?](#50)
[*graphName* __node keyexists__ *node* *key*](#51)
[*graphName* __node insert__ ?*node*...?](#52)
[*graphName* __node lappend__ *node* *key* *value*](#53)
[*graphName* __node opposite__ *node* *arc*](#54)
[*graphName* __node rename__ *node* *newname*](#55)
[*graphName* __node set__ *node* *key* ?*value*?](#56)
[*graphName* __node unset__ *node* *key*](#57)
[*graphName* __nodes__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node* *node*...?](#58)
[*graphName* __get__ *key*](#59)
[*graphName* __getall__ ?*pattern*?](#60)
[*graphName* __keys__ ?*pattern*?](#61)
[*graphName* __keyexists__ *key*](#62)
[*graphName* __serialize__ ?*node*...?](#63)
[*graphName* __set__ *key* ?*value*?](#64)
[*graphName* __swap__ *node1* *node2*](#65)
[*graphName* __unset__ *key*](#66)
[*graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd*](#67)
# <a name='description'></a>DESCRIPTION
A directed graph is a structure containing two collections of elements, called
*nodes* and *arcs* respectively, together with a relation ("connectivity") that
places a general structure upon the nodes and arcs.
Each arc is connected to two nodes, one of which is called the
*[source](../../../../index.md#source)* and the other the *target*. This imposes
a direction upon the arc, which is said to go from the source to the target. It
is allowed that source and target of an arc are the same node. Such an arc is
called a *[loop](../../../../index.md#loop)*. Whenever a node is either the
source or target of an arc both are said to be
*[adjacent](../../../../index.md#adjacent)*. This extends into a relation
between nodes, i.e. if two nodes are connected through at least one arc they are
said to be *[adjacent](../../../../index.md#adjacent)* too.
Each node can be the source and target for any number of arcs. The former are
called the *outgoing arcs* of the node, the latter the *incoming arcs* of the
node. The number of arcs in either set is called the *in-degree* resp. the
*out-degree* of the node.
In addition to maintaining the node and arc relationships, this graph
implementation allows any number of named *attributes* to be associated with the
graph itself, and each node or arc.
*Note:* The major version of the package
__[struct](../../../../index.md#struct)__ has been changed to version 2.0, due
to backward incompatible changes in the API of this module. Please read the
section [Changes for 2.0](#section2) for a full list of all changes,
incompatible and otherwise.
*Note:* A C-implementation of the command can be had from the location
[http://www.purl.org/NET/schlenker/tcl/cgraph](http://www.purl.org/NET/schlenker/tcl/cgraph).
See also [http://wiki.tcl.tk/cgraph](http://wiki.tcl.tk/cgraph). This
implementation uses a bit less memory than the tcl version provided here
directly, and is faster. Its support is limited to versions of the package
before 2.0.
As of version 2.2 of this package a critcl based C implementation is available
from here as well. This implementation however requires Tcl 8.4 to run.
The main command of the package is:
- <a name='1'></a>__::struct::graph__ ?*graphName*? ?__=__|__:=__|__as__|__deserialize__ *source*?
The command creates a new graph object with an associated global Tcl command
whose name is *graphName*. This command may be used to invoke various
operations on the graph. It has the following general form:
* <a name='2'></a>__graphName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
If *graphName* is not specified a unique name will be generated by the
package itself. If a *source* is specified the new graph will be initialized
to it. For the operators __=__, __:=__, and __as__ the *source* argument is
interpreted as the name of another graph object, and the assignment operator
__=__ will be executed. For the operator __deserialize__ the *source* is a
serialized graph object and __deserialize__ will be executed.
In other words
::struct::graph mygraph = b
is equivalent to
::struct::graph mygraph
mygraph = b
and
::struct::graph mygraph deserialize $b
is equivalent to
::struct::graph mygraph
mygraph deserialize $b
The following commands are possible for graph objects:
- <a name='3'></a>*graphName* __=__ *sourcegraph*
This is the *assignment* operator for graph objects. It copies the graph
contained in the graph object *sourcegraph* over the graph data in
*graphName*. The old contents of *graphName* are deleted by this operation.
This operation is in effect equivalent to
*graphName* __deserialize__ [*sourcegraph* __serialize__]
The operation assumes that the *sourcegraph* provides the method
__serialize__ and that this method returns a valid graph serialization.
- <a name='4'></a>*graphName* __-->__ *destgraph*
This is the *reverse assignment* operator for graph objects. It copies the
graph contained in the graph object *graphName* over the graph data in the
object *destgraph*. The old contents of *destgraph* are deleted by this
operation.
This operation is in effect equivalent to
*destgraph* __deserialize__ [*graphName* __serialize__]
The operation assumes that the *destgraph* provides the method
__deserialize__ and that this method takes a graph serialization.
- <a name='5'></a>*graphName* __append__ *key* *value*
Appends a *value* to one of the keyed values associated with the graph.
Returns the new value given to the attribute *key*.
- <a name='6'></a>*graphName* __deserialize__ *serialization*
This is the complement to __serialize__. It replaces the graph data in
*graphName* with the graph described by the *serialization* value. The old
contents of *graphName* are deleted by this operation.
- <a name='7'></a>*graphName* __destroy__
Destroys the graph, including its storage space and associated command.
- <a name='8'></a>*graphName* __arc append__ *arc* *key* *value*
Appends a *value* to one of the keyed values associated with an *arc*.
Returns the new value given to the attribute *key*.
- <a name='9'></a>*graphName* __arc attr__ *key*
- <a name='10'></a>*graphName* __arc attr__ *key* __-arcs__ *list*
- <a name='11'></a>*graphName* __arc attr__ *key* __-glob__ *globpattern*
- <a name='12'></a>*graphName* __arc attr__ *key* __-regexp__ *repattern*
This method retrieves the value of the attribute named *key*, for all arcs
in the graph (matching the restriction specified via one of the possible
options) and having the specified attribute.
The result is a dictionary mapping from arc names to the value of attribute
*key* at that arc. Arcs not having the attribute *key*, or not passing a
specified restriction, are not listed in the result.
The possible restrictions are:
* __-arcs__
The value is a list of arcs. Only the arcs mentioned in this list are
searched for the attribute.
* __-glob__
The value is a glob pattern. Only the arcs in the graph whose names
match this pattern are searched for the attribute.
* __-regexp__
The value is a regular expression. Only the arcs in the graph whose
names match this pattern are searched for the attribute.
- <a name='13'></a>*graphName* __arc delete__ *arc* ?*arc* ...?
Remove the specified arcs from the graph.
- <a name='14'></a>*graphName* __arc exists__ *arc*
Return true if the specified *arc* exists in the graph.
- <a name='15'></a>*graphName* __arc flip__ *arc*
Reverses the direction of the named *arc*, i.e. the source and target nodes
of the arc are exchanged with each other.
- <a name='16'></a>*graphName* __arc get__ *arc* *key*
Returns the value associated with the key *key* for the *arc*.
- <a name='17'></a>*graphName* __arc getall__ *arc* ?*pattern*?
Returns a dictionary (suitable for use with [__array set__]) for the *arc*.
If the *pattern* is specified only the attributes whose names match the
pattern will be part of the returned dictionary. The pattern is a __glob__
pattern.
- <a name='18'></a>*graphName* __arc getunweighted__
Returns a list containing the names of all arcs in the graph which have no
weight associated with them.
- <a name='19'></a>*graphName* __arc getweight__ *arc*
Returns the weight associated with the *arc*. Throws an error if the arc has
no weight associated with it.
- <a name='20'></a>*graphName* __arc keys__ *arc* ?*pattern*?
Returns a list of keys for the *arc*. If the *pattern* is specified only the
attributes whose names match the pattern will be part of the returned list.
The pattern is a __glob__ pattern.
- <a name='21'></a>*graphName* __arc keyexists__ *arc* *key*
Return true if the specified *key* exists for the *arc*.
- <a name='22'></a>*graphName* __arc insert__ *start* *end* ?*child*?
Insert an arc named *child* into the graph beginning at the node *start* and
ending at the node *end*. If the name of the new arc is not specified the
system will generate a unique name of the form *arc**x*.
- <a name='23'></a>*graphName* __arc lappend__ *arc* *key* *value*
Appends a *value* (as a list) to one of the keyed values associated with an
*arc*. Returns the new value given to the attribute *key*.
- <a name='24'></a>*graphName* __arc rename__ *arc* *newname*
Renames the arc *arc* to *newname*. An error is thrown if either the arc
does not exist, or a arc with name *newname* does exist. The result of the
command is the new name of the arc.
- <a name='25'></a>*graphName* __arc set__ *arc* *key* ?*value*?
Set or get one of the keyed values associated with an arc. An arc may have
any number of keyed values associated with it. If *value* is not specified,
this command returns the current value assigned to the key; if *value* is
specified, this command assigns that value to the key, and returns that
value.
- <a name='26'></a>*graphName* __arc setunweighted__ ?*weight*?
Sets the weight of all arcs without a weight to *weight*. Returns the empty
string as its result. If not present *weight* defaults to __0__.
- <a name='27'></a>*graphName* __arc setweight__ *arc* *weight*
Sets the weight of the *arc* to *weight*. Returns *weight*.
- <a name='28'></a>*graphName* __arc unsetweight__ *arc*
Removes the weight of the *arc*, if present. Does nothing otherwise. Returns
the empty string.
- <a name='29'></a>*graphName* __arc hasweight__ *arc*
Determines if the *arc* has a weight associated with it. The result is a
boolean value, __True__ if a weight is defined, and __False__ otherwise.
- <a name='30'></a>*graphName* __arc source__ *arc*
Return the node the given *arc* begins at.
- <a name='31'></a>*graphName* __arc target__ *arc*
Return the node the given *arc* ends at.
- <a name='32'></a>*graphName* __arc nodes__ *arc*
Return the nodes the given *arc* begins and ends at, as a two-element list.
- <a name='33'></a>*graphName* __arc move-source__ *arc* *newsource*
Changes the source node of the arc to *newsource*. It can be said that the
arc rotates around its target node.
- <a name='34'></a>*graphName* __arc move-target__ *arc* *newtarget*
Changes the target node of the arc to *newtarget*. It can be said that the
arc rotates around its source node.
- <a name='35'></a>*graphName* __arc move__ *arc* *newsource* *newtarget*
Changes both source and target nodes of the arc to *newsource*, and
*newtarget* resp.
- <a name='36'></a>*graphName* __arc unset__ *arc* *key*
Remove a keyed value from the arc *arc*. The method will do nothing if the
*key* does not exist.
- <a name='37'></a>*graphName* __arc weights__
Returns a dictionary whose keys are the names of all arcs which have a
weight associated with them, and the values are these weights.
- <a name='38'></a>*graphName* __arcs__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node node...*?
Returns a list of arcs in the graph. If no restriction is specified a list
containing all arcs is returned. Restrictions can limit the list of returned
arcs based on the nodes that are connected by the arc, on the keyed values
associated with the arc, or both. A general filter command can be used as
well. The restrictions that involve connected nodes take a variable number
of nodes as argument, specified after the name of the restriction itself.
The restrictions imposed by either __-in__, __-out__, __-adj__, __-inner__,
or __-embedded__ are applied first. Specifying more than one of them is
illegal.
After that the restrictions set via __-key__ (and __-value__) are applied.
Specifying more than one __-key__ (and __-value__) is illegal. Specifying
__-value__ alone, without __-key__ is illegal as well.
Any restriction set through __-filter__ is applied last. Specifying more
than one __-filter__ is illegal.
Coming back to the restrictions based on a set of nodes, the command
recognizes the following switches:
* __-in__
Return a list of all arcs whose target is one of the nodes in the set of
nodes. I.e. it computes the union of all incoming arcs of the nodes in
the set.
* __-out__
Return a list of all arcs whose source is one of the nodes in the set of
nodes. I.e. it computes the union of all outgoing arcs of the nodes in
the set.
* __-adj__
Return a list of all arcs adjacent to at least one of the nodes in the
set. This is the union of the nodes returned by __-in__ and __-out__.
* __-inner__
Return a list of all arcs which are adjacent to two of the nodes in the
set. This is the set of arcs in the subgraph spawned by the specified
nodes.
* __-embedding__
Return a list of all arcs adjacent to exactly one of the nodes in the
set. This is the set of arcs connecting the subgraph spawned by the
specified nodes to the rest of the graph.
* __-key__ *key*
Limit the list of arcs that are returned to those arcs that have an
associated key *key*.
* __-value__ *value*
This restriction can only be used in combination with __-key__. It
limits the list of arcs that are returned to those arcs whose associated
key *key* has the value *value*.
* __-filter__ *cmdrefix*
Limit the list of arcs that are returned to those arcs that pass the
test. The command in *cmdprefix* is called with two arguments, the name
of the graph object, and the name of the arc in question. It is executed
in the context of the caller and has to return a boolean value. Arcs for
which the command returns __false__ are removed from the result list
before it is returned to the caller.
- <a name='39'></a>*graphName* __lappend__ *key* *value*
Appends a *value* (as a list) to one of the keyed values associated with the
graph. Returns the new value given to the attribute *key*.
- <a name='40'></a>*graphName* __node append__ *node* *key* *value*
Appends a *value* to one of the keyed values associated with an *node*.
Returns the new value given to the attribute *key*.
- <a name='41'></a>*graphName* __node attr__ *key*
- <a name='42'></a>*graphName* __node attr__ *key* __-nodes__ *list*
- <a name='43'></a>*graphName* __node attr__ *key* __-glob__ *globpattern*
- <a name='44'></a>*graphName* __node attr__ *key* __-regexp__ *repattern*
This method retrieves the value of the attribute named *key*, for all nodes
in the graph (matching the restriction specified via one of the possible
options) and having the specified attribute.
The result is a dictionary mapping from node names to the value of attribute
*key* at that node. Nodes not having the attribute *key*, or not passing a
specified restriction, are not listed in the result.
The possible restrictions are:
* __-nodes__
The value is a list of nodes. Only the nodes mentioned in this list are
searched for the attribute.
* __-glob__
The value is a glob pattern. Only the nodes in the graph whose names
match this pattern are searched for the attribute.
* __-regexp__
The value is a regular expression. Only the nodes in the graph whose
names match this pattern are searched for the attribute.
- <a name='45'></a>*graphName* __node degree__ ?-in|-out? *node*
Return the number of arcs adjacent to the specified *node*. If one of the
restrictions __-in__ or __-out__ is given only the incoming resp. outgoing
arcs are counted.
- <a name='46'></a>*graphName* __node delete__ *node* ?*node*...?
Remove the specified nodes from the graph. All of the nodes' arcs will be
removed as well to prevent unconnected arcs.
- <a name='47'></a>*graphName* __node exists__ *node*
Return true if the specified *node* exists in the graph.
- <a name='48'></a>*graphName* __node get__ *node* *key*
Return the value associated with the key *key* for the *node*.
- <a name='49'></a>*graphName* __node getall__ *node* ?*pattern*?
Returns a dictionary (suitable for use with [__array set__]) for the *node*.
If the *pattern* is specified only the attributes whose names match the
pattern will be part of the returned dictionary. The pattern is a __glob__
pattern.
- <a name='50'></a>*graphName* __node keys__ *node* ?*pattern*?
Returns a list of keys for the *node*. If the *pattern* is specified only
the attributes whose names match the pattern will be part of the returned
list. The pattern is a __glob__ pattern.
- <a name='51'></a>*graphName* __node keyexists__ *node* *key*
Return true if the specified *key* exists for the *node*.
- <a name='52'></a>*graphName* __node insert__ ?*node*...?
Insert one or more nodes into the graph. The new nodes have no arcs
connected to them. If no node is specified one node will be inserted, and
the system will generate a unique name of the form *node**x* for it.
- <a name='53'></a>*graphName* __node lappend__ *node* *key* *value*
Appends a *value* (as a list) to one of the keyed values associated with an
*node*. Returns the new value given to the attribute *key*.
- <a name='54'></a>*graphName* __node opposite__ *node* *arc*
Return the node at the other end of the specified *arc*, which has to be
adjacent to the given *node*.
- <a name='55'></a>*graphName* __node rename__ *node* *newname*
Renames the node *node* to *newname*. An error is thrown if either the node
does not exist, or a node with name *newname* does exist. The result of the
command is the new name of the node.
- <a name='56'></a>*graphName* __node set__ *node* *key* ?*value*?
Set or get one of the keyed values associated with a node. A node may have
any number of keyed values associated with it. If *value* is not specified,
this command returns the current value assigned to the key; if *value* is
specified, this command assigns that value to the key.
- <a name='57'></a>*graphName* __node unset__ *node* *key*
Remove a keyed value from the node *node*. The method will do nothing if the
*key* does not exist.
- <a name='58'></a>*graphName* __nodes__ ?-key *key*? ?-value *value*? ?-filter *cmdprefix*? ?-in|-out|-adj|-inner|-embedding *node* *node*...?
Return a list of nodes in the graph. Restrictions can limit the list of
returned nodes based on neighboring nodes, or based on the keyed values
associated with the node. The restrictions that involve neighboring nodes
have a list of nodes as argument, specified after the name of the
restriction itself.
The possible restrictions are the same as for method __arcs__. The exact
meanings change slightly, as they operate on nodes instead of arcs. The
command recognizes:
* __-in__
Return a list of all nodes with at least one outgoing arc ending in a
node found in the specified set of nodes. Alternatively specified as the
set of source nodes for the __-in__ arcs of the node set. The *incoming
neighbours*.
* __-out__
Return a list of all nodes with at least one incoming arc starting in a
node found in the specified set of nodes. Alternatively specified as the
set of target nodes for the __-out__ arcs of the node set. The *outgoing
neighbours*.
* __-adj__
This is the union of the nodes returned by __-in__ and __-out__. The
*neighbours*.
* __-inner__
The set of neighbours (see __-adj__ above) which are also in the set of
nodes. I.e. the intersection between the set of nodes and the neighbours
per __-adj__.
* __-embedding__
The set of neighbours (see __-adj__ above) which are not in the set of
nodes. I.e. the difference between the neighbours as per __-adj__, and
the set of nodes.
* __-key__ *key*
Limit the list of nodes that are returned to those nodes that have an
associated key *key*.
* __-value__ *value*
This restriction can only be used in combination with __-key__. It
limits the list of nodes that are returned to those nodes whose
associated key *key* has the value *value*.
* __-filter__ *cmdrefix*
Limit the list of nodes that are returned to those nodes that pass the
test. The command in *cmdprefix* is called with two arguments, the name
of the graph object, and the name of the node in question. It is
executed in the context of the caller and has to return a boolean value.
Nodes for which the command returns __false__ are removed from the
result list before it is returned to the caller.
- <a name='59'></a>*graphName* __get__ *key*
Return the value associated with the key *key* for the graph.
- <a name='60'></a>*graphName* __getall__ ?*pattern*?
Returns a dictionary (suitable for use with [__array set__]) for the whole
graph. If the *pattern* is specified only the attributes whose names match
the pattern will be part of the returned dictionary. The pattern is a
__glob__ pattern.
- <a name='61'></a>*graphName* __keys__ ?*pattern*?
Returns a list of keys for the whole graph. If the *pattern* is specified
only the attributes whose names match the pattern will be part of the
returned list. The pattern is a __glob__ pattern.
- <a name='62'></a>*graphName* __keyexists__ *key*
Return true if the specified *key* exists for the whole graph.
- <a name='63'></a>*graphName* __serialize__ ?*node*...?
This method serializes the sub-graph spanned up by the *node*s. In other
words it returns a tcl value completely describing that graph. If no nodes
are specified the whole graph will be serialized. This allows, for example,
the transfer of graph objects (or parts thereof) over arbitrary channels,
persistence, etc. This method is also the basis for both the copy
constructor and the assignment operator.
The result of this method has to be semantically identical over all
implementations of the graph interface. This is what will enable us to copy
graph data between different implementations of the same interface.
The result is a list containing a multiple of three items, plus one! In
other words, '[llength $serial] % 3 == 1'. Valid values include 1, 4, 7, ...
The last element of the list is a dictionary containing the attributes
associated with the whole graph. Regarding the other elements; each triple
consists of
The name of the node to be described,
A dictionary containing the attributes associated with the node,
And a list describing all the arcs starting at that node.
The elements of the arc list are lists containing three or four elements
each, i.e.
The name of the arc described by the element,
A reference to the destination node of the arc. This reference is an integer
number given the index of that node in the main serialization list. As that
it is greater than or equal to zero, less than the length of the
serialization, and a multiple of three. *Note:* For internal consistency no
arc name may be used twice, whether in the same node, or at some other node.
This is a global consistency requirement for the serialization.
And a dictionary containing the attributes associated with the arc.
The weight associated with the arc. This value is optional. Its non-presence
means that the arc in question has no weight associated with it.
*Note:* This information is new, compared to the serialization of
__[graph](../../../../index.md#graph)__ 2.3 and earlier. By making it an
optional element the new format is maximally compatible with the old. This
means that any graph not using weights will generate a serialization which
is still understood by the older graph package. A serialization will not be
understood any longer by the older packages if, and only if the graph it was
generated from actually has arcs with weights.
For all attribute dictionaries they keys are the names of the attributes,
and the values are the values for each name.
*Note:* The order of the nodes in the serialization has no relevance, nor
has the order of the arcs per node.
# A possible serialization for the graph structure
#
# d -----> %2
# / ^ \\
# / / \\
# / b \\
# / / \\
# %1 <- a - %0 e
# ^ \\ /
# \\ c /
# \\ \\ /
# \\ v v
# f ------ %3
# is
#
# %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {}
#
# This assumes that the graph has neither attribute data nor weighted arcs.
- <a name='64'></a>*graphName* __set__ *key* ?*value*?
Set or get one of the keyed values associated with a graph. A graph may have
any number of keyed values associated with it. If *value* is not specified,
this command returns the current value assigned to the key; if *value* is
specified, this command assigns that value to the key.
- <a name='65'></a>*graphName* __swap__ *node1* *node2*
Swap the position of *node1* and *node2* in the graph.
- <a name='66'></a>*graphName* __unset__ *key*
Remove a keyed value from the graph. The method will do nothing if the *key*
does not exist.
- <a name='67'></a>*graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd*
Perform a breadth-first or depth-first walk of the graph starting at the
node *node* going in either the direction of outgoing or opposite to the
incoming arcs.
The type of walk, breadth-first or depth-first, is determined by the value
of *type*; __bfs__ indicates breadth-first, __dfs__ indicates depth-first.
Depth-first is the default.
The order of the walk, pre-order, post-order or both-order is determined by
the value of *order*; __pre__ indicates pre-order, __post__ indicates
post-order, __both__ indicates both-order. Pre-order is the default.
Pre-order walking means that a node is visited before any of its neighbors
(as defined by the *direction*, see below). Post-order walking means that a
parent is visited after any of its neighbors. Both-order walking means that
a node is visited before *and* after any of its neighbors. The combination
of a breadth-first walk with post- or both-order is illegal.
The direction of the walk is determined by the value of *dir*; __backward__
indicates the direction opposite to the incoming arcs, __forward__ indicates
the direction of the outgoing arcs.
As the walk progresses, the command *cmd* will be evaluated at each node,
with the mode of the call (__enter__ or __leave__) and values *graphName*
and the name of the current node appended. For a pre-order walk, all nodes
are __enter__ed, for a post-order all nodes are left. In a both-order walk
the first visit of a node __enter__s it, the second visit __leave__s it.
# <a name='section2'></a>Changes for 2.0
The following noteworthy changes have occurred:
1. The API for accessing attributes and their values has been simplified.
All functionality regarding the default attribute "data" has been removed.
This default attribute does not exist anymore. All accesses to attributes
have to specify the name of the attribute in question. This backward
*incompatible* change allowed us to simplify the signature of all methods
handling attributes.
Especially the flag __-key__ is not required anymore, even more, its use is
now forbidden. Please read the documentation for the arc and node methods
__set__, __get__, __getall__, __unset__, __append__, __lappend__,
__keyexists__ and __keys__ for a description of the new API's.
1. The methods __keys__ and __getall__ now take an optional pattern argument
and will return only attribute data for keys matching this pattern.
1. Arcs and nodes can now be renamed. See the documentation for the methods
__arc rename__ and __node rename__.
1. The structure has been extended with API's for the serialization and
deserialization of graph objects, and a number of operations based on them
(graph assignment, copy construction).
Please read the documentation for the methods __serialize__,
__deserialize__, __=__, and __-->__, and the documentation on the
construction of graph objects.
Beyond the copying of whole graph objects these new API's also enable the
transfer of graph objects over arbitrary channels and for easy persistence.
1. A new method, __attr__, was added to both __arc__ and __node__ allowing the
query and retrieval of attribute data without regard to arc and node
relationships.
1. Both methods __arcs__ and __nodes__ have been extended with the ability to
select arcs and nodes based on an arbitrary filtering criterium.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: graph* 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.
# <a name='keywords'></a>KEYWORDS
[adjacent](../../../../index.md#adjacent), [arc](../../../../index.md#arc),
[cgraph](../../../../index.md#cgraph), [degree](../../../../index.md#degree),
[edge](../../../../index.md#edge), [graph](../../../../index.md#graph),
[loop](../../../../index.md#loop), [neighbour](../../../../index.md#neighbour),
[node](../../../../index.md#node),
[serialization](../../../../index.md#serialization),
[subgraph](../../../../index.md#subgraph), [vertex](../../../../index.md#vertex)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/graph1.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
|
[//000000001]: # (struct::graph_v1 - Tcl Data Structures)
[//000000002]: # (Generated from file 'graph1.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::graph_v1(n) 1.2.1 tcllib "Tcl Data Structures")
# NAME
struct::graph_v1 - Create and manipulate directed graph objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::graph ?1.2.1?
[__graphName__ *option* ?*arg arg ...*?](#1)
[*graphName* __destroy__](#2)
[*graphName* __arc append__ *arc* ?-key *key*? *value*](#3)
[*graphName* __arc delete__ *arc* ?*arc* ...?](#4)
[*graphName* __arc exists__ *arc*](#5)
[*graphName* __arc get__ *arc* ?-key *key*?](#6)
[*graphName* __arc getall__ *arc*](#7)
[*graphName* __arc keys__ *arc*](#8)
[*graphName* __arc keyexists__ *arc* ?-key *key*?](#9)
[*graphName* __arc insert__ *start* *end* ?*child*?](#10)
[*graphName* __arc lappend__ *arc* ?-key *key*? *value*](#11)
[*graphName* __arc set__ *arc* ?-key *key*? ?*value*?](#12)
[*graphName* __arc source__ *arc*](#13)
[*graphName* __arc target__ *arc*](#14)
[*graphName* __arc unset__ *arc* ?-key *key*?](#15)
[*graphName* __arcs__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*?](#16)
[*graphName* __node append__ *node* ?-key *key*? *value*](#17)
[*graphName* __node degree__ ?-in|-out? *node*](#18)
[*graphName* __node delete__ *node* ?*node* ...?](#19)
[*graphName* __node exists__ *node*](#20)
[*graphName* __node get__ *node* ?-key *key*?](#21)
[*graphName* __node getall__ *node*](#22)
[*graphName* __node keys__ *node*](#23)
[*graphName* __node keyexists__ *node* ?-key *key*?](#24)
[*graphName* __node insert__ ?*child*?](#25)
[*graphName* __node lappend__ *node* ?-key *key*? *value*](#26)
[*graphName* __node opposite__ *node* *arc*](#27)
[*graphName* __node set__ *node* ?-key *key*? ?*value*?](#28)
[*graphName* __node unset__ *node* ?-key *key*?](#29)
[*graphName* __nodes__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*?](#30)
[*graphName* __get__ ?-key *key*?](#31)
[*graphName* __getall__](#32)
[*graphName* __keys__](#33)
[*graphName* __keyexists__ ?-key *key*?](#34)
[*graphName* __set__ ?-key *key*? ?*value*?](#35)
[*graphName* __swap__ *node1* *node2*](#36)
[*graphName* __unset__ ?-key *key*?](#37)
[*graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd*](#38)
# <a name='description'></a>DESCRIPTION
The __::struct::graph__ command creates a new graph object with an associated
global Tcl command whose name is *graphName*. This command may be used to invoke
various operations on the graph. It has the following general form:
- <a name='1'></a>__graphName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
A directed graph is a structure containing two collections of elements, called
*nodes* and *arcs* respectively, together with a relation ("connectivity") that
places a general structure upon the nodes and arcs.
Each arc is connected to two nodes, one of which is called the *source* and the
other the *target*. This imposes a direction upon the arc, which is said to go
from the source to the target. It is allowed that source and target of an arc
are the same node. Such an arc is called a *loop*. Whenever a node is source or
target of an arc both are said to be *adjacent*. This extends into a relation
between nodes, i.e. if two nodes are connected through at least one arc they are
said to be *adjacent* too.
Each node can be the source and target for any number of arcs. The former are
called the *outgoing arcs* of the node, the latter the *incoming arcs* of the
node. The number of edges in either set is called the *in-* resp. the
*out-degree* of the node.
In addition to maintaining the node and arc relationships, this graph
implementation allows any number of keyed values to be associated with each node
and arc.
The following commands are possible for graph objects:
- <a name='2'></a>*graphName* __destroy__
Destroy the graph, including its storage space and associated command.
- <a name='3'></a>*graphName* __arc append__ *arc* ?-key *key*? *value*
Appends a *value* to one of the keyed values associated with an *arc*. If no
*key* is specified, the key __data__ is assumed.
- <a name='4'></a>*graphName* __arc delete__ *arc* ?*arc* ...?
Remove the specified arcs from the graph.
- <a name='5'></a>*graphName* __arc exists__ *arc*
Return true if the specified *arc* exists in the graph.
- <a name='6'></a>*graphName* __arc get__ *arc* ?-key *key*?
Return the value associated with the key *key* for the *arc*. If no key is
specified, the key __data__ is assumed.
- <a name='7'></a>*graphName* __arc getall__ *arc*
Returns a serialized list of key/value pairs (suitable for use with [__array
set__]) for the *arc*.
- <a name='8'></a>*graphName* __arc keys__ *arc*
Returns a list of keys for the *arc*.
- <a name='9'></a>*graphName* __arc keyexists__ *arc* ?-key *key*?
Return true if the specified *key* exists for the *arc*. If no *key* is
specified, the key __data__ is assumed.
- <a name='10'></a>*graphName* __arc insert__ *start* *end* ?*child*?
Insert an arc named *child* into the graph beginning at the node *start* and
ending at the node *end*. If the name of the new arc is not specified the
system will generate a unique name of the form *arc**x*.
- <a name='11'></a>*graphName* __arc lappend__ *arc* ?-key *key*? *value*
Appends a *value* (as a list) to one of the keyed values associated with an
*arc*. If no *key* is specified, the key __data__ is assumed.
- <a name='12'></a>*graphName* __arc set__ *arc* ?-key *key*? ?*value*?
Set or get one of the keyed values associated with an arc. If no key is
specified, the key __data__ is assumed. Each arc that is added to a graph
has the empty string assigned to the key __data__ automatically. An arc may
have any number of keyed values associated with it. If *value* is not
specified, this command returns the current value assigned to the key; if
*value* is specified, this command assigns that value to the key.
- <a name='13'></a>*graphName* __arc source__ *arc*
Return the node the given *arc* begins at.
- <a name='14'></a>*graphName* __arc target__ *arc*
Return the node the given *arc* ends at.
- <a name='15'></a>*graphName* __arc unset__ *arc* ?-key *key*?
Remove a keyed value from the arc *arc*. If no key is specified, the key
__data__ is assumed.
- <a name='16'></a>*graphName* __arcs__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*?
Return a list of arcs in the graph. If no restriction is specified a list
containing all arcs is returned. Restrictions can limit the list of returned
arcs based on the nodes that are connected by the arc, on the keyed values
associated with the arc, or both. The restrictions that involve connected
nodes have a list of nodes as argument, specified after the name of the
restriction itself.
* __-in__
Return a list of all arcs whose target is one of the nodes in the
*nodelist*.
* __-out__
Return a list of all arcs whose source is one of the nodes in the
*nodelist*.
* __-adj__
Return a list of all arcs adjacent to at least one of the nodes in the
*nodelist*. This is the union of the nodes returned by __-in__ and
__-out__.
* __-inner__
Return a list of all arcs adjacent to two of the nodes in the
*nodelist*. This is the set of arcs in the subgraph spawned by the
specified nodes.
* __-embedding__
Return a list of all arcs adjacent to exactly one of the nodes in the
*nodelist*. This is the set of arcs connecting the subgraph spawned by
the specified nodes to the rest of the graph.
* __-key__ *key*
Limit the list of arcs that are returned to those arcs that have an
associated key *key*.
* __-value__ *value*
This restriction can only be used in combination with __-key__. It
limits the list of arcs that are returned to those arcs whose associated
key *key* has the value *value*.
The restrictions imposed by either __-in__, __-out__, __-adj__, __-inner__,
or __-embedded__ are applied first. Specifying more than one of them is
illegal. At last the restrictions set via __-key__ (and __-value__) are
applied. Specifying more than one __-key__ (and __-value__) is illegal.
- <a name='17'></a>*graphName* __node append__ *node* ?-key *key*? *value*
Appends a *value* to one of the keyed values associated with an *node*. If
no *key* is specified, the key __data__ is assumed.
- <a name='18'></a>*graphName* __node degree__ ?-in|-out? *node*
Return the number of arcs adjacent to the specified *node*. If one of the
restrictions __-in__ or __-out__ is given only the incoming resp. outgoing
arcs are counted.
- <a name='19'></a>*graphName* __node delete__ *node* ?*node* ...?
Remove the specified nodes from the graph. All of the nodes' arcs will be
removed as well to prevent unconnected arcs.
- <a name='20'></a>*graphName* __node exists__ *node*
Return true if the specified *node* exists in the graph.
- <a name='21'></a>*graphName* __node get__ *node* ?-key *key*?
Return the value associated with the key *key* for the *node*. If no key is
specified, the key __data__ is assumed.
- <a name='22'></a>*graphName* __node getall__ *node*
Returns a serialized list of key/value pairs (suitable for use with [__array
set__]) for the *node*.
- <a name='23'></a>*graphName* __node keys__ *node*
Returns a list of keys for the *node*.
- <a name='24'></a>*graphName* __node keyexists__ *node* ?-key *key*?
Return true if the specified *key* exists for the *node*. If no *key* is
specified, the key __data__ is assumed.
- <a name='25'></a>*graphName* __node insert__ ?*child*?
Insert a node named *child* into the graph. The nodes has no arcs connected
to it. If the name of the new child is not specified the system will
generate a unique name of the form *node**x*.
- <a name='26'></a>*graphName* __node lappend__ *node* ?-key *key*? *value*
Appends a *value* (as a list) to one of the keyed values associated with an
*node*. If no *key* is specified, the key __data__ is assumed.
- <a name='27'></a>*graphName* __node opposite__ *node* *arc*
Return the node at the other end of the specified *arc*, which has to be
adjacent to the given *node*.
- <a name='28'></a>*graphName* __node set__ *node* ?-key *key*? ?*value*?
Set or get one of the keyed values associated with a node. If no key is
specified, the key __data__ is assumed. Each node that is added to a graph
has the empty string assigned to the key __data__ automatically. A node may
have any number of keyed values associated with it. If *value* is not
specified, this command returns the current value assigned to the key; if
*value* is specified, this command assigns that value to the key.
- <a name='29'></a>*graphName* __node unset__ *node* ?-key *key*?
Remove a keyed value from the node *node*. If no key is specified, the key
__data__ is assumed.
- <a name='30'></a>*graphName* __nodes__ ?-key *key*? ?-value *value*? ?-in|-out|-adj|-inner|-embedding *nodelist*?
Return a list of nodes in the graph. Restrictions can limit the list of
returned nodes based on neighboring nodes, or based on the keyed values
associated with the node. The restrictions that involve neighboring nodes
have a list of nodes as argument, specified after the name of the
restriction itself.
The possible restrictions are the same as for method __arcs__. The set of
nodes to return is computed as the union of all source and target nodes for
all the arcs satisfying the restriction as defined for __arcs__.
- <a name='31'></a>*graphName* __get__ ?-key *key*?
Return the value associated with the key *key* for the graph. If no key is
specified, the key __data__ is assumed.
- <a name='32'></a>*graphName* __getall__
Returns a serialized list of key/value pairs (suitable for use with [__array
set__]) for the whole graph.
- <a name='33'></a>*graphName* __keys__
Returns a list of keys for the whole graph.
- <a name='34'></a>*graphName* __keyexists__ ?-key *key*?
Return true if the specified *key* exists for the whole graph. If no *key*
is specified, the key __data__ is assumed.
- <a name='35'></a>*graphName* __set__ ?-key *key*? ?*value*?
Set or get one of the keyed values associated with a graph. If no key is
specified, the key __data__ is assumed. Each graph has the empty string
assigned to the key __data__ automatically. A graph may have any number of
keyed values associated with it. If *value* is not specified, this command
returns the current value assigned to the key; if *value* is specified, this
command assigns that value to the key.
- <a name='36'></a>*graphName* __swap__ *node1* *node2*
Swap the position of *node1* and *node2* in the graph.
- <a name='37'></a>*graphName* __unset__ ?-key *key*?
Remove a keyed value from the graph. If no key is specified, the key
__data__ is assumed.
- <a name='38'></a>*graphName* __walk__ *node* ?-order *order*? ?-type *type*? ?-dir *direction*? -command *cmd*
Perform a breadth-first or depth-first walk of the graph starting at the
node *node* going in either the direction of outgoing or opposite to the
incoming arcs.
The type of walk, breadth-first or depth-first, is determined by the value
of *type*; __bfs__ indicates breadth-first, __dfs__ indicates depth-first.
Depth-first is the default.
The order of the walk, pre-order, post-order or both-order is determined by
the value of *order*; __pre__ indicates pre-order, __post__ indicates
post-order, __both__ indicates both-order. Pre-order is the default.
Pre-order walking means that a node is visited before any of its neighbors
(as defined by the *direction*, see below). Post-order walking means that a
parent is visited after any of its neighbors. Both-order walking means that
a node is visited before *and* after any of its neighbors. The combination
of a bread-first walk with post- or both-order is illegal.
The direction of the walk is determined by the value of *dir*; __backward__
indicates the direction opposite to the incoming arcs, __forward__ indicates
the direction of the outgoing arcs.
As the walk progresses, the command *cmd* will be evaluated at each node,
with the mode of the call (__enter__ or __leave__) and values *graphName*
and the name of the current node appended. For a pre-order walk, all nodes
are __enter__ed, for a post-order all nodes are left. In a both-order walk
the first visit of a node __enter__s it, the second visit __leave__s it.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: graph* 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.
# <a name='keywords'></a>KEYWORDS
[cgraph](../../../../index.md#cgraph), [graph](../../../../index.md#graph)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/graphops.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
|
[//000000001]: # (struct::graph::op - Tcl Data Structures)
[//000000002]: # (Generated from file 'graphops.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::graph::op(n) 0.11.3 tcllib "Tcl Data Structures")
# NAME
struct::graph::op - Operation for (un)directed graph objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Operations](#section2)
- [Background theory and terms](#section3)
- [Shortest Path Problem](#subsection1)
- [Travelling Salesman Problem](#subsection2)
- [Matching Problem](#subsection3)
- [Cut Problems](#subsection4)
- [K-Center Problem](#subsection5)
- [Flow Problems](#subsection6)
- [Approximation algorithm](#subsection7)
- [References](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require struct::graph::op ?0.11.3?
[__struct::graph::op::toAdjacencyMatrix__ *g*](#1)
[__struct::graph::op::toAdjacencyList__ *G* ?*options*...?](#2)
[__struct::graph::op::kruskal__ *g*](#3)
[__struct::graph::op::prim__ *g*](#4)
[__struct::graph::op::isBipartite?__ *g* ?*bipartvar*?](#5)
[__struct::graph::op::tarjan__ *g*](#6)
[__struct::graph::op::connectedComponents__ *g*](#7)
[__struct::graph::op::connectedComponentOf__ *g* *n*](#8)
[__struct::graph::op::isConnected?__ *g*](#9)
[__struct::graph::op::isCutVertex?__ *g* *n*](#10)
[__struct::graph::op::isBridge?__ *g* *a*](#11)
[__struct::graph::op::isEulerian?__ *g* ?*tourvar*?](#12)
[__struct::graph::op::isSemiEulerian?__ *g* ?*pathvar*?](#13)
[__struct::graph::op::dijkstra__ *g* *start* ?*options*...?](#14)
[__struct::graph::op::distance__ *g* *origin* *destination* ?*options*...?](#15)
[__struct::graph::op::eccentricity__ *g* *n* ?*options*...?](#16)
[__struct::graph::op::radius__ *g* ?*options*...?](#17)
[__struct::graph::op::diameter__ *g* ?*options*...?](#18)
[__struct::graph::op::BellmanFord__ *G* *startnode*](#19)
[__struct::graph::op::Johnsons__ *G* ?*options*...?](#20)
[__struct::graph::op::FloydWarshall__ *G*](#21)
[__struct::graph::op::MetricTravellingSalesman__ *G*](#22)
[__struct::graph::op::Christofides__ *G*](#23)
[__struct::graph::op::GreedyMaxMatching__ *G*](#24)
[__struct::graph::op::MaxCut__ *G* *U* *V*](#25)
[__struct::graph::op::UnweightedKCenter__ *G* *k*](#26)
[__struct::graph::op::WeightedKCenter__ *G* *nodeWeights* *W*](#27)
[__struct::graph::op::GreedyMaxIndependentSet__ *G*](#28)
[__struct::graph::op::GreedyWeightedMaxIndependentSet__ *G* *nodeWeights*](#29)
[__struct::graph::op::VerticesCover__ *G*](#30)
[__struct::graph::op::EdmondsKarp__ *G* *s* *t*](#31)
[__struct::graph::op::BusackerGowen__ *G* *desiredFlow* *s* *t*](#32)
[__struct::graph::op::ShortestsPathsByBFS__ *G* *s* *outputFormat*](#33)
[__struct::graph::op::BFS__ *G* *s* ?*outputFormat*...?](#34)
[__struct::graph::op::MinimumDiameterSpanningTree__ *G*](#35)
[__struct::graph::op::MinimumDegreeSpanningTree__ *G*](#36)
[__struct::graph::op::MaximumFlowByDinic__ *G* *s* *t* *blockingFlowAlg*](#37)
[__struct::graph::op::BlockingFlowByDinic__ *G* *s* *t*](#38)
[__struct::graph::op::BlockingFlowByMKM__ *G* *s* *t*](#39)
[__struct::graph::op::createResidualGraph__ *G* *f*](#40)
[__struct::graph::op::createAugmentingNetwork__ *G* *f* *path*](#41)
[__struct::graph::op::createLevelGraph__ *Gf* *s*](#42)
[__struct::graph::op::TSPLocalSearching__ *G* *C*](#43)
[__struct::graph::op::TSPLocalSearching3Approx__ *G* *C*](#44)
[__struct::graph::op::createSquaredGraph__ *G*](#45)
[__struct::graph::op::createCompleteGraph__ *G* *originalEdges*](#46)
# <a name='description'></a>DESCRIPTION
The package described by this document, __struct::graph::op__, is a companion to
the package __[struct::graph](graph.md)__. It provides a series of common
operations and algorithms applicable to (un)directed graphs.
Despite being a companion the package is not directly dependent on
__[struct::graph](graph.md)__, only on the API defined by that package. I.e. the
operations of this package can be applied to any and all graph objects which
provide the same API as the objects created through
__[struct::graph](graph.md)__.
# <a name='section2'></a>Operations
- <a name='1'></a>__struct::graph::op::toAdjacencyMatrix__ *g*
This command takes the graph *g* and returns a nested list containing the
adjacency matrix of *g*.
The elements of the outer list are the rows of the matrix, the inner
elements are the column values in each row. The matrix has "__n__+1" rows
and columns, with the first row and column (index 0) containing the name of
the node the row/column is for. All other elements are boolean values,
__True__ if there is an arc between the 2 nodes of the respective row and
column, and __False__ otherwise.
Note that the matrix is symmetric. It does not represent the directionality
of arcs, only their presence between nodes. It is also unable to represent
parallel arcs in *g*.
- <a name='2'></a>__struct::graph::op::toAdjacencyList__ *G* ?*options*...?
Procedure creates for input graph *G*, it's representation as *[Adjacency
List](../../../../index.md#adjacency_list)*. It handles both directed and
undirected graphs (default is undirected). It returns dictionary that for
each node (key) returns list of nodes adjacent to it. When considering
weighted version, for each adjacent node there is also weight of the edge
included.
* Arguments:
+ Graph object *G* (input)
A graph to convert into an *[Adjacency
List](../../../../index.md#adjacency_list)*.
* Options:
+ __-directed__
By default *G* is operated as if it were an *Undirected graph*.
Using this option tells the command to handle *G* as the directed
graph it is.
+ __-weights__
By default any weight information the graph *G* may have is ignored.
Using this option tells the command to put weight information into
the result. In that case it is expected that all arcs have a proper
weight, and an error is thrown if that is not the case.
- <a name='3'></a>__struct::graph::op::kruskal__ *g*
This command takes the graph *g* and returns a list containing the names of
the arcs in *g* which span up a minimum weight spanning tree (MST), or, in
the case of an un-connected graph, a minimum weight spanning forest (except
for the 1-vertex components). Kruskal's algorithm is used to compute the
tree or forest. This algorithm has a time complexity of *O(E*log E)* or
*O(E* log V)*, where *V* is the number of vertices and
*[E](../../../../index.md#e)* is the number of edges in graph *g*.
The command will throw an error if one or more arcs in *g* have no weight
associated with them.
A note regarding the result, the command refrains from explicitly listing
the nodes of the MST as this information is implicitly provided in the arcs
already.
- <a name='4'></a>__struct::graph::op::prim__ *g*
This command takes the graph *g* and returns a list containing the names of
the arcs in *g* which span up a minimum weight spanning tree (MST), or, in
the case of an un-connected graph, a minimum weight spanning forest (except
for the 1-vertex components). Prim's algorithm is used to compute the tree
or forest. This algorithm has a time complexity between *O(E+V*log V)* and
*O(V*V)*, depending on the implementation (Fibonacci heap + Adjacency list
versus Adjacency Matrix). As usual *V* is the number of vertices and
*[E](../../../../index.md#e)* the number of edges in graph *g*.
The command will throw an error if one or more arcs in *g* have no weight
associated with them.
A note regarding the result, the command refrains from explicitly listing
the nodes of the MST as this information is implicitly provided in the arcs
already.
- <a name='5'></a>__struct::graph::op::isBipartite?__ *g* ?*bipartvar*?
This command takes the graph *g* and returns a boolean value indicating
whether it is bipartite (__true__) or not (__false__). If the variable
*bipartvar* is specified the two partitions of the graph are there as a
list, if, and only if the graph is bipartit. If it is not the variable, if
specified, is not touched.
- <a name='6'></a>__struct::graph::op::tarjan__ *g*
This command computes the set of *strongly connected* components (SCCs) of
the graph *g*. The result of the command is a list of sets, each of which
contains the nodes for one of the SCCs of *g*. The union of all SCCs covers
the whole graph, and no two SCCs intersect with each other.
The graph *g* is *acyclic* if all SCCs in the result contain only a single
node. The graph *g* is *strongly connected* if the result contains only a
single SCC containing all nodes of *g*.
- <a name='7'></a>__struct::graph::op::connectedComponents__ *g*
This command computes the set of *connected* components (CCs) of the graph
*g*. The result of the command is a list of sets, each of which contains the
nodes for one of the CCs of *g*. The union of all CCs covers the whole
graph, and no two CCs intersect with each other.
The graph *g* is *connected* if the result contains only a single SCC
containing all nodes of *g*.
- <a name='8'></a>__struct::graph::op::connectedComponentOf__ *g* *n*
This command computes the *connected* component (CC) of the graph *g*
containing the node *n*. The result of the command is a sets which contains
the nodes for the CC of *n* in *g*.
The command will throw an error if *n* is not a node of the graph *g*.
- <a name='9'></a>__struct::graph::op::isConnected?__ *g*
This is a convenience command determining whether the graph *g* is
*connected* or not. The result is a boolean value, __true__ if the graph is
connected, and __false__ otherwise.
- <a name='10'></a>__struct::graph::op::isCutVertex?__ *g* *n*
This command determines whether the node *n* in the graph *g* is a *[cut
vertex](../../../../index.md#cut_vertex)* (aka *[articulation
point](../../../../index.md#articulation_point)*). The result is a boolean
value, __true__ if the node is a cut vertex, and __false__ otherwise.
The command will throw an error if *n* is not a node of the graph *g*.
- <a name='11'></a>__struct::graph::op::isBridge?__ *g* *a*
This command determines whether the arc *a* in the graph *g* is a
*[bridge](../../../../index.md#bridge)* (aka *[cut
edge](../../../../index.md#cut_edge)*, or
*[isthmus](../../../../index.md#isthmus)*). The result is a boolean value,
__true__ if the arc is a bridge, and __false__ otherwise.
The command will throw an error if *a* is not an arc of the graph *g*.
- <a name='12'></a>__struct::graph::op::isEulerian?__ *g* ?*tourvar*?
This command determines whether the graph *g* is *eulerian* or not. The
result is a boolean value, __true__ if the graph is eulerian, and __false__
otherwise.
If the graph is eulerian and *tourvar* is specified then an euler tour is
computed as well and stored in the named variable. The tour is represented
by the list of arcs traversed, in the order of traversal.
- <a name='13'></a>__struct::graph::op::isSemiEulerian?__ *g* ?*pathvar*?
This command determines whether the graph *g* is *semi-eulerian* or not. The
result is a boolean value, __true__ if the graph is semi-eulerian, and
__false__ otherwise.
If the graph is semi-eulerian and *pathvar* is specified then an euler path
is computed as well and stored in the named variable. The path is
represented by the list of arcs traversed, in the order of traversal.
- <a name='14'></a>__struct::graph::op::dijkstra__ *g* *start* ?*options*...?
This command determines distances in the weighted *g* from the node *start*
to all other nodes in the graph. The options specify how to traverse graphs,
and the format of the result.
Two options are recognized
* __-arcmode__ mode
The accepted mode values are __directed__ and __undirected__. For
directed traversal all arcs are traversed from source to target. For
undirected traversal all arcs are traversed in the opposite direction as
well. Undirected traversal is the default.
* __-outputformat__ format
The accepted format values are __distances__ and __tree__. In both cases
the result is a dictionary keyed by the names of all nodes in the graph.
For __distances__ the value is the distance of the node to *start*,
whereas for __tree__ the value is the path from the node to *start*,
excluding the node itself, but including *start*. Tree format is the
default.
- <a name='15'></a>__struct::graph::op::distance__ *g* *origin* *destination* ?*options*...?
This command determines the (un)directed distance between the two nodes
*origin* and *destination* in the graph *g*. It accepts the option
__-arcmode__ of __struct::graph::op::dijkstra__.
- <a name='16'></a>__struct::graph::op::eccentricity__ *g* *n* ?*options*...?
This command determines the (un)directed
*[eccentricity](../../../../index.md#eccentricity)* of the node *n* in the
graph *g*. It accepts the option __-arcmode__ of
__struct::graph::op::dijkstra__.
The (un)directed *[eccentricity](../../../../index.md#eccentricity)* of a
node is the maximal (un)directed distance between the node and any other
node in the graph.
- <a name='17'></a>__struct::graph::op::radius__ *g* ?*options*...?
This command determines the (un)directed
*[radius](../../../../index.md#radius)* of the graph *g*. It accepts the
option __-arcmode__ of __struct::graph::op::dijkstra__.
The (un)directed *[radius](../../../../index.md#radius)* of a graph is the
minimal (un)directed *[eccentricity](../../../../index.md#eccentricity)* of
all nodes in the graph.
- <a name='18'></a>__struct::graph::op::diameter__ *g* ?*options*...?
This command determines the (un)directed
*[diameter](../../../../index.md#diameter)* of the graph *g*. It accepts the
option __-arcmode__ of __struct::graph::op::dijkstra__.
The (un)directed *[diameter](../../../../index.md#diameter)* of a graph is
the maximal (un)directed *[eccentricity](../../../../index.md#eccentricity)*
of all nodes in the graph.
- <a name='19'></a>__struct::graph::op::BellmanFord__ *G* *startnode*
Searching for [shortests paths](#subsection1) between chosen node and all
other nodes in graph *G*. Based on relaxation method. In comparison to
__struct::graph::op::dijkstra__ it doesn't need assumption that all weights
on edges in input graph *G* have to be positive.
That generality sets the complexity of algorithm to - *O(V*E)*, where *V* is
the number of vertices and *[E](../../../../index.md#e)* is number of edges
in graph *G*.
* Arguments:
+ Graph object *G* (input)
Directed, connected and edge weighted graph *G*, without any
negative cycles ( presence of cycles with the negative sum of weight
means that there is no shortest path, since the total weight becomes
lower each time the cycle is traversed ). Negative weights on edges
are allowed.
+ Node *startnode* (input)
The node for which we find all shortest paths to each other node in
graph *G*.
* Result:
Dictionary containing for each node (key) distances to each other node
in graph *G*.
*Note:* If algorithm finds a negative cycle, it will return error message.
- <a name='20'></a>__struct::graph::op::Johnsons__ *G* ?*options*...?
Searching for [shortest paths](#subsection1) between all pairs of vertices
in graph. For sparse graphs asymptotically quicker than
__struct::graph::op::FloydWarshall__ algorithm. Johnson's algorithm uses
__struct::graph::op::BellmanFord__ and __struct::graph::op::dijkstra__ as
subprocedures.
Time complexity: *O(n**2*log(n) +n*m)*, where *n* is the number of nodes and
*m* is the number of edges in graph *G*.
* Arguments:
+ Graph object *G* (input)
Directed graph *G*, weighted on edges and not containing any cycles
with negative sum of weights ( the presence of such cycles means
there is no shortest path, since the total weight becomes lower each
time the cycle is traversed ). Negative weights on edges are
allowed.
* Options:
+ __-filter__
Returns only existing distances, cuts all *Inf* values for
non-existing connections between pairs of nodes.
* Result:
Dictionary containing distances between all pairs of vertices.
- <a name='21'></a>__struct::graph::op::FloydWarshall__ *G*
Searching for [shortest paths](#subsection1) between all pairs of edges in
weighted graphs.
Time complexity: *O(V^3)* - where *V* is number of vertices.
Memory complexity: *O(V^2)*.
* Arguments:
+ Graph object *G* (input)
Directed and weighted graph *G*.
* Result:
Dictionary containing shortest distances to each node from each node.
*Note:* Algorithm finds solutions dynamically. It compares all possible
paths through the graph between each pair of vertices. Graph shouldn't
possess any cycle with negative sum of weights (the presence of such cycles
means there is no shortest path, since the total weight becomes lower each
time the cycle is traversed).
On the other hand algorithm can be used to find those cycles - if any
shortest distance found by algorithm for any nodes *v* and *u* (when *v* is
the same node as *u*) is negative, that node surely belong to at least one
negative cycle.
- <a name='22'></a>__struct::graph::op::MetricTravellingSalesman__ *G*
Algorithm for solving a metric variation of [Travelling salesman
problem](#subsection2). *TSP problem* is *NP-Complete*, so there is no
efficient algorithm to solve it. Greedy methods are getting extremely slow,
with the increase in the set of nodes.
* Arguments:
+ Graph object *G* (input)
Undirected, weighted graph *G*.
* Result:
Approximated solution of minimum *Hamilton Cycle* - closed path visiting
all nodes, each exactly one time.
*Note:* [It's 2-approximation algorithm.](#subsection7)
- <a name='23'></a>__struct::graph::op::Christofides__ *G*
Another algorithm for solving [metric *TSP problem*](#subsection2).
Christofides implementation uses *Max Matching* for reaching better
approximation factor.
* Arguments:
+ Graph Object *G* (input)
Undirected, weighted graph *G*.
* Result:
Approximated solution of minimum *Hamilton Cycle* - closed path visiting
all nodes, each exactly one time.
*Note:* [It's is a 3/2 approximation algorithm. ](#subsection7)
- <a name='24'></a>__struct::graph::op::GreedyMaxMatching__ *G*
*Greedy Max Matching* procedure, which finds [maximal
matching](#subsection3) (not maximum) for given graph *G*. It adds edges to
solution, beginning from edges with the lowest cost.
* Arguments:
+ Graph Object *G* (input)
Undirected graph *G*.
* Result:
Set of edges - the max matching for graph *G*.
- <a name='25'></a>__struct::graph::op::MaxCut__ *G* *U* *V*
Algorithm solving a [Maximum Cut Problem](#subsection4).
* Arguments:
+ Graph Object *G* (input)
The graph to cut.
+ List *U* (output)
Variable storing first set of nodes (cut) given by solution.
+ List *V* (output)
Variable storing second set of nodes (cut) given by solution.
* Result:
Algorithm returns number of edges between found two sets of nodes.
*Note:* *MaxCut* is a [2-approximation algorithm.](#subsection7)
- <a name='26'></a>__struct::graph::op::UnweightedKCenter__ *G* *k*
Approximation algorithm that solves a [k-center problem](#subsection5).
* Arguments:
+ Graph Object *G* (input)
Undirected complete graph *G*, which satisfies triangle inequality.
+ Integer *k* (input)
Positive integer that sets the number of nodes that will be included
in *k-center*.
* Result:
Set of nodes - *k* center for graph *G*.
*Note:* *UnweightedKCenter* is a [2-approximation algorithm.](#subsection7)
- <a name='27'></a>__struct::graph::op::WeightedKCenter__ *G* *nodeWeights* *W*
Approximation algorithm that solves a weighted version of [k-center
problem](#subsection5).
* Arguments:
+ Graph Object *G* (input)
Undirected complete graph *G*, which satisfies triangle inequality.
+ Integer *W* (input)
Positive integer that sets the maximum possible weight of *k-center*
found by algorithm.
+ List *nodeWeights* (input)
List of nodes and its weights in graph *G*.
* Result:
Set of nodes, which is solution found by algorithm.
*Note:**WeightedKCenter* is a [3-approximation algorithm.](#subsection7)
- <a name='28'></a>__struct::graph::op::GreedyMaxIndependentSet__ *G*
A *maximal independent set* is an *[independent
set](../../../../index.md#independent_set)* such that adding any other node
to the set forces the set to contain an edge.
Algorithm for input graph *G* returns set of nodes (list), which are
contained in Max Independent Set found by algorithm.
- <a name='29'></a>__struct::graph::op::GreedyWeightedMaxIndependentSet__ *G* *nodeWeights*
Weighted variation of *Maximal Independent Set*. It takes as an input
argument not only graph *G* but also set of weights for all vertices in
graph *G*.
*Note:* Read also *Maximal Independent Set* description for more info.
- <a name='30'></a>__struct::graph::op::VerticesCover__ *G*
*Vertices cover* is a set of vertices such that each edge of the graph is
incident to at least one vertex of the set. This 2-approximation algorithm
searches for minimum *vertices cover*, which is a classical optimization
problem in computer science and is a typical example of an *NP-hard*
optimization problem that has an approximation algorithm. For input graph
*G* algorithm returns the set of edges (list), which is Vertex Cover found
by algorithm.
- <a name='31'></a>__struct::graph::op::EdmondsKarp__ *G* *s* *t*
Improved Ford-Fulkerson's algorithm, computing the [maximum
flow](#subsection6) in given flow network *G*.
* Arguments:
+ Graph Object *G* (input)
Weighted and directed graph. Each edge should have set integer
attribute considered as maximum throughputs that can be carried by
that link (edge).
+ Node *s* (input)
The node that is a source for graph *G*.
+ Node *t* (input)
The node that is a sink for graph *G*.
* Result:
Procedure returns the dictionary containing throughputs for all edges.
For each key ( the edge between nodes *u* and *v* in the form of *list u
v* ) there is a value that is a throughput for that key. Edges where
throughput values are equal to 0 are not returned ( it is like there was
no link in the flow network between nodes connected by such edge).
The general idea of algorithm is finding the shortest augumenting paths in
graph *G*, as long as they exist, and for each path updating the edge's
weights along that path, with maximum possible throughput. The final
(maximum) flow is found when there is no other augumenting path from source
to sink.
*Note:* Algorithm complexity : *O(V*E)*, where *V* is the number of nodes
and *[E](../../../../index.md#e)* is the number of edges in graph *G*.
- <a name='32'></a>__struct::graph::op::BusackerGowen__ *G* *desiredFlow* *s* *t*
Algorithm finds solution for a [minimum cost flow problem](#subsection6).
So, the goal is to find a flow, whose max value can be *desiredFlow*, from
source node *s* to sink node *t* in given flow network *G*. That network
except throughputs at edges has also defined a non-negative cost on each
edge - cost of using that edge when directing flow with that edge ( it can
illustrate e.g. fuel usage, time or any other measure dependent on usages ).
* Arguments:
+ Graph Object *G* (input)
Flow network (directed graph), each edge in graph should have two
integer attributes: *cost* and *throughput*.
+ Integer *desiredFlow* (input)
Max value of the flow for that network.
+ Node *s* (input)
The source node for graph *G*.
+ Node *t* (input)
The sink node for graph *G*.
* Result:
Dictionary containing values of used throughputs for each edge ( key ).
found by algorithm.
*Note:* Algorithm complexity : *O(V**2*desiredFlow)*, where *V* is the
number of nodes in graph *G*.
- <a name='33'></a>__struct::graph::op::ShortestsPathsByBFS__ *G* *s* *outputFormat*
Shortest pathfinding algorithm using BFS method. In comparison to
__struct::graph::op::dijkstra__ it can work with negative weights on edges.
Of course negative cycles are not allowed. Algorithm is better than dijkstra
for sparse graphs, but also there exist some pathological cases (those cases
generally don't appear in practise) that make time complexity increase
exponentially with the growth of the number of nodes.
* Arguments:
+ Graph Object *G* (input)
Input graph.
+ Node *s* (input)
Source node for which all distances to each other node in graph *G*
are computed.
* Options and result:
+ __distances__
When selected *outputFormat* is __distances__ - procedure returns
dictionary containing distances between source node *s* and each
other node in graph *G*.
+ __paths__
When selected *outputFormat* is __paths__ - procedure returns
dictionary containing for each node *v*, a list of nodes, which is a
path between source node *s* and node *v*.
- <a name='34'></a>__struct::graph::op::BFS__ *G* *s* ?*outputFormat*...?
Breadth-First Search - algorithm creates the BFS Tree. Memory and time
complexity: *O(V + E)*, where *V* is the number of nodes and
*[E](../../../../index.md#e)* is number of edges.
* Arguments:
+ Graph Object *G* (input)
Input graph.
+ Node *s* (input)
Source node for BFS procedure.
* Options and result:
+ __graph__
When selected __outputFormat__ is __graph__ - procedure returns a
graph structure (__[struct::graph](graph.md)__), which is equivalent
to BFS tree found by algorithm.
+ __tree__
When selected __outputFormat__ is __tree__ - procedure returns a
tree structure (__[struct::tree](struct_tree.md)__), which is
equivalent to BFS tree found by algorithm.
- <a name='35'></a>__struct::graph::op::MinimumDiameterSpanningTree__ *G*
The goal is to find for input graph *G*, the *spanning tree* that has the
minimum *[diameter](../../../../index.md#diameter)* value.
General idea of algorithm is to run *[BFS](../../../../index.md#bfs)* over
all vertices in graph *G*. If the diameter *d* of the tree is odd, then we
are sure that tree given by *[BFS](../../../../index.md#bfs)* is minimum
(considering diameter value). When, diameter *d* is even, then optimal tree
can have minimum *[diameter](../../../../index.md#diameter)* equal to *d* or
*d-1*.
In that case, what algorithm does is rebuilding the tree given by
*[BFS](../../../../index.md#bfs)*, by adding a vertice between root node and
root's child node (nodes), such that subtree created with child node as root
node is the greatest one (has the greatests height). In the next step for
such rebuilded tree, we run again *[BFS](../../../../index.md#bfs)* with new
node as root node. If the height of the tree didn't changed, we have found a
better solution.
For input graph *G* algorithm returns the graph structure
(__[struct::graph](graph.md)__) that is a spanning tree with minimum
diameter found by algorithm.
- <a name='36'></a>__struct::graph::op::MinimumDegreeSpanningTree__ *G*
Algorithm finds for input graph *G*, a spanning tree *T* with the minimum
possible degree. That problem is *NP-hard*, so algorithm is an approximation
algorithm.
Let *V* be the set of nodes for graph *G* and let *W* be any subset of *V*.
Lets assume also that *OPT* is optimal solution and *ALG* is solution found
by algorithm for input graph *G*.
It can be proven that solution found with the algorithm must fulfil
inequality:
*((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1*.
* Arguments:
+ Graph Object *G* (input)
Undirected simple graph.
* Result:
Algorithm returns graph structure, which is equivalent to spanning tree
*T* found by algorithm.
- <a name='37'></a>__struct::graph::op::MaximumFlowByDinic__ *G* *s* *t* *blockingFlowAlg*
Algorithm finds [maximum flow](#subsection6) for the flow network
represented by graph *G*. It is based on the blocking-flow finding methods,
which give us different complexities what makes a better fit for different
graphs.
* Arguments:
+ Graph Object *G* (input)
Directed graph *G* representing the flow network. Each edge should
have attribute *throughput* set with integer value.
+ Node *s* (input)
The source node for the flow network *G*.
+ Node *t* (input)
The sink node for the flow network *G*.
* Options:
+ __dinic__
Procedure will find maximum flow for flow network *G* using Dinic's
algorithm (__struct::graph::op::BlockingFlowByDinic__) for blocking
flow computation.
+ __mkm__
Procedure will find maximum flow for flow network *G* using
Malhotra, Kumar and Maheshwari's algorithm
(__struct::graph::op::BlockingFlowByMKM__) for blocking flow
computation.
* Result:
Algorithm returns dictionary containing it's flow value for each edge
(key) in network *G*.
*Note:* __struct::graph::op::BlockingFlowByDinic__ gives *O(m*n^2)*
complexity and __struct::graph::op::BlockingFlowByMKM__ gives *O(n^3)*
complexity, where *n* is the number of nodes and *m* is the number of edges
in flow network *G*.
- <a name='38'></a>__struct::graph::op::BlockingFlowByDinic__ *G* *s* *t*
Algorithm for given network *G* with source *s* and sink *t*, finds a
[blocking flow](#subsection6), which can be used to obtain a *[maximum
flow](../../../../index.md#maximum_flow)* for that network *G*.
* Arguments:
+ Graph Object *G* (input)
Directed graph *G* representing the flow network. Each edge should
have attribute *throughput* set with integer value.
+ Node *s* (input)
The source node for the flow network *G*.
+ Node *t* (input)
The sink node for the flow network *G*.
* Result:
Algorithm returns dictionary containing it's blocking flow value for
each edge (key) in network *G*.
*Note:* Algorithm's complexity is *O(n*m)*, where *n* is the number of nodes
and *m* is the number of edges in flow network *G*.
- <a name='39'></a>__struct::graph::op::BlockingFlowByMKM__ *G* *s* *t*
Algorithm for given network *G* with source *s* and sink *t*, finds a
[blocking flow](#subsection6), which can be used to obtain a *[maximum
flow](../../../../index.md#maximum_flow)* for that
*[network](../../../../index.md#network)* *G*.
* Arguments:
+ Graph Object *G* (input)
Directed graph *G* representing the flow network. Each edge should
have attribute *throughput* set with integer value.
+ Node *s* (input)
The source node for the flow network *G*.
+ Node *t* (input)
The sink node for the flow network *G*.
* Result:
Algorithm returns dictionary containing it's blocking flow value for
each edge (key) in network *G*.
*Note:* Algorithm's complexity is *O(n^2)*, where *n* is the number of nodes
in flow network *G*.
- <a name='40'></a>__struct::graph::op::createResidualGraph__ *G* *f*
Procedure creates a *[residual graph](../../../../index.md#residual_graph)*
(or [residual network](#subsection6) ) for network *G* and given flow *f*.
* Arguments:
+ Graph Object *G* (input)
Flow network (directed graph where each edge has set attribute:
*throughput* ).
+ dictionary *f* (input)
Current flows in flow network *G*.
* Result:
Procedure returns graph structure that is a *[residual
graph](../../../../index.md#residual_graph)* created from input flow
network *G*.
- <a name='41'></a>__struct::graph::op::createAugmentingNetwork__ *G* *f* *path*
Procedure creates an [augmenting network](#subsection6) for a given residual
network *G* , flow *f* and augmenting path *path*.
* Arguments:
+ Graph Object *G* (input)
Residual network (directed graph), where for every edge there are
set two attributes: throughput and cost.
+ Dictionary *f* (input)
Dictionary which contains for every edge (key), current value of the
flow on that edge.
+ List *path* (input)
Augmenting path, set of edges (list) for which we create the network
modification.
* Result:
Algorithm returns graph structure containing the modified augmenting
network.
- <a name='42'></a>__struct::graph::op::createLevelGraph__ *Gf* *s*
For given residual graph *Gf* procedure finds the [level
graph](#subsection6).
* Arguments:
+ Graph Object *Gf* (input)
Residual network, where each edge has it's attribute *throughput*
set with certain value.
+ Node *s* (input)
The source node for the residual network *Gf*.
* Result:
Procedure returns a *[level graph](../../../../index.md#level_graph)*
created from input *residual network*.
- <a name='43'></a>__struct::graph::op::TSPLocalSearching__ *G* *C*
Algorithm is a *heuristic of local searching* for *Travelling Salesman
Problem*. For some solution of *TSP problem*, it checks if it's possible to
find a better solution. As *TSP* is well known NP-Complete problem, so
algorithm is a approximation algorithm (with 2 approximation factor).
* Arguments:
+ Graph Object *G* (input)
Undirected and complete graph with attributes "weight" set on each
single edge.
+ List *C* (input)
A list of edges being *Hamiltonian cycle*, which is solution of *TSP
Problem* for graph *G*.
* Result:
Algorithm returns the best solution for *TSP problem*, it was able to
find.
*Note:* The solution depends on the choosing of the beginning cycle *C*.
It's not true that better cycle assures that better solution will be found,
but practise shows that we should give starting cycle with as small sum of
weights as possible.
- <a name='44'></a>__struct::graph::op::TSPLocalSearching3Approx__ *G* *C*
Algorithm is a *heuristic of local searching* for *Travelling Salesman
Problem*. For some solution of *TSP problem*, it checks if it's possible to
find a better solution. As *TSP* is well known NP-Complete problem, so
algorithm is a approximation algorithm (with 3 approximation factor).
* Arguments:
+ Graph Object *G* (input)
Undirected and complete graph with attributes "weight" set on each
single edge.
+ List *C* (input)
A list of edges being *Hamiltonian cycle*, which is solution of *TSP
Problem* for graph *G*.
* Result:
Algorithm returns the best solution for *TSP problem*, it was able to
find.
*Note:* In practise 3-approximation algorithm turns out to be far more
effective than 2-approximation, but it gives worser approximation factor.
Further heuristics of local searching (e.g. 4-approximation) doesn't give
enough boost to square the increase of approximation factor, so 2 and 3
approximations are mainly used.
- <a name='45'></a>__struct::graph::op::createSquaredGraph__ *G*
X-Squared graph is a graph with the same set of nodes as input graph *G*,
but a different set of edges. X-Squared graph has edge *(u,v)*, if and only
if, the distance between *u* and *v* nodes is not greater than X and *u !=
v*.
Procedure for input graph *G*, returns its two-squared graph.
*Note:* Distances used in choosing new set of edges are considering the
number of edges, not the sum of weights at edges.
- <a name='46'></a>__struct::graph::op::createCompleteGraph__ *G* *originalEdges*
For input graph *G* procedure adds missing arcs to make it a *[complete
graph](../../../../index.md#complete_graph)*. It also holds in variable
*originalEdges* the set of arcs that graph *G* possessed before that
operation.
# <a name='section3'></a>Background theory and terms
## <a name='subsection1'></a>Shortest Path Problem
- Definition (*single-pair shortest path problem*):
Formally, given a weighted graph (let *V* be the set of vertices, and
*[E](../../../../index.md#e)* a set of edges), and one vertice *v* of *V*,
find a path *P* from *v* to a *v'* of V so that the sum of weights on edges
along the path is minimal among all paths connecting v to v'.
- Generalizations:
*The single-source shortest path problem*, in which we have to find shortest
paths from a source vertex v to all other vertices in the graph.
*The single-destination shortest path problem*, in which we have to find
shortest paths from all vertices in the graph to a single destination vertex
v. This can be reduced to the single-source shortest path problem by
reversing the edges in the graph.
*The all-pairs shortest path problem*, in which we have to find shortest
paths between every pair of vertices v, v' in the graph.
*Note:* The result of *Shortest Path problem* can be *Shortest Path tree*,
which is a subgraph of a given (possibly weighted) graph constructed so that
the distance between a selected root node and all other nodes is minimal. It
is a tree because if there are two paths between the root node and some
vertex v (i.e. a cycle), we can delete the last edge of the longer path
without increasing the distance from the root node to any node in the
subgraph.
## <a name='subsection2'></a>Travelling Salesman Problem
- Definition:
For given edge-weighted (weights on edges should be positive) graph the goal
is to find the cycle that visits each node in graph exactly once
(*Hamiltonian cycle*).
- Generalizations:
*Metric TSP* - A very natural restriction of the *TSP* is to require that
the distances between cities form a *metric*, i.e., they satisfy *the
triangle inequality*. That is, for any 3 cities *A*, *B* and
*[C](../../../../index.md#c)*, the distance between *A* and
*[C](../../../../index.md#c)* must be at most the distance from *A* to *B*
plus the distance from *B* to *[C](../../../../index.md#c)*. Most natural
instances of *TSP* satisfy this constraint.
*Euclidean TSP* - Euclidean TSP, or *planar TSP*, is the *TSP* with the
distance being the ordinary *Euclidean distance*. *Euclidean TSP* is a
particular case of *TSP* with *triangle inequality*, since distances in
plane obey triangle inequality. However, it seems to be easier than general
*TSP* with *triangle inequality*. For example, *the minimum spanning tree*
of the graph associated with an instance of *Euclidean TSP* is a *Euclidean
minimum spanning tree*, and so can be computed in expected *O(n log n)* time
for *n* points (considerably less than the number of edges). This enables
the simple *2-approximation algorithm* for TSP with triangle inequality
above to operate more quickly.
*Asymmetric TSP* - In most cases, the distance between two nodes in the
*TSP* network is the same in both directions. The case where the distance
from *A* to *B* is not equal to the distance from *B* to *A* is called
*asymmetric TSP*. A practical application of an *asymmetric TSP* is route
optimisation using street-level routing (asymmetric due to one-way streets,
slip-roads and motorways).
## <a name='subsection3'></a>Matching Problem
- Definition:
Given a graph *G = (V,E)*, a matching or *edge-independent set* *M* in *G*
is a set of pairwise non-adjacent edges, that is, no two edges share a
common vertex. A vertex is *matched* if it is incident to an edge in the
*matching M*. Otherwise the vertex is *unmatched*.
- Generalizations:
*Maximal matching* - a matching *M* of a graph G with the property that if
any edge not in *M* is added to *M*, it is no longer a
*[matching](../../../../index.md#matching)*, that is, *M* is maximal if it
is not a proper subset of any other
*[matching](../../../../index.md#matching)* in graph G. In other words, a
*matching M* of a graph G is maximal if every edge in G has a non-empty
intersection with at least one edge in *M*.
*Maximum matching* - a matching that contains the largest possible number of
edges. There may be many *maximum matchings*. The *matching number* of a
graph G is the size of a *maximum matching*. Note that every *maximum
matching* is *maximal*, but not every *maximal matching* is a *maximum
matching*.
*Perfect matching* - a matching which matches all vertices of the graph.
That is, every vertex of the graph is incident to exactly one edge of the
matching. Every *perfect matching* is
*[maximum](../../../../index.md#maximum)* and hence *maximal*. In some
literature, the term *complete matching* is used. A *perfect matching* is
also a *minimum-size edge cover*. Moreover, the size of a *maximum matching*
is no larger than the size of a *minimum edge cover*.
*Near-perfect matching* - a matching in which exactly one vertex is
unmatched. This can only occur when the graph has an odd number of vertices,
and such a *[matching](../../../../index.md#matching)* must be
*[maximum](../../../../index.md#maximum)*. If, for every vertex in a graph,
there is a near-perfect matching that omits only that vertex, the graph is
also called *factor-critical*.
- Related terms:
*Alternating path* - given a matching *M*, an *alternating path* is a path
in which the edges belong alternatively to the matching and not to the
matching.
*[Augmenting path](../../../../index.md#augmenting_path)* - given a matching
*M*, an *[augmenting path](../../../../index.md#augmenting_path)* is an
*alternating path* that starts from and ends on free (unmatched) vertices.
## <a name='subsection4'></a>Cut Problems
- Definition:
A *cut* is a partition of the vertices of a graph into two *disjoint
subsets*. The *cut-set* of the *cut* is the set of edges whose end points
are in different subsets of the partition. Edges are said to be crossing the
cut if they are in its *cut-set*.
Formally:
a *cut* *C = (S,T)* is a partition of *V* of a graph *G = (V, E)*.
an *s-t cut* *C = (S,T)* of a *[flow
network](../../../../index.md#flow_network)* *N = (V, E)* is a cut of *N*
such that *s* is included in *S* and *t* is included in *T*, where *s* and
*t* are the *[source](../../../../index.md#source)* and the *sink* of *N*
respectively.
The *cut-set* of a *cut C = (S,T)* is such set of edges from graph *G = (V,
E)* that each edge *(u, v)* satisfies condition that *u* is included in *S*
and *v* is included in *T*.
In an *unweighted undirected* graph, the size or weight of a cut is the
number of edges crossing the cut. In a *weighted graph*, the same term is
defined by the sum of the weights of the edges crossing the cut.
In a *[flow network](../../../../index.md#flow_network)*, an *s-t cut* is a
cut that requires the *[source](../../../../index.md#source)* and the *sink*
to be in different subsets, and its *cut-set* only consists of edges going
from the *source's* side to the *sink's* side. The capacity of an *s-t cut*
is defined by the sum of capacity of each edge in the *cut-set*.
The *cut* of a graph can sometimes refer to its *cut-set* instead of the
partition.
- Generalizations:
*Minimum cut* - A cut is minimum if the size of the cut is not larger than
the size of any other cut.
*Maximum cut* - A cut is maximum if the size of the cut is not smaller than
the size of any other cut.
*Sparsest cut* - The *Sparsest cut problem* is to bipartition the vertices
so as to minimize the ratio of the number of edges across the cut divided by
the number of vertices in the smaller half of the partition.
## <a name='subsection5'></a>K-Center Problem
- Definitions:
* *Unweighted K-Center*
For any set *S* ( which is subset of *V* ) and node *v*, let the
*connect(v,S)* be the cost of cheapest edge connecting *v* with any node
in *S*. The goal is to find such *S*, that *|S| = k* and
*max_v{connect(v,S)}* is possibly small.
In other words, we can use it i.e. for finding best locations in the
city ( nodes of input graph ) for placing k buildings, such that those
buildings will be as close as possible to all other locations in town.
* *Weighted K-Center*
The variation of *unweighted k-center problem*. Besides the fact graph
is edge-weighted, there are also weights on vertices of input graph *G*.
We've got also restriction *W*. The goal is to choose such set of nodes
*S* ( which is a subset of *V* ), that it's total weight is not greater
than *W* and also function: *max_v { min_u { cost(u,v) }}* has the
smallest possible worth ( *v* is a node in *V* and *u* is a node in *S*
).
## <a name='subsection6'></a>Flow Problems
- Definitions:
*the maximum flow problem* - the goal is to find a feasible flow through a
single-source, single-sink flow network that is maximum. The *maximum flow
problem* can be seen as a special case of more complex network flow
problems, such as the *circulation problem*. The maximum value of an *s-t
flow* is equal to the minimum capacity of an *s-t cut* in the network, as
stated in the *max-flow min-cut theorem*.
More formally for flow network *G = (V,E)*, where for each edge *(u, v)* we
have its throuhgput *c(u,v)* defined. As *[flow](../../../../index.md#flow)*
*F* we define set of non-negative integer attributes *f(u,v)* assigned to
edges, satisfying such conditions:
for each edge *(u, v)* in *G* such condition should be satisfied: 0 <=
f(u,v) <= c(u,v)
Network *G* has source node *s* such that the flow *F* is equal to the sum
of outcoming flow decreased by the sum of incoming flow from that source
node *s*.
Network *G* has sink node *t* such that the the *-F* value is equal to the
sum of the incoming flow decreased by the sum of outcoming flow from that
sink node *t*.
For each node that is not a *[source](../../../../index.md#source)* or
*sink* the sum of incoming flow and sum of outcoming flow should be equal.
*the minimum cost flow problem* - the goal is finding the cheapest possible
way of sending a certain amount of flow through a *[flow
network](../../../../index.md#flow_network)*.
*[blocking flow](../../../../index.md#blocking_flow)* - a *[blocking
flow](../../../../index.md#blocking_flow)* for a *residual network* *Gf* we
name such flow *b* in *Gf* that:
Each path from *sink* to *[source](../../../../index.md#source)* is the
shortest path in *Gf*.
Each shortest path in *Gf* contains an edge with fully used throughput in
*Gf+b*.
*residual network* - for a flow network *G* and flow *f* *residual network*
is built with those edges, which can send larger flow. It contains only
those edges, which can send flow larger than 0.
*level network* - it has the same set of nodes as *[residual
graph](../../../../index.md#residual_graph)*, but has only those edges
*(u,v)* from *Gf* for which such equality is satisfied: *distance(s,u)+1 =
distance(s,v)*.
*[augmenting network](../../../../index.md#augmenting_network)* - it is a
modification of *residual network* considering the new flow values.
Structure stays unchanged but values of throughputs and costs at edges are
different.
## <a name='subsection7'></a>Approximation algorithm
- k-approximation algorithm:
Algorithm is a k-approximation, when for *ALG* (solution returned by
algorithm) and *OPT* (optimal solution), such inequality is true:
for minimalization problems: *ALG/OPT <= k*
for maximalization problems: *OPT/ALG <= k*
# <a name='section4'></a>References
1. [Adjacency matrix](http://en.wikipedia.org/wiki/Adjacency_matrix)
1. [Adjacency list](http://en.wikipedia.org/wiki/Adjacency_list)
1. [Kruskal's algorithm](http://en.wikipedia.org/wiki/Kruskal%27s_algorithm)
1. [Prim's algorithm](http://en.wikipedia.org/wiki/Prim%27s_algorithm)
1. [Bipartite graph](http://en.wikipedia.org/wiki/Bipartite_graph)
1. [Strongly connected
components](http://en.wikipedia.org/wiki/Strongly_connected_components)
1. [Tarjan's strongly connected components
algorithm](http://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm)
1. [Cut vertex](http://en.wikipedia.org/wiki/Cut_vertex)
1. [Bridge](http://en.wikipedia.org/wiki/Bridge_(graph_theory))
1. [Bellman-Ford's
algorithm](http://en.wikipedia.org/wiki/Bellman-Ford_algorithm)
1. [Johnson's algorithm](http://en.wikipedia.org/wiki/Johnson_algorithm)
1. [Floyd-Warshall's
algorithm](http://en.wikipedia.org/wiki/Floyd-Warshall_algorithm)
1. [Travelling Salesman
Problem](http://en.wikipedia.org/wiki/Travelling_salesman_problem)
1. [Christofides
Algorithm](http://en.wikipedia.org/wiki/Christofides_algorithm)
1. [Max Cut](http://en.wikipedia.org/wiki/Maxcut)
1. [Matching](http://en.wikipedia.org/wiki/Matching)
1. [Max Independent Set](http://en.wikipedia.org/wiki/Maximal_independent_set)
1. [Vertex Cover](http://en.wikipedia.org/wiki/Vertex_cover_problem)
1. [Ford-Fulkerson's
algorithm](http://en.wikipedia.org/wiki/Ford-Fulkerson_algorithm)
1. [Maximum Flow problem](http://en.wikipedia.org/wiki/Maximum_flow_problem)
1. [Busacker-Gowen's
algorithm](http://en.wikipedia.org/wiki/Minimum_cost_flow_problem)
1. [Dinic's algorithm](http://en.wikipedia.org/wiki/Dinic's_algorithm)
1. [K-Center problem](http://www.csc.kth.se/~viggo/wwwcompendium/node128.html)
1. [BFS](http://en.wikipedia.org/wiki/Breadth-first_search)
1. [Minimum Degree Spanning
Tree](http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree)
1. [Approximation
algorithm](http://en.wikipedia.org/wiki/Approximation_algorithm)
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: graph* 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.
# <a name='keywords'></a>KEYWORDS
[adjacency list](../../../../index.md#adjacency_list), [adjacency
matrix](../../../../index.md#adjacency_matrix),
[adjacent](../../../../index.md#adjacent), [approximation
algorithm](../../../../index.md#approximation_algorithm),
[arc](../../../../index.md#arc), [articulation
point](../../../../index.md#articulation_point), [augmenting
network](../../../../index.md#augmenting_network), [augmenting
path](../../../../index.md#augmenting_path), [bfs](../../../../index.md#bfs),
[bipartite](../../../../index.md#bipartite), [blocking
flow](../../../../index.md#blocking_flow),
[bridge](../../../../index.md#bridge), [complete
graph](../../../../index.md#complete_graph), [connected
component](../../../../index.md#connected_component), [cut
edge](../../../../index.md#cut_edge), [cut
vertex](../../../../index.md#cut_vertex), [degree](../../../../index.md#degree),
[degree constrained spanning
tree](../../../../index.md#degree_constrained_spanning_tree),
[diameter](../../../../index.md#diameter),
[dijkstra](../../../../index.md#dijkstra),
[distance](../../../../index.md#distance),
[eccentricity](../../../../index.md#eccentricity),
[edge](../../../../index.md#edge), [flow
network](../../../../index.md#flow_network),
[graph](../../../../index.md#graph),
[heuristic](../../../../index.md#heuristic), [independent
set](../../../../index.md#independent_set),
[isthmus](../../../../index.md#isthmus), [level
graph](../../../../index.md#level_graph), [local
searching](../../../../index.md#local_searching),
[loop](../../../../index.md#loop), [matching](../../../../index.md#matching),
[max cut](../../../../index.md#max_cut), [maximum
flow](../../../../index.md#maximum_flow), [minimal spanning
tree](../../../../index.md#minimal_spanning_tree), [minimum cost
flow](../../../../index.md#minimum_cost_flow), [minimum degree spanning
tree](../../../../index.md#minimum_degree_spanning_tree), [minimum diameter
spanning tree](../../../../index.md#minimum_diameter_spanning_tree),
[neighbour](../../../../index.md#neighbour), [node](../../../../index.md#node),
[radius](../../../../index.md#radius), [residual
graph](../../../../index.md#residual_graph), [shortest
path](../../../../index.md#shortest_path), [squared
graph](../../../../index.md#squared_graph), [strongly connected
component](../../../../index.md#strongly_connected_component),
[subgraph](../../../../index.md#subgraph), [travelling
salesman](../../../../index.md#travelling_salesman),
[vertex](../../../../index.md#vertex), [vertex
cover](../../../../index.md#vertex_cover)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Alejandro Paz <[email protected]>
Copyright © 2008 (docs) Andreas Kupries <[email protected]>
Copyright © 2009 Michal Antoniewski <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/matrix.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
|
[//000000001]: # (struct::matrix - Tcl Data Structures)
[//000000002]: # (Generated from file 'matrix.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::matrix(n) 2.0.3 tcllib "Tcl Data Structures")
# NAME
struct::matrix - Create and manipulate matrix objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::matrix ?2.0.3?
[__::struct::matrix__ ?*matrixName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1)
[__matrixName__ *option* ?*arg arg ...*?](#2)
[*matrixName* __=__ *sourcematrix*](#3)
[*matrixName* __-->__ *destmatrix*](#4)
[*matrixName* __add column__ ?*values*?](#5)
[*matrixName* __add row__ ?*values*?](#6)
[*matrixName* __add columns__ *n*](#7)
[*matrixName* __add rows__ *n*](#8)
[*matrixName* __cells__](#9)
[*matrixName* __cellsize__ *column row*](#10)
[*matrixName* __columns__](#11)
[*matrixName* __columnwidth__ *column*](#12)
[*matrixName* __delete column__ *column*](#13)
[*matrixName* __delete columns__ *n*](#14)
[*matrixName* __delete row__ *row*](#15)
[*matrixName* __delete rows__ *n*](#16)
[*matrixName* __deserialize__ *serialization*](#17)
[*matrixName* __destroy__](#18)
[*matrixName* __format 2string__ ?*report*?](#19)
[*matrixName* __format 2chan__ ??*report*? *channel*?](#20)
[*matrixName* __get cell__ *column row*](#21)
[*matrixName* __get column__ *column*](#22)
[*matrixName* __get rect__ *column_tl row_tl column_br row_br*](#23)
[*matrixName* __get row__ *row*](#24)
[*matrixName* __insert column__ *column* ?*values*?](#25)
[*matrixName* __insert row__ *row* ?*values*?](#26)
[*matrixName* __link__ ?-transpose? *arrayvar*](#27)
[*matrixName* __links__](#28)
[*matrixName* __rowheight__ *row*](#29)
[*matrixName* __rows__](#30)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern*](#31)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern*](#32)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern*](#33)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern*](#34)
[*matrixName* __serialize__ ?*column_tl row_tl column_br row_br*?](#35)
[*matrixName* __set cell__ *column row value*](#36)
[*matrixName* __set column__ *column values*](#37)
[*matrixName* __set rect__ *column row values*](#38)
[*matrixName* __set row__ *row values*](#39)
[*matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row*](#40)
[*matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column*](#41)
[*matrixName* __swap columns__ *column_a column_b*](#42)
[*matrixName* __swap rows__ *row_a row_b*](#43)
[*matrixName* __transpose__](#44)
[*matrixName* __unlink__ *arrayvar*](#45)
# <a name='description'></a>DESCRIPTION
A matrix is a rectangular collection of cells, i.e. organized in rows and
columns. Each cell contains exactly one value of arbitrary form. The cells in
the matrix are addressed by pairs of integer numbers, with the first (left)
number in the pair specifying the column and the second (right) number
specifying the row the cell is in. These indices are counted from 0 upward. The
special non-numeric index __end__ refers to the last row or column in the
matrix, depending on the context. Indices of the form __end__-__number__ are
counted from the end of the row or column, like they are for standard Tcl lists.
Trying to access non-existing cells causes an error.
The matrices here are created empty, i.e. they have neither rows nor columns.
The user then has to add rows and columns as needed by his application. A
specialty of this structure is the ability to export an array-view onto its
contents. Such can be used by tkTable, for example, to link the matrix into the
display.
The main command of the package is:
- <a name='1'></a>__::struct::matrix__ ?*matrixName*? ?__=__|__:=__|__as__|__deserialize__ *source*?
The command creates a new matrix object with an associated global Tcl
command whose name is *matrixName*. This command may be used to invoke
various operations on the matrix. It has the following general form:
* <a name='2'></a>__matrixName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
If *matrixName* is not specified a unique name will be generated by the
package itself. If a *source* is specified the new matrix will be
initialized to it. For the operators __=__, __:=__, and __as__ the argument
*source* is interpreted as the name of another matrix object, and the
assignment operator __=__ will be executed. For __deserialize__ the *source*
is a serialized matrix object and __deserialize__ will be executed.
In other words
::struct::matrix mymatrix = b
is equivalent to
::struct::matrix mymatrix
mymatrix = b
and
::struct::matrix mymatrix deserialize $b
is equivalent to
::struct::matrix mymatrix
mymatrix deserialize $b
The following commands are possible for matrix objects:
- <a name='3'></a>*matrixName* __=__ *sourcematrix*
This is the assignment operator for matrix objects. It copies the matrix
contained in the matrix object *sourcematrix* over the matrix data in
*matrixName*. The old contents of *matrixName* are deleted by this
operation.
This operation is in effect equivalent to
*matrixName* __deserialize__ [*sourcematrix* __serialize__]
- <a name='4'></a>*matrixName* __-->__ *destmatrix*
This is the reverse assignment operator for matrix objects. It copies the
matrix contained in the matrix object *matrixName* over the matrix data in
the object *destmatrix*. The old contents of *destmatrix* are deleted by
this operation.
This operation is in effect equivalent to
*destmatrix* __deserialize__ [*matrixName* __serialize__]
- <a name='5'></a>*matrixName* __add column__ ?*values*?
Extends the matrix by one column and then acts like __set column__ (see
below) on this new column if there were *values* supplied. Without *values*
the new cells will be set to the empty string. The new column is appended
immediately behind the last existing column.
- <a name='6'></a>*matrixName* __add row__ ?*values*?
Extends the matrix by one row and then acts like __set row__ (see below) on
this new row if there were *values* supplied. Without *values* the new cells
will be set to the empty string. The new row is appended immediately behind
the last existing row.
- <a name='7'></a>*matrixName* __add columns__ *n*
Extends the matrix by *n* columns. The new cells will be set to the empty
string. The new columns are appended immediately behind the last existing
column. A value of *n* equal to or smaller than 0 is not allowed.
- <a name='8'></a>*matrixName* __add rows__ *n*
Extends the matrix by *n* rows. The new cells will be set to the empty
string. The new rows are appended immediately behind the last existing row.
A value of *n* equal to or smaller than 0 is not allowed.
- <a name='9'></a>*matrixName* __cells__
Returns the number of cells currently managed by the matrix. This is the
product of __rows__ and __columns__.
- <a name='10'></a>*matrixName* __cellsize__ *column row*
Returns the length of the string representation of the value currently
contained in the addressed cell.
- <a name='11'></a>*matrixName* __columns__
Returns the number of columns currently managed by the matrix.
- <a name='12'></a>*matrixName* __columnwidth__ *column*
Returns the length of the longest string representation of all the values
currently contained in the cells of the addressed column if these are all
spanning only one line. For cell values spanning multiple lines the length
of their longest line goes into the computation.
*Note:* The command recognizes ANSI color control sequences and excludes
them from the width of a line, as they are logically of zero width.
- <a name='13'></a>*matrixName* __delete column__ *column*
Deletes the specified column from the matrix and shifts all columns with
higher indices one index down.
- <a name='14'></a>*matrixName* __delete columns__ *n*
Deletes *n* columns from the right of the matrix. The value of *n* has to
satisfy the constraint "0 < *n* < [__matrixName__ __columns__]"
- <a name='15'></a>*matrixName* __delete row__ *row*
Deletes the specified row from the matrix and shifts all row with higher
indices one index down.
- <a name='16'></a>*matrixName* __delete rows__ *n*
Deletes *n* rows from the bottom of the matrix. The value of *n* has to
satisfy the constraint "0 < *n* < [__matrixName__ __rows__]"
- <a name='17'></a>*matrixName* __deserialize__ *serialization*
This is the complement to __serialize__. It replaces matrix data in
*matrixName* with the matrix described by the *serialization* value. The old
contents of *matrixName* are deleted by this operation.
- <a name='18'></a>*matrixName* __destroy__
Destroys the matrix, including its storage space and associated command.
- <a name='19'></a>*matrixName* __format 2string__ ?*report*?
Formats the matrix using the specified report object and returns the string
containing the result of this operation. The report has to support the
__printmatrix__ method. If no *report* is specified the system will use an
internal report definition to format the matrix.
- <a name='20'></a>*matrixName* __format 2chan__ ??*report*? *channel*?
Formats the matrix using the specified report object and writes the string
containing the result of this operation into the channel. The report has to
support the __printmatrix2channel__ method. If no *report* is specified the
system will use an internal report definition to format the matrix. If no
*channel* is specified the system will use __stdout__.
- <a name='21'></a>*matrixName* __get cell__ *column row*
Returns the value currently contained in the cell identified by row and
column index.
- <a name='22'></a>*matrixName* __get column__ *column*
Returns a list containing the values from all cells in the column identified
by the index. The contents of the cell in row 0 are stored as the first
element of this list.
- <a name='23'></a>*matrixName* __get rect__ *column_tl row_tl column_br row_br*
Returns a list of lists of cell values. The values stored in the result come
from the sub-matrix whose top-left and bottom-right cells are specified by
*column_tl, row_tl* and *column_br, row_br* resp. Note that the following
equations have to be true: "*column_tl* <= *column_br*" and "*row_tl* <=
*row_br*". The result is organized as follows: The outer list is the list of
rows, its elements are lists representing a single row. The row with the
smallest index is the first element of the outer list. The elements of the
row lists represent the selected cell values. The cell with the smallest
index is the first element in each row list.
- <a name='24'></a>*matrixName* __get row__ *row*
Returns a list containing the values from all cells in the row identified by
the index. The contents of the cell in column 0 are stored as the first
element of this list.
- <a name='25'></a>*matrixName* __insert column__ *column* ?*values*?
Extends the matrix by one column and then acts like __set column__ (see
below) on this new column if there were *values* supplied. Without *values*
the new cells will be set to the empty string. The new column is inserted
just before the column specified by the given index. This means, if *column*
is less than or equal to zero, then the new column is inserted at the
beginning of the matrix, before the first column. If *column* has the value
__end__, or if it is greater than or equal to the number of columns in the
matrix, then the new column is appended to the matrix, behind the last
column. The old column at the chosen index and all columns with higher
indices are shifted one index upward.
- <a name='26'></a>*matrixName* __insert row__ *row* ?*values*?
Extends the matrix by one row and then acts like __set row__ (see below) on
this new row if there were *values* supplied. Without *values* the new cells
will be set to the empty string. The new row is inserted just before the row
specified by the given index. This means, if *row* is less than or equal to
zero, then the new row is inserted at the beginning of the matrix, before
the first row. If *row* has the value __end__, or if it is greater than or
equal to the number of rows in the matrix, then the new row is appended to
the matrix, behind the last row. The old row at that index and all rows with
higher indices are shifted one index upward.
- <a name='27'></a>*matrixName* __link__ ?-transpose? *arrayvar*
Links the matrix to the specified array variable. This means that the
contents of all cells in the matrix is stored in the array too, with all
changes to the matrix propagated there too. The contents of the cell
*(column,row)* is stored in the array using the key *column,row*. If the
option __-transpose__ is specified the key *row,column* will be used
instead. It is possible to link the matrix to more than one array. Note that
the link is bidirectional, i.e. changes to the array are mirrored in the
matrix too.
- <a name='28'></a>*matrixName* __links__
Returns a list containing the names of all array variables the matrix was
linked to through a call to method __link__.
- <a name='29'></a>*matrixName* __rowheight__ *row*
Returns the height of the specified row in lines. This is the highest number
of lines spanned by a cell over all cells in the row.
- <a name='30'></a>*matrixName* __rows__
Returns the number of rows currently managed by the matrix.
- <a name='31'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern*
Searches the whole matrix for cells matching the *pattern* and returns a
list with all matches. Each item in the aforementioned list is a list itself
and contains the column and row index of the matching cell, in this order.
The results are ordered by column first and row second, both times in
ascending order. This means that matches to the left and the top of the
matrix come before matches to the right and down.
The type of the pattern (string, glob, regular expression) is determined by
the option after the __search__ keyword. If no option is given it defaults
to __-exact__.
If the option __-nocase__ is specified the search will be case-insensitive.
- <a name='32'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern*
Like __search all__, but the search is restricted to the specified column.
- <a name='33'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern*
Like __search all__, but the search is restricted to the specified row.
- <a name='34'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern*
Like __search all__, but the search is restricted to the specified
rectangular area of the matrix.
- <a name='35'></a>*matrixName* __serialize__ ?*column_tl row_tl column_br row_br*?
This method serializes the sub-matrix spanned up by the rectangle
specification. In other words it returns a tcl *value* completely describing
that matrix. If no rectangle is specified the whole matrix will be
serialized. This allows, for example, the transfer of matrix objects (or
parts thereof) over arbitrary channels, persistence, etc. This method is
also the basis for both the copy constructor and the assignment operator.
The result of this method has to be semantically identical over all
implementations of the matrix interface. This is what will enable us to copy
matrix data between different implementations of the same interface.
The result is a list containing exactly three items.
The first two elements of the list specify the number of rows and columns of
the matrix, in that order. The values integer numbers greater than or equal
to zero.
The last element of the list contains the values of the matrix cells we have
serialized, in the form of a value like it is returned by the __get rect__.
However empty cells to the right and bottom of the matrix can be left out of
that value as the size information in the serialization allows the receiver
the creation of a matrix with the proper size despite the missing values.
# A possible serialization for the matrix structure
#
# | a b d g |
# | c e |
# | f |
#
# is
#
# 3 4 {{a b d g} {c e} {f}}
- <a name='36'></a>*matrixName* __set cell__ *column row value*
Sets the value in the cell identified by row and column index to the data in
the third argument.
- <a name='37'></a>*matrixName* __set column__ *column values*
Sets the values in the cells identified by the column index to the elements
of the list provided as the third argument. Each element of the list is
assigned to one cell, with the first element going into the cell in row 0
and then upward. If there are less values in the list than there are rows
the remaining rows are set to the empty string. If there are more values in
the list than there are rows the superfluous elements are ignored. The
matrix is not extended by this operation.
- <a name='38'></a>*matrixName* __set rect__ *column row values*
Takes a list of lists of cell values and writes them into the submatrix
whose top-left cell is specified by the two indices. If the sublists of the
outerlist are not of equal length the shorter sublists will be filled with
empty strings to the length of the longest sublist. If the submatrix
specified by the top-left cell and the number of rows and columns in the
*values* extends beyond the matrix we are modifying the over-extending parts
of the values are ignored, i.e. essentially cut off. This subcommand expects
its input in the format as returned by __get rect__.
- <a name='39'></a>*matrixName* __set row__ *row values*
Sets the values in the cells identified by the row index to the elements of
the list provided as the third argument. Each element of the list is
assigned to one cell, with the first element going into the cell in column 0
and then upward. If there are less values in the list than there are columns
the remaining columns are set to the empty string. If there are more values
in the list than there are columns the superfluous elements are ignored. The
matrix is not extended by this operation.
- <a name='40'></a>*matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row*
Sorts the columns in the matrix using the data in the specified *row* as the
key to sort by. The options __-increasing__ and __-decreasing__ have the
same meaning as for __lsort__. If no option is specified __-increasing__ is
assumed.
- <a name='41'></a>*matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column*
Sorts the rows in the matrix using the data in the specified *column* as the
key to sort by. The options __-increasing__ and __-decreasing__ have the
same meaning as for __lsort__. If no option is specified __-increasing__ is
assumed.
- <a name='42'></a>*matrixName* __swap columns__ *column_a column_b*
Swaps the contents of the two specified columns.
- <a name='43'></a>*matrixName* __swap rows__ *row_a row_b*
Swaps the contents of the two specified rows.
- <a name='44'></a>*matrixName* __transpose__
Transposes the contents of the matrix, i.e. swaps rows for columns and vice
versa.
- <a name='45'></a>*matrixName* __unlink__ *arrayvar*
Removes the link between the matrix and the specified arrayvariable, if
there is one.
# <a name='section2'></a>EXAMPLES
The examples below assume a 5x5 matrix M with the first row containing the
values 1 to 5, with 1 in the top-left cell. Each other row contains the contents
of the row above it, rotated by one cell to the right.
% M get rect 0 0 4 4
{{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
% M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M get rect 0 0 4 4
{{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
Assuming that the style definitions in the example section of the manpage for
the package __[report](../report/report.md)__ are loaded into the interpreter
now an example which formats a matrix into a tabular report. The code filling
the matrix with data is not shown. contains useful data.
% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% m format 2string r
+---+-------------------+-------+-------+--------+
|000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok |7 |13 |53.85 |
|002|CATCH return error |68 |91 |74.73 |
|003|CATCH no catch used|7 |14 |50.00 |
|004|IF if true numeric |12 |33 |36.36 |
|005|IF elseif |15 |47 |31.91 |
| |true numeric | | | |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% r printmatrix m
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: matrix* 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.
# <a name='keywords'></a>KEYWORDS
[matrix](../../../../index.md#matrix)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002-2013 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/matrix1.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
|
[//000000001]: # (struct::matrix_v1 - Tcl Data Structures)
[//000000002]: # (Generated from file 'matrix1.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::matrix_v1(n) 1.2.1 tcllib "Tcl Data Structures")
# NAME
struct::matrix_v1 - Create and manipulate matrix objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::matrix ?1.2.1?
[__matrixName__ *option* ?*arg arg ...*?](#1)
[*matrixName* __add column__ ?*values*?](#2)
[*matrixName* __add row__ ?*values*?](#3)
[*matrixName* __add columns__ *n*](#4)
[*matrixName* __add rows__ *n*](#5)
[*matrixName* __cells__](#6)
[*matrixName* __cellsize__ *column row*](#7)
[*matrixName* __columns__](#8)
[*matrixName* __columnwidth__ *column*](#9)
[*matrixName* __delete column__ *column*](#10)
[*matrixName* __delete row__ *row*](#11)
[*matrixName* __destroy__](#12)
[*matrixName* __format 2string__ ?*report*?](#13)
[*matrixName* __format 2chan__ ??*report*? *channel*?](#14)
[*matrixName* __get cell__ *column row*](#15)
[*matrixName* __get column__ *column*](#16)
[*matrixName* __get rect__ *column_tl row_tl column_br row_br*](#17)
[*matrixName* __get row__ *row*](#18)
[*matrixName* __insert column__ *column* ?*values*?](#19)
[*matrixName* __insert row__ *row* ?*values*?](#20)
[*matrixName* __link__ ?-transpose? *arrayvar*](#21)
[*matrixName* __links__](#22)
[*matrixName* __rowheight__ *row*](#23)
[*matrixName* __rows__](#24)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern*](#25)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern*](#26)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern*](#27)
[*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern*](#28)
[*matrixName* __set cell__ *column row value*](#29)
[*matrixName* __set column__ *column values*](#30)
[*matrixName* __set rect__ *column row values*](#31)
[*matrixName* __set row__ *row values*](#32)
[*matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row*](#33)
[*matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column*](#34)
[*matrixName* __swap columns__ *column_a column_b*](#35)
[*matrixName* __swap rows__ *row_a row_b*](#36)
[*matrixName* __unlink__ *arrayvar*](#37)
# <a name='description'></a>DESCRIPTION
The __::struct::matrix__ command creates a new matrix object with an associated
global Tcl command whose name is *matrixName*. This command may be used to
invoke various operations on the matrix. It has the following general form:
- <a name='1'></a>__matrixName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
A matrix is a rectangular collection of cells, i.e. organized in rows and
columns. Each cell contains exactly one value of arbitrary form. The cells in
the matrix are addressed by pairs of integer numbers, with the first (left)
number in the pair specifying the column and the second (right) number
specifying the row the cell is in. These indices are counted from 0 upward. The
special non-numeric index __end__ refers to the last row or column in the
matrix, depending on the context. Indices of the form __end__-__number__ are
counted from the end of the row or column, like they are for standard Tcl lists.
Trying to access non-existing cells causes an error.
The matrices here are created empty, i.e. they have neither rows nor columns.
The user then has to add rows and columns as needed by his application. A
specialty of this structure is the ability to export an array-view onto its
contents. Such can be used by tkTable, for example, to link the matrix into the
display.
The following commands are possible for matrix objects:
- <a name='2'></a>*matrixName* __add column__ ?*values*?
Extends the matrix by one column and then acts like __setcolumn__ (see
below) on this new column if there were *values* supplied. Without *values*
the new cells will be set to the empty string. The new column is appended
immediately behind the last existing column.
- <a name='3'></a>*matrixName* __add row__ ?*values*?
Extends the matrix by one row and then acts like __setrow__ (see below) on
this new row if there were *values* supplied. Without *values* the new cells
will be set to the empty string. The new row is appended immediately behind
the last existing row.
- <a name='4'></a>*matrixName* __add columns__ *n*
Extends the matrix by *n* columns. The new cells will be set to the empty
string. The new columns are appended immediately behind the last existing
column. A value of *n* equal to or smaller than 0 is not allowed.
- <a name='5'></a>*matrixName* __add rows__ *n*
Extends the matrix by *n* rows. The new cells will be set to the empty
string. The new rows are appended immediately behind the last existing row.
A value of *n* equal to or smaller than 0 is not allowed.
- <a name='6'></a>*matrixName* __cells__
Returns the number of cells currently managed by the matrix. This is the
product of __rows__ and __columns__.
- <a name='7'></a>*matrixName* __cellsize__ *column row*
Returns the length of the string representation of the value currently
contained in the addressed cell.
- <a name='8'></a>*matrixName* __columns__
Returns the number of columns currently managed by the matrix.
- <a name='9'></a>*matrixName* __columnwidth__ *column*
Returns the length of the longest string representation of all the values
currently contained in the cells of the addressed column if these are all
spanning only one line. For cell values spanning multiple lines the length
of their longest line goes into the computation.
- <a name='10'></a>*matrixName* __delete column__ *column*
Deletes the specified column from the matrix and shifts all columns with
higher indices one index down.
- <a name='11'></a>*matrixName* __delete row__ *row*
Deletes the specified row from the matrix and shifts all row with higher
indices one index down.
- <a name='12'></a>*matrixName* __destroy__
Destroys the matrix, including its storage space and associated command.
- <a name='13'></a>*matrixName* __format 2string__ ?*report*?
Formats the matrix using the specified report object and returns the string
containing the result of this operation. The report has to support the
__printmatrix__ method. If no *report* is specified the system will use an
internal report definition to format the matrix.
- <a name='14'></a>*matrixName* __format 2chan__ ??*report*? *channel*?
Formats the matrix using the specified report object and writes the string
containing the result of this operation into the channel. The report has to
support the __printmatrix2channel__ method. If no *report* is specified the
system will use an internal report definition to format the matrix. If no
*channel* is specified the system will use __stdout__.
- <a name='15'></a>*matrixName* __get cell__ *column row*
Returns the value currently contained in the cell identified by row and
column index.
- <a name='16'></a>*matrixName* __get column__ *column*
Returns a list containing the values from all cells in the column identified
by the index. The contents of the cell in row 0 are stored as the first
element of this list.
- <a name='17'></a>*matrixName* __get rect__ *column_tl row_tl column_br row_br*
Returns a list of lists of cell values. The values stored in the result come
from the sub-matrix whose top-left and bottom-right cells are specified by
*column_tl, row_tl* and *column_br, row_br* resp. Note that the following
equations have to be true: "*column_tl* <= *column_br*" and "*row_tl* <=
*row_br*". The result is organized as follows: The outer list is the list of
rows, its elements are lists representing a single row. The row with the
smallest index is the first element of the outer list. The elements of the
row lists represent the selected cell values. The cell with the smallest
index is the first element in each row list.
- <a name='18'></a>*matrixName* __get row__ *row*
Returns a list containing the values from all cells in the row identified by
the index. The contents of the cell in column 0 are stored as the first
element of this list.
- <a name='19'></a>*matrixName* __insert column__ *column* ?*values*?
Extends the matrix by one column and then acts like __setcolumn__ (see
below) on this new column if there were *values* supplied. Without *values*
the new cells will be set to the empty string. The new column is inserted
just before the column specified by the given index. This means, if *column*
is less than or equal to zero, then the new column is inserted at the
beginning of the matrix, before the first column. If *column* has the value
__end__, or if it is greater than or equal to the number of columns in the
matrix, then the new column is appended to the matrix, behind the last
column. The old column at the chosen index and all columns with higher
indices are shifted one index upward.
- <a name='20'></a>*matrixName* __insert row__ *row* ?*values*?
Extends the matrix by one row and then acts like __setrow__ (see below) on
this new row if there were *values* supplied. Without *values* the new cells
will be set to the empty string. The new row is inserted just before the row
specified by the given index. This means, if *row* is less than or equal to
zero, then the new row is inserted at the beginning of the matrix, before
the first row. If *row* has the value __end__, or if it is greater than or
equal to the number of rows in the matrix, then the new row is appended to
the matrix, behind the last row. The old row at that index and all rows with
higher indices are shifted one index upward.
- <a name='21'></a>*matrixName* __link__ ?-transpose? *arrayvar*
Links the matrix to the specified array variable. This means that the
contents of all cells in the matrix is stored in the array too, with all
changes to the matrix propagated there too. The contents of the cell
*(column,row)* is stored in the array using the key *column,row*. If the
option __-transpose__ is specified the key *row,column* will be used
instead. It is possible to link the matrix to more than one array. Note that
the link is bidirectional, i.e. changes to the array are mirrored in the
matrix too.
- <a name='22'></a>*matrixName* __links__
Returns a list containing the names of all array variables the matrix was
linked to through a call to method __link__.
- <a name='23'></a>*matrixName* __rowheight__ *row*
Returns the height of the specified row in lines. This is the highest number
of lines spanned by a cell over all cells in the row.
- <a name='24'></a>*matrixName* __rows__
Returns the number of rows currently managed by the matrix.
- <a name='25'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __all__ *pattern*
Searches the whole matrix for cells matching the *pattern* and returns a
list with all matches. Each item in the aforementioned list is a list itself
and contains the column and row index of the matching cell, in this order.
The results are ordered by column first and row second, both times in
ascending order. This means that matches to the left and the top of the
matrix come before matches to the right and down.
The type of the pattern (string, glob, regular expression) is determined by
the option after the __search__ keyword. If no option is given it defaults
to __-exact__.
If the option __-nocase__ is specified the search will be case-insensitive.
- <a name='26'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __column__ *column pattern*
Like __search all__, but the search is restricted to the specified column.
- <a name='27'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __row__ *row pattern*
Like __search all__, but the search is restricted to the specified row.
- <a name='28'></a>*matrixName* __search__ ?-nocase? ?-exact|-glob|-regexp? __rect__ *column_tl row_tl column_br row_br pattern*
Like __search all__, but the search is restricted to the specified
rectangular area of the matrix.
- <a name='29'></a>*matrixName* __set cell__ *column row value*
Sets the value in the cell identified by row and column index to the data in
the third argument.
- <a name='30'></a>*matrixName* __set column__ *column values*
Sets the values in the cells identified by the column index to the elements
of the list provided as the third argument. Each element of the list is
assigned to one cell, with the first element going into the cell in row 0
and then upward. If there are less values in the list than there are rows
the remaining rows are set to the empty string. If there are more values in
the list than there are rows the superfluous elements are ignored. The
matrix is not extended by this operation.
- <a name='31'></a>*matrixName* __set rect__ *column row values*
Takes a list of lists of cell values and writes them into the submatrix
whose top-left cell is specified by the two indices. If the sublists of the
outerlist are not of equal length the shorter sublists will be filled with
empty strings to the length of the longest sublist. If the submatrix
specified by the top-left cell and the number of rows and columns in the
*values* extends beyond the matrix we are modifying the over-extending parts
of the values are ignored, i.e. essentially cut off. This subcommand expects
its input in the format as returned by __getrect__.
- <a name='32'></a>*matrixName* __set row__ *row values*
Sets the values in the cells identified by the row index to the elements of
the list provided as the third argument. Each element of the list is
assigned to one cell, with the first element going into the cell in column 0
and then upward. If there are less values in the list than there are columns
the remaining columns are set to the empty string. If there are more values
in the list than there are columns the superfluous elements are ignored. The
matrix is not extended by this operation.
- <a name='33'></a>*matrixName* __sort columns__ ?__-increasing__|__-decreasing__? *row*
Sorts the columns in the matrix using the data in the specified *row* as the
key to sort by. The options __-increasing__ and __-decreasing__ have the
same meaning as for __lsort__. If no option is specified __-increasing__ is
assumed.
- <a name='34'></a>*matrixName* __sort rows__ ?__-increasing__|__-decreasing__? *column*
Sorts the rows in the matrix using the data in the specified *column* as the
key to sort by. The options __-increasing__ and __-decreasing__ have the
same meaning as for __lsort__. If no option is specified __-increasing__ is
assumed.
- <a name='35'></a>*matrixName* __swap columns__ *column_a column_b*
Swaps the contents of the two specified columns.
- <a name='36'></a>*matrixName* __swap rows__ *row_a row_b*
Swaps the contents of the two specified rows.
- <a name='37'></a>*matrixName* __unlink__ *arrayvar*
Removes the link between the matrix and the specified arrayvariable, if
there is one.
# <a name='section2'></a>EXAMPLES
The examples below assume a 5x5 matrix M with the first row containing the
values 1 to 5, with 1 in the top-left cell. Each other row contains the contents
of the row above it, rotated by one cell to the right.
% M getrect 0 0 4 4
{{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
% M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M getrect 0 0 4 4
{{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
Assuming that the style definitions in the example section of the manpage for
the package __[report](../report/report.md)__ are loaded into the interpreter
now an example which formats a matrix into a tabular report. The code filling
the matrix with data is not shown. contains useful data.
% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% m format 2string r
+---+-------------------+-------+-------+--------+
|000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok |7 |13 |53.85 |
|002|CATCH return error |68 |91 |74.73 |
|003|CATCH no catch used|7 |14 |50.00 |
|004|IF if true numeric |12 |33 |36.36 |
|005|IF elseif |15 |47 |31.91 |
| |true numeric | | | |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% r printmatrix m
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: matrix* 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.
# <a name='keywords'></a>KEYWORDS
[matrix](../../../../index.md#matrix)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/pool.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
|
[//000000001]: # (struct::pool - Tcl Data Structures)
[//000000002]: # (Generated from file 'pool.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::pool(n) 1.2.3 tcllib "Tcl Data Structures")
# NAME
struct::pool - Create and manipulate pool objects (of discrete items)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [POOLS AND ALLOCATION](#section2)
- [ITEMS](#section3)
- [POOL OBJECT COMMAND](#section4)
- [EXAMPLES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::pool ?1.2.3?
[__::struct::pool__ ?*poolName*? ?*maxsize*?](#1)
[__poolName__ *option* ?*arg arg ...*?](#2)
[*poolName* __add__ *itemName1* ?*itemName2 itemName3 ...*?](#3)
[*poolName* __clear__ ?__-force__?](#4)
[*poolName* __destroy__ ?__-force__?](#5)
[*poolName* __info__ *type* ?*arg*?](#6)
[*poolName* __maxsize__ ?*maxsize*?](#7)
[*poolName* __release__ *itemName*](#8)
[*poolName* __remove__ *itemName* ?__-force__?](#9)
[*poolName* __request__ itemVar ?options?](#10)
# <a name='description'></a>DESCRIPTION
This package provides pool objects which can be used to manage finite
collections of discrete items.
- <a name='1'></a>__::struct::pool__ ?*poolName*? ?*maxsize*?
Creates a new pool object. If no *poolName* is supplied, then the new pool
will be named pool__X__, where X is a positive integer. The optional second
argument *maxsize* has to be a positive integer indicating the maximum size
of the pool; this is the maximum number of items the pool may hold. The
default for this value is __10__.
The pool object has an associated global Tcl command whose name is
*poolName*. This command may be used to invoke various configuration
operations on the report. It has the following general form:
* <a name='2'></a>__poolName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. See
section [POOL OBJECT COMMAND](#section4) for a detailed list of options
and their behaviour.
# <a name='section2'></a>POOLS AND ALLOCATION
The purpose of the pool command and the pool object command that it generates,
is to manage pools of discrete items. Examples of a pool of discrete items are:
- the seats in a cinema, theatre, train etc.. for which visitors/travelers can
make a reservation;
- the dynamic IP-addresses that an ISP can dole out to subscribers;
- a car rental's collection of cars, which can be rented by customers;
- the class rooms in a school building, which need to be scheduled;
- the database connections available to client-threads in a web-server
application;
- the books in a library that customers can borrow;
- etc ...
The common denominator in the examples is that there is a more or less fixed
number of items (seats, IP-addresses, cars, ...) that are supposed to be
allocated on a more or less regular basis. An item can be allocated only once at
a time. An item that is allocated, must be released before it can be
re-allocated. While several items in a pool are being allocated and released
continuously, the total number of items in the pool remains constant.
Keeping track of which items are allocated, and by whom, is the purpose of the
pool command and its subordinates.
*Pool parlance*: If we say that an item is *allocated*, it means that the item
is *busy*, *owned* or *occupied*; it is not available anymore. If an item is
*free*, it is *available*. Deallocating an item is equivalent to setting free or
releasing an item. The person or entity to which the item has been allotted is
said to own the item.
# <a name='section3'></a>ITEMS
*Discrete items*
The __[pool](../../../../index.md#pool)__ command is designed for *discrete
items only*. Note that there are pools where allocation occurs on a non-discrete
basis, for example computer memory. There are also pools from which the shares
that are doled out are not expected to be returned, for example a charity fund
or a pan of soup from which you may receive a portion. Finally, there are even
pools from which nothing is ever allocated or returned, like a swimming pool or
a cesspool.
*Unique item names*
A pool cannot manage duplicate item names. Therefore, items in a pool must have
unique names.
*Item equivalence*
From the point of view of the manager of a pool, items are equivalent. The
manager of a pool is indifferent about which entity/person occupies a given
item. However, clients may have preferences for a particular item, based on some
item property they know.
*Preferences*
A future owner may have a preference for a particular item. Preference based
allocation is supported (see the __-prefer__ option to the request subcommand).
A preference for a particular item is most likely to result from variability
among features associated with the items. Note that the pool commands themselves
are not designed to manage such item properties. If item properties play a role
in an application, they should be managed separately.
# <a name='section4'></a>POOL OBJECT COMMAND
The following subcommands and corresponding arguments are available to any pool
object command.
- <a name='3'></a>*poolName* __add__ *itemName1* ?*itemName2 itemName3 ...*?
This command adds the items on the command line to the pool. If duplicate
item names occur on the command line, an error is raised. If one or more of
the items already exist in the pool, this also is considered an error.
- <a name='4'></a>*poolName* __clear__ ?__-force__?
Removes all items from the pool. If there are any allocated items at the
time when the command is invoked, an error is raised. This behaviour may be
modified through the __-force__ argument. If it is supplied on the command
line, the pool will be cleared regardless the allocation state of its items.
- <a name='5'></a>*poolName* __destroy__ ?__-force__?
Destroys the pool data structure, all associated variables and the
associated pool object command. By default, the command checks whether any
items are still allocated and raises an error if such is the case. This
behaviour may be modified through the argument __-force__. If it is supplied
on the command line, the pool data structure will be destroyed regardless
allocation state of its items.
- <a name='6'></a>*poolName* __info__ *type* ?*arg*?
Returns various information about the pool for further programmatic use. The
*type* argument indicates the type of information requested. Only the type
__allocID__ uses an additional argument.
* __allocID__ *itemName*
returns the allocID of the item whose name is *itemName*. Free items
have an allocation id of __-1__.
* __allitems__
returns a list of all items in the pool.
* __allocstate__
Returns a list of key-value pairs, where the keys are the items and the
values are the corresponding allocation id's. Free items have an
allocation id of __-1__.
* __cursize__
returns the current pool size, i.e. the number of items in the pool.
* __freeitems__
returns a list of items that currently are not allocated.
* __maxsize__
returns the maximum size of the pool.
- <a name='7'></a>*poolName* __maxsize__ ?*maxsize*?
Sets or queries the maximum size of the pool, depending on whether the
*maxsize* argument is supplied or not. If *maxsize* is supplied, the maximum
size of the pool will be set to that value. If no argument is supplied, the
current maximum size of the pool is returned. In this variant, the command
is an alias for:
__poolName info maxsize__.
The *maxsize* argument has to be a positive integer.
- <a name='8'></a>*poolName* __release__ *itemName*
Releases the item whose name is *itemName* that was allocated previously. An
error is raised if the item was not allocated at the time when the command
was issued.
- <a name='9'></a>*poolName* __remove__ *itemName* ?__-force__?
Removes the item whose name is *itemName* from the pool. If the item was
allocated at the time when the command was invoked, an error is raised. This
behaviour may be modified through the optional argument __-force__. If it is
supplied on the command line, the item will be removed regardless its
allocation state.
- <a name='10'></a>*poolName* __request__ itemVar ?options?
Handles a request for an item, taking into account a possible preference for
a particular item. There are two possible outcomes depending on the
availability of items:
The request is honoured, an item is allocated and the variable whose name is
passed with the argument *itemVar* will be set to the name of the item that
was allocated. The command returns 1.
The request is denied. No item is allocated. The variable whose name is
itemVar is not set. Attempts to read *itemVar* may raise an error if the
variable was not defined before issuing the request. The command returns 0.
The return values from this command are meant to be inspected. The examples
below show how to do this. Failure to check the return value may result in
erroneous behaviour. If no preference for a particular item is supplied
through the option __-prefer__ (see below), then all requests are honoured
as long as items are available.
The following options are supported:
* __-allocID__ *allocID*
If the request is honoured, an item will be allocated to the entity
identified by allocID. If the allocation state of an item is queried, it
is this allocation ID that will be returned. If the option __-allocID__
is not supplied, the item will be given to and owned by __dummyID__.
Allocation id's may be anything except the value -1, which is reserved
for free items.
* __-prefer__ *preferredItem*
This option modifies the allocation strategy as follows: If the item
whose name is *preferredItem* is not allocated at the time when the
command is invoked, the request is honoured (return value is 1). If the
item was allocated at the time when the command was invoked, the request
is denied (return value is 0).
# <a name='section5'></a>EXAMPLES
Two examples are provided. The first one mimics a step by step interactive tclsh
session, where each step is explained. The second example shows the usage in a
server application that talks to a back-end application.
*Example 1*
This example presents an interactive tclsh session which considers the case of a
Car rental's collection of cars. Ten steps explain its usage in chronological
order, from the creation of the pool, via the most important stages in the usage
of a pool, to the final destruction.
*Note aside:*
In this example, brand names are used to label the various items. However, a
brand name could be regarded as a property of an item. Because the pool command
is not designed to manage properties of items, they need to be managed
separately. In the latter case the items should be labeled with more neutral
names such as: car1, car2, car3 , etc ... and a separate database or array
should hold the brand names associated with the car labels.
1. Load the package into an interpreter
% package require pool
0.1
2. Create a pool object called `CarPool' with a maximum size of 55 items (cars):
% pool CarPool 55
CarPool
4. Add items to the pool:
% CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen
5. Somebody crashed the Toyota. Remove it from the pool as follows:
% CarPool remove Toyota
6. Acquired a new car for the pool. Add it as follows:
% CarPool add Nissan
7. Check whether the pool was adjusted correctly:
% CarPool info allitems
Trabant Chrysler1 Chrysler2 Volkswagen Nissan
Suspend the interactive session temporarily, and show the programmatic use of
the request subcommand:
# Mrs. Swift needs a car. She doesn't have a preference for a
# particular car. We'll issue a request on her behalf as follows:
if { [CarPool request car -allocID "Mrs. Swift"] } {
# request was honoured, process the variable `car'
puts "$car has been allocated to [CarPool info allocID $car]."
} else {
# request was denied
puts "No car available."
}
Note how the __if__ command uses the value returned by the __request__
subcommand.
# Suppose Mr. Wiggly has a preference for the Trabant:
if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] } {
# request was honoured, process the variable `car'
puts "$car has been allocated to [CarPool info allocID $car]."
} else {
# request was denied
puts "The Trabant was not available."
}
Resume the interactive session:
8. When the car is returned then you can render it available by:
% CarPool release Trabant
9. When done, you delete the pool.
% CarPool destroy
Couldn't destroy `CarPool' because some items are still allocated.
Oops, forgot that Mrs. Swift still occupies a car.
10. We force the destruction of the pool as follows:
% CarPool destroy -force
*Example 2*
This example describes the case from which the author's need for pool management
originated. It is an example of a server application that receives requests from
client applications. The client requests are dispatched onto a back-end
application before being returned to the client application. In many cases there
are a few equivalent instances of back-end applications to which a client
request may be passed along. The file descriptors that identify the channels to
these back-end instances make up a pool of connections. A particular connection
may be allocated to just one client request at a time.
# Create the pool of connections (pipes)
set maxpipes 10
pool Pipes $maxpipes
for {set i 0} {$i < $maxpipes} {incr i} {
set fd [open "|backendApplication" w+]
Pipes add $fd
}
# A client request comes in. The request is identified as `clientX'.
# Dispatch it onto an instance of a back-end application
if { [Pipes request fd -allocID clientX] } {
# a connection was allocated
# communicate to the back-end application via the variable `fd'
puts $fd "someInstruction"
# ...... etc.
} else {
# all connections are currently occupied
# store the client request in a queue for later processing,
# or return a 'Server busy' message to the client.
}
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: pool* 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.
# <a name='keywords'></a>KEYWORDS
[discrete items](../../../../index.md#discrete_items),
[finite](../../../../index.md#finite), [pool](../../../../index.md#pool),
[struct](../../../../index.md#struct)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Erik Leunissen <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/prioqueue.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
[//000000001]: # (struct::prioqueue - Tcl Data Structures)
[//000000002]: # (Generated from file 'prioqueue.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::prioqueue(n) 1.4 tcllib "Tcl Data Structures")
# NAME
struct::prioqueue - Create and manipulate prioqueue objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::prioqueue ?1.4?
[__::struct::prioqueue__ ?__-ascii|-dictionary|-integer|-real__? ?*prioqueueName*?](#1)
[*prioqueueName* __option__ ?*arg arg ...*?](#2)
[*prioqueueName* __clear__](#3)
[*prioqueueName* __[remove](../../../../index.md#remove)__ *item*](#4)
[*prioqueueName* __destroy__](#5)
[*prioqueueName* __get__ ?*count*?](#6)
[*prioqueueName* __peek__ ?*count*?](#7)
[*prioqueueName* __peekpriority__ ?*count*?](#8)
[*prioqueueName* __put__ *item prio* ?*item prio ...*?](#9)
[*prioqueueName* __size__](#10)
# <a name='description'></a>DESCRIPTION
This package implements a simple priority queue using nested tcl lists.
The command __::struct::prioqueue__ creates a new priority queue with default
priority key type *-integer*. This means that keys given to the __put__
subcommand must have this type.
This also sets the priority ordering. For key types *-ascii* and *-dictionary*
the data is sorted in ascending order (as with __lsort__ *-increasing*), thereas
for *-integer* and *-real* the data is sorted in descending order (as with
__lsort__ *-decreasing*).
Prioqueue names are unrestricted, but may be recognized as options if no
priority type is given.
- <a name='1'></a>__::struct::prioqueue__ ?__-ascii|-dictionary|-integer|-real__? ?*prioqueueName*?
The __::struct::prioqueue__ command creates a new prioqueue object with an
associated global Tcl command whose name is *prioqueueName*. This command
may be used to invoke various operations on the prioqueue. It has the
following general form:
- <a name='2'></a>*prioqueueName* __option__ ?*arg arg ...*?
__option__ and the *arg*s determine the exact behavior of the command. The
following commands are possible for prioqueue objects:
- <a name='3'></a>*prioqueueName* __clear__
Remove all items from the prioqueue.
- <a name='4'></a>*prioqueueName* __[remove](../../../../index.md#remove)__ *item*
Remove the selected item from this priority queue.
- <a name='5'></a>*prioqueueName* __destroy__
Destroy the prioqueue, including its storage space and associated command.
- <a name='6'></a>*prioqueueName* __get__ ?*count*?
Return the front *count* items of the prioqueue (but not their priorities)
and remove them from the prioqueue. If *count* is not specified, it defaults
to 1. If *count* is 1, the result is a simple string; otherwise, it is a
list. If specified, *count* must be greater than or equal to 1. If there are
no or too few items in the prioqueue, this command will throw an error.
- <a name='7'></a>*prioqueueName* __peek__ ?*count*?
Return the front *count* items of the prioqueue (but not their priorities),
without removing them from the prioqueue. If *count* is not specified, it
defaults to 1. If *count* is 1, the result is a simple string; otherwise, it
is a list. If specified, *count* must be greater than or equal to 1. If
there are no or too few items in the queue, this command will throw an
error.
- <a name='8'></a>*prioqueueName* __peekpriority__ ?*count*?
Return the front *count* items priority keys, without removing them from the
prioqueue. If *count* is not specified, it defaults to 1. If *count* is 1,
the result is a simple string; otherwise, it is a list. If specified,
*count* must be greater than or equal to 1. If there are no or too few items
in the queue, this command will throw an error.
- <a name='9'></a>*prioqueueName* __put__ *item prio* ?*item prio ...*?
Put the *item* or items specified into the prioqueue. *prio* must be a valid
priority key for this type of prioqueue, otherwise an error is thrown and no
item is added. Items are inserted at their priority ranking. Items with
equal priority are added in the order they were added.
- <a name='10'></a>*prioqueueName* __size__
Return the number of items in the prioqueue.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: prioqueue* 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.
# <a name='keywords'></a>KEYWORDS
[ordered list](../../../../index.md#ordered_list),
[prioqueue](../../../../index.md#prioqueue), [priority
queue](../../../../index.md#priority_queue)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003 Michael Schlenker <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/queue.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
[//000000001]: # (struct::queue - Tcl Data Structures)
[//000000002]: # (Generated from file 'queue.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::queue(n) 1.4.5 tcllib "Tcl Data Structures")
# NAME
struct::queue - Create and manipulate queue objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require struct::queue ?1.4.5?
[*queueName* __option__ ?*arg arg ...*?](#1)
[*queueName* __clear__](#2)
[*queueName* __destroy__](#3)
[*queueName* __get__ ?*count*?](#4)
[*queueName* __peek__ ?*count*?](#5)
[*queueName* __put__ *item* ?*item ...*?](#6)
[*queueName* __unget__ *item*](#7)
[*queueName* __size__](#8)
# <a name='description'></a>DESCRIPTION
The __::struct__ namespace contains a commands for processing finite queues.
It exports a single command, __::struct::queue__. All functionality provided
here can be reached through a subcommand of this command.
*Note:* As of version 1.4.1 of this package a critcl based C implementation is
available. This implementation however requires Tcl 8.4 to run.
The __::struct::queue__ command creates a new queue object with an associated
global Tcl command whose name is *queueName*. This command may be used to invoke
various operations on the queue. It has the following general form:
- <a name='1'></a>*queueName* __option__ ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. The
following commands are possible for queue objects:
- <a name='2'></a>*queueName* __clear__
Remove all items from the queue.
- <a name='3'></a>*queueName* __destroy__
Destroy the queue, including its storage space and associated command.
- <a name='4'></a>*queueName* __get__ ?*count*?
Return the front *count* items of the queue and remove them from the queue.
If *count* is not specified, it defaults to 1. If *count* is 1, the result
is a simple string; otherwise, it is a list. If specified, *count* must be
greater than or equal to 1. If there are not enough items in the queue to
fulfull the request, this command will throw an error.
- <a name='5'></a>*queueName* __peek__ ?*count*?
Return the front *count* items of the queue, without removing them from the
queue. If *count* is not specified, it defaults to 1. If *count* is 1, the
result is a simple string; otherwise, it is a list. If specified, *count*
must be greater than or equal to 1. If there are not enough items in the
queue to fulfull the request, this command will throw an error.
- <a name='6'></a>*queueName* __put__ *item* ?*item ...*?
Put the *item* or items specified into the queue. If more than one *item* is
given, they will be added in the order they are listed.
- <a name='7'></a>*queueName* __unget__ *item*
Put the *item* into the queue, at the front, i.e. before any other items
already in the queue. This makes this operation the complement to the method
__get__.
- <a name='8'></a>*queueName* __size__
Return the number of items in the queue.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: queue* 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.
# <a name='keywords'></a>KEYWORDS
[graph](../../../../index.md#graph), [list](../../../../index.md#list),
[matrix](../../../../index.md#matrix), [pool](../../../../index.md#pool),
[prioqueue](../../../../index.md#prioqueue),
[record](../../../../index.md#record), [set](../../../../index.md#set),
[skiplist](../../../../index.md#skiplist), [stack](../../../../index.md#stack),
[tree](../../../../index.md#tree)
# <a name='category'></a>CATEGORY
Data structures
|
Added embedded/md/tcllib/files/modules/struct/record.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
|
[//000000001]: # (struct::record - Tcl Data Structures)
[//000000002]: # (Generated from file 'record.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::record(n) 1.2.1 tcllib "Tcl Data Structures")
# NAME
struct::record - Define and create records (similar to 'C' structures)
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [RECORD MEMBERS](#section2)
- [RECORD COMMAND](#section3)
- [INSTANCE COMMAND](#section4)
- [EXAMPLES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::record ?1.2.1?
[__record define__ *recordName* *recordMembers* ?*instanceName1 instanceName2 ...*?](#1)
[__record show__ *record*](#2)
[__record show__ *instances* *recordName*](#3)
[__record show__ *members* *recordName*](#4)
[__record show__ *values* *instanceName*](#5)
[__record exists__ *record* *recordName*](#6)
[__record exists__ *instance* *instanceName*](#7)
[__record delete__ *record* *recordName*](#8)
[__record delete__ *instance* *instanceName*](#9)
[*recordName* __*instanceName|#auto*__ ?*-member1 value1 -member2 value2 ...*?](#10)
[*instanceName* __cget__ ?*-member1 -member2 ...*?](#11)
[*instanceName* __configure__ ?*-member1 value1 -member2 value2 ...*?](#12)
# <a name='description'></a>DESCRIPTION
The __::struct::record__ package provides a mechanism to group variables
together as one data structure, similar to a 'C' structure. The members of a
record can be variables or other records. However, a record can not contain
circular record, i.e. records that contain the same record as a member.
This package was structured so that it is very similar to how Tk objects work.
Each record definition creates a record object that encompasses that definition.
Subsequently, that record object can create instances of that record. These
instances can then be manipulated with the __cget__ and __configure__ methods.
The package only contains one top level command, but several sub commands (see
below). It also obeys the namespace in which the record was define, hence the
objects returned are fully qualified.
- <a name='1'></a>__record define__ *recordName* *recordMembers* ?*instanceName1 instanceName2 ...*?
Defines a record. *recordName* is the name of the record, and is also used
as an object command. This object command is used to create instances of the
record definition. *recordMembers* are the members of the record that make
up the record definition. These are variables and other record. If optional
*instanceName* args are given, then an instance is generated after the
definition is created for each *instanceName*.
- <a name='2'></a>__record show__ *record*
Returns a list of records that have been defined.
- <a name='3'></a>__record show__ *instances* *recordName*
Returns the instances that have been instantiated by *recordName*.
- <a name='4'></a>__record show__ *members* *recordName*
Returns the members that are defined for record *recordName*. It returns the
same format as how the records were defined.
- <a name='5'></a>__record show__ *values* *instanceName*
Returns a list of values that are set for the instance *instanceName*. The
output is a list of key/value pairs. If there are nested records, then the
values of the nested records will itself be a list.
- <a name='6'></a>__record exists__ *record* *recordName*
Tests for the existence of a *record* with the name *recordName*.
- <a name='7'></a>__record exists__ *instance* *instanceName*
Tests for the existence of a *instance* with the name *instanceName*.
- <a name='8'></a>__record delete__ *record* *recordName*
Deletes *recordName*, and all instances of *recordName*. It will return an
error if the record does not exist.
- <a name='9'></a>__record delete__ *instance* *instanceName*
Deletes *instance* with the name of *instanceName*. It will return an error
if the instance does not exist.
# <a name='section2'></a>RECORD MEMBERS
Record members can either be variables, or other records, However, the same
record can not be nested witin itself (circular). To define a nested record, you
need to specify the __record__ keyword, along the with name of the record, and
the name of the instance of that nested record. For example, it would look like
this:
# this is the nested record
record define mynestedrecord {
nest1
nest2
}
# This is the main record
record define myrecord {
mem1
mem2
{record mynestedrecord mem3}
}
You can also assign default or initial values to the members of a record, by
enclosing the member entry in braces:
record define myrecord {
mem1
{mem2 5}
}
All instances created from this record definition, will initially have 5 as the
value for *mem2*. If no default is given, then the value will be the empty
string.
*Getting Values*
To get a value of a member, there are several ways to do this.
1. To get a member value, then use the instance built-in __cget__ method:
*instanceName* __cget__ -mem1
1. To get multiple member values, you can specify them all in one command:
*instanceName* __cget__ -mem1 -mem2
1. To get a list of the key/value of all of the members, there are 3 ways:
- *instanceName* __cget__
- *instanceName* __configure__
- *instanceName*
1. To get a value of a nested member, then use the dot notation:
*instanceName* __cget__ -mem3.nest1
*Setting Values*
To set a value of a member, there are several ways to do this.
1. To set a member value, then use the instance built-in __configure__ method:
*instanceName* __configure__ -mem1 val1
1. To set multiple member values, you can specify them all in one command:
*instanceName* __configure__ -mem1 va1 -mem2 val2
1. To set a value of a nested member, then use the dot notation:
*instanceName* __configure__ -mem3.nest1 value
*Alias access*
In the original implementation, access was done by using dot notation similar to
how 'C' structures are accessed. However, there was a concensus to make the
interface more Tcl like, which made sense. However, the original alias access
still exists. It might prove to be helpful to some.
Basically, for every member of every instance, an alias is created. This alias
is used to get and set values for that member. An example will illustrate the
point, using the above defined records:
# Create an instance first
% myrecord inst1
::inst1
% # To get a member of an instance, just use the
% # alias (it behaves like a Tcl command):
% inst1.mem1
%
% # To set a member via the alias, just include
% # a value (optionally the equal sign - syntactic sugar)
% inst1.mem1 = 5
5
% inst1.mem1
5
% # For nested records, just continue with the
% # dot notation (note no equal sign)
% inst1.mem3.nest1 10
10
% inst1.mem3.nest1
10
% # just the instance by itself gives all
% # member/values pairs for that instance
% inst1
-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
% # and to get all members within the nested record
% inst1.mem3
-nest1 10 -nest2 {}
%
# <a name='section3'></a>RECORD COMMAND
The following subcommands and corresponding arguments are available to any
record command:
- <a name='10'></a>*recordName* __*instanceName|#auto*__ ?*-member1 value1 -member2 value2 ...*?
Using the *recordName* object command that was created from the record
definition, instances of the record definition can be created. Once a
instance is created, then it inherits the members of the record definition,
very similar to how objects work. During instance generation, an object
command for the instance is created as well, using *instanceName*. This
object command is used to access the data members of the instance. During
the instantiation, values for that instance can be given, *but* all values
must be given, and be given in key/value pairs. Nested records, need to be
in list format.
Optionally, *#auto* can be used in place of *instanceName*. When #auto is
used, then a instance name will automatically be generated, of the form
recordName<integer>, where <integer> is a unique integer (starting at 0)
that is generated.
# <a name='section4'></a>INSTANCE COMMAND
The following subcommands and corresponding arguments are available to any
record instance command:
- <a name='11'></a>*instanceName* __cget__ ?*-member1 -member2 ...*?
Each instance has the sub command __cget__ associated with it. This is very
similar to how Tk widget's cget command works. It queries the values of the
member for that particular instance. If no arguments are given, then a
key/value list is returned.
- <a name='12'></a>*instanceName* __configure__ ?*-member1 value1 -member2 value2 ...*?
Each instance has the sub command __configure__ associated with it. This is
very similar to how Tk widget's configure command works. It sets the values
of the particular member for that particular instance. If no arguments are
given, then a key/value list is returned.
# <a name='section5'></a>EXAMPLES
Two examples are provided to give an good illustration on how to use this
package.
*Example 1*
Probably the most obvious example would be to hold contact information, such as
addresses, phone numbers, comments, etc. Since a person can have multiple phone
numbers, multiple email addresses, etc, we will use nested records to define
these. So, the first thing we do is define the nested records:
##
## This is an interactive example, to see what is
## returned by each command as well.
##
% namespace import ::struct::record::*
% # define a nested record. Notice that country has default 'USA'.
% record define locations {
street
street2
city
state
zipcode
{country USA}
phone
}
::locations
% # Define the main record. Notice that it uses the location record twice.
% record define contacts {
first
middle
last
{record locations home}
{record locations work}
}
::contacts
% # Create an instance for the contacts record.
% contacts cont1
::cont1
% # Display some introspection values
% record show records
::contacts ::locations
% #
% record show values cont1
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% #
% record show instances contacts
::cont1
% #
% cont1 config
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% #
% cont1 cget
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% # copy one record to another record
% record define contacts2 [record show members contacts]
::contacts2
% record show members contacts2
first middle last {record locations home} {record locations work}
% record show members contacts
first middle last {record locations home} {record locations work}
%
*Example 1*
This next example just illustrates a simple linked list
% # define a very simple record for linked list
% record define llist {
value
next
}
::llist
% llist lstart
::lstart
% lstart config -value 1 -next [llist #auto]
% [lstart cget -next] config -value 2 -next [llist #auto]
% [[lstart cget -next] cget -next] config -value 3 -next "end"
% set next lstart
lstart
% while 1 {
lappend values [$next cget -value]
set next [$next cget -next]
if {[string match "end" $next]} {break}
}
% puts "$values"
1 2 3
% # cleanup linked list
% # We could just use delete record llist also
% foreach I [record show instances llist] {
record delete instance $I
}
% record show instances llist
%
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: record* 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.
# <a name='keywords'></a>KEYWORDS
[data structures](../../../../index.md#data_structures),
[record](../../../../index.md#record), [struct](../../../../index.md#struct)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002, Brett Schwarz <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/skiplist.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
[//000000001]: # (struct::skiplist - Tcl Data Structures)
[//000000002]: # (Generated from file 'skiplist.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::skiplist(n) 1.3 tcllib "Tcl Data Structures")
# NAME
struct::skiplist - Create and manipulate skiplists
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::skiplist ?1.3?
[__skiplistName__ *option* ?*arg arg ...*?](#1)
[*skiplistName* __delete__ *node* ?*node*...?](#2)
[*skiplistName* __destroy__](#3)
[*skiplistName* __insert__ *key value*](#4)
[*skiplistName* __search__ *node* ?__-key__ *key*?](#5)
[*skiplistName* __size__](#6)
[*skiplistName* __walk__ *cmd*](#7)
# <a name='description'></a>DESCRIPTION
The __::struct::skiplist__ command creates a new skiplist object with an
associated global Tcl command whose name is *skiplistName*. This command may be
used to invoke various operations on the skiplist. It has the following general
form:
- <a name='1'></a>__skiplistName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
Skip lists are an alternative data structure to binary trees. They can be used
to maintain ordered lists over any sequence of insertions and deletions. Skip
lists use randomness to achieve probabilistic balancing, and as a result the
algorithms for insertion and deletion in skip lists are much simpler and faster
than those for binary trees.
To read more about skip lists see Pugh, William. *Skip lists: a probabilistic
alternative to balanced trees* In: Communications of the ACM, June 1990, 33(6)
668-676.
Currently, the key can be either a number or a string, and comparisons are
performed with the built in greater than operator. The following commands are
possible for skiplist objects:
- <a name='2'></a>*skiplistName* __delete__ *node* ?*node*...?
Remove the specified nodes from the skiplist.
- <a name='3'></a>*skiplistName* __destroy__
Destroy the skiplist, including its storage space and associated command.
- <a name='4'></a>*skiplistName* __insert__ *key value*
Insert a node with the given *key* and *value* into the skiplist. If a node
with that key already exists, then the that node's value is updated and its
node level is returned. Otherwise a new node is created and 0 is returned.
- <a name='5'></a>*skiplistName* __search__ *node* ?__-key__ *key*?
Search for a given key in a skiplist. If not found then 0 is returned. If
found, then a two element list of 1 followed by the node's value is retuned.
- <a name='6'></a>*skiplistName* __size__
Return a count of the number of nodes in the skiplist.
- <a name='7'></a>*skiplistName* __walk__ *cmd*
Walk the skiplist from the first node to the last. At each node, the command
*cmd* will be evaluated with the key and value of the current node appended.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: skiplist* 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.
# <a name='keywords'></a>KEYWORDS
[skiplist](../../../../index.md#skiplist)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2000 Keith Vetter
|
Added embedded/md/tcllib/files/modules/struct/stack.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
[//000000001]: # (struct::stack - Tcl Data Structures)
[//000000002]: # (Generated from file 'stack.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::stack(n) 1.5.3 tcllib "Tcl Data Structures")
# NAME
struct::stack - Create and manipulate stack objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require struct::stack ?1.5.3?
[*stackName* __option__ ?*arg arg ...*?](#1)
[*stackName* __clear__](#2)
[*stackName* __destroy__](#3)
[*stackName* __get__](#4)
[*stackName* __getr__](#5)
[*stackName* __peek__ ?*count*?](#6)
[*stackName* __peekr__ ?*count*?](#7)
[*stackName* __trim__ ?*newsize*?](#8)
[*stackName* __trim*__ ?*newsize*?](#9)
[*stackName* __pop__ ?*count*?](#10)
[*stackName* __push__ *item* ?*item...*?](#11)
[*stackName* __size__](#12)
# <a name='description'></a>DESCRIPTION
The __::struct__ namespace contains a commands for processing finite stacks.
It exports a single command, __::struct::stack__. All functionality provided
here can be reached through a subcommand of this command.
*Note:* As of version 1.3.3 of this package a critcl based C implementation is
available. This implementation however requires Tcl 8.4 to run.
The __::struct::stack__ command creates a new stack object with an associated
global Tcl command whose name is *stackName*. This command may be used to invoke
various operations on the stack. It has the following general form:
- <a name='1'></a>*stackName* __option__ ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command. The
following commands are possible for stack objects:
- <a name='2'></a>*stackName* __clear__
Remove all items from the stack.
- <a name='3'></a>*stackName* __destroy__
Destroy the stack, including its storage space and associated command.
- <a name='4'></a>*stackName* __get__
Returns the whole contents of the stack as a list, without removing them
from the stack.
- <a name='5'></a>*stackName* __getr__
A variant of __get__, which returns the contents in reversed order.
- <a name='6'></a>*stackName* __peek__ ?*count*?
Return the top *count* items of the stack, without removing them from the
stack. If *count* is not specified, it defaults to 1. If *count* is 1, the
result is a simple string; otherwise, it is a list. If specified, *count*
must be greater than or equal to 1. If there are not enoughs items on the
stack to fulfull the request, this command will throw an error.
- <a name='7'></a>*stackName* __peekr__ ?*count*?
A variant of __peek__, which returns the items in reversed order.
- <a name='8'></a>*stackName* __trim__ ?*newsize*?
Shrinks the stack to contain at most *newsize* elements and returns a list
containing the elements which were removed. Nothing is done if the stack is
already at the specified size, or smaller. In that case the result is the
empty list.
- <a name='9'></a>*stackName* __trim*__ ?*newsize*?
A variant of __trim__ which performs the shrinking, but does not return the
removed elements.
- <a name='10'></a>*stackName* __pop__ ?*count*?
Return the top *count* items of the stack, and remove them from the stack.
If *count* is not specified, it defaults to 1. If *count* is 1, the result
is a simple string; otherwise, it is a list. If specified, *count* must be
greater than or equal to 1. If there are not enoughs items on the stack to
fulfull the request, this command will throw an error.
- <a name='11'></a>*stackName* __push__ *item* ?*item...*?
Push the *item* or items specified onto the stack. If more than one *item*
is given, they will be pushed in the order they are listed.
- <a name='12'></a>*stackName* __size__
Return the number of items on the stack.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: stack* 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.
# <a name='keywords'></a>KEYWORDS
[graph](../../../../index.md#graph), [matrix](../../../../index.md#matrix),
[queue](../../../../index.md#queue), [tree](../../../../index.md#tree)
# <a name='category'></a>CATEGORY
Data structures
|
Added embedded/md/tcllib/files/modules/struct/struct_list.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
|
[//000000001]: # (struct::list - Tcl Data Structures)
[//000000002]: # (Generated from file 'struct_list.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::list(n) 1.8.4 tcllib "Tcl Data Structures")
# NAME
struct::list - Procedures for manipulating lists
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON](#section3)
- [TABLE JOIN](#section4)
- [REFERENCES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require struct::list ?1.8.4?
[__::struct::list__ __longestCommonSubsequence__ *sequence1* *sequence2* ?*maxOccurs*?](#1)
[__::struct::list__ __longestCommonSubsequence2__ *sequence1 sequence2* ?*maxOccurs*?](#2)
[__::struct::list__ __lcsInvert__ *lcsData* *len1* *len2*](#3)
[__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*](#4)
[__::struct::list__ __lcsInvertMerge__ *lcsData* *len1* *len2*](#5)
[__::struct::list__ __lcsInvertMerge2__ *lcs1* *lcs2* *len1* *len2*](#6)
[__::struct::list__ __reverse__ *sequence*](#7)
[__::struct::list__ __shuffle__ *list*](#8)
[__::struct::list__ __assign__ *sequence* *varname* ?*varname*?...](#9)
[__::struct::list__ __flatten__ ?__-full__? ?__--__? *sequence*](#10)
[__::struct::list__ __map__ *sequence* *cmdprefix*](#11)
[__::struct::list__ __mapfor__ *var* *sequence* *script*](#12)
[__::struct::list__ __filter__ *sequence* *cmdprefix*](#13)
[__::struct::list__ __filterfor__ *var* *sequence* *expr*](#14)
[__::struct::list__ __split__ *sequence* *cmdprefix* ?*passVar* *failVar*?](#15)
[__::struct::list__ __fold__ *sequence* *initialvalue* *cmdprefix*](#16)
[__::struct::list__ __shift__ *listvar*](#17)
[__::struct::list__ __iota__ *n*](#18)
[__::struct::list__ __equal__ *a* *b*](#19)
[__::struct::list__ __repeat__ *size* *element1* ?*element2* *element3*...?](#20)
[__::struct::list__ __repeatn__ *value* *size*...](#21)
[__::struct::list__ __dbJoin__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? {*keycol* *table*}...](#22)
[__::struct::list__ __dbJoinKeyed__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? *table*...](#23)
[__::struct::list__ __swap__ *listvar* *i* *j*](#24)
[__::struct::list__ __firstperm__ *list*](#25)
[__::struct::list__ __nextperm__ *perm*](#26)
[__::struct::list__ __permutations__ *list*](#27)
[__::struct::list__ __foreachperm__ *var* *list* *body*](#28)
# <a name='description'></a>DESCRIPTION
The __::struct::list__ namespace contains several useful commands for processing
Tcl lists. Generally speaking, they implement algorithms more complex or
specialized than the ones provided by Tcl itself.
It exports only a single command, __struct::list__. All functionality provided
here can be reached through a subcommand of this command.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::struct::list__ __longestCommonSubsequence__ *sequence1* *sequence2* ?*maxOccurs*?
Returns the longest common subsequence of elements in the two lists
*sequence1* and *sequence2*. If the *maxOccurs* parameter is provided, the
common subsequence is restricted to elements that occur no more than
*maxOccurs* times in *sequence2*.
The return value is a list of two lists of equal length. The first sublist
is of indices into *sequence1*, and the second sublist is of indices into
*sequence2*. Each corresponding pair of indices corresponds to equal
elements in the sequences; the sequence returned is the longest possible.
- <a name='2'></a>__::struct::list__ __longestCommonSubsequence2__ *sequence1 sequence2* ?*maxOccurs*?
Returns an approximation to the longest common sequence of elements in the
two lists *sequence1* and *sequence2*. If the *maxOccurs* parameter is
omitted, the subsequence computed is exactly the longest common subsequence;
otherwise, the longest common subsequence is approximated by first
determining the longest common sequence of only those elements that occur no
more than *maxOccurs* times in *sequence2*, and then using that result to
align the two lists, determining the longest common subsequences of the
sublists between the two elements.
As with __longestCommonSubsequence__, the return value is a list of two
lists of equal length. The first sublist is of indices into *sequence1*, and
the second sublist is of indices into *sequence2*. Each corresponding pair
of indices corresponds to equal elements in the sequences. The sequence
approximates the longest common subsequence.
- <a name='3'></a>__::struct::list__ __lcsInvert__ *lcsData* *len1* *len2*
This command takes a description of a longest common subsequence
(*lcsData*), inverts it, and returns the result. Inversion means here that
as the input describes which parts of the two sequences are identical the
output describes the differences instead.
To be fully defined the lengths of the two sequences have to be known and
are specified through *len1* and *len2*.
The result is a list where each element describes one chunk of the
differences between the two sequences. This description is a list containing
three elements, a type and two pairs of indices into *sequence1* and
*sequence2* respectively, in this order. The type can be one of three
values:
* __added__
Describes an addition. I.e. items which are missing in *sequence1* can
be found in *sequence2*. The pair of indices into *sequence1* describes
where the added range had been expected to be in *sequence1*. The first
index refers to the item just before the added range, and the second
index refers to the item just after the added range. The pair of indices
into *sequence2* describes the range of items which has been added to
it. The first index refers to the first item in the range, and the
second index refers to the last item in the range.
* __deleted__
Describes a deletion. I.e. items which are in *sequence1* are missing
from *sequence2*. The pair of indices into *sequence1* describes the
range of items which has been deleted. The first index refers to the
first item in the range, and the second index refers to the last item in
the range. The pair of indices into *sequence2* describes where the
deleted range had been expected to be in *sequence2*. The first index
refers to the item just before the deleted range, and the second index
refers to the item just after the deleted range.
* __changed__
Describes a general change. I.e a range of items in *sequence1* has been
replaced by a different range of items in *sequence2*. The pair of
indices into *sequence1* describes the range of items which has been
replaced. The first index refers to the first item in the range, and the
second index refers to the last item in the range. The pair of indices
into *sequence2* describes the range of items replacing the original
range. Again the first index refers to the first item in the range, and
the second index refers to the last item in the range.
sequence 1 = {a b r a c a d a b r a}
lcs 1 = {1 2 4 5 8 9 10}
lcs 2 = {0 1 3 4 5 6 7}
sequence 2 = {b r i c a b r a c}
Inversion = {{deleted {0 0} {-1 0}}
{changed {3 3} {2 2}}
{deleted {6 7} {4 5}}
{added {10 11} {8 8}}}
*Notes:*
An index of __-1__ in a *deleted* chunk refers to just before the first
element of the second sequence.
Also an index equal to the length of the first sequence in an *added* chunk
refers to just behind the end of the sequence.
- <a name='4'></a>__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*
Similar to __lcsInvert__. Instead of directly taking the result of a call to
__longestCommonSubsequence__ this subcommand expects the indices for the two
sequences in two separate lists.
- <a name='5'></a>__::struct::list__ __lcsInvertMerge__ *lcsData* *len1* *len2*
Similar to __lcsInvert__. It returns essentially the same structure as that
command, except that it may contain chunks of type __unchanged__ too.
These new chunks describe the parts which are unchanged between the two
sequences. This means that the result of this command describes both the
changed and unchanged parts of the two sequences in one structure.
sequence 1 = {a b r a c a d a b r a}
lcs 1 = {1 2 4 5 8 9 10}
lcs 2 = {0 1 3 4 5 6 7}
sequence 2 = {b r i c a b r a c}
Inversion/Merge = {{deleted {0 0} {-1 0}}
{unchanged {1 2} {0 1}}
{changed {3 3} {2 2}}
{unchanged {4 5} {3 4}}
{deleted {6 7} {4 5}}
{unchanged {8 10} {5 7}}
{added {10 11} {8 8}}}
- <a name='6'></a>__::struct::list__ __lcsInvertMerge2__ *lcs1* *lcs2* *len1* *len2*
Similar to __lcsInvertMerge__. Instead of directly taking the result of a
call to __longestCommonSubsequence__ this subcommand expects the indices for
the two sequences in two separate lists.
- <a name='7'></a>__::struct::list__ __reverse__ *sequence*
The subcommand takes a single *sequence* as argument and returns a new
sequence containing the elements of the input sequence in reverse order.
- <a name='8'></a>__::struct::list__ __shuffle__ *list*
The subcommand takes a *list* and returns a copy of that list with the
elements it contains in random order. Every possible ordering of elements is
equally likely to be generated. The Fisher-Yates shuffling algorithm is used
internally.
- <a name='9'></a>__::struct::list__ __assign__ *sequence* *varname* ?*varname*?...
The subcommand assigns the first __n__ elements of the input *sequence* to
the one or more variables whose names were listed after the sequence, where
__n__ is the number of specified variables.
If there are more variables specified than there are elements in the
*sequence* the empty string will be assigned to the superfluous variables.
If there are more elements in the *sequence* than variable names specified
the subcommand returns a list containing the unassigned elements. Else an
empty list is returned.
tclsh> ::struct::list assign {a b c d e} foo bar
c d e
tclsh> set foo
a
tclsh> set bar
b
- <a name='10'></a>__::struct::list__ __flatten__ ?__-full__? ?__--__? *sequence*
The subcommand takes a single *sequence* and returns a new sequence where
one level of nesting was removed from the input sequence. In other words,
the sublists in the input sequence are replaced by their elements.
The subcommand will remove any nesting it finds if the option __-full__ is
specified.
tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10}
1 2 3 4 5 6 7 {8 9} 10
tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10}
1 2 3 4 5 6 7 8 9 10
- <a name='11'></a>__::struct::list__ __map__ *sequence* *cmdprefix*
The subcommand takes a *sequence* to operate on and a command prefix
(*cmdprefix*) specifying an operation, applies the command prefix to each
element of the sequence and returns a sequence consisting of the results of
that application.
The command prefix will be evaluated with a single word appended to it. The
evaluation takes place in the context of the caller of the subcommand.
tclsh> # squaring all elements in a list
tclsh> proc sqr {x} {expr {$x*$x}}
tclsh> ::struct::list map {1 2 3 4 5} sqr
1 4 9 16 25
tclsh> # Retrieving the second column from a matrix
tclsh> # given as list of lists.
tclsh> proc projection {n list} {::lindex $list $n}
tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1}
b 2 f
- <a name='12'></a>__::struct::list__ __mapfor__ *var* *sequence* *script*
The subcommand takes a *sequence* to operate on and a tcl *script*, applies
the script to each element of the sequence and returns a sequence consisting
of the results of that application.
The script will be evaluated as is, and has access to the current list
element through the specified iteration variable *var*. The evaluation takes
place in the context of the caller of the subcommand.
tclsh> # squaring all elements in a list
tclsh> ::struct::list mapfor x {1 2 3 4 5} {
expr {$x * $x}
}
1 4 9 16 25
tclsh> # Retrieving the second column from a matrix
tclsh> # given as list of lists.
tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} {
lindex $x 1
}
b 2 f
- <a name='13'></a>__::struct::list__ __filter__ *sequence* *cmdprefix*
The subcommand takes a *sequence* to operate on and a command prefix
(*cmdprefix*) specifying an operation, applies the command prefix to each
element of the sequence and returns a sequence consisting of all elements of
the *sequence* for which the command prefix returned __true__. In other
words, this command filters out all elements of the input *sequence* which
fail the test the *cmdprefix* represents, and returns the remaining
elements.
The command prefix will be evaluated with a single word appended to it. The
evaluation takes place in the context of the caller of the subcommand.
tclsh> # removing all odd numbers from the input
tclsh> proc even {x} {expr {($x % 2) == 0}}
tclsh> ::struct::list filter {1 2 3 4 5} even
2 4
*Note:* The __filter__ is a specialized application of __fold__ where the
result is extended with the current item or not, depending o nthe result of
the test.
- <a name='14'></a>__::struct::list__ __filterfor__ *var* *sequence* *expr*
The subcommand takes a *sequence* to operate on and a tcl expression
(*expr*) specifying a condition, applies the conditionto each element of the
sequence and returns a sequence consisting of all elements of the *sequence*
for which the expression returned __true__. In other words, this command
filters out all elements of the input *sequence* which fail the test the
condition *expr* represents, and returns the remaining elements.
The expression will be evaluated as is, and has access to the current list
element through the specified iteration variable *var*. The evaluation takes
place in the context of the caller of the subcommand.
tclsh> # removing all odd numbers from the input
tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0}
2 4
- <a name='15'></a>__::struct::list__ __split__ *sequence* *cmdprefix* ?*passVar* *failVar*?
This is a variant of method __filter__, see above. Instead of returning just
the elements passing the test we get lists of both passing and failing
elements.
If no variable names are specified then the result of the command will be a
list containing the list of passing elements, and the list of failing
elements, in this order. Otherwise the lists of passing and failing elements
are stored into the two specified variables, and the result will be a list
containing two numbers, the number of elements passing the test, and the
number of elements failing, in this order.
The interface to the test is the same as used by __filter__.
- <a name='16'></a>__::struct::list__ __fold__ *sequence* *initialvalue* *cmdprefix*
The subcommand takes a *sequence* to operate on, an arbitrary string
*initial value* and a command prefix (*cmdprefix*) specifying an operation.
The command prefix will be evaluated with two words appended to it. The
second of these words will always be an element of the sequence. The
evaluation takes place in the context of the caller of the subcommand.
It then reduces the sequence into a single value through repeated
application of the command prefix and returns that value. This reduction is
done by
* __1__
Application of the command to the initial value and the first element of
the list.
* __2__
Application of the command to the result of the last call and the second
element of the list.
* __...__
* __i__
Application of the command to the result of the last call and the
__i__'th element of the list.
* __...__
* __end__
Application of the command to the result of the last call and the last
element of the list. The result of this call is returned as the result
of the subcommand.
tclsh> # summing the elements in a list.
tclsh> proc + {a b} {expr {$a + $b}}
tclsh> ::struct::list fold {1 2 3 4 5} 0 +
15
- <a name='17'></a>__::struct::list__ __shift__ *listvar*
The subcommand takes the list contained in the variable named by *listvar*
and shifts it down one element. After the call *listvar* will contain a list
containing the second to last elements of the input list. The first element
of the ist is returned as the result of the command. Shifting the empty list
does nothing.
- <a name='18'></a>__::struct::list__ __iota__ *n*
The subcommand returns a list containing the integer numbers in the range
__[0,n)__. The element at index __i__ of the list contain the number __i__.
For "*n* == __0__" an empty list will be returned.
- <a name='19'></a>__::struct::list__ __equal__ *a* *b*
The subcommand compares the two lists *a* and *b* for equality. In other
words, they have to be of the same length and have to contain the same
elements in the same order. If an element is a list the same definition of
equality applies recursively.
A boolean value will be returned as the result of the command. This value
will be __true__ if the two lists are equal, and __false__ else.
- <a name='20'></a>__::struct::list__ __repeat__ *size* *element1* ?*element2* *element3*...?
The subcommand creates a list of length "*size* * *number of elements*" by
repeating *size* times the sequence of elements *element1* *element2* *...*.
*size* must be a positive integer, *element*__n__ can be any Tcl value. Note
that __repeat 1 arg ...__ is identical to __list arg ...__, though the *arg*
is required with __repeat__.
*Examples:*
tclsh> ::struct::list repeat 3 a
a a a
tclsh> ::struct::list repeat 3 [::struct::list repeat 3 0]
{0 0 0} {0 0 0} {0 0 0}
tclsh> ::struct::list repeat 3 a b c
a b c a b c a b c
tclsh> ::struct::list repeat 3 [::struct::list repeat 2 a] b c
{a a} b c {a a} b c {a a} b c
- <a name='21'></a>__::struct::list__ __repeatn__ *value* *size*...
The subcommand creates a (nested) list containing the *value* in all
positions. The exact size and degree of nesting is determined by the *size*
arguments, all of which have to be integer numbers greater than or equal to
zero.
A single argument *size* which is a list of more than one element will be
treated as if more than argument *size* was specified.
If only one argument *size* is present the returned list will not be nested,
of length *size* and contain *value* in all positions. If more than one
*size* argument is present the returned list will be nested, and of the
length specified by the last *size* argument given to it. The elements of
that list are defined as the result of __Repeat__ for the same arguments,
but with the last *size* value removed.
An empty list will be returned if no *size* arguments are present.
tclsh> ::struct::list repeatn 0 3 4
{0 0 0} {0 0 0} {0 0 0} {0 0 0}
tclsh> ::struct::list repeatn 0 {3 4}
{0 0 0} {0 0 0} {0 0 0} {0 0 0}
tclsh> ::struct::list repeatn 0 {3 4 5}
{{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}}
- <a name='22'></a>__::struct::list__ __dbJoin__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? {*keycol* *table*}...
The method performs a table join according to relational algebra. The
execution of any of the possible outer join operation is triggered by the
presence of either option __-left__, __-right__, or __-full__. If none of
these options is present a regular inner join will be performed. This can
also be triggered by specifying __-inner__. The various possible join
operations are explained in detail in section [TABLE JOIN](#section4).
If the __-keys__ is present its argument is the name of a variable to store
the full list of found keys into. Depending on the exact nature of the input
table and the join mode the output table may not contain all the keys by
default. In such a case the caller can declare a variable for this
information and then insert it into the output table on its own, as she will
have more information about the placement than this command.
What is left to explain is the format of the arguments.
The *keycol* arguments are the indices of the columns in the tables which
contain the key values to use for the joining. Each argument applies to the
table following immediately after it. The columns are counted from __0__,
which references the first column. The table associated with the column
index has to have at least *keycol*+1 columns. An error will be thrown if
there are less.
The *table* arguments represent a table or matrix of rows and columns of
values. We use the same representation as generated and consumed by the
methods __get rect__ and __set rect__ of
__[matrix](../../../../index.md#matrix)__ objects. In other words, each
argument is a list, representing the whole matrix. Its elements are lists
too, each representing a single rows of the matrix. The elements of the
row-lists are the column values.
The table resulting from the join operation is returned as the result of the
command. We use the same representation as described above for the input
*table*s.
- <a name='23'></a>__::struct::list__ __dbJoinKeyed__ ?__-inner__|__-left__|__-right__|__-full__? ?__-keys__ *varname*? *table*...
The operations performed by this method are the same as described above for
__dbJoin__. The only difference is in the specification of the keys to use.
Instead of using column indices separate from the table here the keys are
provided within the table itself. The row elements in each *table* are not
the lists of column values, but a two-element list where the second element
is the regular list of column values and the first element is the key to
use.
- <a name='24'></a>__::struct::list__ __swap__ *listvar* *i* *j*
The subcommand exchanges the elements at the indices *i* and *j* in the list
stored in the variable named by *listvar*. The list is modified in place,
and also returned as the result of the subcommand.
- <a name='25'></a>__::struct::list__ __firstperm__ *list*
This subcommand returns the lexicographically first permutation of the input
*list*.
- <a name='26'></a>__::struct::list__ __nextperm__ *perm*
This subcommand accepts a permutation of a set of elements (provided by
*perm*) and returns the next permutatation in lexicographic sequence.
The algorithm used here is by Donal E. Knuth, see section
[REFERENCES](#section5) for details.
- <a name='27'></a>__::struct::list__ __permutations__ *list*
This subcommand returns a list containing all permutations of the input
*list* in lexicographic order.
- <a name='28'></a>__::struct::list__ __foreachperm__ *var* *list* *body*
This subcommand executes the script *body* once for each permutation of the
specified *list*. The permutations are visited in lexicographic order, and
the variable *var* is set to the permutation for which *body* is currently
executed. The result of the loop command is the empty string.
# <a name='section3'></a>LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON
The __longestCommonSubsequence__ subcommand forms the core of a flexible system
for doing differential comparisons of files, similar to the capability offered
by the Unix command __[diff](../../../../index.md#diff)__. While this procedure
is quite rapid for many tasks of file comparison, its performance degrades
severely if *sequence2* contains many equal elements (as, for instance, when
using this procedure to compare two files, a quarter of whose lines are blank.
This drawback is intrinsic to the algorithm used (see the Reference for
details).
One approach to dealing with the performance problem that is sometimes effective
in practice is arbitrarily to exclude elements that appear more than a certain
number of times. This number is provided as the *maxOccurs* parameter. If
frequent lines are excluded in this manner, they will not appear in the common
subsequence that is computed; the result will be the longest common subsequence
of infrequent elements. The procedure __longestCommonSubsequence2__ implements
this heuristic. It functions as a wrapper around __longestCommonSubsequence__;
it computes the longest common subsequence of infrequent elements, and then
subdivides the subsequences that lie between the matches to approximate the true
longest common subsequence.
# <a name='section4'></a>TABLE JOIN
This is an operation from relational algebra for relational databases.
The easiest way to understand the regular inner join is that it creates the
cartesian product of all the tables involved first and then keeps only all those
rows in the resulting table for which the values in the specified key columns
are equal to each other.
Implementing this description naively, i.e. as described above will generate a
*huge* intermediate result. To avoid this the cartesian product and the
filtering of row are done at the same time. What is required is a fast way to
determine if a key is present in a table. In a true database this is done
through indices. Here we use arrays internally.
An *outer* join is an extension of the inner join for two tables. There are
three variants of outerjoins, called *left*, *right*, and *full* outer joins.
Their result always contains all rows from an inner join and then some
additional rows.
1. For the left outer join the additional rows are all rows from the left
table for which there is no key in the right table. They are joined to an
empty row of the right table to fit them into the result.
1. For the right outer join the additional rows are all rows from the right
table for which there is no key in the left table. They are joined to an
empty row of the left table to fit them into the result.
1. The full outer join combines both left and right outer join. In other
words, the additional rows are as defined for left outer join, and right
outer join, combined.
We extend all the joins from two to __n__ tables (__n__ > 2) by executing
(...((table1 join table2) join table3) ...) join tableN
Examples for all the joins:
Inner Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} inner join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver}
Left Outer Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} left outer join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver} {2 blue {} {}}
Right Outer Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} right outer join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver} {{} {} 3 driver}
Full Outer Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} full outer join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver} {2 blue {} {}}
{{} {} 3 driver}
# <a name='section5'></a>REFERENCES
1. J. W. Hunt and M. D. McIlroy, "An algorithm for differential file
comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone Laboratories (1976).
Available on the Web at the second author's personal site:
[http://www.cs.dartmouth.edu/~doug/](http://www.cs.dartmouth.edu/~doug/)
1. Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming' volume
4". Available on the Web at the author's personal site:
[http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz](http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz).
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: list* 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.
# <a name='keywords'></a>KEYWORDS
[Fisher-Yates](../../../../index.md#fisher_yates),
[assign](../../../../index.md#assign), [common](../../../../index.md#common),
[comparison](../../../../index.md#comparison),
[diff](../../../../index.md#diff),
[differential](../../../../index.md#differential),
[equal](../../../../index.md#equal), [equality](../../../../index.md#equality),
[filter](../../../../index.md#filter), [first
permutation](../../../../index.md#first_permutation),
[flatten](../../../../index.md#flatten),
[folding](../../../../index.md#folding), [full outer
join](../../../../index.md#full_outer_join), [generate
permutations](../../../../index.md#generate_permutations), [inner
join](../../../../index.md#inner_join), [join](../../../../index.md#join), [left
outer join](../../../../index.md#left_outer_join),
[list](../../../../index.md#list), [longest common
subsequence](../../../../index.md#longest_common_subsequence),
[map](../../../../index.md#map), [next
permutation](../../../../index.md#next_permutation), [outer
join](../../../../index.md#outer_join),
[permutation](../../../../index.md#permutation),
[reduce](../../../../index.md#reduce),
[repeating](../../../../index.md#repeating),
[repetition](../../../../index.md#repetition),
[reshuffle](../../../../index.md#reshuffle),
[reverse](../../../../index.md#reverse), [right outer
join](../../../../index.md#right_outer_join),
[shuffle](../../../../index.md#shuffle),
[subsequence](../../../../index.md#subsequence),
[swapping](../../../../index.md#swapping)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2003-2005 by Kevin B. Kenny. All rights reserved
Copyright © 2003-2012 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/struct_set.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
[//000000001]: # (struct::set - Tcl Data Structures)
[//000000002]: # (Generated from file 'struct_set.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::set(n) 2.2.3 tcllib "Tcl Data Structures")
# NAME
struct::set - Procedures for manipulating sets
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [REFERENCES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.0
package require struct::set ?2.2.3?
[__::struct::set__ __empty__ *set*](#1)
[__::struct::set__ __size__ *set*](#2)
[__::struct::set__ __contains__ *set* *item*](#3)
[__::struct::set__ __union__ ?*set1*...?](#4)
[__::struct::set__ __intersect__ ?*set1*...?](#5)
[__::struct::set__ __difference__ *set1* *set2*](#6)
[__::struct::set__ __symdiff__ *set1* *set2*](#7)
[__::struct::set__ __intersect3__ *set1* *set2*](#8)
[__::struct::set__ __equal__ *set1* *set2*](#9)
[__::struct::set__ __include__ *svar* *item*](#10)
[__::struct::set__ __exclude__ *svar* *item*](#11)
[__::struct::set__ __add__ *svar* *set*](#12)
[__::struct::set__ __subtract__ *svar* *set*](#13)
[__::struct::set__ __subsetof__ *A* *B*](#14)
# <a name='description'></a>DESCRIPTION
The __::struct::set__ namespace contains several useful commands for processing
finite sets.
It exports only a single command, __struct::set__. All functionality provided
here can be reached through a subcommand of this command.
*Note:* As of version 2.2 of this package a critcl based C implementation is
available. This implementation however requires Tcl 8.4 to run.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::struct::set__ __empty__ *set*
Returns a boolean value indicating if the *set* is empty (__true__), or not
(__false__).
- <a name='2'></a>__::struct::set__ __size__ *set*
Returns an integer number greater than or equal to zero. This is the number
of elements in the *set*. In other words, its cardinality.
- <a name='3'></a>__::struct::set__ __contains__ *set* *item*
Returns a boolean value indicating if the *set* contains the element *item*
(__true__), or not (__false__).
- <a name='4'></a>__::struct::set__ __union__ ?*set1*...?
Computes the set containing the union of *set1*, *set2*, etc., i.e. "*set1*
+ *set2* + ...", and returns this set as the result of the command.
- <a name='5'></a>__::struct::set__ __intersect__ ?*set1*...?
Computes the set containing the intersection of *set1*, *set2*, etc., i.e.
"*set1* * *set2* * ...", and returns this set as the result of the command.
- <a name='6'></a>__::struct::set__ __difference__ *set1* *set2*
Computes the set containing the difference of *set1* and *set2*, i.e.
("*set1* - *set2*") and returns this set as the result of the command.
- <a name='7'></a>__::struct::set__ __symdiff__ *set1* *set2*
Computes the set containing the symmetric difference of *set1* and *set2*,
i.e. ("(*set1* - *set2*) + (*set2* - *set1*)") and returns this set as the
result of the command.
- <a name='8'></a>__::struct::set__ __intersect3__ *set1* *set2*
This command is a combination of the methods __intersect__ and
__difference__. It returns a three-element list containing "*set1***set2*",
"*set1*-*set2*", and "*set2*-*set1*", in this order. In other words, the
intersection of the two parameter sets, and their differences.
- <a name='9'></a>__::struct::set__ __equal__ *set1* *set2*
Returns a boolean value indicating if the two sets are equal (__true__) or
not (__false__).
- <a name='10'></a>__::struct::set__ __include__ *svar* *item*
The element *item* is added to the set specified by the variable name in
*svar*. The return value of the command is empty. This is the equivalent of
__lappend__ for sets. If the variable named by *svar* does not exist it will
be created.
- <a name='11'></a>__::struct::set__ __exclude__ *svar* *item*
The element *item* is removed from the set specified by the variable name in
*svar*. The return value of the command is empty. This is a near-equivalent
of __lreplace__ for sets.
- <a name='12'></a>__::struct::set__ __add__ *svar* *set*
All the element of *set* are added to the set specified by the variable name
in *svar*. The return value of the command is empty. This is like the method
__include__, but for the addition of a whole set. If the variable named by
*svar* does not exist it will be created.
- <a name='13'></a>__::struct::set__ __subtract__ *svar* *set*
All the element of *set* are removed from the set specified by the variable
name in *svar*. The return value of the command is empty. This is like the
method __exclude__, but for the removal of a whole set.
- <a name='14'></a>__::struct::set__ __subsetof__ *A* *B*
Returns a boolean value indicating if the set *A* is a true subset of or
equal to the set *B* (__true__), or not (__false__).
# <a name='section3'></a>REFERENCES
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: set* 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.
# <a name='keywords'></a>KEYWORDS
[cardinality](../../../../index.md#cardinality),
[difference](../../../../index.md#difference),
[emptiness](../../../../index.md#emptiness),
[exclusion](../../../../index.md#exclusion),
[inclusion](../../../../index.md#inclusion),
[intersection](../../../../index.md#intersection),
[membership](../../../../index.md#membership), [set](../../../../index.md#set),
[symmetric difference](../../../../index.md#symmetric_difference),
[union](../../../../index.md#union)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/struct_tree.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
|
[//000000001]: # (struct::tree - Tcl Data Structures)
[//000000002]: # (Generated from file 'struct_tree.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::tree(n) 2.1.1 tcllib "Tcl Data Structures")
# NAME
struct::tree - Create and manipulate tree objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Tree CLASS API](#subsection1)
- [Tree OBJECT API](#subsection2)
- [Changes for 2.0](#subsection3)
- [EXAMPLES](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::tree ?2.1.1?
package require struct::list ?1.5?
[__::struct::tree__ ?*treeName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1)
[__treeName__ __option__ ?*arg arg ...*?](#2)
[__::struct::tree::prune__](#3)
[*treeName* __=__ *sourcetree*](#4)
[*treeName* __-->__ *desttree*](#5)
[*treeName* __ancestors__ *node*](#6)
[*treeName* __append__ *node* *key* *value*](#7)
[*treeName* __attr__ *key*](#8)
[*treeName* __attr__ *key* __-nodes__ *list*](#9)
[*treeName* __attr__ *key* __-glob__ *globpattern*](#10)
[*treeName* __attr__ *key* __-regexp__ *repattern*](#11)
[*treeName* __children__ ?__-all__? *node* ?__filter__ *cmdprefix*?](#12)
[*treeName* __cut__ *node*](#13)
[*treeName* __delete__ *node* ?*node* ...?](#14)
[*treeName* __depth__ *node*](#15)
[*treeName* __descendants__ *node* ?__filter__ *cmdprefix*?](#16)
[*treeName* __deserialize__ *serialization*](#17)
[*treeName* __destroy__](#18)
[*treeName* __exists__ *node*](#19)
[*treeName* __get__ *node* *key*](#20)
[*treeName* __getall__ *node* ?*pattern*?](#21)
[*treeName* __keys__ *node* ?*pattern*?](#22)
[*treeName* __keyexists__ *node* *key*](#23)
[*treeName* __index__ *node*](#24)
[*treeName* __insert__ *parent* *index* ?*child* ?*child* ...??](#25)
[*treeName* __isleaf__ *node*](#26)
[*treeName* __lappend__ *node* *key* *value*](#27)
[*treeName* __leaves__](#28)
[*treeName* __move__ *parent* *index* *node* ?*node* ...?](#29)
[*treeName* __next__ *node*](#30)
[*treeName* __numchildren__ *node*](#31)
[*treeName* __nodes__](#32)
[*treeName* __parent__ *node*](#33)
[*treeName* __previous__ *node*](#34)
[*treeName* __rename__ *node* *newname*](#35)
[*treeName* __rootname__](#36)
[*treeName* __serialize__ ?*node*?](#37)
[*treeName* __set__ *node* *key* ?*value*?](#38)
[*treeName* __size__ ?*node*?](#39)
[*treeName* __splice__ *parent* *from* ?*to*? ?*child*?](#40)
[*treeName* __swap__ *node1* *node2*](#41)
[*treeName* __unset__ *node* *key*](#42)
[*treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? *loopvar* *script*](#43)
[*treeName* __walkproc__ *node* ?__-order__ *order*? ?__-type__ *type*? *cmdprefix*](#44)
# <a name='description'></a>DESCRIPTION
A tree is a collection of named elements, called nodes, one of which is
distinguished as a root, along with a relation ("parenthood") that places a
hierarchical structure on the nodes. (Data Structures and Algorithms; Aho,
Hopcroft and Ullman; Addison-Wesley, 1987). In addition to maintaining the node
relationships, this tree implementation allows any number of keyed values to be
associated with each node.
The element names can be arbitrary strings.
A tree is thus similar to an array, but with three important differences:
1. Trees are accessed through an object command, whereas arrays are accessed
as variables. (This means trees cannot be local to a procedure.)
1. Trees have a hierarchical structure, whereas an array is just an unordered
collection.
1. Each node of a tree has a separate collection of attributes and values.
This is like an array where every value is a dictionary.
*Note:* The major version of the package
__[struct](../../../../index.md#struct)__ has been changed to version 2.0, due
to backward incompatible changes in the API of this module. Please read the
section [Changes for 2.0](#subsection3) for a full list of all changes,
incompatible and otherwise.
# <a name='section2'></a>API
## <a name='subsection1'></a>Tree CLASS API
The main commands of the package are:
- <a name='1'></a>__::struct::tree__ ?*treeName*? ?__=__|__:=__|__as__|__deserialize__ *source*?
The command creates a new tree object with an associated global Tcl command
whose name is *treeName*. This command may be used to invoke various
operations on the tree. It has the following general form:
* <a name='2'></a>__treeName__ __option__ ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
If *treeName* is not specified a unique name will be generated by the
package itself. If a *source* is specified the new tree will be initialized
to it. For the operators __=__, __:=__, and __as__ *source* is interpreted
as the name of another tree object, and the assignment operator __=__ will
be executed. For __deserialize__ the *source* is a serialized tree object
and __deserialize__ will be executed.
In other words
::struct::tree mytree = b
is equivalent to
::struct::tree mytree
mytree = b
and
::struct::tree mytree deserialize $b
is equivalent to
::struct::tree mytree
mytree deserialize $b
- <a name='3'></a>__::struct::tree::prune__
This command is provided outside of the tree methods, as it is not a tree
method per se. It however interacts tightly with the method __walk__. When
used in the walk script it causes the traversal to ignore the children of
the node we are currently at. This command cannot be used with the traversal
modes which look at children before their parent, i.e. __post__ and __in__.
The only applicable orders of traversal are __pre__ and __both__. An error
is thrown if the command and chosen order of traversal do not fit.
## <a name='subsection2'></a>Tree OBJECT API
Two general observations beforehand:
1. The root node of the tree can be used in most places where a node is asked
for. The default name of the rootnode is "root", but this can be changed
with the method __rename__ (see below). Whatever the current name for the
root node of the tree is, it can be retrieved by calling the method
__rootname__.
1. The method __insert__ is the only way to create new nodes, and they are
automatically added to a parent. A tree object cannot have nodes without a
parent, save the root node.
And now the methods supported by tree objects created by this package:
- <a name='4'></a>*treeName* __=__ *sourcetree*
This is the assignment operator for tree objects. It copies the tree
contained in the tree object *sourcetree* over the tree data in *treeName*.
The old contents of *treeName* are deleted by this operation.
This operation is in effect equivalent to
*treeName* __deserialize__ [*sourcetree* __serialize__]
- <a name='5'></a>*treeName* __-->__ *desttree*
This is the reverse assignment operator for tree objects. It copies the tree
contained in the tree object *treeName* over the tree data in the object
*desttree*. The old contents of *desttree* are deleted by this operation.
This operation is in effect equivalent to
*desttree* __deserialize__ [*treeName* __serialize__]
- <a name='6'></a>*treeName* __ancestors__ *node*
This method extends the method __parent__ and returns a list containing all
ancestor nodes to the specified *node*. The immediate ancestor, in other
words, parent node, is the first element in that list, its parent the second
element, and so on until the root node is reached, making it the last
element of the returned list.
- <a name='7'></a>*treeName* __append__ *node* *key* *value*
Appends a *value* to one of the keyed values associated with an node.
Returns the new value given to the attribute *key*.
- <a name='8'></a>*treeName* __attr__ *key*
- <a name='9'></a>*treeName* __attr__ *key* __-nodes__ *list*
- <a name='10'></a>*treeName* __attr__ *key* __-glob__ *globpattern*
- <a name='11'></a>*treeName* __attr__ *key* __-regexp__ *repattern*
This method retrieves the value of the attribute named *key*, for all nodes
in the tree (matching the restriction specified via one of the possible
options) and having the specified attribute.
The result is a dictionary mapping from node names to the value of attribute
*key* at that node. Nodes not having the attribute *key*, or not passing a
specified restriction, are not listed in the result.
The possible restrictions are:
* __-nodes__
The value is a list of nodes. Only the nodes mentioned in this list are
searched for the attribute.
* __-glob__
The value is a glob pattern. Only the nodes in the tree whose names
match this pattern are searched for the attribute.
* __-regexp__
The value is a regular expression. Only the nodes in the tree whose
names match this pattern are searched for the attribute.
- <a name='12'></a>*treeName* __children__ ?__-all__? *node* ?__filter__ *cmdprefix*?
Return a list of the children of *node*. If the option __-all__ is
specified, then not only the direct children, but their children, and so on
are returned in the result. If a filter command is specified only those
nodes are listed in the final result which pass the test. The command in
*cmdprefix* is called with two arguments, the name of the tree object, and
the name of the node in question. It is executed in the context of the
caller and has to return a boolean value. Nodes for which the command
returns __false__ are removed from the result list before it is returned to
the caller.
Some examples:
mytree insert root end 0 ; mytree set 0 volume 30
mytree insert root end 1
mytree insert root end 2
mytree insert 0 end 3
mytree insert 0 end 4
mytree insert 4 end 5 ; mytree set 5 volume 50
mytree insert 4 end 6
proc vol {t n} {
$t keyexists $n volume
}
proc vgt40 {t n} {
if {![$t keyexists $n volume]} {return 0}
expr {[$t get $n volume] > 40}
}
tclsh> lsort [mytree children -all root filter vol]
0 5
tclsh> lsort [mytree children -all root filter vgt40]
5
tclsh> lsort [mytree children root filter vol]
0
tclsh> puts ([lsort [mytree children root filter vgt40]])
()
- <a name='13'></a>*treeName* __cut__ *node*
Removes the node specified by *node* from the tree, but not its children.
The children of *node* are made children of the parent of the *node*, at the
index at which *node* was located.
- <a name='14'></a>*treeName* __delete__ *node* ?*node* ...?
Removes the specified nodes from the tree. All of the nodes' children will
be removed as well to prevent orphaned nodes.
- <a name='15'></a>*treeName* __depth__ *node*
Return the number of steps from node *node* to the root node.
- <a name='16'></a>*treeName* __descendants__ *node* ?__filter__ *cmdprefix*?
This method extends the method __children__ and returns a list containing
all nodes descending from *node*, and passing the filter, if such was
specified.
This is actually the same as "*treeName* __children__ __-all__".
__descendants__ should be prefered, and "children -all" will be deprecated
sometime in the future.
- <a name='17'></a>*treeName* __deserialize__ *serialization*
This is the complement to __serialize__. It replaces tree data in *treeName*
with the tree described by the *serialization* value. The old contents of
*treeName* are deleted by this operation.
- <a name='18'></a>*treeName* __destroy__
Destroy the tree, including its storage space and associated command.
- <a name='19'></a>*treeName* __exists__ *node*
Returns true if the specified node exists in the tree.
- <a name='20'></a>*treeName* __get__ *node* *key*
Returns the value associated with the key *key* for the node *node*.
- <a name='21'></a>*treeName* __getall__ *node* ?*pattern*?
Returns a dictionary (suitable for use with [__array set__]) containing the
attribute data for the *node*. If the glob *pattern* is specified only the
attributes whose names match the pattern will be part of the dictionary.
- <a name='22'></a>*treeName* __keys__ *node* ?*pattern*?
Returns a list of keys for the *node*. If the *pattern* is specified only
the attributes whose names match the pattern will be part of the returned
list. The pattern is a __glob__ pattern.
- <a name='23'></a>*treeName* __keyexists__ *node* *key*
Return true if the specified *key* exists for the *node*.
- <a name='24'></a>*treeName* __index__ *node*
Returns the index of *node* in its parent's list of children. For example,
if a node has *nodeFoo*, *nodeBar*, and *nodeBaz* as children, in that
order, the index of *nodeBar* is 1.
- <a name='25'></a>*treeName* __insert__ *parent* *index* ?*child* ?*child* ...??
Insert one or more nodes into the tree as children of the node *parent*. The
nodes will be added in the order they are given. If *parent* is __root__, it
refers to the root of the tree. The new nodes will be added to the *parent*
node's child list at the index given by *index*. The *index* can be __end__
in which case the new nodes will be added after the current last child.
Indices of the form "end-__n__" are accepted as well.
If any of the specified children already exist in *treeName*, those nodes
will be moved from their original location to the new location indicated by
this command.
If no *child* is specified, a single node will be added, and a name will be
generated for the new node. The generated name is of the form *node*__x__,
where __x__ is a number. If names are specified they must neither contain
whitespace nor colons (":").
The return result from this command is a list of nodes added.
- <a name='26'></a>*treeName* __isleaf__ *node*
Returns true if *node* is a leaf of the tree (if *node* has no children),
false otherwise.
- <a name='27'></a>*treeName* __lappend__ *node* *key* *value*
Appends a *value* (as a list) to one of the keyed values associated with an
*node*. Returns the new value given to the attribute *key*.
- <a name='28'></a>*treeName* __leaves__
Return a list containing all leaf nodes known to the tree.
- <a name='29'></a>*treeName* __move__ *parent* *index* *node* ?*node* ...?
Make the specified nodes children of *parent*, inserting them into the
parent's child list at the index given by *index*. Note that the command
will take all nodes out of the tree before inserting them under the new
parent, and that it determines the position to place them into after the
removal, before the re-insertion. This behaviour is important when it comes
to moving one or more nodes to a different index without changing their
parent node.
- <a name='30'></a>*treeName* __next__ *node*
Return the right sibling of *node*, or the empty string if *node* was the
last child of its parent.
- <a name='31'></a>*treeName* __numchildren__ *node*
Return the number of immediate children of *node*.
- <a name='32'></a>*treeName* __nodes__
Return a list containing all nodes known to the tree.
- <a name='33'></a>*treeName* __parent__ *node*
Return the parent of *node*.
- <a name='34'></a>*treeName* __previous__ *node*
Return the left sibling of *node*, or the empty string if *node* was the
first child of its parent.
- <a name='35'></a>*treeName* __rename__ *node* *newname*
Renames the node *node* to *newname*. An error is thrown if either the node
does not exist, or a node with name *newname* does exist. The result of the
command is the new name of the node.
- <a name='36'></a>*treeName* __rootname__
Returns the name of the root node of the tree.
- <a name='37'></a>*treeName* __serialize__ ?*node*?
This method serializes the sub-tree starting at *node*. In other words it
returns a tcl *value* completely describing the tree starting at *node*.
This allows, for example, the transfer of tree objects (or parts thereof)
over arbitrary channels, persistence, etc. This method is also the basis for
both the copy constructor and the assignment operator.
The result of this method has to be semantically identical over all
implementations of the tree interface. This is what will enable us to copy
tree data between different implementations of the same interface.
The result is a list containing containing a multiple of three elements. It
is like a serialized array except that there are two values following each
key. They are the names of the nodes in the serialized tree. The two values
are a reference to the parent node and the attribute data, in this order.
The reference to the parent node is the empty string for the root node of
the tree. For all other nodes it is the index of the parent node in the
list. This means that they are integers, greater than or equal to zero, less
than the length of the list, and multiples of three. The order of the nodes
in the list is important insofar as it is used to reconstruct the lists of
children for each node. The children of a node have to be listed in the
serialization in the same order as they are listed in their parent in the
tree.
The attribute data of a node is a dictionary, i.e. a list of even length
containing a serialized array. For a node without attribute data the
dictionary is the empty list.
*Note:* While the current implementation returns the root node as the first
element of the list, followed by its children and their children in a
depth-first traversal this is not necessarily true for other
implementations. The only information a reader of the serialized data can
rely on for the structure of the tree is that the root node is signaled by
the empty string for the parent reference, that all other nodes refer to
their parent through the index in the list, and that children occur in the
same order as in their parent.
A possible serialization for the tree structure
+- d
+- a -+
root -+- b +- e
+- c
is
{root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}}
The above assumes that none of the nodes have attributes.
- <a name='38'></a>*treeName* __set__ *node* *key* ?*value*?
Set or get one of the keyed values associated with a node. A node may have
any number of keyed values associated with it. If *value* is not specified,
this command returns the current value assigned to the key; if *value* is
specified, this command assigns that value to the key, and returns it.
- <a name='39'></a>*treeName* __size__ ?*node*?
Return a count of the number of descendants of the node *node*; if no node
is specified, __root__ is assumed.
- <a name='40'></a>*treeName* __splice__ *parent* *from* ?*to*? ?*child*?
Insert a node named *child* into the tree as a child of the node *parent*.
If *parent* is __root__, it refers to the root of the tree. The new node
will be added to the parent node's child list at the index given by *from*.
The children of *parent* which are in the range of the indices *from* and
*to* are made children of *child*. If the value of *to* is not specified it
defaults to __end__. If no name is given for *child*, a name will be
generated for the new node. The generated name is of the form *node*__x__,
where __x__ is a number. The return result from this command is the name of
the new node.
The arguments *from* and *to* are regular list indices, i.e. the form
"end-__n__" is accepted as well.
- <a name='41'></a>*treeName* __swap__ *node1* *node2*
Swap the position of *node1* and *node2* in the tree.
- <a name='42'></a>*treeName* __unset__ *node* *key*
Removes a keyed value from the node *node*. The method will do nothing if
the *key* does not exist.
- <a name='43'></a>*treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? *loopvar* *script*
Perform a breadth-first or depth-first walk of the tree starting at the node
*node*. The type of walk, breadth-first or depth-first, is determined by the
value of *type*; __bfs__ indicates breadth-first, __dfs__ indicates
depth-first. Depth-first is the default. The order of the walk, pre-, post-,
both- or in-order is determined by the value of *order*; __pre__ indicates
pre-order, __post__ indicates post-order, __both__ indicates both-order and
__in__ indicates in-order. Pre-order is the default.
Pre-order walking means that a parent node is visited before any of its
children. For example, a breadth-first search starting from the root will
visit the root, followed by all of the root's children, followed by all of
the root's grandchildren. Post-order walking means that a parent node is
visited after any of its children. Both-order walking means that a parent
node is visited before *and* after any of its children. In-order walking
means that a parent node is visited after its first child and before the
second. This is a generalization of in-order walking for binary trees and
will do the right thing if a binary tree is walked. The combination of a
breadth-first walk with in-order is illegal.
As the walk progresses, the *script* will be evaluated at each node. The
evaluation takes place in the context of the caller of the method. Regarding
loop variables, these are listed in *loopvar*. If one only one variable is
specified it will be set to the id of the node. When two variables are
specified, i.e. *loopvar* is a true list, then the first variable will be
set to the action performed at the node, and the other to the id of the node
itself. All loop variables are created in the context of the caller.
There are three possible actions: __enter__, __leave__, or __visit__.
__enter__ actions occur during pre-order walks; __leave__ actions occur
during post-order walks; __visit__ actions occur during in-order walks. In a
both-order walk, the command will be evaluated twice for each node; the
action is __enter__ for the first evaluation, and __leave__ for the second.
*Note*: The __enter__ action for a node is always performed before the
walker will look at the children of that node. This means that changes made
by the *script* to the children of the node will immediately influence the
walker and the steps it will take.
Any other manipulation, for example of nodes higher in the tree (i.e already
visited), or upon leaving will have undefined results. They may succeed,
error out, silently compute the wrong result, or anything in between.
At last a small table showing the relationship between the various options
and the possible actions.
order type actions notes
----- ---- ----- -----
pre dfs enter parent before children
post dfs leave parent after children
in dfs visit parent between first and second child.
both dfs enter, leave parent before and after children
----- ---- ----- -----
pre bfs enter parent before children
post bfs leave parent after children
in bfs -- illegal --
both bfs enter, leave parent before and after children
----- ---- ----- -----
Note the command __::struct::tree::prune__. This command can be used in the
walk script to force the command to ignore the children of the node we are
currently at. It will throw an error if the order of traversal is either
__post__ or __in__ as these modes visit the children before their parent,
making pruning non-sensical.
- <a name='44'></a>*treeName* __walkproc__ *node* ?__-order__ *order*? ?__-type__ *type*? *cmdprefix*
This method is like method __walk__ in all essentials, except the interface
to the user code. This method invokes a command prefix with three additional
arguments (tree, node, and action), instead of evaluating a script and
passing the node via a loop variable.
## <a name='subsection3'></a>Changes for 2.0
The following noteworthy changes have occurred:
1. The API for accessing attributes and their values has been simplified.
All functionality regarding the default attribute "data" has been removed.
This default attribute does not exist anymore. All accesses to attributes
have to specify the name of the attribute in question. This backward
*incompatible* change allowed us to simplify the signature of all methods
handling attributes.
Especially the flag __-key__ is not required anymore, even more, its use is
now forbidden. Please read the documentation for the methods __set__,
__get__, __getall__, __unset__, __append__, __lappend__, __keyexists__ and
__keys__ for a description of the new API's.
1. The methods __keys__ and __getall__ now take an optional pattern argument
and will return only attribute data for keys matching this pattern.
1. Nodes can now be renamed. See the documentation for the method __rename__.
1. The structure has been extended with API's for the serialization and
deserialization of tree objects, and a number of operations based on them
(tree assignment, copy construction).
Please read the documentation for the methods __serialize__,
__deserialize__, __=__, and __-->__, and the documentation on the
construction of tree objects.
Beyond the copying of whole tree objects these new API's also enable the
transfer of tree objects over arbitrary channels and for easy persistence.
1. The walker API has been streamlined and made more similar to the command
__[foreach](../../../../index.md#foreach)__. In detail:
- The superfluous option __-command__ has been removed.
- Ditto for the place holders. Instead of the placeholders two loop
variables have to be specified to contain node and action information.
- The old command argument has been documented as a script now, which it
was in the past too.
- The fact that __enter__ actions are called before the walker looks at
the children of a node has been documented now. In other words it is
now officially allowed to manipulate the list of children for a node
under *these* circumstances. It has been made clear that changes under
any other circumstances will have undefined results, from silently
computing the wrong result to erroring out.
1. A new method, __attr__, was added allowing the query and retrieval of
attribute data without regard to the node relationship.
1. The method __children__ has been extended with the ability to select from
the children of the node based on an arbitrary filtering criterium. Another
extension is the ability to look not only at the immediate children of the
node, but the whole tree below it.
# <a name='section3'></a>EXAMPLES
The following example demonstrates the creation of new nodes:
mytree insert root end 0 ; # Create node 0, as child of the root
mytree insert root end 1 2 ; # Ditto nodes 1 & 2
mytree insert 0 end 3 ; # Now create node 3 as child of node 0
mytree insert 0 end ; # Create another child of 0, with a
# generated name. The name is returned
# as the result of the command.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: tree* 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.
# <a name='keywords'></a>KEYWORDS
[breadth-first](../../../../index.md#breadth_first),
[depth-first](../../../../index.md#depth_first),
[in-order](../../../../index.md#in_order), [node](../../../../index.md#node),
[post-order](../../../../index.md#post_order),
[pre-order](../../../../index.md#pre_order),
[serialization](../../../../index.md#serialization),
[tree](../../../../index.md#tree)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002-2004,2012 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/struct/struct_tree1.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
|
[//000000001]: # (struct::tree_v1 - Tcl Data Structures)
[//000000002]: # (Generated from file 'struct_tree1.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::tree_v1(n) 1.2.2 tcllib "Tcl Data Structures")
# NAME
struct::tree_v1 - Create and manipulate tree objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require struct::tree ?1.2.2?
[__treeName__ __option__ ?*arg arg ...*?](#1)
[*treeName* __append__ *node* ?-key *key*? *value*](#2)
[*treeName* __children__ *node*](#3)
[*treeName* __cut__ *node*](#4)
[*treeName* __delete__ *node* ?*node* ...?](#5)
[*treeName* __depth__ *node*](#6)
[*treeName* __destroy__](#7)
[*treeName* __exists__ *node*](#8)
[*treeName* __get__ *node* ?__-key__ *key*?](#9)
[*treeName* __getall__ *node*](#10)
[*treeName* __keys__ *node*](#11)
[*treeName* __keyexists__ *node* ?-key *key*?](#12)
[*treeName* __index__ *node*](#13)
[*treeName* __insert__ *parent* *index* ?*child* ?*child* ...??](#14)
[*treeName* __isleaf__ *node*](#15)
[*treeName* __lappend__ *node* ?-key *key*? *value*](#16)
[*treeName* __move__ *parent* *index* *node* ?*node* ...?](#17)
[*treeName* __next__ *node*](#18)
[*treeName* __numchildren__ *node*](#19)
[*treeName* __parent__ *node*](#20)
[*treeName* __previous__ *node*](#21)
[*treeName* __set__ *node* ?__-key__ *key*? ?*value*?](#22)
[*treeName* __size__ ?*node*?](#23)
[*treeName* __splice__ *parent* *from* ?*to*? ?*child*?](#24)
[*treeName* __swap__ *node1* *node2*](#25)
[*treeName* __unset__ *node* ?__-key__ *key*?](#26)
[*treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? __-command__ *cmd*](#27)
# <a name='description'></a>DESCRIPTION
The __::struct::tree__ command creates a new tree object with an associated
global Tcl command whose name is *treeName*. This command may be used to invoke
various operations on the tree. It has the following general form:
- <a name='1'></a>__treeName__ __option__ ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
A tree is a collection of named elements, called nodes, one of which is
distinguished as a root, along with a relation ("parenthood") that places a
hierarchical structure on the nodes. (Data Structures and Algorithms; Aho,
Hopcroft and Ullman; Addison-Wesley, 1987). In addition to maintaining the node
relationships, this tree implementation allows any number of keyed values to be
associated with each node.
The element names can be arbitrary strings.
A tree is thus similar to an array, but with three important differences:
1. Trees are accessed through an object command, whereas arrays are accessed
as variables. (This means trees cannot be local to a procedure.)
1. Trees have a hierarchical structure, whereas an array is just an unordered
collection.
1. Each node of a tree has a separate collection of attributes and values.
This is like an array where every value is a dictionary.
The following commands are possible for tree objects:
- <a name='2'></a>*treeName* __append__ *node* ?-key *key*? *value*
Appends a *value* to one of the keyed values associated with an node. If no
*key* is specified, the key __data__ is assumed.
- <a name='3'></a>*treeName* __children__ *node*
Return a list of the children of *node*.
- <a name='4'></a>*treeName* __cut__ *node*
Removes the node specified by *node* from the tree, but not its children.
The children of *node* are made children of the parent of the *node*, at the
index at which *node* was located.
- <a name='5'></a>*treeName* __delete__ *node* ?*node* ...?
Removes the specified nodes from the tree. All of the nodes' children will
be removed as well to prevent orphaned nodes.
- <a name='6'></a>*treeName* __depth__ *node*
Return the number of steps from node *node* to the root node.
- <a name='7'></a>*treeName* __destroy__
Destroy the tree, including its storage space and associated command.
- <a name='8'></a>*treeName* __exists__ *node*
Returns true if the specified node exists in the tree.
- <a name='9'></a>*treeName* __get__ *node* ?__-key__ *key*?
Return the value associated with the key *key* for the node *node*. If no
key is specified, the key __data__ is assumed.
- <a name='10'></a>*treeName* __getall__ *node*
Returns a serialized list of key/value pairs (suitable for use with [__array
set__]) for the *node*.
- <a name='11'></a>*treeName* __keys__ *node*
Returns a list of keys for the *node*.
- <a name='12'></a>*treeName* __keyexists__ *node* ?-key *key*?
Return true if the specified *key* exists for the *node*. If no *key* is
specified, the key __data__ is assumed.
- <a name='13'></a>*treeName* __index__ *node*
Returns the index of *node* in its parent's list of children. For example,
if a node has *nodeFoo*, *nodeBar*, and *nodeBaz* as children, in that
order, the index of *nodeBar* is 1.
- <a name='14'></a>*treeName* __insert__ *parent* *index* ?*child* ?*child* ...??
Insert one or more nodes into the tree as children of the node *parent*. The
nodes will be added in the order they are given. If *parent* is __root__, it
refers to the root of the tree. The new nodes will be added to the *parent*
node's child list at the index given by *index*. The *index* can be __end__
in which case the new nodes will be added after the current last child.
If any of the specified children already exist in *treeName*, those nodes
will be moved from their original location to the new location indicated by
this command.
If no *child* is specified, a single node will be added, and a name will be
generated for the new node. The generated name is of the form *node*__x__,
where __x__ is a number. If names are specified they must neither contain
whitespace nor colons (":").
The return result from this command is a list of nodes added.
- <a name='15'></a>*treeName* __isleaf__ *node*
Returns true if *node* is a leaf of the tree (if *node* has no children),
false otherwise.
- <a name='16'></a>*treeName* __lappend__ *node* ?-key *key*? *value*
Appends a *value* (as a list) to one of the keyed values associated with an
*node*. If no *key* is specified, the key __data__ is assumed.
- <a name='17'></a>*treeName* __move__ *parent* *index* *node* ?*node* ...?
Make the specified nodes children of *parent*, inserting them into the
parent's child list at the index given by *index*. Note that the command
will take all nodes out of the tree before inserting them under the new
parent, and that it determines the position to place them into after the
removal, before the re-insertion. This behaviour is important when it comes
to moving one or more nodes to a different index without changing their
parent node.
- <a name='18'></a>*treeName* __next__ *node*
Return the right sibling of *node*, or the empty string if *node* was the
last child of its parent.
- <a name='19'></a>*treeName* __numchildren__ *node*
Return the number of immediate children of *node*.
- <a name='20'></a>*treeName* __parent__ *node*
Return the parent of *node*.
- <a name='21'></a>*treeName* __previous__ *node*
Return the left sibling of *node*, or the empty string if *node* was the
first child of its parent.
- <a name='22'></a>*treeName* __set__ *node* ?__-key__ *key*? ?*value*?
Set or get one of the keyed values associated with a node. If no key is
specified, the key __data__ is assumed. Each node that is added to a tree
has the value "" assigned to the key __data__ automatically. A node may have
any number of keyed values associated with it. If *value* is not specified,
this command returns the current value assigned to the key; if *value* is
specified, this command assigns that value to the key.
- <a name='23'></a>*treeName* __size__ ?*node*?
Return a count of the number of descendants of the node *node*; if no node
is specified, __root__ is assumed.
- <a name='24'></a>*treeName* __splice__ *parent* *from* ?*to*? ?*child*?
Insert a node named *child* into the tree as a child of the node *parent*.
If *parent* is __root__, it refers to the root of the tree. The new node
will be added to the parent node's child list at the index given by *from*.
The children of *parent* which are in the range of the indices *from* and
*to* are made children of *child*. If the value of *to* is not specified it
defaults to __end__. If no name is given for *child*, a name will be
generated for the new node. The generated name is of the form *node*__x__,
where __x__ is a number. The return result from this command is the name of
the new node.
- <a name='25'></a>*treeName* __swap__ *node1* *node2*
Swap the position of *node1* and *node2* in the tree.
- <a name='26'></a>*treeName* __unset__ *node* ?__-key__ *key*?
Removes a keyed value from the node *node*. If no key is specified, the key
__data__ is assumed.
- <a name='27'></a>*treeName* __walk__ *node* ?__-order__ *order*? ?__-type__ *type*? __-command__ *cmd*
Perform a breadth-first or depth-first walk of the tree starting at the node
*node*. The type of walk, breadth-first or depth-first, is determined by the
value of *type*; __bfs__ indicates breadth-first, __dfs__ indicates
depth-first. Depth-first is the default. The order of the walk, pre-, post-,
both- or in-order is determined by the value of *order*; __pre__ indicates
pre-order, __post__ indicates post-order, __both__ indicates both-order and
__in__ indicates in-order. Pre-order is the default.
Pre-order walking means that a parent node is visited before any of its
children. For example, a breadth-first search starting from the root will
visit the root, followed by all of the root's children, followed by all of
the root's grandchildren. Post-order walking means that a parent node is
visited after any of its children. Both-order walking means that a parent
node is visited before *and* after any of its children. In-order walking
means that a parent node is visited after its first child and before the
second. This is a generalization of in-order walking for binary trees and
will do the right thing if a binary is walked. The combination of a
breadth-first walk with in-order is illegal.
As the walk progresses, the command *cmd* will be evaluated at each node.
Percent substitution will be performed on *cmd* before evaluation, just as
in a __[bind](../../../../index.md#bind)__ script. The following
substitutions are recognized:
* __%%__
Insert the literal % character.
* __%t__
Name of the tree object.
* __%n__
Name of the current node.
* __%a__
Name of the action occurring; one of __enter__, __leave__, or __visit__.
__enter__ actions occur during pre-order walks; __leave__ actions occur
during post-order walks; __visit__ actions occur during in-order walks.
In a both-order walk, the command will be evaluated twice for each node;
the action is __enter__ for the first evaluation, and __leave__ for the
second.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *struct :: tree* 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.
# <a name='keywords'></a>KEYWORDS
[tree](../../../../index.md#tree)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2002 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/tar/tar.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
[//000000001]: # (tar - Tar file handling)
[//000000002]: # (Generated from file 'tar.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tar(n) 0.11 tcllib "Tar file handling")
# NAME
tar - Tar file creation, extraction & manipulation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require tar ?0.11?
[__::tar::contents__ *tarball* ?__-chan__?](#1)
[__::tar::stat__ *tarball* ?file? ?__-chan__?](#2)
[__::tar::untar__ *tarball* *args*](#3)
[__::tar::get__ *tarball* *fileName* ?__-chan__?](#4)
[__::tar::create__ *tarball* *files* *args*](#5)
[__::tar::add__ *tarball* *files* *args*](#6)
[__::tar::remove__ *tarball* *files*](#7)
# <a name='description'></a>DESCRIPTION
Note: Starting with version 0.8 the tar reader commands (contents, stats, get,
untar) support the GNU LongName extension (header type 'L') for large paths.
- <a name='1'></a>__::tar::contents__ *tarball* ?__-chan__?
Returns a list of the files contained in *tarball*. The order is not sorted
and depends on the order files were stored in the archive.
If the option __-chan__ is present *tarball* is interpreted as an open
channel. It is assumed that the channel was opened for reading, and
configured for binary input. The command will *not* close the channel.
- <a name='2'></a>__::tar::stat__ *tarball* ?file? ?__-chan__?
Returns a nested dict containing information on the named ?file? in
*tarball*, or all files if none is specified. The top level are pairs of
filename and info. The info is a dict with the keys "__mode__ __uid__
__gid__ __size__ __mtime__ __type__ __linkname__ __uname__ __gname__
__devmajor__ __devminor__"
% ::tar::stat tarball.tar
foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
If the option __-chan__ is present *tarball* is interpreted as an open
channel. It is assumed that the channel was opened for reading, and
configured for binary input. The command will *not* close the channel.
- <a name='3'></a>__::tar::untar__ *tarball* *args*
Extracts *tarball*. *-file* and *-glob* limit the extraction to files which
exactly match or pattern match the given argument. No error is thrown if no
files match. Returns a list of filenames extracted and the file size. The
size will be null for non regular files. Leading path seperators are
stripped so paths will always be relative.
* __-dir__ dirName
Directory to extract to. Uses __pwd__ if none is specified
* __-file__ fileName
Only extract the file with this name. The name is matched against the
complete path stored in the archive including directories.
* __-glob__ pattern
Only extract files patching this glob style pattern. The pattern is
matched against the complete path stored in the archive.
* __-nooverwrite__
Dont overwrite files that already exist
* __-nomtime__
Leave the file modification time as the current time instead of setting
it to the value in the archive.
* __-noperms__
In Unix, leave the file permissions as the current umask instead of
setting them to the values in the archive.
* __-chan__
If this option is present *tarball* is interpreted as an open channel.
It is assumed that the channel was opened for reading, and configured
for binary input. The command will *not* close the channel.
% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
puts "Extracted $file ($size bytes)"
}
- <a name='4'></a>__::tar::get__ *tarball* *fileName* ?__-chan__?
Returns the contents of *fileName* from the *tarball*.
% set readme [::tar::get tarball.tar doc/README] {
% puts $readme
}
If the option __-chan__ is present *tarball* is interpreted as an open
channel. It is assumed that the channel was opened for reading, and
configured for binary input. The command will *not* close the channel.
An error is thrown when *fileName* is not found in the tar archive.
- <a name='5'></a>__::tar::create__ *tarball* *files* *args*
Creates a new tar file containing the *files*. *files* must be specified as
a single argument which is a proper list of filenames.
* __-dereference__
Normally __create__ will store links as an actual link pointing at a
file that may or may not exist in the archive. Specifying this option
will cause the actual file point to by the link to be stored instead.
* __-chan__
If this option is present *tarball* is interpreted as an open channel.
It is assumed that the channel was opened for writing, and configured
for binary output. The command will *not* close the channel.
% ::tar::create new.tar [glob -nocomplain file*]
% ::tar::contents new.tar
file1 file2 file3
- <a name='6'></a>__::tar::add__ *tarball* *files* *args*
Appends *files* to the end of the existing *tarball*. *files* must be
specified as a single argument which is a proper list of filenames.
* __-dereference__
Normally __add__ will store links as an actual link pointing at a file
that may or may not exist in the archive. Specifying this option will
cause the actual file point to by the link to be stored instead.
* __-prefix__ string
Normally __add__ will store files under exactly the name specified as
argument. Specifying a ?-prefix? causes the *string* to be prepended to
every name.
* __-quick__
The only sure way to find the position in the *tarball* where new files
can be added is to read it from start, but if *tarball* was written with
a "blocksize" of 1 (as this package does) then one can alternatively
find this position by seeking from the end. The ?-quick? option tells
__add__ to do the latter.
- <a name='7'></a>__::tar::remove__ *tarball* *files*
Removes *files* from the *tarball*. No error will result if the file does
not exist in the tarball. Directory write permission and free disk space
equivalent to at least the size of the tarball will be needed.
% ::tar::remove new.tar {file2 file3}
% ::tar::contents new.tar
file3
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tar* 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.
# <a name='keywords'></a>KEYWORDS
[archive](../../../../index.md#archive), [tape
archive](../../../../index.md#tape_archive), [tar](../../../../index.md#tar)
# <a name='category'></a>CATEGORY
File formats
|
Added embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
|
[//000000001]: # (tepam::argument_dialogbox - Tcl's Enhanced Procedure and Argument Manager)
[//000000002]: # (Generated from file 'tepam_argument_dialogbox.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tepam::argument_dialogbox(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager")
# NAME
tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [ARGUMENT DIALOGBOX CALL](#section2)
- [Context Definition Items](#subsection1)
- [Formatting and Display Options](#subsection2)
- [Global Custom Data Validation](#subsection3)
- [Data Entry Widget Items](#subsection4)
- [Entry Widget Item Attributes](#subsection5)
- [APPLICATION SPECIFIC ENTRY WIDGETS](#section3)
- [VARIABLES](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require Tk 8.3
package require tepam ?0.5?
[__tepam::argument_dialogbox__ *item_name item_attributes ?item_name item_attributes? ?...?*](#1)
[__tepam::argument_dialogbox__ {*item_name item_attributes ?item_name item_attributes? ?...?*}](#2)
# <a name='description'></a>DESCRIPTION
# <a name='section2'></a>ARGUMENT DIALOGBOX CALL
The TEPAM __argument_dialogbox__ is a flexible and easily usable data entry form
generator that is available if Tk has been loaded. Each data entry element of a
form is defined via a *data entry item* that can be provided to
__argument_dialogbox__ in two formats:
- <a name='1'></a>__tepam::argument_dialogbox__ *item_name item_attributes ?item_name item_attributes? ?...?*
Using this first format, each *data entry item* is defined via a pair of two
arguments. The first one is the *item name* that defines the entry widget
that has to be used in the form. The second argument, called *item
attributes*, specifies the variable which is attributed to the data entry
element as well as eventual formatting and context information.
The __argument_dialogbox__ returns __ok__ if the entered data have been
acknowledged (via the *OK* button) and validated by a data checker. If the
entered data have been rejected (via the *Cancel* button) the
__argument_dialogbox__ returns __cancel__.
A small example illustrates how the __argument_dialogbox__ can be employed:
set DialogResult [__tepam::argument_dialogbox__ \
__-title__ "Itinerary selection" \
__-file__ {*-label "Itinerary report" -variable report_file*} \
__-frame__ {*-label "Itinerary start"*} \
__-comment__ {*-text "Specify your itinerary start location"*} \
__-entry__ {*-label "City" -variable start_city -type string*} \
__-entry__ {*-label "Street" -variable start_street -type string -optional 1*} \
__-entry__ {*-label "Street number" -variable start_street_nbr -type integer -optional 1*} \
__-frame__ {*-label "Itinerary destination"*} \
__-comment__ {*-text "Specify your itinerary destination"*} \
__-entry__ {*-label "City" -variable dest_city -type string*} \
__-entry__ {*-label "Street" -variable dest_street -type string -optional 1*} \
__-entry__ {*-label "Street number" -variable dest_street_nbr -type integer -optional 1*} \
__-frame__ {} \
__-checkbutton__ {*-label "Don't use highways" -variable no_highway*}
] This example opens a dialog box that has the title *Itinerary selection*.
A first entry widget in this box allows selecting a report file. It follows
two frames to define respectively an itinerary start and end location. Each
of these locations that are described with a comment has three entry widgets
to specify respectively the city, street and the street number. Bellow the
second frame there is a check button that allows specifying if eventual
highways should be ignored.
- <a name='2'></a>__tepam::argument_dialogbox__ {*item_name item_attributes ?item_name item_attributes? ?...?*}
Sometimes it is simpler to provide all the data entry item definitions in
form of a single list to __argument_dialogbox__, and not as individual
arguments. The second format that is supported by __argument_dialogbox__
corresponds exactly to the first one, except that all item definitions are
packed into a single list that is provided to __argument_dialogbox__. The
previous example can therefore also be written in the following way:
set DialogResult [__tepam::argument_dialogbox {__
__-title__ "Itinerary selection"
__-file__ {*-label "Itinerary report" -variable report_file*}
...
__-checkbutton__ {*-label "Don't use highways" -variable no_highway*}
__}__]
The commands __argument_dialogbox__ as well as
__[procedure](../../../../index.md#procedure)__ are exported from the namespace
__tepam__. To use these commands without the __tepam::__ namespace prefix, it is
sufficient to import them into the main namespace:
__namespace import tepam::*__
set DialogResult [__argument_dialogbox__ \
-title "Itinerary selection"
...
The following subsections explain the different argument item types that are
accepted by the __argument_dialogbox__, classified into three groups. The first
data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument_dialogbox__.
## <a name='subsection1'></a>Context Definition Items
The first item group allows specifying some context aspects of an argument
dialog box. These items are taking a simple character string as item attribute:
tepam::argument_dialogbox \
__-<argument_name>__ *string* \
...
The following items are classified into this group:
- -title *string*
The dialog box window title which is by default *Dialog* can be changed with
the *-title* item:
tepam::argument_dialogbox \
__-title__ "System configuration" \
...
- -window *string*
The argument dialog box uses by default *.dialog* as dialog top level
window. This path can be changed with the *-window* item:
tepam::argument_dialogbox \
__-window__ .dialog \
...
- -parent *string*
By defining a parent window, the argument dialog box will be displayed
beside this one. Without explicit parent window definition, the top-level
window will be considered as parent window.
tepam::argument_dialogbox \
__-parent__ .my_appl \
...
- -context *string*
If a context is defined the dialog box state, e.g. the entered data as well
as the window size and position, is restored the next time the argument
dialog box is called. The assignment of a context allows saving the dialog
box state in its context to distinguish between different usages of the
argument dialog box.
tepam::argument_dialogbox \
__-context__ destination_definitions \
...
## <a name='subsection2'></a>Formatting and Display Options
Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user. A couple of items allow structuring
and commenting the dialog boxes.
The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:
tepam::argument_dialogbox \
...
__-<argument_name>__ { *
?-<attribute_name> <attribute_value>?
?-<attribute_name> <attribute_value>?
?...?*
}
...
The following items are classified into this group:
- -frame *list*
The *-frame* item allows packing all following entry widgets into a labeled
frame, until a next frame item is defined or until the last entry widget has
been defined. It recognizes the following attributes inside the item
attribute list:
* -label *string*
An optional frame label can be specified with the *-label* statement.
Example:
tepam::argument_dialogbox \
...
__-frame__ {*-label "Destination address"*}
...
To close an open frame without opening a new one, an empty list has to be
provided to the *-frame* statement.
tepam::argument_dialogbox \
...
__-frame__ {}
...
- -sep [const {{}}]
Entry widgets can be separated with the *-sep* statement which doesn't
require additional definitions. The related definition list has to exist,
but its content is ignored.
tepam::argument_dialogbox \
...
__-sep__ {}
...
- -comment *string*
Comments and descriptions can be added with the *-text* attribute of the
*-comment* item. Please note that each entry widget itself can also contain
a *-text* attribute for comments and descriptions. But the *-comment* item
allows for example adding a description between two frames.
tepam::argument_dialogbox \
...
__-comment__ {*-text "Specify bellow the destination address"*}
...
- -yscroll __0__|__1__|__auto__
This attribute allows controlling an eventual vertical scrollbar. Setting it
to __0__ will permanently disable the scrollbar, setting it to __1__ will
enable it. By default it is set to __auto__. The scrollbar is enabled in
this mode only if the vertical data entry form size exceeds 66% of the
screen height.
tepam::argument_dialogbox \
...
__-yscroll__ __auto__
...
## <a name='subsection3'></a>Global Custom Data Validation
This item group allows specifying global custom checks to validate the entered
data.
- -validatecommand *script*
Custom data checks can be performed via validation commands that are defined
with the *-validatecommand* item. Example:
tepam::argument_dialogbox \
-entry {-label "Your comment" -variable YourCom} \
__-validatecommand__ {IllegalWordDetector $YourCom}
The validation command is executed in the context of the calling procedure,
once all the basic data checks have been performed and data variables are
assigned. All data is accessed via the data variables. Note that there is
also an entry widget specific attribute *-validatecommand* that allows
declaring custom checks for specific data entries.
The attribute *-validatecommand* can be repeated to declare multiple custom
checks.
- -validatecommand_error_text *string*
This item allows overriding the default error message for a global custom
argument validation (defined by *-validatecommand*). Also this attribute can
be repeated in case multiple checks are declared.
- -validatecommand2 *script*
- -validatecommand2_error_text *string*
These items are mainly for TEPAM internal usage.
These items corrspond respectively to *-validatecommand* and
*-validatecommand_error_text*. However, the data validation is not performed
in the next upper stack level, but two stack levels higher.
## <a name='subsection4'></a>Data Entry Widget Items
Data entry widgets are created with the widget items. These items require as
item attributes a definition list, which contains itself attribute name and
value pairs:
tepam::argument_dialogbox \
...
__-<argument_name>__ { *
?-<attribute_name> <attribute_value>?
?-<attribute_name> <attribute_value>?
?...?*
}
...
The attribute list can contain various attributes to describe and comment an
entry widget and to constrain its entered value. All entry widgets are accepting
a common set of attributes that are described in the section [Entry Widget Item
Attributes](#subsection5).
TEPAM defines a rich set of entry widgets. If necessary, this set can be
extended with additional application specific entry widgets (see [APPLICATION
SPECIFIC ENTRY WIDGETS](#section3)):
- -entry *list*
The *-entry* item generates the simplest but most universal data entry
widget. It allows entering any kind of data in form of single line strings.
tepam::argument_dialogbox \
__-entry__ {-label Name -variable Entry}
- -text *list*
The *-text* item generates a multi line text entry widget. The widget height
can be selected with the *-height* attribute.
tepam::argument_dialogbox \
__-text__ {-label Name -variable Text -height 5}
- -checkbox *list*
A group of check boxes is created with the *-checkbox* item. The number of
check boxes and their option values are specified with a list assigned to
the *-choices* attribute or via a variable declared with the
*-choicevariable* attribute:
tepam::argument_dialogbox \
__-checkbox__ {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} -default italic}
If the labels of the check boxes should differ from the option values, their
labels can be defined with the *-choicelabels* attribute:
tepam::argument_dialogbox \
__-checkbox__ {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} \
-choicelabels {Bold Italic Underline} \
-default italic}
In contrast to a radio box group, a check box group allows selecting
simultaneously several choice options. The selection is stored for this
reason inside the defined variable in form of a list, even if only one
choice option has been selected.
- -radiobox *list*
A group of radio boxes is created with the *-radiobox* item. The number of
radio boxes and their option values are specified with a list assigned to
the *-choices* attribute or via a variable declared with the
*-choicevariable* attribute.
In contrast to a check box group, a radio box group allows selecting
simultaneously only one choice option. The selected option value is stored
directly, and not in form of a list, inside the defined variable.
tepam::argument_dialogbox \
__-radiobox__ {-label "Text adjustment" -variable Adjustment \
-choices {left center right} -default left}
If the labels of the radio boxes should differ from the option values, their
labels can be defined with the *-choicelabels* attribute:
tepam::argument_dialogbox \
__-radiobox__ {-label "Text adjustment" -variable Adjustment \
-choices {left center right} \
-choicelabels {Left Center Right} -default left}
- -checkbutton *list*
The *-checkbutton* entry widget allows activating or deactivating a single
choice option. The result written into the variable will either be __0__ if
the check button was not activated or __1__ if it was activated. An
eventually provided default value has also to be either __0__ or __1__.
tepam::argument_dialogbox \
__-checkbutton__ {-label Capitalize -variable Capitalize -default 1}
Several types of list and combo boxes are available to handle selection lists.
- -combobox *list*
The combobox is a combination of a normal entry widget together with a
drop-down list box. The combobox allows selecting from this drop-down list
box a single element. The list of the available elements can be provided
either as a list to the *-choices* attribute, or via a variable that is
specified with the *-choicevariable* attribute.
tepam::argument_dialogbox \
__-combobox__ {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}
And here is an example of using a variable to define the selection list:
set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
__-combobox__ {-label "Text size" -variable Size -choicevariable TextSizes -default 12}
- -listbox *list*
In contrast to the combo box, the list box is always displayed by the
*listbox* entry widget. Only one element is selectable unless the
*-multiple_selection* attribute is set. The list box height can be selected
with the *-height* attribute. If the height is not explicitly defined, the
list box height is automatically adapted to the argument dialog box size.
The first example uses a variable to define the available choices:
set set AvailableSizes
for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
tepam::argument_dialogbox \
__-listbox__ {-label "Distance" -variable Distance \
-choicevariable AvailableSizes -default 6 -height 5}
Here is a multi-element selection example. Please note that also the default
selection can contain multiple elements:
tepam::argument_dialogbox \
__-listbox__ {-label "Text styles" -variable Styles \
-choices {bold italic underline overstrike} \
-choicelabels {Bold Italic Underline Overstrike} \
-default {bold underline} -multiple_selection 1 \
-height 3}
- -disjointlistbox *list*
A disjoint list box has to be used instead of a normal list box if the
selection order is important. The disjoint list box entry widget has in fact
two list boxes, one to select elements and one to display the selected
elements in the chosen order.
Disjoint listboxes allow always selecting multiple elements. With the
exception of the *-multiple_selection* attribute, disjointed list boxes are
accepting the same attributes as the normal listbox, e.g. *-height,
-choices, -choicevariable, -default*.
tepam::argument_dialogbox \
__-disjointlistbox__ {-label "Preferred scripting languages" -variable Languages \
-comment "Please select your preferred languages in the order" \
-choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
-default {Tcl Perl Python}}
The file and directory selectors are building a next group of data entry
widgets. A paragraph of section [Entry Widget Item Attributes](#subsection5)
explains the widget specific attributes that allow specifying the targeted file
types, active directory etc.
- -file *list*
The item *-file* creates a group composed by an entry widget together with a
button that allows opening a file browser. The data type *file* is
automatically selected for this entry if no data type has been explicitly
defined with the *-type* attribute.
tepam::argument_dialogbox \
__-file__ {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
-initialfile "picture.gif"}
- -existingfile *list*
The item *-existingfile* creates a group composed by an entry widget
together with a button that allows opening a browser to select an existing
file. The data type *existingfile* is automatically selected for this entry
if no data type has been explicitly defined with the *-type* attribute.
tepam::argument_dialogbox \
__-existingfile__ {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
-initialfile "picture.gif"}
- -directory *list*
The item *-directory* creates a group composed by an entry widget together
with a button that allows opening a directory browser. The data type
*directory* is automatically selected for this entry if no data type has
been explicitly defined with the *-type* attribute.
tepam::argument_dialogbox \
__-directory__ {-label "Report directory" -variable ReportDir}
- -existingdirectory *list*
The item *-existingdirectory* creates a group composed by an entry widget
together with a button that allows opening a browser to select an existing
directory. The data type *existingdirectory* is automatically selected for
this entry if no data type has been explicitly defined with the *-type*
attribute.
tepam::argument_dialogbox \
__-existingdirectory__ {-label "Report directory" -variable ReportDir}
Finally, there is a last group of some other special data entry widgets.
- -color *list*
The color selector is composed by an entry widget together with a button
that allows opening a color browser. The data type *color* is automatically
selected for this entry widget type if no data type has been explicitly
defined with the *-type* attribute.
tepam::argument_dialogbox \
__-color__ {-label "Background color" -variable Color -default red}
- -font *list*
The font selector is composed by an entry widget together with a button that
allows opening a font browser. The data type *font* is automatically
selected for this entry widget type if no data type has been explicitly
defined with the *-type* attribute. The entry widget displays an example
text in the format of the selected font.
The font browser allows selecting by default the font families provided by
the __font families__ Tk command as well as a reasonable set of different
font sizes between 6 points and 40 points. Different sets of font families
and font sizes can be specified respectively via the *-font_families* or
*-font_sizes* attributes.
If no default font is provided via the *-default* attribute, the default
font of the label widget to display the selected font will be used as
default selected font. If the font family of this label widget is not part
of the available families the first available family is used as default. If
the font size of this label widget is not part of the available sizes the
next close available size is selected as default size.
tepam::argument_dialogbox \
__-font__ {-label "Font" -variable Font \
-font_sizes {8 10 12 16} \
-default {Arial 20 italic}}
## <a name='subsection5'></a>Entry Widget Item Attributes
All the entry widget items are accepting the following attributes:
- -text *string*
Eventual descriptions and comments specified with the *-text* attribute are
displayed above the entry widget.
tepam::argument_dialogbox \
-entry {__-text "Please enter your name bellow"__ -variable Name}
- -label *string*
The label attribute creates left to the entry widget a label using the
provided string as label text:
tepam::argument_dialogbox \
-entry {__-label Name__ -variable Name}
- -variable *string*
All entry widgets require a specified variable. After accepting the entered
information with the OK button, the entry widget data is stored inside the
defined variables.
tepam::argument_dialogbox \
-existingdirectory {-label "Report directory" __-variable ReportDir__}
- -default *string*
Eventual default data for the entry widgets can be provided via the
*-default* attribute. The default value is overridden if an argument dialog
box with a defined context is called another time. The value acknowledged in
a previous call will be used in this case as default value.
tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} __-default italic__}
- -optional __0__|__1__
Data can be specified as optional or mandatory with the *-optional*
attribute that requires either __0__ (mandatory) or __1__ (optional) as
attribute data.
In case an entry is optional and no data has been entered, e.g. the entry
contains an empty character string, the entry will be considered as
undefined and the assigned variable will not be defined.
tepam::argument_dialogbox \
-entry {-label "City" -variable start_city -type string} \
-entry {-label "Street" -variable start_street -type string __-optional 0__} \
-entry {-label "Street number" -variable start_street_nbr -type integer __-optional 1__} \
- -type *string*
If the data type is defined with the *-type* attribute the argument dialog
box will automatically perform a data type check after acknowledging the
entered values and before the dialog box is closed. If a type incompatible
value is found an error message box appears and the user can correct the
value.
The argument dialog box accepts all types that have been specified by the
TEPAM package and that are also used by
__[tepam::procedure](tepam_procedure.md)__ (see the *tepam::procedure
reference manual*).
Some entry widgets like the file and directory widgets, as well as the color
and font widgets are specifying automatically the default data type if no
type has been specified explicitly with the *-type* attribute.
tepam::argument_dialogbox \
__-entry__ {-label "Street number" -variable start_street_nbr __-type integer__} \
- -range *string*
Values can be constrained with the *-range* attribute. The valid range is
defined with a list containing the minimum valid value and a maximum valid
value.
The *-range* attribute has to be used only for numerical arguments, like
integers and doubles.
tepam::argument_dialogbox \
-entry {-label Month -variable Month -type integer __-range {1 12}__}
- -validatecommand *string*
Custom argument value validations can be performed via specific validation
commands that are defined with the *-validatecommand* attribute. The
provided validation command can be a complete script in which the pattern
*%P* is placeholder for the argument value that has to be validated.
tepam::argument_dialogbox \
-entry {-label "Your comment" -variable YourCom \
__-validatecommand__ "IllegalWordDetector %P"}
While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global data validation
attribute *-validatecommand* that allows performing validation that involves
multiple arguments.
- -validatecommand_error_text *string*
This attribute allows overriding the default error message for a custom
argument validation (defined by *-validatecommand*).
Some other attributes are supported by the list and combo boxes as well as by
the radio and check buttons.
- -choices *string*
Choice lists can directly be defined with the *-choices* attribute. This way
to define choice lists is especially adapted for smaller, fixed selection
lists.
tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
__-choices {bold italic underline}__ -default underline
- -choicelabels *string* *(only check and radio buttons)*
If the labels of the check and radio boxes should differ from the option
values, they can be defined with the *-choicelabels* attribute:
tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} \
__-choicelabels {Bold Italic Underline}__
- -choicevariable *string*
Another way to define the choice lists is using the *-choicevariable*
attribute. This way to define choice lists is especially adapted for huge
and eventually variable selection lists.
set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
-combobox {-label "Text size" -variable Size __-choicevariable TextSizes__}
- -multiple_selection __0__|__1__
The list box item (__-listbox__) allows by default selecting only one list
element. By setting the *-multiple_selection* attribute to __1__, multiple
elements can be selected.
tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
-choices {bold italic underline} -default underline \
__-multiple_selection 1__ -height 3}
Some additional attributes are supported by the file and directory selection
widgets.
- -filetypes *string*
The file type attribute is used by the __-file__ and __-existingfile__ items
to define the file endings that are searched by the file browser.
tepam::argument_dialogbox \
-file {-label "Image file" -variable ImageF \
__-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}__}
- -initialfile *string*
The initial file used by the file browsers of the __-file__ and
__-existingfile__ widgets are by default the file defined with the
*-default* attribute, unless a file is specified with the *-initialfile*
attribute.
tepam::argument_dialogbox \
-file {-variable ImageF __-initialfile "picture.gif"__}
- -activedir *string*
The *-activedir* attribute will override the default active search directory
used by the file browsers of all file and directory entry widgets. The
default active search directory is defined by the directory of a specified
initial file (*-initialfile*) if defined, and otherwise by the directory of
the default file/directory, specified with the *-default* attribute.
tepam::argument_dialogbox \
-file "-variable ImageF __-activedir $pwd__"
Finally, there is a last attribute supported by some widgets:
- -height *string*
All widgets containing a selection list (__-listbox__, __-disjointlistbox__,
__-font__) as well as the multi line __-text__ widget are accepting the
*-height* attribute that defines the number of displayed rows of the
selection lists.
tepam::argument_dialogbox \
-listbox {-label "Text size" -variable Size \
-choices {8 9 10 12 15 18} -default 12 __-height 3__}
If the no height has been explicitly specified the height of the widget will
be dynamically adapted to the argument dialog box size.
# <a name='section3'></a>APPLICATION SPECIFIC ENTRY WIDGETS
An application specific entry widget can be made available to the argument
dialog box by adding a dedicated procedure to the __tepam__ namespace. This
procedure has three arguments; the first one is the widget path, the second one
a subcommand and the third argument has various purposes:
*proc* tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
*upvar Option Option; # if required*
*variable argument_dialogbox; # if required*
switch $Command {
"create" <CreateCommandSequence>
"set_choice" <SetChoiceCommandSequence>
"set" <SetCommandv>
"get" <GetCommandSequence>
}
}
__Argument_dialogbox__ takes care about the *-label* and *-text* attributes for
all entry widgets. For any data entry widget it creates a frame into which the
data entry widget components can be placed. The path to this frame is provided
via the *W* argument.
The entry widget procedure has to support 3 mandatory and an optional command
that are selected via the argument *Command*:
- *create*
The entry widget is called a first time with the command *create* to build
the data entry widget.
The frames that are made available by __argument_dialogbox__ for the entry
widgets are by default only extendable in the X direction. To make them also
extendable in the Y direction, for example for extendable list boxes, the
command __ad_form(make_expandable) $W__ has to be executed when an entry
widget is built.
- *set_choice*
The entry widget procedure is only called with the *set_choice* command if
the *-choices* or *-choicevariable* has been specified. The command is
therefore only relevant for list and combo boxes.
The available selection list that is either specified with the *-choices* or
*-choicevariable* attribute is provided via the *Par* argument to the entry
widget procedure. This list can be used to initialize an available choice
list.
- *set*
If a default value is either defined via the *-default* attribute or via a
preceding call the entry widget procedure is called with the *set* command.
The argument *Par* contains in this case the value to which the entry widget
has to be initialized.
- *get*
The entry widget procedure command *get* has to return the current value of
the entry widget.
Eventually specified entry widget item attributes are available via the
__Option__ array variable of the calling procedure. This variable becomes
accessible inside the entry widget procedure via the __upvar__ command.
There may be a need to store some information in a variable. The array variable
__argument_dialogbox__ has to be used for this purpose together with array
indexes starting with *"$W,"*, e.g. *argument_dialogbox($W,values)*.
Examples of entry widget procedures are directly provided by the TEPAM package
source file that specifies the standard entry widget procedures. The simplest
procedure is the one for the basic *entry* widget:
proc tepam::ad_form(entry) {W Command {Par ""}} {
switch $Command {
"create" {pack [entry \$W.entry] -fill x \
-expand yes -pady 4 -side left}
"set" {\$W.entry insert 0 $Par}
"get" {return [\$W.entry get]}
}
}
It is also possible to relay on an existing entry widget procedure to derive a
new, more specific one. The *radiobox* widget is used for example, to create a
new entry widget that allows selecting either *left*, *center* or *right*. The
original *radiobox* widget is called with the *set_choice* command immediately
after the *create* command, to define the fixed list of selection options.
proc tepam::ad_form(rcl) {W Command {Par ""}} {
set Res [ad_form(radiobox) $W $Command $Par]
if {$Command=="create"} {
ad_form(radiobox) $W set_choice {left center right}
}
return $Res
}
Please consult the TEPAM package source file to find additional and more complex
examples of entry widget procedures.
# <a name='section4'></a>VARIABLES
The __argument_dialogbox__ is using two variables inside the namespace
__::tepam__:
- __argument_dialogbox__
Application specific entry widget procedures can use this array variable to
store their own data, using as index the widget path provided to the
procedure, e.g. *argument_dialogbox($W,<sub_index>)*.
- __last_parameters__
This array variable is only used by an argument dialog box if its context
has been specified via the *-context* attribute. The argument dialog box
position and size as well as its entered data are stored inside this
variable if the data are acknowledged and the form is closed. This allows
the form to restore its previous state once it is called another time.
To reuse the saved parameters not just in the actual application session but
also in another one, it is sufficient to store the __last_parameter__ array
variable contents in a configuration file which is loaded the next time an
application is launched.
# <a name='see-also'></a>SEE ALSO
[tepam(n)](tepam_introduction.md), [tepam::procedure(n)](tepam_procedure.md)
# <a name='keywords'></a>KEYWORDS
[data entry form](../../../../index.md#data_entry_form), [parameter entry
form](../../../../index.md#parameter_entry_form)
# <a name='category'></a>CATEGORY
Argument entry form, mega widget
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2013, Andreas Drollinger
|
Added embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
|
[//000000001]: # (tepam::doc_gen - Tcl's Enhanced Procedure and Argument Manager)
[//000000002]: # (Generated from file 'tepam_doc_gen.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tepam::doc_gen(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager")
# NAME
tepam::doc_gen - TEPAM DOC Generation, reference manual
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [ARGUMENTS](#section2)
- [PREDEFINED DOCUMENT FORMATS](#section3)
- [TXT - Text format](#subsection1)
- [HTML - HTML format](#subsection2)
- [POD - Perl document format](#subsection3)
- [DT - TclLib DocTools format](#subsection4)
- [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4)
- [EXAMPLES](#section5)
- [tepam::doc_gen::generate](#subsection5)
- [tepam::doc_gen::patch](#subsection6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require tepam 0.5
package require tepam::doc_gen ?0.1?
[__tepam::doc_gen::generate__ ?-format *format*? ?-style *style*? ?-header_footer? ?-dest_file *dest_file*? *name*](#1)
[__tepam::doc_gen::patch__ ?-format *format*? ?-style *style*? ?-search_pattern *search_pattern*? ?-src_string *src_string* | -src_file *src_file*? ?-dest_file *dest_file*? ?name?](#2)
# <a name='description'></a>DESCRIPTION
This package generates documentations of TEPAM procedures (procedures that have
been declared with __[tepam::procedure](tepam_procedure.md)__). The documents
are generated in the classic UNIX document style using the following document
sections: Name, Synopsis, Description, Arguments and Example. __TEPAM Doc Gen__
provides support for various document formats. Support for additional formats
can be added if necessary.
The __TEPAM Doc Gen__ package provides the following commands:
- <a name='1'></a>__tepam::doc_gen::generate__ ?-format *format*? ?-style *style*? ?-header_footer? ?-dest_file *dest_file*? *name*
This command generates the documentation for a specified procedure (*name*)
in one of the supported formats (TXT, HTML, POD (Perl Doc), DT (TclLib
DocTool), or in a custom specific format. The format is specified via
?format?. The flag ?-header_footer? adds to the documentation file header
and footer. If ?dest_file? is specified the documentation is stored in a
file (the file header and footer are added automatically in this case) and
the file name is returned. Otherwise the documentation string is returned by
__generate__.
- <a name='2'></a>__tepam::doc_gen::patch__ ?-format *format*? ?-style *style*? ?-search_pattern *search_pattern*? ?-src_string *src_string* | -src_file *src_file*? ?-dest_file *dest_file*? ?name?
This command inserts procedure documentations into an existing master
document at the locations indicated by insertion placeholders which are
matching the pattern of ?search_pattern?. The existing master document is
either provided as data to the argument (?src_string?) or via a file
(?src_file?). The final document is returned by
__[patch](../../../../index.md#patch)__ if no destination file is defined
(?dest_file?). Otherwise, the document is stored in the specified file, and
the number of insertion placeholders that could be handled successfully is
returned.
Any insertion placeholders of the master document are handled by default. By
defining the argument ?name? the documentation insertion will be restricted
to a particular procedure.
# <a name='section2'></a>ARGUMENTS
- ?-format *format*?
Specifies the documentation format. __TEPAM Doc Gen__ provides support for
the following formats:
TXT - Text format (default)
HTML
POD - Perl Plain Old Documentation format (PerlPOD)
DT - TclLib DocTool format
Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how
support for additional formats can be added.
- ?-style *style*?
The documentation is by default generated in Tcl style (e.g. __command arg1
arg2 ...__). C-style documentation can be generated by setting this argument
to 'C' (e.g. __command(arg1,arg2,...)__).
- ?-dest_file *dest_file*?
If ?dest_file? is defined the documentation is written into the specified
destination file. Otherwise the documentation string is returned by the
commands __generate__ and __[patch](../../../../index.md#patch)__.
- *name* / ?name?
This is the name of the procedure for which the documentation has to be
generated. This is a mandatory argument for __generate__, but an optional
argument for __[patch](../../../../index.md#patch)__.
- ?-header_footer?
__Generate__ adds to the generated procedure documentation the file header
and footer only if a file is generated. By selecting the flag
?-header_footer? the header and footer are also generated if the
documentation is returned as string by __generate__.
- ?-src_string *src_string* | -src_file *src_file*?
__[Patch](../../../../index.md#patch)__ inserts procedure documentations
into an existing document that is either provided as string to the argument
(?src_string?) or as a file (?src_file?). One of these two arguments need to
be specified.
- ?-search_pattern *search_pattern*?
The argument ?search_pattern? defines the documentation insertion
placeholder used in a document. It is a regular expression accepted by
__regexp__ and needs to contain a parenthesized sub-expression that contains
the procedure name for which the documentation needs to be inserted.
The default insertion placeholder pattern is *\{!(.*?)!\}*, which means that
the procedure name will be embedded between *{!* and *!}*. The section
[EXAMPLES](#section5) contains a custom insertion placeholder pattern
example.
# <a name='section3'></a>PREDEFINED DOCUMENT FORMATS
__TEPAM Doc Gen__ pre-defines the following document formats:
## <a name='subsection1'></a>TXT - Text format
The documentation will be generated in a simple text format if this format is
selected. The format can be customized via the following variable:
- __tepam::doc_gen::Option(TXT,MaxLineLength)__
Default: 80
This variable defines the line wrapping limit (character position).
## <a name='subsection2'></a>HTML - HTML format
__TEPAM Doc Gen__ generates CSS styled HTML files. The HTML documentation can be
customized via the following variable:
- __tepam::doc_gen::Option(HTML,CssFile)__
Default: "tepam_doc_stylesheet.css"
This variable specifies the CSS stylesheet file that is referred by the
generated HTML files.
The CSS stylesheet can be customized to change the documentation formatting. A
good starting point to create a customized CSS stylesheet is to use the CSS file
provided by the __TEPAM Doc Gen__ example/demo. The HTML documentation uses the
following CSS class styles:
- *h1.tepam_page_title* - Document page title. Only used by __generate__ if a
file is created or if the header and footer are built (flag ?-header_footer?
selected).
- *div.tepam_command_help* - Documentation container. The entire procedure
documentation is placed inside this container.
- *p.tepam_section_title* - Section title (e.g. *Name*, *Synopsis*,
*Description*, ...)
- *p.tepam_sub_section_title* - Sub-section title (used to separate the
documentation of multiple sub-procedures)
- *p.tepam_name* - Name section
- *p.tepam_synopsis* - Synopsis section
- *p.tepam_description* - Single description paragraph
- *ul.tepam_description_list* - Item of a HTML bulleted/unordered list inside
the description section
- *dt.tepam_argument* - Item of a HTML description list used to list the
procedure arguments
- *p.tepam_argument_description* - Argument description paragraph
- *p.tepam_argument_attribute* - Argument attribute line
- *pre.tepam_example* - Example section
## <a name='subsection3'></a>POD - Perl document format
The documentation is generated in the Perl Plain Old Documentation format
(PerlPOD) if this format is selected.
## <a name='subsection4'></a>DT - TclLib DocTools format
The documentation is generated in the Tcllib DocTools format if this format is
selected.
# <a name='section4'></a>ADDING SUPPORT FOR NEW DOCUMENT FORMATS
Support for a new document format can be added by defining in the
__tepam::doc_gen__ namespace a set of procedures that generate the different
document components.
The following documentation listing contains tokens that refer to the different
document generation procedures:
* <01>*
*<03> <20s>* NAME*<20e>*
* <30s>* message_box - Displays text in a message box*<30e>*
* <20s>* SYNOPSYS*<20e>*
* <40s>* message_box [-mtype <mtype>] <text>*<40e>*
* <20s>* DESCRIPTION*<20e>*
* <21s> message_box<21e>*
* <54s> message_box [-mtype <mtype>] <text><54e>*
* <50s>* This procedure allows displaying a text in an message box. The following
* * message types are supported:*<50e>*
*<51> <53s>* * Info*<53e>*
* <53s>* * Warning*<53e>*
* <53s>* * Error*<53e>* *<52>*
* <50s>* If the text parameter is use multiple times the different texts are
* * concatenated to create the message text.*<50e>*
* <20s>* ARGUMENTS*<20e>*
*<60> <62s>* [-mtype <mtype>]*<62e>*
*<63> <65s>* Message type*<65e>*
* <66s>* Default: "Warning"*<66e>*
* <66s>* Multiple: yes*<66e>*
* <66s>* Choices: Info, Warning, Error*<66e>* *<64>*
* <62s>* <text>*<62e>*
*<63> <65s>* One or multiple text lines to display*<65e>*
* <66s>* Type: string*<66e>*
* <66s>* Multiple: yes*<66e>* *<64><61>*
* <20s>* EXAMPLE*<20e>*
*<70> <72s>* message_box "Please save first the document"*<72e>*
* <73s>* -> 1*<73e>* *<71><04>*
* <02>*
There are 2 types of document generation procedures:
- Content generation procedures (e.g. <40s>...<40e>)
These procedures generate some document content based on the text that is
provided as procedure argument. The listing above shows two tokens for these
procedures to indicate the beginning and the end of the generated content.
- Control generation procedures (e.g. <03>)
These procedures generate control constructs, for example to generate the
prolog code and epilog code for lists, sections, etc. These procedures have
no argument.
The following set of procedures needs to be defined to provide support for a new
document format:
- *01* - __gen($Format,Header)__ {*Text*}
Only called if __doc_gen__ generates a file or if it is called with the flag
?-header_footer?. The procedure creates the file header. The provided
parameter is the procedure name for which the documentation has to be
generated.
- *02* - __gen($Format,Footer)__ {*Text*}
Only called if __doc_gen__ generates a file or if it is called with the flag
?-header_footer?. The procedure creates the file footer.
- *03* - __gen($Format,Begin)__ {}
Generates the documentation prolog (preamble)
- *04* - __gen($Format,End)__ {}
Generates the documentation epilog
- *20* - __gen($Format,SectionTitle)__ {*Text*}
Generates a section title (e.g. *Name*, *Synopsis*, *Description*, ...). The
raw title text is provided as parameter
- *21* - __gen($Format,SubSectionTitle)__ {*Text*}
Generates a sub-section title. Sub-sections are used if a single
documentation is generated for multiple sub-commands to make a separation
between them. The raw title text is provided as parameter
- *30* - __gen($Format,Name)__ {*Text*}
Generates the name section (without title). The raw section text is provided
as parameter.
- *40* - __gen($Format,Synopsis)__ {*Text*}
Generates the synopsis section (without title). The section text provided as
parameter is pre-formatted (the argument strings are generated by
__gen($Format,ArgumentString)__).
- *50* - __gen($Format,Description)__ {*Text*}
Generates a description paragraph. The raw paragraph text is provided as
parameter.
- *51* - __gen($Format,DescriptionListBegin)__ {}
Generates the prolog of a bulleted/unordered list inside the description
section. This prolog is usually the start code of a list structure.
- *52* - __gen($Format,DescriptionListEnd)__ {}
Generates the epilog of a bulleted/unordered list inside the description
section. This epilog is usually the end code of a list structure.
- *53* - __gen($Format,DescriptionListItem)__ {*Text*}
Generates a text item in a bulleted/unordered description list. The raw item
text is provided as parameter.
- *54* - __gen($Format,DescriptionSynopsis)__ {*Text*}
Generates the synopsis line on the beginning of the description section. The
command can return an empty string if no synopsys line is required at this
place.
Some formats (e.g. Tcl DocTools) require that the synopsis line is defined
in the description section, to build then automatically the synopsis
section. The section text provided as parameter is pre-formatted (the
argument strings are generated by __gen($Format,ArgumentString)__).
- *60* - __gen($Format,ArgumentListBegin)__ {}
Generates the prolog of argument list (definition/non-bulleted list). This
prolog is usually the start code of a definition list.
- *61* - __gen($Format,ArgumentListEnd)__ {}
Generates the epilog of the argument list. This epilog is usually the end
string of a list structure.
- *62* - __gen($Format,ArgumentListItem)__ {Name IsOptional IsNamed Type}
Generates an argument item line inside the argument list. This command can
rely on __gen($Format,ArgumentDetailBegin)__ since the parameters are
identical.
- *63* - __gen($Format,ArgumentDetailBegin)__ {}
Generates the argument details prolog (preamble).
- *64* - __gen($Format,ArgumentDetailEnd)__ {}
Generates the argument details epilog
- *65* - __gen($Format,ArgumentDescription)__ {*Text*}
Generates the argument description (single paragraph).
- *66* - __gen($Format,ArgumentAttribute)__ {*Text*}
Generates a single argument attribute string. The command is called
individually for each attribute.
- *70* - __gen($Format,ExampleBegin)__ {}
Generates the example section prolog (preamble)
- *71* - __gen($Format,ExampleEnd)__ {}
Generates the example section epilog
- *72* - __gen($Format,ExampleCommandLine)__ {*Text*}
Generates a single command line in the example section. The command is
called for each individual command line.
- *73* - __gen($Format,ExampleResultLine)__ {*Text*}
Generates a command result line
- *80* - __gen($Format,ArgumentString)__ {Name IsOptional IsNamed Type}
Generates the part of the command line or the synopsis that is specific to
an argument. The generated string has to indicate if an argument is
optional, named and if it is a flag.
The following parameters are provided to this procedure:
* *Name*
Name of the argument
* *IsOptional*
If true (=__1__) the argument is optional which should be indicated by
the generated string (for example by putting the argument into brackets
{[]} or into question marks '?'):
gen(TXT,ArgumentString) mtype 1 0 string ->
*"[mtype]"*
* *IsNamed*
If true (=__1__) an argument is a named argument (option). The generated
string should in this case contain the argument/option name, followed by
the argument itself:
gen(TXT,ArgumentString) mtype 0 1 string ->
*"-mtype <mtype>"* Named arguments can also be optional:
gen(TXT,ArgumentString) mtype 1 1 string ->
*"[-mtype <mtype>]"*
* *Type*
Indicates the type of the argument. If the type is set to __none__ the
argument is a flag, which needs to be indicated by the generated string.
Example:
gen(TXT,ArgumentString) close 1 1 none ->
*"[-close]"*
# <a name='section5'></a>EXAMPLES
## <a name='subsection5'></a>tepam::doc_gen::generate
The __TEPAM Doc Gen__ package can be explored by generating the documentation of
the command __tepam::doc_gen::generate__. The following example generates the
document in text format (default format):
__tepam::doc_gen::generate__ tepam::doc_gen::generate
The next example generates the documentation in HTML format:
__tepam::doc_gen::generate__ -format HTML tepam::doc_gen::generate
The flag ?header_footer? adds also the file header and footer:
__tepam::doc_gen::generate__ -format HTML -header_footer tepam::doc_gen::generate
The documentation can directly be stored in a file. The file header and footer
are automatically generated in this way:
__tepam::doc_gen::generate__ -format HTML -dest_file doc_gen.html tepam::doc_gen::generate
The generated HTML file refers a CSS stylesheet file (default:
tepam_doc_stylesheet.css). To display the HTML file correctly this CSS
stylesheet file needs to be copied into the directory of the generated HTML
file.
The Tcl DOC Tools format can be used as intermediate format to generate other
formats, for example HTML:
*# Generate the documentation in Tcl Doc Tool format*
set dt [__tepam::doc_gen::generate__ -format DT -header_footer tepam::doc_gen::generate]
**
*# Create a new doc tools object (HTML format)*
package require doctools
::doctools::new myDoc -format html
**
*# Open the HTML file, and write the HTML formatted documentation*
set fHtml [open doc_gen.dt.html w]
puts $fHtml [myDoc format $dt]
close $fHtml
## <a name='subsection6'></a>tepam::doc_gen::patch
While __generate__ provides a limited number of possibilities to vary the
document structure, __[patch](../../../../index.md#patch)__ offers more
flexibility. Multiple documentations for different procedures and meta
information can for example be added.
The following listing shows how the __[patch](../../../../index.md#patch)__
command works. It defines first a HTML master document string that contains 2
procedure documentation placeholders (*{*<ProcedureName>*}*). There placeholders
are replaced by __[patch](../../../../index.md#patch)__ with the generated
documentation of the referred procedures. Since nonstandard placeholders are
used, __[patch](../../../../index.md#patch)__ is called with an explicit
placeholder pattern definition (argument *search_pattern*).
*# Define the HTML master document*
set HtmlMasterDoc {\
<html>
<head>
<title>tepam::doc_gen</title>
<link rel="stylesheet" href="tepam_doc_stylesheet.css">
<meta content="documentation" name="keywords"></meta>
</head>
<body>
<h1>tepam::doc_gen</h1>
<h2>Generate</h2>
__{*tepam::doc_gen::generate*}__
<h2>Patch</h2>
__{*tepam::doc_gen::patch*}__
</body>
<html>\
}
**
*# Patch the master document: This will replace the placeholders by the
# procedure documentation divisions:*
__tepam::doc_gen::patch__ -format HTML -search_pattern {\{\*(.*?)\*\}} \
-src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html
# <a name='see-also'></a>SEE ALSO
[tepam(n)](tepam_introduction.md), [tepam::procedure(n)](tepam_procedure.md)
# <a name='keywords'></a>KEYWORDS
[automatic documentation](../../../../index.md#automatic_documentation),
[documentation](../../../../index.md#documentation), [procedure
documentation](../../../../index.md#procedure_documentation)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2013, Andreas Drollinger
|
Added embedded/md/tcllib/files/modules/tepam/tepam_introduction.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
|
[//000000001]: # (tepam - Tcl's Enhanced Procedure and Argument Manager)
[//000000002]: # (Generated from file 'tepam_introduction.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tepam(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager")
# NAME
tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument
Manager
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Description](#section1)
- [OVERVIEW](#section2)
- [PROCEDURE DECLARATION](#section3)
- [PROCEDURE HELP](#section4)
- [PROCEDURE CALL](#section5)
- [INTERACTIVE PROCEDURE CALLS](#section6)
- [FLEXIBLE ARGUMENT DIALOG BOX](#section7)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='description'></a>DESCRIPTION
This document is an informal introduction into TEPAM, the Tcl's Enhanced
Procedure and Argument Manager. Detailed information to the TEPAM package is
provided in the *tepam::procedure* and *tepam::argument_dialogbox* reference
manuals.
# <a name='section2'></a>OVERVIEW
This package provides a new Tcl procedure declaration syntax that simplifies the
implementation of procedure subcommands and the handling of the different types
of procedure arguments like flags or switches, options, unnamed arguments,
optional and mandatory options and arguments, default values, etc. Procedure
declarations can be enriched with detailed information about the procedure and
its arguments. This information is used for the following purposes:
First of all, a preamble is added in front of the body of a procedure that is
declared with TEPAM. This preamble calls an argument manager that that uses the
provided information to check the validity of the argument types and values
before the procedure body is executed. Then, the information is used to generate
help and usage texts if requested, or to generate clear error message in case an
argument validation fails. The information also allows generating automatically
graphical forms that allows an interactive definition of all arguments, in case
a procedure is called interactively. And finally, the additional information
helps self-commenting in a clean way the declaration of a procedure and of all
its arguments.
The graphical form generator that creates the necessary argument specification
forms for the interactive procedure calls is also available for other purposes
than for procedure argument specifications. It allows creating code efficiently
complex parameter entry forms that are usable independently from TEPAM's new
procedure definition method.
Here is a short overview about all major TEPAM features:
- New self-documenting procedure declaration syntax: The additional
information to declare properly a procedure has not to be provided with
additional statements, but can be added in a natural syntax directly into
the procedure header.
- Easy way to specify subcommands: A subcommand is declared like a procedure,
simply with a procedure name composed by a base name followed by a
subcommand name. Sub-subcommands are created identically using simply
procedure names composed by 3 words.
- Flexible usage of flags (switches), options (named arguments) and unnamed
arguments. Option names are optionally automatically completed.
- Support for default values, mandatory/optional options and arguments, choice
lists, value ranges, multiple usable options/arguments.
- Choice of a *named arguments first, unnamed arguments later* procedure
calling style (typical for Tcl commands) or of an *unnamed arguments first,
named arguments later* procedure calling style (typical for Tk commands).
- In case the *named arguments first, unnamed arguments later* style (Tcl) is
selected: Clear separation between options and arguments via the "--" flag.
The unnamed arguments can optionally be accessed as options (named
arguments).
- Automatic type and value check before the procedure body is executed, taking
into account validation ranges, choice lists and custom validation commands.
Generation of clear error message if necessary.
- Many predefined types exist (integer, boolean, double, color, file, font,
...). Other application specific types can easily be added.
- Automatic help and usage text generation if a procedure is called with the
*-help* flag.
- Automatic generation of an interactive argument definition form, in case a
procedure is called with the *-interactive* flag.
- Procedure calls can be logged which is useful to get for interactively
called procedures the command call lines.
- Powerful and code efficient generation of complex parameter definition
forms.
# <a name='section3'></a>PROCEDURE DECLARATION
TEPAM's procedure declaration syntax is simple and self-explaining. Instead of
declaring a procedure with the Tcl key word
__[proc](../../../../index.md#proc)__, a procedure is declared with the TEPAM
command __[procedure](../../../../index.md#procedure)__ which takes as
__[proc](../../../../index.md#proc)__ also 3 arguments: The procedure name, the
procedure header and the procedure body.
The following example declares the subcommand
__[message](../../../../index.md#message)__ of the procedure __display__. This
command has several named and unnamed arguments:
__[tepam::procedure](tepam_procedure.md)__ {display message} {
-return -
-short_description "Displays a simple message box"
-description "This procedure allows displaying a configurable message box."
-args {
{-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
{-font -type font -default {Arial 10 italic} -description "Message text font"}
{-level -type integer -optional -range {1 10} -description "Message level"}
{-fg -type color -default black -description "Message color"}
{-bg -type color -optional -description "Background color"}
{-no_border -type none -description "Use a splash window style (no border)"}
{-log_file -type file -optional -description "Optional message log file"}
{text -type string -multiple -description "Multiple text lines to display"}
}
} {
* puts "display message:"
foreach var {mtype font level fg bg no_border log_file text} {
if {[info exists $var]} {
puts " $var=[set $var]"
}
}
*}
A call of procedure that has been declared in this way will first invoke the
TEPAM argument manager, before the procedure body is executed. The argument
manager parses the provided arguments, validates them, completes them eventually
with some default values, and makes them finally available to the procedure body
as local variables. In case an argument is missing or has a wrong type, the
argument manager generates an error message that explains the reason for the
error.
As the example above shows, the TEPAM command
__[procedure](../../../../index.md#procedure)__ accepts subcommand definitions
as procedure name and allows defining much more information than just the
argument list inside the procedure header. The procedure body on the other hand
is identical between a command declared with
__[proc](../../../../index.md#proc)__ and a command declared with
__[procedure](../../../../index.md#procedure)__.
The procedure header allows defining in addition to the arguments some procedure
attributes, like a description, information concerning the return value, etc.
This information is basically used for the automatic generation of comprehensive
help and usage texts.
A list of argument definition statements assigned to the *-args* argument is
defining the procedure arguments. Each argument definition statement starts with
the argument name, optionally followed by some argument attributes.
Three types of arguments can be defined: Unnamed arguments, named arguments and
flags. The distinction between the named and unnamed arguments is made by the
first argument name character which is simply "-" for named arguments. A flag is
defined as named argument that has the type *none*.
Named and unnamed arguments are mandatory, unless they are declared with the
*-optional* flag and unless they have a default value specified with the
*-default* option. Named arguments and the last unnamed argument can have the
attribute *-multiple*, which means that they can be defined multiple times. The
expected argument data type is specified with the *-type* option. TEPAM defines
a large set of standard data types which can easily be completed with
application specific data types.
The argument declaration order has only an importance for unnamed arguments that
are by default parsed after the named arguments (Tcl style). A variable allows
changing this behavior in a way that unnamed arguments are parsed first, before
the named arguments (Tk style).
# <a name='section4'></a>PROCEDURE HELP
The declared procedure can simply be called with the *-help* option to get the
information about the usage of the procedure and its arguments:
__display message__ -help
* -> NAME display message - Displays a simple message box SYNOPSYS display
message [-mtype <mtype>] : Message type, default: "Warning", choices: {Info
Warning Error} [-font <font>] : Message text font, type: font, default: Arial 10
italic [-level <level>] : Message level, type: integer, range: 1..10 [-fg <fg>]
: Message color, type: color, default: black [-bg <bg>] : Background color,
type: color [-no_border ] : Use a splash window style (no border) [-log_file
<log_file>] : Optional message log file, type: file <text> : Multiple text lines
to display, type: string DESCRIPTION This procedure allows displaying a
configurable message box.*
# <a name='section5'></a>PROCEDURE CALL
The specified procedure can be called in many ways. The following listing shows
some valid procedure calls:
__display message__ "The document hasn't yet been saved!"
*-> display message:
mtype=Warning
font=Arial 10 italic
fg=black
no_border=0
text={The document hasn't yet been saved!}*
__display message__ -fg red -bg black "Please save first the document"
*-> display message:
mtype=Warning
font=Arial 10 italic
fg=red
bg=black
no_border=0
text={Please save first the document}*
__display message__ -mtype Error -no_border "Why is here no border?"
*-> display message:
mtype=Error
font=Arial 10 italic
fg=black
no_border=1
text={Why is here no border?}*
__display message__ -font {Courier 12} -level 10 \
"Is there enough space?" "Reduce otherwise the font size!"
*-> display message: mtype=Warning font=Courier 12 level=10 fg=black no_border=0
text={Is there enough space?} {Reduce otherwise the font size!}* The next lines
show how wrong arguments are recognized. The *text* argument that is mandatory
is missing in the first procedure call:
__display message__ -font {Courier 12}
* -> display message: Required argument is missing: text* Only known arguments
are accepted:
__display message__ -category warning Hello
* -> display message: Argument '-category' not known* Argument types are
automatically checked and an error message is generated in case the argument
value has not the expected type:
__display message__ -fg MyColor "Hello"
* -> display message: Argument 'fg' requires type 'color'. Provided value:
'MyColor'* Selection choices have to be respected ...
__display message__ -mtype Fatal Hello
* -> display message: Argument (mtype) has to be one of the following elements:
Info, Warning, Error* ... as well as valid value ranges:
__display message__ -level 12 Hello
* -> display message: Argument (level) has to be between 1 and 10*
# <a name='section6'></a>INTERACTIVE PROCEDURE CALLS
The most intuitive way to call the procedure is using an form that allows
specifying all arguments interactively. This form will automatically be
generated if the declared procedure is called with the *-interactive* flag. To
use this feature the Tk library has to be loaded.
__display message__ -interactive
The generated form contains for each argument a data entry widget that is
adapted to the argument type. Check buttons are used to specify flags, radio
boxes for tiny choice lists, disjoint list boxes for larger choice lists and
files, directories, fonts and colors can be selected with dedicated browsers.
After acknowledging the specified argument data via an OK button, the entered
data are first validated, before the provided arguments are transformed into
local variables and the procedure body is executed. In case the entered data are
invalid, a message appears and the user can correct them until they are valid.
The procedure calls can optionally be logged in a variable. This is for example
useful to get the command call lines of interactively called procedures.
# <a name='section7'></a>FLEXIBLE ARGUMENT DIALOG BOX
The form generator that creates in the previous example the argument dialog box
for the interactive procedure call is also available for other purposes than for
the definition of procedure arguments. If Tk has been loaded TEPAM provides and
argument dialog box that allows creating complex parameter definition forms in a
very efficient way.
The following example tries to illustrate the simplicity to create complex data
entry forms. It creates an input mask that allows specifying a file to copy, a
destination folder as well as a checkbox that allows specifying if an eventual
existing file can be overwritten. Comfortable browsers can be used to select
files and directories. And finally, the form offers also the possibility to
accept and decline the selection. Here is the code snippet that is doing all
this:
__[tepam::argument_dialogbox](tepam_argument_dialogbox.md)__ \
__-existingfile__ {-label "Source file" -variable SourceFile} \
__-existingdirectory__ {-label "Destination folder" -variable DestDir} \
__-checkbutton__ {-label "Overwrite existing file" -variable Overwrite}
The __argument_dialogbox__ returns __ok__ if the entered data are validated. It
will return __cancel__ if the data entry has been canceled. After the validation
of the entered data, the __argument_dialogbox__ defines all the specified
variables with the entered data inside the calling context.
An __argument_dialogbox__ requires a pair of arguments for each variable that it
has to handle. The first argument defines the entry widget type used to select
the variable's value and the second one is a lists of attributes related to the
variable and the entry widget.
Many entry widget types are available: Beside the simple generic entries, there
are different kinds of list and combo boxes available, browsers for existing and
new files and directories, check and radio boxes and buttons, as well as color
and font pickers. If necessary, additional entry widgets can be defined.
The attribute list contains pairs of attribute names and attribute data. The
primary attribute is *-variable* used to specify the variable in the calling
context into which the entered data has to be stored. Another often used
attribute is *-label* that allows adding a label to the data entry widget. Other
attributes are available that allow specifying default values, the expected data
types, valid data ranges, etc.
The next example of a more complex argument dialog box provides a good overview
about the different available entry widget types and parameter attributes. The
example contains also some formatting instructions like *-frame* and *-sep*
which allows organizing the different entry widgets in frames and sections:
set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
set Result [__[tepam::argument_dialogbox](tepam_argument_dialogbox.md)__ \
__-title__ "System configuration" \
__-context__ test_1 \
__-frame__ {-label "Entries"} \
__-entry__ {-label Entry1 -variable Entry1} \
__-entry__ {-label Entry2 -variable Entry2 -default "my default"} \
__-frame__ {-label "Listbox & combobox"} \
__-listbox__ {-label "Listbox, single selection" -variable Listbox1 \
-choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
__-listbox__ {-label "Listbox, multiple selection" -variable Listbox2
-choicevariable ChoiceList -default {"Choice 2" "Choice 3"}
-multiple_selection 1 -height 3} \
__-disjointlistbox__ {-label "Disjoined listbox" -variable DisJntListbox
-choicevariable ChoiceList \
-default {"Choice 3" "Choice 5"} -height 3} \
__-combobox__ {-label "Combobox" -variable Combobox \
-choices {1 2 3 4 5 6 7 8} -default 3} \
__-frame__ {-label "Checkbox, radiobox and checkbutton"} \
__-checkbox__ {-label Checkbox -variable Checkbox
-choices {bold italic underline} -choicelabels {Bold Italic Underline} \
-default italic} \
__-radiobox__ {-label Radiobox -variable Radiobox
-choices {bold italic underline} -choicelabels {Bold Italic Underline} \
-default underline} \
__-checkbutton__ {-label CheckButton -variable Checkbutton -default 1} \
__-frame__ {-label "Files & directories"} \
__-existingfile__ {-label "Input file" -variable InputFile} \
__-file__ {-label "Output file" -variable OutputFile} \
__-sep__ {} \
__-existingdirectory__ {-label "Input directory" -variable InputDirectory} \
__-directory__ {-label "Output irectory" -variable OutputDirectory} \
__-frame__ {-label "Colors and fonts"} \
__-color__ {-label "Background color" -variable Color -default red} \
__-sep__ {} \
__-font__ {-label "Font" -variable Font -default {Courier 12 italic}}
] The __argument_dialogbox__ defines all the specified variables with the
entered data and returns __ok__ if the data have been validated via the Ok
button. If the data entry is cancelled by activating the Cancel button, the
__argument_dialogbox__ returns __cancel__.
if {$Result=="cancel"} {
puts "Canceled"
} else { # $Result=="ok"
puts "Arguments: "
foreach Var {
Entry1 Entry2
Listbox1 Listbox2 DisJntListbox
Combobox Checkbox Radiobox Checkbutton
InputFile OutputFile InputDirectory OutputDirectory
Color Font
} {
puts " $Var: '[set $Var]'"
}
}
*-> Arguments: Entry1: 'Hello, this is a trial' Entry2: 'my default' Listbox1:
'1' Listbox2: '{Choice 2} {Choice 3}' DisJntListbox: '{Choice 3} {Choice 5}'
Combobox: '3' Checkbox: 'italic' Radiobox: 'underline' Checkbutton: '1'
InputFile: 'c:\tepam\in.txt' OutputFile: 'c:\tepam\out.txt' InputDirectory:
'c:\tepam\input' OutputDirectory: 'c:\tepam\output' Color: 'red' Font: 'Courier
12 italic'*
# <a name='see-also'></a>SEE ALSO
[tepam::argument_dialogbox(n)](tepam_argument_dialogbox.md),
[tepam::procedure(n)](tepam_procedure.md)
# <a name='keywords'></a>KEYWORDS
[argument integrity](../../../../index.md#argument_integrity), [argument
validation](../../../../index.md#argument_validation),
[arguments](../../../../index.md#arguments), [entry
mask](../../../../index.md#entry_mask), [parameter entry
form](../../../../index.md#parameter_entry_form),
[procedure](../../../../index.md#procedure),
[subcommand](../../../../index.md#subcommand)
# <a name='category'></a>CATEGORY
Procedures, arguments, parameters, options
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2013, Andreas Drollinger
|
Added embedded/md/tcllib/files/modules/tepam/tepam_procedure.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
|
[//000000001]: # (tepam::procedure - Tcl's Enhanced Procedure and Argument Manager)
[//000000002]: # (Generated from file 'tepam_procedure.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tepam::procedure(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager")
# NAME
tepam::procedure - TEPAM procedure, reference manual
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [TERMINOLOGY](#section2)
- [PROCEDURE DECLARATION](#section3)
- [Procedure Attributes](#subsection1)
- [Argument Declaration](#subsection2)
- [VARIABLES](#section4)
- [ARGUMENT TYPES](#section5)
- [Predefined Argument Types](#subsection3)
- [Defining Application Specific Argument Types](#subsection4)
- [PROCEDURE CALLS](#section6)
- [Help](#subsection5)
- [Interactive Procedure Call](#subsection6)
- [Unnamed Arguments](#subsection7)
- [Named Arguments](#subsection8)
- [Unnamed Arguments First, Named Arguments Later (Tk
Style)](#subsection9)
- [Named Arguments First, Unnamed Arguments Later (Tcl
Style)](#subsection10)
- [Raw Argument List](#subsection11)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.3
package require tepam ?0.5?
[__tepam::procedure__ *name* *attributes* *body*](#1)
# <a name='description'></a>DESCRIPTION
This package provides an alternative way to declare Tcl procedures and to manage
its arguments. There is a lot of benefit to declare a procedure with TEPAM
rather than with the Tcl standard command __proc__: TEPAM allows specifying
inside the procedure declaration all information that is required to generate
comprehensive documentations and help support. The information is also used by
an automatically invoked argument checker that validates the provided procedure
arguments before the procedure body is executed. Finally, a procedure can be
called interactively which will open a graphical form that allows specifying the
procedure arguments.
TEPAM simplifies also the handling of the different types of argument, like the
*named arguments* (often also called *options*) and the *unnamed arguments*.
TEPAM supports the *named first, unnamed later* style (typical Tcl command
style) as well as also the *unnamed first, named later* style (typical Tk
command style). TEPAM takes care about default values for arguments, optional
arguments, multiple applicable arguments, etc. and eliminates the need to check
the validity of the argument inside the procedure bodies.
An informal overview of all the TEPAM procedure declaration and calling features
as well as a short introduction into TEPAM is provided by *tepam(n)*.
# <a name='section2'></a>TERMINOLOGY
The exact meaning of several terms that are used in this document will be
shortly explained to avoid any ambiguities and misunderstandings.
- *Subcommand*
The usage of subcommands is heavily used in the Tcl language. Several
commands are incorporated into a single main command and are selectable via
the first argument.
The __string__ command is an example of such a command that implements for
example subcommands to check a character string length, to compare strings,
to extract substrings, etc:
__string length__ *string*
__string compare__ *string* *string*
__string range__ *string* *first* *last*
...
TEPAM provides a framework that allows implementing easily such subcommands
in form of Tcl procedures. It allows not only defining a first level of
subcommands, but also a higher level of subcommands. The __string__ command
class check could be implemented as independent sub-sub-commands of the
__string__ command:
__string is alnum__ *string*
__string is integer__ *string*
__string is double__ *string*
...
- *Procedure attribute*
TEPAM allows attaching to a declared procedure different kind of attributes.
Some of these attributes are *just* used for documentation purposes, but
other attributes specify the way how the procedure has to be called. Also
the procedure arguments are defined in form of a procedure attribute.
- *Argument*
TEPAM uses the term *argument* for the parameters of a procedure.
The following example calls the subcommand __string compare__ with several
arguments:
__string compare__
*-nocase -length 3 "emphasized" "emphasised"* The following paragraphs
discuss these different argument types.
- *Named argument*
Some parameters, as *-length 3* of the subcommand __string compare__ have to
be provided as pairs of argument names and argument values. This parameter
type is often also called *option*.
TEPAM uses the term *named argument* for such options as well as for the
flags (see next item).
- *Flag, switch*
Another parameter type is the *flag* or the *switch*. Flags are provided
simply by naming the flag leading with the '-' character. The *-nocase* of
the previous __string compare__ example is such a flag.
*Flags* are considered by TEPAM like a special form of *named arguments*.
- *Unnamed argument*
For the other parameters, e.g. the ones for which the argument name has not
to be mentioned, TEPAM uses the term *unnamed argument*. The previous
__string compare__ example uses for the two provided character strings two
*unnamed arguments*.
- *Argument attribute*
TEPAM allows describing the purpose of each procedure argument with
*argument attributes*. While some of them are just documenting the
attributes, most attributes are used by an argument manager to control and
validate the arguments that are provided during a procedure call. Argument
attributes are used to specify default values, parameter classes (integer,
xdigit, font, ...), choice validation lists, value ranges, etc.
- *Named arguments first, unnamed arguments later*
The __string compare__ command of the previous example requires that the
*named arguments* (options, flags) are provided first. The two mandatory
(unnamed) arguments have to be provided as last argument.
__string compare__
*-nocase -length 3 Water $Text* This is the usual Tcl style (exceptions
exist) which is referred in the TEPAM documentation as *named arguments
first, unnamed arguments later style*.
- *Unnamed arguments first, named arguments later*
In contrast to most Tcl commands, Tk uses generally (exceptions exist also
here) a different calling style where the *unnamed arguments* have to be
provided first, before the *named arguments* have to be provided:
__pack__
*.ent1 .ent2 -fill x -expand yes -side left* This style is referred in the
TEPAM documentation as *unnamed arguments first, named arguments later
style*.
# <a name='section3'></a>PROCEDURE DECLARATION
TEPAM allows declaring new Tcl procedures with the command __tepam::procedure__
that has similar to the standard Tcl command __proc__ also 3 arguments:
- <a name='1'></a>__tepam::procedure__ *name* *attributes* *body*
The TEPAM procedure declaration syntax is demonstrated by the following example:
__tepam::procedure__ {display message} {
-short_description
"Displays a simple message box"
-description
"This procedure allows displaying a configurable\
message box. The default message type that is\
created is a warning, but also errors and info can\
be generated.
The procedure accepts multiple text lines."
-example
{display message -mtype Warning "Save first your job"}
-args {
{-mtype -choices {Info Warning Error} \
-default Warning -description "Message type"}
{text -type string -multiple \
-description "Multiple text lines to display"}
}
} {
puts "Message type: $mtype"
puts "Message: $text"
}
The 3 arguments of __procedure__ are:
- *name*
The procedure name can be used in very flexible ways. Procedure names can
have namespace qualifiers. By providing a two element name list as procedure
name, a subcommand of a procedure will be declared. It is even possible to
declare sub-sub-commands of a procedure by providing name lists with three
elements.
Here are some valid procedure declarations using different procedure names
(the attribute and body arguments are empty for simplicity):
*# Simple procedure name:*
tepam::procedure __display_message__ {} {}
**
*# Procedure declared in the main namespace:*
tepam::procedure __::display_message__ {} {}
**
*# Procedure in the namespace* __::ns__*:*
tepam::procedure __::ns::display_message__ {} {}
**
*# Declaration of the subcommand* __message__ *of the procedure* __display__*:*
tepam::procedure __{display message}__ {} {}
- *attributes*
All procedure attributes are provided in form of an option list that
contains pairs of option names and option values. The example above has as
procedure attribute a short and a normal description, but also the procedure
arguments are defined in form of a procedure attribute.
Most procedure attributes are providing information for documentation
purposes. But some of them affect also the way how the procedure can be
called. The section [Procedure Attributes](#subsection1) discusses in detail
the available procedure attributes.
The procedure arguments are defined in form of a special procedure
attribute. Most of the information provided in the argument definition is
not just used for documentation purposes. This information is in fact used
by the TEPAM argument manager to handle and validate the various forms of
arguments that are provided during the procedure calls. The section
[Argument Declaration](#subsection2) discusses in detail all the argument
definition attributes.
- *body*
This is the normal procedure body. The declared arguments will be available
to the procedure body in form of variables.
The procedure body will only be executed if the provided set of arguments
could be validated by the TEPAM argument manager.
tepam::procedure {display_message} {
-args {
{-__mtype__ -default Warning -choices {Warning Error}}
{__text__ -type string}
}
} {
puts "Message type: __$mtype__"
puts "Message: __$text__"
}
The commands __[procedure](../../../../index.md#procedure)__ as well as
__argument_dialogbox__ are exported from the namespace __tepam__. To use these
commands without the __tepam::__ namespace prefix, it is sufficient to import
them into the main namespace:
__namespace import tepam::*__
__[procedure](../../../../index.md#procedure)__ {display_message} {
-args {
...
## <a name='subsection1'></a>Procedure Attributes
The first group of attributes affect the behavior of the declared procedure:
- -named_arguments_first __0__|__1__
This attribute defines the calling style of a procedure. TEPAM uses by
default the *named arguments first, unnamed arguments later* style (Tcl).
This default behavior can globally be changed by setting the variable
__tepam::named_arguments_first__ to __0__. This global calling style can be
changed individually for a procedure with the *-named_arguments_first*
attribute.
- -auto_argument_name_completion __0__|__1__
The declared procedures will by default automatically try to match
eventually abbreviated argument names to the defined arguments names. This
default behavior can globally be changed by setting the variable
__tepam::auto_argument_name_completion__ to __0__. This global setting of
the automatic argument name completion can be changed individually for a
procedure with the *-auto_argument_name_completion* procedure attribute.
- -interactive_display_format __extended__|__short__
A procedure declared with the TEPAM __procedure__ command can always be
called with the __-interactive__ option. By doing so, a graphical form will
be generated that allows specifying all procedure argument values. There are
two display modes for these interactive forms. While the *extended* mode is
more adapted for small procedure argument sets, the __short__ form is more
adequate for huge procedure argument sets.
The choice to use short or extended forms can be globally configured via the
variable __tepam::interactive_display_format__. This global setting can then
be changed individually for a procedure with the
*-interactive_display_format* procedure attribute.
- -args *list*
The procedure arguments are declared via the *-args* attribute. An argument
is defined via a list having as first element the argument name, followed by
eventual argument attributes. All these argument definition lists are
packaged themselves into a global list that is assigned to the *-args*
attribute.
The argument definition syntax will be described more in detail in the
following sub section.
The next attributes allow specifying custom argument checks as well as custom
error messages in case these checks are failing:
- -validatecommand *script*
Custom argument validations can be performed via specific validation
commands that are defined with the *-validatecommand* attribute.
Validation command declaration example:
tepam::procedure {display_message} {
-args {
{text -type string -description "Message text"} }
__-validatecommand {IllegalWordDetector $text}__
} {
}
The validation command is executed in the context of the declared procedure
body. The different argument values are accessed via the argument names.
Note there is also an argument attribute *-validatecommand* that allows
declaring custom checks for specific arguments.
The attribute *-validatecommand* can be repeated to declare multiple custom
checks.
- -validatecommand_error_text *string*
This attribute allows overriding the default error message for a custom
argument validation (defined by *-validatecommand*). Also this attribute can
be repeated in case multiple argument checks are declared.
The following attribute allows controlling the logging settings for an
individual procedure:
- -command_log __0__|__1__|__"interactive"__
This argument configures the logging of the procedure calls into the list
variable __tepam::ProcedureCallLogList__. The default configuration defined
by the variable __tepam::command_log__ will be used if this argument is not
defined in a procedure declaration.
Setting this argument to __0__ will disable any procedure call loggings,
setting it to __1__ will log any procedure calls and setting it to
__interactive__ will log just the procedures that are called interactively
(procedures called with the __-interactive__ flag).
The next group of procedure attributes is just used for the purpose of
documentation and help text generation:
- -category *string*
A category can be assigned to a procedure for documentation purposes. Any
string is accepted as category.
- -short_description *string*
The short description of a procedure is used in the documentation summary of
a generated procedure list as well as in the NAME section of a generated
procedure manual page.
- -description *string*
The (full) description assigned to a procedure is used to create user manual
and help pages.
- -return *string*
The *-return* attribute allows defining the expected return value of a
procedure (used for documentation purposes).
- -example *string*
A help text or manual page of a procedure can be enriched with eventual
examples, using the *-example* attribute.
## <a name='subsection2'></a>Argument Declaration
The following example shows the structure that is used for the argument
definitions in the context of a procedure declaration:
tepam::procedure {display_message} {
-args __{
{-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
{-font -type font -default {Arial 10 italic} -description "Message text font"}
{-level -type integer -optional -range {1 10} -description "Message level"}
{-fg -type color -optional -description "Message color"}
{-log_file -type file -optional -description "Optional message log file"}
{text -type string -multiple -description "Multiple text lines to display"}
}__
} {
}
Each of the procedure arguments is declared with a list that has as first
element the argument name, followed by eventual attributes. The argument
definition syntax can be formalized in the following way:
tepam::procedure <name> {
-args __{
{<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a> <arg_attr_name_1b> <arg_attr_value_1b> ...}
{<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a> <arg_attr_name_2b> <arg_attr_value_2b> ...}
...
}__
} <body>
The argument names and attributes have to be used in the following way:
- Argument name (*<argument_name_<n>>*)
The provided argument name specifies whether the argument is an *unnamed
argument* or a *named argument*. In addition to this, an argument name can
also be blank to indicate an argument comment, or it can start with # to
indicate a section comment.
* *"<Name>"*
This is the simplest form of an argument name: An argument whose name is
not starting with '-' is an *unnamed argument*. The parameter provided
during a procedure call will be assigned to a variable with the name
*<Name>*.
tepam::procedure {print_string} {
-args {
{__[text](../../../../index.md#text)__ -type string -description "This is an unnamed argument"}
}
} {
puts __$text__
}
print_string __"Hello"__
* -> Hello*
* *"-<Name>"*
An argument whose name starts with '-' is a *named argument* (also
called *option*). The parameter provided during a procedure call will be
assigned to a variable with the name *<Name>* (not *-<Name>*).
tepam::procedure {print_string} {
-args {
{__-text__ -type string -description "This is a named argument"}
}
} {
puts __$text__
}
print_string __-text "Hello"__
* -> Hello*
* *"--"*
This flag allows clearly specifying the end of the named arguments and
the beginning of the unnamed arguments, in case the *named arguments
first, unnamed arguments later style (Tcl)* has been selected.
If the *unnamed arguments first, named arguments later style (Tk)* style
is selected, this flag is ignored if the unnamed arguments have already
been parsed. Otherwise it will be assigned to the corresponding unnamed
argument.
* *"-"* or *""*
A blank argument name (either '-' or *''*) starts a comment for the
following arguments.
tepam::procedure {print_time} {
-interactive_display_format short
-args {
{hours -type integer -description "Hour"}
{minutes -type integer -description "Minute"}
__{- The following arguments are optional:}__
{seconds -type integer -default 0 -description "Seconds"}
{milliseconds -type integer -default 0 -description "Milliseconds"}
}
} {
puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]"
}
Argument comments are basically used in the graphical argument
definition forms that are created if a procedure is called
interactively.
* *"#*"*
An argument definition list that starts with '#' is considered as a
section comment. The argument definition list will be trimmed from the
'#' characters and the remaining string will be used as section comment.
Section comments can be used to structure visually the argument
definition code. Section comments are also used to structure the
generated help texts and the interactive argument definition forms.
tepam::procedure {complex_multiply} {
-description "This function perform a complex multiplication"
-args {
__{#### First complex number ####}__
{-r0 -type double -description "First number real part"}
{-i0 -type double -description "First number imaginary part"}
__{#### Second complex number ####}__
{-r1 -type double -description "Second number real part"}
{-i1 -type double -description "Second number imaginary part"}
}
} {
return [expr $r0*$r1 - $i0*$i1]
}
- Argument attributes (*<arg_attr_name_<mn>> <arg_attr_value_<mn>>*)
The following argument attributes are supported:
* -description *string*
The description argument attribute is used for documentation purpose.
Interactive argument definition forms use this attribute to provide
explanations for an argument.
* -type *type*
The type argument attribute allows assigning the argument either to a
predefined data type, or to an application specific data type. The
argument values that are provided during a procedure call are
automatically checked with respect to the defined argument type.
The section [ARGUMENT TYPES](#section5) provides a list of predefined
data types and explains how application specific types can be specified.
The argument type *none* has a special meaning. An argument that has the
type *none* is handled as a *flag*. A flag is always optional and its
related variable contains the logical value __1__ if the flag has been
defined during the procedure call, or otherwise __0__.
* -default *value*
Eventual default values can be defined with the -default argument
attribute. Arguments with default values are automatically optional
arguments.
* -optional|-mandatory
Arguments are by default mandatory, unless a default value is defined.
The flag *-optional* transforms an argument into an optional argument.
In case an optional argument is not defined during a procedure call, the
corresponding variable will not be defined. The flag *-mandatory* is the
opposite to *-optional*. This flag exists only for completion reason,
since an argument is anyway mandatory by default.
* -multiple
Arguments that have the *-multiple* attribute can be defined multiple
times during a procedure call. The values that are provided during a
procedure call for such an argument are stored in a list variable. This
is even the case if such an argument is only defined once during a
procedure call.
The *-multiple* attribute can be attributed to unnamed arguments and to
named arguments. The pair of argument name/argument value has to be
repeated for each provided value in case of a named argument. In case
the argument with the *-multiple* attribute is an unnamed argument, this
one has to be the absolute last one of all unnamed arguments.
* -choices *list*
A possible set of valid argument values can be attributed to an argument
via the *-choices* attribute. The argument value provided during a
procedure call will be checked against the provided choice values.
* -choicelabels *list*
An eventual short description can be attributed to each choice option
with the *-choicelabels* attribute. These descriptions will be used in
the generated help texts and as radio and check box labels for the
interactive calls.
The *-choicelabels* attribute is optional, but if it is defined, its
list needs to have the identical size as the *-choices* argument list.
* -range *{double double}*
Another argument constraint can be defined with the *-range* attribute.
The valid range is defined with a list containing the minimum valid
value and a maximum valid value. The *-range* attribute has to be used
only for numerical arguments, like integers and doubles.
* -validatecommand *script*
Custom argument value validations can be performed via specific
validation commands that are defined with the *-validatecommand*
attribute. The provided validation command can be a complete script in
which the pattern *%P* is replaced by the argument value that has to be
validated.
Validation command declaration example:
tepam::procedure {display_message} {
-args {
{text -type string -description "Message text" \
__-validatecommand {IllegalWordDetector %P}__}
} {
}
While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global attribute
*-validatecommand* that allows performing validation that involves
multiple arguments.
* -validatecommand_error_text *string*
This attribute allows overriding the default error message for a custom
argument validation (defined by *-validatecommand*).
* -widget *string*
The widgets that allow defining the different arguments in case of an
interactive procedure call are normally selected automatically in
function of the argument type. The *-widget* attribute allows specifying
explicitly a certain widget type for an argument.
* -auxargs *list*
In case a procedure is called interactively, additional argument
attributes can be provided to the interactive argument definition form
via the *-auxargs* attribute that is itself a list of attribute
name/attribute value pairs:
-auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
-<arg_attr_name_1b> <arg_attr_value_1b>
...
}
For example, if a procedure takes as argument a file name it may be
beneficial to specify the required file type for the interactive
argument definition form. This information can be provided via the
*-auxargs* attribute to the argument definition form:
tepam::procedure LoadPicture {
-args {
{FileName -type existingfile -description "Picture file" \
__-auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}__}
}
} {
}
* -auxargs_commands *script*
If the auxiliary argument attributes are not static but have to be
dynamically adaptable, the *-auxargs_commands* allows defining them via
commands that are executed during a procedure call. A list of pairs of
auxiliary attribute names and commands has to be provided to the
*-auxargs_commands* attribute. The provided commands are executed in the
context of the calling procedure.
-auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
-<arg_attr_name_1b> <arg_attr_command_1b>
...
}
# <a name='section4'></a>VARIABLES
Several variables defined inside the __::tepam__ namespace impact the mode of
operation of the procedures that have been declared with the TEPAM __procedure__
command.
- __named_arguments_first__
This variable defines the general calling style of the procedures. It is by
default set to __1__ which selects the *named arguments first, unnamed
arguments later* style (Tcl style).
By setting this variable to __0__, the *named arguments first, unnamed
arguments later* style is globally selected (Tk style):
set tepam::named_arguments_first 0
While this variable defines the general calling style, the procedure
attribute *-named_arguments_first* can adapt this style individually for
each declared procedure.
- __auto_argument_name_completion__
This variable controls the general automatic argument name matching mode. By
default it is set to __1__, meaning that the called procedures are trying to
match eventually abbreviated argument names with the declared argument
names.
By setting this variable to __0__ the automatic argument name matching mode
is disabled:
set tepam::auto_argument_name_completion 0
While this variable defines the general matching mode, the procedure
attribute *-auto_argument_name_completion* can adapt this mode individually
for each declared procedure.
- __interactive_display_format__
A procedure declared via the TEPAM __procedure__ command can always be
called with the __-interactive__ switch. By doing so, a graphical form will
be generated that allows entering interactively all procedure arguments.
There are two display modes for these interactive forms. The *extended* mode
which is the default mode is more adapted for small procedure argument sets.
The __short__ form is more adequate for huge procedure argument sets:
set tepam::interactive_display_format "short"
The choice to use short or extended forms can be globally configured via the
variable __interactive_display_format__. This global setting can be changed
individually for a procedure with the procedure attribute
*-interactive_display_format*.
- __help_line_length__
The maximum line length used by the procedure help text generator can be
specified with this variable. The default length which is set to 80
(characters) can easily be adapted to the need of an application:
set tepam::help_line_length 120
Since this variable is applied directly during the help text generation, its
value can continuously be adapted to the current need.
- __command_log__
Procedure calls can be logged inside the list variable
__tepam::ProcedureCallLogList__. The variable __tepam::command_log__
controls the default logging settings for any procedures. The following
configurations are supported:
*0*: Disables any procedure call loggings
*1*: Enables any procedure call loggings
*"interactive"*: Will log any procedures called interactively (e.g.
procedures called with the -interactive flag). This is the default
configuration.
This default logging configuration can be changed individually for each
procedure with the *-command_log* attribute.
# <a name='section5'></a>ARGUMENT TYPES
TEPAM provides a comprehensive set of procedure argument types. They can easily
be completed with application specific types if necessary.
## <a name='subsection3'></a>Predefined Argument Types
To remember, a type can be assigned to each specified procedure argument:
tepam::procedure {warning} {
-args {
{-font __-type font__ -default {Arial 10 italic}}
{-severity_level __-type integer__ -optional -range {1 10}}
{-fg __-type color__ -optional -description "Message color"}
{text __-type string__ -multiple -description "Multiple text lines to display"}
}
} {
...
}
There are some *special purpose types* that are building the first category of
predefined argument types:
- __none__ A *flag*, also called *switch*, is defined as a named argument that
has the type __none__. Flags are always optional and the default value of
the assigned variable is set to __0__. In contrast to the (normal) named
arguments, no argument value has to be provided to a flag.
tepam::procedure flag_test {
-args {
__{-flag -type none -description "This is a flag"}__
}
} {
puts __$flag__
}
flag_test
*-> 0*
flag_test -flag
*-> 1*
Since no argument value has to be provided to a flag, also no data check is
performed for this argument type.
- __string__ __String__ is a generic argument data type. Any data string can
be provided to a string type argument and no data type checks are therefore
performed. The string type allows defining single line strings during the
interactive procedure calls.
- __text__ __Text__ is identical to __string__ with the only difference that
it allows entering multi line strings during interactive procedure calls.
- __{}__ A __blank__ argument type signifies an undefined argument type. This
is the default argument type that will be used if no type has been
explicitly specified. An argument that has a __blank__ type behaves
identically than an argument that has a __string__ type, e.g. no argument
data checks are performed. The only difference is that the data type
__string__ is mentioned in the generated help documentation, while this is
not the case for the __blank__ type.
Several *numerical types* are defined by TEPAM. The type validation procedures
are using the __string is <type> -strict__ commands to check the validity of the
provided arguments, which assures that no empty strings are accepted as argument
value. The type validation expression for the numerical types and the argument
types to which this expression is applied are:
string is __<type_to_check>__ -strict
*<argument_value>*
- *boolean*
- *integer*
- *double*
Empty strings are accepted as argument value for all the alpha numeric argument
types. The argument types that are falling into this category and validation
expression used for them are:
string is *<type_to_check>*
*<argument_value>*
- *alnum*
- *alpha*
- *ascii*
- *control*
- *digit*
- *graph*
- *lower*
- *print*
- *punct*
- *space*
- *upper*
- *wordchar*
- *xdigit*
In addition to the data types checked with the __string is <type>__ commands,
TEPAM specifies some other useful data types:
- *char* Each string that has a length of 1 character meets the *character*
type. The type check is made with the following expression:
expr [string length *<argument_value>*]==1
- *color* Any character strings that are accepted by Tk as a color are
considered as valid color argument. Please note that the Tk package has to
be loaded to use the type *color*. TEPAM is using the following command to
validate the color type:
expr ![catch {winfo rgb . *<argument_value>*}
]
- *font* Any character strings that are accepted by Tk as a font are
considered as valid font argument. Please note that the Tk package has to be
loaded to use the *font* type. TEPAM is using the following command to
validate the color type:
expr ![catch {font measure <argument_value> ""}
]
- *file* Any strings that are not containing one of the following characters
are considered as valid file names: * ? " < >. It is not necessary that the
file and its containing directory exist. Zero-length strings are not
considered as valid file names.
The following expression is used to validate the file names:
expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>
]
- *existingfile* The argument is valid if it matches with an existing file.
The following check is performed to validate the arguments of this type:
file exists <argument_value>
- *directory* The directory argument is validated exactly in the same way as
the file arguments.
- *existingdirectory* The argument is valid if it matches with an existing
directory. The following check is performed to validate the arguments of
this type:
file isdirectory <argument_value>
## <a name='subsection4'></a>Defining Application Specific Argument Types
To add support for a new application specific argument type it is just necessary
to add into the namespace __tepam__ a validation function
__Validation(<type>)__. This function requires one argument. It has to returns
__1__ if the provided argument matches with the relevant data type. The function
has to return otherwise __0__.
The validation command section of the "tepam.tcl" package provides sufficient
examples of validation functions, since it implements the ones for the standard
TEPAM types.
The following additional code snippet shows the validation function for a custom
argument type that requires values that have a character string length of
exactly 2:
proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}}
# <a name='section6'></a>PROCEDURE CALLS
## <a name='subsection5'></a>Help
Each procedure can be called with the *-help* flag. The procedure will then
print a generated help text to *stdout* and will then return without performing
any additional actions.
Taking the first procedure declared in [PROCEDURE CALLS](#section6), the help
request and the printed help text would be:
__display message -help__
*-> NAME display message - Displays a simple message box SYNOPSIS display
message [-mtype <mtype>] Message type, default: "Warning", choices: {Info,
Warning, Error} <text> Multiple text lines to display, type: string DESCRIPTION
This procedure allows displaying a configurable message box. The default message
type that is created is a warning, but also errors and info can be generated.
The procedure accepts multiple text lines. EXAMPLE display message -mtype
Warning "Save first your job"* The argument manager is checking if the last
provided argument is *-help* and generates the requested help message if this is
the case. So, also the following example will print the help message:
__display message -mtype Info "It is 7:00" -help__ On the other hand, the
following call will result in an error:
__display message -help -mtype Info "It is 7:00"__
*-> display message: Argument '-help' not known*
## <a name='subsection6'></a>Interactive Procedure Call
If Tk has been loaded a procedure can be called with the *-interactive* flag to
open a graphical form that allows specifying interactively all procedure
arguments. The following example assures that the Tk library is loaded and shows
the command line to call interactively the procedure declared in [PROCEDURE
CALLS](#section6):
package require Tk
__display message -interactive__ Also the *-interactive* flag has to be placed
at the last argument position as this is also required for the *-help* flag.
Arguments defined before the *-interactive* flag will be ignored. The following
example is therefore also a valid interactive procedure call:
__display message__ -mtype Info "It is 7:00"
__-interactive__
## <a name='subsection7'></a>Unnamed Arguments
Unnamed arguments are typically provided to the called procedure as simple
parameters. This procedure calling form requires that the provided arguments are
strictly following the order of the specified arguments. Several parameters can
be assigned to the last argument if this one has the *-multiple* attribute. So,
the following declared procedure ...
tepam::procedure {display_message} {
-args {
{mtype -choices {Info Warning Error}}
{text -type string -multiple}
}
} {
puts "$mtype: [join $text]"
}
... can for example be called in the following ways:
__display_message Info "It is PM 7:00."__
*-> Info: It is PM 7:00.*
__display_message Info "It is PM 7:00." "You should go home."__
*-> Info: It is PM 7:00. You should go home.* The nice thing is that unnamed
arguments can also be called as named arguments, which can be handy, for example
if the exact specified argument order is not known to a user:
__display_message -mtype Info -text "It is PM 7:00."__
*-> Info: It is PM 7:00.*
__display_message -text "It is PM 7:00." -mtype Info__
*-> Info: It is PM 7:00.*
__display_message -mtype Info -text "It is PM 7:00." -text "You should go home."__
*-> Info: It is PM 7:00. You should go home.*
__display_message -text "It is PM 7:00." -text "You should go home." -mtype Info__
*-> Info: It is PM 7:00. You should go home.*
## <a name='subsection8'></a>Named Arguments
Named arguments have to be provided to a procedure in form of a parameter pairs
composed by the argument names and the argument values. The order how they are
provided during a procedure call is irrelevant and has not to match with the
argument specification order.
The following declared procedure ...
tepam::procedure {display_message} {
-args {
{-mtype -choices {Info Warning Error}}
{-text -type string -multiple}
}
} {
puts "$mtype: [join $text]"
}
... can be called in the following ways:
__display_message -mtype Info -text "It is PM 7:00."__
*-> Info: It is PM 7:00.*
__display_message -text "It is PM 7:00." -mtype Info__
*-> Info: It is PM 7:00.*
__display_message -mtype Info -text "It is PM 7:00." -text "You should go home."__
*-> Info: It is PM 7:00. You should go home.*
__display_message -text "It is PM 7:00." -text "You should go home." -mtype Info__
*-> Info: It is PM 7:00. You should go home.* Also named arguments that have not
the *-multiple* attribute can be provided multiple times. Only the last provided
argument will be retained in such a case:
__display_message -mtype Info -text "It is PM 7:00." -mtype Warning__
*-> Warning: It is PM 7:00.*
## <a name='subsection9'></a>Unnamed Arguments First, Named Arguments Later (Tk Style)
A procedure that has been defined while the variable
__tepam::named_arguments_first__ was set to 1, or with the procedure attribute
*-named_arguments_first* set to 1 has to be called in the Tcl style. The
following procedure declaration will be used in this section to illustrate the
meaning of this calling style:
__set tepam::named_arguments_first 1__
tepam::procedure my_proc {
-args {
{-n1 -default ""}
{-n2 -default ""}
{u1 -default ""}
{u2 -default ""}
}
} {
puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
}
The unnamed arguments are placed at the end of procedure call, after the named
arguments:
my_proc __-n1 N1 -n2 N2 U1 U2__
*-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'* The argument parser considers the first
argument that doesn't start with the '-' character as well as all following
arguments as unnamed argument:
my_proc __U1 U2__
*-> n1:'', n2:'', u1:'U1', u2:'U2'* Named arguments can be defined multiple
times. If the named argument has the *-multiply* attribute, all argument values
will be collected in a list. Otherwise, only the last provided attribute value
will be retained:
my_proc __-n1 N1 -n2 N2 -n1 M1 U1 U2__
*-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'* The name of the first unnamed argument
has therefore not to start with the '-' character. The unnamed argument is
otherwise considered as name of another named argument. This is especially
important if the first unnamed argument is given by a variable that can contain
any character strings:
my_proc __-n1 N1 -n2 N2 "->" "<-"__
*-> my_proc: Argument '->' not known*
set U1 "->"
my_proc __-n1 N1 -n2 N2 $U1 U2__
my_proc: Argument '->' not known
The '--' flag allows separating unambiguously the unnamed arguments from the
named arguments. All data after the '--' flag will be considered as unnamed
argument:
my_proc __-n1 N1 -n2 N2 -- "->" "<-"__
*-> n1:'N1', n2:'N2', u1:'->', u2:'<-'*
set U1 "->"
my_proc __-n1 N1 -n2 N2 -- $U1 U2__
*-> n1:'N1', n2:'N2', u1:'->', u2:'<-'*
## <a name='subsection10'></a>Named Arguments First, Unnamed Arguments Later (Tcl Style)
The Tk calling style will be chosen if a procedure is defined while the variable
__tepam::named_arguments_first__ is set to 0, or if the procedure attribute
*-named_arguments_first* has been set to 0. The following procedure will be used
in this section to illustrate this calling style:
__set tepam::named_arguments_first 0__
tepam::procedure my_proc {
-args {
{-n1 -default ""}
{-n2 -default ""}
{u1}
{u2 -default "" -multiple}
}
} {
puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
}
The unnamed arguments have to be provided first in this case. The named
arguments are provided afterwards:
my_proc __U1 U2 -n1 N1 -n2 N2__
*-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* The argument parser will assign to each
defined unnamed argument a value before it switches to read the named arguments.
This default behavior changes a bit if there are unnamed arguments that are
optional or that can take multiple values.
An argument value will only be assigned to an unnamed argument that is optional
(that has either the *-optional* attribute or that has a default value), if the
value is not beginning with the '-' character or if no named arguments are
defined. The value that starts with '-' is otherwise considered as the name of a
named argument.
Argument values are assigned to an argument that has the *-multiple* attribute
as long as the parameter value doesn't starts with the '-' character.
Values that start with the '-' character can therefore not be assigned to
optional unnamed arguments, which restricts the usage of the Tcl procedure
calling style. The Tk style may be preferable in some cases, since it allows
separating unambiguously the named arguments from the unnamed ones with the '--'
flag.
Let's explore in a bit less theoretically the ways how the previously defined
procedure can be called: The first example calls the procedure without any
parameters, which leads to an error since *u1* is a mandatory argument:
my_proc
*-> my_proc: Required argument is missing: u1* The procedure call is valid if
one parameter is provided for *u1*:
my_proc __U1__
*-> n1:'', n2:'', u1:'U1', u2:''* If more parameters are provided that are not
starting with the '-' character, they will be attributed to the unnamed
arguments. *U2* will receive 3 of these parameters, since it accepts multiple
values:
my_proc __U1 U2 U3 U4__
*-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'* As soon as one parameter starts with
'-' and all unnamed arguments have been assigned, the argument manager tries to
interpret the parameter as name of a named argument. The procedure call will
fail if a value beginning with '-' is assigned to an unnamed argument:
my_proc __U1 U2 U3 U4 -U5__
*-> my_proc: Argument '-U5' not known* The attribution of a parameter to a named
argument will fail if there are undefined unnamed (non optional) arguments. The
name specification will in this case simply be considered as a parameter value
that is attributed to the *next* unnamed argument. This was certainly not the
intention in the following example:
my_proc __-n1 N1__
*-> n1:'', n2:'', u1:'-n1', u2:'N1'* The situation is completely different if
values have already been assigned to all mandatory unnamed arguments. A
parameter beginning with the '-' character will in this case be considered as a
name identifier for a named argument:
my_proc __U1 -n1 N1__
*-> n1:'N1', n2:'', u1:'U1', u2:''* No unnamed arguments are allowed behind the
named arguments:
my_proc __U1 -n1 N1 U2__
*-> my_proc: Argument 'U2' is not an option* The '--' flag has no special
meaning if not all mandatory arguments have got assigned a value. This flag will
simply be attributed to one of the unnamed arguments:
my_proc __-- -n1 N1__
*-> n1:'N1', n2:'', u1:'--', u2:''* But the '--' flag is simply ignored if the
argument parser has started to handle the named arguments:
my_proc __U1 -- -n1 N1__
*-> n1:'N1', n2:'', u1:'U1', u2:''*
my_proc __U1 -n1 N1 -- -n2 N2__
*-> n1:'N1', n2:'N2', u1:'U1', u2:''*
## <a name='subsection11'></a>Raw Argument List
It may be necessary sometimes that the procedure body is able to access the
entire list of arguments provided during a procedure call. This can happen via
the __args__ variable that contains always the unprocessed argument list:
tepam::procedure {display_message} {
-args {
{-mtype -choices {Warning Error} -default Warning}
{text -type string -multiple}
}
} {
puts "args: __$args__"
}
display_message -mtype Warning "It is 7:00"
*-> args: -mtype Warning {It is 7:00}*
# <a name='see-also'></a>SEE ALSO
[tepam(n)](tepam_introduction.md),
[tepam::argument_dialogbox(n)](tepam_argument_dialogbox.md)
# <a name='keywords'></a>KEYWORDS
[argument integrity](../../../../index.md#argument_integrity), [argument
validation](../../../../index.md#argument_validation),
[arguments](../../../../index.md#arguments),
[procedure](../../../../index.md#procedure),
[subcommand](../../../../index.md#subcommand)
# <a name='category'></a>CATEGORY
Procedures, arguments, parameters, options
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2013, Andreas Drollinger
|
Added embedded/md/tcllib/files/modules/term/ansi_cattr.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
[//000000001]: # (term::ansi::code::attr - Terminal control)
[//000000002]: # (Generated from file 'ansi_cattr.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::ansi::code::attr(n) 0.1 tcllib "Terminal control")
# NAME
term::ansi::code::attr - ANSI attribute sequences
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Introspection](#subsection1)
- [Attributes](#subsection2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::ansi::code ?0.1?
package require term::ansi::code::attr ?0.1?
[__::term::ansi::code::attr::names__](#1)
[__::term::ansi::code::attr::import__ ?*ns*? ?*arg*...?](#2)
[__::term::ansi::code::attr::fgblack__](#3)
[__::term::ansi::code::attr::fgred__](#4)
[__::term::ansi::code::attr::fggreen__](#5)
[__::term::ansi::code::attr::fgyellow__](#6)
[__::term::ansi::code::attr::fgblue__](#7)
[__::term::ansi::code::attr::fgmagenta__](#8)
[__::term::ansi::code::attr::fgcyan__](#9)
[__::term::ansi::code::attr::fgwhite__](#10)
[__::term::ansi::code::attr::fgdefault__](#11)
[__::term::ansi::code::attr::bgblack__](#12)
[__::term::ansi::code::attr::bgred__](#13)
[__::term::ansi::code::attr::bggreen__](#14)
[__::term::ansi::code::attr::bgyellow__](#15)
[__::term::ansi::code::attr::bgblue__](#16)
[__::term::ansi::code::attr::bgmagenta__](#17)
[__::term::ansi::code::attr::bgcyan__](#18)
[__::term::ansi::code::attr::bgwhite__](#19)
[__::term::ansi::code::attr::bgdefault__](#20)
[__::term::ansi::code::attr::bold__](#21)
[__::term::ansi::code::attr::dim__](#22)
[__::term::ansi::code::attr::italic__](#23)
[__::term::ansi::code::attr::underline__](#24)
[__::term::ansi::code::attr::blink__](#25)
[__::term::ansi::code::attr::revers__](#26)
[__::term::ansi::code::attr::hidden__](#27)
[__::term::ansi::code::attr::strike__](#28)
[__::term::ansi::code::attr::nobold__](#29)
[__::term::ansi::code::attr::noitalic__](#30)
[__::term::ansi::code::attr::nounderline__](#31)
[__::term::ansi::code::attr::noblink__](#32)
[__::term::ansi::code::attr::norevers__](#33)
[__::term::ansi::code::attr::nohidden__](#34)
[__::term::ansi::code::attr::nostrike__](#35)
[__::term::ansi::code::attr::reset__](#36)
# <a name='description'></a>DESCRIPTION
This package provides symbolic names for the ANSI attribute control codes. For
each control code a single command is provided which returns this code as its
result. None of the commands of this package write to a channel; that is handled
by higher level packages, like __[term::ansi::send](ansi_send.md)__.
# <a name='section2'></a>API
## <a name='subsection1'></a>Introspection
- <a name='1'></a>__::term::ansi::code::attr::names__
This command is for introspection. It returns as its result a list
containing the names of all attribute commands.
- <a name='2'></a>__::term::ansi::code::attr::import__ ?*ns*? ?*arg*...?
This command imports some or all attribute commands into the namespace *ns*.
This is by default the namespace *attr*. Note that this is relative
namespace name, placing the imported command into a child of the current
namespace. By default all commands are imported, this can howver be
restricted by listing the names of the wanted commands after the namespace
argument.
## <a name='subsection2'></a>Attributes
- <a name='3'></a>__::term::ansi::code::attr::fgblack__
Set text color to *Black*.
- <a name='4'></a>__::term::ansi::code::attr::fgred__
Set text color to *Red*.
- <a name='5'></a>__::term::ansi::code::attr::fggreen__
Set text color to *Green*.
- <a name='6'></a>__::term::ansi::code::attr::fgyellow__
Set text color to *Yellow*.
- <a name='7'></a>__::term::ansi::code::attr::fgblue__
Set text color to *Blue*.
- <a name='8'></a>__::term::ansi::code::attr::fgmagenta__
Set text color to *Magenta*.
- <a name='9'></a>__::term::ansi::code::attr::fgcyan__
Set text color to *Cyan*.
- <a name='10'></a>__::term::ansi::code::attr::fgwhite__
Set text color to *White*.
- <a name='11'></a>__::term::ansi::code::attr::fgdefault__
Set default text color (*Black*).
- <a name='12'></a>__::term::ansi::code::attr::bgblack__
Set background to *Black*.
- <a name='13'></a>__::term::ansi::code::attr::bgred__
Set background to *Red*.
- <a name='14'></a>__::term::ansi::code::attr::bggreen__
Set background to *Green*.
- <a name='15'></a>__::term::ansi::code::attr::bgyellow__
Set background to *Yellow*.
- <a name='16'></a>__::term::ansi::code::attr::bgblue__
Set background to *Blue*.
- <a name='17'></a>__::term::ansi::code::attr::bgmagenta__
Set background to *Magenta*.
- <a name='18'></a>__::term::ansi::code::attr::bgcyan__
Set background to *Cyan*.
- <a name='19'></a>__::term::ansi::code::attr::bgwhite__
Set background to *White*.
- <a name='20'></a>__::term::ansi::code::attr::bgdefault__
Set default background (Transparent).
- <a name='21'></a>__::term::ansi::code::attr::bold__
Bold on.
- <a name='22'></a>__::term::ansi::code::attr::dim__
Dim on.
- <a name='23'></a>__::term::ansi::code::attr::italic__
Italics on.
- <a name='24'></a>__::term::ansi::code::attr::underline__
Underscore on.
- <a name='25'></a>__::term::ansi::code::attr::blink__
Blink on.
- <a name='26'></a>__::term::ansi::code::attr::revers__
Reverse on.
- <a name='27'></a>__::term::ansi::code::attr::hidden__
Hidden on.
- <a name='28'></a>__::term::ansi::code::attr::strike__
Strike-through on.
- <a name='29'></a>__::term::ansi::code::attr::nobold__
Bold off.
- <a name='30'></a>__::term::ansi::code::attr::noitalic__
Italics off.
- <a name='31'></a>__::term::ansi::code::attr::nounderline__
Underscore off.
- <a name='32'></a>__::term::ansi::code::attr::noblink__
Blink off.
- <a name='33'></a>__::term::ansi::code::attr::norevers__
Reverse off.
- <a name='34'></a>__::term::ansi::code::attr::nohidden__
Hidden off.
- <a name='35'></a>__::term::ansi::code::attr::nostrike__
Strike-through off.
- <a name='36'></a>__::term::ansi::code::attr::reset__
Reset all attributes to their default values.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[ansi](../../../../index.md#ansi), [attribute
control](../../../../index.md#attribute_control), [color
control](../../../../index.md#color_control),
[control](../../../../index.md#control),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/ansi_cctrl.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
|
[//000000001]: # (term::ansi::code::ctrl - Terminal control)
[//000000002]: # (Generated from file 'ansi_cctrl.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::ansi::code::ctrl(n) 0.2 tcllib "Terminal control")
# NAME
term::ansi::code::ctrl - ANSI control sequences
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Introspection](#subsection1)
- [Sequences](#subsection2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::ansi::code ?0.2?
package require term::ansi::code::ctrl ?0.2?
[__::term::ansi::code::ctrl::names__](#1)
[__::term::ansi::code::ctrl::import__ ?*ns*? ?*arg*...?](#2)
[__::term::ansi::code::ctrl::eeol__](#3)
[__::term::ansi::code::ctrl::esol__](#4)
[__::term::ansi::code::ctrl::el__](#5)
[__::term::ansi::code::ctrl::ed__](#6)
[__::term::ansi::code::ctrl::eu__](#7)
[__::term::ansi::code::ctrl::es__](#8)
[__::term::ansi::code::ctrl::sd__](#9)
[__::term::ansi::code::ctrl::su__](#10)
[__::term::ansi::code::ctrl::ch__](#11)
[__::term::ansi::code::ctrl::sc__](#12)
[__::term::ansi::code::ctrl::rc__](#13)
[__::term::ansi::code::ctrl::sca__](#14)
[__::term::ansi::code::ctrl::rca__](#15)
[__::term::ansi::code::ctrl::st__](#16)
[__::term::ansi::code::ctrl::ct__](#17)
[__::term::ansi::code::ctrl::cat__](#18)
[__::term::ansi::code::ctrl::qdc__](#19)
[__::term::ansi::code::ctrl::qds__](#20)
[__::term::ansi::code::ctrl::qcp__](#21)
[__::term::ansi::code::ctrl::rd__](#22)
[__::term::ansi::code::ctrl::elw__](#23)
[__::term::ansi::code::ctrl::dlw__](#24)
[__::term::ansi::code::ctrl::eg__](#25)
[__::term::ansi::code::ctrl::lg__](#26)
[__::term::ansi::code::ctrl::scs0__ *tag*](#27)
[__::term::ansi::code::ctrl::scs1__ *tag*](#28)
[__::term::ansi::code::ctrl::sda__ *arg*...](#29)
[__::term::ansi::code::ctrl::sda_fgblack__](#30)
[__::term::ansi::code::ctrl::sda_fgred__](#31)
[__::term::ansi::code::ctrl::sda_fggreen__](#32)
[__::term::ansi::code::ctrl::sda_fgyellow__](#33)
[__::term::ansi::code::ctrl::sda_fgblue__](#34)
[__::term::ansi::code::ctrl::sda_fgmagenta__](#35)
[__::term::ansi::code::ctrl::sda_fgcyan__](#36)
[__::term::ansi::code::ctrl::sda_fgwhite__](#37)
[__::term::ansi::code::ctrl::sda_fgdefault__](#38)
[__::term::ansi::code::ctrl::sda_bgblack__](#39)
[__::term::ansi::code::ctrl::sda_bgred__](#40)
[__::term::ansi::code::ctrl::sda_bggreen__](#41)
[__::term::ansi::code::ctrl::sda_bgyellow__](#42)
[__::term::ansi::code::ctrl::sda_bgblue__](#43)
[__::term::ansi::code::ctrl::sda_bgmagenta__](#44)
[__::term::ansi::code::ctrl::sda_bgcyan__](#45)
[__::term::ansi::code::ctrl::sda_bgwhite__](#46)
[__::term::ansi::code::ctrl::sda_bgdefault__](#47)
[__::term::ansi::code::ctrl::sda_bold__](#48)
[__::term::ansi::code::ctrl::sda_dim__](#49)
[__::term::ansi::code::ctrl::sda_italic__](#50)
[__::term::ansi::code::ctrl::sda_underline__](#51)
[__::term::ansi::code::ctrl::sda_blink__](#52)
[__::term::ansi::code::ctrl::sda_revers__](#53)
[__::term::ansi::code::ctrl::sda_hidden__](#54)
[__::term::ansi::code::ctrl::sda_strike__](#55)
[__::term::ansi::code::ctrl::sda_nobold__](#56)
[__::term::ansi::code::ctrl::sda_noitalic__](#57)
[__::term::ansi::code::ctrl::sda_nounderline__](#58)
[__::term::ansi::code::ctrl::sda_noblink__](#59)
[__::term::ansi::code::ctrl::sda_norevers__](#60)
[__::term::ansi::code::ctrl::sda_nohidden__](#61)
[__::term::ansi::code::ctrl::sda_nostrike__](#62)
[__::term::ansi::code::ctrl::sda_reset__](#63)
[__::term::ansi::send::fcp__ *row* *col*](#64)
[__::term::ansi::code::ctrl::cu__ ?*n*?](#65)
[__::term::ansi::code::ctrl::cd__ ?*n*?](#66)
[__::term::ansi::code::ctrl::cf__ ?*n*?](#67)
[__::term::ansi::code::ctrl::cb__ ?*n*?](#68)
[__::term::ansi::code::ctrl::ss__ ?*s* *e*?](#69)
[__::term::ansi::code::ctrl::skd__ *code* *str*](#70)
[__::term::ansi::code::ctrl::title__ *str*](#71)
[__::term::ansi::code::ctrl::gron__](#72)
[__::term::ansi::code::ctrl::groff__](#73)
[__::term::ansi::code::ctrl::tlc__](#74)
[__::term::ansi::code::ctrl::trc__](#75)
[__::term::ansi::code::ctrl::brc__](#76)
[__::term::ansi::code::ctrl::blc__](#77)
[__::term::ansi::code::ctrl::ltj__](#78)
[__::term::ansi::code::ctrl::ttj__](#79)
[__::term::ansi::code::ctrl::rtj__](#80)
[__::term::ansi::code::ctrl::btj__](#81)
[__::term::ansi::code::ctrl::fwj__](#82)
[__::term::ansi::code::ctrl::hl__](#83)
[__::term::ansi::code::ctrl::vl__](#84)
[__::term::ansi::code::ctrl::groptim__ *str*](#85)
[__::term::ansi::code::ctrl::clear__](#86)
[__::term::ansi::code::ctrl::init__](#87)
[__::term::ansi::code::ctrl::showat__ *row* *col* *text*](#88)
# <a name='description'></a>DESCRIPTION
This package provides symbolic names for the ANSI control sequences. For each
sequence a single command is provided which returns the sequence as its result.
None of the commands of this package write to a channel; that is handled by
higher level packages, like __[term::ansi::send](ansi_send.md)__.
# <a name='section2'></a>API
## <a name='subsection1'></a>Introspection
- <a name='1'></a>__::term::ansi::code::ctrl::names__
This command is for introspection. It returns as its result a list
containing the names of all attribute commands.
- <a name='2'></a>__::term::ansi::code::ctrl::import__ ?*ns*? ?*arg*...?
This command imports some or all attribute commands into the namespace *ns*.
This is by default the namespace *ctrl*. Note that this is relative
namespace name, placing the imported command into a child of the current
namespace. By default all commands are imported, this can howver be
restricted by listing the names of the wanted commands after the namespace
argument.
## <a name='subsection2'></a>Sequences
- <a name='3'></a>__::term::ansi::code::ctrl::eeol__
Erase (to) End Of Line
- <a name='4'></a>__::term::ansi::code::ctrl::esol__
Erase (to) Start Of Line
- <a name='5'></a>__::term::ansi::code::ctrl::el__
Erase (current) Line
- <a name='6'></a>__::term::ansi::code::ctrl::ed__
Erase Down (to bottom)
- <a name='7'></a>__::term::ansi::code::ctrl::eu__
Erase Up (to top)
- <a name='8'></a>__::term::ansi::code::ctrl::es__
Erase Screen
- <a name='9'></a>__::term::ansi::code::ctrl::sd__
Scroll Down
- <a name='10'></a>__::term::ansi::code::ctrl::su__
Scroll Up
- <a name='11'></a>__::term::ansi::code::ctrl::ch__
Cursor Home
- <a name='12'></a>__::term::ansi::code::ctrl::sc__
Save Cursor
- <a name='13'></a>__::term::ansi::code::ctrl::rc__
Restore Cursor (Unsave)
- <a name='14'></a>__::term::ansi::code::ctrl::sca__
Save Cursor + Attributes
- <a name='15'></a>__::term::ansi::code::ctrl::rca__
Restore Cursor + Attributes
- <a name='16'></a>__::term::ansi::code::ctrl::st__
Set Tab (@ current position)
- <a name='17'></a>__::term::ansi::code::ctrl::ct__
Clear Tab (@ current position)
- <a name='18'></a>__::term::ansi::code::ctrl::cat__
Clear All Tabs
- <a name='19'></a>__::term::ansi::code::ctrl::qdc__
Query Device Code
- <a name='20'></a>__::term::ansi::code::ctrl::qds__
Query Device Status
- <a name='21'></a>__::term::ansi::code::ctrl::qcp__
Query Cursor Position
- <a name='22'></a>__::term::ansi::code::ctrl::rd__
Reset Device
- <a name='23'></a>__::term::ansi::code::ctrl::elw__
Enable Line Wrap
- <a name='24'></a>__::term::ansi::code::ctrl::dlw__
Disable Line Wrap
- <a name='25'></a>__::term::ansi::code::ctrl::eg__
Enter Graphics Mode
- <a name='26'></a>__::term::ansi::code::ctrl::lg__
Exit Graphics Mode
- <a name='27'></a>__::term::ansi::code::ctrl::scs0__ *tag*
Set default character set
- <a name='28'></a>__::term::ansi::code::ctrl::scs1__ *tag*
Set alternate character set Select Character Set.
Choose which character set is used for either default (scs0) or alternate
font (scs1). This does not change whether default or alternate font are
used, only their definition.
The legal tags, and their meanings, are:
* A
United Kingdom Set
* B
ASCII Set
* 0
Special Graphics
* 1
Alternate Character ROM Standard Character Set
* 2
Alternate Character ROM Special Graphics
- <a name='29'></a>__::term::ansi::code::ctrl::sda__ *arg*...
Set Display Attributes. The arguments are the code sequences for the
possible attributes, as provided by the package
__[term::ansi::code::attr](ansi_cattr.md)__. For convenience this package
also provides additional commands each setting a single specific attribute.
- <a name='30'></a>__::term::ansi::code::ctrl::sda_fgblack__
Set text color to *Black*.
- <a name='31'></a>__::term::ansi::code::ctrl::sda_fgred__
Set text color to *Red*.
- <a name='32'></a>__::term::ansi::code::ctrl::sda_fggreen__
Set text color to *Green*.
- <a name='33'></a>__::term::ansi::code::ctrl::sda_fgyellow__
Set text color to *Yellow*.
- <a name='34'></a>__::term::ansi::code::ctrl::sda_fgblue__
Set text color to *Blue*.
- <a name='35'></a>__::term::ansi::code::ctrl::sda_fgmagenta__
Set text color to *Magenta*.
- <a name='36'></a>__::term::ansi::code::ctrl::sda_fgcyan__
Set text color to *Cyan*.
- <a name='37'></a>__::term::ansi::code::ctrl::sda_fgwhite__
Set text color to *White*.
- <a name='38'></a>__::term::ansi::code::ctrl::sda_fgdefault__
Set default text color (*Black*).
- <a name='39'></a>__::term::ansi::code::ctrl::sda_bgblack__
Set background to *Black*.
- <a name='40'></a>__::term::ansi::code::ctrl::sda_bgred__
Set background to *Red*.
- <a name='41'></a>__::term::ansi::code::ctrl::sda_bggreen__
Set background to *Green*.
- <a name='42'></a>__::term::ansi::code::ctrl::sda_bgyellow__
Set background to *Yellow*.
- <a name='43'></a>__::term::ansi::code::ctrl::sda_bgblue__
Set background to *Blue*.
- <a name='44'></a>__::term::ansi::code::ctrl::sda_bgmagenta__
Set background to *Magenta*.
- <a name='45'></a>__::term::ansi::code::ctrl::sda_bgcyan__
Set background to *Cyan*.
- <a name='46'></a>__::term::ansi::code::ctrl::sda_bgwhite__
Set background to *White*.
- <a name='47'></a>__::term::ansi::code::ctrl::sda_bgdefault__
Set default background (Transparent).
- <a name='48'></a>__::term::ansi::code::ctrl::sda_bold__
Bold on.
- <a name='49'></a>__::term::ansi::code::ctrl::sda_dim__
Dim on.
- <a name='50'></a>__::term::ansi::code::ctrl::sda_italic__
Italics on.
- <a name='51'></a>__::term::ansi::code::ctrl::sda_underline__
Underscore on.
- <a name='52'></a>__::term::ansi::code::ctrl::sda_blink__
Blink on.
- <a name='53'></a>__::term::ansi::code::ctrl::sda_revers__
Reverse on.
- <a name='54'></a>__::term::ansi::code::ctrl::sda_hidden__
Hidden on.
- <a name='55'></a>__::term::ansi::code::ctrl::sda_strike__
Strike-through on.
- <a name='56'></a>__::term::ansi::code::ctrl::sda_nobold__
Bold off.
- <a name='57'></a>__::term::ansi::code::ctrl::sda_noitalic__
Italics off.
- <a name='58'></a>__::term::ansi::code::ctrl::sda_nounderline__
Underscore off.
- <a name='59'></a>__::term::ansi::code::ctrl::sda_noblink__
Blink off.
- <a name='60'></a>__::term::ansi::code::ctrl::sda_norevers__
Reverse off.
- <a name='61'></a>__::term::ansi::code::ctrl::sda_nohidden__
Hidden off.
- <a name='62'></a>__::term::ansi::code::ctrl::sda_nostrike__
Strike-through off.
- <a name='63'></a>__::term::ansi::code::ctrl::sda_reset__
Reset all attributes to their default values.
- <a name='64'></a>__::term::ansi::send::fcp__ *row* *col*
Force Cursor Position (aka Go To).
- <a name='65'></a>__::term::ansi::code::ctrl::cu__ ?*n*?
Cursor Up. *n* defaults to 1.
- <a name='66'></a>__::term::ansi::code::ctrl::cd__ ?*n*?
Cursor Down. *n* defaults to 1.
- <a name='67'></a>__::term::ansi::code::ctrl::cf__ ?*n*?
Cursor Forward. *n* defaults to 1.
- <a name='68'></a>__::term::ansi::code::ctrl::cb__ ?*n*?
Cursor Backward. *n* defaults to 1.
- <a name='69'></a>__::term::ansi::code::ctrl::ss__ ?*s* *e*?
Scroll Screen (entire display, or between rows start end, inclusive).
- <a name='70'></a>__::term::ansi::code::ctrl::skd__ *code* *str*
Set Key Definition.
- <a name='71'></a>__::term::ansi::code::ctrl::title__ *str*
Set the terminal title.
- <a name='72'></a>__::term::ansi::code::ctrl::gron__
Switch to character/box graphics. I.e. switch to the alternate font.
- <a name='73'></a>__::term::ansi::code::ctrl::groff__
Switch to regular characters. I.e. switch to the default font.
- <a name='74'></a>__::term::ansi::code::ctrl::tlc__
Character graphics, Top Left Corner.
- <a name='75'></a>__::term::ansi::code::ctrl::trc__
Character graphics, Top Right Corner.
- <a name='76'></a>__::term::ansi::code::ctrl::brc__
Character graphics, Bottom Right Corner.
- <a name='77'></a>__::term::ansi::code::ctrl::blc__
Character graphics, Bottom Left Corner.
- <a name='78'></a>__::term::ansi::code::ctrl::ltj__
Character graphics, Left T Junction.
- <a name='79'></a>__::term::ansi::code::ctrl::ttj__
Character graphics, Top T Junction.
- <a name='80'></a>__::term::ansi::code::ctrl::rtj__
Character graphics, Right T Junction.
- <a name='81'></a>__::term::ansi::code::ctrl::btj__
Character graphics, Bottom T Junction.
- <a name='82'></a>__::term::ansi::code::ctrl::fwj__
Character graphics, Four-Way Junction.
- <a name='83'></a>__::term::ansi::code::ctrl::hl__
Character graphics, Horizontal Line.
- <a name='84'></a>__::term::ansi::code::ctrl::vl__
Character graphics, Vertical Line.
- <a name='85'></a>__::term::ansi::code::ctrl::groptim__ *str*
Optimize character graphics. The generator commands above create way to many
superfluous commands shifting into and out of the graphics mode. This
command removes all shifts which are not needed. To this end it also knows
which characters will look the same in both modes, to handle strings created
outside of this package.
- <a name='86'></a>__::term::ansi::code::ctrl::clear__
Clear screen. In essence a sequence of CursorHome + EraseDown.
- <a name='87'></a>__::term::ansi::code::ctrl::init__
Initialize default and alternate fonts to ASCII and box graphics.
- <a name='88'></a>__::term::ansi::code::ctrl::showat__ *row* *col* *text*
Format the block of text for display at the specified location.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[ansi](../../../../index.md#ansi), [attribute
control](../../../../index.md#attribute_control), [color
control](../../../../index.md#color_control),
[control](../../../../index.md#control),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/ansi_cmacros.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
[//000000001]: # (term::ansi::code::macros - Terminal control)
[//000000002]: # (Generated from file 'ansi_cmacros.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::ansi::code::macros(n) 0.1 tcllib "Terminal control")
# NAME
term::ansi::code::macros - Macro sequences
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Introspection](#subsection1)
- [Sequences](#subsection2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require textutil::repeat
package require textutil::tabify
package require term::ansi::code::macros ?0.1?
[__::term::ansi::code::macros::names__](#1)
[__::term::ansi::code::macros::import__ ?*ns*? ?*arg*...?](#2)
[__::term::ansi::code::macros::menu__ *menu*](#3)
[__::term::ansi::code::macros::frame__ *string*](#4)
# <a name='description'></a>DESCRIPTION
This package provides higher level control sequences for more complex shapes.
# <a name='section2'></a>API
## <a name='subsection1'></a>Introspection
- <a name='1'></a>__::term::ansi::code::macros::names__
This command is for introspection. It returns as its result a list
containing the names of all attribute commands.
- <a name='2'></a>__::term::ansi::code::macros::import__ ?*ns*? ?*arg*...?
This command imports some or all attribute commands into the namespace *ns*.
This is by default the namespace *macros*. Note that this is relative
namespace name, placing the imported command into a child of the current
namespace. By default all commands are imported, this can howver be
restricted by listing the names of the wanted commands after the namespace
argument.
## <a name='subsection2'></a>Sequences
- <a name='3'></a>__::term::ansi::code::macros::menu__ *menu*
The description of a menu is converted into a formatted rectangular block of
text, with the menu command characters highlighted using bold red text. The
result is returned as the result of the command.
The description, *menu*, is a dictionary mapping from menu label to command
character.
- <a name='4'></a>__::term::ansi::code::macros::frame__ *string*
The paragraph of text contained in the string is padded with spaces at the
right margin, after normalizing internal tabs, and then put into a frame
made of box-graphics. The result is returned as the result of the command.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[ansi](../../../../index.md#ansi), [control](../../../../index.md#control),
[frame](../../../../index.md#frame), [menu](../../../../index.md#menu),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/ansi_code.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
[//000000001]: # (term::ansi::code - Terminal control)
[//000000002]: # (Generated from file 'ansi_code.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::ansi::code(n) 0.2 tcllib "Terminal control")
# NAME
term::ansi::code - Helper for control sequences
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::ansi::code ?0.2?
[__::term::ansi::code::esc__ *str*](#1)
[__::term::ansi::code::escb__ *str*](#2)
[__::term::ansi::code::define__ *name* *escape* *code*](#3)
[__::term::ansi::code::const__ *name* *code*](#4)
# <a name='description'></a>DESCRIPTION
This package provides commands enabling the definition of control sequences in
an easy manner.
- <a name='1'></a>__::term::ansi::code::esc__ *str*
This command returns the argument string, prefixed with the ANSI escape
character, "\033."
- <a name='2'></a>__::term::ansi::code::escb__ *str*
This command returns the argument string, prefixed with a common ANSI escape
sequence, "\033[".
- <a name='3'></a>__::term::ansi::code::define__ *name* *escape* *code*
This command defines a procedure *name* which returns the control sequence
*code*, beginning with the specified escape sequence, either __esc__, or
__escb__.
- <a name='4'></a>__::term::ansi::code::const__ *name* *code*
This command defines a procedure *name* which returns the control sequence
*code*.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[control](../../../../index.md#control),
[declare](../../../../index.md#declare), [define](../../../../index.md#define),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/ansi_ctrlu.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
[//000000001]: # (term::ansi::ctrl::unix - Terminal control)
[//000000002]: # (Generated from file 'ansi_ctrlu.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::ansi::ctrl::unix(n) 0.1.1 tcllib "Terminal control")
# NAME
term::ansi::ctrl::unix - Control operations and queries
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Introspection](#subsection1)
- [Operations](#subsection2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::ansi::ctrl::unix ?0.1.1?
[__::term::ansi::ctrl::unix::import__ ?*ns*? ?*arg*...?](#1)
[__::term::ansi::ctrl::unix::raw__](#2)
[__::term::ansi::ctrl::unix::cooked__](#3)
[__::term::ansi::ctrl::unix::columns__](#4)
[__::term::ansi::ctrl::unix::rows__](#5)
# <a name='description'></a>DESCRIPTION
*WARNING*: This package is unix-specific and depends on the availability of two
unix system commands for terminal control, i.e. __stty__ and __tput__, both of
which have to be found in the __$PATH__. If any of these two commands is missing
the loading of the package will fail.
The package provides commands to switch the standard input of the current
process between *[raw](../../../../index.md#raw)* and
*[cooked](../../../../index.md#cooked)* input modes, and to query the size of
terminals, i.e. the available number of columns and lines.
# <a name='section2'></a>API
## <a name='subsection1'></a>Introspection
- <a name='1'></a>__::term::ansi::ctrl::unix::import__ ?*ns*? ?*arg*...?
This command imports some or all attribute commands into the namespace *ns*.
This is by default the namespace *ctrl*. Note that this is relative
namespace name, placing the imported command into a child of the current
namespace. By default all commands are imported, this can howver be
restricted by listing the names of the wanted commands after the namespace
argument.
## <a name='subsection2'></a>Operations
- <a name='2'></a>__::term::ansi::ctrl::unix::raw__
This command switches the standard input of the current process to
*[raw](../../../../index.md#raw)* input mode. This means that from then on
all characters typed by the user are immediately reported to the application
instead of waiting in the OS buffer until the Enter/Return key is received.
- <a name='3'></a>__::term::ansi::ctrl::unix::cooked__
This command switches the standard input of the current process to
*[cooked](../../../../index.md#cooked)* input mode. This means that from
then on all characters typed by the user are kept in OS buffers for editing
until the Enter/Return key is received.
- <a name='4'></a>__::term::ansi::ctrl::unix::columns__
This command queries the terminal connected to the standard input for the
number of columns available for display.
- <a name='5'></a>__::term::ansi::ctrl::unix::rows__
This command queries the terminal connected to the standard input for the
number of rows (aka lines) available for display.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[ansi](../../../../index.md#ansi), [columns](../../../../index.md#columns),
[control](../../../../index.md#control), [cooked](../../../../index.md#cooked),
[input mode](../../../../index.md#input_mode),
[lines](../../../../index.md#lines), [raw](../../../../index.md#raw),
[rows](../../../../index.md#rows), [terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/ansi_send.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
|
[//000000001]: # (term::ansi::send - Terminal control)
[//000000002]: # (Generated from file 'ansi_send.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::ansi::send(n) 0.2 tcllib "Terminal control")
# NAME
term::ansi::send - Output of ANSI control sequences to terminals
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::ansi::send ?0.2?
[__::term::ansi::send::import__ ?*ns*? *...*](#1)
[__::term::ansi::send::eeol__](#2)
[__::term::ansi::send::esol__](#3)
[__::term::ansi::send::el__](#4)
[__::term::ansi::send::ed__](#5)
[__::term::ansi::send::eu__](#6)
[__::term::ansi::send::es__](#7)
[__::term::ansi::send::sd__](#8)
[__::term::ansi::send::su__](#9)
[__::term::ansi::send::ch__](#10)
[__::term::ansi::send::sc__](#11)
[__::term::ansi::send::rc__](#12)
[__::term::ansi::send::sca__](#13)
[__::term::ansi::send::rca__](#14)
[__::term::ansi::send::st__](#15)
[__::term::ansi::send::ct__](#16)
[__::term::ansi::send::cat__](#17)
[__::term::ansi::send::qdc__](#18)
[__::term::ansi::send::qds__](#19)
[__::term::ansi::send::qcp__](#20)
[__::term::ansi::send::rd__](#21)
[__::term::ansi::send::elw__](#22)
[__::term::ansi::send::dlw__](#23)
[__::term::ansi::send::eg__](#24)
[__::term::ansi::send::lg__](#25)
[__::term::ansi::send::scs0__ *tag*](#26)
[__::term::ansi::send::scs1__ *tag*](#27)
[__::term::ansi::send::sda__ *arg*...](#28)
[__::term::ansi::send::sda_fgblack__](#29)
[__::term::ansi::send::sda_fgred__](#30)
[__::term::ansi::send::sda_fggreen__](#31)
[__::term::ansi::send::sda_fgyellow__](#32)
[__::term::ansi::send::sda_fgblue__](#33)
[__::term::ansi::send::sda_fgmagenta__](#34)
[__::term::ansi::send::sda_fgcyan__](#35)
[__::term::ansi::send::sda_fgwhite__](#36)
[__::term::ansi::send::sda_fgdefault__](#37)
[__::term::ansi::send::sda_bgblack__](#38)
[__::term::ansi::send::sda_bgred__](#39)
[__::term::ansi::send::sda_bggreen__](#40)
[__::term::ansi::send::sda_bgyellow__](#41)
[__::term::ansi::send::sda_bgblue__](#42)
[__::term::ansi::send::sda_bgmagenta__](#43)
[__::term::ansi::send::sda_bgcyan__](#44)
[__::term::ansi::send::sda_bgwhite__](#45)
[__::term::ansi::send::sda_bgdefault__](#46)
[__::term::ansi::send::sda_bold__](#47)
[__::term::ansi::send::sda_dim__](#48)
[__::term::ansi::send::sda_italic__](#49)
[__::term::ansi::send::sda_underline__](#50)
[__::term::ansi::send::sda_blink__](#51)
[__::term::ansi::send::sda_revers__](#52)
[__::term::ansi::send::sda_hidden__](#53)
[__::term::ansi::send::sda_strike__](#54)
[__::term::ansi::send::sda_nobold__](#55)
[__::term::ansi::send::sda_noitalic__](#56)
[__::term::ansi::send::sda_nounderline__](#57)
[__::term::ansi::send::sda_noblink__](#58)
[__::term::ansi::send::sda_norevers__](#59)
[__::term::ansi::send::sda_nohidden__](#60)
[__::term::ansi::send::sda_nostrike__](#61)
[__::term::ansi::send::sda_reset__](#62)
[__::term::ansi::send::fcp__ *row* *col*](#63)
[__::term::ansi::send::cu__ ?*n*?](#64)
[__::term::ansi::send::cd__ ?*n*?](#65)
[__::term::ansi::send::cf__ ?*n*?](#66)
[__::term::ansi::send::cb__ ?*n*?](#67)
[__::term::ansi::send::ss__ ?*s* *e*?](#68)
[__::term::ansi::send::skd__ *code* *str*](#69)
[__::term::ansi::send::title__ *str*](#70)
[__::term::ansi::send::gron__](#71)
[__::term::ansi::send::groff__](#72)
[__::term::ansi::send::tlc__](#73)
[__::term::ansi::send::trc__](#74)
[__::term::ansi::send::brc__](#75)
[__::term::ansi::send::blc__](#76)
[__::term::ansi::send::ltj__](#77)
[__::term::ansi::send::ttj__](#78)
[__::term::ansi::send::rtj__](#79)
[__::term::ansi::send::btj__](#80)
[__::term::ansi::send::fwj__](#81)
[__::term::ansi::send::hl__](#82)
[__::term::ansi::send::vl__](#83)
[__::term::ansi::send::groptim__ *str*](#84)
[__::term::ansi::send::clear__](#85)
[__::term::ansi::send::init__](#86)
[__::term::ansi::send::showat__ *row* *col* *text*](#87)
# <a name='description'></a>DESCRIPTION
This package provides commands to send ANSI terminal control sequences to a
terminal. All commands come in two variants, one for sending to any channel, the
other for sending to *stdout*.
The commands are defined using the control sequences provided by the package
__[term::ansi::code::ctrl](ansi_cctrl.md)__. They have the same arguments as the
commands they are based on, with the exception of the variant for sending to any
channel. Their first argument is always a channel handle, then followed by the
original arguments. Below we will list only the variant sending to *stdout*.
- <a name='1'></a>__::term::ansi::send::import__ ?*ns*? *...*
Imports the commands of this package into the namespace *ns*. If not
specified it defaults to *send*. Note that this default is a relative
namespace name, i.e. the actual namespace will be created under the current
namespace.
By default all commands will be imported, this can however be restricted to
specific commands, by listing them after the namespace to import them into.
- <a name='2'></a>__::term::ansi::send::eeol__
Erase (to) End Of Line.
- <a name='3'></a>__::term::ansi::send::esol__
Erase (to) Start Of Line.
- <a name='4'></a>__::term::ansi::send::el__
Erase (current) Line.
- <a name='5'></a>__::term::ansi::send::ed__
Erase Down (to bottom).
- <a name='6'></a>__::term::ansi::send::eu__
Erase Up (to top).
- <a name='7'></a>__::term::ansi::send::es__
Erase Screen.
- <a name='8'></a>__::term::ansi::send::sd__
Scroll Down.
- <a name='9'></a>__::term::ansi::send::su__
Scroll Up.
- <a name='10'></a>__::term::ansi::send::ch__
Cursor Home.
- <a name='11'></a>__::term::ansi::send::sc__
Save Cursor. Note: Only one saved position can be handled. This is no
unlimited stack. Saving before restoring will overwrite the saved data.
- <a name='12'></a>__::term::ansi::send::rc__
Restore Cursor (Unsave).
- <a name='13'></a>__::term::ansi::send::sca__
Save Cursor + Attributes.
- <a name='14'></a>__::term::ansi::send::rca__
Restore Cursor + Attributes.
- <a name='15'></a>__::term::ansi::send::st__
Set Tab (@ current position).
- <a name='16'></a>__::term::ansi::send::ct__
Clear Tab (@ current position).
- <a name='17'></a>__::term::ansi::send::cat__
Clear All Tabs.
- <a name='18'></a>__::term::ansi::send::qdc__
Query Device Code.
- <a name='19'></a>__::term::ansi::send::qds__
Query Device Status.
- <a name='20'></a>__::term::ansi::send::qcp__
Query Cursor Position.
- <a name='21'></a>__::term::ansi::send::rd__
Reset Device.
- <a name='22'></a>__::term::ansi::send::elw__
Enable Line Wrap.
- <a name='23'></a>__::term::ansi::send::dlw__
Disable Line Wrap.
- <a name='24'></a>__::term::ansi::send::eg__
Enter Graphics Mode.
- <a name='25'></a>__::term::ansi::send::lg__
Exit Graphics Mode.
- <a name='26'></a>__::term::ansi::send::scs0__ *tag*
- <a name='27'></a>__::term::ansi::send::scs1__ *tag*
Select Character Set.
Choose which character set is used for default (scs0) and alternate font
(scs1). This does not change whether default or alternate font are used,
just their definitions.
The legal tags, and their meanings, are:
* A
United Kingdom Set
* B
ASCII Set
* 0
Special Graphics
* 1
Alternate Character ROM Standard Character Set
* 2
Alternate Character ROM Special Graphics
- <a name='28'></a>__::term::ansi::send::sda__ *arg*...
Set Display Attributes. The arguments are the code sequences for the
possible attributes, as provided by the package
__[term::ansi::code::attr](ansi_cattr.md)__. For convenience this package
also provides additional commands each setting a single specific attribute.
- <a name='29'></a>__::term::ansi::send::sda_fgblack__
Set text color to *Black*.
- <a name='30'></a>__::term::ansi::send::sda_fgred__
Set text color to *Red*.
- <a name='31'></a>__::term::ansi::send::sda_fggreen__
Set text color to *Green*.
- <a name='32'></a>__::term::ansi::send::sda_fgyellow__
Set text color to *Yellow*.
- <a name='33'></a>__::term::ansi::send::sda_fgblue__
Set text color to *Blue*.
- <a name='34'></a>__::term::ansi::send::sda_fgmagenta__
Set text color to *Magenta*.
- <a name='35'></a>__::term::ansi::send::sda_fgcyan__
Set text color to *Cyan*.
- <a name='36'></a>__::term::ansi::send::sda_fgwhite__
Set text color to *White*.
- <a name='37'></a>__::term::ansi::send::sda_fgdefault__
Set default text color (*Black*).
- <a name='38'></a>__::term::ansi::send::sda_bgblack__
Set background to *Black*.
- <a name='39'></a>__::term::ansi::send::sda_bgred__
Set background to *Red*.
- <a name='40'></a>__::term::ansi::send::sda_bggreen__
Set background to *Green*.
- <a name='41'></a>__::term::ansi::send::sda_bgyellow__
Set background to *Yellow*.
- <a name='42'></a>__::term::ansi::send::sda_bgblue__
Set background to *Blue*.
- <a name='43'></a>__::term::ansi::send::sda_bgmagenta__
Set background to *Magenta*.
- <a name='44'></a>__::term::ansi::send::sda_bgcyan__
Set background to *Cyan*.
- <a name='45'></a>__::term::ansi::send::sda_bgwhite__
Set background to *White*.
- <a name='46'></a>__::term::ansi::send::sda_bgdefault__
Set default background (Transparent).
- <a name='47'></a>__::term::ansi::send::sda_bold__
Bold on.
- <a name='48'></a>__::term::ansi::send::sda_dim__
Dim on.
- <a name='49'></a>__::term::ansi::send::sda_italic__
Italics on.
- <a name='50'></a>__::term::ansi::send::sda_underline__
Underscore on.
- <a name='51'></a>__::term::ansi::send::sda_blink__
Blink on.
- <a name='52'></a>__::term::ansi::send::sda_revers__
Reverse on.
- <a name='53'></a>__::term::ansi::send::sda_hidden__
Hidden on.
- <a name='54'></a>__::term::ansi::send::sda_strike__
Strike-through on.
- <a name='55'></a>__::term::ansi::send::sda_nobold__
Bold off.
- <a name='56'></a>__::term::ansi::send::sda_noitalic__
Italics off.
- <a name='57'></a>__::term::ansi::send::sda_nounderline__
Underscore off.
- <a name='58'></a>__::term::ansi::send::sda_noblink__
Blink off.
- <a name='59'></a>__::term::ansi::send::sda_norevers__
Reverse off.
- <a name='60'></a>__::term::ansi::send::sda_nohidden__
Hidden off.
- <a name='61'></a>__::term::ansi::send::sda_nostrike__
Strike-through off.
- <a name='62'></a>__::term::ansi::send::sda_reset__
Reset all attributes to their default values.
- <a name='63'></a>__::term::ansi::send::fcp__ *row* *col*
Force Cursor Position (aka Go To).
- <a name='64'></a>__::term::ansi::send::cu__ ?*n*?
Cursor Up. *n* defaults to 1.
- <a name='65'></a>__::term::ansi::send::cd__ ?*n*?
Cursor Down. *n* defaults to 1.
- <a name='66'></a>__::term::ansi::send::cf__ ?*n*?
Cursor Forward. *n* defaults to 1.
- <a name='67'></a>__::term::ansi::send::cb__ ?*n*?
Cursor Backward. *n* defaults to 1.
- <a name='68'></a>__::term::ansi::send::ss__ ?*s* *e*?
Scroll Screen (entire display, or between rows start end, inclusive).
- <a name='69'></a>__::term::ansi::send::skd__ *code* *str*
Set Key Definition.
- <a name='70'></a>__::term::ansi::send::title__ *str*
Set the terminal title.
- <a name='71'></a>__::term::ansi::send::gron__
Switch to character/box graphics. I.e. switch to the alternate font.
- <a name='72'></a>__::term::ansi::send::groff__
Switch to regular characters. I.e. switch to the default font.
- <a name='73'></a>__::term::ansi::send::tlc__
Character graphics, Top Left Corner.
- <a name='74'></a>__::term::ansi::send::trc__
Character graphics, Top Right Corner.
- <a name='75'></a>__::term::ansi::send::brc__
Character graphics, Bottom Right Corner.
- <a name='76'></a>__::term::ansi::send::blc__
Character graphics, Bottom Left Corner.
- <a name='77'></a>__::term::ansi::send::ltj__
Character graphics, Left T Junction.
- <a name='78'></a>__::term::ansi::send::ttj__
Character graphics, Top T Junction.
- <a name='79'></a>__::term::ansi::send::rtj__
Character graphics, Right T Junction.
- <a name='80'></a>__::term::ansi::send::btj__
Character graphics, Bottom T Junction.
- <a name='81'></a>__::term::ansi::send::fwj__
Character graphics, Four-Way Junction.
- <a name='82'></a>__::term::ansi::send::hl__
Character graphics, Horizontal Line.
- <a name='83'></a>__::term::ansi::send::vl__
Character graphics, Vertical Line.
- <a name='84'></a>__::term::ansi::send::groptim__ *str*
Optimize character graphics. The generator commands above create way to many
superfluous commands shifting into and out of the graphics mode. This
command removes all shifts which are not needed. To this end it also knows
which characters will look the same in both modes, to handle strings created
outside of this package.
- <a name='85'></a>__::term::ansi::send::clear__
Clear screen. In essence a sequence of CursorHome + EraseDown.
- <a name='86'></a>__::term::ansi::send::init__
Initialize default and alternate fonts to ASCII and box graphics.
- <a name='87'></a>__::term::ansi::send::showat__ *row* *col* *text*
Show the block of text at the specified location.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[character output](../../../../index.md#character_output),
[control](../../../../index.md#control),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/imenu.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
[//000000001]: # (term::interact::menu - Terminal control)
[//000000002]: # (Generated from file 'imenu.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::interact::menu(n) 0.1 tcllib "Terminal control")
# NAME
term::interact::menu - Terminal widget, menu
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Object API](#section3)
- [Configuration](#section4)
- [Interaction](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::interact::menu ?0.1?
[__term::interact::menu__ *object* *dict* ?*options*...?](#1)
[*object* __interact__](#2)
[*object* __done__](#3)
[*object* __clear__](#4)
[*object* __configure__](#5)
[*object* __configure__ *option*](#6)
[*object* __configure__ *option* *value*...](#7)
[*object* __cget__ *option*](#8)
# <a name='description'></a>DESCRIPTION
This package provides a class for the creation of a simple menu control.
# <a name='section2'></a>Class API
The package exports a single command, the class command, enabling the creation
of menu instances. Its API is:
- <a name='1'></a>__term::interact::menu__ *object* *dict* ?*options*...?
This command creates a new menu object with the name *object*, initializes
it, and returns the fully qualified name of the object command as its
result.
The argument is the menu to show, possibly followed by configuration options
and their values. The options are explained in the section
[Configuration](#section4). The menu is a dictionary maping labels to
symbolic action codes.
# <a name='section3'></a>Object API
The objects created by the class command provide the methods listed below:
- <a name='2'></a>*object* __interact__
Shows the menu in the screen at the configured location and starts
interacting with it. This opens its own event loop for the processing of
incoming characters. The method returns when the interaction has completed.
See section [Interaction](#section5) for a description of the possible
interaction.
The method returns the symbolic action of the menu item selected by the user
at the end of the interaction.
- <a name='3'></a>*object* __done__
This method can be used by user supplied actions to terminate the
interaction with the object.
- <a name='4'></a>*object* __clear__
This method can be used by user supplied actions to remove the menu from the
terminal.
- <a name='5'></a>*object* __configure__
- <a name='6'></a>*object* __configure__ *option*
- <a name='7'></a>*object* __configure__ *option* *value*...
- <a name='8'></a>*object* __cget__ *option*
Standard methods to retrieve and configure the options of the menu.
# <a name='section4'></a>Configuration
A menu instance recognizes the following options:
- __-in__ chan
Specifies the channel to read character sequences from. Defaults to
__stdin__.
- __-out__ chan
Specifies the channel to write the menu contents to. Defaults to __stdout__.
- __-column__ int
Specifies the column of the terminal where the left margin of the menu
display should appear. Defaults to 0, i.e. the left-most column.
- __-line__ int
Specifies the line of the terminal where the top margin of the menu display
should appear. Defaults to 0, i.e. the top-most line.
- __-height__ int
Specifies the number of lines of text to show at most in the display.
Defaults to 25.
- __-actions__ dict
Specifies a dictionary containing additional actions, using character
sequences as keys. Note that these sequences cannot override the hardwired
sequences described in section [Interaction](#section5).
- __-hilitleft__ int
- __-hilitright__ int
By default the entire selected menu entry is highlighted in revers output.
However, when present these two options restrict revers dispay to the
specified sub-range of the entry.
- __-framed__ bool
By default the menu is shown using only header and footer out of characters
box graphics. If this flag is set the menu is fully enclosed in a box.
# <a name='section5'></a>Interaction
A menu object recognizes the control sequences listed below and acts as
described. The user can supply more control sequences to act on via the
configuration, but is not able to overide these defaults.
- Cursor Up
The selection is moved up one entry, except if the first entry of the menu
is already selected.
- Cursor Down
The selection is moved down one entry, except if the last entry of the menu
is already selected.
- Enter/Return
The interaction with the object is terminated.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[control](../../../../index.md#control), [menu](../../../../index.md#menu),
[terminal](../../../../index.md#terminal), [text
display](../../../../index.md#text_display)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/ipager.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
[//000000001]: # (term::interact::pager - Terminal control)
[//000000002]: # (Generated from file 'ipager.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::interact::pager(n) 0.1 tcllib "Terminal control")
# NAME
term::interact::pager - Terminal widget, paging
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Object API](#section3)
- [Configuration](#section4)
- [Interaction](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::interact::pager ?0.1?
[__term::interact::pager__ *object* *text* ?*options*...?](#1)
[*object* __interact__](#2)
[*object* __done__](#3)
[*object* __clear__](#4)
[*object* __text__ *text*](#5)
[*object* __configure__](#6)
[*object* __configure__ *option*](#7)
[*object* __configure__ *option* *value*...](#8)
[*object* __cget__ *option*](#9)
# <a name='description'></a>DESCRIPTION
This package provides a class for the creation of a simple paging text display.
# <a name='section2'></a>Class API
The package exports a single command, the class command, enabling the creation
of pager instances. Its API is:
- <a name='1'></a>__term::interact::pager__ *object* *text* ?*options*...?
This command creates a new pager object with the name *object*, initializes
it, and returns the fully qualified name of the object command as its
result.
The argument is the text to show, possibly followed by configuration options
and their values. The options are explained in the section
[Configuration](#section4).
# <a name='section3'></a>Object API
The objects created by the class command provide the methods listed below:
- <a name='2'></a>*object* __interact__
Show the pager in the screen at the configured location and start
interacting with it. This opens its own event loop for the processing of
incoming characters. The method returns when the interaction has completed.
See section [Interaction](#section5) for a description of the possible
interaction.
- <a name='3'></a>*object* __done__
This method can be used by user supplied actions to terminate the
interaction with the object.
- <a name='4'></a>*object* __clear__
This method can be used by user supplied actions to remove the pager from
the terminal.
- <a name='5'></a>*object* __text__ *text*
This method can be used to change the text shown by the pager. The pager
will reset the dispay to show the first line of the text at the top.
- <a name='6'></a>*object* __configure__
- <a name='7'></a>*object* __configure__ *option*
- <a name='8'></a>*object* __configure__ *option* *value*...
- <a name='9'></a>*object* __cget__ *option*
Standard methods to retrieve and configure the options of the pager.
# <a name='section4'></a>Configuration
A pager instance recognizes the following options:
- __-in__ chan
Specifies the channel to read character sequences from. Defaults to
__stdin__.
- __-out__ chan
Specifies the channel to write the pager contents to. Defaults to
__stdout__.
- __-column__ int
Specifies the column of the terminal where the left margin of the pager
display should appear. Defaults to 0, i.e. the left-most column.
- __-line__ int
Specifies the line of the terminal where the top margin of the pager display
should appear. Defaults to 0, i.e. the top-most line.
- __-height__ int
Specifies the number of lines of text to show at most in the display.
Defaults to 25.
- __-actions__ dict
Specifies a dictionary containing additional actions, using character
sequences as keys. Note that these sequences cannot override the hardwired
sequences described in section [Interaction](#section5).
# <a name='section5'></a>Interaction
A pager object recognizes the control sequences listed below and acts as
described. The user can supply more control sequences to act on via the
configuration, but is not able to overide these defaults.
- Cursor Up
The text is scrolled down a single line, making one more line visible at the
top. The pager will not react if the first line of the text is already
shown.
- Cursor Down
The text is scrolled up a single line, making one more line visible at the
bottom. The pager will not react if the last line of the text is already
shown.
- Page Up
The text is scrolled down a page. The pager will not react if the first line
of the text is already shown.
- Page Down
The text is scrolled up a page. The pager will not react if the last line of
the text is already shown.
- Enter/Return
The interaction with the object is terminated.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[control](../../../../index.md#control), [pager](../../../../index.md#pager),
[terminal](../../../../index.md#terminal), [text
display](../../../../index.md#text_display)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/receive.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
[//000000001]: # (term::receive - Terminal control)
[//000000002]: # (Generated from file 'receive.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::receive(n) 0.1 tcllib "Terminal control")
# NAME
term::receive - General input from terminals
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::receive ?0.1?
[__::term::receive::getch__ ?*chan*?](#1)
[__::term::receive::listen__ *cmd* ?*chan*?](#2)
[*cmd* __process__ *string*](#3)
[*cmd* __eof__](#4)
[__::term::receive::unlisten__ ?*chan*?](#5)
# <a name='description'></a>DESCRIPTION
This package provides the most primitive commands for receiving characters to a
terminal. They are in essence convenient wrappers around the builtin commands
__[read](../../../../index.md#read)__ and __fileevent__.
- <a name='1'></a>__::term::receive::getch__ ?*chan*?
This command reads a single character from the channel with handle *chan*
and returns it as the result of the command.
If not specified *chan* defaults to __stdin__.
It is the responsibility of the caller to make sure that the channel can
provide single characters. On unix this can be done, for example, by using
the command of package __[term::ansi::ctrl::unix](ansi_ctrlu.md)__.
- <a name='2'></a>__::term::receive::listen__ *cmd* ?*chan*?
This command sets up a filevent listener for the channel with handle *chan*
and invokes the command prefix *cmd* whenever characters have been received,
or EOF was reached.
If not specified *chan* defaults to __stdin__.
The signature of the command prefix is
* <a name='3'></a>*cmd* __process__ *string*
This method is invoked when characters were received, and *string* holds
them for processing.
* <a name='4'></a>*cmd* __eof__
This method is invoked when EOF was reached on the channel we listen on.
It will be the last call to be received by the callback.
- <a name='5'></a>__::term::receive::unlisten__ ?*chan*?
This command disables the filevent listener for the channel with handle
*chan*.
If not specified *chan* defaults to __stdin__.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[character input](../../../../index.md#character_input),
[control](../../../../index.md#control), [get
character](../../../../index.md#get_character),
[listener](../../../../index.md#listener),
[receiver](../../../../index.md#receiver),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/term.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
[//000000001]: # (term - Terminal control)
[//000000002]: # (Generated from file 'term.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term(n) 0.1 tcllib "Terminal control")
# NAME
term - General terminal control
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term ?0.1?
# <a name='description'></a>DESCRIPTION
It is planned to have this package provide highlevel general terminal control
commands, in the vein of ncurses or similar packages. Currently nothing has been
implemented however. I.e. this package is empty. It can be loaded, yet provides
nothing.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[control](../../../../index.md#control),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/term_bind.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
[//000000001]: # (term::receive::bind - Terminal control)
[//000000002]: # (Generated from file 'term_bind.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::receive::bind(n) 0.1 tcllib "Terminal control")
# NAME
term::receive::bind - Keyboard dispatch from terminals
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Object API](#section3)
- [Notes](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::receive::bind ?0.1?
[__term::receive::bind__ *object* ?*map*?](#1)
[*object* __map__ *str* *cmd*](#2)
[*object* __default__ *cmd*](#3)
[*object* __listen__ ?*chan*?](#4)
[*object* __unlisten__ ?*chan*?](#5)
[*object* __reset__](#6)
[*object* __next__ *char*](#7)
[*object* __process__ *str*](#8)
[*object* __eof__](#9)
# <a name='description'></a>DESCRIPTION
This package provides a class for the creation of simple dispatchers from
character sequences to actions. Internally each dispatcher is in essence a
deterministic finite automaton with tree structure.
# <a name='section2'></a>Class API
The package exports a single command, the class command, enabling the creation
of dispatcher instances. Its API is:
- <a name='1'></a>__term::receive::bind__ *object* ?*map*?
This command creates a new dispatcher object with the name *object*,
initializes it, and returns the fully qualified name of the object command
as its result.
The argument is a dictionary mapping from strings, i.e. character sequences
to the command prefices to invoke when the sequence is found in the input
stream.
# <a name='section3'></a>Object API
The objects created by the class command provide the methods listed below:
- <a name='2'></a>*object* __map__ *str* *cmd*
This method adds an additional mapping from the string *str* to the action
*cmd*. The mapping will take effect immediately should the processor be in a
prefix of *str*, or at the next reset operation. The action is a command
prefix and will be invoked with one argument appended to it, the character
sequence causing the invokation. It is executed in the global namespace.
- <a name='3'></a>*object* __default__ *cmd*
This method defines a default action *cmd* which will be invoked whenever an
unknown character sequence is encountered. The command prefix is handled in
the same as the regular action defined via method __map__.
- <a name='4'></a>*object* __listen__ ?*chan*?
This methods sets up a filevent listener for the channel with handle *chan*
and invokes the dispatcher object whenever characters have been received, or
EOF was reached.
If not specified *chan* defaults to __stdin__.
- <a name='5'></a>*object* __unlisten__ ?*chan*?
This methods removes the filevent listener for the channel with handle
*chan*.
If not specified *chan* defaults to __stdin__.
- <a name='6'></a>*object* __reset__
This method resets the character processor to the beginning of the tree.
- <a name='7'></a>*object* __next__ *char*
This method causes the character processor to process the character *c*.
This may simply advance the internal state, or invoke an associated action
for a recognized sequence.
- <a name='8'></a>*object* __process__ *str*
This method causes the character processor to process the character sequence
*str*, advancing the internal state and invoking action as necessary. This
is a callback for __listen__.
- <a name='9'></a>*object* __eof__
This method causes the character processor to handle EOF on the input. This
is currently no-op. This is a callback for __listen__.
# <a name='section4'></a>Notes
The simplicity of the DFA means that it is not possible to recognize a character
sequence with has a another recognized character sequence as its prefix.
In other words, the set of recognized strings has to form a *prefix code*.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[character input](../../../../index.md#character_input),
[control](../../../../index.md#control),
[dispatcher](../../../../index.md#dispatcher),
[listener](../../../../index.md#listener),
[receiver](../../../../index.md#receiver),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/term/term_send.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
|
[//000000001]: # (term::send - Terminal control)
[//000000002]: # (Generated from file 'term_send.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (term::send(n) 0.1 tcllib "Terminal control")
# NAME
term::send - General output to terminals
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require term::send ?0.1?
[__::term::send::wrch__ *chan* *str*](#1)
[__::term::send::wr__ *str*](#2)
# <a name='description'></a>DESCRIPTION
This package provides the most primitive commands for sending characters to a
terminal. They are in essence convenient wrappers around the builtin command
__puts__.
- <a name='1'></a>__::term::send::wrch__ *chan* *str*
Send the text *str* to the channel specified by the handle *chan*. In
contrast to the builtin command __puts__ this command does not terminate the
string with a line terminator. It also forces an flush of Tcl internal and
OS buffers to ensure that the characters are processed immediately.
- <a name='2'></a>__::term::send::wr__ *str*
This convenience command is like __::term::send::wrch__, except that the
destination channel is fixed to *stdout*.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *term* 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.
# <a name='keywords'></a>KEYWORDS
[character output](../../../../index.md#character_output),
[control](../../../../index.md#control),
[terminal](../../../../index.md#terminal)
# <a name='category'></a>CATEGORY
Terminal control
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/textutil/adjust.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
[//000000001]: # (textutil::adjust - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'adjust.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::adjust(n) 0.7.3 tcllib "Text and string utilities, macro processing")
# NAME
textutil::adjust - Procedures to adjust, indent, and undent paragraphs
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::adjust ?0.7.3?
[__::textutil::adjust::adjust__ *string* ?*option value...*?](#1)
[__::textutil::adjust::readPatterns__ *filename*](#2)
[__::textutil::adjust::listPredefined__](#3)
[__::textutil::adjust::getPredefined__ *filename*](#4)
[__::textutil::adjust::indent__ *string* *prefix* ?*skip*?](#5)
[__::textutil::adjust::undent__ *string*](#6)
# <a name='description'></a>DESCRIPTION
The package __textutil::adjust__ provides commands that manipulate strings or
texts (a.k.a. long strings or string with embedded newlines or paragraphs),
adjusting, or indenting them.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::adjust::adjust__ *string* ?*option value...*?
Do a justification on the *string* according to the options. The string is
taken as one big paragraph, ignoring any newlines. Then the line is
formatted according to the options used, and the command returns a new
string with enough lines to contain all the printable chars in the input
string. A line is a set of characters between the beginning of the string
and a newline, or between 2 newlines, or between a newline and the end of
the string. If the input string is small enough, the returned string won't
contain any newlines.
Together with __::textutil::adjust::indent__ it is possible to create
properly wrapped paragraphs with arbitrary indentations.
By default, any occurrence of space or tabulation characters are replaced by
a single space so that each word in a line is separated from the next one by
exactly one space character, and this forms a *real* line. Each *real* line
is placed in a *logical* line, which has exactly a given length (see the
option __-length__ below). The *real* line may be shorter. Again by default,
trailing spaces are ignored before returning the string (see the option
__-full__ below).
The following options may be used after the *string* parameter, and change
the way the command places a *real* line in a *logical* line.
* __-full__ *boolean*
If set to __false__ (default), trailing space characters are deleted
before returning the string. If set to __true__, any trailing space
characters are left in the string.
* __-hyphenate__ *boolean*
If set to __false__ (default), no hyphenation will be done. If set to
__true__, the command will try to hyphenate the last word of a line.
*Note*: Hyphenation patterns must be loaded prior, using the command
__::textutil::adjust::readPatterns__.
* __-justify__ __center|left|plain|right__
Sets the justification of the returned string to either __left__
(default), __center__, __plain__ or __right__. The justification means
that any line in the returned string but the last one is build according
to the value. If the justification is set to __plain__ and the number of
printable chars in the last line is less than 90% of the length of a
line (see the option __-length__), then this line is justified with the
__left__ value, avoiding the expansion of this line when it is too
small. The meaning of each value is:
+ __center__
The real line is centered in the logical line. If needed, a set of
space characters are added at the beginning (half of the needed set)
and at the end (half of the needed set) of the line if required (see
the option __-full__).
+ __left__
The real line is set on the left of the logical line. It means that
there are no space chars at the beginning of this line. If required,
all needed space chars are added at the end of the line (see the
option __-full__).
+ __plain__
The real line is exactly set in the logical line. It means that
there are no leading or trailing space chars. All the needed space
chars are added in the *real* line, between 2 (or more) words.
+ __right__
The real line is set on the right of the logical line. It means that
there are no space chars at the end of this line, and there may be
some space chars at the beginning, despite of the __-full__ option.
* __-length__ *integer*
Set the length of the *logical* line in the string to *integer*.
*integer* must be a positive integer value. Defaults to __72__.
* __-strictlength__ *boolean*
If set to __false__ (default), a line can exceed the specified
__-length__ if a single word is longer than __-length__. If set to
__true__, words that are longer than __-length__ are split so that no
line exceeds the specified __-length__.
- <a name='2'></a>__::textutil::adjust::readPatterns__ *filename*
Loads the internal storage for hyphenation patterns with the contents of the
file *filename*. This has to be done prior to calling command
__::textutil::adjust::adjust__ with "__-hyphenate__ __true__", or the
hyphenation process will not work correctly.
The package comes with a number of predefined pattern files, and the command
__::textutil::adjust::listPredefined__ can be used to find out their names.
- <a name='3'></a>__::textutil::adjust::listPredefined__
This command returns a list containing the names of the hyphenation files
coming with this package.
- <a name='4'></a>__::textutil::adjust::getPredefined__ *filename*
Use this command to query the package for the full path name of the
hyphenation file *filename* coming with the package. Only the filenames
found in the list returned by __::textutil::adjust::listPredefined__ are
legal arguments for this command.
- <a name='5'></a>__::textutil::adjust::indent__ *string* *prefix* ?*skip*?
Each line in the *string* is indented by adding the string *prefix* at its
beginning. The modified string is returned as the result of the command.
If *skip* is specified the first *skip* lines are left untouched. The
default for *skip* is __0__, causing the modification of all lines. Negative
values for *skip* are treated like __0__. In other words, *skip* > __0__
creates a hanging indentation.
Together with __::textutil::adjust::adjust__ it is possible to create
properly wrapped paragraphs with arbitrary indentations.
- <a name='6'></a>__::textutil::adjust::undent__ *string*
The command computes the common prefix for all lines in *string* consisting
solely out of whitespace, removes this from each line and returns the
modified string.
Lines containing only whitespace are always reduced to completely empty
lines. They and empty lines are also ignored when computing the prefix to
remove.
Together with __::textutil::adjust::adjust__ it is possible to create
properly wrapped paragraphs with arbitrary indentations.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[TeX](../../../../index.md#tex), [adjusting](../../../../index.md#adjusting),
[formatting](../../../../index.md#formatting),
[hyphenation](../../../../index.md#hyphenation),
[indenting](../../../../index.md#indenting),
[justification](../../../../index.md#justification),
[paragraph](../../../../index.md#paragraph),
[string](../../../../index.md#string),
[undenting](../../../../index.md#undenting)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/textutil/expander.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
|
[//000000001]: # (textutil::expander - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'expander.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::expander(n) 1.3.1 tcllib "Text and string utilities, macro processing")
# NAME
textutil::expander - Procedures to process templates and expand text.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXPANDER API](#section2)
- [TUTORIAL](#section3)
- [Basics](#subsection1)
- [Embedding Macros](#subsection2)
- [Writing Macro Commands](#subsection3)
- [Changing the Expansion Brackets](#subsection4)
- [Customized Macro Expansion](#subsection5)
- [Using the Context Stack](#subsection6)
- [HISTORY](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::expander ?1.3.1?
[__::textutil::expander__ *expanderName*](#1)
[*expanderName* __cappend__ *text*](#2)
[*expanderName* __cget__ *varname*](#3)
[*expanderName* __cis__ *cname*](#4)
[*expanderName* __cname__](#5)
[*expanderName* __cpop__ *cname*](#6)
[*expanderName* __ctopandclear__](#7)
[*expanderName* __cpush__ *cname*](#8)
[*expanderName* __cset__ *varname* *value*](#9)
[*expanderName* __cvar__ *varname*](#10)
[*expanderName* __errmode__ *newErrmode*](#11)
[*expanderName* __evalcmd__ ?*newEvalCmd*?](#12)
[*expanderName* __expand__ *string* ?*brackets*?](#13)
[*expanderName* __lb__ ?*newbracket*?](#14)
[*expanderName* __rb__ ?*newbracket*?](#15)
[*expanderName* __reset__](#16)
[*expanderName* __setbrackets__ *lbrack rbrack*](#17)
[*expanderName* __textcmd__ ?*newTextCmd*?](#18)
[*expanderName* __where__](#19)
# <a name='description'></a>DESCRIPTION
The Tcl __[subst](../../../../index.md#subst)__ command is often used to support
a kind of template processing. Given a string with embedded variables or
function calls, __[subst](../../../../index.md#subst)__ will interpolate the
variable and function values, returning the new string:
% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% subst {$greeting, [place]!}
Howdy, World!
%
By defining a suitable set of Tcl commands,
__[subst](../../../../index.md#subst)__ can be used to implement a markup
language similar to HTML.
The __[subst](../../../../index.md#subst)__ command is efficient, but it has
three drawbacks for this kind of template processing:
- There's no way to identify and process the plain text between two embedded
Tcl commands; that makes it difficult to handle plain text in a
context-sensitive way.
- Embedded commands are necessarily bracketed by __[__ and __]__; it's
convenient to be able to choose different brackets in special cases. Someone
producing web pages that include a large quantity of Tcl code examples might
easily prefer to use __<<__ and __>>__ as the embedded code delimiters
instead.
- There's no easy way to handle incremental input, as one might wish to do
when reading data from a socket.
At present, expander solves the first two problems; eventually it will solve the
third problem as well.
The following section describes the command API to the expander; this is
followed by the tutorial sections, see [TUTORIAL](#section3).
# <a name='section2'></a>EXPANDER API
The __textutil::expander__ package provides only one command, described below.
The rest of the section is taken by a description of the methods for the
expander objects created by this command.
- <a name='1'></a>__::textutil::expander__ *expanderName*
The command creates a new expander object with an associated Tcl command
whose name is *expanderName*. This command may be used to invoke various
operations on the graph. If the *expanderName* is not fully qualified it is
interpreted as relative to the current namespace. The command has the
following general form:
*expanderName* option ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
The following commands are possible for expander objects:
- <a name='2'></a>*expanderName* __cappend__ *text*
Appends a string to the output in the current context. This command should
rarely be used by macros or application code.
- <a name='3'></a>*expanderName* __cget__ *varname*
Retrieves the value of variable *varname*, defined in the current context.
- <a name='4'></a>*expanderName* __cis__ *cname*
Determines whether or not the name of the current context is *cname*.
- <a name='5'></a>*expanderName* __cname__
Returns the name of the current context.
- <a name='6'></a>*expanderName* __cpop__ *cname*
Pops a context from the context stack, returning all accumulated output in
that context. The context must be named *cname*, or an error results.
- <a name='7'></a>*expanderName* __ctopandclear__
Returns the output currently captured in the topmost context and clears that
buffer. This is similar to a combination of __cpop__ followed by __cpush__,
except that internal state (brackets) is preserved here.
- <a name='8'></a>*expanderName* __cpush__ *cname*
Pushes a context named *cname* onto the context stack. The context must be
popped by __cpop__ before expansion ends or an error results.
- <a name='9'></a>*expanderName* __cset__ *varname* *value*
Sets variable *varname* to *value* in the current context.
- <a name='10'></a>*expanderName* __cvar__ *varname*
Retrieves the internal variable name of context variable *varname*; this
allows the variable to be passed to commands like __lappend__.
- <a name='11'></a>*expanderName* __errmode__ *newErrmode*
Sets the macro expansion error mode to one of __nothing__, __macro__,
__error__, or __fail__; the default value is __fail__. The value determines
what the expander does if an error is detected during expansion of a macro.
* __fail__
The error propagates normally and can be caught or ignored by the
application.
* __error__
The macro expands into a detailed error message, and expansion
continues.
* __macro__
The macro expands to itself; that is, it is passed along to the output
unchanged.
* __nothing__
The macro expands to the empty string, and is effectively ignored.
- <a name='12'></a>*expanderName* __evalcmd__ ?*newEvalCmd*?
Returns the current evaluation command, which defaults to __uplevel #0__. If
specified, *newEvalCmd* will be saved for future use and then returned; it
must be a Tcl command expecting one additional argument: the macro to
evaluate.
- <a name='13'></a>*expanderName* __expand__ *string* ?*brackets*?
Expands the input string, replacing embedded macros with their expanded
values, and returns the expanded string.
Note that this method pushes a new (empty) context on the stack of contexts
while it is running, and removes it on return.
If *brackets* is given, it must be a list of two strings; the items will be
used as the left and right macro expansion bracket sequences for this
expansion only.
- <a name='14'></a>*expanderName* __lb__ ?*newbracket*?
Returns the current value of the left macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
- <a name='15'></a>*expanderName* __rb__ ?*newbracket*?
Returns the current value of the right macro expansion bracket; this is for
use as or within a macro, when the bracket needs to be included in the
output text. If *newbracket* is specified, it becomes the new bracket, and
is returned.
- <a name='16'></a>*expanderName* __reset__
Resets all expander settings to their initial values. Unusual results are
likely if this command is called from within a call to __expand__.
- <a name='17'></a>*expanderName* __setbrackets__ *lbrack rbrack*
Sets the left and right macro expansion brackets. This command is for use as
or within a macro, or to permanently change the bracket definitions. By
default, the brackets are __[__ and __]__, but any non-empty string can be
used; for example, __<__ and __>__ or __(*__ and __*)__ or even __Hello,__
and __World!__.
- <a name='18'></a>*expanderName* __textcmd__ ?*newTextCmd*?
Returns the current command for processing plain text, which defaults to the
empty string, meaning *identity*. If specified, *newTextCmd* will be saved
for future use and then returned; it must be a Tcl command expecting one
additional argument: the text to process. The expander object will this
command for all plain text it encounters, giving the user of the object the
ability to process all plain text in some standard way before writing it to
the output. The object expects that the command returns the processed plain
text.
*Note* that the combination of "__textcmd__ *plaintext*" is run through the
*evalcmd* for the actual evaluation. In other words, the *textcmd* is
treated as a special macro implicitly surrounding all plain text in the
template.
- <a name='19'></a>*expanderName* __where__
Returns a three-element list containing the current character position,
line, and column the expander is at in the processing of the current input
string.
# <a name='section3'></a>TUTORIAL
## <a name='subsection1'></a>Basics
To begin, create an expander object:
% package require textutil::expander
1.2
% ::textutil::expander myexp
::myexp
%
The created __::myexp__ object can be used to expand text strings containing
embedded Tcl commands. By default, embedded commands are delimited by square
brackets. Note that expander doesn't attempt to interpolate variables, since
variables can be referenced by embedded commands:
% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% ::myexp expand {[set greeting], [place]!}
Howdy, World!
%
## <a name='subsection2'></a>Embedding Macros
An expander macro is simply a Tcl script embedded within a text string. Expander
evaluates the script in the global context, and replaces it with its result
string. For example,
% set greetings {Howdy Hi "What's up"}
Howdy Hi "What's up"
% ::myexp expand {There are many ways to say "Hello, World!":
[set result {}
foreach greeting $greetings {
append result "$greeting, World!\\n"
}
set result]
And that's just a small sample!}
There are many ways to say "Hello, World!":
Howdy, World!
Hi, World!
What's up, World!
And that's just a small sample!
%
## <a name='subsection3'></a>Writing Macro Commands
More typically, *macro commands* are used to create a markup language. A macro
command is just a Tcl command that returns an output string. For example, expand
can be used to implement a generic document markup language that can be
retargeted to HTML or any other output format:
% proc bold {} {return "<b>"}
% proc /bold {} {return "</b>"}
% ::myexp expand {Some of this text is in [bold]boldface[/bold]}
Some of this text is in <b>boldface</b>
%
The above definitions of __bold__ and __/bold__ returns HTML, but such commands
can be as complicated as needed; they could, for example, decide what to return
based on the desired output format.
## <a name='subsection4'></a>Changing the Expansion Brackets
By default, embedded macros are enclosed in square brackets, __[__ and __]__. If
square brackets need to be included in the output, the input can contain the
__lb__ and __rb__ commands. Alternatively, or if square brackets are
objectionable for some other reason, the macro expansion brackets can be changed
to any pair of non-empty strings.
The __setbrackets__ command changes the brackets permanently. For example, you
can write pseudo-html by change them to __<__ and __>__:
% ::myexp setbrackets < >
% ::myexp expand {<bold>This is boldface</bold>}
<b>This is boldface</b>
Alternatively, you can change the expansion brackets temporarily by passing the
desired brackets to the __expand__ command:
% ::myexp setbrackets "\\[" "\\]"
% ::myexp expand {<bold>This is boldface</bold>} {< >}
<b>This is boldface</b>
%
## <a name='subsection5'></a>Customized Macro Expansion
By default, macros are evaluated using the Tcl __uplevel #0__ command, so that
the embedded code executes in the global context. The application can provide a
different evaluation command using __evalcmd__; this allows the application to
use a safe interpreter, for example, or even to evaluated something other than
Tcl code. There is one caveat: to be recognized as valid, a macro must return 1
when passed to Tcl's "info complete" command.
For example, the following code "evaluates" each macro by returning the macro
text itself.
proc identity {macro} {return $macro}
::myexp evalcmd identity
## <a name='subsection6'></a>Using the Context Stack
Often it's desirable to define a pair of macros which operate in some way on the
plain text between them. Consider a set of macros for adding footnotes to a web
page: one could have implement something like this:
Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote "See Candide, by Voltaire"]
The __footnote__ macro would, presumably, assign a number to this footnote and
save the text to be formatted later on. However, this solution is ugly if the
footnote text is long or should contain additional markup. Consider the
following instead:
Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote]See [bookTitle "Candide"], by
[authorsName "Voltaire"], for more information.[/footnote]
Here the footnote text is contained between __footnote__ and __/footnote__
macros, continues onto a second line, and contains several macros of its own.
This is both clearer and more flexible; however, with the features presented so
far there's no easy way to do it. That's the purpose of the context stack.
All macro expansion takes place in a particular context. Here, the __footnote__
macro pushes a new context onto the context stack. Then, all expanded text gets
placed in that new context. __/footnote__ retrieves it by popping the context.
Here's a skeleton implementation of these two macros:
proc footnote {} {
::myexp cpush footnote
}
proc /footnote {} {
set footnoteText [::myexp cpop footnote]
# Save the footnote text, and return an appropriate footnote
# number and link.
}
The __cpush__ command pushes a new context onto the stack; the argument is the
context's name. It can be any string, but would typically be the name of the
macro itself. Then, __cpop__ verifies that the current context has the expected
name, pops it off of the stack, and returns the accumulated text.
Expand provides several other tools related to the context stack. Suppose the
first macro in a context pair takes arguments or computes values which the
second macro in the pair needs. After calling __cpush__, the first macro can
define one or more context variables; the second macro can retrieve their values
any time before calling __cpop__. For example, suppose the document must specify
the footnote number explicitly:
proc footnote {footnoteNumber} {
::myexp cpush footnote
::myexp csave num $footnoteNumber
# Return an appropriate link
}
proc /footnote {} {
set footnoteNumber [::myexp cget num]
set footnoteText [::myexp cpop footnote]
# Save the footnote text and its footnoteNumber for future
# output.
}
At times, it might be desirable to define macros that are valid only within a
particular context pair; such macros should verify that they are only called
within the correct context using either __cis__ or __cname__.
# <a name='section4'></a>HISTORY
__expander__ was written by William H. Duquette; it is a repackaging of the
central algorithm of the expand macro processing tool.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
[uri, http://www.wjduquette.com/expand, regexp,
[split](../../../../index.md#split), [string](../../../../index.md#string)
# <a name='keywords'></a>KEYWORDS
[string](../../../../index.md#string), [template
processing](../../../../index.md#template_processing), [text
expansion](../../../../index.md#text_expansion)
# <a name='category'></a>CATEGORY
Documentation tools
# <a name='copyright'></a>COPYRIGHT
Copyright © William H. Duquette, http://www.wjduquette.com/expand
|
Added embedded/md/tcllib/files/modules/textutil/repeat.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
[//000000001]: # (textutil::repeat - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'repeat.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::repeat(n) 0.7.1 tcllib "Text and string utilities, macro processing")
# NAME
textutil::repeat - Procedures to repeat strings.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::repeat ?0.7?
[__::textutil::repeat::strRepeat__ *text* *num*](#1)
[__::textutil::repeat::blank__ *num*](#2)
# <a name='description'></a>DESCRIPTION
The package __textutil::repeat__ provides commands to generate long strings by
repeating a shorter string many times.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::repeat::strRepeat__ *text* *num*
This command returns a string containing the *text* repeated *num* times.
The repetitions are joined without characters between them. A value of *num*
<= 0 causes the command to return an empty string.
*Note*: If the Tcl core the package is loaded in provides the command
__string repeat__ then this command will be implemented in its terms, for
maximum possible speed. Otherwise a fast implementation in Tcl will be used.
- <a name='2'></a>__::textutil::repeat::blank__ *num*
A convenience command. Returns a string of *num* spaces.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[blanks](../../../../index.md#blanks),
[repetition](../../../../index.md#repetition),
[string](../../../../index.md#string)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/textutil/tabify.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
[//000000001]: # (textutil::tabify - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'tabify.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::tabify(n) 0.7 tcllib "Text and string utilities, macro processing")
# NAME
textutil::tabify - Procedures to (un)tabify strings
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::tabify ?0.7?
[__::textutil::tabify::tabify__ *string* ?*num*?](#1)
[__::textutil::tabify::tabify2__ *string* ?*num*?](#2)
[__::textutil::tabify::untabify__ *string* ?*num*?](#3)
[__::textutil::tabify::untabify2__ *string* ?*num*?](#4)
# <a name='description'></a>DESCRIPTION
The package __textutil::tabify__ provides commands that convert between
tabulation and ordinary whitespace in strings.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::tabify::tabify__ *string* ?*num*?
Tabify the *string* by replacing any substring of *num* space chars by a
tabulation and return the result as a new string. *num* defaults to 8.
- <a name='2'></a>__::textutil::tabify::tabify2__ *string* ?*num*?
Similar to __::textutil::tabify__ this command tabifies the *string* and
returns the result as a new string. A different algorithm is used however.
Instead of replacing any substring of *num* spaces this command works more
like an editor. *num* defaults to 8.
Each line of the text in *string* is treated as if there are tabstops every
*num* columns. Only sequences of space characters containing more than one
space character and found immediately before a tabstop are replaced with
tabs.
- <a name='3'></a>__::textutil::tabify::untabify__ *string* ?*num*?
Untabify the *string* by replacing any tabulation char by a substring of
*num* space chars and return the result as a new string. *num* defaults to
8.
- <a name='4'></a>__::textutil::tabify::untabify2__ *string* ?*num*?
Untabify the *string* by replacing any tabulation char by a substring of at
most *num* space chars and return the result as a new string. Unlike
__textutil::tabify::untabify__ each tab is not replaced by a fixed number of
space characters. The command overlays each line in the *string* with
tabstops every *num* columns instead and replaces tabs with just enough
space characters to reach the next tabstop. This is the complement of the
actions taken by __::textutil::tabify::tabify2__. *num* defaults to 8.
There is one asymmetry though: A tab can be replaced with a single space,
but not the other way around.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[formatting](../../../../index.md#formatting),
[string](../../../../index.md#string), [tabstops](../../../../index.md#tabstops)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/textutil/textutil.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
|
[//000000001]: # (textutil - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'textutil.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil(n) 0.8 tcllib "Text and string utilities, macro processing")
# NAME
textutil - Procedures to manipulate texts and strings.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil ?0.8?
[__::textutil::adjust__ *string args*](#1)
[__::textutil::adjust::readPatterns__ *filename*](#2)
[__::textutil::adjust::listPredefined__](#3)
[__::textutil::adjust::getPredefined__ *filename*](#4)
[__::textutil::indent__ *string* *prefix* ?*skip*?](#5)
[__::textutil::undent__ *string*](#6)
[__::textutil::splitn__ *string* ?*len*?](#7)
[__::textutil::splitx__ *string* ?*regexp*?](#8)
[__::textutil::tabify__ *string* ?*num*?](#9)
[__::textutil::tabify2__ *string* ?*num*?](#10)
[__::textutil::trim__ *string* ?*regexp*?](#11)
[__::textutil::trimleft__ *string* ?*regexp*?](#12)
[__::textutil::trimright__ *string* ?*regexp*?](#13)
[__::textutil::trimPrefix__ *string* *prefix*](#14)
[__::textutil::trimEmptyHeading__ *string*](#15)
[__::textutil::untabify__ *string* ?*num*?](#16)
[__::textutil::untabify2__ *string* ?*num*?](#17)
[__::textutil::strRepeat__ *text num*](#18)
[__::textutil::blank__ *num*](#19)
[__::textutil::chop__ *string*](#20)
[__::textutil::tail__ *string*](#21)
[__::textutil::cap__ *string*](#22)
[__::textutil::uncap__ *string*](#23)
[__::textutil::longestCommonPrefixList__ *list*](#24)
[__::textutil::longestCommonPrefix__ ?*string*...?](#25)
# <a name='description'></a>DESCRIPTION
The package __textutil__ provides commands that manipulate strings or texts
(a.k.a. long strings or string with embedded newlines or paragraphs). It is
actually a bundle providing the commands of the six packages
- __[textutil::adjust](adjust.md)__
- __[textutil::repeat](repeat.md)__
- __[textutil::split](textutil_split.md)__
- __[textutil::string](textutil_string.md)__
- __[textutil::tabify](tabify.md)__
- __[textutil::trim](trim.md)__
in the namespace __textutil__.
The bundle is *deprecated*, and it will be removed in a future release of
Tcllib, after the next release. It is recommended to use the relevant sub
packages instead for whatever functionality is needed by the using package or
application.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::adjust__ *string args*
Do a justification on the *string* according to *args*. The string is taken
as one big paragraph, ignoring any newlines. Then the line is formatted
according to the options used, and the command return a new string with
enough lines to contain all the printable chars in the input string. A line
is a set of chars between the beginning of the string and a newline, or
between 2 newlines, or between a newline and the end of the string. If the
input string is small enough, the returned string won't contain any
newlines.
Together with __::textutil::indent__ it is possible to create properly
wrapped paragraphs with arbitrary indentations.
By default, any occurrence of spaces characters or tabulation are replaced
by a single space so each word in a line is separated from the next one by
exactly one space char, and this forms a *real* line. Each *real* line is
placed in a *logical* line, which have exactly a given length (see
__-length__ option below). The *real* line may have a lesser length. Again
by default, any trailing spaces are ignored before returning the string (see
__-full__ option below). The following options may be used after the
*string* parameter, and change the way the command place a *real* line in a
*logical* line.
* -full *boolean*
If set to __false__, any trailing space chars are deleted before
returning the string. If set to __true__, any trailing space chars are
left in the string. Default to __false__.
* __-hyphenate__ *boolean*
if set to __false__, no hyphenation will be done. If set to __true__,
the last word of a line is tried to be hyphenated. Defaults to
__false__. Note: hyphenation patterns must be loaded prior, using the
command __::textutil::adjust::readPatterns__.
* __-justify__ __center|left|plain|right__
Set the justification of the returned string to __center__, __left__,
__plain__ or __right__. By default, it is set to __left__. The
justification means that any line in the returned string but the last
one is build according to the value. If the justification is set to
__plain__ and the number of printable chars in the last line is less
than 90% of the length of a line (see __-length__), then this line is
justified with the __left__ value, avoiding the expansion of this line
when it is too small. The meaning of each value is:
+ __center__
The real line is centered in the logical line. If needed, a set of
space characters are added at the beginning (half of the needed set)
and at the end (half of the needed set) of the line if required (see
the option __-full__).
+ __left__
The real line is set on the left of the logical line. It means that
there are no space chars at the beginning of this line. If required,
all needed space chars are added at the end of the line (see the
option __-full__).
+ __plain__
The real line is exactly set in the logical line. It means that
there are no leading or trailing space chars. All the needed space
chars are added in the *real* line, between 2 (or more) words.
+ __right__
The real line is set on the right of the logical line. It means that
there are no space chars at the end of this line, and there may be
some space chars at the beginning, despite of the __-full__ option.
* __-length__ *integer*
Set the length of the *logical* line in the string to *integer*.
*integer* must be a positive integer value. Defaults to __72__.
* __-strictlength__ *boolean*
If set to __false__, a line can exceed the specified __-length__ if a
single word is longer than __-length__. If set to __true__, words that
are longer than __-length__ are split so that no line exceeds the
specified __-length__. Defaults to __false__.
- <a name='2'></a>__::textutil::adjust::readPatterns__ *filename*
Loads the internal storage for hyphenation patterns with the contents of the
file *filename*. This has to be done prior to calling command
__::textutil::adjust__ with "__-hyphenate__ __true__", or the hyphenation
process will not work correctly.
The package comes with a number of predefined pattern files, and the command
__::textutil::adjust::listPredefined__ can be used to find out their names.
- <a name='3'></a>__::textutil::adjust::listPredefined__
This command returns a list containing the names of the hyphenation files
coming with this package.
- <a name='4'></a>__::textutil::adjust::getPredefined__ *filename*
Use this command to query the package for the full path name of the
hyphenation file *filename* coming with the package. Only the filenames
found in the list returned by __::textutil::adjust::listPredefined__ are
legal arguments for this command.
- <a name='5'></a>__::textutil::indent__ *string* *prefix* ?*skip*?
Each line in the *string* indented by adding the string *prefix* at its
beginning. The modified string is returned as the result of the command.
If *skip* is specified the first *skip* lines are left untouched. The
default for *skip* is __0__, causing the modification of all lines. Negative
values for *skip* are treated like __0__. In other words, *skip* > __0__
creates a hanging indentation.
Together with __::textutil::adjust__ it is possible to create properly
wrapped paragraphs with arbitrary indentations.
- <a name='6'></a>__::textutil::undent__ *string*
The command computes the common prefix for all lines in *string* consisting
solely out of whitespace, removes this from each line and returns the
modified string.
Lines containing only whitespace are always reduced to completely empty
lines. They and empty lines are also ignored when computing the prefix to
remove.
Together with __::textutil::adjust__ it is possible to create properly
wrapped paragraphs with arbitrary indentations.
- <a name='7'></a>__::textutil::splitn__ *string* ?*len*?
This command splits the given *string* into chunks of *len* characters and
returns a list containing these chunks. The argument *len* defaults to __1__
if none is specified. A negative length is not allowed and will cause the
command to throw an error. Providing an empty string as input is allowed,
the command will then return an empty list. If the length of the *string* is
not an entire multiple of the chunk length, then the last chunk in the
generated list will be shorter than *len*.
- <a name='8'></a>__::textutil::splitx__ *string* ?*regexp*?
Split the *string* and return a list. The string is split according to the
regular expression *regexp* instead of a simple list of chars. Note that if
you add parenthesis into the *regexp*, the parentheses part of separator
would be added into list as additional element. If the *string* is empty the
result is the empty list, like for __[split](../../../../index.md#split)__.
If *regexp* is empty the *string* is split at every character, like
__[split](../../../../index.md#split)__ does. The regular expression
*regexp* defaults to "[\\t \\r\\n]+".
- <a name='9'></a>__::textutil::tabify__ *string* ?*num*?
Tabify the *string* by replacing any substring of *num* space chars by a
tabulation and return the result as a new string. *num* defaults to 8.
- <a name='10'></a>__::textutil::tabify2__ *string* ?*num*?
Similar to __::textutil::tabify__ this command tabifies the *string* and
returns the result as a new string. A different algorithm is used however.
Instead of replacing any substring of *num* spaces this command works more
like an editor. *num* defaults to 8.
Each line of the text in *string* is treated as if there are tabstops every
*num* columns. Only sequences of space characters containing more than one
space character and found immediately before a tabstop are replaced with
tabs.
- <a name='11'></a>__::textutil::trim__ *string* ?*regexp*?
Remove in *string* any leading and trailing substring according to the
regular expression *regexp* and return the result as a new string. This
apply on any *line* in the string, that is any substring between 2 newline
chars, or between the beginning of the string and a newline, or between a
newline and the end of the string, or, if the string contain no newline,
between the beginning and the end of the string. The regular expression
*regexp* defaults to "[ \\t]+".
- <a name='12'></a>__::textutil::trimleft__ *string* ?*regexp*?
Remove in *string* any leading substring according to the regular expression
*regexp* and return the result as a new string. This apply on any *line* in
the string, that is any substring between 2 newline chars, or between the
beginning of the string and a newline, or between a newline and the end of
the string, or, if the string contain no newline, between the beginning and
the end of the string. The regular expression *regexp* defaults to "[
\\t]+".
- <a name='13'></a>__::textutil::trimright__ *string* ?*regexp*?
Remove in *string* any trailing substring according to the regular
expression *regexp* and return the result as a new string. This apply on any
*line* in the string, that is any substring between 2 newline chars, or
between the beginning of the string and a newline, or between a newline and
the end of the string, or, if the string contain no newline, between the
beginning and the end of the string. The regular expression *regexp*
defaults to "[ \\t]+".
- <a name='14'></a>__::textutil::trimPrefix__ *string* *prefix*
Removes the *prefix* from the beginning of *string* and returns the result.
The *string* is left unchanged if it doesn't have *prefix* at its beginning.
- <a name='15'></a>__::textutil::trimEmptyHeading__ *string*
Looks for empty lines (including lines consisting of only whitespace) at the
beginning of the *string* and removes it. The modified string is returned as
the result of the command.
- <a name='16'></a>__::textutil::untabify__ *string* ?*num*?
Untabify the *string* by replacing any tabulation char by a substring of
*num* space chars and return the result as a new string. *num* defaults to
8.
- <a name='17'></a>__::textutil::untabify2__ *string* ?*num*?
Untabify the *string* by replacing any tabulation char by a substring of at
most *num* space chars and return the result as a new string. Unlike
__textutil::untabify__ each tab is not replaced by a fixed number of space
characters. The command overlays each line in the *string* with tabstops
every *num* columns instead and replaces tabs with just enough space
characters to reach the next tabstop. This is the complement of the actions
taken by __::textutil::tabify2__. *num* defaults to 8.
There is one asymmetry though: A tab can be replaced with a single space,
but not the other way around.
- <a name='18'></a>__::textutil::strRepeat__ *text num*
The implementation depends on the core executing the package. Used __string
repeat__ if it is present, or a fast tcl implementation if it is not.
Returns a string containing the *text* repeated *num* times. The repetitions
are joined without characters between them. A value of *num* <= 0 causes the
command to return an empty string.
- <a name='19'></a>__::textutil::blank__ *num*
A convenience command. Returns a string of *num* spaces.
- <a name='20'></a>__::textutil::chop__ *string*
A convenience command. Removes the last character of *string* and returns
the shortened string.
- <a name='21'></a>__::textutil::tail__ *string*
A convenience command. Removes the first character of *string* and returns
the shortened string.
- <a name='22'></a>__::textutil::cap__ *string*
Capitalizes the first character of *string* and returns the modified string.
- <a name='23'></a>__::textutil::uncap__ *string*
The complementary operation to __::textutil::cap__. Forces the first
character of *string* to lower case and returns the modified string.
- <a name='24'></a>__::textutil::longestCommonPrefixList__ *list*
- <a name='25'></a>__::textutil::longestCommonPrefix__ ?*string*...?
Computes the longest common prefix for either the *string*s given to the
command, or the strings specified in the single *list*, and returns it as
the result of the command.
If no strings were specified the result is the empty string. If only one
string was specified, the string itself is returned, as it is its own
longest common prefix.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[TeX](../../../../index.md#tex), [formatting](../../../../index.md#formatting),
[hyphenation](../../../../index.md#hyphenation),
[indenting](../../../../index.md#indenting),
[paragraph](../../../../index.md#paragraph), [regular
expression](../../../../index.md#regular_expression),
[string](../../../../index.md#string), [trimming](../../../../index.md#trimming)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/textutil/textutil_split.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (textutil::split - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'textutil_split.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::split(n) 0.8 tcllib "Text and string utilities, macro processing")
# NAME
textutil::split - Procedures to split texts
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::split ?0.8?
[__::textutil::split::splitn__ *string* ?*len*?](#1)
[__::textutil::split::splitx__ *string* ?*regexp*?](#2)
# <a name='description'></a>DESCRIPTION
The package __textutil::split__ provides commands that split strings by size and
arbitrary regular expressions.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::split::splitn__ *string* ?*len*?
This command splits the given *string* into chunks of *len* characters and
returns a list containing these chunks. The argument *len* defaults to __1__
if none is specified. A negative length is not allowed and will cause the
command to throw an error. Providing an empty string as input is allowed,
the command will then return an empty list. If the length of the *string* is
not an entire multiple of the chunk length, then the last chunk in the
generated list will be shorter than *len*.
- <a name='2'></a>__::textutil::split::splitx__ *string* ?*regexp*?
This command splits the *string* and return a list. The string is split
according to the regular expression *regexp* instead of a simple list of
chars. *Note*: When parentheses are used in the *regexp*, i.e. regex capture
groups, then these groups will be added into the result list as additional
elements. If the *string* is empty the result is the empty list, like for
__[split](../../../../index.md#split)__. If *regexp* is empty the *string*
is split at every character, like __[split](../../../../index.md#split)__
does. The regular expression *regexp* defaults to "[\\t \\r\\n]+".
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[regular expression](../../../../index.md#regular_expression),
[split](../../../../index.md#split), [string](../../../../index.md#string)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/textutil/textutil_string.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
[//000000001]: # (textutil::string - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'textutil_string.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::string(n) 0.8 tcllib "Text and string utilities, macro processing")
# NAME
textutil::string - Procedures to manipulate texts and strings.
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::string ?0.8?
[__::textutil::string::chop__ *string*](#1)
[__::textutil::string::tail__ *string*](#2)
[__::textutil::string::cap__ *string*](#3)
[__::textutil::string::capEachWord__ *string*](#4)
[__::textutil::string::uncap__ *string*](#5)
[__::textutil::string::longestCommonPrefixList__ *list*](#6)
[__::textutil::string::longestCommonPrefix__ ?*string*...?](#7)
# <a name='description'></a>DESCRIPTION
The package __textutil::string__ provides miscellaneous string manipulation
commands.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::string::chop__ *string*
A convenience command. Removes the last character of *string* and returns
the shortened string.
- <a name='2'></a>__::textutil::string::tail__ *string*
A convenience command. Removes the first character of *string* and returns
the shortened string.
- <a name='3'></a>__::textutil::string::cap__ *string*
Capitalizes the first character of *string* and returns the modified string.
- <a name='4'></a>__::textutil::string::capEachWord__ *string*
Capitalizes the first character of word of the *string* and returns the
modified string. Words quoted with either backslash or dollar-sign are left
untouched.
- <a name='5'></a>__::textutil::string::uncap__ *string*
The complementary operation to __::textutil::string::cap__. Forces the first
character of *string* to lower case and returns the modified string.
- <a name='6'></a>__::textutil::string::longestCommonPrefixList__ *list*
- <a name='7'></a>__::textutil::string::longestCommonPrefix__ ?*string*...?
Computes the longest common prefix for either the *string*s given to the
command, or the strings specified in the single *list*, and returns it as
the result of the command.
If no strings were specified the result is the empty string. If only one
string was specified, the string itself is returned, as it is its own
longest common prefix.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[capitalize](../../../../index.md#capitalize),
[chop](../../../../index.md#chop), [common
prefix](../../../../index.md#common_prefix),
[formatting](../../../../index.md#formatting),
[prefix](../../../../index.md#prefix), [string](../../../../index.md#string),
[uncapitalize](../../../../index.md#uncapitalize)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/textutil/trim.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
[//000000001]: # (textutil::trim - Text and string utilities, macro processing)
[//000000002]: # (Generated from file 'trim.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (textutil::trim(n) 0.7 tcllib "Text and string utilities, macro processing")
# NAME
textutil::trim - Procedures to trim strings
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require textutil::trim ?0.7?
[__::textutil::trim::trim__ *string* ?*regexp*?](#1)
[__::textutil::trim::trimleft__ *string* ?*regexp*?](#2)
[__::textutil::trim::trimright__ *string* ?*regexp*?](#3)
[__::textutil::trim::trimPrefix__ *string* *prefix*](#4)
[__::textutil::trim::trimEmptyHeading__ *string*](#5)
# <a name='description'></a>DESCRIPTION
The package __textutil::trim__ provides commands that trim strings using
arbitrary regular expressions.
The complete set of procedures is described below.
- <a name='1'></a>__::textutil::trim::trim__ *string* ?*regexp*?
Remove in *string* any leading and trailing substring according to the
regular expression *regexp* and return the result as a new string. This is
done for all *lines* in the string, that is any substring between 2 newline
chars, or between the beginning of the string and a newline, or between a
newline and the end of the string, or, if the string contain no newline,
between the beginning and the end of the string. The regular expression
*regexp* defaults to "[ \\t]+".
- <a name='2'></a>__::textutil::trim::trimleft__ *string* ?*regexp*?
Remove in *string* any leading substring according to the regular expression
*regexp* and return the result as a new string. This apply on any *line* in
the string, that is any substring between 2 newline chars, or between the
beginning of the string and a newline, or between a newline and the end of
the string, or, if the string contain no newline, between the beginning and
the end of the string. The regular expression *regexp* defaults to "[
\\t]+".
- <a name='3'></a>__::textutil::trim::trimright__ *string* ?*regexp*?
Remove in *string* any trailing substring according to the regular
expression *regexp* and return the result as a new string. This apply on any
*line* in the string, that is any substring between 2 newline chars, or
between the beginning of the string and a newline, or between a newline and
the end of the string, or, if the string contain no newline, between the
beginning and the end of the string. The regular expression *regexp*
defaults to "[ \\t]+".
- <a name='4'></a>__::textutil::trim::trimPrefix__ *string* *prefix*
Removes the *prefix* from the beginning of *string* and returns the result.
The *string* is left unchanged if it doesn't have *prefix* at its beginning.
- <a name='5'></a>__::textutil::trim::trimEmptyHeading__ *string*
Looks for empty lines (including lines consisting of only whitespace) at the
beginning of the *string* and removes it. The modified string is returned as
the result of the command.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *textutil* 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.
# <a name='see-also'></a>SEE ALSO
regexp(n), split(n), string(n)
# <a name='keywords'></a>KEYWORDS
[prefix](../../../../index.md#prefix), [regular
expression](../../../../index.md#regular_expression),
[string](../../../../index.md#string), [trimming](../../../../index.md#trimming)
# <a name='category'></a>CATEGORY
Text processing
|
Added embedded/md/tcllib/files/modules/tie/tie.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
|
[//000000001]: # (tie - Tcl Data Structures)
[//000000002]: # (Generated from file 'tie.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tie(n) 1.1 tcllib "Tcl Data Structures")
# NAME
tie - Array persistence
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [USING TIES](#section2)
- [TIE API](#subsection1)
- [STANDARD DATA SOURCE TYPES](#subsection2)
- [CREATING NEW DATA SOURCES](#section3)
- [DATA SOURCE OBJECTS](#subsection3)
- [REGISTERING A NEW DATA SOURCE CLASS](#subsection4)
- [DATA SOURCE CLASS](#subsection5)
- [DATA SOURCE OBJECT API](#subsection6)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require tie ?1.1?
[__::tie::tie__ *arrayvarname* *options*... *dstype* *dsname*...](#1)
[__::tie::untie__ *arrayvarname* ?*token*?](#2)
[__::tie::info__ __ties__ *arrayvarname*](#3)
[__::tie::info__ __types__](#4)
[__::tie::info__ __type__ *dstype*](#5)
[__::tie::register__ *dsclasscmd* __as__ *dstype*](#6)
[__dsclasscmd__ *objname* ?*dsname*...?](#7)
[__ds__ __destroy__](#8)
[__ds__ __names__](#9)
[__ds__ __size__](#10)
[__ds__ __get__](#11)
[__ds__ __set__ *dict*](#12)
[__ds__ __unset__ ?*pattern*?](#13)
[__ds__ __setv__ *index* *value*](#14)
[__ds__ __unsetv__ *index*](#15)
[__ds__ __getv__ *index*](#16)
# <a name='description'></a>DESCRIPTION
The __tie__ package provides a framework for the creation of persistent Tcl
array variables. It should be noted that the provided mechanism is generic
enough to also allow its usage for the distribution of the contents of Tcl
arrays over multiple threads and processes, i.e. communication.
This, persistence and communication, is accomplished by *tying*) a Tcl array
variable to a *[data source](../../../../index.md#data_source)*. Examples of
data sources are other Tcl arrays and files.
It should be noted that a single Tcl array variable can be tied to more than one
*[data source](../../../../index.md#data_source)*. It is this feature which
allows the framework to be used for communication as well. Just tie several Tcl
arrays in many client processes to a Tcl array in a server and all changes to
any of them will be distributed to all. Less centralized variants of this are of
course possible as well.
# <a name='section2'></a>USING TIES
## <a name='subsection1'></a>TIE API
This section describes the basic API used to establish and remove ties between
Tcl array variables and data sources. This interface is the only one a casual
user has to be concerned about. The following sections about the various
internal interfaces can be safely skipped.
- <a name='1'></a>__::tie::tie__ *arrayvarname* *options*... *dstype* *dsname*...
This command establishes a tie between the Tcl array whose name is provided
by the argument *arrayvarname* and the *[data
source](../../../../index.md#data_source)* identified by the *dstype* and
its series of *dsname* arguments. All changes made to the Tcl array after
this command returns will be saved to the *[data
source](../../../../index.md#data_source)* for safekeeping (or
distribution).
The result of the command is always a token which identifies the new tie.
This token can be used later to destroy this specific tie.
* varname *arrayvarname* (in)
The name of the Tcl array variable to connect the new tie to.
* name|command *dstype* (in)
This argument specifies the type of the *[data
source](../../../../index.md#data_source)* we wish to access. The
*dstype* can be one of __log__, __array__, __remotearray__, __file__,
__growfile__, or __dsource__; in addition, the programmer can register
additional data source types. Each *dstype* is followed by one or more
arguments that identify the *[data
source](../../../../index.md#data_source)* to which the array is to be
tied.
* string *dsname* (in)
The series of *dsname* arguments coming after the *dstype* identifies
the *[data source](../../../../index.md#data_source)* we wish to connect
to, and has to be appropriate for the chosen type.
The command understands a number of additional options which guide the
process of setting up the connection between Tcl array and *[data
source](../../../../index.md#data_source)*.
* __-open__
The Tcl array for the new tie is *loaded* from the *[data
source](../../../../index.md#data_source)*, and the previously existing
contents of the Tcl array are erased. Care is taken to *not* erase the
previous contents should the creation of the tie fail.
This option and the option __-save__ exclude each other. If neither this
nor option __-save__ are specified then this option is assumed as
default.
* __-save__
The Tcl array for the new tie is *saved* to the *[data
source](../../../../index.md#data_source)*, and the previously existing
contents of the *[data source](../../../../index.md#data_source)* are
erased.
This option and the option __-open__ exclude each other. If neither this
nor option __-open__ are specified then option __-open__ is assumed as
default.
* __-merge__
Using this option prevents the erasure of any previously existing
content and merges the data instead. It can be specified in conjunction
with either __-open__ or __-save__. They determine how data existing in
both Tcl array and *[data source](../../../../index.md#data_source)*,
i.e duplicates, are dealt with.
When used with __-open__ data in the *[data
source](../../../../index.md#data_source)* has precedence. In other
words, for duplicates the data in the *[data
source](../../../../index.md#data_source)* is loaded into the Tcl array.
When used with __-save__ data in the Tcl array has precedence. In other
words, for duplicates the data in the Tcl array is saved into the *[data
source](../../../../index.md#data_source)*.
- <a name='2'></a>__::tie::untie__ *arrayvarname* ?*token*?
This command dissolves one or more ties associated with the Tcl array named
by *arrayvarname*. If no *token* is specified then all ties to that Tcl
array are dissolved. Otherwise only the tie the token stands for is removed,
if it is actually connected to the array. Trying to remove a specific tie
not belonging to the provided array will cause an error.
It should be noted that while severing a tie will destroy management
information internal to the package the *[data
source](../../../../index.md#data_source)* which was handled by the tie will
not be touched, only closed.
After the command returns none of changes made to the array will be saved to
the *[data source](../../../../index.md#data_source)* anymore.
The result of the command is an empty string.
* varname *arrayname* (in)
The name of a Tcl array variable which may have ties.
* handle *token* (in)
A handle representing a specific tie. This argument is optional.
- <a name='3'></a>__::tie::info__ __ties__ *arrayvarname*
This command returns a list of ties associated with the Tcl array variable
named by *arrayvarname*. The result list will be empty if the variable has
no ties associated with it.
- <a name='4'></a>__::tie::info__ __types__
This command returns a dictionary of registered types, and the class
commands they are associated with.
- <a name='5'></a>__::tie::info__ __type__ *dstype*
This command returns the fully resolved class command for a type name. This
means that the command will follow a chain of type definitions ot its end.
## <a name='subsection2'></a>STANDARD DATA SOURCE TYPES
This package provides the six following types as examples and standard data
sources.
- __log__
This *[data source](../../../../index.md#data_source)* does not maintain any
actual data, nor persistence. It does not accept any identifying arguments.
All changes are simply logged to __stdout__.
- __array__
This *[data source](../../../../index.md#data_source)* uses a regular Tcl
array as the origin of the persistent data. It accepts a single identifying
argument, the name of this Tcl array. All changes are mirrored to that
array.
- __remotearray__
This *[data source](../../../../index.md#data_source)* is similar to
__array__. The difference is that the Tcl array to which we are mirroring is
not directly accessible, but through a
__[send](../../../../index.md#send)__-like command.
It accepts three identifying arguments, the name of the other Tcl array, the
command prefix for the __[send](../../../../index.md#send)__-like accessor
command, and an identifier for the remote entity hosting the array, in this
order. All changes are mirrored to that array, via the command prefix. All
commands will be executed in the context of the global namespace.
__[send](../../../../index.md#send)__-like means that the command prefix has
to have __[send](../../../../index.md#send)__ syntax and semantics. I.e. it
is a channel over which we can send arbitrary commands to some other entity.
The remote array *[data source](../../../../index.md#data_source)* however
uses only the commands __[set](../../../../index.md#set)__, __unset__,
__array exists__, __array names__, __array set__, and __array get__ to
retrieve and set values in the remote array.
The command prefix and the entity id are separate to allow the data source
to use options like __-async__ when assembling the actual commands.
Examples of command prefixes, listed with the id of the remote entity,
without options. In reality only the part before the id is the command
prefix:
* __[send](../../../../index.md#send)__ *tkname*
The Tcl array is in a remote interpreter and is accessed via Tk's X
communication.
* __comm::comm send__ *hostportid*
The Tcl array is in a remote interpreter and is accessed through a
socket.
* __thread::send__ *threadid*
The Tcl array is in a remote interpreter in a different thread of this
process.
- __file__
This *[data source](../../../../index.md#data_source)* uses a single file as
origin of the persistent data. It accepts a single identifying argument, the
path to this file. The file has to be both readable and writable. It may not
exist, the *[data source](../../../../index.md#data_source)* will create it
in that case. This (and only this) situation will require that the directory
for the file exists and is writable as well.
All changes are saved in the file, as proper Tcl commands, one command per
operation. In other words, the file will always contain a proper Tcl script.
If the file exists when the tie using it is set up, then it will be
compacted, i.e. superfluous operations are removed, if the operations log
stored in it contains either at least one operation clearing the whole
array, or at least 1.5 times more operations than entries in the loaded
array.
- __growfile__
This *[data source](../../../../index.md#data_source)* is like __file__ in
terms of the storage medium for the array data, and how it is configured. In
constrast to the former it however assumes and ensures that the tied array
will never shrink. I.e. the creation of new array entries, and the
modification of existing entries is allowed, but the deletion of entries is
not, and causes the data source to throw errors.
This restriction allows us to simplify both file format and access to the
file radically. For one, the file is read only once and the internal cache
cannot be invalidated. Second, writing data is reduced to a simple append,
and no compaction step is necessary. The format of the contents is the
string representation of a dictionary which can be incrementally extended
forever at the end.
- __dsource__
This *[data source](../../../../index.md#data_source)* uses an explicitly
specified *data source object* as the source for the persistent data. It
accepts a single identifying argument, the command prefix, i.e. object
command.
To use this type it is necessary to know how the framework manages ties and
what [data source objects](#subsection3) are.
All changes are delegated to the specified object.
# <a name='section3'></a>CREATING NEW DATA SOURCES
This section is of no interest to the casual user of ties. Only developers
wishing to create new data sources have to know the information provided herein.
## <a name='subsection3'></a>DATA SOURCE OBJECTS
All ties are represented internally by an in-memory object which mediates
between the tie framework and the specific *[data
source](../../../../index.md#data_source)*, like an array, file, etc. This is
the *data source object*.
Its class, the [data source class](#subsection5) is *not* generic, but specific
to the type of the *[data source](../../../../index.md#data_source)*. Writing a
new *[data source](../../../../index.md#data_source)* requires us to write such
a class, and then registering it with the framework as a new type.
The following subsections describe the various APIs a [data source
class](#subsection5) and the objects it generates will have to follow to be
compatible with the tie framework.
Data source objects are normally automatically created and destroyed by the
framework when a tie is created, or removed. This management can be explicitly
bypassed through the usage of the "dsource" type. The *[data
source](../../../../index.md#data_source)* for this type is a *data source
object* itself, and this object is outside of the scope of the tie framework and
not managed by it. In other words, this type allows the creation of ties which
talk to pre-existing *data source object*s, and these objects will survive the
removal of the ties using them as well.
## <a name='subsection4'></a>REGISTERING A NEW DATA SOURCE CLASS
After a [data source class](#subsection5) has been written it is necessary to
register it as a new type with the framework.
- <a name='6'></a>__::tie::register__ *dsclasscmd* __as__ *dstype*
Using this command causes the tie framework to remember the class command
*dsclasscmd* of a [data source class](#subsection5) under the type name
*dstype*.
After the call the argument *dstype* of the basic user command
__::tie::tie__ will accept *dstype* as a type name and translate it
internally to the appropriate class command for the creation of [data source
objects](#subsection3) for the new *[data
source](../../../../index.md#data_source)*.
## <a name='subsection5'></a>DATA SOURCE CLASS
Each data source class is represented by a single command, also called the
*class command*, or *object creation command*. Its syntax is
- <a name='7'></a>__dsclasscmd__ *objname* ?*dsname*...?
The first argument of the class command is the name of the *data source
object* to create. The framework itself will always supply the string
__%AUTO%__, to signal that the class command has to generate not only the
object, but the object name as well.
This is followed by a series of arguments identifying the data source the
new object is for. These are the same *dsname* arguments which are given to
the basic user command __::tie::tie__. Their actual meaning is dependent on
the *data source class*.
The result of the class command has to be the fully-qualified name of the
new *data source object*, i.e. the name of the *object command*. The
interface this command has to follow is described in the section [DATA
SOURCE OBJECT API](#subsection6)
## <a name='subsection6'></a>DATA SOURCE OBJECT API
Please read the section [DATA SOURCE CLASS](#subsection5) first, to know how to
generate new *object commands*.
Each *object command* for a *[data source](../../../../index.md#data_source)*
object has to provide at least the methods listed below for proper
inter-operation with the tie framework. Note that the names of most of the
methods match the subcommands of the builtin
__[array](../../../../index.md#array)__ command.
- <a name='8'></a>__ds__ __destroy__
This method is called when the object __ds__ is destroyed. It now has to
release all its internal resources associated with the external data source.
- <a name='9'></a>__ds__ __names__
This command has to return a list containing the names of all keys found in
the *[data source](../../../../index.md#data_source)* the object talks to.
This is equivalent to __array names__.
- <a name='10'></a>__ds__ __size__
This command has to return an integer number specifying the number of keys
found in the *[data source](../../../../index.md#data_source)* the object
talks to. This is equivalent to __array size__.
- <a name='11'></a>__ds__ __get__
This command has to return a dictionary containing the data found in the
*[data source](../../../../index.md#data_source)* the object talks to. This
is equivalent to __array get__.
- <a name='12'></a>__ds__ __set__ *dict*
This command takes a dictionary and adds its contents to the data source the
object talks to. This is equivalent to __array set__.
- <a name='13'></a>__ds__ __unset__ ?*pattern*?
This command takes a pattern and removes all elements whose keys matching it
from the *[data source](../../../../index.md#data_source)*. If no pattern is
specified it defaults to __*__, causing the removal of all elements. This is
nearly equivalent to __array unset__.
- <a name='14'></a>__ds__ __setv__ *index* *value*
This command has to save the *value* in the *[data
source](../../../../index.md#data_source)* the object talks to, under the
key *index*.
The result of the command is ignored. If an error is thrown then this error
will show up as error of the set operation which caused the method call.
- <a name='15'></a>__ds__ __unsetv__ *index*
This command has to remove the value under the key *index* from the *[data
source](../../../../index.md#data_source)* the object talks to.
The result of the command is ignored. If an error is thrown then this error
will show up as error of the unset operation which caused the method call.
- <a name='16'></a>__ds__ __getv__ *index*
This command has to return the value for the key *index* in the *[data
source](../../../../index.md#data_source)* the object talks to.
And here a small table comparing the *[data
source](../../../../index.md#data_source)* methods to the regular Tcl commands
for accessing an array.
Regular Tcl Data source
----------- -----------
array names a ds names
array size a ds size
array get a ds get
array set a dict ds set dict
array unset a pattern ds unset ?pattern?
----------- -----------
set a($idx) $val ds setv idx val
unset a($idx) ds unsetv idx
$a($idx) ds getv idx
----------- -----------
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tie* 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.
# <a name='keywords'></a>KEYWORDS
[array](../../../../index.md#array), [database](../../../../index.md#database),
[file](../../../../index.md#file), [metakit](../../../../index.md#metakit),
[persistence](../../../../index.md#persistence),
[tie](../../../../index.md#tie), [untie](../../../../index.md#untie)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004-2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/tie/tie_std.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
[//000000001]: # (tie - Tcl Data Structures)
[//000000002]: # (Generated from file 'tie_std.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tie(n) 1.1 tcllib "Tcl Data Structures")
# NAME
tie - Array persistence, standard data sources
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require tie::std::log ?1.0?
package require tie::std::array ?1.0?
package require tie::std::rarray ?1.0.1?
package require tie::std::file ?1.0.4?
package require tie::std::growfile ?1.0?
package require tie::std::dsource ?1.0?
# <a name='description'></a>DESCRIPTION
The packages listed as requirements for this document are internal packages
providing the standard data sources of package __[tie](tie.md)__, as described
in section *STANDARD DATA SOURCE TYPES* of __[tie](tie.md)__'s documentation.
They are automatically loaded and registered by __[tie](tie.md)__ when it itself
is requested, and as such there is no need to request them on their own,
although it is possible to do so.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tie* 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.
# <a name='keywords'></a>KEYWORDS
[array](../../../../index.md#array), [database](../../../../index.md#database),
[file](../../../../index.md#file), [metakit](../../../../index.md#metakit),
[persistence](../../../../index.md#persistence),
[tie](../../../../index.md#tie), [untie](../../../../index.md#untie)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008-2015 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/tiff/tiff.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
[//000000001]: # (tiff - TIFF image manipulation)
[//000000002]: # (Generated from file 'tiff.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tiff(n) 0.2.1 tcllib "TIFF image manipulation")
# NAME
tiff - TIFF reading, writing, and querying and manipulation of meta data
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [VARIABLES](#section3)
- [LIMITATIONS](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require tiff ?0.2.1?
[__::tiff::isTIFF__ *file*](#1)
[__::tiff::byteOrder__ *file*](#2)
[__::tiff::numImages__ *file*](#3)
[__::tiff::dimensions__ *file* ?image?](#4)
[__::tiff::imageInfo__ *file* ?image?](#5)
[__::tiff::entries__ *file* ?image?](#6)
[__::tiff::getEntry__ *file* *entry* ?image?](#7)
[__::tiff::addEntry__ *file* *entry* ?image?](#8)
[__::tiff::deleteEntry__ *file* *entry* ?image?](#9)
[__::tiff::getImage__ *file* ?image?](#10)
[__::tiff::writeImage__ *image* *file* ?entry?](#11)
[__::tiff::nametotag__ *names*](#12)
[__::tiff::tagtoname__ *tags*](#13)
[__::tiff::debug__ *file*](#14)
# <a name='description'></a>DESCRIPTION
This package provides commands to query, modify, read, and write TIFF images.
TIFF stands for *Tagged Image File Format* and is a standard for lossless
storage of photographical images and associated metadata. It is specified at
[http://partners.adobe.com/public/developer/tiff/index.html](http://partners.adobe.com/public/developer/tiff/index.html).
Multiple images may be stored in a single TIFF file. The ?image? options to the
functions in this package are for accessing images other than the first. Data in
a TIFF image is stored as a series of tags having a numerical value, which are
represented in either a 4 digit hexadecimal format or a string name. For a
reference on defined tags and their meanings see
[http://www.awaresystems.be/imaging/tiff/tifftags.html](http://www.awaresystems.be/imaging/tiff/tifftags.html)
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::tiff::isTIFF__ *file*
Returns a boolean value indicating if *file* is a TIFF image.
- <a name='2'></a>__::tiff::byteOrder__ *file*
Returns either __big__ or __little__. Throws an error if *file* is not a
TIFF image.
- <a name='3'></a>__::tiff::numImages__ *file*
Returns the number of images in *file*. Throws an error if *file* is not a
TIFF image.
- <a name='4'></a>__::tiff::dimensions__ *file* ?image?
Returns the dimensions of image number ?image? in *file* as a list of the
horizontal and vertical pixel count. Throws an error if *file* is not a TIFF
image.
- <a name='5'></a>__::tiff::imageInfo__ *file* ?image?
Returns a dictionary with keys __ImageWidth__, __ImageLength__,
__BitsPerSample__, __Compression__, __PhotometricInterpretation__,
__ImageDescription__, __Orientation__, __XResolution__, __YResolution__,
__ResolutionUnit__, __DateTime__, __Artist__, and __HostComputer__. The
values are the associated properties of the TIFF ?image? in *file*. Values
may be empty if the associated tag is not present in the file.
puts [::tiff::imageInfo photo.tif]
ImageWidth 686 ImageLength 1024 BitsPerSample {8 8 8} Compression 1
PhotometricInterpretation 2 ImageDescription {} Orientation 1
XResolution 170.667 YResolution 170.667 ResolutionUnit 2 DateTime {2005:12:28 19:44:45}
Artist {} HostComputer {}
There is nothing special about these tags, this is simply a convience
procedure which calls __getEntry__ with common entries. Throws an error if
*file* is not a TIFF image.
- <a name='6'></a>__::tiff::entries__ *file* ?image?
Returns a list of all entries in the given *file* and ?image? in hexadecimal
format. Throws an error if *file* is not a TIFF image.
- <a name='7'></a>__::tiff::getEntry__ *file* *entry* ?image?
Returns the value of *entry* from image ?image? in the TIFF *file*. *entry*
may be a list of multiple entries. If an entry does not exist, an empty
string is returned
set data [::tiff::getEntry photo.tif {0131 0132}]
puts "file was written at [lindex $data 0] with software [lindex $data 1]"
Throws an error if *file* is not a TIFF image.
- <a name='8'></a>__::tiff::addEntry__ *file* *entry* ?image?
Adds the specified entries to the image named by ?image? (default 0), or
optionally __all__. *entry* must be a list where each element is a list of
tag, type, and value. If a tag already exists, it is overwritten.
::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}}
The data types are defined as follows
* __1__
BYTE (8 bit unsigned integer)
* __2__
ASCII
* __3__
SHORT (16 bit unsigned integer)
* __4__
LONG (32 bit unsigned integer)
* __5__
RATIONAL
* __6__
SBYTE (8 bit signed byte)
* __7__
UNDEFINED (uninterpreted binary data)
* __8__
SSHORT (signed 16 bit integer)
* __9__
SLONG (signed 32 bit integer)
* __10__
SRATIONAL
* __11__
FLOAT (32 bit floating point number)
* __12__
DOUBLE (64 bit floating point number)
Throws an error if *file* is not a TIFF image.
- <a name='9'></a>__::tiff::deleteEntry__ *file* *entry* ?image?
Deletes the specified entries from the image named by ?image? (default 0),
or optionally __all__. Throws an error if *file* is not a TIFF image.
- <a name='10'></a>__::tiff::getImage__ *file* ?image?
Returns the name of a Tk image containing the image at index ?image? from
*file* Throws an error if *file* is not a TIFF image, or if image is an
unsupported format. Supported formats are uncompressed 24 bit RGB and
uncompressed 8 bit palette.
- <a name='11'></a>__::tiff::writeImage__ *image* *file* ?entry?
Writes the contents of the Tk image *image* to a tiff file *file*. Files are
written in the 24 bit uncompressed format, with big endian byte order.
Additional entries to be added to the image may be specified, in the same
format as __tiff::addEntry__
- <a name='12'></a>__::tiff::nametotag__ *names*
Returns a list with *names* translated from string to 4 digit format. 4
digit names in the input are passed through unchanged. Strings without a
defined tag name will throw an error.
- <a name='13'></a>__::tiff::tagtoname__ *tags*
Returns a list with *tags* translated from 4 digit to string format. If a
tag does not have a defined name it is passed through unchanged.
- <a name='14'></a>__::tiff::debug__ *file*
Prints everything we know about the given file in a nice format.
# <a name='section3'></a>VARIABLES
The mapping of 4 digit tag names to string names uses the array
::tiff::tiff_tags. The reverse mapping uses the array ::tiff::tiff_sgat.
# <a name='section4'></a>LIMITATIONS
1. Cannot write exif ifd
1. Reading limited to uncompressed 8 bit rgb and 8 bit palletized images
1. Writing limited to uncompressed 8 bit rgb
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tiff* 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.
# <a name='keywords'></a>KEYWORDS
[image](../../../../index.md#image), [tif](../../../../index.md#tif),
[tiff](../../../../index.md#tiff)
# <a name='category'></a>CATEGORY
File formats
# <a name='copyright'></a>COPYRIGHT
Copyright © 2005-2006, Aaron Faupell <[email protected]>
|
Added embedded/md/tcllib/files/modules/tool/meta.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
[//000000001]: # (oo::util - Utility commands for TclOO)
[//000000002]: # (Generated from file 'meta.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (oo::util(n) 1.2.2 tcllib "Utility commands for TclOO")
# NAME
oo::util - Utility commands for TclOO
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [AUTHORS](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require oo::util ?1.2.2?
[__mymethod__ *method* ?*arg*...?](#1)
[__classmethod__ *name* *arguments* *body*](#2)
[__classvariable__ ?*arg*...?](#3)
[__link__ *method*...](#4)
[__link__ {*alias* *method*}...](#5)
[__ooutil::singleton__ ?*arg*...?](#6)
# <a name='description'></a>DESCRIPTION
This package provides a convenience command for the easy specification of
instance methods as callback commands, like timers, file events, Tk bindings,
etc.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__mymethod__ *method* ?*arg*...?
This command is available within instance methods. It takes a method name
and, possibly, arguments for the method and returns a command prefix which,
when executed, will invoke the named method of the object we are in, with
the provided arguments, and any others supplied at the time of actual
invokation.
Note: The command is equivalent to and named after the command provided by
the OO package __[snit](../snit/snit.md)__ for the same purpose.
- <a name='2'></a>__classmethod__ *name* *arguments* *body*
This command is available within class definitions. It takes a method name
and, possibly, arguments for the method and creates a method on the class,
available to a user of the class and of derived classes.
Note: The command is equivalent to the command __typemethod__ provided by
the OO package __[snit](../snit/snit.md)__ for the same purpose.
Example
oo::class create ActiveRecord {
classmethod find args { puts "[self] called with arguments: $args" }
}
oo::class create Table {
superclass ActiveRecord
}
puts [Table find foo bar]
# ======
# which will write
# ======
# ::Table called with arguments: foo bar
- <a name='3'></a>__classvariable__ ?*arg*...?
This command is available within instance methods. It takes a series of
variable names and makes them available in the method's scope. The
originating scope for the variables is the class (instance) the object
instance belongs to. In other words, the referenced variables are shared
between all instances of their class.
Note: The command is roughly equivalent to the command __typevariable__
provided by the OO package __[snit](../snit/snit.md)__ for the same purpose.
The difference is that it cannot be used in the class definition itself.
Example:
% oo::class create Foo {
method bar {z} {
classvariable x y
return [incr x $z],[incr y]
}
}
::Foo
% Foo create a
::a
% Foo create b
::b
% a bar 2
2,1
% a bar 3
5,2
% b bar 7
12,3
% b bar -1
11,4
% a bar 0
11,5
- <a name='4'></a>__link__ *method*...
- <a name='5'></a>__link__ {*alias* *method*}...
This command is available within instance methods. It takes a list of method
names and/or pairs of alias- and method-name and makes the named methods
available to all instance methods without requiring the __my__ command.
The alias name under which the method becomes available defaults to the
method name, except where explicitly specified through an alias/method pair.
Examples:
link foo
# The method foo is now directly accessible as foo instead of my foo.
link {bar foo}
# The method foo is now directly accessible as bar.
link a b c
# The methods a, b, and c all become directly acessible under their
# own names.
The main use of this command is expected to be in instance constructors, for
convenience, or to set up some methods for use in a mini DSL.
- <a name='6'></a>__ooutil::singleton__ ?*arg*...?
This command is a meta-class, i.e. a variant of the builtin __oo::class__
which ensures that it creates only a single instance of the classes defined
with it.
Syntax and results are like for __oo::class__.
Example:
% oo::class create example {
self mixin singleton
method foo {} {self}
}
::example
% [example new] foo
::oo::Obj22
% [example new] foo
::oo::Obj22
# <a name='section3'></a>AUTHORS
Donal Fellows, Andreas Kupries
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *oo::util* 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.
# <a name='see-also'></a>SEE ALSO
[snit(n)](../snit/snit.md)
# <a name='keywords'></a>KEYWORDS
[TclOO](../../../../index.md#tcloo), [callback](../../../../index.md#callback),
[class methods](../../../../index.md#class_methods), [class
variables](../../../../index.md#class_variables), [command
prefix](../../../../index.md#command_prefix),
[currying](../../../../index.md#currying), [method
reference](../../../../index.md#method_reference), [my
method](../../../../index.md#my_method),
[singleton](../../../../index.md#singleton)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011-2015 Andreas Kupries, BSD licensed
|
Added embedded/md/tcllib/files/modules/tool/tool.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
[//000000001]: # (tool - Standardized OO Framework for development)
[//000000002]: # (Generated from file 'tool.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tool(n) 0.4.2 tcllib "Standardized OO Framework for development")
# NAME
tool - TclOO Library (TOOL) Framework
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Keywords](#section2)
- [Public Object Methods](#section3)
- [Private Object Methods](#section4)
- [AUTHORS](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require sha1
package require dicttool
package require oo::meta
package require oo::dialect
[tool::define __class_method__ *arglist* *body*](#1)
[tool::define __[array](../../../../index.md#array)__ *name* *contents*](#2)
[tool::define __array_ensemble__ *methodname* *varname* ?cases?](#3)
[tool::define __dict_ensemble__ *methodname* *varname* ?cases?](#4)
[tool::define __[method](../../../../index.md#method)__ *methodname* *arglist* *body*](#5)
[tool::define __option__ *name* *dictopts*](#6)
[tool::define __property__ ?branch? *field* *value*](#7)
[tool::define __variable__ *name* *value*](#8)
[*object* __cget__ *option*](#9)
[*object* __configure__ ?keyvaluelist?](#10)
[*object* __configure__ *field* *value* ?field? ?value? ?...?](#11)
[*object* __configurelist__ ?keyvaluelist?](#12)
[*object* __forward__ *stub* *forward*](#13)
[*object* __graft__ *stub* *forward*](#14)
[*object* __InitializePublic__](#15)
[*object* __Eval_Script__ ?script?](#16)
[*object* __Option_Default__ *field*](#17)
# <a name='description'></a>DESCRIPTION
This module implements the Tcl Object Oriented Library framework, or *TOOL*. It
is intended to be a general purpose framework that is useable in its own right,
and easily extensible.
TOOL defines a metaclass with provides several additional keywords to the TclOO
description langauge, default behaviors for its consituent objects, and top-down
integration with the capabilities provided by the __oo::meta__ package.
The TOOL metaclass was build with the __oo::dialect__ package, and thus can be
used as the basis for additional metaclasses. As a metaclass, TOOL has it's own
"class" class, "object" class, and define namespace.
package require tool
# tool::class workds just like oo::class
tool::class create myclass {
}
# tool::define works just like oo::define
tool::define myclass method noop {} {}
# tool::define and tool::class understand additional keywords
tool::define myclass array_ensemble mysettings mysettings {}
# And tool interoperates with oo::define
oo::define myclass method do_something {} { return something }
# TOOL and TclOO objects are interchangeable
oo::class create myooclass {
superclass myclass
}
Several manual pages go into more detail about specific keywords and methods.
- __tool::array_ensemble__
- __[tool::dict_ensemble](tool_dict_ensemble.md)__
- __tool::method_ensemble__
- __tool::object__
- __tool::option_handling__
# <a name='section2'></a>Keywords
TOOL adds new (or modifies) keywords used in the definitions of classes.
However, the new keywords are only available via calls to *tool::class create*
or *tool::define*
- <a name='1'></a>tool::define __class_method__ *arglist* *body*
Defines a method for the class object itself. This method will be passed on
to descendents of the class, unlike __self method__.
- <a name='2'></a>tool::define __[array](../../../../index.md#array)__ *name* *contents*
Declares a variable *name* which will be initialized as an array, populated
with *contents* for objects of this class, as well as any objects for
classes which are descendents of this class.
- <a name='3'></a>tool::define __array_ensemble__ *methodname* *varname* ?cases?
Declares a method ensemble *methodname* which will control access to
variable *varname*. Cases are a key/value list of method names and bodies
which will be overlaid on top of the standard template. See
__tool::array_ensemble__.
One method name is reserved: __initialize__. __initialize__ Declares the
initial values to be populated in the array, as a key/value list, and will
not be expressed as a method for the ensemble.
- <a name='4'></a>tool::define __dict_ensemble__ *methodname* *varname* ?cases?
Declares a method ensemble *methodname* which will control access to
variable *varname*. Cases are a key/value list of method names and bodies
which will be overlaid on top of the standard template. See
__[tool::dict_ensemble](tool_dict_ensemble.md)__.
One method name is reserved: __initialize__. __initialize__ Declares the
initial values to be populated in the array, as a key/value list, and will
not be expressed as a method for the ensemble.
- <a name='5'></a>tool::define __[method](../../../../index.md#method)__ *methodname* *arglist* *body*
If *methodname* contains ::, the method is considered to be part of a method
ensemble. See __tool::method_ensembles__. Otherwise this command behaves
exactly like the standard __oo::define__
__[method](../../../../index.md#method)__ command.
- <a name='6'></a>tool::define __option__ *name* *dictopts*
Declares an option. *dictopts* is a key/value list defining parameters for
the option. See __tool::option_handling__.
tool::class create myclass {
option color {
post-command: {puts [list %self%'s %field% is now %value%]}
default: green
}
}
myclass create foo
foo configure color purple
> foo's color is now purple
- <a name='7'></a>tool::define __property__ ?branch? *field* *value*
Defines a new leaf in the class metadata tree. With no branch, the leaf will
appear in the *const* section, accessible by either the object's
__property__ method, or via __oo::meta::info__ *class* __get const__
*field*:
- <a name='8'></a>tool::define __variable__ *name* *value*
Declares a variable *name* which will be initialized with the value *value*
for objects of this class, as well as any objects for classes which are
descendents of this class.
# <a name='section3'></a>Public Object Methods
The TOOL object mother of all classes defines several methods to enforces
consistent behavior throughout the framework.
- <a name='9'></a>*object* __cget__ *option*
Return the value of this object's option *option*. If the __property
options_strict__ is true for this class, calling an option which was not
declared by the __option__ keyword will throw an error. In all other cases
if the value is present in the object's *options* array that value is
returned. If it does not exist, the object will attempt to retrieve a
property of the same name.
- <a name='10'></a>*object* __configure__ ?keyvaluelist?
- <a name='11'></a>*object* __configure__ *field* *value* ?field? ?value? ?...?
This command will inject new values into the objects *options* array,
according to the rules as set forth by the option descriptions. See
__tool::option_handling__ for details. __configure__ will strip leading -'s
off of field names, allowing it to behave in a quasi-backward compatible
manner to tk options.
- <a name='12'></a>*object* __configurelist__ ?keyvaluelist?
This command will inject new values into the objects *options* array,
according to the rules as set forth by the option descriptions. This command
will perform validation and alternate storage rules. It will not invoke
trigger rules. See __tool::option_handling__ for details.
- <a name='13'></a>*object* __forward__ *stub* *forward*
A passthrough to __oo:objdefine [self] forward__
- <a name='14'></a>*object* __graft__ *stub* *forward*
Delegates the *<stub>* method to the object or command designated by
*forward*
tool::object create A
tool::object create B
A graft buddy B
A configure color red
B configure color blue
A cget color
> red
A <buddy> cget color
> blue
# <a name='section4'></a>Private Object Methods
- <a name='15'></a>*object* __InitializePublic__
Consults the metadata for the class to ensure every array, option, and
variable which has been declared but not initialized is initialized with the
default value. This method is called by the constructor and the morph
method. It is safe to invoke multiple times.
- <a name='16'></a>*object* __Eval_Script__ ?script?
Executes a block of text within the namespace of the object. Lines that
begin with a # are ignored as comments. Commands that begin with :: are
interpreted as calling a global command. All other Tcl commands that lack a
"my" prefix are given one, to allow the script to exercise internal methods.
This method is intended for configuration scripts, where the object's
methods are intepreting a domain specific language.
tool::class myclass {
constructor script {
my Eval_Script $script
}
method node {nodename info} {
my variable node
dict set node $nodename $info
}
method get {args} {
my variable node
return [dict get $node $args]
}
}
myclass create movies {
# This block of code is executed by the object
node {The Day the Earth Stood Still} {
date: 1952
characters: {GORT Klatoo}
}
}
movies get {The Day the Earth Stood Still} date:
> 1952
- <a name='17'></a>*object* __Option_Default__ *field*
Computes the default value for an option. See __tool::option_handling__.
# <a name='section5'></a>AUTHORS
Sean Woods
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tcloo* 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.
# <a name='keywords'></a>KEYWORDS
[TOOL](../../../../index.md#tool), [TclOO](../../../../index.md#tcloo),
[framework](../../../../index.md#framework)
# <a name='category'></a>CATEGORY
TclOO
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
[//000000001]: # (tool::dict_ensemble - Standardized OO Framework for development)
[//000000002]: # (Generated from file 'tool_dict_ensemble.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tool::dict_ensemble(n) 0.4.2 tcllib "Standardized OO Framework for development")
# NAME
tool::dict_ensemble - Dictionary Tools
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [AUTHORS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require tool ?0.4.2?
[*object* *ensemble* __add__ *field*](#1)
# <a name='description'></a>DESCRIPTION
The __dict_ensemble__ command is a keyword added by __[tool](tool.md)__. It
defines a public variable (stored as a dict), and an access function to
manipulated and access the values stored in that dict.
- <a name='1'></a>*object* *ensemble* __add__ *field*
] *value* *value ...*] Adds elements to a list maintained with the *field*
leaf of the dict maintained my this ensemble. Declares a variable *name*
which will be initialized as an array, populated with *contents* for objects
of this class, as well as any objects for classes which are descendents of
this class.
# <a name='section2'></a>AUTHORS
Sean Woods
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *tool* 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.
# <a name='keywords'></a>KEYWORDS
[TOOL](../../../../index.md#tool), [TclOO](../../../../index.md#tcloo)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/connect.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
|
[//000000001]: # (transfer::connect - Data transfer facilities)
[//000000002]: # (Generated from file 'connect.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::connect(n) 0.2 tcllib "Data transfer facilities")
# NAME
transfer::connect - Connection setup
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Options](#subsection4)
- [Secure connections](#section3)
- [TLS Security Considerations](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit ?1.0?
package require transfer::connect ?0.2?
[__transfer::connect__ *objectName* ?*options*...?](#1)
[*objectName* __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __connect__ *command*](#4)
# <a name='description'></a>DESCRIPTION
This package provides objects holding enough information to enable them to
either actively connect to a counterpart, or to passively wait for a connection
from said counterpart. I.e. any object created by this packages is always in one
of two complementary modes, called *[active](../../../../index.md#active)* (the
object initiates the connection) and *[passive](../../../../index.md#passive)*
(the object receives the connection).
Of the two objects in a connecting pair one has to be configured for
*[active](../../../../index.md#active)* mode, and the other then has to be
configured for *[passive](../../../../index.md#passive)* mode. This establishes
which of the two partners connects to whom (the
*[active](../../../../index.md#active)* to the other), or, who is waiting on
whom (the *[passive](../../../../index.md#passive)* on the other). Note that
this is completely independent of the direction of any data transmission using
the connection after it has been established. An active object can, after
establishing the connection, either transmit or receive data. Equivalently the
passive object can do the same after the waiting for its partner has ended.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__transfer::connect__ *objectName* ?*options*...?
This command creates a new connection object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [Object
command](#subsection2) and [Object methods](#subsection3). The set of
supported *options* is explained in section [Options](#subsection4).
The object command will be created under the current namespace if the
*objectName* is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as the
result of the command.
## <a name='subsection2'></a>Object command
All objects created by the __::transfer::connect__ command have the following
general form:
- <a name='2'></a>*objectName* __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object. This is safe to do for an
*[active](../../../../index.md#active)* object when a connection has been
started, as the completion callback is synchronous. For a
*[passive](../../../../index.md#passive)* object currently waiting for its
partner to establish the connection however this is not safe and will cause
errors later on, when the connection setup completes and tries to access the
now missing data structures of the destroyed object.
- <a name='4'></a>*objectName* __connect__ *command*
This method starts the connection setup per the configuration of the object.
When the connection is established the callback *command* will be invoked
with one additional argument, the channel handle of the socket over which
data can be transfered.
The detailed behaviour of the method depends on the configured mode.
* *[active](../../../../index.md#active)*
The connection setup is done synchronously. The object waits until the
connection is established. The method returns the empty string as its
result.
* *[passive](../../../../index.md#passive)*
The connection setup is done asynchronously. The method returns
immediately after a listening socket has been set up. The connection
will be established in the background. The method returns the port
number of the listening socket, for use by the caller. One important use
is the transfer of this information to the counterpart so that it knows
where it has to connect to.
This is necessary as the object might have been configured for port
__0__, allowing the operating system to choose the actual port it will
listen on.
The listening port is closed immediately when the connection was
established by the partner, to keep the time interval small within which
a third party can connect to the port too. Even so it is recommended to
use additional measures in the protocol outside of the connect and
transfer object to ensure that a connection is not used with an
unidentified/unauthorized partner One possibility for this is the use of
SSL/TLS. See the option __-socketcmd__ and section [Secure
connections](#section3) for information on how to do this.
## <a name='subsection4'></a>Options
Connection objects support the set of options listed below.
- __-mode__ *mode*
This option specifies the mode the object is in. It is optional and defaults
to __active__ mode. The two possible modes are:
* __active__
In this mode the two options __-host__ and __-port__ are relevant and
specify the host and TCP port the object has to connect to. The host is
given by either name or IP address.
* __passive__
In this mode the option __-host__ has no relevance and is ignored should
it be configured. The only option the object needs is __-port__, and it
specifies the TCP port on which the listening socket is opened to await
the connection from the partner.
- __-host__ *hostname-or-ipaddr*
This option specifies the host to connect to in
*[active](../../../../index.md#active)* mode, either by name or ip-address.
An object configured for *[passive](../../../../index.md#passive)* mode
ignores this option.
- __-port__ *int*
For *[active](../../../../index.md#active)* mode this option specifies the
port the object is expected to connect to. For
*[passive](../../../../index.md#passive)* mode however it is the port where
the object creates the listening socket waiting for a connection. It
defaults to __0__, which allows the OS to choose the actual port to listen
on.
- __-socketcmd__ *command*
This option allows the user to specify which command to use to open a
socket. The default is to use the builtin __::socket__. Any compatible with
that command is allowed.
The envisioned main use is the specfication of __tls::socket__. I.e. this
option allows the creation of secure transfer channels, without making this
package explicitly dependent on the __[tls](../../../../index.md#tls)__
package.
See also section [Secure connections](#section3).
- __-encoding__ encodingname
- __-eofchar__ eofspec
- __-translation__ transspec
These options are the same as are recognized by the builtin command
__fconfigure__. They provide the configuration to be set for the channel
between the two partners after it has been established, but before the
callback is invoked (See method __connect__).
# <a name='section3'></a>Secure connections
One way to secure connections made by objects of this package is to require the
package __[tls](../../../../index.md#tls)__ and then configure the option
__-socketcmd__ to force the use of command __tls::socket__ to open the socket.
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create a connector with secure socket setup,
transfer::connect C -socketcmd tls::socket ...
...
# <a name='section4'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[active](../../../../index.md#active), [channel](../../../../index.md#channel),
[connection](../../../../index.md#connection),
[passive](../../../../index.md#passive), [secure](../../../../index.md#secure),
[ssl](../../../../index.md#ssl), [tls](../../../../index.md#tls),
[transfer](../../../../index.md#transfer)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/copyops.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
[//000000001]: # (transfer::copy - Data transfer facilities)
[//000000002]: # (Generated from file 'copyops.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::copy(n) 0.2 tcllib "Data transfer facilities")
# NAME
transfer::copy - Data transfer foundation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require transfer::copy ?0.2?
[__transfer::copy::do__ __chan__|__string__ *data* *outchannel* ?*options*...?](#1)
[__transfer::copy::chan__ *channel* *outchannel* ?*options*...?](#2)
[__transfer::copy::string__ *string* *outchannel* ?*options*...?](#3)
[__transfer::copy::doChan__ *channel* *outchannel* *optvar*](#4)
[__transfer::copy::doString__ *string* *outchannel* *optvar*](#5)
[__transfer::copy::options__ *outchannel* *optionlist* *optvar*](#6)
# <a name='description'></a>DESCRIPTION
This package provides a number of commands for the asynchronous of information
contained in either a string or channel. The main point of this package is that
the commands here provide a nicer callback API than the builtin command
__fcopy__, making the use of these facilities simpler than the builtin.
# <a name='section2'></a>API
- <a name='1'></a>__transfer::copy::do__ __chan__|__string__ *data* *outchannel* ?*options*...?
This command transfers the information in *data* to the *outchannel*,
according to the *options*. The type of the information in *data* is
determined by the first argument.
The options available to this command are the same as are available to the
command __transfer::copy::options__, and explained there.
* __chan__
The argument *data* contains the handle of a channel and the actual
infomration to transfer is read from that channel.
* __string__
The argument *data* contains a string and this is the information to be
transfered.
- <a name='2'></a>__transfer::copy::chan__ *channel* *outchannel* ?*options*...?
This command is a shorter and more direct form for the command
__transfer::copy::do chan__.
- <a name='3'></a>__transfer::copy::string__ *string* *outchannel* ?*options*...?
This command is a shorter and more direct form for the command
__transfer::copy::do string__.
- <a name='4'></a>__transfer::copy::doChan__ *channel* *outchannel* *optvar*
This command is an alternate form of __transfer::copy::chan__ which reads
its options out of the array variable named by *optvar* instead of from a
variable length argument list.
- <a name='5'></a>__transfer::copy::doString__ *string* *outchannel* *optvar*
This command is an alternate form of __transfer::copy::string__ which reads
its options out of the array variable named by *optvar* instead of from a
variable length argument list.
- <a name='6'></a>__transfer::copy::options__ *outchannel* *optionlist* *optvar*
This command is the option processor used by all the commands above which
read their options from a variable length argument list. It first reads
default settings from the channel handle *outchannel*, then processes the
list of options in *optionlist*, at last stores the results in the array
variable named by *optvar*. The contents of that variable are in a format
which is directly understood by all the commands above which read their
options out of an array variable.
The recognized options are:
* __-blocksize__ *int*
This option specifies the size of the chunks to transfer in one
operation. It is optional and defaults to the value of __-buffersize__
as configured for the output channel.
If specified its value has to be an integer number greater than zero.
* __-command__ *commandprefix*
This option specifies the completion callback of the operation. This
option has to be specified. An error will be thrown if it is not, or if
the empty list was specified as argument to it.
Its value has to be a command prefix, i.e. a list whose first word is
the command to execute, followed by words containing fixed arguments.
When the callback is invoked one or two additional arguments are
appended to the prefix. The first argument is the number of bytes which
were transfered. The optional second argument is an error message and
added if and only if an error occured during the the transfer.
* __-progress__ *commandprefix*
This option specifies the progress callback of the operation. It is
optional and defaults to the empty list. This last possibility signals
that no feedback was asked for and disabled it.
Its value has to be a command prefix, see above, __-command__ for a more
detailed explanation. When the callback is invoked a single additional
arguments is appended to the prefix. This argument is the number of
bytes which were transfered so far.
* __-size__ *int*
This option specifies the number of bytes to read from the input data
and transfer. It is optional and defaults to "Transfer everything". Its
value has to be an integer number and any value less than zero has the
same meaning, i.e. to transfer all available data. Any other value is
the amount of bytes to transfer.
All transfer commands will throw error an when their user tries to
transfer more data than is available in the input. This happens
immediately, before the transfer is actually started, should the input
be a string. Otherwise the, i.e. for a channel as input, the error is
thrown the moment the underflow condition is actually detected.
* __-encoding__ *encodingname*
* __-eofchar__ *eofspec*
* __-translation__ *transspec*
These options are the same as are recognized by the builtin command
__fconfigure__ and provide the settings for the output channel which are
to be active during the transfer, and only then. I.e. the settings of
the output channel before the transfer are saved, and restored at the
end of a transfer, regardless of its success or failure. None of these
options are required, and they default to the settings of the output
channel if not specified.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[channel](../../../../index.md#channel), [copy](../../../../index.md#copy),
[transfer](../../../../index.md#transfer)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/ddest.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
[//000000001]: # (transfer::data::destination - Data transfer facilities)
[//000000002]: # (Generated from file 'ddest.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::data::destination(n) 0.2 tcllib "Data transfer facilities")
# NAME
transfer::data::destination - Data destination
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Object command](#subsection1)
- [Object methods](#subsection2)
- [Options](#subsection3)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit ?1.0?
package require transfer::data::destination ?0.2?
[__transfer::data::destination__ *objectName* ?*options*...?](#1)
[*objectName* __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __put__ *chunk*](#4)
[*objectName* __done__](#5)
[*objectName* __valid__ *msgvar*](#6)
[*objectName* __receive__ *channel* *done*](#7)
# <a name='description'></a>DESCRIPTION
This package provides objects mainly describing the destination of a data
transfer. They are also able to initiate the reception of information from a
channel into the described destination.
# <a name='section2'></a>API
- <a name='1'></a>__transfer::data::destination__ *objectName* ?*options*...?
This command creates a new data destination object with an associated Tcl
command whose name is *objectName*. This
*[object](../../../../index.md#object)* command is explained in full detail
in the sections [Object command](#subsection1) and [Object
methods](#subsection2). The set of supported *options* is explained in
section [Options](#subsection3).
The object command will be created under the current namespace if the
*objectName* is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as the
result of the command.
## <a name='subsection1'></a>Object command
All objects created by the __::transfer::data::destination__ command have the
following general form:
- <a name='2'></a>*objectName* __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection2) for the detailed
specifications.
## <a name='subsection2'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object. Doing so while the object is busy with the
reception of information from a channel will cause errors later on, when the
reception completes and tries to access the now missing data structures of
the destroyed object.
- <a name='4'></a>*objectName* __put__ *chunk*
The main receptor method. Saves the received *chunk* of data into the
configured destination. It has to be called for each piece of data received.
- <a name='5'></a>*objectName* __done__
The secondary receptor method. Finalizes the receiver. It has to be called
when the receiving channel signals EOF. Afterward neither itself nor method
__put__ can be called anymore.
- <a name='6'></a>*objectName* __valid__ *msgvar*
This method checks the configuration of the object for validity. It returns
a boolean flag as result, whose value is __True__ if the object is valid,
and __False__ otherwise. In the latter case the variable whose name is
stored in *msgvar* is set to an error message describing the problem found
with the configuration. Otherwise this variable is not touched.
- <a name='7'></a>*objectName* __receive__ *channel* *done*
This method initiates the reception of data from the specified *channel*.
The received data will be stored into the configured destination, via calls
to the methods __put__ and __done__. When the reception completes the
command prefix *done* is invoked, with the number of received characters
appended to it as the sole additional argument.
## <a name='subsection3'></a>Options
All data destinations support the options listed below. It should be noted that
all are semi-exclusive, each specifying a different type of destination and
associated information. If these options are specified more than once then the
last option specified is used to actually configure the object.
- __-channel__ *handle*
This option specifies that the destination of the data is a channel, and its
associated argument is the handle of the channel to write the received data
to.
- __-file__ *path*
This option specifies that the destination of the data is a file, and its
associated argument is the path of the file to write the received data to.
- __-variable__ *varname*
This option specifies that the destination of the data is a variable, and
its associated argument contains the name of the variable to write the
received data to. The variable is assumed to be global or namespaced,
anchored at the global namespace.
- __-progress__ *command*
This option, if specified, defines a command to be invoked for each chunk of
bytes received, allowing the user to monitor the progress of the reception
of the data. The callback is always invoked with one additional argument,
the number of bytes received so far.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[channel](../../../../index.md#channel), [copy](../../../../index.md#copy),
[data destination](../../../../index.md#data_destination),
[transfer](../../../../index.md#transfer)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/dsource.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
[//000000001]: # (transfer::data::source - Data transfer facilities)
[//000000002]: # (Generated from file 'dsource.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::data::source(n) 0.2 tcllib "Data transfer facilities")
# NAME
transfer::data::source - Data source
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Options](#subsection4)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit ?1.0?
package require transfer::copy ?0.2?
package require transfer::data::source ?0.2?
[__transfer::data::source__ *objectName* ?*options*...?](#1)
[*objectName* __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __type__](#4)
[*objectName* __data__](#5)
[*objectName* __size__](#6)
[*objectName* __valid__ *msgvar*](#7)
[*objectName* __transmit__ *channel* *blocksize* *done*](#8)
# <a name='description'></a>DESCRIPTION
This package provides objects mainly describing the origin of some data to
transfer. They are also able to initiate transfers of the described information
to a channel using the foundation package __[transfer::copy](copyops.md)__.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__transfer::data::source__ *objectName* ?*options*...?
This command creates a new data source object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [Object
command](#subsection2) and [Object methods](#subsection3). The set of
supported *options* is explained in section [Options](#subsection4).
The object command will be created under the current namespace if the
*objectName* is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as the
result of the command.
## <a name='subsection2'></a>Object command
All objects created by the __::transfer::data::source__ command have the
following general form:
- <a name='2'></a>*objectName* __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object. Doing so while a transfer initiated by the
object is active is safe as all data required for the transfer itself was
copied, and the completion of the transfer will not try to access the
initiating object anymore. i.e. the transfer is completely separate from the
source object itself.
- <a name='4'></a>*objectName* __type__
This method returns a string describing the type of the data the object is
refering to. The possible values and their meanings are:
* __undefined__
No data was specified at all, or it was specified incompletely. The
object does not know the type.
* __string__
The data to transfer is contained in a string.
* __channel__
The data to transfer is contained in a channel.
- <a name='5'></a>*objectName* __data__
This method returns a value depending on the type of the data the object
refers to, through which the data can be accessed. The method throws an
error if the type is __undefined__. For type __string__ the returned result
is the data itself, whereas for type __channel__ the returned result is the
handle of the channel containing the data.
- <a name='6'></a>*objectName* __size__
This method returns a value depending on the type of the data the object
refers to, the size of the data. The method throws an error if the type is
__undefined__. Return of a negative value signals that the object is unable
to determine an absolute size upfront (like for data in a channel).
- <a name='7'></a>*objectName* __valid__ *msgvar*
This method checks the configuration of the object for validity. It returns
a boolean flag as result, whose value is __True__ if the object is valid,
and __False__ otherwise. In the latter case the variable whose name is
stored in *msgvar* is set to an error message describing the problem found
with the configuration. Otherwise this variable is not touched.
- <a name='8'></a>*objectName* __transmit__ *channel* *blocksize* *done*
This method initiates a transfer of the referenced data to the specified
*channel*. When the transfer completes the command prefix *done* is invoked,
per the rules for the option __-command__ of command __transfer::copy::do__
in the package __[transfer::copy](copyops.md)__. The *blocksize* specifies
the size of the chunks to transfer in one go. See the option __-blocksize__
of command __transfer::copy::do__ in the package
__[transfer::copy](copyops.md)__.
## <a name='subsection4'></a>Options
All data sources support the options listed below. It should be noted that the
first four options are semi-exclusive, each specifying a different type of data
source and associated content. If these options are specified more than once
then the last option specified is used to actually configure the object.
- __-string__ *text*
This option specifies that the source of the data is an immediate string,
and its associated argument contains the string in question.
- __-channel__ *handle*
This option specifies that the source of the data is a channel, and its
associated argument is the handle of the channel containing the data.
- __-file__ *path*
This option specifies that the source of the data is a file, and its
associated argument is the path of the file containing the data.
- __-variable__ *varname*
This option specifies that the source of the data is a string stored in a
variable, and its associated argument contains the name of the variable in
question. The variable is assumed to be global or namespaced, anchored at
the global namespace.
- __-size__ *int*
This option specifies the size of the data transfer. It is optional and
defaults to -1. This value, and any other value less than zero signals to
transfer all the data from the source.
- __-progress__ *command*
This option, if specified, defines a command to be invoked for each chunk of
bytes transmitted, allowing the user to monitor the progress of the
transmission of the data. The callback is always invoked with one additional
argument, the number of bytes transmitted so far.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[channel](../../../../index.md#channel), [copy](../../../../index.md#copy),
[data source](../../../../index.md#data_source),
[transfer](../../../../index.md#transfer)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/receiver.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
|
[//000000001]: # (transfer::receiver - Data transfer facilities)
[//000000002]: # (Generated from file 'receiver.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::receiver(n) 0.2 tcllib "Data transfer facilities")
# NAME
transfer::receiver - Data source
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Options](#subsection4)
- [Secure connections](#section3)
- [TLS Security Considerations](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit ?1.0?
package require transfer::data::destination ?0.2?
package require transfer::connect ?0.2?
package require transfer::receiver ?0.2?
[__transfer::receiver__ *object* ?*options*...?](#1)
[__transfer::receiver__ __stream channel__ *chan* *host* *port* ?*arg*...?](#2)
[__transfer::receiver__ __stream file__ *path* *host* *port* ?*arg*...?](#3)
[*objectName* __method__ ?*arg arg ...*?](#4)
[*objectName* __destroy__](#5)
[*objectName* __start__](#6)
[*objectName* __busy__](#7)
# <a name='description'></a>DESCRIPTION
This package pulls data destinations and connection setup together into a
combined object for the reception of information coming in over a socket. These
objects understand all the options from objects created by the packages
__[transfer::data::destination](ddest.md)__ and
__[transfer::connect](connect.md)__.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__transfer::receiver__ *object* ?*options*...?
This command creates a new receiver object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [Object
command](#subsection2) and [Object methods](#subsection3). The set of
supported *options* is explained in section [Options](#subsection4).
The object command will be created under the current namespace if the
*objectName* is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as the
result of the command.
- <a name='2'></a>__transfer::receiver__ __stream channel__ *chan* *host* *port* ?*arg*...?
This method creates a fire-and-forget transfer for the data coming from the
source at host/port (details below) and writing to the channel *chan*,
starting at the current seek location. The channel is configured to use
binary translation and encoding for the transfer. The channel is *not*
closed when the transfer has completed. This is left to the completion
callback.
If both *host* and *port* are provided an __active__ connection to the data
source is made. If only a *port* is specified (with *host* the empty string)
then a __passive__ connection is made instead, i.e. the receiver then waits
for a conneciton by the transmitter.
Any arguments after the port are treated as options and are used to
configure the internal receiver object. See the section
[Options](#subsection4) for a list of the supported options and their
meaning. *Note* however that the signature of the command prefix specified
for the __-command__ callback differs from the signature for the same option
of the receiver object. This callback is only given the number of bytes and
transfered, and possibly an error message. No reference to the internally
used receiver object is made.
The result returned by the command is the empty string if it was set to make
an *[active](../../../../index.md#active)* connection, and the port the
internal receiver object is listening on otherwise, i.e when it is
configured to connect *[passive](../../../../index.md#passive)*ly. See also
the package __[transfer::connect](connect.md)__ and the description of the
method __connect__ for where this behaviour comes from.
- <a name='3'></a>__transfer::receiver__ __stream file__ *path* *host* *port* ?*arg*...?
This method is like __stream channel__, except that the received data is
written to the file *path*, replacing any prior content.
## <a name='subsection2'></a>Object command
All objects created by the __::transfer::receiver__ command have the following
general form:
- <a name='4'></a>*objectName* __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='5'></a>*objectName* __destroy__
This method destroys the object. Doing so while a reception is on progress
will cause errors later on, when the reception completes and tries to access
the now missing data structures of the destroyed object.
- <a name='6'></a>*objectName* __start__
This method initiates the data reception, setting up the connection first
and then copying the received information into the destination. The method
will throw an error if a reception is already/still in progress. I.e. it is
not possible to run two receptions in parallel, only in sequence. Errors
will also be thrown if the configuration of the data destination is invalid,
or if no completion callback was specified.
The result returned by the method is the empty string for an object
configured to make an *[active](../../../../index.md#active)* connection,
and the port the object is listening on otherwise, i.e when it is configured
to connect *[passive](../../../../index.md#passive)*ly. See also the package
__[transfer::connect](connect.md)__ and the description of the method
__connect__ for where this behaviour comes from.
- <a name='7'></a>*objectName* __busy__
This method returns a boolean value telling us whether a reception is in
progress (__True__), or not (__False__).
## <a name='subsection4'></a>Options
All receiver objects support the union of the options supported by their connect
and data destination components, plus one of their own. See also the
documentation for the packages __[transfer::data::destination](ddest.md)__ and
__[transfer::connect](connect.md)__.
- __-command__ *cmdprefix*
This option specifies the command to invoke when the reception of the
information has been completed. The arguments given to this command are the
same as given to the completion callback of the command
__transfer::copy::do__ provided by the package
__[transfer::copy](copyops.md)__.
- __-mode__ *mode*
This option specifies the mode the object is in. It is optional and defaults
to __active__ mode. The two possible modes are:
* __active__
In this mode the two options __-host__ and __-port__ are relevant and
specify the host and TCP port the object has to connect to. The host is
given by either name or IP address.
* __passive__
In this mode the option __-host__ has no relevance and is ignored should
it be configured. The only option the object needs is __-port__, and it
specifies the TCP port on which the listening socket is opened to await
the connection from the partner.
- __-host__ *hostname-or-ipaddr*
This option specifies the host to connect to in
*[active](../../../../index.md#active)* mode, either by name or ip-address.
An object configured for *[passive](../../../../index.md#passive)* mode
ignores this option.
- __-port__ *int*
For *[active](../../../../index.md#active)* mode this option specifies the
port the object is expected to connect to. For
*[passive](../../../../index.md#passive)* mode however it is the port where
the object creates the listening socket waiting for a connection. It
defaults to __0__, which allows the OS to choose the actual port to listen
on.
- __-socketcmd__ *command*
This option allows the user to specify which command to use to open a
socket. The default is to use the builtin __::socket__. Any compatible with
that command is allowed.
The envisioned main use is the specfication of __tls::socket__. I.e. this
option allows the creation of secure transfer channels, without making this
package explicitly dependent on the __[tls](../../../../index.md#tls)__
package.
See also section [Secure connections](#section3).
- __-encoding__ encodingname
- __-eofchar__ eofspec
- __-translation__ transspec
These options are the same as are recognized by the builtin command
__fconfigure__. They provide the configuration to be set for the channel
between the two partners after it has been established, but before the
callback is invoked (See method __connect__).
- __-channel__ *handle*
This option specifies that the destination of the data is a channel, and its
associated argument is the handle of the channel to write the received data
to.
- __-file__ *path*
This option specifies that the destination of the data is a file, and its
associated argument is the path of the file to write the received data to.
- __-variable__ *varname*
This option specifies that the destination of the data is a variable, and
its associated argument contains the name of the variable to write the
received data to. The variable is assumed to be global or namespaced,
anchored at the global namespace.
- __-progress__ *command*
This option, if specified, defines a command to be invoked for each chunk of
bytes received, allowing the user to monitor the progress of the reception
of the data. The callback is always invoked with one additional argument,
the number of bytes received so far.
# <a name='section3'></a>Secure connections
One way to secure connections made by objects of this package is to require the
package __[tls](../../../../index.md#tls)__ and then configure the option
__-socketcmd__ to force the use of command __tls::socket__ to open the socket.
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create a connector with secure socket setup,
transfer::receiver R -socketcmd tls::socket ...
...
# <a name='section4'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[channel](../../../../index.md#channel), [copy](../../../../index.md#copy),
[data destination](../../../../index.md#data_destination),
[receiver](../../../../index.md#receiver),
[secure](../../../../index.md#secure), [ssl](../../../../index.md#ssl),
[tls](../../../../index.md#tls), [transfer](../../../../index.md#transfer)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/tqueue.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
[//000000001]: # (transfer::copy::queue - Data transfer facilities)
[//000000002]: # (Generated from file 'tqueue.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::copy::queue(n) 0.1 tcllib "Data transfer facilities")
# NAME
transfer::copy::queue - Queued transfers
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Options](#section3)
- [Use](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit ?1.0?
package require struct::queue ?1.4?
package require transfer::copy ?0.2?
package require transfer::copy::queue ?0.1?
[__transfer::copy::queue__ *objectName* *outchannel* ?*options*...?](#1)
[*objectName* __method__ ?*arg arg ...*?](#2)
[*objectName* __destroy__](#3)
[*objectName* __busy__](#4)
[*objectName* __pending__](#5)
[*objectName* __put__ *request*](#6)
# <a name='description'></a>DESCRIPTION
This package provides objects which serialize transfer requests for a single
channel by means of a fifo queue. Accumulated requests are executed in order of
entrance, with the first request reaching an idle object starting the execution
in general. New requests can be added while the object is active and are defered
until all requests entered before them have been completed successfully.
When a request causes a transfer error execution stops and all requests coming
after it are not served. Currently this means that their completion callbacks
are never triggered at all.
*NOTE*: Not triggering the completion callbacks of the unserved requests after
an error stops the queue object is something I am not fully sure that it makes
sense. It forces the user of the queue to remember the callbacks as well and run
them. Because otherwise everything in the system which depends on getting a
notification about the status of a request will hang in the air. I am slowly
convincing myself that it is more sensible to trigger the relevant completion
callbacks with an error message about the queue abort, and 0 bytes transfered.
All transfer requests are of the form
{type data options...}
where *type* is in {__chan__, __string__}, and *data* specifies the information
to transfer. For __chan__ the data is the handle of the channel containing the
actual information to transfer, whereas for __string__ *data* contains directly
the information to transfer. The *options* are a list of them and their values,
and are the same as are accepted by the low-level copy operations of the package
__[transfer::copy](copyops.md)__. Note how just prepending the request with
__transfer::copy::do__ and inserting a channel handle in between *data* and
*options* easily transforms it from a pure data structure into a command whose
evaluation will perform the request.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__transfer::copy::queue__ *objectName* *outchannel* ?*options*...?
This command creates a new queue object for the management of the channel
*outchannel*, with an associated Tcl command whose name is *objectName*.
This *[object](../../../../index.md#object)* command is explained in full
detail in the sections [Object command](#subsection2) and [Object
methods](#subsection3). The set of supported *options* is explained in
section [Options](#section3).
The object command will be created under the current namespace if the
*objectName* is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as the
result of the command.
## <a name='subsection2'></a>Object command
All objects created by the __::transfer::copy::queue__ command have the
following general form:
- <a name='2'></a>*objectName* __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='3'></a>*objectName* __destroy__
This method destroys the object. Doing so while the object is busy will
cause errors later on, when the currently executed request completes and
tries to access the now missing data structures of the destroyed object.
- <a name='4'></a>*objectName* __busy__
This method returns a boolean value telling us if the object is currently
serving a request (i.e. *busy*, value __True__), or not (i.e.
*[idle](../../../../index.md#idle)*, value __False__).
- <a name='5'></a>*objectName* __pending__
This method returns the number of requests currently waiting in the queue
for their execution. A request currently served is not counted as waiting.
- <a name='6'></a>*objectName* __put__ *request*
This method enters the transfer *request* into the object's queue of waiting
requests. If the object is *[idle](../../../../index.md#idle)* it will
become *busy*, immediately servicing the request. Otherwise servicing the
new request will be defered until all preceding requests have been served.
# <a name='section3'></a>Options
The only option known is __-on-status-change__. It is optional and defaults to
the empty list, disabling the reporting of status changes. Otherwise its
argument is a command prefix which is invoked whenever the internal status of
the object changed. The callback is invoked with two additional arguments, the
result of the methods __pending__ and __busy__, in this order. This allows any
user to easily know, for example, when the object has processed all outstanding
requests.
# <a name='section4'></a>Use
A possible application of this package and class is within a HTTP 1.1 server,
managing the results waiting for transfer to the client.
It should be noted that in this application the system also needs an additional
data structure which keeps track of outstanding results as they may come back in
a different order than the requests from the client, and releases them to the
actual queue in the proper order.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[channel](../../../../index.md#channel), [copy](../../../../index.md#copy),
[queue](../../../../index.md#queue), [transfer](../../../../index.md#transfer)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/transfer/transmitter.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
|
[//000000001]: # (transfer::transmitter - Data transfer facilities)
[//000000002]: # (Generated from file 'transmitter.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (transfer::transmitter(n) 0.2 tcllib "Data transfer facilities")
# NAME
transfer::transmitter - Data source
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Package commands](#subsection1)
- [Object command](#subsection2)
- [Object methods](#subsection3)
- [Options](#subsection4)
- [Secure connections](#section3)
- [TLS Security Considerations](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require snit ?1.0?
package require transfer::copy ?0.2?
package require transfer::data::source ?0.2?
package require transfer::connect ?0.2?
package require transfer::transmitter ?0.2?
[__transfer::transmitter__ *objectName* ?*options*...?](#1)
[__transfer::transmitter__ __stream channel__ *chan* *host* *port* ?*arg*...?](#2)
[__transfer::transmitter__ __stream file__ *path* *host* *port* ?*arg*...?](#3)
[*objectName* __method__ ?*arg arg ...*?](#4)
[*objectName* __destroy__](#5)
[*objectName* __start__](#6)
[*objectName* __busy__](#7)
# <a name='description'></a>DESCRIPTION
This package pulls data sources and connection setup together into a combined
object for the transmission of information over a socket. These objects
understand all the options from objects created by the packages
__[transfer::data::source](dsource.md)__ and
__[transfer::connect](connect.md)__.
# <a name='section2'></a>API
## <a name='subsection1'></a>Package commands
- <a name='1'></a>__transfer::transmitter__ *objectName* ?*options*...?
This command creates a new transmitter object with an associated Tcl command
whose name is *objectName*. This *[object](../../../../index.md#object)*
command is explained in full detail in the sections [Object
command](#subsection2) and [Object methods](#subsection3). The set of
supported *options* is explained in section [Options](#subsection4).
The object command will be created under the current namespace if the
*objectName* is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as the
result of the command.
- <a name='2'></a>__transfer::transmitter__ __stream channel__ *chan* *host* *port* ?*arg*...?
This method creates a fire-and-forget transfer for the data contained in the
channel *chan*, starting at the current seek location. The channel is
configured to use binary translation and encoding for the transfer. The
channel is automatically closed when the transfer has completed.
If both *host* and *port* are provided an __active__ connection to the
destination is made. If only a *port* is specified (with *host* the empty
string) then a __passive__ connection is made instead.
Any arguments after the port are treated as options and are used to
configure the internal transmitter object. See the section
[Options](#subsection4) for a list of the supported options and their
meaning. *Note* however that the signature of the command prefix specified
for the __-command__ callback differs from the signature for the same option
of the transmitter object. This callback is only given the number of bytes
and transfered, and possibly an error message. No reference to the
internally used transmitter object is made.
The result returned by the command is the empty string if it was set to make
an *[active](../../../../index.md#active)* connection, and the port the
internal transmitter object is listening on otherwise, i.e when it is
configured to connect *[passive](../../../../index.md#passive)*ly. See also
the package __[transfer::connect](connect.md)__ and the description of the
method __connect__ for where this behaviour comes from.
- <a name='3'></a>__transfer::transmitter__ __stream file__ *path* *host* *port* ?*arg*...?
This method is like __stream channel__, except that the data contained in
the file *path* is transfered.
## <a name='subsection2'></a>Object command
All objects created by the __::transfer::transmitter__ command have the
following general form:
- <a name='4'></a>*objectName* __method__ ?*arg arg ...*?
The method __method__ and its *arg*'uments determine the exact behavior of
the command. See section [Object methods](#subsection3) for the detailed
specifications.
## <a name='subsection3'></a>Object methods
- <a name='5'></a>*objectName* __destroy__
This method destroys the object. Doing so while a transmission is in
progress will cause errors later on, when the transmission completes and
tries to access the now missing data structures of the destroyed object.
- <a name='6'></a>*objectName* __start__
This method initiates the data transmission, setting up the connection first
and then copying the information. The method will throw an error if a
transmission is already/still in progress. I.e. it is not possible to run
two transmissions in parallel on a single object, only in sequence. Multiple
transmitter objects are needed to manage parallel transfers, one per
transmission. Errors will also be thrown if the configuration of the data
source is invalid, or if no completion callback was specified.
The result returned by the method is the empty string for an object
configured to make an *[active](../../../../index.md#active)* connection,
and the port the object is listening on otherwise, i.e when it is configured
to connect *[passive](../../../../index.md#passive)*ly. See also the package
__[transfer::connect](connect.md)__ and the description of the method
__connect__ for where this behaviour comes from.
- <a name='7'></a>*objectName* __busy__
This method returns a boolean value telling us whether a transmission is in
progress (__True__), or not (__False__).
## <a name='subsection4'></a>Options
All transmitter objects support the union of the options supported by their
connect and data source components, plus two of their own. See also the
documentation for the packages __[transfer::data::source](dsource.md)__ and
__[transfer::connect](connect.md)__.
- __-blocksize__ *int*
This option specifies the size of the chunks to be transmitted in one block.
Usage is optional, its default value is __1024__.
- __-command__ *cmdprefix*
This option specifies the command to invoke when the transmission of the
information has been completed. The arguments given to this command are the
same as given to the completion callback of the command
__transfer::copy::do__ provided by the package
__[transfer::copy](copyops.md)__.
- __-mode__ *mode*
This option specifies the mode the object is in. It is optional and defaults
to __active__ mode. The two possible modes are:
* __active__
In this mode the two options __-host__ and __-port__ are relevant and
specify the host and TCP port the object has to connect to. The host is
given by either name or IP address.
* __passive__
In this mode the option __-host__ has no relevance and is ignored should
it be configured. The only option the object needs is __-port__, and it
specifies the TCP port on which the listening socket is opened to await
the connection from the partner.
- __-host__ *hostname-or-ipaddr*
This option specifies the host to connect to in
*[active](../../../../index.md#active)* mode, either by name or ip-address.
An object configured for *[passive](../../../../index.md#passive)* mode
ignores this option.
- __-port__ *int*
For *[active](../../../../index.md#active)* mode this option specifies the
port the object is expected to connect to. For
*[passive](../../../../index.md#passive)* mode however it is the port where
the object creates the listening socket waiting for a connection. It
defaults to __0__, which allows the OS to choose the actual port to listen
on.
- __-socketcmd__ *command*
This option allows the user to specify which command to use to open a
socket. The default is to use the builtin __::socket__. Any compatible with
that command is allowed.
The envisioned main use is the specfication of __tls::socket__. I.e. this
option allows the creation of secure transfer channels, without making this
package explicitly dependent on the __[tls](../../../../index.md#tls)__
package.
See also section [Secure connections](#section3).
- __-encoding__ encodingname
- __-eofchar__ eofspec
- __-translation__ transspec
These options are the same as are recognized by the builtin command
__fconfigure__. They provide the configuration to be set for the channel
between the two partners after it has been established, but before the
callback is invoked (See method __connect__).
- __-string__ *text*
This option specifies that the source of the data is an immediate string,
and its associated argument contains the string in question.
- __-channel__ *handle*
This option specifies that the source of the data is a channel, and its
associated argument is the handle of the channel containing the data.
- __-file__ *path*
This option specifies that the source of the data is a file, and its
associated argument is the path of the file containing the data.
- __-variable__ *varname*
This option specifies that the source of the data is a string stored in a
variable, and its associated argument contains the name of the variable in
question. The variable is assumed to be global or namespaced, anchored at
the global namespace.
- __-size__ *int*
This option specifies the size of the data transfer. It is optional and
defaults to -1. This value, and any other value less than zero signals to
transfer all the data from the source.
- __-progress__ *command*
This option, if specified, defines a command to be invoked for each chunk of
bytes transmitted, allowing the user to monitor the progress of the
transmission of the data. The callback is always invoked with one additional
argument, the number of bytes transmitted so far.
# <a name='section3'></a>Secure connections
One way to secure connections made by objects of this package is to require the
package __[tls](../../../../index.md#tls)__ and then configure the option
__-socketcmd__ to force the use of command __tls::socket__ to open the socket.
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create a connector with secure socket setup,
transfer::transmitter T -socketcmd tls::socket ...
...
# <a name='section4'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *transfer* 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.
# <a name='keywords'></a>KEYWORDS
[channel](../../../../index.md#channel), [copy](../../../../index.md#copy),
[data source](../../../../index.md#data_source),
[secure](../../../../index.md#secure), [ssl](../../../../index.md#ssl),
[tls](../../../../index.md#tls), [transfer](../../../../index.md#transfer),
[transmitter](../../../../index.md#transmitter)
# <a name='category'></a>CATEGORY
Transfer module
# <a name='copyright'></a>COPYRIGHT
Copyright © 2006-2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/treeql/treeql.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
|
[//000000001]: # (treeql - Tree Query Language)
[//000000002]: # (Generated from file 'treeql.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (treeql(n) 1.3.1 tcllib "Tree Query Language")
# NAME
treeql - Query tree objects
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [TreeQL CLASS API](#subsection1)
- [TreeQL OBJECT API](#subsection2)
- [The Tree Query Language](#section3)
- [TreeQL Concepts](#subsection3)
- [Structural generators](#subsection4)
- [Attribute Filters](#subsection5)
- [Attribute Mutators](#subsection6)
- [Attribute String Accessors](#subsection7)
- [Sub-queries](#subsection8)
- [Node Set Operators](#subsection9)
- [Node Set Iterators](#subsection10)
- [Typed node support](#subsection11)
- [Examples](#section4)
- [References](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require snit
package require struct::list
package require struct::set
package require treeql ?1.3.1?
[__treeql__ *objectname* __-tree__ *tree* ?__-query__ *query*? ?__-nodes__ *nodes*? ?*args*...?](#1)
[*qo* __query__ *args*...](#2)
[*qo* __result__](#3)
[*qo* __discard__](#4)
# <a name='description'></a>DESCRIPTION
This package provides objects which can be used to query and transform tree
objects following the API of tree objects created by the package
__[struct::tree](../struct/struct_tree.md)__.
The tree query and manipulation language used here, TreeQL, is inspired by Cost
(See section [References](#section5) for more information).
__treeql__, the package, is a fairly thin query facility over tree-structured
data types. It implements an ordered set of nodes (really a list) which are
generated and filtered through the application of TreeQL operators to each node
in turn.
# <a name='section2'></a>API
## <a name='subsection1'></a>TreeQL CLASS API
The command __treeql__ is a __[snit](../snit/snit.md)__::type which implements
the Treeql Query Language. This means that it follows the API for class commands
as specified by the package __[snit](../snit/snit.md)__. Its general syntax is
- <a name='1'></a>__treeql__ *objectname* __-tree__ *tree* ?__-query__ *query*? ?__-nodes__ *nodes*? ?*args*...?
The command creates a new tree query object and returns the fully qualified
name of the object command as its result. The API the returned command is
following is described in the section [TreeQL OBJECT API](#subsection2)
Each query object is associated with a single *tree* object. This is the
object all queries will be run against.
If the option __-nodes__ was specified then its argument is treated as a
list of nodes. This list is used to initialize the node set. It defaults to
the empty list.
If the option __-query__ was specified then its argument will be interpreted
as an object, the *parent query* of this query. It defaults to the object
itself. All queries will be interpreted in the environment of this object.
Any arguments coming after the options are treated as a query and run
immediately, after the *node set* has been initialized. This uses the same
syntax for the query as the method __query__.
The operations of the TreeQL available for this are explained in the section
about [The Tree Query Language](#section3). This section also explains the
term *node set* used above.
## <a name='subsection2'></a>TreeQL OBJECT API
As __treeql__ has been implemented in __[snit](../snit/snit.md)__ all the
standard methods of __[snit](../snit/snit.md)__-based classes are available to
the user and therefore not listed here. Please read the documentation for
__[snit](../snit/snit.md)__ for what they are and what functionality they
provide
The methods provided by the package __treeql__ itself are listed and explained
below.
- <a name='2'></a>*qo* __query__ *args*...
This method interprets its arguments as a series of TreeQL operators and
interpretes them from the left to right (i.e. first to last). Note that the
first operator uses the *node set* currently known to the object to perform
its actions. In other words, the *node set* is *not* cleared, or modified in
other ways, before the query is run. This allows the user to run several
queries one after the other and have each use the results of the last. Any
initialization has to be done by any query itself, using TreeQL operators.
The result of the method is the *node set* after the last operator of the
query has been executed.
*Note* that uncaught errors will leave the *node set* of the object in an
intermediate state, per the TreeQL operators which were executed
successfully before the error occurred.
The above means in detail that:
The first argument is interpreted as the name of a query operator, the
number of arguments required by that operator is then determined, and taken
from the immediately following arguments.
Because of this operators cannot have optional arguments, all arguments have
to be present as defined. Failure to do this will, at least, confuse the
query interpreter, but more likely cause errors.
The operator is applied to the current node set, yielding a new node set,
and/or manipulating the tree object the query object is connected to.
The arguments used (i.e. operator name and arguments) are removed from the
list of method arguments, and then the whole process is repeated from step
[1], until the list of arguments is empty or an error occurred.
# q is the query object.
q query root children get data
# The above query
# - Resets the node set to the root node - root
# - Adds the children of root to the set - children
# - Replaces the node set with the - get data
# values for the attribute 'data',
# for all nodes in the set which
# have such an attribute.
# - And returns this information.
# Below we can see the same query, but rewritten
# to show the structure as it is seen by the query
# interpreter.
q query \\
root \\
children \\
get data
The operators of the TreeQL language available for this are explained in the
section about [The Tree Query Language](#section3). This section also
explains the term *node set* used above.
- <a name='3'></a>*qo* __result__
This method returns a list containing the current node set.
- <a name='4'></a>*qo* __discard__
This method returns the current node set (like method __result__), but also
destroys the query object (*qo*). This is useful when constructing and using
sub-queries (%AUTO% objects immediately destroyed after use).
# <a name='section3'></a>The Tree Query Language
This and the following sections specify the Tree Query Language used by the
query objects of this package in detail.
First we explain the general concepts underneath the language which are required
to comprehend it. This is followed by the specifications for all the available
query operators. They fall into eight categories, and each category has its own
section.
1. [TreeQL Concepts](#subsection3)
1. [Structural generators](#subsection4)
1. [Attribute Filters](#subsection5)
1. [Attribute Mutators](#subsection6)
1. [Attribute String Accessors](#subsection7)
1. [Sub-queries](#subsection8)
1. [Node Set Operators](#subsection9)
1. [Node Set Iterators](#subsection10)
1. [Typed node support](#subsection11)
## <a name='subsection3'></a>TreeQL Concepts
The main concept which has to be understood is that of the *node set*. Each
query object maintains exactly one such *node set*, and essentially all
operators use it and input argument and for their result. This structure simply
contains the handles of all nodes which are currently of interest to the query
object. To name it a *[set](../../../../index.md#set)* is a bit of a misnomer,
because
1. A node (handle) can occur in the structure more than once, and
1. the order of nodes in the structure is important as well. Whenever an
operator processes all nodes in the node set it will do so in the order
they occur in the structure.
Regarding the possible multiple occurrence of a node, consider a node set
containing two nodes A and B, both having node P as their immediate parent.
Application of the TreeQL operator "parent" will then add P to the new node set
twice, once per node it was parent of. I.e. the new node set will then be {P P}.
## <a name='subsection4'></a>Structural generators
All tree-structural operators locate nodes in the tree based on a structural
relation ship to the nodes currently in the set and then replace the current
node set with the set of nodes found Nodes which fulfill such a relationship
multiple times are added to the result as often as they fulfill the
relationship.
It is important to note that the found nodes are collected in a separate storage
area while processing the node set, and are added to (or replacing) the current
node set only after the current node set has been processed completely. In other
words, the new nodes are *not* processed by the operator as well and do not
affect the iteration.
When describing an operator the variable __N__ will be used to refer to any node
in the node set.
- __ancestors__
Replaces the current node set with the ancestors for all nodes __N__ in the
node set, should __N__ have a parent. In other words, nodes without a parent
do not contribute to the new node set. In other words, uses all nodes on the
path from node __N__ to root, in this order (root last), for all nodes __N__
in the node set. This includes the root, but not the node itself.
- __rootpath__
Replaces the current node set with the ancestors for all nodes __N__ in the
node set, should __N__ have a parent. In other words, nodes without a parent
do not contribute to the new node set. In contrast to the operator
__ancestors__ the nodes are added in reverse order however, i.e. the root
node first.
- __parent__
Replaces the current node set with the parent of node __N__, for all nodes
__N__ in the node set, should __N__ have a parent. In other words, nodes
without a parent do not contribute to the new node set.
- __children__
Replaces the current node set with the immediate children of node __N__, for
all nodes __N__ in the node set, should __N__ have children. In other words,
nodes without children do not contribute to the new node set.
- __left__
Replaces the current node set with the previous/left sibling for all nodes
__N__ in the node set, should __N__ have siblings to the left. In other
words, nodes without left siblings do not contribute to the new node set.
- __right__
Replaces the current node set with the next/right sibling for all nodes
__N__ in the node set, should __N__ have siblings to the right. In other
words, nodes without right siblings do not contribute to the new node set.
- __prev__
Replaces the current node set with all previous/left siblings of node __N__,
for all nodes __N__ in the node set, should __N__ have siblings to the left.
In other words, nodes without left siblings are ignored. The left sibling
adjacent to the node is added first, and the leftmost sibling last (reverse
tree order).
- __esib__
Replaces the current node set with all previous/left siblings of node __N__,
for all nodes __N__ in the node set, should __N__ have siblings to the left.
In other words, nodes without left siblings are ignored. The leftmost
sibling is added first, and the left sibling adjacent to the node last (tree
order).
The method name is a shorthand for *Earlier SIBling*.
- __next__
Replaces the current node set with all next/right siblings of node __N__,
for all nodes __N__ in the node set, should __N__ have siblings to the
right. In other words, nodes without right siblings do not contribute to the
new node set. The right sibling adjacent to the node is added first, and the
rightmost sibling last (tree order).
- __root__
Replaces the current node set with a node set containing a single node, the
root of the tree.
- __tree__
Replaces the current node set with a node set containing all nodes found in
the tree. The nodes are added in pre-order (parent first, then children, the
latter from left to right, first to last).
- __descendants__
Replaces the current node set with the nodes in all subtrees rooted at node
__N__, for all nodes __N__ in the node set, should __N__ have children. In
other words, nodes without children do not contribute to the new node set.
This is like the operator __children__, but covers the children of children
as well, i.e. all the *proper descendants*. "Rooted at __N__" means that
__N__ itself is not added to the new set, which is also implied by *proper
descendants*.
- __subtree__
Like operator __descendants__, but includes the node __N__. In other words:
Replaces the current node set with the nodes of the subtree of node __N__,
for all nodes __N__ in the node set, should __N__ have children. In other
words, nodes without children do not contribute to the new node set. I.e
this is like the operator __children__, but covers the children of children,
etc. as well. "Of __N__" means that __N__ itself is added to the new set.
- __forward__
Replaces the current node set with the nodes in the subtrees rooted at the
right siblings of node __N__, for all nodes __N__ in the node set, should
__N__ have right siblings, and they children. In other words, nodes without
right siblings, and them without children are ignored.
This is equivalent to the operator sequence
next descendants
- __later__
This is an alias for the operator __forward__.
- __backward__
Replaces the current node set with the nodes in the flattened previous
subtrees, in reverse tree order.
This is nearly equivalent to the operator sequence
prev descendants
The only difference is that this uses the nodes in reverse order.
- __earlier__
Replaces the current node set with the nodes in the flattened previous
subtrees, in tree order.
This is equivalent to the operator sequence
prev subtree
## <a name='subsection5'></a>Attribute Filters
These operators filter the node set by reference to attributes of nodes and
their properties. Filter means that all nodes not fulfilling the criteria are
removed from the node set. In other words, the node set is replaced by the set
of nodes fulfilling the filter criteria.
- __hasatt__ *attr*
Reduces the node set to nodes which have an attribute named *attr*.
- __withatt__ *attr* *value*
Reduces the node set to nodes which have an attribute named *attr*, and
where the value of that attribute is equal to *value* (The "==" operator is
__string equal -nocase__).
- __withatt!__ *attr* *val*
This is the same as __withatt__, but all nodes in the node set have to have
the attribute, and the "==" operator is __string equal__, i.e. no
__-nocase__. The operator will fail with an error if they don't have the
attribute.
- __attof__ *attr* *vals*
Reduces the node set to nodes which which have an attribute named *attr* and
where the value of that attribute is contained in the list *vals* of legal
values. The contained-in operator used here does glob matching (using the
attribute value as pattern) and ignores the case of the attribute value,
*but not* for the elements of *vals*.
- __attmatch__ *attr* *match*
Same as __withatt__, but __string match__ is used as the "==" operator, and
*match* is the pattern checked for.
*Note* that *match* is a interpreted as a partial argument *list* for
__string match__. This means that it is interpreted as a list containing the
pattern, and the pattern element can be preceded by options understand by
__string match__, like __-nocase__. This is especially important should the
pattern contain spaces. It has to be wrapped into a list for correct
interpretation by this operator
## <a name='subsection6'></a>Attribute Mutators
These operators change node attributes within the underlying tree. In other
words, all these operators have *side effects*.
- __set__ *attr* *val*
Sets the attribute *attr* to the value *val*, for all nodes __N__ in the
node set. The operator will fail if a node does not have an attribute named
*attr*. The tree will be left in a partially modified state.
- __unset__ *attr*
Unsets the attribute *attr*, for all nodes __N__ in the node set. The
operator will fail if a node does not have an attribute named *attr*. The
tree will be left in a partially modified state.
## <a name='subsection7'></a>Attribute String Accessors
These operators retrieve the values of node attributes from the underlying tree.
The collected results are stored in the node set, but are not actually nodes.
In other words, they redefine the semantics of the node set stored by the query
object to contain non-node data after their completion.
The query interpreter will terminate after it has finished processing one of
these operators, silently discarding any later query elements. It also means
that our talk about maintenance of a node set is not quite true. It is a node
set while the interpreter is processing commands, but can be left as an
attribute value set at the end of query processing.
- __string__ *op* *attr*
Applies the string operator *op* to the attribute named *attr*, for all
nodes __N__ in the node set, collects the results of that application and
places them into the node set.
The operator will fail if a node does not have an attribute named *attr*.
The argument *op* is interpreted as partial argument list for the builtin
command __[string](../../../../index.md#string)__. Its first word has to be
any of the sub-commands understood by
__[string](../../../../index.md#string)__. This has to be followed by all
arguments required for the subcommand, except the last. that last argument
is supplied by the attribute value.
- __get__ *pattern*
For all nodes __N__ in the node set it determines all their attributes with
names matching the glob *pattern*, then the values of these attributes, at
last it replaces the node set with the list of these attribute values.
- __attlist__
This is a convenience definition for the operator __getvals *__. In other
words, it replaces the node set with a list of the attribute values for all
attributes for all nodes __N__ in the node set.
- __attrs__ *glob*
Replaces the current node set with a list of attribute lists, one attribute
list per for all nodes __N__ in the node set.
- __attval__ *attname*
Reduces the current node set with the operator __hasatt__, and then replaces
it with a list containing the values of the attribute named *attname* for
all nodes __N__ in the node set.
## <a name='subsection8'></a>Sub-queries
Sub-queries yield node sets which are then used to augment, reduce or replace
the current node set.
- __andq__ *query*
Replaces the node set with the set-intersection of the node set generated by
the sub-query *query* and itself.
The execution of the sub-query uses the current node set as its own initial
node set.
- __orq__ *query*
Replaces the node set with the set-union of the node set generated by the
sub-query *query* and itself. Duplicate nodes are removed.
The execution of the sub-query uses the current node set as its own initial
node set.
- __notq__ *query*
Replaces the node set with the set of nodes generated by the sub-query
*query* which are also not in the current node set. In other word the set
difference of itself and the node set generated by the sub-query.
The execution of the sub-query uses the current node set as its own initial
node set.
## <a name='subsection9'></a>Node Set Operators
These operators change the node set directly, without referring to the tree.
- __unique__
Removes duplicate nodes from the node set, preserving order. In other words,
the earliest occurrence of a node handle is preserved, every other
occurrence is removed.
- __select__
Replaces the current node set with a node set containing only the first node
from the current node set
- __transform__ *query* *var* *body*
First it interprets the sub-query *query*, using the current node set as its
initial node set. Then it iterates over the result of that query, binding
the handle of each node to the variable named in *var*, and executing the
script *body*. The collected results of these executions is made the new
node set, replacing the current one.
The script *body* is executed in the context of the caller.
- __map__ *var* *body*
Iterates over the current node set, binding the handle of each node to the
variable named in *var*, and executing the script *body*. The collected
results of these executions is made the new node set, replacing the current
one.
The script *body* is executed in the context of the caller.
- __quote__ *val*
Appends the literal value *val* to the current node set.
- __replace__ *val*
Replaces the current node set with the literal list value *val*.
## <a name='subsection10'></a>Node Set Iterators
- __foreach__ *query* *var* *body*
Interprets the sub-query *query*, then performs the equivalent of operator
__over__ on the nodes in the node set created by that query. The current
node set is not changed, except through side effects from the script *body*.
The script *body* is executed in the context of the caller.
- __with__ *query* *body*
Interprets the *query*, then runs the script *body* on the node set
generated by the query. At last it restores the current node set as it was
before the execution of the query.
The script *body* is executed in the context of the caller.
- __over__ *var* *body*
Executes the script *body* for each node in the node set, with the variable
named by *var* bound to the name of the current node. The script *body* is
executed in the context of the caller.
This is like the builtin __[foreach](../../../../index.md#foreach)__, with
the node set as the source of the list to iterate over.
The results of executing the *body* are ignored.
- __delete__
Deletes all the nodes contained in the current node set from the tree.
## <a name='subsection11'></a>Typed node support
These filters and accessors assume the existence of an attribute called
__@type__, and are short-hand forms useful for cost-like tree query, html tree
editing, and so on.
- __nodetype__
Returns the node type of nodes. Attribute string accessor. This is
equivalent to
get @type
- __oftype__ *t*
Reduces the node set to nodes whose type is equal to *t*, with letter case
ignored.
- __nottype__ *t*
Reduces the node set to nodes whose type is not equal to *t*, with letter
case ignored.
- __oftypes__ *attrs*
Reduces set to nodes whose @type is an element in the list *attrs* of types.
The value of @type is used as a glob pattern, and letter case is relevant.
# <a name='section4'></a>Examples
... TODO ...
# <a name='section5'></a>References
1. [COST](http://wiki.tcl.tk/COST) on the Tcler's Wiki.
1. [TreeQL](http://wiki.tcl.tk/treeql) on the Tcler's Wiki. Discuss this
package there.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *treeql* 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.
# <a name='keywords'></a>KEYWORDS
[Cost](../../../../index.md#cost), [DOM](../../../../index.md#dom),
[TreeQL](../../../../index.md#treeql), [XPath](../../../../index.md#xpath),
[XSLT](../../../../index.md#xslt), [structured
queries](../../../../index.md#structured_queries),
[tree](../../../../index.md#tree), [tree query
language](../../../../index.md#tree_query_language)
# <a name='category'></a>CATEGORY
Data structures
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004 Colin McCormack <[email protected]>
Copyright © 2004 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/try/tcllib_throw.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
[//000000001]: # (throw - Forward compatibility implementation of [throw])
[//000000002]: # (Generated from file 'tcllib_throw.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (throw(n) 1 tcllib "Forward compatibility implementation of [throw]")
# NAME
throw - throw - Throw an error exception with a message
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require throw ?1?
[__::throw__ *error_code* *error_message*](#1)
# <a name='description'></a>DESCRIPTION
This package provides a forward-compatibility implementation of Tcl 8.6's throw
command (TIP 329), for Tcl 8.5. The code was directly pulled from Tcl 8.6
revision ?, when try/finally was implemented as Tcl procedure instead of in C.
- <a name='1'></a>__::throw__ *error_code* *error_message*
throw is merely a reordering of the arguments of the error command. It
throws an error with the indicated error code and error message.
# <a name='section2'></a>EXAMPLES
__throw__ {MYERROR CODE} "My error message"
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *try* 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.
# <a name='see-also'></a>SEE ALSO
error(n)
# <a name='keywords'></a>KEYWORDS
[error](../../../../index.md#error), [return](../../../../index.md#return),
[throw](../../../../index.md#throw)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2015 Miguel MartÃnez López, BSD licensed
|
Added embedded/md/tcllib/files/modules/try/tcllib_try.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
[//000000001]: # (try - Forward compatibility implementation of [try])
[//000000002]: # (Generated from file 'tcllib_try.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (try(n) 1 tcllib "Forward compatibility implementation of [try]")
# NAME
try - try - Trap and process errors and exceptions
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [EXAMPLES](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require try ?1?
[__::try__ *body* ?*handler...*? ?__finally__ *script*?](#1)
# <a name='description'></a>DESCRIPTION
This package provides a forward-compatibility implementation of Tcl 8.6's
try/finally command (TIP 329), for Tcl 8.5. The code was directly pulled from
Tcl 8.6 revision ?, when try/finally was implemented as Tcl procedure instead of
in C.
- <a name='1'></a>__::try__ *body* ?*handler...*? ?__finally__ *script*?
This command executes the script *body* and, depending on what the outcome
of that script is (normal exit, error, or some other exceptional result),
runs a handler script to deal with the case. Once that has all happened, if
the __finally__ clause is present, the *script* it includes will be run and
the result of the handler (or the *body* if no handler matched) is allowed
to continue to propagate. Note that the __finally__ clause is processed even
if an error occurs and irrespective of which, if any, *handler* is used.
The *handler* clauses are each expressed as several words, and must have one
of the following forms:
* __on__ *code variableList script*
This clause matches if the evaluation of *body* completed with the
exception code *code*. The *code* may be expressed as an integer or one
of the following literal words: __ok__, __error__, __return__,
__break__, or __continue__. Those literals correspond to the integers 0
through 4 respectively.
* __trap__ *pattern variableList script*
This clause matches if the evaluation of *body* resulted in an error and
the prefix of the __-errorcode__ from the interpreter's status
dictionary is equal to the *pattern*. The number of prefix words taken
from the __-errorcode__ is equal to the list-length of *pattern*, and
inter-word spaces are normalized in both the __-errorcode__ and
*pattern* before comparison.
The *variableList* word in each *handler* is always interpreted as a
list of variable names. If the first word of the list is present and
non-empty, it names a variable into which the result of the evaluation
of *body* (from the main __try__) will be placed; this will contain the
human-readable form of any errors. If the second word of the list is
present and non-empty, it names a variable into which the options
dictionary of the interpreter at the moment of completion of execution
of *body* will be placed.
The *script* word of each *handler* is also always interpreted the same:
as a Tcl script to evaluate if the clause is matched. If *script* is a
literal __-__ and the *handler* is not the last one, the *script* of the
following *handler* is invoked instead (just like with the __switch__
command).
Note that *handler* clauses are matched against in order, and that the
first matching one is always selected. At most one *handler* clause will
selected. As a consequence, an __on error__ will mask any subsequent
__trap__ in the __try__. Also note that __on error__ is equivalent to
__trap {}__.
If an exception (i.e. any non-__ok__ result) occurs during the
evaluation of either the *handler* or the __finally__ clause, the
original exception's status dictionary will be added to the new
exception's status dictionary under the __-during__ key.
# <a name='section2'></a>EXAMPLES
Ensure that a file is closed no matter what:
set f [open /some/file/name a]
__try__ {
puts \$f "some message"
# ...
} __finally__ {
close \$f
}
Handle different reasons for a file to not be openable for reading:
__try__ {
set f [open /some/file/name]
} __trap__ {POSIX EISDIR} {} {
puts "failed to open /some/file/name: it's a directory"
} __trap__ {POSIX ENOENT} {} {
puts "failed to open /some/file/name: it doesn't exist"
}
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *try* 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.
# <a name='see-also'></a>SEE ALSO
catch(n), error(n), return(n), [throw(n)](tcllib_throw.md)
# <a name='keywords'></a>KEYWORDS
[cleanup](../../../../index.md#cleanup), [error](../../../../index.md#error),
[exception](../../../../index.md#exception),
[final](../../../../index.md#final), [resource
management](../../../../index.md#resource_management)
# <a name='category'></a>CATEGORY
Utility
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Donal K. Fellows, BSD licensed
|
Added embedded/md/tcllib/files/modules/udpcluster/udpcluster.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
[//000000001]: # (udpcluster - Lightweight UDP based tool for cluster node discovery)
[//000000002]: # (Generated from file 'udpcluster.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (udpcluster(n) 0.3.3 tcllib "Lightweight UDP based tool for cluster node discovery")
# NAME
udpcluster - UDP Peer-to-Peer cluster
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Bugs, Ideas, Feedback](#section2)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require udpcluster ?0.3.3?
package require ip
package require nettool
package require comm
package require interp
package require dicttool
package require cron
# <a name='description'></a>DESCRIPTION
This package is a lightweight alternative to Zeroconf. It utilizes UDP packets
to populate a table of services provided by each node on a local network. Each
participant broadcasts a key/value list in plain UTF-8 which lists what ports
are open, and what protocols are expected on those ports. Developers are free to
add any additional key/value pairs beyond those.
Using udpcluster.
For every service you wish to publish invoke:
cluster::publish echo@[cluster::macid] {port 10000 protocol echo}
To query what services are available on the local network:
set results [cluster::search PATTERN]
# And inside that result...
echo@LOCALMACID {
port 10000
protocol echo
}
To unpublish a service:
cluster::unpublish echo@[cluster::macid]
Results will Historical Notes:
This tool was originally known as nns::cluster, but as development progressed,
it was clear that it wasn't interacting with any of the other facilities in NNS.
# <a name='section2'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *nameserv* 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.
# <a name='keywords'></a>KEYWORDS
[name service](../../../../index.md#name_service),
[server](../../../../index.md#server)
# <a name='category'></a>CATEGORY
Networking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2016-2018 Sean Woods <[email protected]>
|
Added embedded/md/tcllib/files/modules/uev/uevent.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
[//000000001]: # (uevent - User events)
[//000000002]: # (Generated from file 'uevent.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (uevent(n) 0.3.1 tcllib "User events")
# NAME
uevent - User events
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require uevent ?0.3.1?
package require logger
[__::uevent::bind__ *tag* *event* *command*](#1)
[__[command](../../../../index.md#command)__ *tag* *event* *details*](#2)
[__::uevent::unbind__ *token*](#3)
[__::uevent::generate__ *tag* *event* ?*details*?](#4)
[__::uevent::list__](#5)
[__::uevent::list__ *tag*](#6)
[__::uevent::list__ *tag* *event*](#7)
[__::uevent::watch::tag::add__ *pattern* *command*](#8)
[__{*}command__ __bound__ *tag*](#9)
[__{*}command__ __unbound__ *tag*](#10)
[__::uevent::watch::tag::remove__ *token*](#11)
[__::uevent::watch::event::add__ *tag_pattern* *event_pattern* *command*](#12)
[__{*}command__ __bound__ *tag* *event*](#13)
[__{*}command__ __unbound__ *tag* *event*](#14)
[__::uevent::watch::event::remove__ *token*](#15)
# <a name='description'></a>DESCRIPTION
This package provides a general facility for the handling of user events. Allows
the binding of arbitrary commands to arbitrary events on arbitrary tags, removal
of bindings, and event generation.
The main difference to the event system built into the Tcl/Tk core is that the
latter can generate only virtual events, and only for widgets. It is not
possible to use the builtin facilities to bind to events on arbitrary
(pseudo-)objects, nor is it able to generate events for such.
Here we can, by assuming that each object in question is represented by its own
tag. Which is possible as we allow arbitrary tags.
More differences:
1. The package uses only a two-level hierarchy, tags and events, to handle
everything, whereas the Tcl/Tk system uses three levels, i.e. objects,
tags, and events, with a n:m relationship between objects and tags.
1. This package triggers all bound commands for a tag/event combination, and
they are independent of each other. A bound command cannot force the event
processing core to abort the processing of command coming after it.
# <a name='section2'></a>API
The package exports eight commands, as specified below. Note that when the
package is used from within Tcl 8.5+ all the higher commands are ensembles, i.e.
the :: separators can be replaceed by spaces.
- <a name='1'></a>__::uevent::bind__ *tag* *event* *command*
Using this command registers the *command* prefix to be triggered when the
*event* occurs for the *tag*. The result of the command is an opaque token
representing the binding. Note that if the same combination of
<*tag*,*event*,*command*> is used multiple times the same token is returned
by every call.
The signature of the *command* prefix is
* <a name='2'></a>__[command](../../../../index.md#command)__ *tag* *event* *details*
where *details* contains the argument(s) of the event. Its contents are
event specific and have to be agreed upon between actual event generator and
consumer. This package simply transfers the information and does not perform
any processing beyond that.
- <a name='3'></a>__::uevent::unbind__ *token*
This command releases the event binding represented by the *token*. The
token has to be the result of a call to __::uevent::bind__. The result of
the command is the empty string.
- <a name='4'></a>__::uevent::generate__ *tag* *event* ?*details*?
This command generates an *event* for the *tag*, triggering all commands
bound to that combination. The *details* argument is simply passed unchanged
to all event handlers. It is the responsibility of the code generating and
consuming the event to have an agreement about the format and contents of
the information carried therein. The result of the command is the empty
string.
Note that all bound commands are triggered, independently of each other. The
event handlers cannot assume a specific order. They are also *not* called
synchronously with the invokation of this command, but simply put into the
event queue for processing when the system returns to the event loop.
Generating an event for an unknown tag, or for a <*tag*,*event*> combination
which has no commands bound to it is allowed, such calls will be ignored.
- <a name='5'></a>__::uevent::list__
In this form the command returns a list containing the names of all tags
which have events with commands bound to them.
- <a name='6'></a>__::uevent::list__ *tag*
In this format the command returns a list containing the names of all events
for the *tag* with commands bound to them. Specifying an unknown tag, i.e. a
tag without event and commands, will cause the command to throw an error.
- <a name='7'></a>__::uevent::list__ *tag* *event*
In this format the command returns a list containing all commands bound to
the *event* for the *tag*. Specifying an unknown tag or unknown event, will
cause the command to throw an error.
- <a name='8'></a>__::uevent::watch::tag::add__ *pattern* *command*
This command sets up a sort of reverse events. Events generated, i.e. the
*command* prefix invoked, when observers bind to and unbind from specific
tags.
Note that the command prefix is only invoked twice per tag, first when the
first command is bound to any event of the tag, and second when the last
command bound to the tag is removed.
The signature of the *command* prefix is
* <a name='9'></a>__{*}command__ __bound__ *tag*
* <a name='10'></a>__{*}command__ __unbound__ *tag*
The result of the command is a token representing the watcher.
- <a name='11'></a>__::uevent::watch::tag::remove__ *token*
This command removes a watcher for (un)bind events on tags.
The result of the command is the empty string.
- <a name='12'></a>__::uevent::watch::event::add__ *tag_pattern* *event_pattern* *command*
This command sets up a sort of reverse events. Events generated, i.e. the
*command* prefix invoked, when observers bind to and unbind from specific
combinations of tags and events.
Note that the command prefix is only invoked twice per tag/event
combination, first when the first command is bound to it, and second when
the last command bound to the it is removed.
The signature of the *command* prefix is
* <a name='13'></a>__{*}command__ __bound__ *tag* *event*
* <a name='14'></a>__{*}command__ __unbound__ *tag* *event*
The result of the command is a token representing the watcher.
- <a name='15'></a>__::uevent::watch::event::remove__ *token*
This command removes a watcher for (un)bind events on tag/event
combinations.
The result of the command is the empty string.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *uevent* 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.
# <a name='see-also'></a>SEE ALSO
[hook(n)](../hook/hook.md)
# <a name='keywords'></a>KEYWORDS
[bind](../../../../index.md#bind), [event](../../../../index.md#event),
[generate event](../../../../index.md#generate_event),
[hook](../../../../index.md#hook), [unbind](../../../../index.md#unbind)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2012 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/uev/uevent_onidle.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
[//000000001]: # (uevent::onidle - User events)
[//000000002]: # (Generated from file 'uevent_onidle.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (uevent::onidle(n) 0.1 tcllib "User events")
# NAME
uevent::onidle - Request merging and deferal to idle time
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Examples](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require uevent::onidle ?0.1?
package require logger
[__::uevent::onidle__ *objectName* *commandprefix*](#1)
[*objectName* __request__](#2)
# <a name='description'></a>DESCRIPTION
This package provides objects which can merge multiple requestes for an action
and execute the action the moment the system (event loop) becomes idle. The
action to be run is configured during object construction.
# <a name='section2'></a>API
The package exports a class, __uevent::onidle__, as specified below.
- <a name='1'></a>__::uevent::onidle__ *objectName* *commandprefix*
The command creates a new *onidle* object with an associated global Tcl
command whose name is *objectName*. This command may be used to invoke
various operations on the object.
The *commandprefix* is the action to perform when the event loop is idle and
the user asked for it using the method __request__ (See below).
The object commands created by the class commands above have the form:
- <a name='2'></a>*objectName* __request__
This method requests the execution of the command prefix specified during
the construction of *objectName* the next time the event loop is idle.
Multiple requests are merged and cause only one execution of the command
prefix.
# <a name='section3'></a>Examples
Examples of this type of deferal are buried in the (C-level) implementations all
the Tk widgets, defering geometry calculations and window redraw activity in
this manner.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *uevent* 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.
# <a name='keywords'></a>KEYWORDS
[callback](../../../../index.md#callback),
[deferal](../../../../index.md#deferal), [event](../../../../index.md#event),
[idle](../../../../index.md#idle), [merge](../../../../index.md#merge),
[on-idle](../../../../index.md#on_idle)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/units/units.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
|
[//000000001]: # (units - Convert and manipulate quantities with units)
[//000000002]: # (Generated from file 'units.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (units(n) 1.2 tcllib "Convert and manipulate quantities with units")
# NAME
units - unit conversion
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [UNIT STRING FORMAT](#section3)
- [Example Valid Unit Strings](#subsection1)
- [SI UNITS](#section4)
- [SI Base Units](#subsection2)
- [SI Derived Units with Special Names](#subsection3)
- [SI Prefixes](#subsection4)
- [Non-SI Units](#subsection5)
- [Quantities and Derived Units with Special Names](#subsection6)
- [REFERENCES](#section5)
- [AUTHORS](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.1
package require units ?2.1?
[__::units::convert__ *value* *targetUnits*](#1)
[__::units::reduce__ *unitString*](#2)
[__::units::new__ *name* *baseUnits*](#3)
# <a name='description'></a>DESCRIPTION
This library provides a conversion facility from a variety of scientific and
engineering shorthand notations into floating point numbers. This allows
application developers to easily convert values with different units into
uniformly scaled numbers.
The units conversion facility is also able to convert between compatible units.
If, for example, a application is expecting a value in *ohms* (Resistance), and
the user specifies units of *milliwebers/femtocoulomb*, the conversion routine
will handle it appropriately. An error will be generated if an incorrect
conversion is attempted.
Values are scaled from one set of units to another by dimensional analysis. Both
the value units and the target units are reduced into primitive units and a
scale factor. Units are checked for compatibility, and the scale factors are
applied by multiplication and division. This technique is extremely flexible and
quite robust.
New units and new unit abbreviations can be defined in terms of existing units
and abbreviations. It is also possible to define a new primitive unit, although
that will probably be unnecessary. New units will most commonly be defined to
accommodate non-SI measurement systems, such as defining the unit *inch* as
*2.54 cm*.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::units::convert__ *value* *targetUnits*
Converts the *value* string into a floating point number, scaled to the
specified *targetUnits*. The *value* string may contain a number and units.
If units are specified, then they must be compatible with the *targetUnits*.
If units are not specified for the *value*, then it will be scaled to the
target units. For example,
% ::units::convert "2.3 miles" km
3.7014912
% ::units::convert 300m/s miles/hour
671.080887616
% ::units::convert "1.0 m kg/s^2" newton
1.0
% ::units::convert 1.0 millimeter
1000.0
- <a name='2'></a>__::units::reduce__ *unitString*
Returns a unit string consisting of a scale factor followed by a space
separated list of sorted and reduced primitive units. The reduced unit
string may include a forward-slash (separated from the surrounding primitive
subunits by spaces) indicating that the remaining subunits are in the
denominator. Generates an error if the *unitString* is invalid.
% ::units::reduce pascal
1000.0 gram / meter second second
- <a name='3'></a>__::units::new__ *name* *baseUnits*
Creates a new unit conversion with the specified name. The new unit *name*
must be only alphabetic (upper or lower case) letters. The *baseUnits*
string can consist of any valid units conversion string, including constant
factors, numerator and denominator parts, units with prefixes, and
exponents. The baseUnits may contain any number of subunits, but it must
reduce to primitive units. BaseUnits could also be the string *-primitive*
to represent a new kind of quantity which cannot be derived from other
units. But you probably would not do that unless you have discovered some
kind of new universal property.
% ::units::new furlong "220 yards"
% ::units::new fortnight "14 days"
% ::units::convert 100m/s furlongs/fortnight
601288.475303
# <a name='section3'></a>UNIT STRING FORMAT
Value and unit string format is quite flexible. It is possible to define
virtually any combination of units, prefixes, and powers. Valid unit strings
must conform to these rules.
- A unit string consists of an optional scale factor followed by zero or more
subunits. The scale factor must be a valid floating point number, and may or
may not be separated from the subunits. The scale factor could be negative.
- Subunits are separated form each other by one or more separator characters,
which are space (" "), hyphen ("-"), asterisk ("*"), and forward-slash
("/"). Sure, go ahead and complain about using a minus sign ("-") to
represent multiplication. It just isn't sound mathematics, and, by rights,
we should require everyone to use the asterisk ("*") to separate all units.
But the bottom line is that complex unit strings like *m-kg/s^2* are
pleasantly readable.
- The forward-slash seperator ("/") indicates that following subunits are in
the denominator. There can be at most one forward-slash separator.
- Subunits can be floating point scale factors, but with the exception of the
leading scale factor, they must be surrounded by valid separators. Subunit
scale factors cannot be negative. (Remember that the hyphen is a unit
separator.)
- Subunits can be valid units or abbreviations. They may include a prefix.
They may include a plural suffix "s" or "es". They may also include a power
string denoted by a circumflex ("^"), followed by a integer, after the unit
name (or plural suffix, if there is one). Negative exponents are not
allowed. (Remember that the hyphen is a unit separator.)
## <a name='subsection1'></a>Example Valid Unit Strings
Unit String Reduced Unit String
------------------------------------------------------------
meter 1.0 meter
kilometer 1000.0 meter
km 1000.0 meter
km/s 1000.0 meter / second
/microsecond 1000000.0 / second
/us 1000000.0 / second
kg-m/s^2 1000.0 gram meter / second second
30second 30.0 second
30 second 30.0 second
30 seconds 30.0 second
200*meter/20.5*second 9.75609756098 meter / second
# <a name='section4'></a>SI UNITS
The standard SI units are predefined according to *NIST Special Publication
330*. Standard units for both SI Base Units (Table 1) and SI Derived Units with
Special Names (Tables 3a and 3b) are included here for reference. Each standard
unit name and abbreviation are included in this package.
## <a name='subsection2'></a>SI Base Units
Quantity Unit Name Abbr.
---------------------------------------------
Length meter m
Mass kilogram kg
Time second s
Current ampere A
Temperature kelvin K
Amount mole mol
Luminous Intensity candela cd
## <a name='subsection3'></a>SI Derived Units with Special Names
Quantity Unit Name Abbr. Units Base Units
--------------------------------------------------------------------
plane angle radian rad m/m m/m
solid angle steradian sr m^2/m^2 m^2/m^2
frequency hertz Hz /s
force newton N m-kg/s^2
pressure pascal Pa N/m^2 kg/m-s^2
energy, work joule J N-m m^2-kg/s^2
power, radiant flux watt W J/s m^2-kg/s^3
electric charge coulomb C s-A
electric potential volt V W/A m^2-kg/s^3-A
capacitance farad F C/V s^4-A^2/m^2-kg
electric resistance ohm V/A m^2-kg/s^3-A^2
electric conductance siemens S A/V s^3-A^2/m^2-kg
magnetic flux weber Wb V-s m^2-kg/s^2-A
magnetic flux density tesla T Wb/m^2 kg/s^2-A
inductance henry H Wb/A m^2-kg/s^2-A^2
luminous flux lumen lm cd-sr
illuminance lux lx lm/m^2 cd-sr/m^2
activity (of a
radionuclide) becquerel Bq /s
absorbed dose gray Gy J/kg m^2/s^2
dose equivalent sievert Sv J/kg m^2/s^2
Note that the SI unit kilograms is actually implemented as grams because 1e-6
kilogram = 1 milligram, not 1 microkilogram. The abbreviation for Electric
Resistance (ohms), which is the omega character, is not supported.
Also note that there is no support for Celsius or Farenheit temperature. The
units conversion routines can only scale values with multiplication and
division, so it is not possible to convert from thermodynamic temperature
(kelvins) to absolute degrees Celsius or Farenheit. Conversion of thermodynamic
quantities, such as thermal expansion (per unit temperature), however, are easy
to add to the units library.
SI Units can have a multiple or sub-multiple prefix. The prefix or its
abbreviation should appear before the unit, without spaces. Compound prefixes
are not allowed, and a prefix should never be used alone. These prefixes are
defined in Table 5 of *Special Publication 330*.
## <a name='subsection4'></a>SI Prefixes
Prefix Name Abbr. Factor
---------------------------------------
yotta Y 1e24
zetta Z 1e21
exa E 1e18
peta P 1e15
tera T 1e12
giga G 1e9
mega M 1e6
kilo k 1e3
hecto h 1e2
deka da 1e1
deca 1e1
deci d 1e-1
centi c 1e-2
milli m 1e-3
micro u 1e-6
nano n 1e-9
pico p 1e-12
femto f 1e-15
atto a 1e-18
zepto z 1e-21
yocto y 1e-24
Note that we define the same prefix with both the USA ("deka") and non-USA
("deca") spellings. Also note that we take the liberty of allowing "micro" to be
typed as a "u" instead of the Greek character mu.
Many non-SI units are commonly used in applications. Appendix B.8 of *NIST
Special Publication 811* lists many non-SI conversion factors. It is not
possible to include all possible unit definitions in this package. In some
cases, many different conversion factors exist for a given unit, depending on
the context. (The appendix lists over 40 conversions for British thermal units!)
Application specific conversions can always be added using the __new__ command,
but some well known and often used conversions are included in this package.
## <a name='subsection5'></a>Non-SI Units
Unit Name Abbr. Base Units
--------------------------------------------------
angstrom 1.0E-10 m
astronomicalUnit AU 1.495979E11 m
atmosphere 1.01325E5 Pa
bar 1.0E5 Pa
calorie 4.1868 J
curie 3.7E10 Bq
day 8.64E4 s
degree 1.745329E-2 rad
erg 1.0E-7 J
faraday 9.648531 C
fermi 1.0E-15 m
foot ft 3.048E-1 m
gauss 1.0E-4 T
gilbert 7.957747E-1 A
grain gr 6.479891E-5 kg
hectare ha 1.0E4 m^2
hour h 3.6E3 s
inch in 2.54E-2 m
lightYear 9.46073E15 m
liter L 1.0E-3 m^3
maxwell Mx 1.0E-8 Wb
mho 1.0 S
micron 1.0E-6 m
mil 2.54E-5 m
mile mi 1.609344E3 m
minute min 6.0E1 s
parsec pc 3.085E16 m
pica 4.233333E-3 m
pound lb 4.535924E-1 kg
revolution 6.283185 rad
revolutionPerMinute rpm 1.047198E-1 rad/s
yard yd 9.144E-1 m
year 3.1536E7 s
## <a name='subsection6'></a>Quantities and Derived Units with Special Names
This units conversion package is limited specifically to unit reduction,
comparison, and scaling. This package does not consider any of the quantity
names for either base or derived units. A similar implementation or an extension
in a typed or object-oriented language might introduce user defined types for
the quantities. Quantity type checking could be used, for example, to ensure
that all *length* values properly reduced to *meters*, or that all *velocity*
values properly reduced to *meters/second*.
A C implementation of this package has been created to work in conjunction with
the Simplified Wrapper Interface Generator
([http://www.swig.org/](http://www.swig.org/)). That package (units.i) exploits
SWIG's typemap system to automatically convert script quantity strings into
floating point quantities. Function arguments are specified as quantity types
(e.g., *typedef float Length*), and target units (expected by the C application
code) are specified in an associative array. Default units are also defined for
each quantity type, and are applied to any unit-less quantity strings.
A units system enhanced with quantity type checking might benefit from inclusion
of other derived types which are expressed in terms of special units, as
illustrated in Table 2 of *NIST Publication 330*. The quantity *area*, for
example, could be defined as units properly reducing to *meter^2*, although the
utility of defining a unit named *square meter* is arguable.
# <a name='section5'></a>REFERENCES
The unit names, abbreviations, and conversion values are derived from those
published by the United States Department of Commerce Technology Administration,
National Institute of Standards and Technology (NIST) in *NIST Special
Publication 330: The International System of Units (SI)* and *NIST Special
Publication 811: Guide for the Use of the International System of Units (SI)*.
Both of these publications are available (as of December 2000) from
[http://physics.nist.gov/cuu/Reference/contents.html](http://physics.nist.gov/cuu/Reference/contents.html)
The ideas behind implementation of this package is based in part on code written
in 1993 by Adrian Mariano which performed dimensional analysis of unit strings
using fixed size tables of C structs. After going missing in the late 1990's,
Adrian's code has reappeared in the GNU Units program at
[http://www.gnu.org/software/units/](http://www.gnu.org/software/units/)
# <a name='section6'></a>AUTHORS
Robert W. Techentin
# <a name='section7'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *units* 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.
# <a name='keywords'></a>KEYWORDS
[angle](../../../../index.md#angle),
[constants](../../../../index.md#constants),
[conversion](../../../../index.md#conversion),
[distance](../../../../index.md#distance),
[radians](../../../../index.md#radians), [unit](../../../../index.md#unit)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2000-2005 Mayo Foundation
|
Added embedded/md/tcllib/files/modules/uri/uri.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
|
[//000000001]: # (uri - Tcl Uniform Resource Identifier Management)
[//000000002]: # (Generated from file 'uri.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (uri(n) 1.2.7 tcllib "Tcl Uniform Resource Identifier Management")
# NAME
uri - URI utilities
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [SCHEMES](#section3)
- [EXTENDING](#section4)
- [QUIRK OPTIONS](#section5)
- [BACKWARD COMPATIBILITY](#subsection1)
- [NEW DESIGNS](#subsection2)
- [DEFAULT VALUES](#subsection3)
- [EXAMPLES](#section6)
- [CREDITS](#section7)
- [Bugs, Ideas, Feedback](#section8)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require uri ?1.2.7?
[__uri::setQuirkOption__ *option* ?*value*?](#1)
[__uri::split__ *url* ?*defaultscheme*?](#2)
[__uri::join__ ?*key* *value*?...](#3)
[__uri::resolve__ *base* *url*](#4)
[__uri::isrelative__ *url*](#5)
[__uri::geturl__ *url* ?*options*...?](#6)
[__uri::canonicalize__ *uri*](#7)
[__uri::register__ *schemeList* *script*](#8)
# <a name='description'></a>DESCRIPTION
This package does two things.
First, it provides a number of commands for manipulating URLs/URIs and fetching
data specified by them. For fetching data this package analyses the requested
URL/URI and then dispatches it to the appropriate package
(__[http](../../../../index.md#http)__, __[ftp](../ftp/ftp.md)__, ...) for
actual retrieval. Currently these commands are defined for the schemes
*[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*,
*[ftp](../../../../index.md#ftp)*, *[mailto](../../../../index.md#mailto)*,
*[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*,
*ldaps* and *[file](../../../../index.md#file)*. The package __uri::urn__ adds
scheme *[urn](../../../../index.md#urn)*.
Second, it provides regular expressions for a number of __registered__ URL/URI
schemes. Registered schemes are currently *[ftp](../../../../index.md#ftp)*,
*[ldap](../../../../index.md#ldap)*, *ldaps*,
*[file](../../../../index.md#file)*, *[http](../../../../index.md#http)*,
*[https](../../../../index.md#https)*, *[gopher](../../../../index.md#gopher)*,
*[mailto](../../../../index.md#mailto)*, *[news](../../../../index.md#news)*,
*[wais](../../../../index.md#wais)* and
*[prospero](../../../../index.md#prospero)*. The package __uri::urn__ adds
scheme *[urn](../../../../index.md#urn)*.
The commands of the package conform to RFC 3986
([https://www.rfc-editor.org/rfc/rfc3986.txt](https://www.rfc-editor.org/rfc/rfc3986.txt)),
with the exception of a loophole arising from RFC 1630 and described in RFC 3986
Sections 5.2.2 and 5.4.2. The loophole allows a relative URI to include a scheme
if it is the same as the scheme of the base URI against which it is resolved.
RFC 3986 recommends avoiding this usage.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__uri::setQuirkOption__ *option* ?*value*?
__uri::setQuirkOption__ is an accessor command for a number of "quirk
options". The command has the same semantics as the command
__[set](../../../../index.md#set)__: when called with one argument it reads
an existing value; with two arguments it writes a new value. The value of a
"quirk option" is boolean: the value __false__ requests conformance with RFC
3986, while __true__ requests use of the quirk. See section [QUIRK
OPTIONS](#section5) for discussion of the different options and their
purpose.
- <a name='2'></a>__uri::split__ *url* ?*defaultscheme*?
__uri::split__ takes a *url*, decodes it and then returns a list of
key/value pairs suitable for __array set__ containing the constituents of
the *url*. If the scheme is missing from the *url* it defaults to the value
of *defaultscheme* if it was specified, or
*[http](../../../../index.md#http)* else. Currently the schemes
*[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*,
*[ftp](../../../../index.md#ftp)*, *[mailto](../../../../index.md#mailto)*,
*[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*,
*ldaps* and *[file](../../../../index.md#file)* are supported by the package
itself. See section [EXTENDING](#section4) on how to expand that range.
The set of constituents of a URL (= the set of keys in the returned
dictionary) is dependent on the scheme of the URL. The only key which is
therefore always present is __scheme__. For the following schemes the
constituents and their keys are known:
* ftp
__user__, __pwd__, __host__, __port__, __path__, __type__, __pbare__.
The pbare is optional.
* http(s)
__user__, __pwd__, __host__, __port__, __path__, __query__,
__fragment__, __pbare__. The pbare is optional.
* file
__path__, __host__. The host is optional.
* mailto
__user__, __host__. The host is optional.
* ldap(s)
__host__, __port__, __dn__, __attrs__, __scope__, __filter__,
__extensions__
* news
Either __message-id__ or __newsgroup-name__.
For discussion of the boolean __pbare__ see options *NoInitialSlash* and
*NoExtraKeys* in [QUIRK OPTIONS](#section5).
The constituents are returned as slices of the argument *url*, without
removal of percent-encoding ("url-encoding") or other adaptations. Notably,
on Windows® the __path__ in scheme *[file](../../../../index.md#file)* is
not a valid local filename. See [EXAMPLES](#section6) for more information.
- <a name='3'></a>__uri::join__ ?*key* *value*?...
__uri::join__ takes a list of key/value pairs (generated by __uri::split__,
for example) and returns the canonical URL they represent. Currently the
schemes *[http](../../../../index.md#http)*,
*[https](../../../../index.md#https)*, *[ftp](../../../../index.md#ftp)*,
*[mailto](../../../../index.md#mailto)*,
*[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*,
*ldaps* and *[file](../../../../index.md#file)* are supported by the package
itself. See section [EXTENDING](#section4) on how to expand that range.
The arguments are expected to be slices of a valid URL, with
percent-encoding ("url-encoding") and any other necessary adaptations.
Notably, on Windows the __path__ in scheme
*[file](../../../../index.md#file)* is not a valid local filename. See
[EXAMPLES](#section6) for more information.
- <a name='4'></a>__uri::resolve__ *base* *url*
__uri::resolve__ resolves the specified *url* relative to *base*, in
conformance with RFC 3986. In other words: a non-relative *url* is returned
unchanged, whereas for a relative *url* the missing parts are taken from
*base* and prepended to it. The result of this operation is returned. For an
empty *url* the result is *base*, without its URI fragment (if any). The
command is available for schemes *[http](../../../../index.md#http)*,
*[https](../../../../index.md#https)*, *[ftp](../../../../index.md#ftp)*,
and *[file](../../../../index.md#file)*.
- <a name='5'></a>__uri::isrelative__ *url*
__uri::isrelative__ determines whether the specified *url* is absolute or
relative. The command is available for a *url* of any scheme.
- <a name='6'></a>__uri::geturl__ *url* ?*options*...?
__uri::geturl__ decodes the specified *url* and then dispatches the request
to the package appropriate for the scheme found in the URL. The command
assumes that the package to handle the given scheme either has the same name
as the scheme itself (including possible capitalization) followed by
__::geturl__, or, in case of this failing, has the same name as the scheme
itself (including possible capitalization). It further assumes that whatever
package was loaded provides a __geturl__-command in the namespace of the
same name as the package itself. This command is called with the given *url*
and all given *options*. Currently __geturl__ does not handle any options
itself.
*Note:* *[file](../../../../index.md#file)*-URLs are an exception to the
rule described above. They are handled internally.
It is not possible to specify results of the command. They depend on the
__geturl__-command for the scheme the request was dispatched to.
- <a name='7'></a>__uri::canonicalize__ *uri*
__uri::canonicalize__ returns the canonical form of a URI. The canonical
form of a URI is one where relative path specifications, i.e. "." and "..",
have been resolved. The command is available for all URI schemes that have
__uri::split__ and __uri::join__ commands. The command returns a
canonicalized URI if the URI scheme has a __path__ component (i.e.
*[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*,
*[ftp](../../../../index.md#ftp)*, and *[file](../../../../index.md#file)*).
For schemes that have __uri::split__ and __uri::join__ commands but no
__path__ component (i.e. *[mailto](../../../../index.md#mailto)*,
*[news](../../../../index.md#news)*, *[ldap](../../../../index.md#ldap)*,
and *ldaps*), the command returns the *uri* unchanged.
- <a name='8'></a>__uri::register__ *schemeList* *script*
__uri::register__ registers the first element of *schemeList* as a new
scheme and the remaining elements as aliases for this scheme. It creates the
namespace for the scheme and executes the *script* in the new namespace. The
script has to declare variables containing regular expressions relevant to
the scheme. At least the variable __schemepart__ has to be declared as that
one is used to extend the variables keeping track of the registered schemes.
# <a name='section3'></a>SCHEMES
In addition to the commands mentioned above this package provides regular
expression to recognize URLs for a number of URL schemes.
For each supported scheme a namespace of the same name as the scheme itself is
provided inside of the namespace *uri* containing the variable __url__ whose
contents are a regular expression to recognize URLs of that scheme. Additional
variables may contain regular expressions for parts of URLs for that scheme.
The variable __uri::schemes__ contains a list of all registered schemes.
Currently these are *[ftp](../../../../index.md#ftp)*,
*[ldap](../../../../index.md#ldap)*, *ldaps*,
*[file](../../../../index.md#file)*, *[http](../../../../index.md#http)*,
*[https](../../../../index.md#https)*, *[gopher](../../../../index.md#gopher)*,
*[mailto](../../../../index.md#mailto)*, *[news](../../../../index.md#news)*,
*[wais](../../../../index.md#wais)* and
*[prospero](../../../../index.md#prospero)*.
# <a name='section4'></a>EXTENDING
Extending the range of schemes supported by __uri::split__ and __uri::join__ is
easy because both commands do not handle the request by themselves but dispatch
it to another command in the *uri* namespace using the scheme of the URL as
criterion.
__uri::split__ and __uri::join__ call __Split[string totitle <scheme>]__ and
__Join[string totitle <scheme>]__ respectively.
The provision of split and join commands is sufficient to extend the commands
__uri::canonicalize__ and __uri::geturl__ (the latter subject to the
availability of a suitable package with a __geturl__ command). In contrast, to
extend the command __uri::resolve__ to a new scheme, the command itself must be
modified.
To extend the range of schemes for which pattern information is available, use
the command __uri::register__.
An example of a package that provides both commands and pattern information for
a new scheme is __uri::urn__, which adds scheme
*[urn](../../../../index.md#urn)*.
# <a name='section5'></a>QUIRK OPTIONS
The value of a "quirk option" is boolean: the value __false__ requests
conformance with RFC 3986, while __true__ requests use of the quirk. Use command
__uri::setQuirkOption__ to access the values of quirk options.
Quirk options are useful both for allowing backwards compatibility when a
command specification changes, and for adding useful features that are not
included in RFC specifications. The following quirk options are currently
defined:
- *NoInitialSlash*
This quirk option concerns the leading character of __path__ (if non-empty)
in the schemes *[http](../../../../index.md#http)*,
*[https](../../../../index.md#https)*, and
*[ftp](../../../../index.md#ftp)*.
RFC 3986 defines __path__ in an absolute URI to have an initial "/", unless
the value of __path__ is the empty string. For the scheme
*[file](../../../../index.md#file)*, all versions of package __uri__ follow
this rule. The quirk option *NoInitialSlash* does not apply to scheme
*[file](../../../../index.md#file)*.
For the schemes *[http](../../../../index.md#http)*,
*[https](../../../../index.md#https)*, and
*[ftp](../../../../index.md#ftp)*, versions of __uri__ before 1.2.7 define
the __path__ *NOT* to include an initial "/". When the quirk option
*NoInitialSlash* is __true__ (the default), this behavior is also used in
version 1.2.7. To use instead values of __path__ as defined by RFC 3986, set
this quirk option to __false__.
This setting does not affect RFC 3986 conformance. If *NoInitialSlash* is
__true__, then the value of __path__ in the schemes
*[http](../../../../index.md#http)*, *[https](../../../../index.md#https)*,
or *[ftp](../../../../index.md#ftp)*, cannot distinguish between URIs in
which the full "RFC 3986 path" is the empty string "" or a single slash "/"
respectively. The missing information is recorded in an additional
__uri::split__ key __pbare__.
The boolean __pbare__ is defined when quirk options *NoInitialSlash* and
*NoExtraKeys* have values __true__ and __false__ respectively. In this case,
if the value of __path__ is the empty string "", __pbare__ is __true__ if
the full "RFC 3986 path" is "", and __pbare__ is __false__ if the full "RFC
3986 path" is "/".
Using this quirk option *NoInitialSlash* is a matter of preference.
- *NoExtraKeys*
This quirk option permits full backward compatibility with versions of
__uri__ before 1.2.7, by omitting the __uri::split__ key __pbare__ described
above (see quirk option *NoInitialSlash*). The outcome is greater backward
compatibility of the __uri::split__ command, but an inability to distinguish
between URIs in which the full "RFC 3986 path" is the empty string "" or a
single slash "/" respectively - i.e. a minor non-conformance with RFC 3986.
If the quirk option *NoExtraKeys* is __false__ (the default), command
__uri::split__ returns an additional key __pbare__, and the commands comply
with RFC 3986. If the quirk option *NoExtraKeys* is __true__, the key
__pbare__ is not defined and there is not full conformance with RFC 3986.
Using the quirk option *NoExtraKeys* is *NOT* recommended, because if set to
__true__ it will reduce conformance with RFC 3986. The option is included
only for compatibility with code, written for earlier versions of __uri__,
that needs values of __path__ without a leading "/", *AND ALSO* cannot
tolerate unexpected keys in the results of __uri::split__.
- *HostAsDriveLetter*
When handling the scheme *[file](../../../../index.md#file)* on the Windows
platform, versions of __uri__ before 1.2.7 use the __host__ field to
represent a Windows drive letter and the colon that follows it, and the
__path__ field to represent the filename path after the colon. Such URIs are
invalid, and are not recognized by any RFC. When the quirk option
*HostAsDriveLetter* is __true__, this behavior is also used in version
1.2.7. To use *[file](../../../../index.md#file)* URIs on Windows that
conform to RFC 3986, set this quirk option to __false__ (the default).
Using this quirk is *NOT* recommended, because if set to __true__ it will
cause the __uri__ commands to expect and produce invalid URIs. The option is
included only for compatibility with legacy code.
- *RemoveDoubleSlashes*
When a URI is canonicalized by __uri::canonicalize__, its __path__ is
normalized by removal of segments "." and "..". RFC 3986 does not mandate
the removal of empty segments "" (i.e. the merger of double slashes, which
is a feature of filename normalization but not of URI __path__
normalization): it treats URIs with excess slashes as referring to different
resources. When the quirk option *RemoveDoubleSlashes* is __true__ (the
default), empty segments will be removed from __path__. To prevent removal,
and thereby conform to RFC 3986, set this quirk option to __false__.
Using this quirk is a matter of preference. A URI with double slashes in its
path was most likely generated by error, certainly so if it has a
straightforward mapping to a file on a server. In some cases it may be
better to sanitize the URI; in others, to keep the URI and let the server
handle the possible error.
## <a name='subsection1'></a>BACKWARD COMPATIBILITY
To behave as similarly as possible to versions of __uri__ earlier than 1.2.7,
set the following quirk options:
- __uri::setQuirkOption__ *NoInitialSlash* 1
- __uri::setQuirkOption__ *NoExtraKeys* 1
- __uri::setQuirkOption__ *HostAsDriveLetter* 1
- __uri::setQuirkOption__ *RemoveDoubleSlashes* 0
In code that can tolerate the return by __uri::split__ of an additional key
__pbare__, set
- __uri::setQuirkOption__ *NoExtraKeys* 0
in order to achieve greater compliance with RFC 3986.
## <a name='subsection2'></a>NEW DESIGNS
For new projects, the following settings are recommended:
- __uri::setQuirkOption__ *NoInitialSlash* 0
- __uri::setQuirkOption__ *NoExtraKeys* 0
- __uri::setQuirkOption__ *HostAsDriveLetter* 0
- __uri::setQuirkOption__ *RemoveDoubleSlashes* 0|1
## <a name='subsection3'></a>DEFAULT VALUES
The default values for package __uri__ version 1.2.7 are intended to be a
compromise between backwards compatibility and improved features. Different
default values may be chosen in future versions of package __uri__.
- __uri::setQuirkOption__ *NoInitialSlash* 1
- __uri::setQuirkOption__ *NoExtraKeys* 0
- __uri::setQuirkOption__ *HostAsDriveLetter* 0
- __uri::setQuirkOption__ *RemoveDoubleSlashes* 1
# <a name='section6'></a>EXAMPLES
A Windows® local filename such as "__C:\Other Files\startup.txt__" is not
suitable for use as the __path__ element of a URI in the scheme
*[file](../../../../index.md#file)*.
The Tcl command __file normalize__ will convert the backslashes to forward
slashes. To generate a valid __path__ for the scheme
*[file](../../../../index.md#file)*, the normalized filename must be prepended
with "__/__", and then any characters that do not match the __regexp__ bracket
expression
[a-zA-Z0-9$_.+!*'(,)?:@&=-]
must be percent-encoded.
The result in this example is "__/C:/Other%20Files/startup.txt__" which is a
valid value for __path__.
% uri::join path /C:/Other%20Files/startup.txt scheme file
file:///C:/Other%20Files/startup.txt
% uri::split file:///C:/Other%20Files/startup.txt
path /C:/Other%20Files/startup.txt scheme file
On UNIX® systems filenames begin with "__/__" which is also used as the
directory separator. The only action needed to convert a filename to a valid
__path__ is percent-encoding.
# <a name='section7'></a>CREDITS
Original code (regular expressions) by Andreas Kupries. Modularisation by Steve
Ball, also the split/join/resolve functionality. RFC 3986 conformance by Keith
Nash.
# <a name='section8'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *uri* 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.
# <a name='keywords'></a>KEYWORDS
[fetching information](../../../../index.md#fetching_information),
[file](../../../../index.md#file), [ftp](../../../../index.md#ftp),
[gopher](../../../../index.md#gopher), [http](../../../../index.md#http),
[https](../../../../index.md#https), [ldap](../../../../index.md#ldap),
[mailto](../../../../index.md#mailto), [news](../../../../index.md#news),
[prospero](../../../../index.md#prospero), [rfc
1630](../../../../index.md#rfc_1630), [rfc 2255](../../../../index.md#rfc_2255),
[rfc 2396](../../../../index.md#rfc_2396), [rfc
3986](../../../../index.md#rfc_3986), [uri](../../../../index.md#uri),
[url](../../../../index.md#url), [wais](../../../../index.md#wais),
[www](../../../../index.md#www)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/uri/urn-scheme.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
|
[//000000001]: # (uri_urn - Tcl Uniform Resource Identifier Management)
[//000000002]: # (Generated from file 'urn-scheme.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (uri_urn(n) 1.0.3 tcllib "Tcl Uniform Resource Identifier Management")
# NAME
uri_urn - URI utilities, URN scheme
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.2
package require uri::urn ?1.0.3?
[__uri::urn::quote__ *url*](#1)
[__uri::urn::unquote__ *url*](#2)
# <a name='description'></a>DESCRIPTION
This package provides two commands to quote and unquote the disallowed
characters for url using the *[urn](../../../../index.md#urn)* scheme, registers
the scheme with the package __[uri](uri.md)__, and provides internal helpers
which will be automatically used by the commands __uri::split__ and
__uri::join__ of package __[uri](uri.md)__ to handle urls using the
*[urn](../../../../index.md#urn)* scheme.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__uri::urn::quote__ *url*
This command quotes the characters disallowed by the
*[urn](../../../../index.md#urn)* scheme (per RFC 2141 sec2.2) in the *url*
and returns the modified url as its result.
- <a name='2'></a>__uri::urn::unquote__ *url*
This commands performs the reverse of __::uri::urn::quote__. It takes an
*[urn](../../../../index.md#urn)* url, removes the quoting from all
disallowed characters, and returns the modified urls as its result.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *uri* 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.
# <a name='keywords'></a>KEYWORDS
[rfc 2141](../../../../index.md#rfc_2141), [uri](../../../../index.md#uri),
[url](../../../../index.md#url), [urn](../../../../index.md#urn)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/uuid/uuid.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
[//000000001]: # (uuid - uuid)
[//000000002]: # (Generated from file 'uuid.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (uuid(n) 1.0.6 tcllib "uuid")
# NAME
uuid - UUID generation and comparison
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [REFERENCES](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require uuid ?1.0.6?
[__::uuid::uuid generate__](#1)
[__::uuid::uuid equal__ *id1* *id2*](#2)
# <a name='description'></a>DESCRIPTION
This package provides a generator of universally unique identifiers (UUID) also
known as globally unique identifiers (GUID). This implementation follows the
draft specification from (1) although this is actually an expired draft
document.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::uuid::uuid generate__
Creates a type 4 uuid by MD5 hashing a number of bits of variant data
including the time and hostname. Returns the string representation of the
new uuid.
- <a name='2'></a>__::uuid::uuid equal__ *id1* *id2*
Compares two uuids and returns true if both arguments are the same uuid.
# <a name='section3'></a>EXAMPLES
% uuid::uuid generate
b12dc22c-5c36-41d2-57da-e29d0ef5839c
# <a name='section4'></a>REFERENCES
1. Paul J. Leach, "UUIDs and GUIDs", February 1998.
([http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt](http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt))
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *uuid* 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.
# <a name='keywords'></a>KEYWORDS
[GUID](../../../../index.md#guid), [UUID](../../../../index.md#uuid)
# <a name='category'></a>CATEGORY
Hashes, checksums, and encryption
# <a name='copyright'></a>COPYRIGHT
Copyright © 2004, Pat Thoyts <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/cc_amex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
[//000000001]: # (valtype::creditcard::amex - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::creditcard::amex(n) 1 tcllib "Validation types")
# NAME
valtype::creditcard::amex - Validation for AMEX creditcard number
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn
package require valtype::creditcard::amex ?1?
[__valtype::creditcard::amex__ __validate__ *value*](#1)
[__valtype::creditcard::amex__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for an AMEX creditcard number.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::creditcard::amex validate .... ;# Does nothing
valtype::creditcard::amex validate .... ;# Throws an error (bad American Expresss creditcard number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::creditcard::amex__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::creditcard::amex__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __CREDITCARD AMEX__. This is then
followed by values detailing the reason for the failure. The full set of
__-errorCode__s which can be thrown by this package are:
- INVALID CREDITCARD AMEX CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be an AMEX creditcard number.
- INVALID CREDITCARD AMEX CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID CREDITCARD AMEX LENGTH
The input value is of the wrong length to be an AMEX creditcard number.
- INVALID CREDITCARD AMEX PREFIX
The input value does not start with the magic value(s) required for it to be
an AMEX creditcard number.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[AMEX](../../../../index.md#amex), [American
Express](../../../../index.md#american_express),
[Checking](../../../../index.md#checking),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking),
[bank](../../../../index.md#bank), [card for
credit](../../../../index.md#card_for_credit), [credit
card](../../../../index.md#credit_card),
[finance](../../../../index.md#finance), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/cc_discover.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
[//000000001]: # (valtype::creditcard::discover - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::creditcard::discover(n) 1 tcllib "Validation types")
# NAME
valtype::creditcard::discover - Validation for Discover creditcard number
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn
package require valtype::creditcard::discover ?1?
[__valtype::creditcard::discover__ __validate__ *value*](#1)
[__valtype::creditcard::discover__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for a Discover creditcard number.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::creditcard::discover validate .... ;# Does nothing
valtype::creditcard::discover validate .... ;# Throws an error (bad Discover creditcard number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::creditcard::discover__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::creditcard::discover__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __CREDITCARD DISCOVER__. This is then
followed by values detailing the reason for the failure. The full set of
__-errorCode__s which can be thrown by this package are:
- INVALID CREDITCARD DISCOVER CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a Discover creditcard number.
- INVALID CREDITCARD DISCOVER CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID CREDITCARD DISCOVER LENGTH
The input value is of the wrong length to be a Discover creditcard number.
- INVALID CREDITCARD DISCOVER PREFIX
The input value does not start with the magic value(s) required for it to be
a Discover creditcard number.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[Discover](../../../../index.md#discover),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking),
[bank](../../../../index.md#bank), [card for
credit](../../../../index.md#card_for_credit), [credit
card](../../../../index.md#credit_card),
[finance](../../../../index.md#finance), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/cc_mastercard.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
[//000000001]: # (valtype::creditcard::mastercard - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::creditcard::mastercard(n) 1 tcllib "Validation types")
# NAME
valtype::creditcard::mastercard - Validation for Mastercard creditcard number
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn
package require valtype::creditcard::mastercard ?1?
[__valtype::creditcard::mastercard__ __validate__ *value*](#1)
[__valtype::creditcard::mastercard__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for a Mastercard creditcard
number.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::creditcard::mastercard validate .... ;# Does nothing
valtype::creditcard::mastercard validate .... ;# Throws an error (bad Mastercard creditcard number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::creditcard::mastercard__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::creditcard::mastercard__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __CREDITCARD MASTERCARD__. This is then
followed by values detailing the reason for the failure. The full set of
__-errorCode__s which can be thrown by this package are:
- INVALID CREDITCARD MASTERCARD CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a Mastercard creditcard number.
- INVALID CREDITCARD MASTERCARD CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID CREDITCARD MASTERCARD LENGTH
The input value is of the wrong length to be a Mastercard creditcard number.
- INVALID CREDITCARD MASTERCARD PREFIX
The input value does not start with the magic value(s) required for it to be
a Mastercard creditcard number.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[MasterCard](../../../../index.md#mastercard),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking),
[bank](../../../../index.md#bank), [card for
credit](../../../../index.md#card_for_credit), [credit
card](../../../../index.md#credit_card),
[finance](../../../../index.md#finance), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/cc_visa.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
[//000000001]: # (valtype::creditcard::visa - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::creditcard::visa(n) 1 tcllib "Validation types")
# NAME
valtype::creditcard::visa - Validation for VISA creditcard number
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn
package require valtype::creditcard::visa ?1?
[__valtype::creditcard::visa__ __validate__ *value*](#1)
[__valtype::creditcard::visa__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for a VISA creditcard number.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::creditcard::visa validate .... ;# Does nothing
valtype::creditcard::visa validate .... ;# Throws an error (bad VISA creditcard number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::creditcard::visa__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::creditcard::visa__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __CREDITCARD VISA__. This is then
followed by values detailing the reason for the failure. The full set of
__-errorCode__s which can be thrown by this package are:
- INVALID CREDITCARD VISA CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a VISA creditcard number.
- INVALID CREDITCARD VISA CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID CREDITCARD VISA LENGTH
The input value is of the wrong length to be a VISA creditcard number.
- INVALID CREDITCARD VISA PREFIX
The input value does not start with the magic value(s) required for it to be
a VISA creditcard number.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[VISA](../../../../index.md#visa),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking),
[bank](../../../../index.md#bank), [card for
credit](../../../../index.md#card_for_credit), [credit
card](../../../../index.md#credit_card),
[finance](../../../../index.md#finance), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/ean13.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
[//000000001]: # (valtype::gs1::ean13 - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::gs1::ean13(n) 1 tcllib "Validation types")
# NAME
valtype::gs1::ean13 - Validation for EAN13
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::gs1::ean13 ?1?
[__valtype::gs1::ean13__ __validate__ *value*](#1)
[__valtype::gs1::ean13__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for an EAN13.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::gs1::ean13 validate .... ;# Does nothing
valtype::gs1::ean13 validate .... ;# Throws an error (bad EAN13).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::gs1::ean13__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::gs1::ean13__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __EAN13__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID EAN13 CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be an EAN13.
- INVALID EAN13 CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID EAN13 LENGTH
The input value is of the wrong length to be an EAN13.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking), [EAN](../../../../index.md#ean),
[EAN13](../../../../index.md#ean13), [European Article
Number](../../../../index.md#european_article_number), [International Article
Number](../../../../index.md#international_article_number),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/iban.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
[//000000001]: # (valtype::iban - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::iban(n) 1.7 tcllib "Validation types")
# NAME
valtype::iban - Validation for IBAN
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::iban ?1.7?
[__valtype::iban__ __validate__ *value*](#1)
[__valtype::iban__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for an IBAN.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::iban validate .... ;# Does nothing
valtype::iban validate .... ;# Throws an error (bad International Bank Account Number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::iban__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::iban__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __IBAN__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID IBAN CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be an IBAN.
- INVALID IBAN CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking), [IBAN](../../../../index.md#iban),
[International Bank Account
Number](../../../../index.md#international_bank_account_number),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking),
[bank](../../../../index.md#bank), [finance](../../../../index.md#finance),
[isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/imei.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
[//000000001]: # (valtype::imei - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::imei(n) 1 tcllib "Validation types")
# NAME
valtype::imei - Validation for IMEI
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn
package require valtype::imei ?1?
[__valtype::imei__ __validate__ *value*](#1)
[__valtype::imei__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for an IMEI.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::imei validate .... ;# Does nothing
valtype::imei validate .... ;# Throws an error (bad International Mobile Equipment Identity (IMEI) number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::imei__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::imei__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __IMEI__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID IMEI CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be an IMEI.
- INVALID IMEI CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID IMEI LENGTH
The input value is of the wrong length to be an IMEI.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking), [IMEI](../../../../index.md#imei),
[International Mobile Equipment
Identity](../../../../index.md#international_mobile_equipment_identity),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking),
[cell-phone](../../../../index.md#cell_phone), [isA](../../../../index.md#isa),
[mobile phone](../../../../index.md#mobile_phone),
[phone](../../../../index.md#phone)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/isbn.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
[//000000001]: # (valtype::isbn - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::isbn(n) 1 tcllib "Validation types")
# NAME
valtype::isbn - Validation for ISBN
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::isbn ?1?
[__valtype::isbn__ __validate__ *value*](#1)
[__valtype::isbn__ __checkdigit__ *value*](#2)
[__valtype::isbn__ __13of__ *value*](#3)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for an ISBN.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::isbn validate .... ;# Does nothing
valtype::isbn validate .... ;# Throws an error (bad ISBN).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::isbn__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::isbn__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
- <a name='3'></a>__valtype::isbn__ __13of__ *value*
This method expects an old-style 10-digit ISBN and returns the canonical
modern 13-digit ISBN. This is used by __validate__ to canonicalize the
input, so that all parts of the system after the validation can expect to
work with modern 13-digit ISBNs.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __ISBN__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID ISBN CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be an ISBN.
- INVALID ISBN CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID ISBN LENGTH
The input value is of the wrong length to be an ISBN.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Book Number](../../../../index.md#book_number),
[Checking](../../../../index.md#checking), [EAN](../../../../index.md#ean),
[EAN13](../../../../index.md#ean13), [European Article
Number](../../../../index.md#european_article_number),
[ISBN](../../../../index.md#isbn), [International Article
Number](../../../../index.md#international_article_number), [International
Standard Book Number](../../../../index.md#international_standard_book_number),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/luhn.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
[//000000001]: # (valtype::luhn - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::luhn(n) 1 tcllib "Validation types")
# NAME
valtype::luhn - Validation for plain number with a LUHN checkdigit
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn ?1?
[__valtype::luhn__ __validate__ *value*](#1)
[__valtype::luhn__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for a plain number with a LUHN
checkdigit.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::luhn validate .... ;# Does nothing
valtype::luhn validate .... ;# Throws an error (bad luhn checkdigit).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::luhn__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::luhn__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __LUHN__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID LUHN CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a plain number with a LUHN
checkdigit.
- INVALID LUHN CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa),
[luhn](../../../../index.md#luhn)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/luhn5.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
[//000000001]: # (valtype::luhn5 - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::luhn5(n) 1 tcllib "Validation types")
# NAME
valtype::luhn5 - Validation for plain number with a LUHN5 checkdigit
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn5 ?1?
[__valtype::luhn5__ __validate__ *value*](#1)
[__valtype::luhn5__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for a plain number with a LUHN5
checkdigit.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::luhn5 validate .... ;# Does nothing
valtype::luhn5 validate .... ;# Throws an error (bad luhn5 checkdigit).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::luhn5__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::luhn5__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __LUHN5__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID LUHN5 CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a plain number with a LUHN5
checkdigit.
- INVALID LUHN5 CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa),
[luhn](../../../../index.md#luhn), [luhn-5](../../../../index.md#luhn_5)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/usnpi.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
[//000000001]: # (valtype::usnpi - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::usnpi(n) 1 tcllib "Validation types")
# NAME
valtype::usnpi - Validation for USNPI
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::luhn
package require valtype::usnpi ?1?
[__valtype::usnpi__ __validate__ *value*](#1)
[__valtype::usnpi__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for an USNPI.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::usnpi validate .... ;# Does nothing
valtype::usnpi validate .... ;# Throws an error (bad US National Provider Identifier (US-NPI) number).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::usnpi__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::usnpi__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __USNPI__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID USNPI CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be an USNPI.
- INVALID USNPI CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID USNPI LENGTH
The input value is of the wrong length to be an USNPI.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking), [NPI](../../../../index.md#npi),
[National Provider
Identifier](../../../../index.md#national_provider_identifier),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[US-NPI](../../../../index.md#us_npi),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa),
[medicare](../../../../index.md#medicare)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/valtype_common.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
[//000000001]: # (valtype::common - Validation types)
[//000000002]: # (Generated from file 'valtype_common.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::common(n) 1 tcllib "Validation types")
# NAME
valtype::common - Validation, common code
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require valtype::common ?1?
[__valtype::common::reject__ *code* *text*](#1)
[__valtype::common::badchar__ *code* ?*text*?](#2)
[__valtype::common::badcheck__ *code* ?*text*?](#3)
[__valtype::common::badlength__ *code* *lengths* ?*text*?](#4)
[__valtype::common::badprefix__ *code* *prefixes* ?*text*?](#5)
# <a name='description'></a>DESCRIPTION
This package implements a number of common commands used by the validation types
in this module. These commands essentially encapsulate the throwing of
validation errors, ensuring that a proper __-errorcode__ is used. See section
[Error Codes](#section3).
# <a name='section2'></a>API
- <a name='1'></a>__valtype::common::reject__ *code* *text*
The core command of this package it throws an __INVALID__ error with the
specified *text*. The first argument is a list of codes extending the
__INVALID__ with detail information.
- <a name='2'></a>__valtype::common::badchar__ *code* ?*text*?
This command throws an __INVALID CHAR__ error with the specified *text*. The
first argument is a list of codes providing details. These are inserted
between the codes __INVALID__ and __CHARACTER__.
- <a name='3'></a>__valtype::common::badcheck__ *code* ?*text*?
This command throws an __INVALID CHECK-DIGIT__ error with the specified
*text*, if any, extended by the standard text "the check digit is
incorrect". The first argument is a list of codes providing details. These
are inserted between the codes __INVALID__ and __CHECK_DIGIT__.
- <a name='4'></a>__valtype::common::badlength__ *code* *lengths* ?*text*?
This command throws an __INVALID LENGTH__ error with the specified *text*,
if any, extended by the standard text "incorrect length, expected ...
character(s)". The first argument is a list of codes providing details.
These are inserted between the codes __INVALID__ and __LENGTH__. The
argument *lengths* is a list of the input lengths which had been expected,
i.e. these are the valid lengths.
- <a name='5'></a>__valtype::common::badprefix__ *code* *prefixes* ?*text*?
This command throws an __INVALID PREFIX__ error with the specified *text*,
if any, extended by the standard text "incorrect prefix, expected ...". The
first argument is a list of codes providing details. These are inserted
between the codes __INVALID__ and __PREFIX__. The argument *prefixes* is a
list of the input prefixes which had been expected, i.e. these are the valid
prefixes.
# <a name='section3'></a>Error Codes
The errors thrown by the commands of this package all use the __-errorcode__
__INVALID__ to distinguish the input validation failures they represent from
package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. This is supplied by the caller. This is then followed
by values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are shown below, with __<>__ a placeholder
for both the caller-supplied type-information, the type description.
- INVALID __<>__ CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a __<>__.
- INVALID __<>__ CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
- INVALID __<>__ LENGTH
The input value is of the wrong length to be a __<>__.
- INVALID __<>__ PREFIX
The input value does not start with the magic value(s) required for it to be
a __<>__.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/valtype/verhoeff.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
[//000000001]: # (valtype::verhoeff - Validation types)
[//000000002]: # (Generated from file 'vtype.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (valtype::verhoeff(n) 1 tcllib "Validation types")
# NAME
valtype::verhoeff - Validation for plain number with a VERHOEFF checkdigit
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Error Codes](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require snit 2
package require valtype::common
package require valtype::verhoeff ?1?
[__valtype::verhoeff__ __validate__ *value*](#1)
[__valtype::verhoeff__ __checkdigit__ *value*](#2)
# <a name='description'></a>DESCRIPTION
This package implements a snit validation type for a plain number with a
VERHOEFF checkdigit.
A validation type is an object that can be used to validate Tcl values of a
particular kind. For example, __snit::integer__, a validation type defined by
the __[snit](../snit/snit.md)__ package is used to validate that a Tcl value is
an integer.
Every validation type has a __validate__ method which is used to do the
validation. This method must take a single argument, the value to be validated;
further, it must do nothing if the value is valid, but throw an error if the
value is invalid:
valtype::verhoeff validate .... ;# Does nothing
valtype::verhoeff validate .... ;# Throws an error (bad verhoeff checkdigit).
The __validate__ method will always return the validated value on success, and
throw the __-errorcode__ INVALID on error, possibly with additional elements
which provide more details about the problem.
# <a name='section2'></a>API
The API provided by this package satisfies the specification of snit validation
types found in the documentation of *[Snit's Not Incr Tcl](../snit/snit.md)*.
- <a name='1'></a>__valtype::verhoeff__ __validate__ *value*
This method validates the *value* and returns it, possibly in a canonical
form, if it passes. If the value does not pass the validation an error is
thrown.
- <a name='2'></a>__valtype::verhoeff__ __checkdigit__ *value*
This method computes a check digit for the *value*. Before doing so it is
validated, except for a checkdigit. If the value does not pass the
validation no check digit is calculated and an error is thrown instead.
# <a name='section3'></a>Error Codes
As said in the package description, the errors thrown by the commands of this
package in response to input validation failures use the __-errorcode__ INVALID
to distinguish themselves from package internal errors.
To provide more detailed information about why the validation failed the
__-errorCode__ goes actually beyond that. First, it will contain a code
detailing the type itself. Here this is __VERHOEFF__. This is then followed by
values detailing the reason for the failure. The full set of __-errorCode__s
which can be thrown by this package are:
- INVALID VERHOEFF CHARACTER
The input value contained one or more bad characters, i.e. characters which
must not occur in the input for it to be a plain number with a VERHOEFF
checkdigit.
- INVALID VERHOEFF CHECK-DIGIT
The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course, th
input may be an outright fake too.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *valtype* 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.
# <a name='keywords'></a>KEYWORDS
[Checking](../../../../index.md#checking),
[Testing](../../../../index.md#testing), [Type
checking](../../../../index.md#type_checking),
[Validation](../../../../index.md#validation), [Value
checking](../../../../index.md#value_checking), [isA](../../../../index.md#isa),
[verhoeff](../../../../index.md#verhoeff)
# <a name='category'></a>CATEGORY
Validation, Type checking
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/cat.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
[//000000001]: # (tcl::chan::cat - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'cat.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::cat(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::cat - Concatenation channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::core ?1?
package require tcl::chan::cat ?1?
[__::tcl::chan::cat__ *chan*...](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::cat__ package provides a command creating concatenation
channels. These are non-seekable channels owning a list of subordinate channels
whose contents they return in order, until all are exhausted. In this manner the
channel is the concatentation of the contents of all the sub-ordinate channels.
Note that the created channels take ownership of the channels they were
constructed with. Whenever they have exhausted one of their channel it will be
closed. Similarly, closing the cat channel will close all the sub-ordinates it
still has.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::core](../virtchannel_core/core.md)__ framework.
Event handling is delegated to the currently active sub-channel.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::cat__ *chan*...
This command creates the concatenation channel using all the provided
channels, and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[concatenation channel](../../../../index.md#concatenation_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/facade.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
[//000000001]: # (tcl::chan::facade - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'facade.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::facade(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::facade - Facade channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require logger
package require tcl::chan::core ?1?
package require tcl::chan::facade ?1?
[__::tcl::chan::facade__ *chan*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::facade__ package provides a command creating facades to other
channels. These are channels which own a single subordinate channel and delegate
all operations to.
The main use for facades is the debugging of actions on a channel. While most of
the information could be tracked by a virtual channel transformation it does not
have access to the event-related operation, and furthermore they are only
available in Tcl 8.6.
Therefore this channel, usable with Tcl 8.5, and having access to everything
going on for a channel.
The intercepted actions on channel are logged through package
__[logger](../log/logger.md)__.
Beyond that facades provide the following additional channel configuration
options:
- __-self__
The TclOO object handling the facade.
- __-fd__
The handle of the subordinate, i.e. wrapped channel.
- __-used__
The last time the wrapped channel was read from or written to by the facade,
as per __clock milliseconds__. A value of __0__ indicates that the
subordinate channel was not accessed at all, yet.
- __-created__
The time the facade was created, as per __clock milliseconds__.
- __-user__
A free-form value identifying the user of the facade and its wrapped
channel.
Of these only option __-user__ is writable.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::facade__ *chan*
This command creates the facade channel around the provided channel *chan*,
and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[concatenation channel](../../../../index.md#concatenation_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
[//000000001]: # (tcl::chan::halfpipe - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'halfpipe.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::halfpipe(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::halfpipe - In-memory channel, half of a fifo2
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Options](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::halfpipe ?1?
package require tcl::chan::halfpipe ?1?
[__::tcl::chan::halfpipe__ ?__-option__ *value*...?](#1)
[*objectCmd* __put__ *bytes*](#2)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::halfpipe__ package provides a command creating one half of a
__[tcl::chan::fifo2](tcllib_fifo2.md)__ pair. Writing into such a channel
invokes a set of callbacks which then handle the data. This is similar to a
channel handler, except having a much simpler API.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::halfpipe__ ?__-option__ *value*...?
This command creates a halfpipe channel and configures it with the callbacks
to run when the channel is closed, data was written to it, or ran empty. See
the section [Options](#section3) for the list of options and associated
semantics. The result of the command is a list containing two elements, the
handle of the new channel, and the object command of the channel handler, in
this order. The latter is supplied to the caller to provide her with access
to the __put__ method for adding data to the channel.
Two halfpipes with a bit of glue logic in the callbacks make for one
__[tcl::chan::fifo2](tcllib_fifo2.md)__.
- <a name='2'></a>*objectCmd* __put__ *bytes*
This method of the channel handler object puts the data *bytes* into the
channel so that it can be read from it.
# <a name='section3'></a>Options
- __-close-command__ cmdprefix
This callback is invoked when the channel is closed. A single argument is
supplied, the handle of the channel being closed. The result of the callback
is ignored.
- __-write-command__ cmdprefix
This callback is invoked when data is written to the channel. Two arguments
are supplied, the handle of the channel written to, and the data written.
The result of the callback is ignored.
- __-empty-command__ cmdprefix
This callback is invoked when the channel has run out of data to read. A
single argument is supplied, the handle of the channel.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[callbacks](../../../../index.md#callbacks), [fifo](../../../../index.md#fifo),
[in-memory channel](../../../../index.md#in_memory_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
[//000000001]: # (tcl::chan::nullzero - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'nullzero.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::nullzero(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::nullzero - Null/Zero channel combination
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::nullzero ?1?
[__::tcl::chan::nullzero__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::nullzero__ package provides a command creating channels, which
are a combination of null and zero devices. They immediately forget whatever is
written to them, and on reading return an infinite stream of null characters.
Packages related to this are __[tcl::chan::null](tcllib_null.md)__ and
__[tcl::chan::zero](tcllib_zero.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::nullzero__
This command creates a new nullzero channel and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[/dev/null](../../../../index.md#_dev_null),
[/dev/zero](../../../../index.md#_dev_zero), [null](../../../../index.md#null),
[reflected channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel),
[zero](../../../../index.md#zero)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/randseed.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
[//000000001]: # (tcl::randomseed - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'randseed.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::randomseed(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::randomseed - Utilities for random channels
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::randomseed ?1?
[__::tcl::randomseed__](#1)
[__::tcl::combine__ *seed1* *seed2*](#2)
# <a name='description'></a>DESCRIPTION
The __tcl::randomseed__ package provides a a few utility commands to help with
the seeding of __[tcl::chan::random](tcllib_random.md)__ channels.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::randomseed__
This command creates returns a list of seed integers suitable as seed
argument for random channels. The numbers are derived from the process id,
current time, and Tcl random number generator.
- <a name='2'></a>__::tcl::combine__ *seed1* *seed2*
This command takes to seed lists and combines them into a single list by
XORing them elementwise, modulo 256. If the lists are not of equial length
the shorter of the two is padded with 0s before merging.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[/dev/random](../../../../index.md#_dev_random),
[merge](../../../../index.md#merge), [random](../../../../index.md#random),
[reflected channel](../../../../index.md#reflected_channel),
[seed](../../../../index.md#seed), [tip 219](../../../../index.md#tip_219),
[virtual channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/std.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
[//000000001]: # (tcl::chan::std - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'std.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::std(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::std - Standard I/O, unification of stdin and stdout
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::core ?1?
package require tcl::chan::std ?1?
[__::tcl::chan::std__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::std__ package provides a command creating a standard channel
which unifies stdin and stdout into a single read- and writable channel. The
result is not seek-able, like the original standard channels.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::core](../virtchannel_core/core.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::std__
This command creates the std channel and returns its handle.
The channel is created only once, on the first call, and all future calls
simply return this handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[reflected channel](../../../../index.md#reflected_channel), [standard
io](../../../../index.md#standard_io), [stdin](../../../../index.md#stdin),
[stdout](../../../../index.md#stdout), [tip 219](../../../../index.md#tip_219),
[virtual channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2011 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
[//000000001]: # (tcl::chan::fifo - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_fifo.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::fifo(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::fifo - In-memory fifo channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::fifo ?1?
[__::tcl::chan::fifo__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::fifo__ package provides a command creating channels which live
purely in memory. Access is fifo-like, i.e. things are read out of the channel
in the order they were written to it. This is equivalent to the fifo channels
provided by the package __Memchan__, except that this is written in pure Tcl,
not C. On the other hand, __Memchan__ is usable with Tcl 8.4 and before, whereas
this package requires Tcl 8.5 or higher, and
__[TclOO](../../../../index.md#tcloo)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::fifo__
This command creates a new fifo channel and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[fifo](../../../../index.md#fifo), [in-memory
channel](../../../../index.md#in_memory_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (tcl::chan::fifo2 - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_fifo2.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::fifo2(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::fifo2 - In-memory interconnected fifo channels
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::halfpipe ?1?
package require tcl::chan::fifo2 ?1?
[__::tcl::chan::fifo2__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::fifo2__ package provides a command creating pairs of channels
which live purely in memory and are connected to each other in a fifo manner.
What is written to one half of the pair can be read from the other half, in the
same order. One particular application for this is communication between
threads, with one half of the pair moved to the thread to talk to. This is
equivalent to the fifo2 channels provided by the package __Memchan__, except
that this is written in pure Tcl, not C. On the other hand, __Memchan__ is
usable with Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher,
and __[TclOO](../../../../index.md#tcloo)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::fifo2__
This command creates a new connected pair of fifo channels and returns their
handles, as a list containing two elements.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[connected fifos](../../../../index.md#connected_fifos),
[fifo](../../../../index.md#fifo), [in-memory
channel](../../../../index.md#in_memory_channel), [inter-thread
communication](../../../../index.md#inter_thread_communication), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (tcl::chan::memchan - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_memchan.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::memchan(n) 1.0.4 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::memchan - In-memory channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::memchan ?1.0.4?
[__::tcl::chan::memchan__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::memchan__ package provides a command creating channels which
live purely in memory. They provide random-access, i.e. are seekable. This is
equivalent to the memchan channels provided by the package __Memchan__, except
that this is written in pure Tcl, not C. On the other hand, __Memchan__ is
usable with Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher,
and __[TclOO](../../../../index.md#tcloo)__.
Packages related to this are __[tcl::chan::string](tcllib_string.md)__ and
__[tcl::chan::variable](tcllib_variable.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::memchan__
This command creates a new memchan channel and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[in-memory channel](../../../../index.md#in_memory_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009-2017 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (tcl::chan::null - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_null.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::null(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::null - Null channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::null ?1?
[__::tcl::chan::null__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::null__ package provides a command creating null channels, i.e.
write-only channels which immediately forget whatever is written to them. This
is equivalent to the null channels provided by the package __Memchan__, except
that this is written in pure Tcl, not C. On the other hand, __Memchan__ is
usable with Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher,
and __[TclOO](../../../../index.md#tcloo)__.
Packages related to this are __[tcl::chan::zero](tcllib_zero.md)__ and
__[tcl::chan::nullzero](nullzero.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::null__
This command creates a new null channel and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[/dev/null](../../../../index.md#_dev_null), [null](../../../../index.md#null),
[reflected channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (tcl::chan::random - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_random.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::random(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::random - Random channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::random ?1?
[__::tcl::chan::random__ *seed*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::random__ package provides a command creating random channels,
i.e. read-only channels which return an infinite stream of pseudo-random
characters upon reading. This is similar to the random channels provided by the
package __Memchan__, except that this is written in pure Tcl, not C, and uses a
much simpler generator as well. On the other hand, __Memchan__ is usable with
Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, and TclOO.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::random__ *seed*
This command creates a new random channel and returns its handle. The seed
is a list of integer numbers used to initialize the internal feedback shift
register of the generator.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[/dev/random](../../../../index.md#_dev_random),
[random](../../../../index.md#random), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
[//000000001]: # (tcl::chan::string - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_string.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::string(n) 1.0.3 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::string - Read-only in-memory channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::string ?1.0.3?
[__::tcl::chan::string__ *content*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::string__ package provides a command creating channels which
live purely in memory. They provide random-access, i.e. are seekable. In
contrast to the channels created by __[tcl::chan::memchan](tcllib_memchan.md)__
they are read-only however, their content is provided at the time of
construction and immutable afterward.
Packages related to this are __[tcl::chan::memchan](tcllib_memchan.md)__ and
__[tcl::chan::variable](tcllib_variable.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::string__ *content*
This command creates a new string channel and returns its handle. The
channel provides random read-only access to the *content* string.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[in-memory channel](../../../../index.md#in_memory_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (tcl::chan::variable - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_variable.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::variable(n) 1.0.4 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::variable - In-memory channel using variable for storage
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::variable ?1.0.4?
[__::tcl::chan::variable__ *varname*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::variable__ package provides a command creating channels which
live purely in memory. They provide random-access, i.e. are seekable. In
contrast to the channels created by __[tcl::chan::memchan](tcllib_memchan.md)__
the data is not hidden in the channel however, but stored in an associated
variable, specified at the time of construction.
Packages related to this are __[tcl::chan::memchan](tcllib_memchan.md)__ and
__[tcl::chan::string](tcllib_string.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::variable__ *varname*
This command creates a new variable channel and returns its handle. The
content of the channel is stored in the associated namespace variable
*varname*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[in-memory channel](../../../../index.md#in_memory_channel), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (tcl::chan::zero - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_zero.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::zero(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::zero - Zero channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::zero ?1?
[__::tcl::chan::zero__](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::zero__ package provides a command creating zero channels, i.e.
read-only channels which return an infinite stream of null characters upon
reading. This is equivalent to the zero channels provided by the package
__Memchan__, except that this is written in pure Tcl, not C. On the other hand,
__Memchan__ is usable with Tcl 8.4 and before, whereas this package requires Tcl
8.5 or higher, and TclOO.
Packages related to this are __[tcl::chan::null](tcllib_null.md)__ and
__[tcl::chan::nullzero](nullzero.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::zero__
This command creates a new zero channel and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[/dev/zero](../../../../index.md#_dev_zero), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel),
[zero](../../../../index.md#zero)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
[//000000001]: # (tcl::chan::textwindow - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'textwindow.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::textwindow(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::textwindow - Textwindow channel
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::events ?1?
package require tcl::chan::textwindow ?1?
[__::tcl::chan::textwindow__ *widget*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::textwindow__ package provides a command creating write-only
channels connected to text widgets. Anything written to the channel is printed
into the associated widget.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
channel handler is a sub-class of the
__[tcl::chan::events](../virtchannel_core/events.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::chan::textwindow__ *widget*
This command creates a new textwindow channel and returns its handle. Data
written to this channel will appear in the associated *widget*.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[Tk](../../../../index.md#tk), [reflected
channel](../../../../index.md#reflected_channel), [text
widget](../../../../index.md#text_widget), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_core/core.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
[//000000001]: # (tcl::chan::core - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'core.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::core(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::core - Basic reflected/virtual channel support
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Instance API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::core ?1?
[__::tcl::chan::core__ *objectName*](#1)
[*objectName* __initialize__ *thechannel* *mode*](#2)
[*objectName* __finalize__ *thechannel*](#3)
[*objectName* __destroy__](#4)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::core__ package provides a
__[TclOO](../../../../index.md#tcloo)__ class implementing common behaviour
needed by virtually every reflected or virtual channel (initialization,
finalization).
This class expects to be used as either superclass of a concrete channel class,
or to be mixed into such a class.
# <a name='section2'></a>Class API
- <a name='1'></a>__::tcl::chan::core__ *objectName*
This command creates a new channel core object with an associated global Tcl
command whose name is *objectName*. This command may be used to invoke
various operations on the object, as described in the section for the
[Instance API](#section3).
# <a name='section3'></a>Instance API
The API of channel core instances provides only two methods, both corresponding
to channel handler commands (For reference see [TIP 219](http:/tip.tcl.tk/219)).
They expect to be called from whichever object instance the channel core was
made a part of.
- <a name='2'></a>*objectName* __initialize__ *thechannel* *mode*
This method implements standard behaviour for the __initialize__ method of
channel handlers. Using introspection it finds the handler methods supported
by the instance and returns a list containing their names, as expected by
the support for reflected channels in the Tcl core.
It further remembers the channel handle in an instance variable for access
by sub-classes.
- <a name='3'></a>*objectName* __finalize__ *thechannel*
This method implements standard behaviour for the __finalize__ method of
channel handlers. It simply destroys itself.
- <a name='4'></a>*objectName* __destroy__
Destroying the channel core instance closes the channel it was initialized
for, see the method __initialize__. When destroyed from within a call of
__finalize__ this does not happen, under the assumption that the channel is
being destroyed by Tcl.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[reflected channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_core/events.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
[//000000001]: # (tcl::chan::events - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'events.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::chan::events(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::chan::events - Event support for reflected/virtual channels
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Instance API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::chan::core ?1?
package require tcl::chan::events ?1?
[__::tcl::chan::events__ *objectName*](#1)
[*objectName* __finalize__ *thechannel*](#2)
[*objectName* __watch__ *thechannel* *eventmask*](#3)
[*objectName* __allow__ *eventname*...](#4)
[*objectName* __disallow__ *eventname*...](#5)
# <a name='description'></a>DESCRIPTION
The __tcl::chan::events__ package provides a
__[TclOO](../../../../index.md#tcloo)__ class implementing common behaviour
needed by virtually every reflected or virtual channel supporting event driven
IO. It is a sub-class of __[tcl::chan::core](core.md)__, inheriting all of its
behaviour.
This class expects to be used as either superclass of a concrete channel class,
or to be mixed into such a class.
# <a name='section2'></a>Class API
- <a name='1'></a>__::tcl::chan::events__ *objectName*
This command creates a new channel event core object with an associated
global Tcl command whose name is *objectName*. This command may be used to
invoke various operations on the object, as described in the section for the
[Instance API](#section3).
# <a name='section3'></a>Instance API
The API of channel event core instances provides only four methods, two
corresponding to channel handler commands (For reference see [TIP
219](http:/tip.tcl.tk/219)), and the other two for use by sub-classes to control
event generation. They former expect to be called from whichever object instance
the channel event core was made a part of.
- <a name='2'></a>*objectName* __finalize__ *thechannel*
This method implements standard behaviour for the __finalize__ method of
channel handlers. It overrides the behaviour inherited from
__[tcl::chan::core](core.md)__ and additionally disables any and all event
generation before destroying itself.
- <a name='3'></a>*objectName* __watch__ *thechannel* *eventmask*
This method implements standard behaviour for the __watch__ method of
channel handlers. Called by the IO system whenever the interest in event
changes it updates the instance state to activate and/or suppress the
generation of the events of (non-)interest.
- <a name='4'></a>*objectName* __allow__ *eventname*...
- <a name='5'></a>*objectName* __disallow__ *eventname*...
These two methods are exported to sub-classes, so that their instances can
notify their event core of the events the channel they implement can (allow)
or cannot (disallow) generate. Together with the information about the
events requested by Tcl's IO system coming in through the __watch__ method
the event core is able to determine which events it should (not) generate
and act accordingly.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[event management](../../../../index.md#event_management), [reflected
channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
[//000000001]: # (tcl::transform::core - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'transformcore.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::core(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::core - Basic reflected/virtual channel transform support
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Instance API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.5
package require TclOO
package require tcl::transform::core ?1?
[__::tcl::transform::core__ *objectName*](#1)
[*objectName* __initialize__ *thechannel* *mode*](#2)
[*objectName* __finalize__ *thechannel*](#3)
[*objectName* __destroy__](#4)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::core__ package provides a
__[TclOO](../../../../index.md#tcloo)__ class implementing common behaviour
needed by virtually every reflected or virtual channel transformation
(initialization, finalization).
This class expects to be used as either superclass of a concrete channel class,
or to be mixed into such a class.
# <a name='section2'></a>Class API
- <a name='1'></a>__::tcl::transform::core__ *objectName*
This command creates a new transform core object with an associated global
Tcl command whose name is *objectName*. This command may be used to invoke
various operations on the object, as described in the section for the
[Instance API](#section3).
# <a name='section3'></a>Instance API
The API of transform core instances provides only two methods, both
corresponding to transform handler commands (For reference see [TIP
230](http:/tip.tcl.tk/230)). They expect to be called from whichever object
instance the transform core was made a part of.
- <a name='2'></a>*objectName* __initialize__ *thechannel* *mode*
This method implements standard behaviour for the __initialize__ method of
transform handlers. Using introspection it finds the handler methods
supported by the instance and returns a list containing their names, as
expected by the support for reflected transformation in the Tcl core.
It further remembers the channel handle in an instance variable for access
by sub-classes.
- <a name='3'></a>*objectName* __finalize__ *thechannel*
This method implements standard behaviour for the __finalize__ method of
channel handlers. It simply destroys itself.
- <a name='4'></a>*objectName* __destroy__
Destroying the transform core instance closes the channel and transform it
was initialized for, see the method __initialize__. When destroyed from
within a call of __finalize__ this does not happen, under the assumption
that the channel and transform are being destroyed by Tcl.
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[reflected channel](../../../../index.md#reflected_channel), [tip
219](../../../../index.md#tip_219), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
[//000000001]: # (tcl::transform::adler32 - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'adler32.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::adler32(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::adler32 - Adler32 transformation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::adler32 ?1?
[__::tcl::transform::adler32__ *chan* __-option__ *value*...](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::adler32__ package provides a command creating a channel
transformation which passes the read and written bytes through unchanged (like
__[tcl::transform::identity](identity.md)__), but additionally continuously
computes the adler32 checksums of the data it has seen for each direction and
stores them in Tcl variables specified at construction time.
Related transformations in this module are
__[tcl::transform::counter](vt_counter.md)__,
__[tcl::transform::crc32](vt_crc32.md)__,
__[tcl::transform::identity](identity.md)__, and
__[tcl::transform::observe](observe.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::adler32__ *chan* __-option__ *value*...
This command creates an adler32 checksumming transformation on top of the
channel *chan* and returns its handle. The accepted options are
* __-read-variable__ varname
The value of the option is the name of a global or namespaced variable,
the location where the transformation has to store the adler32 checksum
of the data read from the channel.
If not specified, or the empty string, the checksum of the read
direction is not saved.
* __-write-variable__ varname
The value of the option is the name of a global or namespaced variable,
the location where the transformation has to store the adler32 checksum
of the data written to the channel.
If not specified, or the empty string, the checksum of the write
direction is not saved.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[adler32](../../../../index.md#adler32), [channel
transformation](../../../../index.md#channel_transformation),
[checksum](../../../../index.md#checksum), [reflected
channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/hex.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
[//000000001]: # (tcl::transform::hex - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'hex.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::hex(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::hex - Hexadecimal encoding transformation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::hex ?1?
[__::tcl::transform::hex__ *chan*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::hex__ package provides a command creating a channel
transformation which hex encodes data written to it, and decodes the data read
from it.
A related transformations in this module is
__[tcl::transform::base64](vt_base64.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::hex__ *chan*
This command creates a hex transformation on top of the channel *chan* and
returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[hexadecimal](../../../../index.md#hexadecimal), [reflected
channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/identity.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
[//000000001]: # (tcl::transform::identity - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'identity.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::identity(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::identity - Identity transformation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::identity ?1?
[__::tcl::transform::identity__ *chan*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::identity__ package provides a command creating an identity
channel transformation, which does nothing but pass the read and written bytes
through it unchanged. Not really useful in an application, however as the
prototypical observer transformation its code is a useful starting point for any
other observers people may wish to write.
The transformations in this module which derived from identity's code are
__[tcl::transform::adler32](adler32.md)__,
__[tcl::transform::counter](vt_counter.md)__,
__[tcl::transform::crc32](vt_crc32.md)__, and
__[tcl::transform::observe](observe.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::identity__ *chan*
This command creates an identity transformation on top of the channel *chan*
and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[identity](../../../../index.md#identity), [reflected
channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (tcl::transform::limitsize - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'limitsize.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::limitsize(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::limitsize - limiting input
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::limitsize ?1?
[__::tcl::transform::limitsize__ *chan* *max*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::limitsize__ package provides a command creating a channel
transformation which limits the number of characters which can be read from the
channel. A generator for an artificial EOF.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::limitsize__ *chan* *max*
This command creates a size limiting transformation on top of the channel
*chan* and returns its handle.
*max* is the number of bytes which can be read from the channel before EOF
is signaled by the transformation. Note that popping the transformation
clears the EOF it generated as well.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[limitsize](../../../../index.md#limitsize), [reflected
channel](../../../../index.md#reflected_channel), [size
limit](../../../../index.md#size_limit), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/observe.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (tcl::transform::observe - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'observe.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::observe(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::observe - Observer transformation, stream copy
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::observe ?1?
[__::tcl::transform::observe__ *chan* *logw* *logr*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::observer__ package provides a command creating a channel
transformation which passes the read and written bytes through unchanged (like
__[tcl::transform::identity](identity.md)__), but additionally copies the data
it has seen for each direction into channels specified at construction time.
Related transformations in this module are
__[tcl::transform::adler32](adler32.md)__,
__[tcl::transform::counter](vt_counter.md)__,
__[tcl::transform::crc32](vt_crc32.md)__, and
__[tcl::transform::identity](identity.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::observe__ *chan* *logw* *logr*
This command creates an observer transformation on top of the channel *chan*
and returns its handle. The channel handles *logr* and *logw* are there the
data is copied to.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[observer](../../../../index.md#observer), [reflected
channel](../../../../index.md#reflected_channel), [stream
copy](../../../../index.md#stream_copy), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/rot.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
[//000000001]: # (tcl::transform::rot - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'rot.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::rot(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::rot - rot-encryption
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::rot ?1?
[__::tcl::transform::rot__ *chan* *key*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::rot__ package provides a command creating a channel
transformation which performs primitive encryption (on writing) and decryption
(on reading) on the alphabetic characters. The algorithm is the Caesar-cipher, a
specific variant of which is rot13.
A related transformations in this module is
__[tcl::transform::otp](vt_otp.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::rot__ *chan* *key*
This command creates a rot encryption transformation on top of the channel
*chan* and returns its handle.
The "*key*" specifies how far characters are rotated in the alphabet, and is
wrapped to the range "0...25".
Note that this transformation affects only bytes in the ranges ASCII
65...90, and 97...122, i.e. the upper- and lower-case alphabetic characters,
i.e. "A...Z" and "a...z". All other bytes are passed through unchanged.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[caesar cipher](../../../../index.md#caesar_cipher), [channel
transformation](../../../../index.md#channel_transformation),
[cipher](../../../../index.md#cipher),
[decryption](../../../../index.md#decryption),
[encryption](../../../../index.md#encryption), [reflected
channel](../../../../index.md#reflected_channel),
[rot](../../../../index.md#rot), [rot13](../../../../index.md#rot13), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (tcl::transform::spacer - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'spacer.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::spacer(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::spacer - Space insertation and removal
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::spacer ?1?
[__::tcl::transform::spacer__ *chan* *n* ?*space*?](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::spacer__ package provides a command creating a channel
transformation which adds spacing to the data written to it, and removes such
spacing from the data read from it.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::spacer__ *chan* *n* ?*space*?
This command creates a spacer transformation on top of the channel *chan*
and returns its handle.
The *space* character sequence will be added every *n* bytes of data
written, and on the read side the same is done in reverse, removing the
spacing. If *space* is not specified it defaults to a single space character
(ASCII 32).
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[reflected channel](../../../../index.md#reflected_channel),
[spacing](../../../../index.md#spacing), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
[//000000001]: # (tcl::transform::zlib - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'tcllib_zlib.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::zlib(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::zlib - zlib (de)compression
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::zlib ?1?
[__::tcl::transform::zlib__ *chan* ?*level*?](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::zlib__ package provides a command creating a channel
transformation which zlib compresses the written data, and decompresses on
reading.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::zlib__ *chan* ?*level*?
This command creates a zlib compressor transformation on top of the channel
*chan* and returns its handle.
The *level* specifies how much effort is put into the compression, from
__0__ to __9__, and defaults to __4__.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[compression](../../../../index.md#compression),
[decompression](../../../../index.md#decompression), [reflected
channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230), [tip 234](../../../../index.md#tip_234),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel),
[zlib](../../../../index.md#zlib)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
[//000000001]: # (tcl::transform::base64 - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'vt_base64.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::base64(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::base64 - Base64 encoding transformation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::base64 ?1?
[__::tcl::transform::base64__ *chan*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::base64__ package provides a command creating a channel
transformation which base64 encodes data written to it, and decodes the data
read from it.
A related transformations in this module is __[tcl::transform::hex](hex.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::base64__ *chan*
This command creates a base64 transformation on top of the channel *chan*
and returns its handle.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[base64](../../../../index.md#base64), [channel
transformation](../../../../index.md#channel_transformation), [reflected
channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230), [tip 317](../../../../index.md#tip_317),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
[//000000001]: # (tcl::transform::counter - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'vt_counter.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::counter(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::counter - Counter transformation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::counter ?1?
[__::tcl::transform::counter__ *chan* __-option__ *value*...](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::counterr__ package provides a command creating a channel
transformation which passes the read and written bytes through unchanged (like
__[tcl::transform::identity](identity.md)__), but additionally counts the bytes
it has seen for each direction and stores these counts in Tcl variables
specified at construction time.
Related transformations in this module are
__[tcl::transform::adler32](adler32.md)__,
__[tcl::transform::crc32](vt_crc32.md)__,
__[tcl::transform::identity](identity.md)__, and
__[tcl::transform::observe](observe.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::counter__ *chan* __-option__ *value*...
This command creates a counter transformation on top of the channel *chan*
and returns its handle. The accepted options are
* __-read-variable__ varname
The value of the option is the name of a global or namespaced variable,
the location where the transformation has to store the byte count of the
data read from the channel.
If not specified, or the empty string, the counter of the read direction
is not saved.
* __-write-variable__ varname
The value of the option is the name of a global or namespaced variable,
the location where the transformation has to store the byte count of the
data written to the channel.
If not specified, or the empty string, the counter of the write
direction is not saved.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[counter](../../../../index.md#counter), [reflected
channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
[//000000001]: # (tcl::transform::crc32 - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'vt_crc32.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::crc32(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::crc32 - Crc32 transformation
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::crc32 ?1?
[__::tcl::transform::crc32__ *chan* __-option__ *value*...](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::crc32__ package provides a command creating a channel
transformation which passes the read and written bytes through unchanged (like
__[tcl::transform::identity](identity.md)__), but additionally continuously
computes the crc32 checksums of the data it has seen for each direction and
stores them in Tcl variables specified at construction time. The checksum in
question is zlib's crc32.
Related transformations in this module are
__[tcl::transform::adler32](adler32.md)__,
__[tcl::transform::counter](vt_counter.md)__,
__[tcl::transform::identity](identity.md)__, and
__[tcl::transform::observe](observe.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::crc32__ *chan* __-option__ *value*...
This command creates a crc32 checksumming transformation on top of the
channel *chan* and returns its handle. The accepted options are
* __-read-variable__ varname
The value of the option is the name of a global or namespaced variable,
the location where the transformation has to store the crc32 checksum of
the data read from the channel.
If not specified, or the empty string, the checksum of the read
direction is not saved.
* __-write-variable__ varname
The value of the option is the name of a global or namespaced variable,
the location where the transformation has to store the crc32 checksum of
the data written to the channel.
If not specified, or the empty string, the checksum of the write
direction is not saved.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[checksum](../../../../index.md#checksum), [crc32](../../../../index.md#crc32),
[reflected channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
[//000000001]: # (tcl::transform::otp - Reflected/virtual channel support)
[//000000002]: # (Generated from file 'vt_otp.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl::transform::otp(n) 1 tcllib "Reflected/virtual channel support")
# NAME
tcl::transform::otp - Encryption via one-time pad
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require tcl::transform::core ?1?
package require tcl::transform::otp ?1?
[__::tcl::transform::otp__ *chan* *keychanw* *keychanr*](#1)
# <a name='description'></a>DESCRIPTION
The __tcl::transform::otp__ package provides a command creating a channel
transformation which uses externally provided one-time pads to perform
encryption (on writing) and decryption (on reading).
A related transformations in this module is __[tcl::transform::rot](rot.md)__.
The internal __[TclOO](../../../../index.md#tcloo)__ class implementing the
transform handler is a sub-class of the
__[tcl::transform::core](../virtchannel_core/transformcore.md)__ framework.
# <a name='section2'></a>API
- <a name='1'></a>__::tcl::transform::otp__ *chan* *keychanw* *keychanr*
This command creates a one-time pad based encryption transformation on top
of the channel *chan* and returns its handle.
The two channels *keychanw* and *keychanr* contain the one-time pads for the
write and read directions, respectively. Their contents are reads and xored
with the bytes written to and read from the channel.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *virtchannel* 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.
# <a name='keywords'></a>KEYWORDS
[channel transformation](../../../../index.md#channel_transformation),
[cipher](../../../../index.md#cipher),
[decryption](../../../../index.md#decryption),
[encryption](../../../../index.md#encryption), [one time
pad](../../../../index.md#one_time_pad), [otp](../../../../index.md#otp),
[reflected channel](../../../../index.md#reflected_channel), [tip
230](../../../../index.md#tip_230),
[transformation](../../../../index.md#transformation), [virtual
channel](../../../../index.md#virtual_channel), [xor](../../../../index.md#xor)
# <a name='category'></a>CATEGORY
Channels
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/websocket/websocket.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
|
[//000000001]: # (websocket - websocket client and server)
[//000000002]: # (Generated from file 'websocket.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (websocket(n) 1.3.1 tcllib "websocket client and server")
# NAME
websocket - Tcl implementation of the websocket protocol
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Callbacks](#section2)
- [API](#section3)
- [Examples](#section4)
- [TLS Security Considerations](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Category](#category)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require http 2.7
package require logger
package require sha1
package require base64
package require websocket ?1.3.1?
[__::websocket::open__ *url* *handler* ?*options*?](#1)
[__::websocket::send__ *sock* *type* ?*msg*? ?*final*?](#2)
[__::websocket::server__ *sock*](#3)
[__::websocket::live__ *sock* *path* *cb* ?*proto*?](#4)
[__::websocket::test__ *srvSock* *cliSock* *path* ?*hdrs*? ?*qry*?](#5)
[__::websocket::upgrade__ *sock*](#6)
[__::websocket::takeover__ *sock* *handler* ?*server*?](#7)
[__::websocket::conninfo__ *sock* *what*](#8)
[__::websocket::find__ ?*host*? ?*port*?](#9)
[__::websocket::configure__ *sock* *args*](#10)
[__::websocket::loglevel__ ?*loglvl*?](#11)
[__::websocket::close__ *sock* ?*code*? ?*reason*?](#12)
# <a name='description'></a>DESCRIPTION
NOTE: THIS DOCUMENTATION IS WORK IN PROGRESS...
The websocket library is a pure Tcl implementation of the WebSocket
specification covering the needs of both clients and servers. Websockets provide
a way to upgrade a regular HTTP connection into a long-lived and continuous
binary or text communication between the client and the server. The library
offers a high-level interface to receive and send data as specified in RFC 6455
(v. 13 of the protocol), relieving callers from all necessary protocol framing
and reassembly. It implements the ping facility specified by the standard,
together with levers to control it. Pings are server-driven and ensure the
liveness of the connection across home (NAT) networks. The library has a number
of introspection facilities to inquire about the current state of the
connection, but also to receive notifications of incoming pings, if necessary.
Finally, the library contains a number of helper procedures to facilitate the
upgrading handshaking in existing web servers.
Central to the library is the procedure __websocket::takeover__ that will take
over a regular socket and treat it as a WebSocket, thus performing all necessary
protocol framing, packetisation and reassembly in servers and clients. The
procedure also takes a handler, a command that will be called back each time a
(possibly reassembled) packet from the remote end is ready for delivery at the
original caller. While exported by the package, the command
__websocket::takeover__ is seldom called in applications, since the package
provides other commands that are specifically tuned for the needs of clients and
servers.
Typically, clients will open a connection to a remote server by providing a
WebSocket URL (*ws:* or *wss:* schemes) and the handler described above to the
command __websocket::open__. The opening procedure is a wrapper around the
latest http::geturl implementations: it arranges to keep the socket created
within the http library opened for reuse, but confiscates it from its (internal)
map of known sockets for its own use.
Servers will start by registering themselves through the command
__::websocket::server__ and a number of handlers for paths using the command
__::websocket::live__. Then for each incoming client connection, they should
test the incoming request to detect if it is an upgrade request using
__::websocket::test__ and perform the final handshake to place the socket
connection under the control of the websocket library and its central procedure
using __::websocket::upgrade__.
Apart from these main commands, the package provides a number of commands for
introspection and basic operations on the websockets that it has under its
control. As WebSockets connections are long-lived, most remaining communication
with the library will be by way of callbacks, i.e. commands that are triggered
whenever important events within the library have occur, but mostly whenever
data has been received on a WebSocket.
# <a name='section2'></a>Callbacks
A number of commands of the library take a handler handler command as an
argument, a command which will be called back upon reception of data, but also
upon important events within the library or events resulting from control
messages sent by the remote end. For each callback being performed, the
following arguments will be appended:
- *sock*
The identifier of the WebSocket, as returned for example by
__::websocket::open__
- *type*
A textual type describing the event or message content, can be one of the
following
* __text__
Complete text message
* __binary__
Complete binary message
* __ping__
Incoming ping message
* __connect__
Notification of successful connection to server
* __disconnect__
Disconnection from remote end
* __close__
Pending closure of connection
- *msg*
Will contain the data of the message, whenever this is relevant, i.e. when
the *type* is __text__, __binary__ or __ping__ and whenever there is data
available.
# <a name='section3'></a>API
- <a name='1'></a>__::websocket::open__ *url* *handler* ?*options*?
This command is used in clients to open a WebSocket to a remote
websocket-enabled HTTP server. The URL provided as an argument in *url*
should start with ws: or wss:, which are the WebSockets counterpart of http:
and https:. The *handler* is a command that will be called back on data
reception or whenever important events occur during the life of the
websocket. __::websocket::open__ will return a socket which serves as both
the identifier of the websocket and of the physical low-level socket to the
server. This socket can be used in a number of other commands for
introspection or for controlling the behaviour of the library. Being
essentially a wrapper around the __::http::geturl__ command, this command
provides mostly the same set of dash-led options than __::http::geturl__.
Documented below are the options that differ from __::http::geturl__ and
which are specific to the WebSocket library.
* -headers
This option is supported, knowing that a number of headers will be
automatically added internally in the library in order to be able to
handshake the upgrading of the socket from a regular HTTP socket to a
WebSocket with the server.
* -validate
This option is not supported as it has no real point for WebSockets.
* -handler
This option is used internally by the websocket library and cannot be
used.
* -command
This option is used internally by the websocket library and cannot be
used.
* -protocol
This option specifies a list of application protocols to handshake with
the server. This protocols might help the server triggering application
specific features.
* -timeout
This option is supported, but will implemented as part of the library to
enable a number of finalising cleanups.
- <a name='2'></a>__::websocket::send__ *sock* *type* ?*msg*? ?*final*?
This command will send a fragment or a control message to the remote end of
the WebSocket identified by *sock*. The type of the message specified in
*type* can either be an integer according to the specification or
(preferrably) one of the following case insensitive strings: "text",
"binary" or "ping". The content of the message to send to the remote end is
contained in *msg* and message fragmentation is made possible by the setting
the argument *final* to non-true, knowing that the type of each fragment has
then to be the same. The command returns the number of bytes that were
effectively sent, or -1 on errors. Serious errors, such as when *sock* does
not identify a known WebSocket or when the connection is not stable yet will
generate errors that must be catched.
- <a name='3'></a>__::websocket::server__ *sock*
This command registers the (accept) socket *sock* as the identifier fo an
HTTP server that is capable of doing WebSockets. Paths onto which this
server will listen for incoming connections should be declared using
__::websocket::live__.
- <a name='4'></a>__::websocket::live__ *sock* *path* *cb* ?*proto*?
This procedure registers callbacks that will be performed on a WebSocket
compliant server registered with __::websocket::server__ whenever a client
connects to a matching path and protocol. *sock* is the listening socket of
the websocket compliant server declared using __::websocket::server__.
*path* is a glob-style path to match in client request, whenever this will
occur. *cb* is the command to callback (see Callbacks). *proto* is a
glob-style protocol name matcher.
- <a name='5'></a>__::websocket::test__ *srvSock* *cliSock* *path* ?*hdrs*? ?*qry*?
This procedure will test if the connection from an incoming client on socket
*cliSock* and on the path *path* is the opening of a WebSocket stream within
a known server *srvSock*. The incoming request is not upgraded at once,
instead a (temporary) context for the incoming connection is created. This
allows server code to perform a number of actions, if necessary, before the
WebSocket stream connection goes live. The text is made by analysing the
content of the headers *hdrs* which should contain a dictionary list of the
HTTP headers of the incoming client connection. The command will return
__1__ if this is an incoming WebSocket upgrade request and __0__ otherwise.
- <a name='6'></a>__::websocket::upgrade__ *sock*
Upgrade the socket *sock* that had been deemed by __::websocket::test__ to
be a WebSocket connection request to a true WebSocket as recognised by this
library. As a result, the necessary connection handshake will be sent to the
client, and the command will arrange for relevant callbacks to be made
during the life of the WebSocket, notably using the specifications described
by __::websocket::live__.
- <a name='7'></a>__::websocket::takeover__ *sock* *handler* ?*server*?
Take over the existing opened socket *sock* to implement sending and
receiving WebSocket framing on top of the socket. The procedure arranges for
*handler* to be called back whenever messages, control messages or other
important internal events are received or occured. *server* defaults to
__0__ and can be set to __1__ (or a boolean that evaluates to true) to
specify that this is a WebSocket within a server. Apart from specificities
in the protocol, servers should ping their clients at regular intervals in
order to keep the connection opened at all time. When *server* is set to
true, the library will arrange to send these pings automatically.
- <a name='8'></a>__::websocket::conninfo__ *sock* *what*
Provides callers with some introspection facilities in order to get some
semi-internal information about an existing websocket connection. Depending
on the value of the *what* argument, the procedure returns the following
piece of information:
* __peername__
Name (preferred) or IP of remote end.
* __sockname__
or __name__ Name or IP of local end.
* __closed__
__1__ if the connection is closed, __0__ otherwise
* __client__
__1__ if the connection is a client websocket, __0__ otherwise
* __server__
__1__ if the connection is a server websocket, __0__ otherwise
* __type__
__server__ if the connection is a server websocket, __client__
otherwise.
* __handler__
The handler command associated to the websocket
* __state__
The state of the websocket, which can be one of:
+ __CONNECTING__
Connection to remote end is in progress.
+ __CONNECTED__
Connection is connected to remote end.
+ __CLOSED__
Connection is closed.
- <a name='9'></a>__::websocket::find__ ?*host*? ?*port*?
Look among existing websocket connections for the ones that match the
hostname and port number filters passed as parameters. This lookup takes the
remote end into account and the *host* argument is matched both against the
hostname (whenever available) and the IP address of the remote end. Both the
*host* and *port* arguments are glob-style string matching filters and
default to __*__, i.e. will match any host and/or port number.
- <a name='10'></a>__::websocket::configure__ *sock* *args*
This command takes a number of dash-led options (and their values) to
configure the behaviour of an existing websocket connection. The recognised
options are the following (they can be shortened to the lowest common
denominator):
* __-keepalive__
is the number of seconds between each keepalive pings being sent along
the connection. A zero or negative number will effectively turn off the
feature. In servers, __-keepalive__ defaults to 30 seconds, and in
clients, no pings are initiated.
* __-ping__
is the text that is used during the automated pings. This text defaults
to the empty string, leading to an empty ping.
- <a name='11'></a>__::websocket::loglevel__ ?*loglvl*?
Set or query the log level of the library, which defaults to error. Logging
is built on top of the logger module, and the library makes use of the
following levels: __debug__, __info__, __notice__, __warn__ and __error__.
When called with no argument, this procedure will simply return the current
log level. Otherwise *loglvl* should contain the desired log level.
- <a name='12'></a>__::websocket::close__ *sock* ?*code*? ?*reason*?
Gracefully close a websocket that was directly or indirectly passed to
__::websocket::takeover__. The procedure will optionally send the *code* and
describing *reason* as part of the closure handshake. Good defaults are
provided, so that reasons for a number of known codes will be sent back.
Only the first 125 characters of a reason string will be kept and sent as
part of the handshake. The known codes are:
* __1000__
Normal closure (the default *code* when none provided).
* __1001__
Endpoint going away
* __1002__
Protocol Error
* __1003__
Received incompatible data type
* __1006__
Abnormal closure
* __1007__
Received data not consistent with type
* __1008__
Policy violation
* __1009__
Received message too big
* __1010__
Missing extension
* __1011__
Unexpected condition
* __1015__
TLS handshake error
# <a name='section4'></a>Examples
The following example opens a websocket connection to the echo service, waits
400ms to ensure that the connection is really established and sends a single
textual message which should be echoed back by the echo service. A real example
would probably use the __connect__ callback to know when connection to the
remote server has been establish and would only send data at that time.
package require websocket
::websocket::loglevel debug
proc handler { sock type msg } {
switch -glob -nocase -- $type {
co* {
puts "Connected on $sock"
}
te* {
puts "RECEIVED: $msg"
}
cl* -
dis* {
}
}
}
proc test { sock } {
puts "[::websocket::conninfo $sock type] from [::websocket::conninfo $sock sockname] to [::websocket::conninfo $sock peername]"
::websocket::send $sock text "Testing, testing..."
}
set sock [::websocket::open ws://echo.websocket.org/ handler]
after 400 test $sock
vwait forever
# <a name='section5'></a>TLS Security Considerations
This package uses the __[TLS](../../../../index.md#tls)__ package to handle the
security for __https__ urls and other socket connections.
Policy decisions like the set of protocols to support and what ciphers to use
are not the responsibility of __[TLS](../../../../index.md#tls)__, nor of this
package itself however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the set of
servers the application will talk to as well.
For example, in light of the recent [POODLE
attack](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)
discovered by Google many servers will disable support for the SSLv3 protocol.
To handle this change the applications using __[TLS](../../../../index.md#tls)__
must be patched, and not this package, nor __[TLS](../../../../index.md#tls)__
itself. Such a patch may be as simple as generally activating __tls1__ support,
as shown in the example below.
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *websocket* 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.
# <a name='see-also'></a>SEE ALSO
[http](../../../../index.md#http)
# <a name='keywords'></a>KEYWORDS
[http](../../../../index.md#http), [internet](../../../../index.md#internet),
[net](../../../../index.md#net), [rfc 6455](../../../../index.md#rfc_6455)
# <a name='category'></a>CATEGORY
Networking
|
Added embedded/md/tcllib/files/modules/wip/wip.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
|
[//000000001]: # (wip - Word Interpreter)
[//000000002]: # (Generated from file 'wip.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (wip(n) 2.2 tcllib "Word Interpreter")
# NAME
wip - Word Interpreter
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [GENERAL BEHAVIOUR](#section2)
- [CLASS API](#section3)
- [OBJECT API](#section4)
- [EXAMPLES](#section5)
- [Bugs, Ideas, Feedback](#section6)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require wip ?2.2?
package require snit ?1.3?
package require struct::set
[__::wip__ *wipName* *engine* *arg*...](#1)
[__def__ *name*](#2)
[__def__ *name* *method_prefix*](#3)
[__wipName__ *option* ?*arg arg ...*?](#4)
[__wip::dsl__ ?*suffix*?](#5)
[*wipName* __def__ *name* ?*method_prefix*?](#6)
[*wipName* __defl__ *names*](#7)
[*wipName* __defd__ *dict*](#8)
[*wipName* __deflva__ *name*...](#9)
[*wipName* __defdva__ (*name* *method_prefix*)...](#10)
[*wipName* __undefl__ *names*](#11)
[*wipName* __undefva__ *name*...](#12)
[*wipName* __unknown__ *cmdprefix*](#13)
[*wipName* __runl__ *wordlist*](#14)
[*wipName* __run__ *word*...](#15)
[*wipName* __run_next__](#16)
[*wipName* __run_next_while__ *acceptable*](#17)
[*wipName* __run_next_until__ *rejected*](#18)
[*wipName* __run_next_if__ *acceptable*](#19)
[*wipName* __run_next_ifnot__ *rejected*](#20)
[*wipName* __next__](#21)
[*wipName* __peek__](#22)
[*wipName* __peekall__](#23)
[*wipName* __insertl__ *at* *wordlist*](#24)
[*wipName* __replacel__ *wordlist*](#25)
[*wipName* __pushl__ *wordlist*](#26)
[*wipName* __addl__ *wordlist*](#27)
[*wipName* __insert__ *at* *word*...](#28)
[*wipName* __replace__ *word*...](#29)
[*wipName* __push__ *word*...](#30)
[*wipName* __add__ *word*...](#31)
# <a name='description'></a>DESCRIPTION
This package provides a micro interpreter for lists of words. Domain specific
languages based on this will have a bit of a Forth feel, with the input stream
segmented into words and any other structuring left to whatever the language
desired. Note that we have here in essence only the core dispatch loop, and no
actual commands whatsoever, making this definitely only a Forth feel and not an
actual Forth.
The idea is derived from Colin McCormack's __[treeql](../treeql/treeql.md)__
processor, modified to require less boiler plate within the command
implementations, at the expense of, likely, execution speed. In addition the
interface between processor core and commands is more complex too.
# <a name='section2'></a>GENERAL BEHAVIOUR
Word interpreters have a mappping from the names of the language commands they
shall recognize to the methods in the engine to invoke for them, and possibly
fixed arguments for these methods. This mapping is largely static, however it is
possible to change it during the execution of a word list (= program).
At the time a language command is defined the word interpreter will use
__[snit](../snit/snit.md)__'s introspection capabilities to determine the number
of arguments expected by the method of the egnine, and together with the number
of fixed arguments supplied in the method prefix of the mapping it then knows
how many arguments the language command is expecting. This is the command's
*arity*. Variable-argument methods (i.e. with the last argument named *args*)
are *not* allowed and will cause the word interpreter to throw an error at
definition time.
Note that while I said __[snit](../snit/snit.md)__'s abilities the engine object
can be written in any way, as long as it understands the method __info args__,
which takes a method name and returns the list of arguments for that method.
When executing a list of words (aka program) the first word is always taken as
the name of a language command, and the next words as its arguments, per the
*arity* of the command. Command and argument words are removed from the list and
then associated method of the engine is executed with the argument words. The
process then repeats using the then-first word of the list.
Note that the methods implementing the language commands may have full access to
the list of words and are allowed to manipulate as they see fit.
1. This means, for example, that while we cannot specify variable-argument
methods directly they can consume words after their fixed arguments before
returning to the execution loop. This may be under the control of their
fixed arguments.
1. Another possibility is the use of method __run_next__ and its variants to
execute commands coming after the current command, changing the order of
execution.
1. Execution can be further changed by use of the program accessor methods
which allow a command implementation to modify the remaining list of words
(insert, replace, prepend, append words) without executing them
immediately.
1. At last the basic __run__ methods save and restore an existing list of
words when used, enabling recursive use from within command
implementations.
# <a name='section3'></a>CLASS API
The main command of the package is:
- <a name='1'></a>__::wip__ *wipName* *engine* *arg*...
The command creates a new word interpreter object with an associated global
Tcl command whose name is *wipName*. If however the string __%AUTO%__ was
used as object name the package will generate its own unique name for the
object.
The *engine* is the object the word interpreter will dispatch all recognized
commands to, and the *arg*uments are a word list which defines an initial
mapping from language words to engine methods.
The recognized language of this word list is
* <a name='2'></a>__def__ *name*
Defines *name* as command of the language, to be mapped to a method of
the *engine* having the same name.
* <a name='3'></a>__def__ *name* *method_prefix*
Defines *name* as command of the language, to be mapped to the method of
the *engine* named in the *method_prefix*.
The returned command may be used to invoke various operations on the object.
It has the following general form:
* <a name='4'></a>__wipName__ *option* ?*arg arg ...*?
*Option* and the *arg*s determine the exact behavior of the command.
The package additionally exports the command:
- <a name='5'></a>__wip::dsl__ ?*suffix*?
This command is for use within snit types which wish to use one or more wip
interpreters as a component. Use within the type definition installs most of
the boilerplate needed to setup and use a word interpreter.
It installs a component named *wip*, and a method __wip_setup__ for
initializing it. This method has to be called from within the constructor of
the type using the word interpreter. If further installs a series of
procedures which make the object API of the word interpreter directly
available to the type's methods, without having to specify the component.
*Note* that this does and cannot install the language to interpret, i.e. the
mapping from words to engine methods.
It is possible to instantiate multiple word interpreter components within a
type by using different suffices as arguments to the command. In that case
the name of the component changes to 'wip___$suffix__', the setup command
becomes 'wip___$suffix___setup' and all the procedures also get the suffix
'___$suffix__'.
# <a name='section4'></a>OBJECT API
The following commands are possible for word interpreter objects:
- <a name='6'></a>*wipName* __def__ *name* ?*method_prefix*?
Defines a language command *name* and maps it to the method named in the
engine's *method_prefix*. If the *method_prefix* name is not specified it is
simply the name of the language command.
- <a name='7'></a>*wipName* __defl__ *names*
Defines a series of language commands, specified through the list of
*names*, all of which are mapped to engine methods of the same name.
- <a name='8'></a>*wipName* __defd__ *dict*
Defines a series of language commands, specified through the dictionary
*dict* of names and method prefixes.
- <a name='9'></a>*wipName* __deflva__ *name*...
As method __defl__, however the list of names is specified through multiple
arguments.
- <a name='10'></a>*wipName* __defdva__ (*name* *method_prefix*)...
As method __defd__, however the dictionary of names and method prefixes is
specified through multiple arguments.
- <a name='11'></a>*wipName* __undefl__ *names*
Removes the named series of language commands from the mapping.
- <a name='12'></a>*wipName* __undefva__ *name*...
As method __undefl__, however the list of names is specified through
multiple arguments.
- <a name='13'></a>*wipName* __unknown__ *cmdprefix*
Sets the handler for unknown words to *cmdprefix*. This command prefix takes
one argument, the current word, and either throws some error, or returns the
result of executing the word, as defined by the handler. The default handler
simply throws an error.
- <a name='14'></a>*wipName* __runl__ *wordlist*
Treats the list of words in *wordlist* as a program and executes the
contained command one by one. The result of the command executed last is
returned as the result of this command.
The *wordlist* is stored in the object for access by the other
*run*-methods, and the general program accessor methods (see below). A
previously stored wordlist is saved during the execution of this method and
restored before it returns. This enables the recursive execution of word
lists within word lists.
- <a name='15'></a>*wipName* __run__ *word*...
As method __runl__, however the list of words to execute is specified
through multiple arguments.
- <a name='16'></a>*wipName* __run_next__
Low-level method. Determines the next word in the list of words, and its
arguments, and then executes it. The result of the executed word is the
result of this method.
Exposed for use within command implementations. The methods __run__ and
__runl__ use it to execute words until their word list is exhausted.
- <a name='17'></a>*wipName* __run_next_while__ *acceptable*
Low-level method. Invokes the method __run_next__ as long as the next word
is in the set of *acceptable* words, and the program is not empty. The
result of the command executed last is returned as the result of this
command.
Exposed for use within command implementations to change the order of
execution.
- <a name='18'></a>*wipName* __run_next_until__ *rejected*
Low-level method. Invokes the method __run_next__ until the next word is in
the set of *rejected* words, and the program is not empty. The result of the
command executed last is returned as the result of this command.
Exposed for use within command implementations to change the order of
execution.
- <a name='19'></a>*wipName* __run_next_if__ *acceptable*
Low-level method. Invokes the method __run_next__ if the next word is in the
set of *acceptable* words, and the program is not empty. The result of the
command executed last is returned as the result of this command.
Exposed for use within command implementations to change the order of
execution.
- <a name='20'></a>*wipName* __run_next_ifnot__ *rejected*
Low-level method. Invokes the method __run_next__ if the next word is not in
the set of *rejected* words, and the program is not empty. The result of the
command executed last is returned as the result of this command.
Exposed for use within command implementations to change the order of
execution.
- <a name='21'></a>*wipName* __next__
Returns the next word in the programm. The word is also removed.
- <a name='22'></a>*wipName* __peek__
Returns the next word in the programm without removing it
- <a name='23'></a>*wipName* __peekall__
Returns the remaining programm in toto.
- <a name='24'></a>*wipName* __insertl__ *at* *wordlist*
Basic programm accessor method. Inserts the specified *wordlist* into the
program, just before the word at position *at*. Positions are counted from
__zero__.
- <a name='25'></a>*wipName* __replacel__ *wordlist*
Basic programm accessor method. Replaces the whole stored program with the
specified *wordlist*.
- <a name='26'></a>*wipName* __pushl__ *wordlist*
Program accessor method. The specified *wordlist* is added to the front of
the remaining program. Equivalent to
$wip insertl 0 $wordlist
- <a name='27'></a>*wipName* __addl__ *wordlist*
Program accessor method. The specified *wordlist* is appended at the end of
the remaining program. Equivalent to
$wip insertl end $wordlist
- <a name='28'></a>*wipName* __insert__ *at* *word*...
Like method __insertl__, except the words are specified through multiple
arguments.
- <a name='29'></a>*wipName* __replace__ *word*...
Like method __setl__, except the words are specified through multiple
arguments.
- <a name='30'></a>*wipName* __push__ *word*...
Like method __pushl__, except the words are specified through multiple
arguments.
- <a name='31'></a>*wipName* __add__ *word*...
Like method __addl__, except the words are specified through multiple
arguments.
# <a name='section5'></a>EXAMPLES
No examples yet.
# <a name='section6'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *wip* 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.
# <a name='keywords'></a>KEYWORDS
[interpreter](../../../../index.md#interpreter),
[list](../../../../index.md#list), [word](../../../../index.md#word)
# <a name='category'></a>CATEGORY
Programming tools
# <a name='copyright'></a>COPYRIGHT
Copyright © 2007-2010 Andreas Kupries <[email protected]>
|
Added embedded/md/tcllib/files/modules/yaml/huddle.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
|
[//000000001]: # (huddle - HUDDLE)
[//000000002]: # (Generated from file 'huddle.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (huddle(n) 0.3 tcllib "HUDDLE")
# NAME
huddle - Create and manipulate huddle object
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [TYPE CALLBACK](#section3)
- [How to add type](#section4)
- [WORKING SAMPLE](#section5)
- [LIMITATIONS](#section6)
- [Bugs, Ideas, Feedback](#section7)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require huddle ?0.3?
[__huddle create__ *key* *value* ?*key value ...*?](#1)
[__huddle list__ ?*value value ...*?](#2)
[__huddle number__ *number*](#3)
[__huddle string__ *string*](#4)
[__huddle boolean__ *expression to evaluate as true or false*](#5)
[__huddle true__](#6)
[__huddle false__](#7)
[__huddle null__](#8)
[__huddle get__ *object* *key* ?*key ...*?](#9)
[__huddle gets__ *object* *key* ?*key ...*?](#10)
[__huddle set__ *objectVar* *key* ?*key ...*? *value*](#11)
[__huddle remove__ *object* *key* ?*key ...*?](#12)
[__huddle combine__ *object1* *object2* ?*object3 ...*?](#13)
[__huddle equal__ *object1* *object2*](#14)
[__huddle append__ *objectVar* *key* *value* ?*key value ...*?](#15)
[__huddle append__ *objectVar* *value* ?*value ...*?](#16)
[__huddle keys__ *object*](#17)
[__huddle llength__ *object*](#18)
[__huddle type__ *object* ?*key key...*?](#19)
[__huddle strip__ *object*](#20)
[__huddle jsondump__ *object* ?*offset*? ?*newline*? ?*begin_offset*?](#21)
[__huddle compile__ *spec* *data*](#22)
[__huddle isHuddle__ *object*](#23)
[__huddle checkHuddle__ *object*](#24)
[__huddle to_node__ *object* ?*tag*?](#25)
[__huddle wrap__ *tag* *src*](#26)
[__huddle call__ *tag* *command* *args*](#27)
[__huddle addType__ *callback*](#28)
[__[callback](../../../../index.md#callback)__ *command* ?*args*?](#29)
[__setting__](#30)
[__get_sub__ *src* *key*](#31)
[__strip__ *src*](#32)
[__[set](../../../../index.md#set)__ *src* *key* *value*](#33)
[__[remove](../../../../index.md#remove)__ *src* *key* *value*](#34)
# <a name='description'></a>DESCRIPTION
Huddle provides a generic Tcl-based serialization/intermediary format.
Currently, each node is wrapped in a tag with simple type information.
When converting huddle-notation to other serialization formats like JSON or YAML
this type information is used to select the proper notation. And when going from
JSON/YAML/... to huddle their notation can be used to select the proper huddle
type.
In that manner huddle can serve as a common intermediary format.
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](../../../../index.md#dict)__. Either the
__[dict](../../../../index.md#dict)__ package or Tcl 8.5 is required for use.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__huddle create__ *key* *value* ?*key value ...*?
Create a huddle object as a dict. It can contain other huddle objects.
- <a name='2'></a>__huddle list__ ?*value value ...*?
Create a huddle object as a list. It can contain other huddle objects.
- <a name='3'></a>__huddle number__ *number*
Create a huddle object as a number.
- <a name='4'></a>__huddle string__ *string*
Create a huddle object as a string.
- <a name='5'></a>__huddle boolean__ *expression to evaluate as true or false*
Create a huddle object as a boolean evaluating an expression as true or
false-
- <a name='6'></a>__huddle true__
Create a huddle object as a boolean true.
- <a name='7'></a>__huddle false__
Create a huddle object as a boolean false.
- <a name='8'></a>__huddle null__
Create a huddle object as a null.
- <a name='9'></a>__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.
- <a name='10'></a>__huddle gets__ *object* *key* ?*key ...*?
Get a sub-object from the huddle object, stripped.
- <a name='11'></a>__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.
- <a name='12'></a>__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.
- <a name='13'></a>__huddle combine__ *object1* *object2* ?*object3 ...*?
Merging huddle objects given.
% 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}}}
- <a name='14'></a>__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
- <a name='15'></a>__huddle append__ *objectVar* *key* *value* ?*key value ...*?
- <a name='16'></a>__huddle append__ *objectVar* *value* ?*value ...*?
Appending child elements. When for dicts, giving key/value. When for lists,
giving values.
% 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}}}
- <a name='17'></a>__huddle keys__ *object*
The same as __dict keys__.
- <a name='18'></a>__huddle llength__ *object*
The same as __llength__.
- <a name='19'></a>__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
- <a name='20'></a>__huddle strip__ *object*
Stripped all tags. Converted to normal Tcl's list/dict.
- <a name='21'></a>__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"}}
- <a name='22'></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}}}}}}}
- <a name='23'></a>__huddle isHuddle__ *object*
if *object* is a huddle, returns 1. the other, returns 0.
- <a name='24'></a>__huddle checkHuddle__ *object*
if *object* is not a huddle, rises an error.
- <a name='25'></a>__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}
- <a name='26'></a>__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}
- <a name='27'></a>__huddle call__ *tag* *command* *args*
for type-callbacks.
devolving *command* to default *tag*-callback
- <a name='28'></a>__huddle addType__ *callback*
add a user-specified-type/tag to the huddle library. To see "Additional
Type".
* __callback__
callback function name for additional type.
# <a name='section3'></a>TYPE CALLBACK
The definition of callback for user-type.
- <a name='29'></a>__[callback](../../../../index.md#callback)__ *command* ?*args*?
* __command__
huddle subcomand which is needed to reply by the callback.
* __args__
arguments of subcommand. The number of list of arguments is different
for each subcommand.
The callback procedure shuould reply the following subcommands.
- <a name='30'></a>__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".
- <a name='31'></a>__get_sub__ *src* *key*
returns a sub node specified by *key*.
* __src__
a node content in huddle object.
- <a name='32'></a>__strip__ *src*
returns stripped node contents. if the type has child nodes, every node must
be stripped.
- <a name='33'></a>__[set](../../../../index.md#set)__ *src* *key* *value*
sets a sub-node from the tagged-content, and returns self.
- <a name='34'></a>__[remove](../../../../index.md#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.
# 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
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]
}
}
}
# <a name='section4'></a>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
# <a name='section5'></a>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"
]
# <a name='section6'></a>LIMITATIONS
now printing.
# <a name='section7'></a>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.
# <a name='see-also'></a>SEE ALSO
[yaml](yaml.md)
# <a name='keywords'></a>KEYWORDS
[data exchange](../../../../index.md#data_exchange), [exchange
format](../../../../index.md#exchange_format),
[huddle](../../../../index.md#huddle), [json](../../../../index.md#json),
[parsing](../../../../index.md#parsing), [text
processing](../../../../index.md#text_processing),
[yaml](../../../../index.md#yaml)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008-2011 KATO Kanryu <[email protected]>
Copyright © 2015 Miguel MartÃnez López <[email protected]>
|
Added embedded/md/tcllib/files/modules/yaml/yaml.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
[//000000001]: # (yaml - YAML processing)
[//000000002]: # (Generated from file 'yaml.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (yaml(n) 0.4.1 tcllib "YAML processing")
# NAME
yaml - YAML Format Encoder/Decoder
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [COMMANDS](#section2)
- [EXAMPLES](#section3)
- [LIMITATIONS](#section4)
- [Bugs, Ideas, Feedback](#section5)
- [See Also](#see-also)
- [Keywords](#keywords)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require yaml ?0.4.1?
[__::yaml::yaml2dict__ ?*options*? *txt*](#1)
[__::yaml::yaml2huddle__ ?*options*? *txt*](#2)
[__::yaml::setOption__ ?*options*?](#3)
[__::yaml::dict2yaml__ *dict* ?*indent*? ?*wordwrap*?](#4)
[__::yaml::list2yaml__ *list* ?*indent*? ?*wordwrap*?](#5)
[__::yaml::huddle2yaml__ *huddle* ?*indent*? ?*wordwrap*?](#6)
# <a name='description'></a>DESCRIPTION
The __yaml__ package provides a simple Tcl-only library for parsing the YAML
[http://www.yaml.org/](http://www.yaml.org/) data exchange format as specified
in [http://www.yaml.org/spec/1.1/](http://www.yaml.org/spec/1.1/).
The __yaml__ package returns data as a Tcl
__[dict](../../../../index.md#dict)__. Either the
__[dict](../../../../index.md#dict)__ package or Tcl 8.5 is required for use.
# <a name='section2'></a>COMMANDS
- <a name='1'></a>__::yaml::yaml2dict__ ?*options*? *txt*
- <a name='2'></a>__::yaml::yaml2huddle__ ?*options*? *txt*
Parse yaml formatted text *txt* into a Tcl dict/huddle and return the value.
* ____-file____
*txt* is a filename of YAML-stream.
* ____-stream____
*txt* is just a YAML-stream.
* ____-types__ *list*__
The *list* is a type list for the yaml-scalar types.(e.g. !!str
!!timestamp !!integer !!true ...)
-types {timestamp integer null true false}
In this case, if a string matched "timestamp", converted to the TCL
internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183)
* ____-m:true__ *param*__
The *param* is two elements of list for the value of true, and
considered strings.
-m:true {1 {true on + yes y}}
In this case, the string "yes" found in YAML Stream, automatically
converted 1.
* ____-m:false__ *param*__
The *param* is two elements of list for the value of false, and
considered strings.
-m:false {0 {false off - no n}}
* ____-m:null__ *param*__
The *param* is two elements of list for the value of null, and
considered strings.
-m:null {"" {null nil "" ~}}
* ____-validate____
Experiment,old: Output stream contains YAML's-tag, each node.
% puts [::yaml::load -validate {[aaa, bbb]}]
=>
!!seq {{!!str aaa} {!!str bbb}}
- <a name='3'></a>__::yaml::setOption__ ?*options*?
Change implicit options for the library. Now, the params are the same as
__::yaml::yaml2dict__. Arguments of__::yaml::yaml2dict__ is more priority
than this setting.
- <a name='4'></a>__::yaml::dict2yaml__ *dict* ?*indent*? ?*wordwrap*?
- <a name='5'></a>__::yaml::list2yaml__ *list* ?*indent*? ?*wordwrap*?
- <a name='6'></a>__::yaml::huddle2yaml__ *huddle* ?*indent*? ?*wordwrap*?
Convert a dict/list/huddle object into YAML stream.
* indent
spaces indent of each block node. currently default is 2.
* wordwrap
word wrap for YAML stream. currently default is 40.
# <a name='section3'></a>EXAMPLES
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.}
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}}
# <a name='section4'></a>LIMITATIONS
tag parser not implemented. currentry, tags are merely ignored.
Only Anchor => Aliases ordering. back alias-referring is not supported.
Too many braces, or too few braces.
Not enough character set of line feeds. Please use only "\n" as line breaks.
# <a name='section5'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *yaml* 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.
# <a name='see-also'></a>SEE ALSO
[base64](../base64/base64.md), [huddle](huddle.md), [json](../json/json.md)
# <a name='keywords'></a>KEYWORDS
[data exchange](../../../../index.md#data_exchange),
[huddle](../../../../index.md#huddle), [parsing](../../../../index.md#parsing),
[text processing](../../../../index.md#text_processing),
[yaml](../../../../index.md#yaml)
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008 KATO Kanryu <[email protected]>
|
Added embedded/md/tcllib/files/modules/zip/decode.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
[//000000001]: # (zipfile::decode - Zip archive handling)
[//000000002]: # (Generated from file 'decode.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (zipfile::decode(n) 0.7.1 tcllib "Zip archive handling")
# NAME
zipfile::decode - Access to zip archives
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require fileutil::magic::mimetype
package require fileutil::decode 0.2.1
package require Trf
package require zlibtcl
package require zipfile::decode ?0.7.1?
[__::zipfile::decode::archive__](#1)
[__::zipfile::decode::close__](#2)
[__::zipfile::decode::comment__ *adict*](#3)
[__::zipfile::decode::content__ *archive*](#4)
[__::zipfile::decode::copyfile__ *adict* *path* *dst*](#5)
[__::zipfile::decode::files__ *adict*](#6)
[__::zipfile::decode::getfile__ *zdict* *path*](#7)
[__::zipfile::decode::hasfile__ *adict* *path*](#8)
[__::zipfile::decode::iszip__ *archive*](#9)
[__::zipfile::decode::open__ *archive*](#10)
[__::zipfile::decode::unzip__ *adict* *dstdir*](#11)
[__::zipfile::decode::unzipfile__ *archive* *dstdir*](#12)
# <a name='description'></a>DESCRIPTION
This package provides commands to decompress and access the contents of zip
archives.
# <a name='section2'></a>API
- <a name='1'></a>__::zipfile::decode::archive__
This command decodes the last opened (and not yet closed) zip archive file.
The result of the command is a dictionary describing the contents of the
archive. The structure of this dictionary is not public. Proper access
should be made through the provided accessor command of this package.
- <a name='2'></a>__::zipfile::decode::close__
This command releases all state associated with the last call of
__::zipfile::decode::open__. The result of the command is the empty string.
- <a name='3'></a>__::zipfile::decode::comment__ *adict*
This command takes a dictionary describing the currently open zip archive
file, as returned by __::zipfile::decode::archive__, and returns the global
comment of the archive.
- <a name='4'></a>__::zipfile::decode::content__ *archive*
This is a convenience command which decodes the specified zip *archive* file
and returns the list of paths found in it as its result.
- <a name='5'></a>__::zipfile::decode::copyfile__ *adict* *path* *dst*
This command takes a dictionary describing the currently open zip archive
file, as returned by __::zipfile::decode::archive__, and copies the
decompressed contents of the file *path* in the archive to the the file
*dst*. An error is thrown if the file is not found in the archive.
- <a name='6'></a>__::zipfile::decode::files__ *adict*
This command takes a dictionary describing the currently open zip archive
file, as returned by __::zipfile::decode::archive__, and returns the list of
files found in the archive.
- <a name='7'></a>__::zipfile::decode::getfile__ *zdict* *path*
This command takes a dictionary describing the currently open zip archive
file, as returned by __::zipfile::decode::archive__, and returns the
decompressed contents of the file *path* in the archive. An error is thrown
if the file is not found in the archive.
- <a name='8'></a>__::zipfile::decode::hasfile__ *adict* *path*
This command takes a dictionary describing the currently open zip archive
file, as returned by __::zipfile::decode::archive__, and check if the
specified *path* is found in the archive. The result of the command is a
boolean flag, __true__ if the path is found, and __false__ otherwise.
- <a name='9'></a>__::zipfile::decode::iszip__ *archive*
This command takes the path of a presumed zip *archive* file and returns a
boolean flag as the result of the command telling us if it actually is a zip
archive (__true__), or not (__false__).
- <a name='10'></a>__::zipfile::decode::open__ *archive*
This command takes the path of a zip *archive* file and prepares it for
decoding. The result of the command is the empty string. All important
information is stored in global state. If multiple open calls are made one
after the other only the state of the last call is available to the other
commands.
- <a name='11'></a>__::zipfile::decode::unzip__ *adict* *dstdir*
This command takes a dictionary describing the currently open zip archive
file, as returned by __::zipfile::decode::archive__, and unpacks the archive
in the given destination directory *dstdir*. The result of the command is
the empty string.
- <a name='12'></a>__::zipfile::decode::unzipfile__ *archive* *dstdir*
This is a convenience command which unpacks the specified zip *archive* file
in the given destination directory *dstdir*.
The result of the command is the empty string.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *zipfile* 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.
# <a name='keywords'></a>KEYWORDS
[decompression](../../../../index.md#decompression),
[zip](../../../../index.md#zip)
# <a name='category'></a>CATEGORY
File
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008-2016 Andreas Kupries
|
Added embedded/md/tcllib/files/modules/zip/encode.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
[//000000001]: # (zipfile::encode - Zip archive handling)
[//000000002]: # (Generated from file 'encode.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (zipfile::encode(n) 0.4 tcllib "Zip archive handling")
# NAME
zipfile::encode - Generation of zip archives
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [Class API](#section2)
- [Instance API](#section3)
- [Bugs, Ideas, Feedback](#section4)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.4
package require logger
package require Trf
package require crc32
package require snit
package require zlibtcl
package require fileutil
package require zipfile::encode ?0.4?
[__::zipfile::encode__ ?*objectName*?](#1)
[__<encoder>__ __comment:__ *text*](#2)
[__<encoder>__ __file:__ *dst* *owned* *src* ?*noCompress*?](#3)
[__<encoder>__ __write__ *archive*](#4)
# <a name='description'></a>DESCRIPTION
This package provides a class for the generation of zip archives.
# <a name='section2'></a>Class API
- <a name='1'></a>__::zipfile::encode__ ?*objectName*?
The class command constructs encoder instances, i.e. objects. The result of
the command is the fully-qualified name of the instance command.
If no *objectName* is specified the class will generate and use an automatic
name. If the *objectName* was specified, but is not fully qualified the
command will be created in the current namespace.
# <a name='section3'></a>Instance API
- <a name='2'></a>__<encoder>__ __comment:__ *text*
This method specifies the text of the global comment for the archive. The
result of the method is the empty string. In case of multiple calls to this
method for the same encoder the data from the last call prevails over all
previous texts.
- <a name='3'></a>__<encoder>__ __file:__ *dst* *owned* *src* ?*noCompress*?
This method adds a new file to the archive. The contents of the file are
found in the filesystem at *src*, and will be stored in the archive under
path *dst*. If the file is declared as *owned* by the archive the original
file will be deleted when the archive is constructed and written. If
*noCompress* is set to __true__ the file will not be compressed on writing.
Otherwise (the default) the file is compressed if it is advantageous. The
result of the method is an empty string.
- <a name='4'></a>__<encoder>__ __write__ *archive*
This method takes the global comment and all added files, encodes them as a
zip archive and stores the result at path *archive* in the filesystem. All
added files which were owned by the archive are deleted at this point. On
the issue of ordering, the files are added to the archive in the same order
as they were specified via __file:__. *Note* that this behaviour is new for
version 0.4 and higher. Before 0.4 no specific order was documented. It was
lexicographically sorted. The change was made to support
__[zip](../../../../index.md#zip)__-based file formats which require a
specific order of files in the archive, for example ".epub".
# <a name='section4'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *zipfile* 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.
# <a name='keywords'></a>KEYWORDS
[compression](../../../../index.md#compression), [zip](../../../../index.md#zip)
# <a name='category'></a>CATEGORY
File
# <a name='copyright'></a>COPYRIGHT
Copyright © 2008-2009 Andreas Kupries
|
Added embedded/md/tcllib/files/modules/zip/mkzip.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
[//000000001]: # (zipfile::mkzip - Zip archive creation)
[//000000002]: # (Generated from file 'mkzip.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (zipfile::mkzip(n) 1.2 tcllib "Zip archive creation")
# NAME
zipfile::mkzip - Build a zip archive
# <a name='toc'></a>Table Of Contents
- [Table Of Contents](#toc)
- [Synopsis](#synopsis)
- [Description](#section1)
- [API](#section2)
- [Bugs, Ideas, Feedback](#section3)
- [Keywords](#keywords)
- [Category](#category)
- [Copyright](#copyright)
# <a name='synopsis'></a>SYNOPSIS
package require Tcl 8.6
package require zipfile::mkzip ?1.2?
[__::zipfile::mkzip::mkzip__ *zipfile* ?__-zipkit__? ?__-runtime__ *prefix*? ?__-comment__ *string*? ?__-directory__ *rootpath*? ?__-exclude__ *exclude*? ?__--__? ?*path*...?](#1)
# <a name='description'></a>DESCRIPTION
This package utilizes the zlib functions in Tcl 8.6 to build zip archives.
# <a name='section2'></a>API
- <a name='1'></a>__::zipfile::mkzip::mkzip__ *zipfile* ?__-zipkit__? ?__-runtime__ *prefix*? ?__-comment__ *string*? ?__-directory__ *rootpath*? ?__-exclude__ *exclude*? ?__--__? ?*path*...?
From [http://wiki.tcl.tk/15158](http://wiki.tcl.tk/15158)
This command constructs a zip archive from a directory tree using nothing
but Tcl 8.6 core features. The resulting zip file should be compatible with
other __[zip](../../../../index.md#zip)__ programs - with the possible
exception of unicode support. The files generated by this command use utf-8
encoding for all filenames and comments and it has been noticed particularly
on Windows the __info-zip__ and the Windows built-in zip view have rather
poor support for this part of the ZIP file specification. The __7-Zip__
program does correctly display utf8 filenames however and the __vfs::zip__
package will use these of course.
If you use
__::mkzip::mkzip__ mystuff.tm -zipkit -directory mystuff.vfs
it will pack your "mystuff.vfs/" virtual filesystem tree into a zip archive
with a suitable header such that on unix you may mark it executable and it
should run with tclkit. Or you can run it with __tclsh__ or __wish__ 8.6 if
you like.
To change the executable header, specify the __-runtime__ "preface" where
preface is a file containing code you want prefixed. For instance, on
Windows you can create a self-extracting zip archive using
mkzip mystuff.exe -directory mystuff.vfs -runtime unzipsfx.exe
The "unzipsfx.exe" is the Info-Zip self-extracting stub.
Accepted options:
* __-runtime__ path
This option specifies a file to use as prefix to the actual zip archive.
If specified __-zipkit__ will be ignored.
* __-zipkit__
Instructs the command to generate a prefix which makes the archive a
zip-based starkit. Ignored if __-runtime__ is present.
* __-comment__ string
This options specifies a global comment to place into the generated
archive.
* __-directory__ path
This option specifies the directory to place into the generated archive.
If specified any argument *path*s are *ignored*.
* __-exclude__ list
This option specifies a list of glob patterns. All paths matching at
least one of the patterns are not placed into the generated archive.
This option defaults to
CVS/* */CVS/* *~ ".#*" "*/.#*"
* __--__
This option signals the end of the options, forcing processing of all
further words as arguments, even if they begin with a dash character.
Accepted arguments:
* path *path*
Each path is a directory or file to place into the generated archive.
Note however that these will be ignored when option __-directory__ is
specified.
# <a name='section3'></a>Bugs, Ideas, Feedback
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category *zipfile* 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.
# <a name='keywords'></a>KEYWORDS
[decompression](../../../../index.md#decompression),
[zip](../../../../index.md#zip)
# <a name='category'></a>CATEGORY
File
# <a name='copyright'></a>COPYRIGHT
Copyright © 2009 Pat Thoyts
|
Added embedded/md/tcllib/toc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
|
[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown')
# Table Of Contents -- tcllib
- [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher
- [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data
- [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder
- [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication
- [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding
- [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps
- [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding
- [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data
- [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder
- [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites
- [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results
- [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV
- [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text
- [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction
- [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction
- [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification
- [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files
- [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher
- [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache
- [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum
- [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times
- [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times
- [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options.
- [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later)
- [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol
- [control](tcllib/files/modules/control/control.md) Procedures for control flow structures.
- [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling
- [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness
- [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms
- [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check
- [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check
- [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands
- [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data.
- [debug](tcllib/files/modules/debug/debug.md) debug narrative - core
- [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller
- [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat
- [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping
- [defer](tcllib/files/modules/defer/defer.md) Defered execution
- [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods)
- [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures)
- [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers
- [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools
- [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client
- [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction
- [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference
- [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq
- [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction
- [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax
- [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference
- [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction
- [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities
- [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction
- [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference
- [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq
- [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction
- [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax
- [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference
- [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents
- [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices
- [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents
- [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format
- [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format
- [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins
- [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices
- [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices
- [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices
- [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin
- [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin
- [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin
- [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin
- [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin
- [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin
- [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices
- [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin
- [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin
- [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format
- [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities
- [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers
- [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C)
- [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE)
- [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN)
- [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR)
- [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C)
- [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE)
- [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN)
- [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR)
- [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins
- [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format
- [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents
- [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents
- [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents
- [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin
- [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin
- [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin
- [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin
- [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin
- [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin
- [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices
- [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin
- [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin
- [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format
- [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities
- [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction
- [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference
- [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq
- [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction
- [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax
- [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference
- [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor
- [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor
- [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities
- [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files
- [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files
- [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition
- [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl
- [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object
- [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather
- [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal
- [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol
- [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls
- [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation
- [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators.
- [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files
- [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl
- [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons
- [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors
- [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons
- [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons
- [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams
- [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation
- [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler
- [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams
- [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities
- [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs
- [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams
- [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams
- [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars
- [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars
- [hook](tcllib/files/modules/hook/hook.md) Hooks
- [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures
- [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings
- [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object
- [ident](tcllib/files/modules/ident/ident.md) Ident protocol client
- [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol
- [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files
- [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing
- [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface.
- [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures.
- [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data
- [json](tcllib/files/modules/json/json.md) JSON parser
- [json::write](tcllib/files/modules/json/json_write.md) JSON generation
- [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures
- [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation
- [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client
- [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface
- [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications.
- [logger](tcllib/files/modules/log/logger.md) System to control logging of events.
- [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger
- [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger
- [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service
- [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages
- [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem
- [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps
- [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines
- [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML
- [math](tcllib/files/modules/math/math.md) Tcl Math Library
- [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers
- [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers
- [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations
- [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration
- [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl
- [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library
- [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package
- [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants
- [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic
- [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic
- [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms
- [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers
- [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations
- [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines
- [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra
- [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory
- [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines
- [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis
- [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions
- [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions
- [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals
- [math::special](tcllib/files/modules/math/special.md) Special mathematical functions
- [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures
- [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions
- [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm
- [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm
- [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption
- [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts
- [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor
- [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets.
- [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client
- [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension
- [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions
- [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol
- [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server
- [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands
- [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values.
- [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications
- [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data
- [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application
- [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction
- [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application
- [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application
- [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol
- [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client
- [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature
- [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO
- [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO
- [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess
- [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords
- [page](tcllib/files/apps/page.md) Parser Generator
- [page_intro](tcllib/files/modules/page/page_intro.md) page introduction
- [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager
- [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility
- [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON
- [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG
- [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities
- [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities
- [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client.
- [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher
- [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin
- [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data
- [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol
- [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation
- [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d
- [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d
- [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module
- [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands
- [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler
- [pt](tcllib/files/apps/pt.md) Parser Tools Application
- [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization
- [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl
- [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA
- [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format
- [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification
- [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization
- [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities
- [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization
- [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage
- [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification
- [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export
- [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format
- [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format
- [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format
- [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format
- [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format
- [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format
- [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import
- [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format
- [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format
- [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format
- [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars
- [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format
- [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format
- [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format
- [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format
- [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format
- [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format
- [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial
- [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars
- [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator
- [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based
- [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX
- [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit
- [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo
- [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities
- [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API
- [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API
- [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools
- [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser
- [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API
- [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations
- [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher
- [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities
- [report](tcllib/files/modules/report/report.md) Create and manipulate report objects
- [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously
- [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm
- [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm
- [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface
- [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl
- [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl
- [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl
- [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl
- [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm
- [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm
- [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing
- [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations
- [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators
- [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol
- [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation
- [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl
- [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions
- [soundex](tcllib/files/modules/soundex/soundex.md) Soundex
- [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension.
- [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing
- [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line
- [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep
- [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal
- [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure
- [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects
- [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects
- [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects
- [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists
- [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects
- [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects
- [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items)
- [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects
- [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects
- [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures)
- [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets
- [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists
- [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects
- [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects
- [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects
- [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum
- [switched](tcllib/files/modules/stooop/switched.md) switch/option management.
- [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation
- [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel
- [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support
- [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels
- [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel
- [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel
- [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels
- [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2
- [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel
- [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel
- [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination
- [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel
- [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout
- [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel
- [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel
- [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage
- [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel
- [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels
- [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation
- [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation
- [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support
- [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation
- [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation
- [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation
- [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation
- [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input
- [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy
- [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad
- [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption
- [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal
- [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression
- [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers
- [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers
- [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor
- [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation
- [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters.
- [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
- [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual
- [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual
- [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual
- [term](tcllib/files/modules/term/term.md) General terminal control
- [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences
- [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences
- [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences
- [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences
- [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries
- [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals
- [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu
- [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging
- [term::receive](tcllib/files/modules/term/receive.md) General input from terminals
- [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals
- [term::send](tcllib/files/modules/term/term_send.md) General output to terminals
- [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings.
- [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs
- [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text.
- [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings.
- [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts
- [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings.
- [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings
- [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings
- [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message
- [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources
- [tie](tcllib/files/modules/tie/tie.md) Array persistence
- [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data
- [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server
- [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework
- [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools
- [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup
- [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation
- [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers
- [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination
- [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source
- [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source
- [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source
- [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects
- [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions
- [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster
- [uevent](tcllib/files/modules/uev/uevent.md) User events
- [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time
- [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization
- [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal
- [units](tcllib/files/modules/units/units.md) unit conversion
- [uri](tcllib/files/modules/uri/uri.md) URI utilities
- [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme
- [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data
- [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison
- [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code
- [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number
- [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number
- [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number
- [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number
- [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13
- [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN
- [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI
- [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN
- [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit
- [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit
- [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI
- [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit
- [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol
- [wip](tcllib/files/modules/wip/wip.md) Word Interpreter
- [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser
- [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder
- [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data
- [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives
- [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives
- [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive
|
Added embedded/md/toc.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
|
[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown')
# Table Of Contents --
- [By Categories]()
* [Argument entry form, mega widget]()
+ [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual
* [Benchmark tools]()
+ [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites
+ [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results
+ [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV
+ [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text
+ [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction
+ [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction
+ [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification
* [CGI programming]()
+ [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures
+ [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures.
+ [json](tcllib/files/modules/json/json.md) JSON parser
+ [json::write](tcllib/files/modules/json/json_write.md) JSON generation
+ [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values.
* [Channels]()
+ [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel
+ [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support
+ [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels
+ [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel
+ [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel
+ [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels
+ [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2
+ [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel
+ [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel
+ [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination
+ [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel
+ [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout
+ [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel
+ [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel
+ [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage
+ [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel
+ [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels
+ [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation
+ [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation
+ [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support
+ [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation
+ [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation
+ [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation
+ [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation
+ [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input
+ [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy
+ [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad
+ [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption
+ [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal
+ [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression
* [Coroutine]()
+ [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling
+ [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness
* [Data structures]()
+ [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms
+ [report](tcllib/files/modules/report/report.md) Create and manipulate report objects
+ [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure
+ [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects
+ [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects
+ [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects
+ [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists
+ [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects
+ [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects
+ [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items)
+ [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects
+ [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects
+ [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures)
+ [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets
+ [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists
+ [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects
+ [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects
+ [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects
+ [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects
* [debugging, tracing, and logging]()
+ [debug](tcllib/files/modules/debug/debug.md) debug narrative - core
+ [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller
+ [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat
+ [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping
* [Documentation tools]()
+ [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction
+ [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference
+ [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq
+ [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction
+ [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax
+ [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference
+ [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction
+ [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities
+ [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction
+ [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference
+ [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq
+ [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction
+ [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax
+ [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference
+ [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents
+ [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices
+ [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents
+ [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format
+ [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format
+ [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins
+ [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices
+ [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices
+ [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices
+ [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices
+ [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format
+ [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities
+ [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers
+ [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C)
+ [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE)
+ [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN)
+ [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR)
+ [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C)
+ [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE)
+ [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN)
+ [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR)
+ [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins
+ [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format
+ [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents
+ [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents
+ [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents
+ [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices
+ [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format
+ [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities
+ [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction
+ [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference
+ [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq
+ [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction
+ [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax
+ [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference
+ [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor
+ [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor
+ [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor
+ [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor
+ [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual
+ [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text.
* [File]()
+ [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives
+ [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives
+ [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive
* [File formats]()
+ [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files
+ [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data
+ [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data
+ [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation
+ [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data
* [Grammars and finite automata]()
+ [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl
+ [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons
+ [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors
+ [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons
+ [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons
+ [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams
+ [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation
+ [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler
+ [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams
+ [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities
+ [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs
+ [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams
+ [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams
+ [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars
+ [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars
* [Hashes, checksums, and encryption]()
+ [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher
+ [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher
+ [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum
+ [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check
+ [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check
+ [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers
+ [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm
+ [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm
+ [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption
+ [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords
+ [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher
+ [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher
+ [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm
+ [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm
+ [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm
+ [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm
+ [soundex](tcllib/files/modules/soundex/soundex.md) Soundex
+ [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum
+ [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers
+ [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers
+ [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison
* [Mathematics]()
+ [math](tcllib/files/modules/math/math.md) Tcl Math Library
+ [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers
+ [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers
+ [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations
+ [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration
+ [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library
+ [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package
+ [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants
+ [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic
+ [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic
+ [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms
+ [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers
+ [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations
+ [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines
+ [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra
+ [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory
+ [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines
+ [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis
+ [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions
+ [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions
+ [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals
+ [math::special](tcllib/files/modules/math/special.md) Special mathematical functions
+ [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures
+ [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions
+ [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing
+ [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations
+ [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators
* [Networking]()
+ [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder
+ [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication
+ [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder
+ [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client
+ [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol
+ [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls
+ [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation
+ [ident](tcllib/files/modules/ident/ident.md) Ident protocol client
+ [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface.
+ [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client
+ [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface
+ [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client
+ [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension
+ [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions
+ [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol
+ [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server
+ [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data
+ [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application
+ [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction
+ [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application
+ [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application
+ [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol
+ [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client
+ [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature
+ [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client.
+ [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol
+ [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation
+ [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d
+ [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d
+ [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface
+ [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl
+ [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl
+ [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl
+ [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl
+ [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol
+ [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation
+ [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation
+ [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server
+ [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster
+ [uri](tcllib/files/modules/uri/uri.md) URI utilities
+ [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme
+ [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol
* [Page Parser Generator]()
+ [page](tcllib/files/apps/page.md) Parser Generator
+ [page_intro](tcllib/files/modules/page/page_intro.md) page introduction
+ [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager
+ [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility
+ [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON
+ [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG
+ [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities
+ [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities
* [Parsing and Grammars]()
+ [pt](tcllib/files/apps/pt.md) Parser Tools Application
+ [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization
+ [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl
+ [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA
+ [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format
+ [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification
+ [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization
+ [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities
+ [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization
+ [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage
+ [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification
+ [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export
+ [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format
+ [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format
+ [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format
+ [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format
+ [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format
+ [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format
+ [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import
+ [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format
+ [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format
+ [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format
+ [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars
+ [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format
+ [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format
+ [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format
+ [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format
+ [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format
+ [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format
+ [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial
+ [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars
+ [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator
+ [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based
+ [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX
+ [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit
+ [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo
+ [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities
+ [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API
+ [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API
+ [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools
+ [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser
+ [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API
+ [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations
* [Procedures, arguments, parameters, options]()
+ [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
+ [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual
* [Programming tools]()
+ [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options.
+ [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later)
+ [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol
+ [control](tcllib/files/modules/control/control.md) Procedures for control flow structures.
+ [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods)
+ [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures)
+ [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities
+ [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files
+ [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files
+ [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition
+ [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl
+ [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object
+ [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather
+ [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal
+ [hook](tcllib/files/modules/hook/hook.md) Hooks
+ [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing
+ [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications.
+ [logger](tcllib/files/modules/log/logger.md) System to control logging of events.
+ [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger
+ [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger
+ [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets.
+ [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin
+ [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler
+ [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl
+ [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions
+ [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension.
+ [switched](tcllib/files/modules/stooop/switched.md) switch/option management.
+ [tie](tcllib/files/modules/tie/tie.md) Array persistence
+ [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources
+ [uevent](tcllib/files/modules/uev/uevent.md) User events
+ [wip](tcllib/files/modules/wip/wip.md) Word Interpreter
* [System]()
+ [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands
+ [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications
+ [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands
* [TclOO]()
+ [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess
+ [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module
+ [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework
* [Terminal control]()
+ [term](tcllib/files/modules/term/term.md) General terminal control
+ [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences
+ [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences
+ [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences
+ [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences
+ [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries
+ [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals
+ [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu
+ [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging
+ [term::receive](tcllib/files/modules/term/receive.md) General input from terminals
+ [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals
+ [term::send](tcllib/files/modules/term/term_send.md) General output to terminals
* [Text formatter plugin]()
+ [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin
+ [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin
+ [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin
+ [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin
+ [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin
+ [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin
+ [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin
+ [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin
+ [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin
+ [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin
+ [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin
+ [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin
+ [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin
+ [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin
+ [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin
+ [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin
* [Text processing]()
+ [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data
+ [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding
+ [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps
+ [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding
+ [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data
+ [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files
+ [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times
+ [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times
+ [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data.
+ [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings
+ [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files
+ [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML
+ [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts
+ [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities
+ [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing
+ [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line
+ [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings.
+ [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs
+ [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings.
+ [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts
+ [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings.
+ [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings
+ [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings
+ [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data
+ [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser
+ [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data
* [Transfer module]()
+ [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup
+ [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation
+ [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers
+ [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination
+ [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source
+ [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source
+ [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source
* [Unfiled]()
+ [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache
+ [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators.
+ [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object
+ [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol
+ [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service
+ [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages
+ [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem
+ [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps
+ [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines
+ [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl
+ [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands
+ [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously
+ [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep
+ [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal
+ [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters.
+ [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time
+ [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization
+ [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal
+ [units](tcllib/files/modules/units/units.md) unit conversion
+ [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder
* [Utilities]()
+ [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools
* [Utility]()
+ [defer](tcllib/files/modules/defer/defer.md) Defered execution
+ [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures
+ [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation
+ [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO
+ [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO
+ [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message
+ [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools
+ [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions
* [Validation, Type checking]()
+ [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code
+ [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number
+ [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number
+ [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number
+ [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number
+ [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13
+ [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN
+ [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI
+ [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN
+ [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit
+ [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit
+ [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI
+ [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit
- [By Type]()
* [Applications]()
+ [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor
+ [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application
+ [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application
+ [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application
+ [page](tcllib/files/apps/page.md) Parser Generator
+ [pt](tcllib/files/apps/pt.md) Parser Tools Application
+ [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor
* [Modules]()
+ [aes]()
- [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher
+ [amazon-s3]()
- [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface
- [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser
+ [asn]()
- [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder
+ [base32]()
- [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding
- [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps
- [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding
+ [base64]()
- [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data
- [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data
- [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data
- [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data
+ [bee]()
- [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder
+ [bench]()
- [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites
- [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results
- [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV
- [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text
- [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction
- [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction
- [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification
+ [bibtex]()
- [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files
+ [blowfish]()
- [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher
+ [cache]()
- [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache
+ [clock]()
- [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times
- [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times
+ [cmdline]()
- [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options.
+ [comm]()
- [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later)
- [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol
+ [control]()
- [control](tcllib/files/modules/control/control.md) Procedures for control flow structures.
+ [coroutine]()
- [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling
- [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness
+ [counter]()
- [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms
+ [crc]()
- [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum
- [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check
- [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check
- [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum
+ [cron]()
- [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands
+ [csv]()
- [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data.
+ [debug]()
- [debug](tcllib/files/modules/debug/debug.md) debug narrative - core
- [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller
- [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat
- [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping
+ [defer]()
- [defer](tcllib/files/modules/defer/defer.md) Defered execution
+ [des]()
- [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers
- [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers
- [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers
+ [dicttool]()
- [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools
+ [dns]()
- [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client
- [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation
+ [docstrip]()
- [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction
- [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities
+ [doctools]()
- [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction
- [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference
- [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq
- [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction
- [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax
- [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference
- [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction
- [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference
- [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq
- [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction
- [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax
- [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference
- [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents
- [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format
- [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format
- [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices
- [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents
- [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction
- [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference
- [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq
- [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction
- [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax
- [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference
- [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor
+ [doctools2base]()
- [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins
- [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers
- [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins
- [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format
+ [doctools2idx]()
- [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices
- [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices
- [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices
- [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin
- [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin
- [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin
- [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin
- [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin
- [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin
- [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices
- [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin
- [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin
- [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format
- [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities
- [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C)
- [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE)
- [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN)
- [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR)
+ [doctools2toc]()
- [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents
- [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C)
- [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE)
- [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN)
- [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR)
- [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents
- [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents
- [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin
- [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin
- [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin
- [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin
- [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin
- [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin
- [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices
- [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin
- [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin
- [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format
- [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities
+ [dtplite]()
- [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor
+ [fileutil]()
- [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities
- [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object
- [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather
- [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal
+ [ftp]()
- [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol
- [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls
+ [ftpd]()
- [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation
+ [fumagic]()
- [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files
- [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files
- [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition
- [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl
+ [generator]()
- [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators.
+ [gpx]()
- [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files
+ [grammar_aycock]()
- [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl
+ [grammar_fa]()
- [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons
- [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors
- [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons
- [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons
+ [grammar_me]()
- [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams
- [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation
- [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler
- [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams
- [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities
- [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs
- [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams
- [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams
+ [grammar_peg]()
- [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars
- [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars
+ [hook]()
- [hook](tcllib/files/modules/hook/hook.md) Hooks
+ [html]()
- [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures
+ [htmlparse]()
- [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings
+ [http]()
- [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication
+ [httpd]()
- [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server
+ [ident]()
- [ident](tcllib/files/modules/ident/ident.md) Ident protocol client
+ [imap4]()
- [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol
+ [inifile]()
- [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files
+ [interp]()
- [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods)
- [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures)
- [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing
+ [irc]()
- [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface.
- [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client.
+ [javascript]()
- [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures.
+ [jpeg]()
- [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data
+ [json]()
- [json](tcllib/files/modules/json/json.md) JSON parser
- [json::write](tcllib/files/modules/json/json_write.md) JSON generation
+ [lambda]()
- [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures
+ [lazyset]()
- [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation
+ [ldap]()
- [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client
- [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface
+ [log]()
- [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications.
- [logger](tcllib/files/modules/log/logger.md) System to control logging of events.
- [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger
- [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger
+ [map]()
- [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service
- [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages
- [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem
- [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps
+ [mapproj]()
- [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines
+ [markdown]()
- [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML
+ [math]()
- [math](tcllib/files/modules/math/math.md) Tcl Math Library
- [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers
- [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers
- [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations
- [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration
- [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl
- [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library
- [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package
- [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants
- [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic
- [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic
- [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms
- [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers
- [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations
- [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines
- [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra
- [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory
- [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines
- [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis
- [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions
- [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions
- [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals
- [math::special](tcllib/files/modules/math/special.md) Special mathematical functions
- [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures
- [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions
- [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters.
+ [md4]()
- [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm
+ [md5]()
- [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm
+ [md5crypt]()
- [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption
+ [mime]()
- [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts
- [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol
+ [multiplexer]()
- [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets.
+ [namespacex]()
- [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands
+ [ncgi]()
- [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values.
+ [nettool]()
- [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications
+ [nmea]()
- [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data
+ [nns]()
- [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client
- [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension
- [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions
- [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol
- [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server
- [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction
+ [nntp]()
- [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol
+ [ntp]()
- [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client
+ [oauth]()
- [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature
+ [oometa]()
- [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess
+ [ooutil]()
- [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO
+ [otp]()
- [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords
+ [page]()
- [page_intro](tcllib/files/modules/page/page_intro.md) page introduction
- [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager
- [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility
- [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON
- [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG
- [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities
- [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities
+ [pki]()
- [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher
+ [pluginmgr]()
- [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin
+ [png]()
- [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data
+ [pop3]()
- [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol
+ [pop3d]()
- [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation
- [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d
- [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d
+ [practcl]()
- [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module
+ [processman]()
- [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands
+ [profiler]()
- [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler
+ [pt]()
- [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization
- [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl
- [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA
- [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format
- [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification
- [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization
- [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities
- [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization
- [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage
- [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification
- [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export
- [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format
- [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format
- [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format
- [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format
- [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format
- [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format
- [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import
- [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format
- [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format
- [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format
- [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars
- [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format
- [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format
- [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format
- [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format
- [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format
- [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format
- [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial
- [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars
- [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator
- [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based
- [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX
- [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit
- [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo
- [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities
- [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API
- [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API
- [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools
- [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser
- [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API
- [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations
+ [rc4]()
- [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher
+ [rcs]()
- [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities
+ [report]()
- [report](tcllib/files/modules/report/report.md) Create and manipulate report objects
+ [rest]()
- [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously
+ [ripemd]()
- [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm
- [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm
+ [sasl]()
- [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl
- [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl
- [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl
- [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl
+ [sha1]()
- [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm
- [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm
+ [simulation]()
- [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing
- [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations
- [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators
+ [smtpd]()
- [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation
+ [snit]()
- [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl
- [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions
+ [soundex]()
- [soundex](tcllib/files/modules/soundex/soundex.md) Soundex
+ [stooop]()
- [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension.
- [switched](tcllib/files/modules/stooop/switched.md) switch/option management.
+ [string]()
- [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing
- [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line
+ [stringprep]()
- [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep
- [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal
- [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization
- [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal
+ [struct]()
- [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure
- [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects
- [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects
- [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects
- [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists
- [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects
- [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects
- [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items)
- [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects
- [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects
- [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures)
- [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets
- [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists
- [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects
- [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects
- [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects
+ [tar]()
- [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation
+ [tepam]()
- [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
- [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual
- [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual
- [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual
+ [term]()
- [term](tcllib/files/modules/term/term.md) General terminal control
- [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences
- [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences
- [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences
- [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences
- [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries
- [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals
- [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu
- [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging
- [term::receive](tcllib/files/modules/term/receive.md) General input from terminals
- [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals
- [term::send](tcllib/files/modules/term/term_send.md) General output to terminals
+ [textutil]()
- [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings.
- [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs
- [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text.
- [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings.
- [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts
- [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings.
- [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings
- [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings
+ [tie]()
- [tie](tcllib/files/modules/tie/tie.md) Array persistence
- [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources
+ [tiff]()
- [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data
+ [tool]()
- [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO
- [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework
- [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools
+ [transfer]()
- [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup
- [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation
- [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers
- [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination
- [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source
- [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source
- [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source
+ [treeql]()
- [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects
+ [try]()
- [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message
- [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions
+ [udpcluster]()
- [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster
+ [uev]()
- [uevent](tcllib/files/modules/uev/uevent.md) User events
- [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time
+ [units]()
- [units](tcllib/files/modules/units/units.md) unit conversion
+ [uri]()
- [uri](tcllib/files/modules/uri/uri.md) URI utilities
- [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme
+ [uuid]()
- [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison
+ [valtype]()
- [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code
- [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number
- [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number
- [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number
- [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number
- [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13
- [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN
- [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI
- [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN
- [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit
- [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit
- [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI
- [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit
+ [virtchannel_base]()
- [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel
- [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel
- [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel
- [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels
- [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2
- [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel
- [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel
- [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination
- [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel
- [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout
- [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel
- [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel
- [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage
- [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel
- [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels
+ [virtchannel_core]()
- [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support
- [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels
- [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support
+ [virtchannel_transform]()
- [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation
- [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation
- [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation
- [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation
- [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation
- [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation
- [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input
- [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy
- [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad
- [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption
- [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal
- [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression
+ [websocket]()
- [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol
+ [wip]()
- [wip](tcllib/files/modules/wip/wip.md) Word Interpreter
+ [yaml]()
- [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object
- [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder
+ [zip]()
- [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives
- [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives
- [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive
|
Added embedded/md/toc0.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
|
[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown')
# Table Of Contents --
- [By Categories]()
* [Argument entry form, mega widget]()
+ [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual
* [Benchmark tools]()
+ [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites
+ [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results
+ [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV
+ [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text
+ [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction
+ [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction
+ [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification
* [CGI programming]()
+ [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures
+ [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures.
+ [json](tcllib/files/modules/json/json.md) JSON parser
+ [json::write](tcllib/files/modules/json/json_write.md) JSON generation
+ [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values.
* [Channels]()
+ [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel
+ [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support
+ [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels
+ [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel
+ [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel
+ [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels
+ [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2
+ [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel
+ [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel
+ [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination
+ [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel
+ [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout
+ [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel
+ [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel
+ [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage
+ [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel
+ [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels
+ [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation
+ [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation
+ [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support
+ [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation
+ [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation
+ [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation
+ [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation
+ [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input
+ [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy
+ [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad
+ [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption
+ [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal
+ [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression
* [Coroutine]()
+ [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling
+ [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness
* [Data structures]()
+ [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms
+ [report](tcllib/files/modules/report/report.md) Create and manipulate report objects
+ [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure
+ [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects
+ [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects
+ [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects
+ [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists
+ [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects
+ [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects
+ [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items)
+ [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects
+ [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects
+ [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures)
+ [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets
+ [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists
+ [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects
+ [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects
+ [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects
+ [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects
* [debugging, tracing, and logging]()
+ [debug](tcllib/files/modules/debug/debug.md) debug narrative - core
+ [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller
+ [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat
+ [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping
* [Documentation tools]()
+ [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction
+ [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference
+ [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq
+ [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction
+ [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax
+ [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference
+ [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction
+ [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities
+ [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction
+ [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference
+ [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq
+ [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction
+ [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax
+ [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference
+ [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents
+ [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices
+ [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents
+ [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format
+ [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format
+ [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins
+ [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices
+ [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices
+ [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices
+ [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices
+ [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format
+ [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities
+ [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers
+ [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C)
+ [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE)
+ [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN)
+ [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR)
+ [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C)
+ [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE)
+ [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN)
+ [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR)
+ [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins
+ [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format
+ [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents
+ [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents
+ [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents
+ [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices
+ [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format
+ [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities
+ [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction
+ [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference
+ [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq
+ [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction
+ [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax
+ [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference
+ [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor
+ [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor
+ [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor
+ [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor
+ [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual
+ [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text.
* [File]()
+ [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives
+ [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives
+ [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive
* [File formats]()
+ [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files
+ [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data
+ [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data
+ [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation
+ [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data
* [Grammars and finite automata]()
+ [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl
+ [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons
+ [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors
+ [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons
+ [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons
+ [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams
+ [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation
+ [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler
+ [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams
+ [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities
+ [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs
+ [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams
+ [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams
+ [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars
+ [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars
* [Hashes, checksums, and encryption]()
+ [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher
+ [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher
+ [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum
+ [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check
+ [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check
+ [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers
+ [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm
+ [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm
+ [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption
+ [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords
+ [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher
+ [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher
+ [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm
+ [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm
+ [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm
+ [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm
+ [soundex](tcllib/files/modules/soundex/soundex.md) Soundex
+ [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum
+ [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers
+ [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers
+ [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison
* [Mathematics]()
+ [math](tcllib/files/modules/math/math.md) Tcl Math Library
+ [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers
+ [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers
+ [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations
+ [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration
+ [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library
+ [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package
+ [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants
+ [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic
+ [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic
+ [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms
+ [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers
+ [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations
+ [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines
+ [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra
+ [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory
+ [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines
+ [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis
+ [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions
+ [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions
+ [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals
+ [math::special](tcllib/files/modules/math/special.md) Special mathematical functions
+ [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures
+ [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions
+ [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing
+ [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations
+ [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators
* [Networking]()
+ [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder
+ [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication
+ [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder
+ [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client
+ [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol
+ [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls
+ [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation
+ [ident](tcllib/files/modules/ident/ident.md) Ident protocol client
+ [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface.
+ [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client
+ [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface
+ [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client
+ [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension
+ [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions
+ [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol
+ [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server
+ [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data
+ [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application
+ [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction
+ [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application
+ [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application
+ [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol
+ [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client
+ [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature
+ [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client.
+ [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol
+ [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation
+ [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d
+ [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d
+ [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface
+ [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl
+ [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl
+ [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl
+ [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl
+ [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol
+ [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation
+ [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation
+ [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server
+ [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster
+ [uri](tcllib/files/modules/uri/uri.md) URI utilities
+ [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme
+ [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol
* [Page Parser Generator]()
+ [page](tcllib/files/apps/page.md) Parser Generator
+ [page_intro](tcllib/files/modules/page/page_intro.md) page introduction
+ [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager
+ [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility
+ [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON
+ [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG
+ [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities
+ [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities
* [Parsing and Grammars]()
+ [pt](tcllib/files/apps/pt.md) Parser Tools Application
+ [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization
+ [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl
+ [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA
+ [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format
+ [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification
+ [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization
+ [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities
+ [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization
+ [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage
+ [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification
+ [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export
+ [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format
+ [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format
+ [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format
+ [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format
+ [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format
+ [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format
+ [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import
+ [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format
+ [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format
+ [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format
+ [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars
+ [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format
+ [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format
+ [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format
+ [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format
+ [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format
+ [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format
+ [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial
+ [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars
+ [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator
+ [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based
+ [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX
+ [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit
+ [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo
+ [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities
+ [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API
+ [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API
+ [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools
+ [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser
+ [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API
+ [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations
* [Procedures, arguments, parameters, options]()
+ [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
+ [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual
* [Programming tools]()
+ [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options.
+ [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later)
+ [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol
+ [control](tcllib/files/modules/control/control.md) Procedures for control flow structures.
+ [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods)
+ [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures)
+ [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities
+ [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files
+ [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files
+ [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition
+ [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl
+ [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object
+ [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather
+ [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal
+ [hook](tcllib/files/modules/hook/hook.md) Hooks
+ [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing
+ [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications.
+ [logger](tcllib/files/modules/log/logger.md) System to control logging of events.
+ [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger
+ [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger
+ [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets.
+ [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin
+ [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler
+ [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl
+ [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions
+ [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension.
+ [switched](tcllib/files/modules/stooop/switched.md) switch/option management.
+ [tie](tcllib/files/modules/tie/tie.md) Array persistence
+ [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources
+ [uevent](tcllib/files/modules/uev/uevent.md) User events
+ [wip](tcllib/files/modules/wip/wip.md) Word Interpreter
* [System]()
+ [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands
+ [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications
+ [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands
* [TclOO]()
+ [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess
+ [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module
+ [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework
* [Terminal control]()
+ [term](tcllib/files/modules/term/term.md) General terminal control
+ [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences
+ [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences
+ [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences
+ [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences
+ [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries
+ [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals
+ [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu
+ [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging
+ [term::receive](tcllib/files/modules/term/receive.md) General input from terminals
+ [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals
+ [term::send](tcllib/files/modules/term/term_send.md) General output to terminals
* [Text formatter plugin]()
+ [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin
+ [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin
+ [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin
+ [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin
+ [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin
+ [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin
+ [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin
+ [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin
+ [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin
+ [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin
+ [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin
+ [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin
+ [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin
+ [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin
+ [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin
+ [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin
* [Text processing]()
+ [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data
+ [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding
+ [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps
+ [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding
+ [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data
+ [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files
+ [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times
+ [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times
+ [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data.
+ [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings
+ [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files
+ [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML
+ [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts
+ [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities
+ [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing
+ [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line
+ [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings.
+ [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs
+ [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings.
+ [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts
+ [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings.
+ [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings
+ [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings
+ [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data
+ [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser
+ [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data
* [Transfer module]()
+ [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup
+ [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation
+ [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers
+ [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination
+ [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source
+ [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source
+ [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source
* [Unfiled]()
+ [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache
+ [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators.
+ [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object
+ [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol
+ [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service
+ [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages
+ [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem
+ [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps
+ [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines
+ [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl
+ [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands
+ [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously
+ [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep
+ [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal
+ [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters.
+ [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time
+ [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization
+ [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal
+ [units](tcllib/files/modules/units/units.md) unit conversion
+ [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder
* [Utilities]()
+ [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools
* [Utility]()
+ [defer](tcllib/files/modules/defer/defer.md) Defered execution
+ [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures
+ [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation
+ [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO
+ [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO
+ [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message
+ [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools
+ [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions
* [Validation, Type checking]()
+ [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code
+ [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number
+ [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number
+ [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number
+ [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number
+ [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13
+ [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN
+ [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI
+ [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN
+ [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit
+ [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit
+ [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI
+ [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit
|
Added embedded/md/toc1.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
|
[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown')
# Table Of Contents --
- [Modules]()
* [aes]()
+ [aes](tcllib/files/modules/aes/aes.md) Implementation of the AES block cipher
* [amazon-s3]()
+ [S3](tcllib/files/modules/amazon-s3/S3.md) Amazon S3 Web Service Interface
+ [xsxp](tcllib/files/modules/amazon-s3/xsxp.md) eXtremely Simple Xml Parser
* [asn]()
+ [asn](tcllib/files/modules/asn/asn.md) ASN.1 BER encoder/decoder
* [base32]()
+ [base32](tcllib/files/modules/base32/base32.md) base32 standard encoding
+ [base32::core](tcllib/files/modules/base32/base32core.md) Expanding basic base32 maps
+ [base32::hex](tcllib/files/modules/base32/base32hex.md) base32 extended hex encoding
* [base64]()
+ [ascii85](tcllib/files/modules/base64/ascii85.md) ascii85-encode/decode binary data
+ [base64](tcllib/files/modules/base64/base64.md) base64-encode/decode binary data
+ [uuencode](tcllib/files/modules/base64/uuencode.md) UU-encode/decode binary data
+ [yencode](tcllib/files/modules/base64/yencode.md) Y-encode/decode binary data
* [bee]()
+ [bee](tcllib/files/modules/bee/bee.md) BitTorrent Serialization Format Encoder/Decoder
* [bench]()
+ [bench](tcllib/files/modules/bench/bench.md) bench - Processing benchmark suites
+ [bench::in](tcllib/files/modules/bench/bench_read.md) bench::in - Reading benchmark results
+ [bench::out::csv](tcllib/files/modules/bench/bench_wcsv.md) bench::out::csv - Formatting benchmark results as CSV
+ [bench::out::text](tcllib/files/modules/bench/bench_wtext.md) bench::out::text - Formatting benchmark results as human readable text
+ [bench_intro](tcllib/files/modules/bench/bench_intro.md) bench introduction
+ [bench_lang_intro](tcllib/files/modules/bench/bench_lang_intro.md) bench language introduction
+ [bench_lang_spec](tcllib/files/modules/bench/bench_lang_spec.md) bench language specification
* [bibtex]()
+ [bibtex](tcllib/files/modules/bibtex/bibtex.md) Parse bibtex files
* [blowfish]()
+ [blowfish](tcllib/files/modules/blowfish/blowfish.md) Implementation of the Blowfish block cipher
* [cache]()
+ [cache::async](tcllib/files/modules/cache/async.md) Asynchronous in-memory cache
* [clock]()
+ [clock_iso8601](tcllib/files/modules/clock/iso8601.md) Parsing ISO 8601 dates/times
+ [clock_rfc2822](tcllib/files/modules/clock/rfc2822.md) Parsing ISO 8601 dates/times
* [cmdline]()
+ [cmdline](tcllib/files/modules/cmdline/cmdline.md) Procedures to process command lines and options.
* [comm]()
+ [comm](tcllib/files/modules/comm/comm.md) A remote communication facility for Tcl (8.3 and later)
+ [comm_wire](tcllib/files/modules/comm/comm_wire.md) The comm wire protocol
* [control]()
+ [control](tcllib/files/modules/control/control.md) Procedures for control flow structures.
* [coroutine]()
+ [coroutine](tcllib/files/modules/coroutine/tcllib_coroutine.md) Coroutine based event and IO handling
+ [coroutine::auto](tcllib/files/modules/coroutine/coro_auto.md) Automatic event and IO coroutine awareness
* [counter]()
+ [counter](tcllib/files/modules/counter/counter.md) Procedures for counters and histograms
* [crc]()
+ [cksum](tcllib/files/modules/crc/cksum.md) Calculate a cksum(1) compatible checksum
+ [crc16](tcllib/files/modules/crc/crc16.md) Perform a 16bit Cyclic Redundancy Check
+ [crc32](tcllib/files/modules/crc/crc32.md) Perform a 32bit Cyclic Redundancy Check
+ [sum](tcllib/files/modules/crc/sum.md) Calculate a sum(1) compatible checksum
* [cron]()
+ [cron](tcllib/files/modules/cron/cron.md) Tool for automating the period callback of commands
* [csv]()
+ [csv](tcllib/files/modules/csv/csv.md) Procedures to handle CSV data.
* [debug]()
+ [debug](tcllib/files/modules/debug/debug.md) debug narrative - core
+ [debug::caller](tcllib/files/modules/debug/debug_caller.md) debug narrative - caller
+ [debug::heartbeat](tcllib/files/modules/debug/debug_heartbeat.md) debug narrative - heartbeat
+ [debug::timestamp](tcllib/files/modules/debug/debug_timestamp.md) debug narrative - timestamping
* [defer]()
+ [defer](tcllib/files/modules/defer/defer.md) Defered execution
* [des]()
+ [des](tcllib/files/modules/des/des.md) Implementation of the DES and triple-DES ciphers
+ [tclDES](tcllib/files/modules/des/tcldes.md) Implementation of the DES and triple-DES ciphers
+ [tclDESjr](tcllib/files/modules/des/tcldesjr.md) Implementation of the DES and triple-DES ciphers
* [dicttool]()
+ [dicttool](tcllib/files/modules/dicttool/dicttool.md) Dictionary Tools
* [dns]()
+ [dns](tcllib/files/modules/dns/tcllib_dns.md) Tcl Domain Name Service Client
+ [tcllib_ip](tcllib/files/modules/dns/tcllib_ip.md) IPv4 and IPv6 address manipulation
* [docstrip]()
+ [docstrip](tcllib/files/modules/docstrip/docstrip.md) Docstrip style source code extraction
+ [docstrip_util](tcllib/files/modules/docstrip/docstrip_util.md) Docstrip-related utilities
* [doctools]()
+ [docidx_intro](tcllib/files/modules/doctools/docidx_intro.md) docidx introduction
+ [docidx_lang_cmdref](tcllib/files/modules/doctools/docidx_lang_cmdref.md) docidx language command reference
+ [docidx_lang_faq](tcllib/files/modules/doctools/docidx_lang_faq.md) docidx language faq
+ [docidx_lang_intro](tcllib/files/modules/doctools/docidx_lang_intro.md) docidx language introduction
+ [docidx_lang_syntax](tcllib/files/modules/doctools/docidx_lang_syntax.md) docidx language syntax
+ [docidx_plugin_apiref](tcllib/files/modules/doctools/docidx_plugin_apiref.md) docidx plugin API reference
+ [doctoc_intro](tcllib/files/modules/doctools/doctoc_intro.md) doctoc introduction
+ [doctoc_lang_cmdref](tcllib/files/modules/doctools/doctoc_lang_cmdref.md) doctoc language command reference
+ [doctoc_lang_faq](tcllib/files/modules/doctools/doctoc_lang_faq.md) doctoc language faq
+ [doctoc_lang_intro](tcllib/files/modules/doctools/doctoc_lang_intro.md) doctoc language introduction
+ [doctoc_lang_syntax](tcllib/files/modules/doctools/doctoc_lang_syntax.md) doctoc language syntax
+ [doctoc_plugin_apiref](tcllib/files/modules/doctools/doctoc_plugin_apiref.md) doctoc plugin API reference
+ [doctools](tcllib/files/modules/doctools/doctools.md) doctools - Processing documents
+ [doctools::changelog](tcllib/files/modules/doctools/changelog.md) Processing text in Emacs ChangeLog format
+ [doctools::cvs](tcllib/files/modules/doctools/cvs.md) Processing text in 'cvs log' format
+ [doctools::idx](tcllib/files/modules/doctools/docidx.md) docidx - Processing indices
+ [doctools::toc](tcllib/files/modules/doctools/doctoc.md) doctoc - Processing tables of contents
+ [doctools_intro](tcllib/files/modules/doctools/doctools_intro.md) doctools introduction
+ [doctools_lang_cmdref](tcllib/files/modules/doctools/doctools_lang_cmdref.md) doctools language command reference
+ [doctools_lang_faq](tcllib/files/modules/doctools/doctools_lang_faq.md) doctools language faq
+ [doctools_lang_intro](tcllib/files/modules/doctools/doctools_lang_intro.md) doctools language introduction
+ [doctools_lang_syntax](tcllib/files/modules/doctools/doctools_lang_syntax.md) doctools language syntax
+ [doctools_plugin_apiref](tcllib/files/modules/doctools/doctools_plugin_apiref.md) doctools plugin API reference
+ [mpexpand](tcllib/files/modules/doctools/mpexpand.md) Markup processor
* [doctools2base]()
+ [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html_cssdefaults.md) Default CSS style for HTML export plugins
+ [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib_msgcat.md) Message catalog management for the various document parsers
+ [doctools::nroff::man_macros](tcllib/files/modules/doctools2base/nroff_manmacros.md) Default CSS style for NROFF export plugins
+ [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl_parse.md) Processing text in 'subst -novariables' format
* [doctools2idx]()
+ [doctools2idx_introduction](tcllib/files/modules/doctools2idx/idx_introduction.md) DocTools - Keyword indices
+ [doctools::idx](tcllib/files/modules/doctools2idx/idx_container.md) Holding keyword indices
+ [doctools::idx::export](tcllib/files/modules/doctools2idx/idx_export.md) Exporting keyword indices
+ [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export_docidx.md) docidx export plugin
+ [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx_export_html.md) HTML export plugin
+ [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx_export_json.md) JSON export plugin
+ [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx_export_nroff.md) nroff export plugin
+ [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx_export_text.md) plain text export plugin
+ [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx_export_wiki.md) wiki export plugin
+ [doctools::idx::import](tcllib/files/modules/doctools2idx/idx_import.md) Importing keyword indices
+ [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import_docidx.md) docidx import plugin
+ [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx_import_json.md) JSON import plugin
+ [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx_parse.md) Parsing text in docidx format
+ [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx_structure.md) Docidx serialization utilities
+ [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx_msgcat_c.md) Message catalog for the docidx parser (C)
+ [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx_msgcat_de.md) Message catalog for the docidx parser (DE)
+ [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx_msgcat_en.md) Message catalog for the docidx parser (EN)
+ [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx_msgcat_fr.md) Message catalog for the docidx parser (FR)
* [doctools2toc]()
+ [doctools2toc_introduction](tcllib/files/modules/doctools2toc/toc_introduction.md) DocTools - Tables of Contents
+ [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc_msgcat_c.md) Message catalog for the doctoc parser (C)
+ [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc_msgcat_de.md) Message catalog for the doctoc parser (DE)
+ [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc_msgcat_en.md) Message catalog for the doctoc parser (EN)
+ [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc_msgcat_fr.md) Message catalog for the doctoc parser (FR)
+ [doctools::toc](tcllib/files/modules/doctools2toc/toc_container.md) Holding tables of contents
+ [doctools::toc::export](tcllib/files/modules/doctools2toc/toc_export.md) Exporting tables of contents
+ [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export_doctoc.md) doctoc export plugin
+ [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc_export_html.md) HTML export plugin
+ [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc_export_json.md) JSON export plugin
+ [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc_export_nroff.md) nroff export plugin
+ [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc_export_text.md) plain text export plugin
+ [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc_export_wiki.md) wiki export plugin
+ [doctools::toc::import](tcllib/files/modules/doctools2toc/toc_import.md) Importing keyword indices
+ [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import_doctoc.md) doctoc import plugin
+ [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc_import_json.md) JSON import plugin
+ [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc_parse.md) Parsing text in doctoc format
+ [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc_structure.md) Doctoc serialization utilities
* [dtplite]()
+ [dtplite](tcllib/files/modules/dtplite/pkg_dtplite.md) Lightweight DocTools Markup Processor
* [fileutil]()
+ [fileutil](tcllib/files/modules/fileutil/fileutil.md) Procedures implementing some file utilities
+ [fileutil::multi](tcllib/files/modules/fileutil/multi.md) Multi-file operation, scatter/gather, standard object
+ [fileutil::multi::op](tcllib/files/modules/fileutil/multiop.md) Multi-file operation, scatter/gather
+ [fileutil_traverse](tcllib/files/modules/fileutil/traverse.md) Iterative directory traversal
* [ftp]()
+ [ftp](tcllib/files/modules/ftp/ftp.md) Client-side tcl implementation of the ftp protocol
+ [ftp::geturl](tcllib/files/modules/ftp/ftp_geturl.md) Uri handler for ftp urls
* [ftpd]()
+ [ftpd](tcllib/files/modules/ftpd/ftpd.md) Tcl FTP server implementation
* [fumagic]()
+ [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront.md) Generator core for compiler of magic(5) files
+ [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen.md) Generator core for compiler of magic(5) files
+ [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes.md) Procedures implementing file-type recognition
+ [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore.md) Runtime core for file type recognition engines written in pure Tcl
* [generator]()
+ [generator](tcllib/files/modules/generator/generator.md) Procedures for creating and using generators.
* [gpx]()
+ [gpx](tcllib/files/modules/gpx/gpx.md) Extracts waypoints, tracks and routes from GPX files
* [grammar_aycock]()
+ [grammar::aycock](tcllib/files/modules/grammar_aycock/aycock.md) Aycock-Horspool-Earley parser generator for Tcl
* [grammar_fa]()
+ [grammar::fa](tcllib/files/modules/grammar_fa/fa.md) Create and manipulate finite automatons
+ [grammar::fa::dacceptor](tcllib/files/modules/grammar_fa/dacceptor.md) Create and use deterministic acceptors
+ [grammar::fa::dexec](tcllib/files/modules/grammar_fa/dexec.md) Execute deterministic finite automatons
+ [grammar::fa::op](tcllib/files/modules/grammar_fa/faop.md) Operations on finite automatons
* [grammar_me]()
+ [grammar::me::cpu](tcllib/files/modules/grammar_me/me_cpu.md) Virtual machine implementation II for parsing token streams
+ [grammar::me::cpu::core](tcllib/files/modules/grammar_me/me_cpucore.md) ME virtual machine state manipulation
+ [grammar::me::cpu::gasm](tcllib/files/modules/grammar_me/gasm.md) ME assembler
+ [grammar::me::tcl](tcllib/files/modules/grammar_me/me_tcl.md) Virtual machine implementation I for parsing token streams
+ [grammar::me::util](tcllib/files/modules/grammar_me/me_util.md) AST utilities
+ [grammar::me_ast](tcllib/files/modules/grammar_me/me_ast.md) Various representations of ASTs
+ [grammar::me_intro](tcllib/files/modules/grammar_me/me_intro.md) Introduction to virtual machines for parsing token streams
+ [grammar::me_vm](tcllib/files/modules/grammar_me/me_vm.md) Virtual machine for parsing token streams
* [grammar_peg]()
+ [grammar::peg](tcllib/files/modules/grammar_peg/peg.md) Create and manipulate parsing expression grammars
+ [grammar::peg::interp](tcllib/files/modules/grammar_peg/peg_interp.md) Interpreter for parsing expression grammars
* [hook]()
+ [hook](tcllib/files/modules/hook/hook.md) Hooks
* [html]()
+ [html](tcllib/files/modules/html/html.md) Procedures to generate HTML structures
* [htmlparse]()
+ [htmlparse](tcllib/files/modules/htmlparse/htmlparse.md) Procedures to parse HTML strings
* [http]()
+ [autoproxy](tcllib/files/modules/http/autoproxy.md) Automatic HTTP proxy usage and authentication
* [httpd]()
+ [tool](tcllib/files/modules/httpd/httpd.md) A TclOO and coroutine based web server
* [ident]()
+ [ident](tcllib/files/modules/ident/ident.md) Ident protocol client
* [imap4]()
+ [imap4](tcllib/files/modules/imap4/imap4.md) imap client-side tcl implementation of imap protocol
* [inifile]()
+ [inifile](tcllib/files/modules/inifile/ini.md) Parsing of Windows INI files
* [interp]()
+ [deleg_method](tcllib/files/modules/interp/deleg_method.md) Creation of comm delegates (snit methods)
+ [deleg_proc](tcllib/files/modules/interp/deleg_proc.md) Creation of comm delegates (procedures)
+ [interp](tcllib/files/modules/interp/tcllib_interp.md) Interp creation and aliasing
* [irc]()
+ [irc](tcllib/files/modules/irc/irc.md) Create IRC connection and interface.
+ [picoirc](tcllib/files/modules/irc/picoirc.md) Small and simple embeddable IRC client.
* [javascript]()
+ [javascript](tcllib/files/modules/javascript/javascript.md) Procedures to generate HTML and Java Script structures.
* [jpeg]()
+ [jpeg](tcllib/files/modules/jpeg/jpeg.md) JPEG querying and manipulation of meta data
* [json]()
+ [json](tcllib/files/modules/json/json.md) JSON parser
+ [json::write](tcllib/files/modules/json/json_write.md) JSON generation
* [lambda]()
+ [lambda](tcllib/files/modules/lambda/lambda.md) Utility commands for anonymous procedures
* [lazyset]()
+ [lazyset](tcllib/files/modules/lazyset/lazyset.md) Lazy evaluation
* [ldap]()
+ [ldap](tcllib/files/modules/ldap/ldap.md) LDAP client
+ [ldapx](tcllib/files/modules/ldap/ldapx.md) LDAP extended object interface
* [log]()
+ [log](tcllib/files/modules/log/log.md) Procedures to log messages of libraries and applications.
+ [logger](tcllib/files/modules/log/logger.md) System to control logging of events.
+ [logger::appender](tcllib/files/modules/log/loggerAppender.md) Collection of predefined appenders for logger
+ [logger::utils](tcllib/files/modules/log/loggerUtils.md) Utilities for logger
* [map]()
+ [map::geocode::nominatim](tcllib/files/modules/map/map_geocode_nominatim.md) Resolving geographical names with a Nominatim service
+ [map::slippy](tcllib/files/modules/map/map_slippy.md) Common code for slippy based map packages
+ [map::slippy::cache](tcllib/files/modules/map/map_slippy_cache.md) Management of a tile cache in the local filesystem
+ [map::slippy::fetcher](tcllib/files/modules/map/map_slippy_fetcher.md) Accessing a server providing tiles for slippy-based maps
* [mapproj]()
+ [mapproj](tcllib/files/modules/mapproj/mapproj.md) Map projection routines
* [markdown]()
+ [markdown](tcllib/files/modules/markdown/markdown.md) Converts Markdown text to HTML
* [math]()
+ [math](tcllib/files/modules/math/math.md) Tcl Math Library
+ [math::bigfloat](tcllib/files/modules/math/bigfloat.md) Arbitrary precision floating-point numbers
+ [math::bignum](tcllib/files/modules/math/bignum.md) Arbitrary precision integer numbers
+ [math::calculus](tcllib/files/modules/math/calculus.md) Integration and ordinary differential equations
+ [math::calculus::romberg](tcllib/files/modules/math/romberg.md) Romberg integration
+ [math::calculus::symdiff](tcllib/files/modules/math/symdiff.md) Symbolic differentiation for Tcl
+ [math::combinatorics](tcllib/files/modules/math/combinatorics.md) Combinatorial functions in the Tcl Math Library
+ [math::complexnumbers](tcllib/files/modules/math/qcomplex.md) Straightforward complex number package
+ [math::constants](tcllib/files/modules/math/constants.md) Mathematical and numerical constants
+ [math::decimal](tcllib/files/modules/math/decimal.md) General decimal arithmetic
+ [math::exact](tcllib/files/modules/math/exact.md) Exact Real Arithmetic
+ [math::fourier](tcllib/files/modules/math/fourier.md) Discrete and fast fourier transforms
+ [math::fuzzy](tcllib/files/modules/math/fuzzy.md) Fuzzy comparison of floating-point numbers
+ [math::geometry](tcllib/files/modules/math/math_geometry.md) Geometrical computations
+ [math::interpolate](tcllib/files/modules/math/interpolate.md) Interpolation routines
+ [math::linearalgebra](tcllib/files/modules/math/linalg.md) Linear Algebra
+ [math::numtheory](tcllib/files/modules/math/numtheory.md) Number Theory
+ [math::optimize](tcllib/files/modules/math/optimize.md) Optimisation routines
+ [math::PCA](tcllib/files/modules/math/pca.md) Package for Principal Component Analysis
+ [math::polynomials](tcllib/files/modules/math/polynomials.md) Polynomial functions
+ [math::rationalfunctions](tcllib/files/modules/math/rational_funcs.md) Polynomial functions
+ [math::roman](tcllib/files/modules/math/roman.md) Tools for creating and manipulating roman numerals
+ [math::special](tcllib/files/modules/math/special.md) Special mathematical functions
+ [math::statistics](tcllib/files/modules/math/statistics.md) Basic statistical functions and procedures
+ [math::trig](tcllib/files/modules/math/trig.md) Trigonometric anf hyperbolic functions
+ [tclrep/machineparameters](tcllib/files/modules/math/machineparameters.md) Compute double precision machine parameters.
* [md4]()
+ [md4](tcllib/files/modules/md4/md4.md) MD4 Message-Digest Algorithm
* [md5]()
+ [md5](tcllib/files/modules/md5/md5.md) MD5 Message-Digest Algorithm
* [md5crypt]()
+ [md5crypt](tcllib/files/modules/md5crypt/md5crypt.md) MD5-based password encryption
* [mime]()
+ [mime](tcllib/files/modules/mime/mime.md) Manipulation of MIME body parts
+ [smtp](tcllib/files/modules/mime/smtp.md) Client-side tcl implementation of the smtp protocol
* [multiplexer]()
+ [multiplexer](tcllib/files/modules/multiplexer/multiplexer.md) One-to-many communication with sockets.
* [namespacex]()
+ [namespacex](tcllib/files/modules/namespacex/namespacex.md) Namespace utility commands
* [ncgi]()
+ [ncgi](tcllib/files/modules/ncgi/ncgi.md) Procedures to manipulate CGI values.
* [nettool]()
+ [nettool](tcllib/files/modules/nettool/nettool.md) Tools for networked applications
* [nmea]()
+ [nmea](tcllib/files/modules/nmea/nmea.md) Process NMEA data
* [nns]()
+ [nameserv](tcllib/files/modules/nns/nns_client.md) Name service facility, Client
+ [nameserv::auto](tcllib/files/modules/nns/nns_auto.md) Name service facility, Client Extension
+ [nameserv::common](tcllib/files/modules/nns/nns_common.md) Name service facility, shared definitions
+ [nameserv::protocol](tcllib/files/modules/nns/nns_protocol.md) Name service facility, client/server protocol
+ [nameserv::server](tcllib/files/modules/nns/nns_server.md) Name service facility, Server
+ [nns_intro](tcllib/files/modules/nns/nns_intro.md) Name service facility, introduction
* [nntp]()
+ [nntp](tcllib/files/modules/nntp/nntp.md) Tcl client for the NNTP protocol
* [ntp]()
+ [ntp_time](tcllib/files/modules/ntp/ntp_time.md) Tcl Time Service Client
* [oauth]()
+ [oauth](tcllib/files/modules/oauth/oauth.md) oauth API base signature
* [oometa]()
+ [oometa](tcllib/files/modules/oometa/oometa.md) oo::meta A data registry for classess
* [ooutil]()
+ [oo::util](tcllib/files/modules/ooutil/ooutil.md) Utility commands for TclOO
* [otp]()
+ [otp](tcllib/files/modules/otp/otp.md) One-Time Passwords
* [page]()
+ [page_intro](tcllib/files/modules/page/page_intro.md) page introduction
+ [page_pluginmgr](tcllib/files/modules/page/page_pluginmgr.md) page plugin manager
+ [page_util_flow](tcllib/files/modules/page/page_util_flow.md) page dataflow/treewalker utility
+ [page_util_norm_lemon](tcllib/files/modules/page/page_util_norm_lemon.md) page AST normalization, LEMON
+ [page_util_norm_peg](tcllib/files/modules/page/page_util_norm_peg.md) page AST normalization, PEG
+ [page_util_peg](tcllib/files/modules/page/page_util_peg.md) page PEG transformation utilities
+ [page_util_quote](tcllib/files/modules/page/page_util_quote.md) page character quoting utilities
* [pki]()
+ [pki](tcllib/files/modules/pki/pki.md) Implementation of the public key cipher
* [pluginmgr]()
+ [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr.md) Manage a plugin
* [png]()
+ [png](tcllib/files/modules/png/png.md) PNG querying and manipulation of meta data
* [pop3]()
+ [pop3](tcllib/files/modules/pop3/pop3.md) Tcl client for POP3 email protocol
* [pop3d]()
+ [pop3d](tcllib/files/modules/pop3d/pop3d.md) Tcl POP3 server implementation
+ [pop3d::dbox](tcllib/files/modules/pop3d/pop3d_dbox.md) Simple mailbox database for pop3d
+ [pop3d::udb](tcllib/files/modules/pop3d/pop3d_udb.md) Simple user database for pop3d
* [practcl]()
+ [practcl](tcllib/files/modules/practcl/practcl.md) The Practcl Module
* [processman]()
+ [processman](tcllib/files/modules/processman/processman.md) Tool for automating the period callback of commands
* [profiler]()
+ [profiler](tcllib/files/modules/profiler/profiler.md) Tcl source code profiler
* [pt]()
+ [pt::ast](tcllib/files/modules/pt/pt_astree.md) Abstract Syntax Tree Serialization
+ [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt_cparam_config_critcl.md) C/PARAM, Canned configuration, Critcl
+ [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt_cparam_config_tea.md) C/PARAM, Canned configuration, TEA
+ [pt::json_language](tcllib/files/modules/pt/pt_json_language.md) The JSON Grammar Exchange Format
+ [pt::param](tcllib/files/modules/pt/pt_param.md) PackRat Machine Specification
+ [pt::pe](tcllib/files/modules/pt/pt_pexpression.md) Parsing Expression Serialization
+ [pt::pe::op](tcllib/files/modules/pt/pt_pexpr_op.md) Parsing Expression Utilities
+ [pt::peg](tcllib/files/modules/pt/pt_pegrammar.md) Parsing Expression Grammar Serialization
+ [pt::peg::container](tcllib/files/modules/pt/pt_peg_container.md) PEG Storage
+ [pt::peg::container::peg](tcllib/files/modules/pt/pt_peg_container_peg.md) PEG Storage. Canned PEG grammar specification
+ [pt::peg::export](tcllib/files/modules/pt/pt_peg_export.md) PEG Export
+ [pt::peg::export::container](tcllib/files/modules/pt/pt_peg_export_container.md) PEG Export Plugin. Write CONTAINER format
+ [pt::peg::export::json](tcllib/files/modules/pt/pt_peg_export_json.md) PEG Export Plugin. Write JSON format
+ [pt::peg::export::peg](tcllib/files/modules/pt/pt_peg_export_peg.md) PEG Export Plugin. Write PEG format
+ [pt::peg::from::container](tcllib/files/modules/pt/pt_peg_from_container.md) PEG Conversion. From CONTAINER format
+ [pt::peg::from::json](tcllib/files/modules/pt/pt_peg_from_json.md) PEG Conversion. Read JSON format
+ [pt::peg::from::peg](tcllib/files/modules/pt/pt_peg_from_peg.md) PEG Conversion. Read PEG format
+ [pt::peg::import](tcllib/files/modules/pt/pt_peg_import.md) PEG Import
+ [pt::peg::import::container](tcllib/files/modules/pt/pt_peg_import_container.md) PEG Import Plugin. From CONTAINER format
+ [pt::peg::import::json](tcllib/files/modules/pt/pt_peg_import_json.md) PEG Import Plugin. Read JSON format
+ [pt::peg::import::peg](tcllib/files/modules/pt/pt_peg_import_peg.md) PEG Import Plugin. Read PEG format
+ [pt::peg::interp](tcllib/files/modules/pt/pt_peg_interp.md) Interpreter for parsing expression grammars
+ [pt::peg::to::container](tcllib/files/modules/pt/pt_peg_to_container.md) PEG Conversion. Write CONTAINER format
+ [pt::peg::to::cparam](tcllib/files/modules/pt/pt_peg_to_cparam.md) PEG Conversion. Write CPARAM format
+ [pt::peg::to::json](tcllib/files/modules/pt/pt_peg_to_json.md) PEG Conversion. Write JSON format
+ [pt::peg::to::param](tcllib/files/modules/pt/pt_peg_to_param.md) PEG Conversion. Write PARAM format
+ [pt::peg::to::peg](tcllib/files/modules/pt/pt_peg_to_peg.md) PEG Conversion. Write PEG format
+ [pt::peg::to::tclparam](tcllib/files/modules/pt/pt_peg_to_tclparam.md) PEG Conversion. Write TCLPARAM format
+ [pt::peg_language](tcllib/files/modules/pt/pt_peg_language.md) PEG Language Tutorial
+ [pt::pegrammar](tcllib/files/modules/pt/pt_peg_introduction.md) Introduction to Parsing Expression Grammars
+ [pt::pgen](tcllib/files/modules/pt/pt_pgen.md) Parser Generator
+ [pt::rde](tcllib/files/modules/pt/pt_rdengine.md) Parsing Runtime Support, PARAM based
+ [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt_tclparam_config_nx.md) Tcl/PARAM, Canned configuration, NX
+ [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt_tclparam_config_snit.md) Tcl/PARAM, Canned configuration, Snit
+ [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt_tclparam_config_tcloo.md) Tcl/PARAM, Canned configuration, Tcloo
+ [pt::util](tcllib/files/modules/pt/pt_util.md) General utilities
+ [pt_export_api](tcllib/files/modules/pt/pt_to_api.md) Parser Tools Export API
+ [pt_import_api](tcllib/files/modules/pt/pt_from_api.md) Parser Tools Import API
+ [pt_introduction](tcllib/files/modules/pt/pt_introduction.md) Introduction to Parser Tools
+ [pt_parse_peg](tcllib/files/modules/pt/pt_parse_peg.md) Parser Tools PEG Parser
+ [pt_parser_api](tcllib/files/modules/pt/pt_parser_api.md) Parser API
+ [pt_peg_op](tcllib/files/modules/pt/pt_peg_op.md) Parser Tools PE Grammar Utility Operations
* [rc4]()
+ [rc4](tcllib/files/modules/rc4/rc4.md) Implementation of the RC4 stream cipher
* [rcs]()
+ [rcs](tcllib/files/modules/rcs/rcs.md) RCS low level utilities
* [report]()
+ [report](tcllib/files/modules/report/report.md) Create and manipulate report objects
* [rest]()
+ [rest](tcllib/files/modules/rest/rest.md) define REST web APIs and call them inline or asychronously
* [ripemd]()
+ [ripemd128](tcllib/files/modules/ripemd/ripemd128.md) RIPEMD-128 Message-Digest Algorithm
+ [ripemd160](tcllib/files/modules/ripemd/ripemd160.md) RIPEMD-160 Message-Digest Algorithm
* [sasl]()
+ [SASL](tcllib/files/modules/sasl/sasl.md) Implementation of SASL mechanisms for Tcl
+ [SASL::NTLM](tcllib/files/modules/sasl/ntlm.md) Implementation of SASL NTLM mechanism for Tcl
+ [SASL::SCRAM](tcllib/files/modules/sasl/scram.md) Implementation of SASL SCRAM mechanism for Tcl
+ [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken.md) Implementation of SASL NTLM mechanism for Tcl
* [sha1]()
+ [sha1](tcllib/files/modules/sha1/sha1.md) SHA1 Message-Digest Algorithm
+ [sha256](tcllib/files/modules/sha1/sha256.md) SHA256 Message-Digest Algorithm
* [simulation]()
+ [simulation::annealing](tcllib/files/modules/simulation/annealing.md) Simulated annealing
+ [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo.md) Monte Carlo simulations
+ [simulation::random](tcllib/files/modules/simulation/simulation_random.md) Pseudo-random number generators
* [smtpd]()
+ [smtpd](tcllib/files/modules/smtpd/smtpd.md) Tcl SMTP server implementation
* [snit]()
+ [snit](tcllib/files/modules/snit/snit.md) Snit's Not Incr Tcl
+ [snitfaq](tcllib/files/modules/snit/snitfaq.md) Snit Frequently Asked Questions
* [soundex]()
+ [soundex](tcllib/files/modules/soundex/soundex.md) Soundex
* [stooop]()
+ [stooop](tcllib/files/modules/stooop/stooop.md) Object oriented extension.
+ [switched](tcllib/files/modules/stooop/switched.md) switch/option management.
* [string]()
+ [string::token](tcllib/files/modules/string/token.md) Regex based iterative lexing
+ [string::token::shell](tcllib/files/modules/string/token_shell.md) Parsing of shell command line
* [stringprep]()
+ [stringprep](tcllib/files/modules/stringprep/stringprep.md) Implementation of stringprep
+ [stringprep::data](tcllib/files/modules/stringprep/stringprep_data.md) stringprep data tables, generated, internal
+ [unicode](tcllib/files/modules/stringprep/unicode.md) Implementation of Unicode normalization
+ [unicode::data](tcllib/files/modules/stringprep/unicode_data.md) unicode data tables, generated, internal
* [struct]()
+ [struct::disjointset](tcllib/files/modules/struct/disjointset.md) Disjoint set data structure
+ [struct::graph](tcllib/files/modules/struct/graph.md) Create and manipulate directed graph objects
+ [struct::graph::op](tcllib/files/modules/struct/graphops.md) Operation for (un)directed graph objects
+ [struct::graph_v1](tcllib/files/modules/struct/graph1.md) Create and manipulate directed graph objects
+ [struct::list](tcllib/files/modules/struct/struct_list.md) Procedures for manipulating lists
+ [struct::matrix](tcllib/files/modules/struct/matrix.md) Create and manipulate matrix objects
+ [struct::matrix_v1](tcllib/files/modules/struct/matrix1.md) Create and manipulate matrix objects
+ [struct::pool](tcllib/files/modules/struct/pool.md) Create and manipulate pool objects (of discrete items)
+ [struct::prioqueue](tcllib/files/modules/struct/prioqueue.md) Create and manipulate prioqueue objects
+ [struct::queue](tcllib/files/modules/struct/queue.md) Create and manipulate queue objects
+ [struct::record](tcllib/files/modules/struct/record.md) Define and create records (similar to 'C' structures)
+ [struct::set](tcllib/files/modules/struct/struct_set.md) Procedures for manipulating sets
+ [struct::skiplist](tcllib/files/modules/struct/skiplist.md) Create and manipulate skiplists
+ [struct::stack](tcllib/files/modules/struct/stack.md) Create and manipulate stack objects
+ [struct::tree](tcllib/files/modules/struct/struct_tree.md) Create and manipulate tree objects
+ [struct::tree_v1](tcllib/files/modules/struct/struct_tree1.md) Create and manipulate tree objects
* [tar]()
+ [tar](tcllib/files/modules/tar/tar.md) Tar file creation, extraction & manipulation
* [tepam]()
+ [tepam](tcllib/files/modules/tepam/tepam_introduction.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
+ [tepam::argument_dialogbox](tcllib/files/modules/tepam/tepam_argument_dialogbox.md) TEPAM argument_dialogbox, reference manual
+ [tepam::doc_gen](tcllib/files/modules/tepam/tepam_doc_gen.md) TEPAM DOC Generation, reference manual
+ [tepam::procedure](tcllib/files/modules/tepam/tepam_procedure.md) TEPAM procedure, reference manual
* [term]()
+ [term](tcllib/files/modules/term/term.md) General terminal control
+ [term::ansi::code](tcllib/files/modules/term/ansi_code.md) Helper for control sequences
+ [term::ansi::code::attr](tcllib/files/modules/term/ansi_cattr.md) ANSI attribute sequences
+ [term::ansi::code::ctrl](tcllib/files/modules/term/ansi_cctrl.md) ANSI control sequences
+ [term::ansi::code::macros](tcllib/files/modules/term/ansi_cmacros.md) Macro sequences
+ [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi_ctrlu.md) Control operations and queries
+ [term::ansi::send](tcllib/files/modules/term/ansi_send.md) Output of ANSI control sequences to terminals
+ [term::interact::menu](tcllib/files/modules/term/imenu.md) Terminal widget, menu
+ [term::interact::pager](tcllib/files/modules/term/ipager.md) Terminal widget, paging
+ [term::receive](tcllib/files/modules/term/receive.md) General input from terminals
+ [term::receive::bind](tcllib/files/modules/term/term_bind.md) Keyboard dispatch from terminals
+ [term::send](tcllib/files/modules/term/term_send.md) General output to terminals
* [textutil]()
+ [textutil](tcllib/files/modules/textutil/textutil.md) Procedures to manipulate texts and strings.
+ [textutil::adjust](tcllib/files/modules/textutil/adjust.md) Procedures to adjust, indent, and undent paragraphs
+ [textutil::expander](tcllib/files/modules/textutil/expander.md) Procedures to process templates and expand text.
+ [textutil::repeat](tcllib/files/modules/textutil/repeat.md) Procedures to repeat strings.
+ [textutil::split](tcllib/files/modules/textutil/textutil_split.md) Procedures to split texts
+ [textutil::string](tcllib/files/modules/textutil/textutil_string.md) Procedures to manipulate texts and strings.
+ [textutil::tabify](tcllib/files/modules/textutil/tabify.md) Procedures to (un)tabify strings
+ [textutil::trim](tcllib/files/modules/textutil/trim.md) Procedures to trim strings
* [tie]()
+ [tie](tcllib/files/modules/tie/tie.md) Array persistence
+ [tie](tcllib/files/modules/tie/tie_std.md) Array persistence, standard data sources
* [tiff]()
+ [tiff](tcllib/files/modules/tiff/tiff.md) TIFF reading, writing, and querying and manipulation of meta data
* [tool]()
+ [oo::util](tcllib/files/modules/tool/meta.md) Utility commands for TclOO
+ [tool](tcllib/files/modules/tool/tool.md) TclOO Library (TOOL) Framework
+ [tool::dict_ensemble](tcllib/files/modules/tool/tool_dict_ensemble.md) Dictionary Tools
* [transfer]()
+ [transfer::connect](tcllib/files/modules/transfer/connect.md) Connection setup
+ [transfer::copy](tcllib/files/modules/transfer/copyops.md) Data transfer foundation
+ [transfer::copy::queue](tcllib/files/modules/transfer/tqueue.md) Queued transfers
+ [transfer::data::destination](tcllib/files/modules/transfer/ddest.md) Data destination
+ [transfer::data::source](tcllib/files/modules/transfer/dsource.md) Data source
+ [transfer::receiver](tcllib/files/modules/transfer/receiver.md) Data source
+ [transfer::transmitter](tcllib/files/modules/transfer/transmitter.md) Data source
* [treeql]()
+ [treeql](tcllib/files/modules/treeql/treeql.md) Query tree objects
* [try]()
+ [throw](tcllib/files/modules/try/tcllib_throw.md) throw - Throw an error exception with a message
+ [try](tcllib/files/modules/try/tcllib_try.md) try - Trap and process errors and exceptions
* [udpcluster]()
+ [udpcluster](tcllib/files/modules/udpcluster/udpcluster.md) UDP Peer-to-Peer cluster
* [uev]()
+ [uevent](tcllib/files/modules/uev/uevent.md) User events
+ [uevent::onidle](tcllib/files/modules/uev/uevent_onidle.md) Request merging and deferal to idle time
* [units]()
+ [units](tcllib/files/modules/units/units.md) unit conversion
* [uri]()
+ [uri](tcllib/files/modules/uri/uri.md) URI utilities
+ [uri_urn](tcllib/files/modules/uri/urn-scheme.md) URI utilities, URN scheme
* [uuid]()
+ [uuid](tcllib/files/modules/uuid/uuid.md) UUID generation and comparison
* [valtype]()
+ [valtype::common](tcllib/files/modules/valtype/valtype_common.md) Validation, common code
+ [valtype::creditcard::amex](tcllib/files/modules/valtype/cc_amex.md) Validation for AMEX creditcard number
+ [valtype::creditcard::discover](tcllib/files/modules/valtype/cc_discover.md) Validation for Discover creditcard number
+ [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc_mastercard.md) Validation for Mastercard creditcard number
+ [valtype::creditcard::visa](tcllib/files/modules/valtype/cc_visa.md) Validation for VISA creditcard number
+ [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13.md) Validation for EAN13
+ [valtype::iban](tcllib/files/modules/valtype/iban.md) Validation for IBAN
+ [valtype::imei](tcllib/files/modules/valtype/imei.md) Validation for IMEI
+ [valtype::isbn](tcllib/files/modules/valtype/isbn.md) Validation for ISBN
+ [valtype::luhn](tcllib/files/modules/valtype/luhn.md) Validation for plain number with a LUHN checkdigit
+ [valtype::luhn5](tcllib/files/modules/valtype/luhn5.md) Validation for plain number with a LUHN5 checkdigit
+ [valtype::usnpi](tcllib/files/modules/valtype/usnpi.md) Validation for USNPI
+ [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff.md) Validation for plain number with a VERHOEFF checkdigit
* [virtchannel_base]()
+ [tcl::chan::cat](tcllib/files/modules/virtchannel_base/cat.md) Concatenation channel
+ [tcl::chan::facade](tcllib/files/modules/virtchannel_base/facade.md) Facade channel
+ [tcl::chan::fifo](tcllib/files/modules/virtchannel_base/tcllib_fifo.md) In-memory fifo channel
+ [tcl::chan::fifo2](tcllib/files/modules/virtchannel_base/tcllib_fifo2.md) In-memory interconnected fifo channels
+ [tcl::chan::halfpipe](tcllib/files/modules/virtchannel_base/halfpipe.md) In-memory channel, half of a fifo2
+ [tcl::chan::memchan](tcllib/files/modules/virtchannel_base/tcllib_memchan.md) In-memory channel
+ [tcl::chan::null](tcllib/files/modules/virtchannel_base/tcllib_null.md) Null channel
+ [tcl::chan::nullzero](tcllib/files/modules/virtchannel_base/nullzero.md) Null/Zero channel combination
+ [tcl::chan::random](tcllib/files/modules/virtchannel_base/tcllib_random.md) Random channel
+ [tcl::chan::std](tcllib/files/modules/virtchannel_base/std.md) Standard I/O, unification of stdin and stdout
+ [tcl::chan::string](tcllib/files/modules/virtchannel_base/tcllib_string.md) Read-only in-memory channel
+ [tcl::chan::textwindow](tcllib/files/modules/virtchannel_base/textwindow.md) Textwindow channel
+ [tcl::chan::variable](tcllib/files/modules/virtchannel_base/tcllib_variable.md) In-memory channel using variable for storage
+ [tcl::chan::zero](tcllib/files/modules/virtchannel_base/tcllib_zero.md) Zero channel
+ [tcl::randomseed](tcllib/files/modules/virtchannel_base/randseed.md) Utilities for random channels
* [virtchannel_core]()
+ [tcl::chan::core](tcllib/files/modules/virtchannel_core/core.md) Basic reflected/virtual channel support
+ [tcl::chan::events](tcllib/files/modules/virtchannel_core/events.md) Event support for reflected/virtual channels
+ [tcl::transform::core](tcllib/files/modules/virtchannel_core/transformcore.md) Basic reflected/virtual channel transform support
* [virtchannel_transform]()
+ [tcl::transform::adler32](tcllib/files/modules/virtchannel_transform/adler32.md) Adler32 transformation
+ [tcl::transform::base64](tcllib/files/modules/virtchannel_transform/vt_base64.md) Base64 encoding transformation
+ [tcl::transform::counter](tcllib/files/modules/virtchannel_transform/vt_counter.md) Counter transformation
+ [tcl::transform::crc32](tcllib/files/modules/virtchannel_transform/vt_crc32.md) Crc32 transformation
+ [tcl::transform::hex](tcllib/files/modules/virtchannel_transform/hex.md) Hexadecimal encoding transformation
+ [tcl::transform::identity](tcllib/files/modules/virtchannel_transform/identity.md) Identity transformation
+ [tcl::transform::limitsize](tcllib/files/modules/virtchannel_transform/limitsize.md) limiting input
+ [tcl::transform::observe](tcllib/files/modules/virtchannel_transform/observe.md) Observer transformation, stream copy
+ [tcl::transform::otp](tcllib/files/modules/virtchannel_transform/vt_otp.md) Encryption via one-time pad
+ [tcl::transform::rot](tcllib/files/modules/virtchannel_transform/rot.md) rot-encryption
+ [tcl::transform::spacer](tcllib/files/modules/virtchannel_transform/spacer.md) Space insertation and removal
+ [tcl::transform::zlib](tcllib/files/modules/virtchannel_transform/tcllib_zlib.md) zlib (de)compression
* [websocket]()
+ [websocket](tcllib/files/modules/websocket/websocket.md) Tcl implementation of the websocket protocol
* [wip]()
+ [wip](tcllib/files/modules/wip/wip.md) Word Interpreter
* [yaml]()
+ [huddle](tcllib/files/modules/yaml/huddle.md) Create and manipulate huddle object
+ [yaml](tcllib/files/modules/yaml/yaml.md) YAML Format Encoder/Decoder
* [zip]()
+ [zipfile::decode](tcllib/files/modules/zip/decode.md) Access to zip archives
+ [zipfile::encode](tcllib/files/modules/zip/encode.md) Generation of zip archives
+ [zipfile::mkzip](tcllib/files/modules/zip/mkzip.md) Build a zip archive
|
Added embedded/md/toc2.md.
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown')
# Table Of Contents --
- [Applications]()
* [dtplite](tcllib/files/apps/dtplite.md) Lightweight DocTools Markup Processor
* [nns](tcllib/files/apps/nns.md) Name service facility, Commandline Client Application
* [nnsd](tcllib/files/apps/nnsd.md) Name service facility, Commandline Server Application
* [nnslog](tcllib/files/apps/nnslog.md) Name service facility, Commandline Logging Client Application
* [page](tcllib/files/apps/page.md) Parser Generator
* [pt](tcllib/files/apps/pt.md) Parser Tools Application
* [tcldocstrip](tcllib/files/apps/tcldocstrip.md) Tcl-based Docstrip Processor
|
Deleted embedded/www/image/arch_core_container.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_core_eplugins.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_core_export.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_core_import.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_core_iplugins.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_core_support.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_core_transform.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_user_app.png.
cannot compute difference between binary files
Deleted embedded/www/image/arch_user_pkg.png.
cannot compute difference between binary files
Deleted embedded/www/image/architecture.png.
cannot compute difference between binary files
Deleted embedded/www/image/expr_ast.png.
cannot compute difference between binary files
Deleted embedded/www/image/flow.png.
cannot compute difference between binary files
Deleted embedded/www/image/gen_options.png.
cannot compute difference between binary files
Deleted embedded/www/index.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
|
<div class='fossil-doc' data-title='Keyword Index'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="toc.html">Table Of Contents</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Keyword Index </h3>
<hr><div class="#doctools_idxnav">
<a href="#c3"> 3 </a> · <a href="#cA"> A </a> · <a href="#cB"> B </a> · <a href="#cC"> C </a> · <a href="#cD"> D </a> · <a href="#cE"> E </a> · <a href="#cF"> F </a> · <a href="#cG"> G </a> · <a href="#cH"> H </a> · <a href="#cI"> I </a> · <a href="#cJ"> J </a> · <a href="#cK"> K </a> · <a href="#cL"> L </a> · <a href="#cM"> M </a> · <a href="#cN"> N </a> · <a href="#cO"> O </a> · <a href="#cP"> P </a> · <a href="#cQ"> Q </a> · <a href="#cR"> R </a> · <a href="#cS"> S </a> · <a href="#cT"> T </a> · <a href="#cU"> U </a> · <a href="#cV"> V </a> · <a href="#cW"> W </a> · <a href="#cX"> X </a> · <a href="#cY"> Y </a> · <a href="#cZ"> Z </a>
</div>
<hr><table class="#doctools_idx" width="100%">
<tr class="#doctools_idxheader"><th colspan="2">
<a name="c3">Keywords: 3</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="3des"> 3DES </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/des/des.html"> des </a> · <a href="tcllib/files/modules/des/tcldes.html"> tclDES </a> · <a href="tcllib/files/modules/des/tcldesjr.html"> tclDESjr </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cA">Keywords: A</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="abstract_syntax_tree"> abstract syntax tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_util.html"> grammar::me::util </a> · <a href="tcllib/files/modules/grammar_me/me_ast.html"> grammar::me_ast </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="acceptance"> acceptance </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="acceptor"> acceptor </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="active"> active </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="adaptors"> adaptors </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="adjacency_list"> adjacency list </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="adjacency_matrix"> adjacency matrix </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="adjacent"> adjacent </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="adjusting"> adjusting </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="adler32"> adler32 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="aes"> aes </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/aes/aes.html"> aes </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="after"> after </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="alias"> alias </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/tcllib_interp.html"> interp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="amazon"> amazon </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/amazon-s3/S3.html"> S3 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ambiguous"> ambiguous </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="american_express"> American Express </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="amex"> AMEX </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="angle"> angle </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/math_geometry.html"> math::geometry </a> · <a href="tcllib/files/modules/units/units.html"> units </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="anonymous_procedure"> anonymous procedure </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/lambda/lambda.html"> lambda </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ansi"> ansi </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_cattr.html"> term::ansi::code::attr </a> · <a href="tcllib/files/modules/term/ansi_cctrl.html"> term::ansi::code::ctrl </a> · <a href="tcllib/files/modules/term/ansi_cmacros.html"> term::ansi::code::macros </a> · <a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="appender"> appender </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/log/loggerAppender.html"> logger::appender </a> · <a href="tcllib/files/modules/log/loggerUtils.html"> logger::utils </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="application"> application </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/apps/nns.html"> nns </a> · <a href="tcllib/files/apps/nnsd.html"> nnsd </a> · <a href="tcllib/files/apps/nnslog.html"> nnslog </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="approximation_algorithm"> approximation algorithm </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="arc"> arc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="arcfour"> arcfour </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rc4/rc4.html"> rc4 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="archive"> archive </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tar/tar.html"> tar </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="argument_integrity"> argument integrity </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a> · <a href="tcllib/files/modules/tepam/tepam_procedure.html"> tepam::procedure </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="argument_processing"> argument processing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cmdline/cmdline.html"> cmdline </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="argument_validation"> argument validation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a> · <a href="tcllib/files/modules/tepam/tepam_procedure.html"> tepam::procedure </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="arguments"> arguments </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a> · <a href="tcllib/files/modules/tepam/tepam_procedure.html"> tepam::procedure </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="argv"> argv </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cmdline/cmdline.html"> cmdline </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="argv0"> argv0 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cmdline/cmdline.html"> cmdline </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="array"> array </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="articulation_point"> articulation point </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ascii85"> ascii85 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/ascii85.html"> ascii85 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="asn"> asn </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="assembler"> assembler </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/gasm.html"> grammar::me::cpu::gasm </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="assert"> assert </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/control/control.html"> control </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="assign"> assign </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ast"> AST </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_ast.html"> grammar::me_ast </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="asynchronous"> asynchronous </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cache/async.html"> cache::async </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="attribute_control"> attribute control </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_cattr.html"> term::ansi::code::attr </a> · <a href="tcllib/files/modules/term/ansi_cctrl.html"> term::ansi::code::ctrl </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="augmenting_network"> augmenting network </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="augmenting_path"> augmenting path </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="authentication"> authentication </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/http/autoproxy.html"> autoproxy </a> · <a href="tcllib/files/modules/sasl/sasl.html"> SASL </a> · <a href="tcllib/files/modules/sasl/ntlm.html"> SASL::NTLM </a> · <a href="tcllib/files/modules/sasl/scram.html"> SASL::SCRAM </a> · <a href="tcllib/files/modules/sasl/gtoken.html"> SASL::XGoogleToken </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="automatic"> automatic </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nns/nns_auto.html"> nameserv::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="automatic_documentation"> automatic documentation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_doc_gen.html"> tepam::doc_gen </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="automaton"> automaton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="aycock"> aycock </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cB">Keywords: B</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bank"> bank </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="base32"> base32 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base32/base32.html"> base32 </a> · <a href="tcllib/files/modules/base32/base32core.html"> base32::core </a> · <a href="tcllib/files/modules/base32/base32hex.html"> base32::hex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="base64"> base64 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/base64.html"> base64 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bash"> bash </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/string/token_shell.html"> string::token::shell </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bee"> bee </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bee/bee.html"> bee </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bench_language"> bench language </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_intro.html"> bench_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_intro.html"> bench_lang_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_spec.html"> bench_lang_spec </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="benchmark"> benchmark </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench.html"> bench </a> · <a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wcsv.html"> bench::out::csv </a> · <a href="tcllib/files/modules/bench/bench_wtext.html"> bench::out::text </a> · <a href="tcllib/files/modules/bench/bench_intro.html"> bench_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_intro.html"> bench_lang_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_spec.html"> bench_lang_spec </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ber"> ber </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bessel_functions"> Bessel functions </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/special.html"> math::special </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bfs"> bfs </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bibliography"> bibliography </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bibtex/bibtex.html"> bibtex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bibtex"> bibtex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bibtex/bibtex.html"> bibtex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bignums"> bignums </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/bignum.html"> math::bignum </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bind"> bind </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uev/uevent.html"> uevent </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bipartite"> bipartite </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bittorrent"> BitTorrent </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bee/bee.html"> bee </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bittorrent"> bittorrent </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bee/bee.html"> bee </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="blanks"> blanks </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/repeat.html"> textutil::repeat </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="block_cipher"> block cipher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/aes/aes.html"> aes </a> · <a href="tcllib/files/modules/blowfish/blowfish.html"> blowfish </a> · <a href="tcllib/files/modules/des/des.html"> des </a> · <a href="tcllib/files/modules/des/tcldes.html"> tclDES </a> · <a href="tcllib/files/modules/des/tcldesjr.html"> tclDESjr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="blocking_flow"> blocking flow </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="blowfish"> blowfish </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/blowfish/blowfish.html"> blowfish </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="book_number"> Book Number </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="breadth_first"> breadth-first </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bridge"> bridge </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="bwidget"> BWidget </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cC">Keywords: C</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="c"> C </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="c_"> C++ </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a> · <a href="tcllib/files/modules/stooop/stooop.html"> stooop </a> · <a href="tcllib/files/modules/stooop/switched.html"> switched </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cache"> cache </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cache/async.html"> cache::async </a> · <a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="caesar_cipher"> caesar cipher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="calculus"> calculus </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/calculus.html"> math::calculus </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="callback"> callback </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cache/async.html"> cache::async </a> · <a href="tcllib/files/modules/hook/hook.html"> hook </a> · <a href="tcllib/files/modules/lambda/lambda.html"> lambda </a> · <a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a> · <a href="tcllib/files/modules/uev/uevent_onidle.html"> uevent::onidle </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="callbacks"> callbacks </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/halfpipe.html"> tcl::chan::halfpipe </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="capitalize"> capitalize </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="card_for_credit"> card for credit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cardinality"> cardinality </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cat"> cat </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="catalog_package"> catalog package </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="catalogue"> catalogue </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cell_phone"> cell-phone </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cer"> cer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cfg"> CFG </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cfl"> CFL </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cgi"> CGI </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ncgi/ncgi.html"> ncgi </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cgraph"> cgraph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graph1.html"> struct::graph_v1 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="changelog"> changelog </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/changelog.html"> doctools::changelog </a> · <a href="tcllib/files/modules/doctools/cvs.html"> doctools::cvs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="channel"> channel </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a> · <a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a> · <a href="tcllib/files/modules/transfer/copyops.html"> transfer::copy </a> · <a href="tcllib/files/modules/transfer/tqueue.html"> transfer::copy::queue </a> · <a href="tcllib/files/modules/transfer/ddest.html"> transfer::data::destination </a> · <a href="tcllib/files/modules/transfer/dsource.html"> transfer::data::source </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="channel_transformation"> channel transformation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_counter.html"> tcl::transform::counter </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a> · <a href="tcllib/files/modules/virtchannel_transform/hex.html"> tcl::transform::hex </a> · <a href="tcllib/files/modules/virtchannel_transform/identity.html"> tcl::transform::identity </a> · <a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a> · <a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a> · <a href="tcllib/files/modules/virtchannel_transform/spacer.html"> tcl::transform::spacer </a> · <a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="character_input"> character input </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/receive.html"> term::receive </a> · <a href="tcllib/files/modules/term/term_bind.html"> term::receive::bind </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="character_output"> character output </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_send.html"> term::ansi::send </a> · <a href="tcllib/files/modules/term/term_send.html"> term::send </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="chat"> chat </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/irc/irc.html"> irc </a> · <a href="tcllib/files/modules/multiplexer/multiplexer.html"> multiplexer </a> · <a href="tcllib/files/modules/irc/picoirc.html"> picoirc </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="checkbox"> checkbox </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/html/html.html"> html </a> · <a href="tcllib/files/modules/javascript/javascript.html"> javascript </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="checkbutton"> checkbutton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/html/html.html"> html </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="checking"> Checking </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/valtype_common.html"> valtype::common </a> · <a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a> · <a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a> · <a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a> · <a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a> · <a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="checksum"> checksum </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a> · <a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="chop"> chop </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cipher"> cipher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pki/pki.html"> pki </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cksum"> cksum </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="class"> class </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a> · <a href="tcllib/files/modules/stooop/stooop.html"> stooop </a> · <a href="tcllib/files/modules/stooop/switched.html"> switched </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="class_methods"> class methods </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="class_variables"> class variables </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cleanup"> cleanup </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/defer/defer.html"> defer </a> · <a href="tcllib/files/modules/try/tcllib_try.html"> try </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="client"> client </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nns/nns_client.html"> nameserv </a> · <a href="tcllib/files/modules/nns/nns_auto.html"> nameserv::auto </a> · <a href="tcllib/files/modules/nns/nns_common.html"> nameserv::common </a> · <a href="tcllib/files/apps/nns.html"> nns </a> · <a href="tcllib/files/modules/nns/nns_intro.html"> nns_intro </a> · <a href="tcllib/files/apps/nnslog.html"> nnslog </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cloud"> cloud </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/amazon-s3/S3.html"> S3 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cmdline_processing"> cmdline processing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cmdline/cmdline.html"> cmdline </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="color_control"> color control </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_cattr.html"> term::ansi::code::attr </a> · <a href="tcllib/files/modules/term/ansi_cctrl.html"> term::ansi::code::ctrl </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="columns"> columns </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="comm"> comm </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a> · <a href="tcllib/files/modules/interp/deleg_method.html"> deleg_method </a> · <a href="tcllib/files/modules/interp/deleg_proc.html"> deleg_proc </a> · <a href="tcllib/files/modules/nns/nns_protocol.html"> nameserv::protocol </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="command"> command </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcl_parse.html"> doctools::tcl::parse </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="command_line_processing"> command line processing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cmdline/cmdline.html"> cmdline </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="command_prefix"> command prefix </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/lambda/lambda.html"> lambda </a> · <a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="comment"> comment </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/jpeg/jpeg.html"> jpeg </a> · <a href="tcllib/files/modules/png/png.html"> png </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="common"> common </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="common_prefix"> common prefix </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="communication"> communication </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="comparison"> comparison </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="complete_graph"> complete graph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="complex_numbers"> complex numbers </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/qcomplex.html"> math::complexnumbers </a> · <a href="tcllib/files/modules/math/fourier.html"> math::fourier </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="compression"> compression </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a> · <a href="tcllib/files/modules/zip/encode.html"> zipfile::encode </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="computations"> computations </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/bigfloat.html"> math::bigfloat </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="concatenation_channel"> concatenation channel </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/cat.html"> tcl::chan::cat </a> · <a href="tcllib/files/modules/virtchannel_base/facade.html"> tcl::chan::facade </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="connected_component"> connected component </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="connected_fifos"> connected fifos </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="connection"> connection </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="constants"> constants </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/constants.html"> math::constants </a> · <a href="tcllib/files/modules/units/units.html"> units </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="container"> CONTAINER </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="contents"> contents </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="context_free_grammar"> context-free grammar </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="context_free_languages"> context-free languages </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="control"> control </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/control/control.html"> control </a> · <a href="tcllib/files/modules/term/term.html"> term </a> · <a href="tcllib/files/modules/term/ansi_code.html"> term::ansi::code </a> · <a href="tcllib/files/modules/term/ansi_cattr.html"> term::ansi::code::attr </a> · <a href="tcllib/files/modules/term/ansi_cctrl.html"> term::ansi::code::ctrl </a> · <a href="tcllib/files/modules/term/ansi_cmacros.html"> term::ansi::code::macros </a> · <a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a> · <a href="tcllib/files/modules/term/ansi_send.html"> term::ansi::send </a> · <a href="tcllib/files/modules/term/imenu.html"> term::interact::menu </a> · <a href="tcllib/files/modules/term/ipager.html"> term::interact::pager </a> · <a href="tcllib/files/modules/term/receive.html"> term::receive </a> · <a href="tcllib/files/modules/term/term_bind.html"> term::receive::bind </a> · <a href="tcllib/files/modules/term/term_send.html"> term::send </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="control_structure"> control structure </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="conversion"> conversion </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/math/roman.html"> math::roman </a> · <a href="tcllib/files/modules/doctools/mpexpand.html"> mpexpand </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a> · <a href="tcllib/files/modules/units/units.html"> units </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cooked"> cooked </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cookie"> cookie </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ncgi/ncgi.html"> ncgi </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="copy"> copy </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/multi.html"> fileutil::multi </a> · <a href="tcllib/files/modules/fileutil/multiop.html"> fileutil::multi::op </a> · <a href="tcllib/files/modules/transfer/copyops.html"> transfer::copy </a> · <a href="tcllib/files/modules/transfer/tqueue.html"> transfer::copy::queue </a> · <a href="tcllib/files/modules/transfer/ddest.html"> transfer::data::destination </a> · <a href="tcllib/files/modules/transfer/dsource.html"> transfer::data::source </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="coroutine"> coroutine </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a> · <a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cost"> Cost </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="counter"> counter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/vt_counter.html"> tcl::transform::counter </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="counting"> counting </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/counter/counter.html"> counter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cparam"> CPARAM </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="crc"> crc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="crc16"> crc16 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/crc16.html"> crc16 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="crc32"> crc32 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="credit_card"> credit card </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cron"> cron </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cron/cron.html"> cron </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cryptography"> cryptography </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/blowfish/blowfish.html"> blowfish </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="css"> CSS </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/html_cssdefaults.html"> doctools::html::cssdefaults </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="csv"> csv </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wcsv.html"> bench::out::csv </a> · <a href="tcllib/files/modules/csv/csv.html"> csv </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="currying"> currying </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/lambda/lambda.html"> lambda </a> · <a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cut_edge"> cut edge </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cut_vertex"> cut vertex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cvs"> CVS </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cvs"> cvs </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/cvs.html"> doctools::cvs </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cvs_log"> cvs log </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/cvs.html"> doctools::cvs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="cyclic_redundancy_check"> cyclic redundancy check </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cD">Keywords: D</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_analysis"> data analysis </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/statistics.html"> math::statistics </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_destination"> data destination </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/ddest.html"> transfer::data::destination </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_entry_form"> data entry form </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html"> tepam::argument_dialogbox </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_exchange"> data exchange </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/modules/json/json.html"> json </a> · <a href="tcllib/files/modules/json/json_write.html"> json::write </a> · <a href="tcllib/files/modules/yaml/yaml.html"> yaml </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_integrity"> data integrity </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/aes/aes.html"> aes </a> · <a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/des/des.html"> des </a> · <a href="tcllib/files/modules/pki/pki.html"> pki </a> · <a href="tcllib/files/modules/rc4/rc4.html"> rc4 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a> · <a href="tcllib/files/modules/des/tcldes.html"> tclDES </a> · <a href="tcllib/files/modules/des/tcldesjr.html"> tclDESjr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_source"> data source </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/dsource.html"> transfer::data::source </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="data_structures"> data structures </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/record.html"> struct::record </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="database"> database </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dataflow"> dataflow </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_util_flow.html"> page_util_flow </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="_ddt"> .ddt </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="de"> DE </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="debug"> debug </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/debug/debug.html"> debug </a> · <a href="tcllib/files/modules/debug/debug_caller.html"> debug::caller </a> · <a href="tcllib/files/modules/debug/debug_heartbeat.html"> debug::heartbeat </a> · <a href="tcllib/files/modules/debug/debug_timestamp.html"> debug::timestamp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="decimal"> decimal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/decimal.html"> math::decimal </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="declare"> declare </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_code.html"> term::ansi::code </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="decompression"> decompression </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a> · <a href="tcllib/files/modules/zip/decode.html"> zipfile::decode </a> · <a href="tcllib/files/modules/zip/mkzip.html"> zipfile::mkzip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="decryption"> decryption </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="deferal"> deferal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uev/uevent_onidle.html"> uevent::onidle </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="define"> define </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_code.html"> term::ansi::code </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="degree"> degree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="degree_constrained_spanning_tree"> degree constrained spanning tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="degrees"> degrees </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/constants.html"> math::constants </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="delegation"> delegation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/deleg_method.html"> deleg_method </a> · <a href="tcllib/files/modules/interp/deleg_proc.html"> deleg_proc </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="depth_first"> depth-first </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="der"> der </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="des"> DES </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/des/des.html"> des </a> · <a href="tcllib/files/modules/des/tcldes.html"> tclDES </a> · <a href="tcllib/files/modules/des/tcldesjr.html"> tclDESjr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="deserialization"> deserialization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/import_docidx.html"> doctools::idx::import::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_import_json.html"> doctools::idx::import::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_structure.html"> doctools::idx::structure </a> · <a href="tcllib/files/modules/doctools2toc/import_doctoc.html"> doctools::toc::import::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import_json.html"> doctools::toc::import::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_structure.html"> doctools::toc::structure </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="_dev_null"> /dev/null </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_null.html"> tcl::chan::null </a> · <a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="_dev_random"> /dev/random </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_random.html"> tcl::chan::random </a> · <a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="_dev_zero"> /dev/zero </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html"> tcl::chan::zero </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="diameter"> diameter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dict"> dict </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dicttool/dicttool.html"> dicttool </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="diff"> diff </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="diff_n_format"> diff -n format </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="difference"> difference </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="differential"> differential </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="differential_equations"> differential equations </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/calculus.html"> math::calculus </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dijkstra"> dijkstra </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="directory_access"> directory access </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldap.html"> ldap </a> · <a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="directory_traversal"> directory traversal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/traverse.html"> fileutil_traverse </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="discover"> Discover </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="discrete_items"> discrete items </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/pool.html"> struct::pool </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="disjoint_set"> disjoint set </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dispatcher"> dispatcher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/term_bind.html"> term::receive::bind </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="distance"> distance </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/math_geometry.html"> math::geometry </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a> · <a href="tcllib/files/modules/units/units.html"> units </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dns"> DNS </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="do"> do </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/control/control.html"> control </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="docidx"> docidx </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/export_docidx.html"> doctools::idx::export::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2idx/import_docidx.html"> doctools::idx::import::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_parse.html"> doctools::idx::parse </a> · <a href="tcllib/files/modules/doctools2idx/idx_structure.html"> doctools::idx::structure </a> · <a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="docidx_commands"> docidx commands </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html"> docidx_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/docidx_lang_intro.html"> docidx_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_syntax.html"> docidx_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="docidx_language"> docidx language </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html"> docidx_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/docidx_lang_intro.html"> docidx_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_syntax.html"> docidx_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="docidx_markup"> docidx markup </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html"> docidx_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/docidx_lang_intro.html"> docidx_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_syntax.html"> docidx_lang_syntax </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="docidx_syntax"> docidx syntax </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/docidx_lang_intro.html"> docidx_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_syntax.html"> docidx_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="docstrip"> docstrip </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip.html"> docstrip </a> · <a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctoc"> doctoc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/export_doctoc.html"> doctools::toc::export::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/doctools2toc/import_doctoc.html"> doctools::toc::import::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_parse.html"> doctools::toc::parse </a> · <a href="tcllib/files/modules/doctools2toc/toc_structure.html"> doctools::toc::structure </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctoc_commands"> doctoc commands </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html"> doctoc_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_intro.html"> doctoc_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html"> doctoc_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctoc_language"> doctoc language </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html"> doctoc_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_intro.html"> doctoc_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html"> doctoc_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctoc_markup"> doctoc markup </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html"> doctoc_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_intro.html"> doctoc_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html"> doctoc_lang_syntax </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctoc_syntax"> doctoc syntax </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_intro.html"> doctoc_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html"> doctoc_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctools"> doctools </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/modules/doctools/changelog.html"> doctools::changelog </a> · <a href="tcllib/files/modules/doctools2base/html_cssdefaults.html"> doctools::html::cssdefaults </a> · <a href="tcllib/files/modules/doctools2idx/export_docidx.html"> doctools::idx::export::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_html.html"> doctools::idx::export::html </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_json.html"> doctools::idx::export::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html"> doctools::idx::export::nroff </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_text.html"> doctools::idx::export::text </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html"> doctools::idx::export::wiki </a> · <a href="tcllib/files/modules/doctools2idx/import_docidx.html"> doctools::idx::import::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_import_json.html"> doctools::idx::import::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_parse.html"> doctools::idx::parse </a> · <a href="tcllib/files/modules/doctools2idx/idx_structure.html"> doctools::idx::structure </a> · <a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a> · <a href="tcllib/files/modules/doctools2base/nroff_manmacros.html"> doctools::nroff::man_macros </a> · <a href="tcllib/files/modules/doctools2base/tcl_parse.html"> doctools::tcl::parse </a> · <a href="tcllib/files/modules/doctools2toc/export_doctoc.html"> doctools::toc::export::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_html.html"> doctools::toc::export::html </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_json.html"> doctools::toc::export::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html"> doctools::toc::export::nroff </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_text.html"> doctools::toc::export::text </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html"> doctools::toc::export::wiki </a> · <a href="tcllib/files/modules/doctools2toc/import_doctoc.html"> doctools::toc::import::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import_json.html"> doctools::toc::import::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_parse.html"> doctools::toc::parse </a> · <a href="tcllib/files/modules/doctools2toc/toc_structure.html"> doctools::toc::structure </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctools_commands"> doctools commands </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html"> doctools_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_intro.html"> doctools_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_syntax.html"> doctools_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctools_language"> doctools language </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html"> doctools_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_intro.html"> doctools_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_syntax.html"> doctools_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctools_markup"> doctools markup </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html"> doctools_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_intro.html"> doctools_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_syntax.html"> doctools_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="doctools_syntax"> doctools syntax </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_intro.html"> doctools_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_syntax.html"> doctools_lang_syntax </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="document"> document </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html"> doctools_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="documentation"> documentation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip.html"> docstrip </a> · <a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a> · <a href="tcllib/files/modules/tepam/tepam_doc_gen.html"> tepam::doc_gen </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dom"> DOM </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="dom"> dom </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/amazon-s3/xsxp.html"> xsxp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="domain_name_service"> domain name service </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="_dtx"> .dtx </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip.html"> docstrip </a> · <a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cE">Keywords: E</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="e"> e </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/constants.html"> math::constants </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ean"> EAN </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ean13"> EAN13 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="earley"> earley </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ebnf"> EBNF </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="eccentricity"> eccentricity </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="edge"> edge </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="emacs"> emacs </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/changelog.html"> doctools::changelog </a> · <a href="tcllib/files/modules/doctools/cvs.html"> doctools::cvs </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="email"> email </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a> · <a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="emptiness"> emptiness </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="empty_interpreter"> empty interpreter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/tcllib_interp.html"> interp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="en"> EN </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="encoding"> encoding </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/ascii85.html"> ascii85 </a> · <a href="tcllib/files/modules/base64/base64.html"> base64 </a> · <a href="tcllib/files/modules/base64/uuencode.html"> uuencode </a> · <a href="tcllib/files/modules/base64/yencode.html"> yencode </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="encryption"> encryption </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/aes/aes.html"> aes </a> · <a href="tcllib/files/modules/blowfish/blowfish.html"> blowfish </a> · <a href="tcllib/files/modules/des/des.html"> des </a> · <a href="tcllib/files/modules/pki/pki.html"> pki </a> · <a href="tcllib/files/modules/rc4/rc4.html"> rc4 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a> · <a href="tcllib/files/modules/des/tcldes.html"> tclDES </a> · <a href="tcllib/files/modules/des/tcldesjr.html"> tclDESjr </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="entry_mask"> entry mask </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="equal"> equal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="equality"> equality </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="equivalence_class"> equivalence class </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="error"> error </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/try/tcllib_throw.html"> throw </a> · <a href="tcllib/files/modules/try/tcllib_try.html"> try </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="error_function"> error function </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/special.html"> math::special </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="european_article_number"> European Article Number </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="event"> event </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a> · <a href="tcllib/files/modules/uev/uevent.html"> uevent </a> · <a href="tcllib/files/modules/uev/uevent_onidle.html"> uevent::onidle </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="event_management"> event management </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_core/events.html"> tcl::chan::events </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="events"> events </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="examples"> examples </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_lang_intro.html"> bench_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="exception"> exception </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/try/tcllib_try.html"> try </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="exchange_format"> exchange format </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/modules/json/json.html"> json </a> · <a href="tcllib/files/modules/json/json_write.html"> json::write </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="exclusion"> exclusion </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="execution"> execution </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="exif"> exif </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/jpeg/jpeg.html"> jpeg </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="exit"> exit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="export"> export </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/html_cssdefaults.html"> doctools::html::cssdefaults </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/export_docidx.html"> doctools::idx::export::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_html.html"> doctools::idx::export::html </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_json.html"> doctools::idx::export::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html"> doctools::idx::export::nroff </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_text.html"> doctools::idx::export::text </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html"> doctools::idx::export::wiki </a> · <a href="tcllib/files/modules/doctools2base/nroff_manmacros.html"> doctools::nroff::man_macros </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/export_doctoc.html"> doctools::toc::export::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_html.html"> doctools::toc::export::html </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_json.html"> doctools::toc::export::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html"> doctools::toc::export::nroff </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_text.html"> doctools::toc::export::text </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html"> doctools::toc::export::wiki </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="expression"> expression </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="extended_namespace"> extended namespace </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cF">Keywords: F</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="faq"> faq </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fetching_information"> fetching information </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fft"> FFT </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/fourier.html"> math::fourier </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fifo"> fifo </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html"> tcl::chan::fifo </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a> · <a href="tcllib/files/modules/virtchannel_base/halfpipe.html"> tcl::chan::halfpipe </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="file"> file </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a> · <a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="file_recognition"> file recognition </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fumagic/cfront.html"> fileutil::magic::cfront </a> · <a href="tcllib/files/modules/fumagic/cgen.html"> fileutil::magic::cgen </a> · <a href="tcllib/files/modules/fumagic/filetypes.html"> fileutil::magic::filetype </a> · <a href="tcllib/files/modules/fumagic/rtcore.html"> fileutil::magic::rt </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="file_type"> file type </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fumagic/cfront.html"> fileutil::magic::cfront </a> · <a href="tcllib/files/modules/fumagic/cgen.html"> fileutil::magic::cgen </a> · <a href="tcllib/files/modules/fumagic/filetypes.html"> fileutil::magic::filetype </a> · <a href="tcllib/files/modules/fumagic/rtcore.html"> fileutil::magic::rt </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="file_utilities"> file utilities </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a> · <a href="tcllib/files/modules/fumagic/cfront.html"> fileutil::magic::cfront </a> · <a href="tcllib/files/modules/fumagic/cgen.html"> fileutil::magic::cgen </a> · <a href="tcllib/files/modules/fumagic/filetypes.html"> fileutil::magic::filetype </a> · <a href="tcllib/files/modules/fumagic/rtcore.html"> fileutil::magic::rt </a> · <a href="tcllib/files/modules/fileutil/multi.html"> fileutil::multi </a> · <a href="tcllib/files/modules/fileutil/multiop.html"> fileutil::multi::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="filesystem"> filesystem </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="filter"> filter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a> · <a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="final"> final </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/try/tcllib_try.html"> try </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="finance"> finance </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="find"> find </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="finite"> finite </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/pool.html"> struct::pool </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="finite_automaton"> finite automaton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fips_180_1"> FIPS 180-1 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sha1/sha1.html"> sha1 </a> · <a href="tcllib/files/modules/sha1/sha256.html"> sha256 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="first_permutation"> first permutation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fisher_yates"> Fisher-Yates </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="flatten"> flatten </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="floating_point"> floating-point </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/bigfloat.html"> math::bigfloat </a> · <a href="tcllib/files/modules/math/fuzzy.html"> math::fuzzy </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="flow"> flow </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/control/control.html"> control </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="flow_network"> flow network </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="folding"> folding </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="foldl"> foldl </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="foldr"> foldr </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="foreach"> foreach </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="form"> form </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/html/html.html"> html </a> · <a href="tcllib/files/modules/ncgi/ncgi.html"> ncgi </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="format_conversion"> format conversion </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="formatter"> formatter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html"> doctools_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="formatting"> formatting </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wcsv.html"> bench::out::csv </a> · <a href="tcllib/files/modules/bench/bench_wtext.html"> bench::out::text </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a> · <a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a> · <a href="tcllib/files/modules/textutil/tabify.html"> textutil::tabify </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="formatting_engine"> formatting engine </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html"> doctools_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fourier_transform"> Fourier transform </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/fourier.html"> math::fourier </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="fr"> FR </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="frame"> frame </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_cmacros.html"> term::ansi::code::macros </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="framework"> framework </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/tool.html"> tool </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ftp"> ftp </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ftp/ftp.html"> ftp </a> · <a href="tcllib/files/modules/ftp/ftp_geturl.html"> ftp::geturl </a> · <a href="tcllib/files/modules/ftpd/ftpd.html"> ftpd </a> · <a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ftpd"> ftpd </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ftpd/ftpd.html"> ftpd </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ftpserver"> ftpserver </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ftpd/ftpd.html"> ftpd </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="full_outer_join"> full outer join </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cG">Keywords: G</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="generate_event"> generate event </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uev/uevent.html"> uevent </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="generate_permutations"> generate permutations </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="generation"> generation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="generator"> generator </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="geocoding"> geocoding </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="geodesy"> geodesy </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a> · <a href="tcllib/files/modules/mapproj/mapproj.html"> mapproj </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="geography"> geography </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="get_character"> get character </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/receive.html"> term::receive </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="gets"> gets </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="global"> global </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="golang"> golang </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/defer/defer.html"> defer </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="gopher"> gopher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="gps"> gps </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/gpx/gpx.html"> gpx </a> · <a href="tcllib/files/modules/nmea/nmea.html"> nmea </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="gpx"> gpx </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/gpx/gpx.html"> gpx </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="grammar"> grammar </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a> · <a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a> · <a href="tcllib/files/modules/grammar_me/me_cpu.html"> grammar::me::cpu </a> · <a href="tcllib/files/modules/grammar_me/me_cpucore.html"> grammar::me::cpu::core </a> · <a href="tcllib/files/modules/grammar_me/gasm.html"> grammar::me::cpu::gasm </a> · <a href="tcllib/files/modules/grammar_me/me_tcl.html"> grammar::me::tcl </a> · <a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_me/me_vm.html"> grammar::me_vm </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="graph"> graph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/gasm.html"> grammar::me::cpu::gasm </a> · <a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a> · <a href="tcllib/files/modules/struct/graph1.html"> struct::graph_v1 </a> · <a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/struct/stack.html"> struct::stack </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="graph_walking"> graph walking </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_util_flow.html"> page_util_flow </a> · <a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="green_threads"> green threads </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="grep"> grep </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="guid"> GUID </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uuid/uuid.html"> uuid </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cH">Keywords: H</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="hashing"> hashing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/md5crypt/md5crypt.html"> md5crypt </a> · <a href="tcllib/files/modules/otp/otp.html"> otp </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a> · <a href="tcllib/files/modules/sha1/sha1.html"> sha1 </a> · <a href="tcllib/files/modules/sha1/sha256.html"> sha256 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="heartbeat"> heartbeat </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/debug/debug_heartbeat.html"> debug::heartbeat </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="heuristic"> heuristic </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="hex"> hex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base32/base32hex.html"> base32::hex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="hexadecimal"> hexadecimal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/hex.html"> tcl::transform::hex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="histogram"> histogram </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/counter/counter.html"> counter </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="hook"> hook </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a> · <a href="tcllib/files/modules/uev/uevent.html"> uevent </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="horspool"> horspool </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="html"> HTML </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools2base/html_cssdefaults.html"> doctools::html::cssdefaults </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_html.html"> doctools::idx::export::html </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_html.html"> doctools::toc::export::html </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/doctools/mpexpand.html"> mpexpand </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="html"> html </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/html/html.html"> html </a> · <a href="tcllib/files/modules/htmlparse/htmlparse.html"> htmlparse </a> · <a href="tcllib/files/modules/javascript/javascript.html"> javascript </a> · <a href="tcllib/files/modules/ncgi/ncgi.html"> ncgi </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="http"> http </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/http/autoproxy.html"> autoproxy </a> · <a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a> · <a href="tcllib/files/modules/httpd/httpd.html"> tool </a> · <a href="tcllib/files/modules/uri/uri.html"> uri </a> · <a href="tcllib/files/modules/websocket/websocket.html"> websocket </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="httpd"> httpd </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/httpd/httpd.html"> tool </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="https"> https </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="httpserver"> httpserver </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/httpd/httpd.html"> tool </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="huddle"> huddle </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/modules/yaml/yaml.html"> yaml </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="human_readable"> human readable </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wtext.html"> bench::out::text </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="hyphenation"> hyphenation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cI">Keywords: I</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="i18n"> i18n </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="iban"> IBAN </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ident"> ident </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ident/ident.html"> ident </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="identification"> identification </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ident/ident.html"> ident </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="identity"> identity </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/identity.html"> tcl::transform::identity </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="idle"> idle </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uev/uevent_onidle.html"> uevent::onidle </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="image"> image </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/jpeg/jpeg.html"> jpeg </a> · <a href="tcllib/files/modules/png/png.html"> png </a> · <a href="tcllib/files/modules/tiff/tiff.html"> tiff </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="imap"> imap </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="imei"> IMEI </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="import"> import </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2idx/import_docidx.html"> doctools::idx::import::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_import_json.html"> doctools::idx::import::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/doctools2toc/import_doctoc.html"> doctools::toc::import::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import_json.html"> doctools::toc::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="in_memory_channel"> in-memory channel </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html"> tcl::chan::fifo </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a> · <a href="tcllib/files/modules/virtchannel_base/halfpipe.html"> tcl::chan::halfpipe </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html"> tcl::chan::memchan </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_string.html"> tcl::chan::string </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html"> tcl::chan::variable </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="in_order"> in-order </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="inclusion"> inclusion </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="incr_tcl"> Incr Tcl </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="indenting"> indenting </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="independent_set"> independent set </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="index"> index </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_intro.html"> docidx_intro </a> · <a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/export_docidx.html"> doctools::idx::export::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_html.html"> doctools::idx::export::html </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_json.html"> doctools::idx::export::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html"> doctools::idx::export::nroff </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_text.html"> doctools::idx::export::text </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html"> doctools::idx::export::wiki </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2idx/import_docidx.html"> doctools::idx::import::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_import_json.html"> doctools::idx::import::json </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="index_formatter"> index formatter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="info"> info </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="inner_join"> inner join </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="input_mode"> input mode </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="integer"> integer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/roman.html"> math::roman </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="integration"> integration </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/calculus.html"> math::calculus </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="inter_thread_communication"> inter-thread communication </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="international_article_number"> International Article Number </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="international_bank_account_number"> International Bank Account Number </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="international_mobile_equipment_identity"> International Mobile Equipment Identity </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="international_standard_book_number"> International Standard Book Number </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="internationalization"> internationalization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="internet"> internet </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a> · <a href="tcllib/files/modules/ftp/ftp.html"> ftp </a> · <a href="tcllib/files/modules/ftp/ftp_geturl.html"> ftp::geturl </a> · <a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a> · <a href="tcllib/files/modules/ldap/ldap.html"> ldap </a> · <a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a> · <a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/pop3d/pop3d_dbox.html"> pop3d::dbox </a> · <a href="tcllib/files/modules/pop3d/pop3d_udb.html"> pop3d::udb </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a> · <a href="tcllib/files/modules/websocket/websocket.html"> websocket </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="internet_address"> internet address </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_ip.html"> tcllib_ip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="interpolation"> interpolation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/interpolate.html"> math::interpolate </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="interpreter"> interpreter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/deleg_method.html"> deleg_method </a> · <a href="tcllib/files/modules/interp/deleg_proc.html"> deleg_proc </a> · <a href="tcllib/files/modules/interp/tcllib_interp.html"> interp </a> · <a href="tcllib/files/modules/wip/wip.html"> wip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="intersection"> intersection </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="interval"> interval </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/bigfloat.html"> math::bigfloat </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ip"> ip </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_ip.html"> tcllib_ip </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ipc"> ipc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ipv4"> ipv4 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_ip.html"> tcllib_ip </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ipv6"> ipv6 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_ip.html"> tcllib_ip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="irc"> irc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/irc/irc.html"> irc </a> · <a href="tcllib/files/modules/irc/picoirc.html"> picoirc </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="isa"> isA </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/valtype_common.html"> valtype::common </a> · <a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a> · <a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a> · <a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a> · <a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a> · <a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="isbn"> ISBN </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="isthmus"> isthmus </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="iterator"> iterator </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cJ">Keywords: J</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="javascript"> javascript </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/javascript/javascript.html"> javascript </a> · <a href="tcllib/files/modules/json/json.html"> json </a> · <a href="tcllib/files/modules/json/json_write.html"> json::write </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="jfif"> jfif </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/jpeg/jpeg.html"> jpeg </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="join"> join </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="jpeg"> jpeg </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/jpeg/jpeg.html"> jpeg </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="json"> JSON </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_export_json.html"> doctools::idx::export::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_import_json.html"> doctools::idx::import::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_json.html"> doctools::toc::export::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_import_json.html"> doctools::toc::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="json"> json </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/modules/json/json.html"> json </a> · <a href="tcllib/files/modules/json/json_write.html"> json::write </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="justification"> justification </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cK">Keywords: K</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="keyword_index"> keyword index </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_intro.html"> docidx_intro </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="keywords"> keywords </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="knuth"> knuth </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/soundex/soundex.html"> soundex </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cL">Keywords: L</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="l10n"> l10n </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="lambda"> lambda </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/lambda/lambda.html"> lambda </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="latex"> LaTeX </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip.html"> docstrip </a> · <a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="latex"> latex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="latitute"> latitute </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ldap"> ldap </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldap.html"> ldap </a> · <a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a> · <a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ldap_client"> ldap client </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldap.html"> ldap </a> · <a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ldif"> ldif </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="least_squares"> least squares </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="left_outer_join"> left outer join </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="lemon"> lemon </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="level_graph"> level graph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="lexer"> lexer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_parse.html"> doctools::idx::parse </a> · <a href="tcllib/files/modules/doctools2toc/toc_parse.html"> doctools::toc::parse </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="lexing"> lexing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/string/token.html"> string::token </a> · <a href="tcllib/files/modules/string/token_shell.html"> string::token::shell </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="limitsize"> limitsize </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="line"> line </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/math_geometry.html"> math::geometry </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="linear_algebra"> linear algebra </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="linear_equations"> linear equations </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="linear_program"> linear program </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/optimize.html"> math::optimize </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="lines"> lines </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="list"> list </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a> · <a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/wip/wip.html"> wip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="listener"> listener </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/receive.html"> term::receive </a> · <a href="tcllib/files/modules/term/term_bind.html"> term::receive::bind </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="literate_programming"> literate programming </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip.html"> docstrip </a> · <a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ll_k_"> LL(k) </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="local_searching"> local searching </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="localization"> localization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="location"> location </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a> · <a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a> · <a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="log"> log </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/debug/debug.html"> debug </a> · <a href="tcllib/files/modules/debug/debug_caller.html"> debug::caller </a> · <a href="tcllib/files/modules/debug/debug_heartbeat.html"> debug::heartbeat </a> · <a href="tcllib/files/modules/debug/debug_timestamp.html"> debug::timestamp </a> · <a href="tcllib/files/modules/doctools/cvs.html"> doctools::cvs </a> · <a href="tcllib/files/modules/log/log.html"> log </a> · <a href="tcllib/files/modules/log/logger.html"> logger </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="log_level"> log level </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/log/log.html"> log </a> · <a href="tcllib/files/modules/log/logger.html"> logger </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="logger"> logger </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/log/logger.html"> logger </a> · <a href="tcllib/files/modules/log/loggerAppender.html"> logger::appender </a> · <a href="tcllib/files/modules/log/loggerUtils.html"> logger::utils </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="longest_common_subsequence"> longest common subsequence </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="longitude"> longitude </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="loop"> loop </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="luhn"> luhn </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="luhn_5"> luhn-5 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cM">Keywords: M</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="macros"> macros </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/nroff_manmacros.html"> doctools::nroff::man_macros </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mail"> mail </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a> · <a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mailto"> mailto </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="man_macros"> man_macros </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/nroff_manmacros.html"> doctools::nroff::man_macros </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="manpage"> manpage </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html"> doctools_plugin_apiref </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/doctools/mpexpand.html"> mpexpand </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="map"> map </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a> · <a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a> · <a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a> · <a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a> · <a href="tcllib/files/modules/mapproj/mapproj.html"> mapproj </a> · <a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="markup"> markup </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_intro.html"> docidx_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html"> docidx_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/docidx_lang_intro.html"> docidx_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_syntax.html"> docidx_lang_syntax </a> · <a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctoc_intro.html"> doctoc_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html"> doctoc_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_intro.html"> doctoc_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html"> doctoc_lang_syntax </a> · <a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/doctools/doctools_intro.html"> doctools_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html"> doctools_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_intro.html"> doctools_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_syntax.html"> doctools_lang_syntax </a> · <a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html"> doctools_plugin_apiref </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/doctools/mpexpand.html"> mpexpand </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mastercard"> MasterCard </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="matching"> matching </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="math"> math </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/math.html"> math </a> · <a href="tcllib/files/modules/math/bigfloat.html"> math::bigfloat </a> · <a href="tcllib/files/modules/math/bignum.html"> math::bignum </a> · <a href="tcllib/files/modules/math/calculus.html"> math::calculus </a> · <a href="tcllib/files/modules/math/qcomplex.html"> math::complexnumbers </a> · <a href="tcllib/files/modules/math/constants.html"> math::constants </a> · <a href="tcllib/files/modules/math/decimal.html"> math::decimal </a> · <a href="tcllib/files/modules/math/fuzzy.html"> math::fuzzy </a> · <a href="tcllib/files/modules/math/math_geometry.html"> math::geometry </a> · <a href="tcllib/files/modules/math/interpolate.html"> math::interpolate </a> · <a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a> · <a href="tcllib/files/modules/math/optimize.html"> math::optimize </a> · <a href="tcllib/files/modules/math/pca.html"> math::PCA </a> · <a href="tcllib/files/modules/math/polynomials.html"> math::polynomials </a> · <a href="tcllib/files/modules/math/rational_funcs.html"> math::rationalfunctions </a> · <a href="tcllib/files/modules/math/special.html"> math::special </a> · <a href="tcllib/files/modules/math/trig.html"> math::trig </a> · <a href="tcllib/files/modules/simulation/annealing.html"> simulation::annealing </a> · <a href="tcllib/files/modules/simulation/montecarlo.html"> simulation::montecarlo </a> · <a href="tcllib/files/modules/simulation/simulation_random.html"> simulation::random </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mathematics"> mathematics </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/fourier.html"> math::fourier </a> · <a href="tcllib/files/modules/math/statistics.html"> math::statistics </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="matrices"> matrices </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="matrix"> matrix </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/csv/csv.html"> csv </a> · <a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a> · <a href="tcllib/files/modules/report/report.html"> report </a> · <a href="tcllib/files/modules/struct/matrix.html"> struct::matrix </a> · <a href="tcllib/files/modules/struct/matrix1.html"> struct::matrix_v1 </a> · <a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/struct/stack.html"> struct::stack </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="max_cut"> max cut </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="maximum"> maximum </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/optimize.html"> math::optimize </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="maximum_flow"> maximum flow </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="md4"> md4 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="md5"> md5 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/md5crypt/md5crypt.html"> md5crypt </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="md5crypt"> md5crypt </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md5crypt/md5crypt.html"> md5crypt </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="medicare"> medicare </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mega_widget"> mega widget </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="membership"> membership </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="menu"> menu </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_cmacros.html"> term::ansi::code::macros </a> · <a href="tcllib/files/modules/term/imenu.html"> term::interact::menu </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="merge"> merge </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a> · <a href="tcllib/files/modules/uev/uevent_onidle.html"> uevent::onidle </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="merge_find"> merge find </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="merging"> merging </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench.html"> bench </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="message"> message </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a> · <a href="tcllib/files/modules/log/log.html"> log </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="message_catalog"> message catalog </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="message_level"> message level </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/log/log.html"> log </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="message_package"> message package </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html"> doctools::msgcat </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html"> doctools::msgcat::idx::c </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html"> doctools::msgcat::idx::de </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html"> doctools::msgcat::idx::en </a> · <a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html"> doctools::msgcat::idx::fr </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html"> doctools::msgcat::toc::c </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html"> doctools::msgcat::toc::de </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html"> doctools::msgcat::toc::en </a> · <a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html"> doctools::msgcat::toc::fr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="message_digest"> message-digest </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/md5crypt/md5crypt.html"> md5crypt </a> · <a href="tcllib/files/modules/otp/otp.html"> otp </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a> · <a href="tcllib/files/modules/sha1/sha1.html"> sha1 </a> · <a href="tcllib/files/modules/sha1/sha256.html"> sha256 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="metakit"> metakit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="method"> method </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/deleg_method.html"> deleg_method </a> · <a href="tcllib/files/modules/interp/tcllib_interp.html"> interp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="method_reference"> method reference </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mime"> mime </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fumagic/cfront.html"> fileutil::magic::cfront </a> · <a href="tcllib/files/modules/fumagic/cgen.html"> fileutil::magic::cgen </a> · <a href="tcllib/files/modules/fumagic/rtcore.html"> fileutil::magic::rt </a> · <a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="minimal_spanning_tree"> minimal spanning tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="minimum"> minimum </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/optimize.html"> math::optimize </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="minimum_cost_flow"> minimum cost flow </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="minimum_degree_spanning_tree"> minimum degree spanning tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="minimum_diameter_spanning_tree"> minimum diameter spanning tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="mobile_phone"> mobile phone </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="module"> module </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="montecarlo_simulation"> montecarlo simulation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/simulation/montecarlo.html"> simulation::montecarlo </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="move"> move </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/multi.html"> fileutil::multi </a> · <a href="tcllib/files/modules/fileutil/multiop.html"> fileutil::multi::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="multi_file"> multi-file </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/multi.html"> fileutil::multi </a> · <a href="tcllib/files/modules/fileutil/multiop.html"> fileutil::multi::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="multiplexer"> multiplexer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/multiplexer/multiplexer.html"> multiplexer </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="multiprecision"> multiprecision </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/bigfloat.html"> math::bigfloat </a> · <a href="tcllib/files/modules/math/bignum.html"> math::bignum </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="my_method"> my method </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cN">Keywords: N</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="name_service"> name service </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nns/nns_client.html"> nameserv </a> · <a href="tcllib/files/modules/nns/nns_auto.html"> nameserv::auto </a> · <a href="tcllib/files/modules/nns/nns_common.html"> nameserv::common </a> · <a href="tcllib/files/modules/nns/nns_protocol.html"> nameserv::protocol </a> · <a href="tcllib/files/modules/nns/nns_server.html"> nameserv::server </a> · <a href="tcllib/files/apps/nns.html"> nns </a> · <a href="tcllib/files/modules/nns/nns_intro.html"> nns_intro </a> · <a href="tcllib/files/apps/nnsd.html"> nnsd </a> · <a href="tcllib/files/apps/nnslog.html"> nnslog </a> · <a href="tcllib/files/modules/udpcluster/udpcluster.html"> udpcluster </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="namespace_unknown"> namespace unknown </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="namespace_utilities"> namespace utilities </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="narrative"> narrative </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/debug/debug.html"> debug </a> · <a href="tcllib/files/modules/debug/debug_caller.html"> debug::caller </a> · <a href="tcllib/files/modules/debug/debug_heartbeat.html"> debug::heartbeat </a> · <a href="tcllib/files/modules/debug/debug_timestamp.html"> debug::timestamp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="national_provider_identifier"> National Provider Identifier </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="neighbour"> neighbour </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="net"> net </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ftp/ftp.html"> ftp </a> · <a href="tcllib/files/modules/ftp/ftp_geturl.html"> ftp::geturl </a> · <a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a> · <a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a> · <a href="tcllib/files/modules/websocket/websocket.html"> websocket </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="nettool"> nettool </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nettool/nettool.html"> nettool </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="network"> network </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/pop3d/pop3d_dbox.html"> pop3d::dbox </a> · <a href="tcllib/files/modules/pop3d/pop3d_udb.html"> pop3d::udb </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="news"> news </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nntp/nntp.html"> nntp </a> · <a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="next_permutation"> next permutation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="nmea"> nmea </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nmea/nmea.html"> nmea </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="nntp"> nntp </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nntp/nntp.html"> nntp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="nntpclient"> nntpclient </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nntp/nntp.html"> nntp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="no_op"> no-op </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/control/control.html"> control </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="node"> node </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a> · <a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="nominatim"> nominatim </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="normalization"> normalization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench.html"> bench </a> · <a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a> · <a href="tcllib/files/modules/stringprep/unicode.html"> unicode </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="npi"> NPI </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="nroff"> nroff </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html"> doctools::idx::export::nroff </a> · <a href="tcllib/files/modules/doctools2base/nroff_manmacros.html"> doctools::nroff::man_macros </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html"> doctools::toc::export::nroff </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/doctools/mpexpand.html"> mpexpand </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ntlm"> NTLM </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sasl/ntlm.html"> SASL::NTLM </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ntp"> NTP </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ntp/ntp_time.html"> ntp_time </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="null"> null </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_null.html"> tcl::chan::null </a> · <a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="number_theory"> number theory </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/numtheory.html"> math::numtheory </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cO">Keywords: O</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="oauth"> oauth </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/oauth/oauth.html"> oauth </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="object"> object </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a> · <a href="tcllib/files/modules/stooop/stooop.html"> stooop </a> · <a href="tcllib/files/modules/stooop/switched.html"> switched </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="object_oriented"> object oriented </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a> · <a href="tcllib/files/modules/stooop/stooop.html"> stooop </a> · <a href="tcllib/files/modules/stooop/switched.html"> switched </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="observer"> observer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a> · <a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="odie"> odie </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cron/cron.html"> cron </a> · <a href="tcllib/files/modules/nettool/nettool.html"> nettool </a> · <a href="tcllib/files/modules/processman/processman.html"> processman </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="on_idle"> on-idle </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uev/uevent_onidle.html"> uevent::onidle </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="one_time_pad"> one time pad </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="optimization"> optimization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/optimize.html"> math::optimize </a> · <a href="tcllib/files/modules/simulation/annealing.html"> simulation::annealing </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ordered_list"> ordered list </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/prioqueue.html"> struct::prioqueue </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="otp"> otp </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="outer_join"> outer join </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cP">Keywords: P</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="package"> package </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/csv/csv.html"> csv </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="package_indexing"> package indexing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="page"> page </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_intro.html"> page_intro </a> · <a href="tcllib/files/modules/page/page_pluginmgr.html"> page_pluginmgr </a> · <a href="tcllib/files/modules/page/page_util_flow.html"> page_util_flow </a> · <a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a> · <a href="tcllib/files/modules/page/page_util_peg.html"> page_util_peg </a> · <a href="tcllib/files/modules/page/page_util_quote.html"> page_util_quote </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pager"> pager </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ipager.html"> term::interact::pager </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="paragraph"> paragraph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="param"> PARAM </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="parameter_entry_form"> parameter entry form </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a> · <a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html"> tepam::argument_dialogbox </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="parser"> parser </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_parse.html"> doctools::idx::parse </a> · <a href="tcllib/files/modules/doctools2base/tcl_parse.html"> doctools::tcl::parse </a> · <a href="tcllib/files/modules/doctools2toc/toc_parse.html"> doctools::toc::parse </a> · <a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a> · <a href="tcllib/files/modules/amazon-s3/xsxp.html"> xsxp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="parser_generator"> parser generator </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/apps/page.html"> page </a> · <a href="tcllib/files/modules/page/page_intro.html"> page_intro </a> · <a href="tcllib/files/modules/page/page_pluginmgr.html"> page_pluginmgr </a> · <a href="tcllib/files/modules/page/page_util_flow.html"> page_util_flow </a> · <a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a> · <a href="tcllib/files/modules/page/page_util_peg.html"> page_util_peg </a> · <a href="tcllib/files/modules/page/page_util_quote.html"> page_util_quote </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="parsing"> parsing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bibtex/bibtex.html"> bibtex </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a> · <a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a> · <a href="tcllib/files/modules/grammar_me/me_cpu.html"> grammar::me::cpu </a> · <a href="tcllib/files/modules/grammar_me/me_cpucore.html"> grammar::me::cpu::core </a> · <a href="tcllib/files/modules/grammar_me/gasm.html"> grammar::me::cpu::gasm </a> · <a href="tcllib/files/modules/grammar_me/me_tcl.html"> grammar::me::tcl </a> · <a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_me/me_vm.html"> grammar::me_vm </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/modules/htmlparse/htmlparse.html"> htmlparse </a> · <a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/modules/string/token_shell.html"> string::token::shell </a> · <a href="tcllib/files/modules/yaml/yaml.html"> yaml </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="parsing_expression"> parsing expression </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="parsing_expression_grammar"> parsing expression grammar </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/modules/page/page_util_peg.html"> page_util_peg </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="partial_application"> partial application </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/lambda/lambda.html"> lambda </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="partition"> partition </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="partitioned_set"> partitioned set </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="passive"> passive </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="password"> password </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/otp/otp.html"> otp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="patch"> patch </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="patching"> patching </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pca"> PCA </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/pca.html"> math::PCA </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="peg"> PEG </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a> · <a href="tcllib/files/modules/page/page_util_peg.html"> page_util_peg </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="performance"> performance </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench.html"> bench </a> · <a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wcsv.html"> bench::out::csv </a> · <a href="tcllib/files/modules/bench/bench_wtext.html"> bench::out::text </a> · <a href="tcllib/files/modules/bench/bench_intro.html"> bench_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_intro.html"> bench_lang_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_spec.html"> bench_lang_spec </a> · <a href="tcllib/files/modules/profiler/profiler.html"> profiler </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="permutation"> permutation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="persistence"> persistence </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="phone"> phone </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pi"> pi </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/constants.html"> math::constants </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="plain_text"> plain text </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_export_text.html"> doctools::idx::export::text </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_text.html"> doctools::toc::export::text </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="plane_geometry"> plane geometry </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/math_geometry.html"> math::geometry </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="plugin"> plugin </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools2base/html_cssdefaults.html"> doctools::html::cssdefaults </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2base/nroff_manmacros.html"> doctools::nroff::man_macros </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="plugin_management"> plugin management </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pluginmgr/pluginmgr.html"> pluginmgr </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="plugin_search"> plugin search </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pluginmgr/pluginmgr.html"> pluginmgr </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="png"> png </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/png/png.html"> png </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="point"> point </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/math_geometry.html"> math::geometry </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="polynomial_functions"> polynomial functions </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/polynomials.html"> math::polynomials </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pool"> pool </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/pool.html"> struct::pool </a> · <a href="tcllib/files/modules/struct/queue.html"> struct::queue </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pop"> pop </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pop3"> pop3 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/pop3d/pop3d_dbox.html"> pop3d::dbox </a> · <a href="tcllib/files/modules/pop3d/pop3d_udb.html"> pop3d::udb </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="post_order"> post-order </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="practcl"> practcl </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/practcl/practcl.html"> practcl </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="pre_order"> pre-order </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="prefix"> prefix </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a> · <a href="tcllib/files/modules/textutil/trim.html"> textutil::trim </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="prime"> prime </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/numtheory.html"> math::numtheory </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="prioqueue"> prioqueue </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/prioqueue.html"> struct::prioqueue </a> · <a href="tcllib/files/modules/struct/queue.html"> struct::queue </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="priority_queue"> priority queue </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/prioqueue.html"> struct::prioqueue </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="proc"> proc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/lambda/lambda.html"> lambda </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="procedure"> procedure </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/deleg_proc.html"> deleg_proc </a> · <a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a> · <a href="tcllib/files/modules/tepam/tepam_procedure.html"> tepam::procedure </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="procedure_documentation"> procedure documentation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_doc_gen.html"> tepam::doc_gen </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="processman"> processman </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/processman/processman.html"> processman </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="producer"> producer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="profile"> profile </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/profiler/profiler.html"> profiler </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="projection"> projection </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mapproj/mapproj.html"> mapproj </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="prospero"> prospero </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="protocol"> protocol </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a> · <a href="tcllib/files/modules/ldap/ldap.html"> ldap </a> · <a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a> · <a href="tcllib/files/modules/nns/nns_protocol.html"> nameserv::protocol </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/pop3d/pop3d_dbox.html"> pop3d::dbox </a> · <a href="tcllib/files/modules/pop3d/pop3d_udb.html"> pop3d::udb </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="proxy"> proxy </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/http/autoproxy.html"> autoproxy </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="public_key_cipher"> public key cipher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pki/pki.html"> pki </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="publisher"> publisher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="push_down_automaton"> push down automaton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cQ">Keywords: Q</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="queue"> queue </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/csv/csv.html"> csv </a> · <a href="tcllib/files/modules/htmlparse/htmlparse.html"> htmlparse </a> · <a href="tcllib/files/modules/struct/stack.html"> struct::stack </a> · <a href="tcllib/files/modules/transfer/tqueue.html"> transfer::copy::queue </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="quoting"> quoting </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_util_quote.html"> page_util_quote </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cR">Keywords: R</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="radians"> radians </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/constants.html"> math::constants </a> · <a href="tcllib/files/modules/units/units.html"> units </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="radiobutton"> radiobutton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/html/html.html"> html </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="radius"> radius </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="random"> random </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/tcllib_random.html"> tcl::chan::random </a> · <a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="random_numbers"> random numbers </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/simulation/simulation_random.html"> simulation::random </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rational_functions"> rational functions </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/rational_funcs.html"> math::rationalfunctions </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="raw"> raw </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rc4"> rc4 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rc4/rc4.html"> rc4 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rcs"> RCS </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rcs_patch"> RCS patch </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="read"> read </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reading"> reading </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="receiver"> receiver </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/receive.html"> term::receive </a> · <a href="tcllib/files/modules/term/term_bind.html"> term::receive::bind </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reconnect"> reconnect </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nns/nns_auto.html"> nameserv::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="record"> record </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/struct/record.html"> struct::record </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="recursive_descent"> recursive descent </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reduce"> reduce </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a> · <a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reference"> reference </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reflected_channel"> reflected channel </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/cat.html"> tcl::chan::cat </a> · <a href="tcllib/files/modules/virtchannel_core/core.html"> tcl::chan::core </a> · <a href="tcllib/files/modules/virtchannel_core/events.html"> tcl::chan::events </a> · <a href="tcllib/files/modules/virtchannel_base/facade.html"> tcl::chan::facade </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html"> tcl::chan::fifo </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a> · <a href="tcllib/files/modules/virtchannel_base/halfpipe.html"> tcl::chan::halfpipe </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html"> tcl::chan::memchan </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_null.html"> tcl::chan::null </a> · <a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_random.html"> tcl::chan::random </a> · <a href="tcllib/files/modules/virtchannel_base/std.html"> tcl::chan::std </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_string.html"> tcl::chan::string </a> · <a href="tcllib/files/modules/virtchannel_base/textwindow.html"> tcl::chan::textwindow </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html"> tcl::chan::variable </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html"> tcl::chan::zero </a> · <a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a> · <a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a> · <a href="tcllib/files/modules/virtchannel_core/transformcore.html"> tcl::transform::core </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_counter.html"> tcl::transform::counter </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a> · <a href="tcllib/files/modules/virtchannel_transform/hex.html"> tcl::transform::hex </a> · <a href="tcllib/files/modules/virtchannel_transform/identity.html"> tcl::transform::identity </a> · <a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a> · <a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a> · <a href="tcllib/files/modules/virtchannel_transform/spacer.html"> tcl::transform::spacer </a> · <a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="regex"> regex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/string/token.html"> string::token </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="regular_expression"> regular expression </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a> · <a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/textutil_split.html"> textutil::split </a> · <a href="tcllib/files/modules/textutil/trim.html"> textutil::trim </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="regular_grammar"> regular grammar </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="regular_languages"> regular languages </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="remote_communication"> remote communication </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="remote_execution"> remote execution </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="remove"> remove </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/multi.html"> fileutil::multi </a> · <a href="tcllib/files/modules/fileutil/multiop.html"> fileutil::multi::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="repeating"> repeating </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="repetition"> repetition </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a> · <a href="tcllib/files/modules/textutil/repeat.html"> textutil::repeat </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="report"> report </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/report/report.html"> report </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reshuffle"> reshuffle </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="residual_graph"> residual graph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="resolver"> resolver </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="resource_management"> resource management </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/try/tcllib_try.html"> try </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="restore"> restore </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nns/nns_auto.html"> nameserv::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="return"> return </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/try/tcllib_throw.html"> throw </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="reverse"> reverse </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_821"> rfc 821 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a> · <a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_822"> rfc 822 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/pop3d/pop3d_dbox.html"> pop3d::dbox </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_868"> rfc 868 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ntp/ntp_time.html"> ntp_time </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_959"> rfc 959 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ftp/ftp.html"> ftp </a> · <a href="tcllib/files/modules/ftp/ftp_geturl.html"> ftp::geturl </a> · <a href="tcllib/files/modules/ftpd/ftpd.html"> ftpd </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_977"> rfc 977 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nntp/nntp.html"> nntp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1034"> rfc 1034 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1035"> rfc 1035 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1036"> rfc 1036 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/nntp/nntp.html"> nntp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1320"> rfc 1320 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1321"> rfc 1321 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1413"> rfc 1413 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ident/ident.html"> ident </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1630"> rfc 1630 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1886"> rfc 1886 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_1939"> rfc 1939 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2030"> rfc 2030 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ntp/ntp_time.html"> ntp_time </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2045"> rfc 2045 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/mime.html"> mime </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2046"> rfc 2046 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/mime.html"> mime </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2049"> rfc 2049 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/mime.html"> mime </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2104"> rfc 2104 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a> · <a href="tcllib/files/modules/sha1/sha1.html"> sha1 </a> · <a href="tcllib/files/modules/sha1/sha256.html"> sha256 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2141"> rfc 2141 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/urn-scheme.html"> uri_urn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2251"> rfc 2251 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldap.html"> ldap </a> · <a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2255"> rfc 2255 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2289"> rfc 2289 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/otp/otp.html"> otp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2396"> rfc 2396 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2554"> rfc 2554 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/smtp.html"> smtp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2718"> RFC 2718 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/oauth/oauth.html"> oauth </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2821"> rfc 2821 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/smtp.html"> smtp </a> · <a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_2849"> rfc 2849 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldapx.html"> ldapx </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_3207"> rfc 3207 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/smtp.html"> smtp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_3513"> rfc 3513 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_ip.html"> tcllib_ip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_3986"> rfc 3986 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_4511"> rfc 4511 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldap.html"> ldap </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_5849"> RFC 5849 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/oauth/oauth.html"> oauth </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_6455"> rfc 6455 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/websocket/websocket.html"> websocket </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc_7858"> rfc 7858 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/dns/tcllib_dns.html"> dns </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc3501"> rfc3501 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rfc3548"> rfc3548 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base32/base32.html"> base32 </a> · <a href="tcllib/files/modules/base32/base32hex.html"> base32::hex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="right_outer_join"> right outer join </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ripemd"> RIPEMD </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="roman_numeral"> roman numeral </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/roman.html"> math::roman </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="roots"> roots </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/calculus.html"> math::calculus </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rot"> rot </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rot13"> rot13 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rounding"> rounding </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/fuzzy.html"> math::fuzzy </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rows"> rows </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rpc"> rpc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="rsa"> rsa </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pki/pki.html"> pki </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="running"> running </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cS">Keywords: S</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="s3"> s3 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/amazon-s3/S3.html"> S3 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="sasl"> SASL </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sasl/sasl.html"> SASL </a> · <a href="tcllib/files/modules/sasl/ntlm.html"> SASL::NTLM </a> · <a href="tcllib/files/modules/sasl/scram.html"> SASL::SCRAM </a> · <a href="tcllib/files/modules/sasl/gtoken.html"> SASL::XGoogleToken </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="scanl"> scanl </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/generator/generator.html"> generator </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="sccs"> SCCS </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="scram"> SCRAM </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sasl/scram.html"> SASL::SCRAM </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="secure"> secure </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="security"> security </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/aes/aes.html"> aes </a> · <a href="tcllib/files/modules/blowfish/blowfish.html"> blowfish </a> · <a href="tcllib/files/modules/crc/cksum.html"> cksum </a> · <a href="tcllib/files/modules/crc/crc16.html"> crc16 </a> · <a href="tcllib/files/modules/crc/crc32.html"> crc32 </a> · <a href="tcllib/files/modules/des/des.html"> des </a> · <a href="tcllib/files/modules/md4/md4.html"> md4 </a> · <a href="tcllib/files/modules/md5/md5.html"> md5 </a> · <a href="tcllib/files/modules/md5crypt/md5crypt.html"> md5crypt </a> · <a href="tcllib/files/modules/otp/otp.html"> otp </a> · <a href="tcllib/files/modules/pki/pki.html"> pki </a> · <a href="tcllib/files/modules/rc4/rc4.html"> rc4 </a> · <a href="tcllib/files/modules/ripemd/ripemd128.html"> ripemd128 </a> · <a href="tcllib/files/modules/ripemd/ripemd160.html"> ripemd160 </a> · <a href="tcllib/files/modules/sha1/sha1.html"> sha1 </a> · <a href="tcllib/files/modules/sha1/sha256.html"> sha256 </a> · <a href="tcllib/files/modules/crc/sum.html"> sum </a> · <a href="tcllib/files/modules/des/tcldes.html"> tclDES </a> · <a href="tcllib/files/modules/des/tcldesjr.html"> tclDESjr </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="seed"> seed </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="selectionbox"> selectionbox </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/javascript/javascript.html"> javascript </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="semantic_markup"> semantic markup </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx_intro.html"> docidx_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html"> docidx_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/docidx_lang_faq.html"> docidx_lang_faq </a> · <a href="tcllib/files/modules/doctools/docidx_lang_intro.html"> docidx_lang_intro </a> · <a href="tcllib/files/modules/doctools/docidx_lang_syntax.html"> docidx_lang_syntax </a> · <a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html"> docidx_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctoc_intro.html"> doctoc_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html"> doctoc_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_faq.html"> doctoc_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_intro.html"> doctoc_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html"> doctoc_lang_syntax </a> · <a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a> · <a href="tcllib/files/modules/doctools2idx/idx_introduction.html"> doctools2idx_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools/doctools_intro.html"> doctools_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html"> doctools_lang_cmdref </a> · <a href="tcllib/files/modules/doctools/doctools_lang_faq.html"> doctools_lang_faq </a> · <a href="tcllib/files/modules/doctools/doctools_lang_intro.html"> doctools_lang_intro </a> · <a href="tcllib/files/modules/doctools/doctools_lang_syntax.html"> doctools_lang_syntax </a> · <a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html"> doctools_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="send"> send </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="serialization"> serialization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bee/bee.html"> bee </a> · <a href="tcllib/files/modules/doctools2idx/export_docidx.html"> doctools::idx::export::docidx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_html.html"> doctools::idx::export::html </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_json.html"> doctools::idx::export::json </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html"> doctools::idx::export::nroff </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_text.html"> doctools::idx::export::text </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html"> doctools::idx::export::wiki </a> · <a href="tcllib/files/modules/doctools2idx/idx_structure.html"> doctools::idx::structure </a> · <a href="tcllib/files/modules/doctools2toc/export_doctoc.html"> doctools::toc::export::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_html.html"> doctools::toc::export::html </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_json.html"> doctools::toc::export::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html"> doctools::toc::export::nroff </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_text.html"> doctools::toc::export::text </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html"> doctools::toc::export::wiki </a> · <a href="tcllib/files/modules/doctools2toc/toc_structure.html"> doctools::toc::structure </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="server"> server </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a> · <a href="tcllib/files/modules/nns/nns_common.html"> nameserv::common </a> · <a href="tcllib/files/modules/nns/nns_server.html"> nameserv::server </a> · <a href="tcllib/files/modules/nns/nns_intro.html"> nns_intro </a> · <a href="tcllib/files/apps/nnsd.html"> nnsd </a> · <a href="tcllib/files/modules/udpcluster/udpcluster.html"> udpcluster </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="service"> service </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/log/logger.html"> logger </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="services"> services </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ftpd/ftpd.html"> ftpd </a> · <a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a> · <a href="tcllib/files/modules/httpd/httpd.html"> tool </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="set"> set </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="sha1"> sha1 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sha1/sha1.html"> sha1 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="sha256"> sha256 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sha1/sha256.html"> sha256 </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="shell"> shell </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/string/token_shell.html"> string::token::shell </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="shortest_path"> shortest path </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="shuffle"> shuffle </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="simulated_annealing"> simulated annealing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/simulation/annealing.html"> simulation::annealing </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="simulation"> simulation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/simulation/simulation_random.html"> simulation::random </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="singleton"> singleton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="size_limit"> size limit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="skiplist"> skiplist </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/struct/skiplist.html"> struct::skiplist </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="slippy"> slippy </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a> · <a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="smtp"> smtp </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/mime/mime.html"> mime </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a> · <a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="smtpd"> smtpd </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="snit"> Snit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="snit"> snit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/interp/deleg_method.html"> deleg_method </a> · <a href="tcllib/files/modules/interp/tcllib_interp.html"> interp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="sntp"> SNTP </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ntp/ntp_time.html"> ntp_time </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="socket"> socket </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/comm/comm_wire.html"> comm_wire </a> · <a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="soundex"> soundex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/soundex/soundex.html"> soundex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="source"> source </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip.html"> docstrip </a> · <a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a> · <a href="tcllib/files/apps/tcldocstrip.html"> tcldocstrip </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="spacing"> spacing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/spacer.html"> tcl::transform::spacer </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="spatial_interpolation"> spatial interpolation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/interpolate.html"> math::interpolate </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="special_functions"> special functions </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/special.html"> math::special </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="specification"> specification </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_lang_spec.html"> bench_lang_spec </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="speed"> speed </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/profiler/profiler.html"> profiler </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="split"> split </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil_split.html"> textutil::split </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="squared_graph"> squared graph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ssl"> ssl </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a> · <a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stack"> stack </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/queue.html"> struct::queue </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="standard_io"> standard io </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/std.html"> tcl::chan::std </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="state"> state </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="state_de_serialization"> state (de)serialization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="statistical_distribution"> statistical distribution </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/simulation/simulation_random.html"> simulation::random </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="statistics"> statistics </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/counter/counter.html"> counter </a> · <a href="tcllib/files/modules/math/math.html"> math </a> · <a href="tcllib/files/modules/math/pca.html"> math::PCA </a> · <a href="tcllib/files/modules/math/statistics.html"> math::statistics </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stdin"> stdin </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/std.html"> tcl::chan::std </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stdout"> stdout </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/std.html"> tcl::chan::std </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stochastic_modelling"> stochastic modelling </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/simulation/montecarlo.html"> simulation::montecarlo </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stream_cipher"> stream cipher </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rc4/rc4.html"> rc4 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stream_copy"> stream copy </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="string"> string </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/string/token.html"> string::token </a> · <a href="tcllib/files/modules/string/token_shell.html"> string::token::shell </a> · <a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a> · <a href="tcllib/files/modules/textutil/expander.html"> textutil::expander </a> · <a href="tcllib/files/modules/textutil/repeat.html"> textutil::repeat </a> · <a href="tcllib/files/modules/textutil/textutil_split.html"> textutil::split </a> · <a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a> · <a href="tcllib/files/modules/textutil/tabify.html"> textutil::tabify </a> · <a href="tcllib/files/modules/textutil/trim.html"> textutil::trim </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="stringprep"> stringprep </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/stringprep/stringprep.html"> stringprep </a> · <a href="tcllib/files/modules/stringprep/stringprep_data.html"> stringprep::data </a> · <a href="tcllib/files/modules/stringprep/unicode_data.html"> unicode::data </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="strongly_connected_component"> strongly connected component </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="struct"> struct </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/pool.html"> struct::pool </a> · <a href="tcllib/files/modules/struct/record.html"> struct::record </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="structure"> structure </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/control/control.html"> control </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="structured_queries"> structured queries </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="style"> style </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/html_cssdefaults.html"> doctools::html::cssdefaults </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="subcommand"> subcommand </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tepam/tepam_introduction.html"> tepam </a> · <a href="tcllib/files/modules/tepam/tepam_procedure.html"> tepam::procedure </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="subgraph"> subgraph </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="subject"> subject </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="submitbutton"> submitbutton </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/javascript/javascript.html"> javascript </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="subscriber"> subscriber </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="subsequence"> subsequence </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="subst"> subst </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcl_parse.html"> doctools::tcl::parse </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="sum"> sum </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/crc/sum.html"> sum </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="swapping"> swapping </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_list.html"> struct::list </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="symmetric_difference"> symmetric difference </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="synchronous"> synchronous </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/cache/async.html"> cache::async </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="syntax_tree"> syntax tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_util.html"> grammar::me::util </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cT">Keywords: T</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="table"> table </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/html/html.html"> html </a> · <a href="tcllib/files/modules/report/report.html"> report </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="table_of_contents"> table of contents </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_intro.html"> doctoc_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a> · <a href="tcllib/files/modules/doctools2toc/toc_introduction.html"> doctools2toc_introduction </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/export_doctoc.html"> doctools::toc::export::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_html.html"> doctools::toc::export::html </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_json.html"> doctools::toc::export::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html"> doctools::toc::export::nroff </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_text.html"> doctools::toc::export::text </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html"> doctools::toc::export::wiki </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/doctools2toc/import_doctoc.html"> doctools::toc::import::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import_json.html"> doctools::toc::import::json </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tabstops"> tabstops </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/tabify.html"> textutil::tabify </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tallying"> tallying </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/counter/counter.html"> counter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tape_archive"> tape archive </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tar/tar.html"> tar </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tar"> tar </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tar/tar.html"> tar </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tcl"> tcl </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/bigfloat.html"> math::bigfloat </a> · <a href="tcllib/files/modules/math/bignum.html"> math::bignum </a> · <a href="tcllib/files/modules/math/decimal.html"> math::decimal </a> · <a href="tcllib/files/modules/math/pca.html"> math::PCA </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tcl_module"> Tcl module </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/docstrip/docstrip_util.html"> docstrip_util </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tcl_syntax"> Tcl syntax </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcl_parse.html"> doctools::tcl::parse </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tcler_s_wiki"> tcler's wiki </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tcllib"> tcllib </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/csv/csv.html"> csv </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tcloo"> TclOO </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tool/meta.html"> oo::util </a> · <a href="tcllib/files/modules/ooutil/ooutil.html"> oo::util </a> · <a href="tcllib/files/modules/oometa/oometa.html"> oometa </a> · <a href="tcllib/files/modules/httpd/httpd.html"> tool </a> · <a href="tcllib/files/modules/tool/tool.html"> tool </a> · <a href="tcllib/files/modules/tool/tool_dict_ensemble.html"> tool::dict_ensemble </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tclparam"> TCLPARAM </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tdpl"> TDPL </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="temp_file"> temp file </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="template_processing"> template processing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/expander.html"> textutil::expander </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="terminal"> terminal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/term.html"> term </a> · <a href="tcllib/files/modules/term/ansi_code.html"> term::ansi::code </a> · <a href="tcllib/files/modules/term/ansi_cattr.html"> term::ansi::code::attr </a> · <a href="tcllib/files/modules/term/ansi_cctrl.html"> term::ansi::code::ctrl </a> · <a href="tcllib/files/modules/term/ansi_cmacros.html"> term::ansi::code::macros </a> · <a href="tcllib/files/modules/term/ansi_ctrlu.html"> term::ansi::ctrl::unix </a> · <a href="tcllib/files/modules/term/ansi_send.html"> term::ansi::send </a> · <a href="tcllib/files/modules/term/imenu.html"> term::interact::menu </a> · <a href="tcllib/files/modules/term/ipager.html"> term::interact::pager </a> · <a href="tcllib/files/modules/term/receive.html"> term::receive </a> · <a href="tcllib/files/modules/term/term_bind.html"> term::receive::bind </a> · <a href="tcllib/files/modules/term/term_send.html"> term::send </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="test"> test </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="testing"> Testing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/valtype_common.html"> valtype::common </a> · <a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a> · <a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a> · <a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a> · <a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a> · <a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="testing"> testing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench.html"> bench </a> · <a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wcsv.html"> bench::out::csv </a> · <a href="tcllib/files/modules/bench/bench_wtext.html"> bench::out::text </a> · <a href="tcllib/files/modules/bench/bench_intro.html"> bench_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_intro.html"> bench_lang_intro </a> · <a href="tcllib/files/modules/bench/bench_lang_spec.html"> bench_lang_spec </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tex"> TeX </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text"> text </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bench/bench_read.html"> bench::in </a> · <a href="tcllib/files/modules/bench/bench_wtext.html"> bench::out::text </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_comparison"> text comparison </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/soundex/soundex.html"> soundex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_conversion"> text conversion </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_differences"> text differences </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/rcs/rcs.html"> rcs </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_display"> text display </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/term/imenu.html"> term::interact::menu </a> · <a href="tcllib/files/modules/term/ipager.html"> term::interact::pager </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_expansion"> text expansion </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/expander.html"> textutil::expander </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_likeness"> text likeness </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/soundex/soundex.html"> soundex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_processing"> text processing </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bibtex/bibtex.html"> bibtex </a> · <a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/apps/page.html"> page </a> · <a href="tcllib/files/modules/page/page_intro.html"> page_intro </a> · <a href="tcllib/files/modules/page/page_pluginmgr.html"> page_pluginmgr </a> · <a href="tcllib/files/modules/page/page_util_flow.html"> page_util_flow </a> · <a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a> · <a href="tcllib/files/modules/page/page_util_peg.html"> page_util_peg </a> · <a href="tcllib/files/modules/page/page_util_quote.html"> page_util_quote </a> · <a href="tcllib/files/modules/yaml/yaml.html"> yaml </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="text_widget"> text widget </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/textwindow.html"> tcl::chan::textwindow </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="threads"> threads </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="throw"> throw </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/try/tcllib_throw.html"> throw </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="thumbnail"> thumbnail </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/jpeg/jpeg.html"> jpeg </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tie"> tie </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tif"> tif </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tiff/tiff.html"> tiff </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tiff"> tiff </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tiff/tiff.html"> tiff </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tile"> tile </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="time"> time </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ntp/ntp_time.html"> ntp_time </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="timestamp"> timestamp </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/png/png.html"> png </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="timestamps"> timestamps </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/debug/debug_timestamp.html"> debug::timestamp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tip_219"> tip 219 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/cat.html"> tcl::chan::cat </a> · <a href="tcllib/files/modules/virtchannel_core/core.html"> tcl::chan::core </a> · <a href="tcllib/files/modules/virtchannel_core/events.html"> tcl::chan::events </a> · <a href="tcllib/files/modules/virtchannel_base/facade.html"> tcl::chan::facade </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html"> tcl::chan::fifo </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a> · <a href="tcllib/files/modules/virtchannel_base/halfpipe.html"> tcl::chan::halfpipe </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html"> tcl::chan::memchan </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_null.html"> tcl::chan::null </a> · <a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_random.html"> tcl::chan::random </a> · <a href="tcllib/files/modules/virtchannel_base/std.html"> tcl::chan::std </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_string.html"> tcl::chan::string </a> · <a href="tcllib/files/modules/virtchannel_base/textwindow.html"> tcl::chan::textwindow </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html"> tcl::chan::variable </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html"> tcl::chan::zero </a> · <a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a> · <a href="tcllib/files/modules/virtchannel_core/transformcore.html"> tcl::transform::core </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tip_230"> tip 230 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_counter.html"> tcl::transform::counter </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a> · <a href="tcllib/files/modules/virtchannel_transform/hex.html"> tcl::transform::hex </a> · <a href="tcllib/files/modules/virtchannel_transform/identity.html"> tcl::transform::identity </a> · <a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a> · <a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a> · <a href="tcllib/files/modules/virtchannel_transform/spacer.html"> tcl::transform::spacer </a> · <a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tip_234"> tip 234 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tip_317"> tip 317 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tk"> Tk </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/textwindow.html"> tcl::chan::textwindow </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tls"> tls </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/comm/comm.html"> comm </a> · <a href="tcllib/files/modules/imap4/imap4.html"> imap4 </a> · <a href="tcllib/files/modules/pop3/pop3.html"> pop3 </a> · <a href="tcllib/files/modules/pop3d/pop3d.html"> pop3d </a> · <a href="tcllib/files/modules/mime/smtp.html"> smtp </a> · <a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tmml"> TMML </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctools.html"> doctools </a> · <a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/apps/dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/dtplite/pkg_dtplite.html"> dtplite </a> · <a href="tcllib/files/modules/doctools/mpexpand.html"> mpexpand </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="toc"> toc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_intro.html"> doctoc_intro </a> · <a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/export_doctoc.html"> doctools::toc::export::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_html.html"> doctools::toc::export::html </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_json.html"> doctools::toc::export::json </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html"> doctools::toc::export::nroff </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_text.html"> doctools::toc::export::text </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html"> doctools::toc::export::wiki </a> · <a href="tcllib/files/modules/doctools2toc/import_doctoc.html"> doctools::toc::import::doctoc </a> · <a href="tcllib/files/modules/doctools2toc/toc_import_json.html"> doctools::toc::import::json </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="toc_formatter"> toc formatter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html"> doctoc_plugin_apiref </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tokenization"> tokenization </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/string/token.html"> string::token </a> · <a href="tcllib/files/modules/string/token_shell.html"> string::token::shell </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tool"> TOOL </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/oometa/oometa.html"> oometa </a> · <a href="tcllib/files/modules/tool/tool.html"> tool </a> · <a href="tcllib/files/modules/tool/tool_dict_ensemble.html"> tool::dict_ensemble </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="top_down_parsing_languages"> top-down parsing languages </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="torrent"> torrent </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/bee/bee.html"> bee </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="touch"> touch </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tpdl"> TPDL </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="trace"> trace </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/debug/debug.html"> debug </a> · <a href="tcllib/files/modules/debug/debug_caller.html"> debug::caller </a> · <a href="tcllib/files/modules/debug/debug_heartbeat.html"> debug::heartbeat </a> · <a href="tcllib/files/modules/debug/debug_timestamp.html"> debug::timestamp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="transducer"> transducer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_aycock/aycock.html"> grammar::aycock </a> · <a href="tcllib/files/modules/grammar_fa/fa.html"> grammar::fa </a> · <a href="tcllib/files/modules/grammar_fa/dacceptor.html"> grammar::fa::dacceptor </a> · <a href="tcllib/files/modules/grammar_fa/dexec.html"> grammar::fa::dexec </a> · <a href="tcllib/files/modules/grammar_fa/faop.html"> grammar::fa::op </a> · <a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_peg/peg.html"> grammar::peg </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/apps/pt.html"> pt </a> · <a href="tcllib/files/modules/pt/pt_astree.html"> pt::ast </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html"> pt::cparam::configuration::critcl </a> · <a href="tcllib/files/modules/pt/pt_cparam_config_tea.html"> pt::cparam::configuration::tea </a> · <a href="tcllib/files/modules/pt/pt_json_language.html"> pt::json_language </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a> · <a href="tcllib/files/modules/pt/pt_pexpression.html"> pt::pe </a> · <a href="tcllib/files/modules/pt/pt_pexpr_op.html"> pt::pe::op </a> · <a href="tcllib/files/modules/pt/pt_pegrammar.html"> pt::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_container.html"> pt::peg::container </a> · <a href="tcllib/files/modules/pt/pt_peg_container_peg.html"> pt::peg::container::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_export.html"> pt::peg::export </a> · <a href="tcllib/files/modules/pt/pt_peg_export_container.html"> pt::peg::export::container </a> · <a href="tcllib/files/modules/pt/pt_peg_export_json.html"> pt::peg::export::json </a> · <a href="tcllib/files/modules/pt/pt_peg_export_peg.html"> pt::peg::export::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_from_container.html"> pt::peg::from::container </a> · <a href="tcllib/files/modules/pt/pt_peg_from_json.html"> pt::peg::from::json </a> · <a href="tcllib/files/modules/pt/pt_peg_from_peg.html"> pt::peg::from::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_import.html"> pt::peg::import </a> · <a href="tcllib/files/modules/pt/pt_peg_import_container.html"> pt::peg::import::container </a> · <a href="tcllib/files/modules/pt/pt_peg_import_json.html"> pt::peg::import::json </a> · <a href="tcllib/files/modules/pt/pt_peg_import_peg.html"> pt::peg::import::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_interp.html"> pt::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_peg_to_container.html"> pt::peg::to::container </a> · <a href="tcllib/files/modules/pt/pt_peg_to_cparam.html"> pt::peg::to::cparam </a> · <a href="tcllib/files/modules/pt/pt_peg_to_json.html"> pt::peg::to::json </a> · <a href="tcllib/files/modules/pt/pt_peg_to_param.html"> pt::peg::to::param </a> · <a href="tcllib/files/modules/pt/pt_peg_to_peg.html"> pt::peg::to::peg </a> · <a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html"> pt::peg::to::tclparam </a> · <a href="tcllib/files/modules/pt/pt_peg_language.html"> pt::peg_language </a> · <a href="tcllib/files/modules/pt/pt_peg_introduction.html"> pt::pegrammar </a> · <a href="tcllib/files/modules/pt/pt_pgen.html"> pt::pgen </a> · <a href="tcllib/files/modules/pt/pt_rdengine.html"> pt::rde </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html"> pt::tclparam::configuration::nx </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html"> pt::tclparam::configuration::snit </a> · <a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html"> pt::tclparam::configuration::tcloo </a> · <a href="tcllib/files/modules/pt/pt_util.html"> pt::util </a> · <a href="tcllib/files/modules/pt/pt_to_api.html"> pt_export_api </a> · <a href="tcllib/files/modules/pt/pt_from_api.html"> pt_import_api </a> · <a href="tcllib/files/modules/pt/pt_introduction.html"> pt_introduction </a> · <a href="tcllib/files/modules/pt/pt_parse_peg.html"> pt_parse_peg </a> · <a href="tcllib/files/modules/pt/pt_parser_api.html"> pt_parser_api </a> · <a href="tcllib/files/modules/pt/pt_peg_op.html"> pt_peg_op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="transfer"> transfer </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/connect.html"> transfer::connect </a> · <a href="tcllib/files/modules/transfer/copyops.html"> transfer::copy </a> · <a href="tcllib/files/modules/transfer/tqueue.html"> transfer::copy::queue </a> · <a href="tcllib/files/modules/transfer/ddest.html"> transfer::data::destination </a> · <a href="tcllib/files/modules/transfer/dsource.html"> transfer::data::source </a> · <a href="tcllib/files/modules/transfer/receiver.html"> transfer::receiver </a> · <a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="transformation"> transformation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_util_peg.html"> page_util_peg </a> · <a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_counter.html"> tcl::transform::counter </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a> · <a href="tcllib/files/modules/virtchannel_transform/hex.html"> tcl::transform::hex </a> · <a href="tcllib/files/modules/virtchannel_transform/identity.html"> tcl::transform::identity </a> · <a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a> · <a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a> · <a href="tcllib/files/modules/virtchannel_transform/spacer.html"> tcl::transform::spacer </a> · <a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="transmitter"> transmitter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/transfer/transmitter.html"> transfer::transmitter </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="travelling_salesman"> travelling salesman </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="traversal"> traversal </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/traverse.html"> fileutil_traverse </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tree"> tree </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/gasm.html"> grammar::me::cpu::gasm </a> · <a href="tcllib/files/modules/grammar_me/me_util.html"> grammar::me::util </a> · <a href="tcllib/files/modules/htmlparse/htmlparse.html"> htmlparse </a> · <a href="tcllib/files/modules/struct/queue.html"> struct::queue </a> · <a href="tcllib/files/modules/struct/stack.html"> struct::stack </a> · <a href="tcllib/files/modules/struct/struct_tree.html"> struct::tree </a> · <a href="tcllib/files/modules/struct/struct_tree1.html"> struct::tree_v1 </a> · <a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tree_query_language"> tree query language </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="tree_walking"> tree walking </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/page/page_util_flow.html"> page_util_flow </a> · <a href="tcllib/files/modules/page/page_util_norm_lemon.html"> page_util_norm_lemon </a> · <a href="tcllib/files/modules/page/page_util_norm_peg.html"> page_util_norm_peg </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="treeql"> TreeQL </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="trigonometry"> trigonometry </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/trig.html"> math::trig </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="trimming"> trimming </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil.html"> textutil </a> · <a href="tcllib/files/modules/textutil/trim.html"> textutil::trim </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="twitter"> twitter </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/oauth/oauth.html"> oauth </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="type"> type </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/fileutil/fileutil.html"> fileutil </a> · <a href="tcllib/files/modules/fumagic/cfront.html"> fileutil::magic::cfront </a> · <a href="tcllib/files/modules/fumagic/cgen.html"> fileutil::magic::cgen </a> · <a href="tcllib/files/modules/fumagic/filetypes.html"> fileutil::magic::filetype </a> · <a href="tcllib/files/modules/fumagic/rtcore.html"> fileutil::magic::rt </a> · <a href="tcllib/files/modules/snit/snit.html"> snit </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="type_checking"> Type checking </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/valtype_common.html"> valtype::common </a> · <a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a> · <a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a> · <a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a> · <a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a> · <a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cU">Keywords: U</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="uevent"> uevent </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/hook/hook.html"> hook </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="unbind"> unbind </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uev/uevent.html"> uevent </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="uncapitalize"> uncapitalize </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/textutil_string.html"> textutil::string </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="undenting"> undenting </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/textutil/adjust.html"> textutil::adjust </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="unicode"> unicode </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/stringprep/stringprep.html"> stringprep </a> · <a href="tcllib/files/modules/stringprep/stringprep_data.html"> stringprep::data </a> · <a href="tcllib/files/modules/stringprep/unicode.html"> unicode </a> · <a href="tcllib/files/modules/stringprep/unicode_data.html"> unicode::data </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="union"> union </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/disjointset.html"> struct::disjointset </a> · <a href="tcllib/files/modules/struct/struct_set.html"> struct::set </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="unit"> unit </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/units/units.html"> units </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="unknown_hooking"> unknown hooking </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="untie"> untie </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/tie/tie_std.html"> tie </a> · <a href="tcllib/files/modules/tie/tie.html"> tie </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="update"> update </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="uri"> uri </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a> · <a href="tcllib/files/modules/uri/urn-scheme.html"> uri_urn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="url"> url </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_import.html"> doctools::idx::import </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_import.html"> doctools::toc::import </a> · <a href="tcllib/files/modules/map/map_geocode_nominatim.html"> map::geocode::nominatim </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a> · <a href="tcllib/files/modules/uri/uri.html"> uri </a> · <a href="tcllib/files/modules/uri/urn-scheme.html"> uri_urn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="urn"> urn </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/urn-scheme.html"> uri_urn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="us_npi"> US-NPI </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="utilities"> utilities </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/namespacex/namespacex.html"> namespacex </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="uuencode"> uuencode </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/uuencode.html"> uuencode </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="uuid"> UUID </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uuid/uuid.html"> uuid </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cV">Keywords: V</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="validation"> Validation </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/valtype_common.html"> valtype::common </a> · <a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a> · <a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a> · <a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a> · <a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a> · <a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="value_checking"> Value checking </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/valtype_common.html"> valtype::common </a> · <a href="tcllib/files/modules/valtype/cc_amex.html"> valtype::creditcard::amex </a> · <a href="tcllib/files/modules/valtype/cc_discover.html"> valtype::creditcard::discover </a> · <a href="tcllib/files/modules/valtype/cc_mastercard.html"> valtype::creditcard::mastercard </a> · <a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a> · <a href="tcllib/files/modules/valtype/ean13.html"> valtype::gs1::ean13 </a> · <a href="tcllib/files/modules/valtype/iban.html"> valtype::iban </a> · <a href="tcllib/files/modules/valtype/imei.html"> valtype::imei </a> · <a href="tcllib/files/modules/valtype/isbn.html"> valtype::isbn </a> · <a href="tcllib/files/modules/valtype/luhn.html"> valtype::luhn </a> · <a href="tcllib/files/modules/valtype/luhn5.html"> valtype::luhn5 </a> · <a href="tcllib/files/modules/valtype/usnpi.html"> valtype::usnpi </a> · <a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="vectors"> vectors </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/math/linalg.html"> math::linearalgebra </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="verhoeff"> verhoeff </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/verhoeff.html"> valtype::verhoeff </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="vertex"> vertex </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graph.html"> struct::graph </a> · <a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="vertex_cover"> vertex cover </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/struct/graphops.html"> struct::graph::op </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="virtual_channel"> virtual channel </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/cat.html"> tcl::chan::cat </a> · <a href="tcllib/files/modules/virtchannel_core/core.html"> tcl::chan::core </a> · <a href="tcllib/files/modules/virtchannel_core/events.html"> tcl::chan::events </a> · <a href="tcllib/files/modules/virtchannel_base/facade.html"> tcl::chan::facade </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html"> tcl::chan::fifo </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html"> tcl::chan::fifo2 </a> · <a href="tcllib/files/modules/virtchannel_base/halfpipe.html"> tcl::chan::halfpipe </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html"> tcl::chan::memchan </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_null.html"> tcl::chan::null </a> · <a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_random.html"> tcl::chan::random </a> · <a href="tcllib/files/modules/virtchannel_base/std.html"> tcl::chan::std </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_string.html"> tcl::chan::string </a> · <a href="tcllib/files/modules/virtchannel_base/textwindow.html"> tcl::chan::textwindow </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html"> tcl::chan::variable </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html"> tcl::chan::zero </a> · <a href="tcllib/files/modules/virtchannel_base/randseed.html"> tcl::randomseed </a> · <a href="tcllib/files/modules/virtchannel_transform/adler32.html"> tcl::transform::adler32 </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_base64.html"> tcl::transform::base64 </a> · <a href="tcllib/files/modules/virtchannel_core/transformcore.html"> tcl::transform::core </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_counter.html"> tcl::transform::counter </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html"> tcl::transform::crc32 </a> · <a href="tcllib/files/modules/virtchannel_transform/hex.html"> tcl::transform::hex </a> · <a href="tcllib/files/modules/virtchannel_transform/identity.html"> tcl::transform::identity </a> · <a href="tcllib/files/modules/virtchannel_transform/limitsize.html"> tcl::transform::limitsize </a> · <a href="tcllib/files/modules/virtchannel_transform/observe.html"> tcl::transform::observe </a> · <a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a> · <a href="tcllib/files/modules/virtchannel_transform/rot.html"> tcl::transform::rot </a> · <a href="tcllib/files/modules/virtchannel_transform/spacer.html"> tcl::transform::spacer </a> · <a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="virtual_machine"> virtual machine </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/grammar_me/me_cpu.html"> grammar::me::cpu </a> · <a href="tcllib/files/modules/grammar_me/me_cpucore.html"> grammar::me::cpu::core </a> · <a href="tcllib/files/modules/grammar_me/gasm.html"> grammar::me::cpu::gasm </a> · <a href="tcllib/files/modules/grammar_me/me_tcl.html"> grammar::me::tcl </a> · <a href="tcllib/files/modules/grammar_me/me_intro.html"> grammar::me_intro </a> · <a href="tcllib/files/modules/grammar_me/me_vm.html"> grammar::me_vm </a> · <a href="tcllib/files/modules/grammar_peg/peg_interp.html"> grammar::peg::interp </a> · <a href="tcllib/files/modules/pt/pt_param.html"> pt::param </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="visa"> VISA </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/valtype/cc_visa.html"> valtype::creditcard::visa </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="vwait"> vwait </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/coroutine/tcllib_coroutine.html"> coroutine </a> · <a href="tcllib/files/modules/coroutine/coro_auto.html"> coroutine::auto </a> · <a href="tcllib/files/modules/smtpd/smtpd.html"> smtpd </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cW">Keywords: W</a>
</th></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="wais"> wais </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="widget"> widget </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="widget_adaptors"> widget adaptors </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/snit/snit.html"> snit </a> · <a href="tcllib/files/modules/snit/snitfaq.html"> snitfaq </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="wiki"> wiki </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools/docidx.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_container.html"> doctools::idx </a> · <a href="tcllib/files/modules/doctools2idx/idx_export.html"> doctools::idx::export </a> · <a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html"> doctools::idx::export::wiki </a> · <a href="tcllib/files/modules/doctools2toc/toc_container.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools/doctoc.html"> doctools::toc </a> · <a href="tcllib/files/modules/doctools2toc/toc_export.html"> doctools::toc::export </a> · <a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html"> doctools::toc::export::wiki </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="word"> word </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/doctools2base/tcl_parse.html"> doctools::tcl::parse </a> · <a href="tcllib/files/modules/wip/wip.html"> wip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="www"> WWW </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/httpd/httpd.html"> tool </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="www"> www </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/uri/uri.html"> uri </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cX">Keywords: X</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="x_208"> x.208 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="x_209"> x.209 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/asn/asn.html"> asn </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="x_500"> x.500 </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/ldap/ldap.html"> ldap </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="xgoogletoken"> XGoogleToken </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/sasl/gtoken.html"> SASL::XGoogleToken </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="xml"> xml </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/amazon-s3/xsxp.html"> xsxp </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="xor"> xor </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/vt_otp.html"> tcl::transform::otp </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="xpath"> XPath </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="xslt"> XSLT </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/treeql/treeql.html"> treeql </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cY">Keywords: Y</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="yaml"> yaml </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/yaml/huddle.html"> huddle </a> · <a href="tcllib/files/modules/yaml/yaml.html"> yaml </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="ydecode"> ydecode </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/yencode.html"> yencode </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="yenc"> yEnc </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/yencode.html"> yencode </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="yencode"> yencode </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/base64/yencode.html"> yencode </a>
</td></tr>
<tr class="#doctools_idxheader"><th colspan="2">
<a name="cZ">Keywords: Z</a>
</th></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="zero"> zero </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_base/nullzero.html"> tcl::chan::nullzero </a> · <a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html"> tcl::chan::zero </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="zip"> zip </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/zip/decode.html"> zipfile::decode </a> · <a href="tcllib/files/modules/zip/encode.html"> zipfile::encode </a> · <a href="tcllib/files/modules/zip/mkzip.html"> zipfile::mkzip </a>
</td></tr>
<tr class="#doctools_idxodd" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="zlib"> zlib </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html"> tcl::transform::zlib </a>
</td></tr>
<tr class="#doctools_idxeven" valign=top>
<td class="#doctools_idxleft" width="35%"><a name="zoom"> zoom </a></td>
<td class="#doctools_idxright" width="65%">
<a href="tcllib/files/modules/map/map_slippy.html"> map::slippy </a> · <a href="tcllib/files/modules/map/map_slippy_cache.html"> map::slippy::cache </a> · <a href="tcllib/files/modules/map/map_slippy_fetcher.html"> map::slippy::fetcher </a>
</td></tr>
</table>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/dtplite.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
|
<div class='fossil-doc' data-title='dtplite - Documentation toolbox'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">dtplite(n) 1.0.5 tcllib "Documentation toolbox"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>dtplite - Lightweight DocTools Markup Processor</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">USE CASES</a></li>
<li class="doctools_subsection"><a href="#subsection2">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
<li class="doctools_subsection"><a href="#subsection4">FORMATS</a></li>
<li class="doctools_subsection"><a href="#subsection5">DIRECTORY STRUCTURES</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">dtplite</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputfile</i></a></li>
<li><a href="#2"><b class="cmd">dtplite</b> <b class="const">validate</b> <i class="arg">inputfile</i></a></li>
<li><a href="#3"><b class="cmd">dtplite</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></li>
<li><a href="#4"><b class="cmd">dtplite</b> <b class="option">-merge</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The application described by this document, <b class="syscmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b>, is the
successor to the extremely simple <b class="syscmd"><a href="../modules/doctools/mpexpand.html">mpexpand</a></b>. Influenced in its
functionality by the <b class="syscmd">dtp</b> doctools processor it is much more
powerful than <b class="syscmd"><a href="../modules/doctools/mpexpand.html">mpexpand</a></b>, yet still as easy to use; definitely
easier than <b class="syscmd">dtp</b> with its myriad of subcommands and options.</p>
<p><b class="syscmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b> is based upon the package <b class="package"><a href="../modules/doctools/doctools.html">doctools</a></b>, like
the other two processors.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">USE CASES</a></h3>
<p><b class="syscmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b> was written with the following three use cases in
mind.</p>
<ol class="doctools_enumerated">
<li><p>Validation of a single document, i.e. checking that it was written in
valid doctools format. This mode can also be used to get a preliminary
version of the formatted output for a single document, for display in
a browser, nroff, etc., allowing proofreading of the formatting.</p></li>
<li><p>Generation of the formatted documentation for a single package,
i.e. all the manpages, plus a table of contents and an index of
keywords.</p></li>
<li><p>An extension of the previous mode of operation, a method for the easy
generation of one documentation tree for several packages, and
especially of a unified table of contents and keyword index.</p></li>
</ol>
<p>Beyond the above we also want to make use of the customization
features provided by the HTML formatter. It is not the only format the
application should be able to generate, but we anticipiate it to be
the most commonly used, and it is one of the few which do provide
customization hooks.</p>
<p>We allow the caller to specify a header string, footer string, a
stylesheet, and data for a bar of navigation links at the top of the
generated document.
While all can be set as long as the formatting engine provides an
appropriate engine parameter (See section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>) the last
two have internal processing which make them specific to HTML.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputfile</i></a></dt>
<dd><p>This is the form for use case [1]. The <i class="arg">options</i> will be
explained later, in section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p>
<dl class="doctools_arguments">
<dt>path <i class="arg">output</i> (in)</dt>
<dd><p>This argument specifies where to write the generated document. It can
be the path to a file or directory, or <b class="const">-</b>.
The last value causes the application to write the generated
documented to <b class="const">stdout</b>.</p>
<p>If the <i class="arg">output</i> does not exist then [file dirname $output]
has to exist and must be a writable directory.
The generated document will be written to a file in that directory,
and the name of that file will be derived from the <i class="arg">inputfile</i>,
the <i class="arg">format</i>, and the value given to option <b class="option">-ext</b> (if
present).</p></dd>
<dt>(path|handle) <i class="arg">format</i> (in)</dt>
<dd><p>This argument specifies the formatting engine to use when processing
the input, and thus the format of the generated document. See section
<span class="sectref"><a href="#subsection4">FORMATS</a></span> for the possibilities recognized by the application.</p></dd>
<dt>path <i class="arg">inputfile</i> (in)</dt>
<dd><p>This argument specifies the path to the file to process. It has to
exist, must be readable, and written in <i class="term"><a href="../../../index.html#doctools">doctools</a></i> format.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b> <b class="const">validate</b> <i class="arg">inputfile</i></a></dt>
<dd><p>This is a simpler form for use case [1]. The "validate" format
generates no output at all, only syntax checks are performed. As such
the specification of an output file or other options is not necessary
and left out.</p></dd>
<dt><a name="3"><b class="cmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></dt>
<dd><p>This is the form for use case [2]. It differs from the form for
use case [1] by having the input documents specified through a
directory instead of a file. The other arguments are identical, except
for <i class="arg">output</i>, which now has to be the path to an existing and
writable directory.</p>
<p>The input documents are all files in <i class="arg">inputdirectory</i> or any of
its subdirectories which were recognized by <b class="cmd">fileutil::fileType</b>
as containing text in <i class="term"><a href="../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="4"><b class="cmd"><a href="../modules/dtplite/pkg_dtplite.html">dtplite</a></b> <b class="option">-merge</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></dt>
<dd><p>This is the form for use case [3]. The only difference to the
form for use case [2] is the additional option <b class="option">-merge</b>.</p>
<p>Each such call will merge the generated documents coming from
processing the input documents under <i class="arg">inputdirectory</i> or any of
its subdirectories to the files under <i class="arg">output</i>. In this manner it
is possible to incrementally build the unified documentation for any
number of packages. Note that it is necessary to run through all the
packages twice to get fully correct cross-references (for formats
supporting them).</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application, with
the exception of the options <b class="option">-o</b> and <b class="option">-merge</b>. These
two were described already, in section <span class="sectref"><a href="#subsection2">COMMAND LINE</a></span>.</p>
<dl class="doctools_options">
<dt><b class="option">-exclude</b> string</dt>
<dd><p>This option specifies an exclude (glob) pattern. Any files identified
as manpages to process which match the exclude pattern are
ignored. The option can be provided multiple times, each usage adding
an additional pattern to the list of exclusions.</p></dd>
<dt><b class="option">-ext</b> string</dt>
<dd><p>If the name of an output file has to be derived from the name of an
input file it will use the name of the <i class="arg">format</i> as the extension
by default. This option here will override this however, forcing it to
use <i class="arg">string</i> as the file extension. This option is ignored if the
name of the output file is fully specified through option <b class="option">-o</b>.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-header</b> file</dt>
<dd><p>This option can be used if and only if the selected <i class="arg">format</i>
provides an engine parameter named "header". It takes the contents of
the specified file and assign them to that parameter, for whatever use
by the engine. The HTML engine will insert the text just after the tag
<b class="const"><body></b>.
If navigation buttons are present (see option <b class="option">-nav</b> below),
then the HTML generated for them is appended to the header data
originating here before the final assignment to the parameter.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-footer</b> file</dt>
<dd><p>Like <b class="option">-header</b>, except that: Any navigation buttons are ignored,
the corresponding required engine parameter is named "footer", and the
data is inserted just before the tag <b class="const"></body></b>.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-style</b> file</dt>
<dd><p>This option can be used if and only if the selected <i class="arg">format</i>
provides an engine parameter named "meta". When specified it will
generate a piece of HTML code declaring the <i class="arg">file</i> as the
stylesheet for the generated document and assign that to the
parameter. The HTML engine will insert this inot the document, just
after the tag <b class="const"><head></b>.</p>
<p>When processing an input directory the stylesheet file is copied into
the output directory and the generated HTML will refer to the copy, to
make the result more self-contained. When processing an input file we
have no location to copy the stylesheet to and so just reference it as
specified.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-toc</b> path</dt>
<dd><p>This option specifies a doctoc file to use for the table of contents
instead of generating our own.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-pre+toc</b> label path|text</dt>
<dd></dd>
<dt><b class="option">-post+toc</b> label path|text</dt>
<dd><p>This option specifies additional doctoc files (or texts) to use in
the navigation bar.</p>
<p>Positioning and handling of multiple uses is like for options
<b class="option">-prenav</b> and <b class="option">-postnav</b>, see below.</p></dd>
<dt><b class="option">-nav</b> label url</dt>
<dd></dd>
<dt><b class="option">-prenav</b> label url</dt>
<dd><p>Use this option to specify a navigation button with <i class="arg">label</i> to
display and the <i class="arg">url</i> to link to. This option can be used if and
only if the selected <i class="arg">format</i> provides an engine parameter named
"header". The HTML generated for this is appended to whatever data we
got from option <b class="option">-header</b> before it is inserted into the
generated documents.</p>
<p>When used multiple times all definitions are collected and a
navigation bar is created, with the first definition shown at the left
edge and the last definition to the right.</p>
<p>The url can be relative. In that case it is assumed to be relative
to the main files (TOC and Keyword index), and will be transformed for
all others to still link properly.</p></dd>
<dt><b class="option">-postnav</b> label url</dt>
<dd><p>Use this option to specify a navigation button with <i class="arg">label</i> to
display and the <i class="arg">url</i> to link to. This option can be used if and
only if the selected <i class="arg">format</i> provides an engine parameter named
"header". The HTML generated for this is appended to whatever data we
got from option <b class="option">-header</b> before it is inserted into the
generated documents.</p>
<p>When used multiple times all definitions are collected and a
navigation bar is created, with the last definition shown at the right
edge and the first definition to the left.</p>
<p>The url can be relative. In that case it is assumed to be relative
to the main files (TOC and Keyword index), and will be transformed for
all others to still link properly.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">FORMATS</a></h3>
<p>At first the <i class="arg">format</i> argument will be treated as a path to a tcl
file containing the code for the requested formatting engine. The
argument will be treated as the name of one of the predefined formats
listed below if and only if the path does not exist.</p>
<p><em>Note a limitation</em>: If treating the format as path to the tcl
script implementing the engine was sucessful, then this script has to
implement not only the engine API for doctools, i.e.
<i class="term">doctools_api</i>, but for <i class="term">doctoc_api</i> and <i class="term">docidx_api</i>
as well. Otherwise the generation of a table of contents and of a
keyword index will fail.</p>
<p>List of predefined formats, i.e. as provided by the
package <b class="package"><a href="../modules/doctools/doctools.html">doctools</a></b>:</p>
<dl class="doctools_definitions">
<dt><b class="const">nroff</b></dt>
<dd><p>The processor generates *roff output, the standard format for unix
manpages.</p></dd>
<dt><b class="const">html</b></dt>
<dd><p>The processor generates HTML output, for usage in and display by web
browsers. This engine is currently the only one providing the various
engine parameters required for the additional customaization of the
output.</p></dd>
<dt><b class="const">tmml</b></dt>
<dd><p>The processor generates TMML output, the Tcl Manpage Markup Language,
a derivative of XML.</p></dd>
<dt><b class="const">latex</b></dt>
<dd><p>The processor generates LaTeX output.</p></dd>
<dt><b class="const">wiki</b></dt>
<dd><p>The processor generates Wiki markup as understood by <b class="syscmd">wikit</b>.</p></dd>
<dt><b class="const">list</b></dt>
<dd><p>The processor extracts the information provided by <b class="cmd">manpage_begin</b>.
This format is used internally to extract the meta data from which
both table of contents and keyword index are derived from.</p></dd>
<dt><b class="const">null</b></dt>
<dd><p>The processor does not generate any output. This is equivalent to
<b class="const">validate</b>.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">DIRECTORY STRUCTURES</a></h3>
<p>In this section we describe the directory structures generated by the
application under <i class="arg">output</i> when processing all documents in an
<i class="arg">inputdirectory</i>. In other words, this is only relevant to the use
cases [2] and [3].</p>
<dl class="doctools_definitions">
<dt>[2]</dt>
<dd><p>The following directory structure is created when processing a single
set of input documents. The file extension used is for output in
HTML, but that is not relevant to the structure and was just used to
have proper file names.</p>
<pre class="doctools_example">
output/
toc.html
index.html
files/
path/to/FOO.html
</pre>
<p>The last line in the example shows the document
generated for a file FOO located at</p>
<pre class="doctools_example">
inputdirectory/path/to/FOO
</pre>
</dd>
<dt>[3]</dt>
<dd><p>When merging many packages into a unified set of documents the
generated directory structure is a bit deeper:</p>
<pre class="doctools_example">
output
.toc
.idx
.tocdoc
.idxdoc
.xrf
toc.html
index.html
FOO1/
...
FOO2/
toc.html
files/
path/to/BAR.html
</pre>
<p>Each of the directories FOO1, ... contains the documents generated for
the package FOO1, ... and follows the structure shown for use case
[2]. The only exception is that there is no per-package index.</p>
<p>The files "<b class="file">.toc</b>", "<b class="file">.idx</b>", and "<b class="file">.xrf</b>" contain the
internal status of the whole output and will be read and updated by
the next invokation. Their contents will not be documented. Remove
these files when all packages wanted for the output have been
processed, i.e. when the output is complete.</p>
<p>The files "<b class="file">.tocdoc</b>", and "<b class="file">.idxdoc</b>", are intermediate files
in doctoc and docidx markup, respectively, containing the main table
of contents and keyword index for the set of documents before their
conversion to the chosen output format.
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../modules/doctools/docidx_intro.html">docidx introduction</a>, <a href="../modules/doctools/doctoc_intro.html">doctoc introduction</a>, <a href="../modules/doctools/doctools_intro.html">doctools introduction</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#html">HTML</a>, <a href="../../../index.html#tmml">TMML</a>, <a href="../../../index.html#conversion">conversion</a>, <a href="../../../index.html#docidx">docidx</a>, <a href="../../../index.html#doctoc">doctoc</a>, <a href="../../../index.html#doctools">doctools</a>, <a href="../../../index.html#manpage">manpage</a>, <a href="../../../index.html#markup">markup</a>, <a href="../../../index.html#nroff">nroff</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2013 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/nns.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
<div class='fossil-doc' data-title='nns - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nns(n) 1.1 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nns - Name service facility, Commandline Client Application</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">USE CASES</a></li>
<li class="doctools_subsection"><a href="#subsection2">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">nns</b> <b class="method">bind</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span> <i class="arg">name</i> <i class="arg">data</i></a></li>
<li><a href="#2"><b class="cmd">nns</b> <b class="method">search</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span> <span class="opt">?<b class="option">-continuous</b>?</span> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#3"><b class="cmd">nns</b> <b class="method">ident</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span></a></li>
<li><a href="#4"><b class="cmd">nns</b> <b class="method">who</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read <i class="term"><a href="../modules/nns/nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>The application described by this document, <b class="syscmd">nns</b>, is a simple
command line client for the nano name service facility provided by the
Tcllib packages <b class="package"><a href="../modules/nns/nns_client.html">nameserv</a></b>, and <b class="package"><a href="../modules/nns/nns_server.html">nameserv::server</a></b>.
Beyond that the application's sources also serve as an example of how
to use the client package <b class="package"><a href="../modules/nns/nns_client.html">nameserv</a></b>. All abilities of a
client are covered, from configuration to registration of names to
searching.</p>
<p>This name service facility has nothing to do with the Internet's
<i class="term">Domain Name System</i>, otherwise known as <i class="term"><a href="../../../index.html#dns">DNS</a></i>. If the
reader is looking for a package dealing with that please see either of
the packages <b class="package"><a href="../modules/dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>, both found in Tcllib
too.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">USE CASES</a></h3>
<p><b class="syscmd">nns</b> was written with the following two main use cases in
mind.</p>
<ol class="doctools_enumerated">
<li><p>Registration of a name/data pair in the name service.</p></li>
<li><p>Searching the name service for entries matching a glob pattern.</p></li>
</ol>
<p>Beyond the above we also want to be able to identify the client, and
get information about the name service.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">nns</b> <b class="method">bind</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span> <i class="arg">name</i> <i class="arg">data</i></a></dt>
<dd><p>This form registers the <i class="arg">name</i>/<i class="arg">data</i> pair in the specified
name service. In this form the command will <em>not</em> exit to keep
the registration alive. The user has to kill it explicitly, either by
sending a signal, or through the job-control facilities of the shell
in use. It will especially survive the loss of the connection to the
name service and reestablish the <i class="arg">name</i>/<i class="arg">data</i> pair when the
connection is restored.</p>
<p>The options to specify the name service will be explained later, in
section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p></dd>
<dt><a name="2"><b class="cmd">nns</b> <b class="method">search</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span> <span class="opt">?<b class="option">-continuous</b>?</span> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>This form searches the specified name service for entries matching the
glob-<i class="arg">pattern</i> and prints them to stdout, with each entry on its
own line. If no pattern is specified it defaults to <b class="const">*</b>,
matching everything.</p>
<p>The options to specify the name service will be explained later, in
section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p>
<p>If the option <b class="option">-continuous</b> is specified the client will not
exit after performing the search, but start to continuously monitor
the service for changes to the set of matching entries, appropriately
updating the display as changes arrive. In that form it will
especially also survive the loss of the connection to the name service
and reestablish the search when the connection is restored.</p></dd>
<dt><a name="3"><b class="cmd">nns</b> <b class="method">ident</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span></a></dt>
<dd><p>This form asks the specified name service for the version and features
of the name service protocol it supports and prints the results to
stdout.</p>
<p>The options to specify the name service will be explained later, in
section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">nns</b> <b class="method">who</b></a></dt>
<dd><p>This form prints name, version, and protocol version of the
application to stdout.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application</p>
<dl class="doctools_options">
<dt><b class="option">-host</b> name|ipaddress</dt>
<dd><p>If this option is not specified it defaults to <b class="const">localhost</b>. It
specifies the name or ip-address of the host the name service to talk
to is running on.</p></dd>
<dt><b class="option">-port</b> number</dt>
<dd><p>If this option is not specified it defaults to <b class="const">38573</b>. It
specifies the TCP port the name service to talk to is listening on for
requests.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../modules/nns/nns_client.html">nameserv(n)</a>, <a href="../modules/nns/nns_common.html">nameserv::common(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#application">application</a>, <a href="../../../index.html#client">client</a>, <a href="../../../index.html#name_service">name service</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/nnsd.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<div class='fossil-doc' data-title='nnsd - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nnsd(n) 1.0.1 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nnsd - Name service facility, Commandline Server Application</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">USE CASES</a></li>
<li class="doctools_subsection"><a href="#subsection2">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">nnsd</b> <span class="opt">?<b class="option">-localonly</b> <i class="arg">flag</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read <i class="term"><a href="../modules/nns/nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>The application described by this document, <b class="syscmd"><a href="nns.html">nns</a></b>, is a simple
command line server for the nano name service facility provided by the
Tcllib packages <b class="package"><a href="../modules/nns/nns_client.html">nameserv</a></b>, and <b class="package"><a href="../modules/nns/nns_server.html">nameserv::server</a></b>.
Beyond that the application's sources also serve as an example of how
to use the server package <b class="package"><a href="../modules/nns/nns_server.html">nameserv::server</a></b>.</p>
<p>This name service facility has nothing to do with the Internet's
<i class="term">Domain Name System</i>, otherwise known as <i class="term"><a href="../../../index.html#dns">DNS</a></i>. If the
reader is looking for a package dealing with that please see either of
the packages <b class="package"><a href="../modules/dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>, both found in Tcllib
too.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">USE CASES</a></h3>
<p><b class="syscmd">nnsd</b> was written with the following main use case in
mind.</p>
<ol class="doctools_enumerated">
<li><p>Run a nano name service on some host.</p></li>
</ol>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">nnsd</b> <span class="opt">?<b class="option">-localonly</b> <i class="arg">flag</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span></a></dt>
<dd><p>The command configures a server per the specified options and starts
it. The command will not exit on its own, as it keeps the name service
database wholly in memory. The user has to kill it explicitly, either
by sending a a signal, or through the job-control facilities of the
shell in use.</p>
<p>The options to configure the name service are explained in section
<span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application</p>
<dl class="doctools_options">
<dt><b class="option">-localonly</b> bool</dt>
<dd><p>If this option is not specified it defaults to <b class="const">true</b>, i.e.
acceptance of only local connections. The server will accept remote
connections, i.e. connections from other hosts, if and only if this
option is configured to <b class="const">false</b>.</p></dd>
<dt><b class="option">-port</b> number</dt>
<dd><p>If this option is not specified it defaults to <b class="const">38573</b>. It
specifies the TCP port the server has to listen on for requests.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../modules/nns/nns_common.html">nameserv::common(n)</a>, <a href="../modules/nns/nns_server.html">nameserv::server(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#application">application</a>, <a href="../../../index.html#name_service">name service</a>, <a href="../../../index.html#server">server</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/nnslog.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<div class='fossil-doc' data-title='nnslog - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nnslog(n) 1.0 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nnslog - Name service facility, Commandline Logging Client Application</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">USE CASES</a></li>
<li class="doctools_subsection"><a href="#subsection2">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">nnslog</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read <i class="term"><a href="../modules/nns/nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>The application described by this document, <b class="syscmd">nnslog</b>, is a
simple command line client for the nano name service facility provided
by the Tcllib packages <b class="package"><a href="../modules/nns/nns_client.html">nameserv</a></b>, and <b class="package"><a href="../modules/nns/nns_server.html">nameserv::server</a></b>.</p>
<p>It essentially implements "<b class="syscmd"><a href="nns.html">nns</a></b> search -continuous *", but
uses a different output formatting. Instead of continuously showing
the current contents of the server in the terminal it simply logs all
received add/remove events to <b class="const">stdout</b>.</p>
<p>This name service facility has nothing to do with the Internet's
<i class="term">Domain Name System</i>, otherwise known as <i class="term"><a href="../../../index.html#dns">DNS</a></i>. If the
reader is looking for a package dealing with that please see either of
the packages <b class="package"><a href="../modules/dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>, both found in Tcllib
too.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">USE CASES</a></h3>
<p><b class="syscmd">nnslog</b> was written with the following main use case in mind.</p>
<ol class="doctools_enumerated">
<li><p>Monitoring the name service for all changes and logging them in a text
terminal.</p></li>
</ol>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">nnslog</b> <span class="opt">?<b class="option">-host</b> <i class="arg">host</i>?</span> <span class="opt">?<b class="option">-port</b> <i class="arg">port</i>?</span></a></dt>
<dd><p>The command connects to the specified name service, sets up a search
for all changes and then prints all received events to stdout, with
each events on its own line. The command will not exit until it is
explicitly terminated by the user. It will especially survive the loss
of the connection to the name service and reestablish the search and
log when the connection is restored.</p>
<p>The options to specify the name service will be explained later, in
section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application</p>
<dl class="doctools_options">
<dt><b class="option">-host</b> name|ipaddress</dt>
<dd><p>If this option is not specified it defaults to <b class="const">localhost</b>. It
specifies the name or ip-address of the host the name service to talk
to is running on.</p></dd>
<dt><b class="option">-port</b> number</dt>
<dd><p>If this option is not specified it defaults to <b class="const">38573</b>. It
specifies the TCP port the name service to talk to is listening on for
requests.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../modules/nns/nns_client.html">nameserv(n)</a>, <a href="../modules/nns/nns_common.html">nameserv::common(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#application">application</a>, <a href="../../../index.html#client">client</a>, <a href="../../../index.html#name_service">name service</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/page.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
|
<div class='fossil-doc' data-title='page - Development Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page(n) 1.0 tcllib "Development Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page - Parser Generator</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection2">OPERATION</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
<li class="doctools_subsection"><a href="#subsection4">PLUGINS</a></li>
<li class="doctools_subsection"><a href="#subsection5">PLUGIN LOCATIONS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">page</b> <span class="opt">?<i class="arg">options</i>...?</span> <span class="opt">?<i class="arg">input</i> <span class="opt">?<i class="arg">output</i>?</span>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The application described by this document, <b class="syscmd">page</b>, is actually
not just a parser generator, as the name implies, but a generic tool
for the execution of arbitrary transformations on texts.</p>
<p>Its genericity comes through the use of <i class="term">plugins</i> for reading,
transforming, and writing data, and the predefined set of plugins
provided by Tcllib is for the generation of memoizing recursive
descent parsers (aka <i class="term">packrat parsers</i>) from grammar
specifications (<i class="term">Parsing Expression Grammars</i>).</p>
<p><b class="syscmd">page</b> is written on top of the package
<b class="package">page::pluginmgr</b>, wrapping its functionality into a command
line based application. All the other <b class="package">page::*</b> packages are
plugin and/or supporting packages for the generation of parsers. The
parsers themselves are based on the packages <b class="package"><a href="../modules/grammar_peg/peg.html">grammar::peg</a></b>,
<b class="package"><a href="../modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></b>, and <b class="package">grammar::mengine</b>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">page</b> <span class="opt">?<i class="arg">options</i>...?</span> <span class="opt">?<i class="arg">input</i> <span class="opt">?<i class="arg">output</i>?</span>?</span></a></dt>
<dd><p>This is general form for calling <b class="syscmd">page</b>. The application will
read the contents of the file <i class="arg">input</i>, process them under the
control of the specified <i class="arg">options</i>, and then write the result to
the file <i class="arg">output</i>.</p>
<p>If <i class="arg">input</i> is the string <b class="const">-</b> the data to process will be
read from <b class="const">stdin</b> instead of a file. Analogously the result will
be written to <b class="const">stdout</b> instead of a file if <i class="arg">output</i> is the
string <b class="const">-</b>. A missing output or input specification causes the
application to assume <b class="const">-</b>.</p>
<p>The detailed specifications of the recognized <i class="arg">options</i> are
provided in section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p>
<dl class="doctools_arguments">
<dt>path <i class="arg">input</i> (in)</dt>
<dd><p>This argument specifies the path to the file to be processed by the
application, or <b class="const">-</b>. The last value causes the application to
read the text from <b class="const">stdin</b>. Otherwise it has to exist, and be
readable. If the argument is missing <b class="const">-</b> is assumed.</p></dd>
<dt>path <i class="arg">output</i> (in)</dt>
<dd><p>This argument specifies where to write the generated text. It can be
the path to a file, or <b class="const">-</b>. The last value causes the
application to write the generated documented to <b class="const">stdout</b>.</p>
<p>If the file <i class="arg">output</i> does not exist then
[file dirname $output] has to exist and must be a writable
directory, as the application will create the fileto write to.</p>
<p>If the argument is missing <b class="const">-</b> is assumed.</p></dd>
</dl></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">OPERATION</a></h3>
<p>... reading ... transforming ... writing - plugins - pipeline ...</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application. Options are always processed in order. I.e. of both
<b class="option">--help</b> and <b class="option">--version</b> are specified the option
encountered first has precedence.</p>
<p>Unknown options specified before any of the options <b class="option">-rd</b>,
<b class="option">-wr</b>, or <b class="option">-tr</b> will cause processing to abort with an
error. Unknown options coming in between these options, or after the
last of them are assumed to always take a single argument and are
associated with the last plugin option coming before them. They will
be checked after all the relevant plugins, and thus the options they
understand, are known. I.e. such unknown options cause error if and
only if the plugin option they are associated with does not understand
them, and was not superceded by a plugin option coming after.</p>
<p>Default options are used if and only if the command line did not
contain any options at all. They will set the application up as a
PEG-based parser generator. The exact list of options is</p>
<pre class="doctools_example">-c peg</pre>
<p>And now the recognized options and their arguments, if they have any:</p>
<dl class="doctools_options">
<dt><b class="option">--help</b></dt>
<dd></dd>
<dt><b class="option">-h</b></dt>
<dd></dd>
<dt><b class="option">-?</b></dt>
<dd><p>When one of these options is found on the command line all arguments
coming before or after are ignored. The application will print a short
description of the recognized options and exit.</p></dd>
<dt><b class="option">--version</b></dt>
<dd></dd>
<dt><b class="option">-V</b></dt>
<dd><p>When one of these options is found on the command line all arguments
coming before or after are ignored. The application will print its
own revision and exit.</p></dd>
<dt><b class="option">-P</b></dt>
<dd><p>This option signals the application to activate visual feedback while
reading the input.</p></dd>
<dt><b class="option">-T</b></dt>
<dd><p>This option signals the application to collect statistics while
reading the input and to print them after reading has completed,
before processing started.</p></dd>
<dt><b class="option">-D</b></dt>
<dd><p>This option signals the application to activate logging in the Safe
base, for the debugging of problems with plugins.</p></dd>
<dt><b class="option">-r</b> parser</dt>
<dd></dd>
<dt><b class="option">-rd</b> parser</dt>
<dd></dd>
<dt><b class="option">--reader</b> parser</dt>
<dd><p>These options specify the plugin the application has to use for
reading the <i class="arg">input</i>. If the options are used multiple times the
last one will be used.</p></dd>
<dt><b class="option">-w</b> generator</dt>
<dd></dd>
<dt><b class="option">-wr</b> generator</dt>
<dd></dd>
<dt><b class="option">--writer</b> generator</dt>
<dd><p>These options specify the plugin the application has to use for
generating and writing the final <i class="arg">output</i>. If the options are used
multiple times the last one will be used.</p></dd>
<dt><b class="option">-t</b> process</dt>
<dd></dd>
<dt><b class="option">-tr</b> process</dt>
<dd></dd>
<dt><b class="option">--transform</b> process</dt>
<dd><p>These options specify a plugin to run on the input. In contrast to
readers and writers each use will <em>not</em> supersede previous
uses, but add each chosen plugin to a list of transformations, either
at the front, or the end, per the last seen use of either option
<b class="option">-p</b> or <b class="option">-a</b>. The initial default is to append the new
transformations.</p></dd>
<dt><b class="option">-a</b></dt>
<dd></dd>
<dt><b class="option">--append</b></dt>
<dd><p>These options signal the application that all following
transformations should be added at the end of the list of
transformations.</p></dd>
<dt><b class="option">-p</b></dt>
<dd></dd>
<dt><b class="option">--prepend</b></dt>
<dd><p>These options signal the application that all following
transformations should be added at the beginning of the list of
transformations.</p></dd>
<dt><b class="option">--reset</b></dt>
<dd><p>This option signals the application to clear the list of
transformations. This is necessary to wipe out the default
transformations used.</p></dd>
<dt><b class="option">-c</b> file</dt>
<dd></dd>
<dt><b class="option">--configuration</b> file</dt>
<dd><p>This option causes the application to load a configuration file and/or
plugin. This is a plugin which in essence provides a pre-defined set
of commandline options. They are processed exactly as if they have
been specified in place of the option and its arguments. This means
that unknown options found at the beginning of the configuration file
are associated with the last plugin, even if that plugin was specified
before the configuration file itself. Conversely, unknown options
coming after the configuration file can be associated with a plugin
specified in the file.</p>
<p>If the argument is a file which cannot be loaded as a plugin the
application will assume that its contents are a list of options and
their arguments, separated by space, tabs, and newlines. Options and
argumentes containing spaces can be quoted via double-quotes (") and
quotes ('). The quote character can be specified within in a quoted
string by doubling it. Newlines in a quoted string are accepted as is.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">PLUGINS</a></h3>
<p><b class="syscmd">page</b> makes use of four different types of plugins, namely:
readers, writers, transformations, and configurations. Here we provide
only a basic introduction on how to use them from <b class="syscmd">page</b>. The
exact APIs provided to and expected from the plugins can be found in
the documentation for <b class="package">page::pluginmgr</b>, for those who wish to
write their own plugins.</p>
<p>Plugins are specified as arguments to the options <b class="option">-r</b>,
<b class="option">-w</b>, <b class="option">-t</b>, <b class="option">-c</b>, and their equivalent longer
forms. See the section <span class="sectref"><a href="#subsection3">OPTIONS</a></span> for reference.</p>
<p>Each such argument will be first treated as the name of a file and
this file is loaded as the plugin. If however there is no file with
that name, then it will be translated into the name of a package, and
this package is then loaded. For each type of plugins the package
management searches not only the regular paths, but a set application-
and type-specific paths as well. Please see the section
<span class="sectref"><a href="#subsection5">PLUGIN LOCATIONS</a></span> for a listing of all paths and their
sources.</p>
<dl class="doctools_definitions">
<dt><b class="option">-c</b> <i class="arg">name</i></dt>
<dd><p>Configurations. The name of the package for the plugin <i class="arg">name</i> is
"page::config::<i class="arg">name</i>".</p>
<p>We have one predefined plugin:</p>
<dl class="doctools_definitions">
<dt><em>peg</em></dt>
<dd><p>It sets the application up as a parser generator accepting parsing
expression grammars and writing a packrat parser in Tcl. The actual
arguments it specifies are:</p>
<pre class="doctools_example">
--reset
--append
--reader peg
--transform reach
--transform use
--writer me
</pre>
</dd>
</dl></dd>
<dt><b class="option">-r</b> <i class="arg">name</i></dt>
<dd><p>Readers. The name of the package for the plugin <i class="arg">name</i> is
"page::reader::<i class="arg">name</i>".</p>
<p>We have five predefined plugins:</p>
<dl class="doctools_definitions">
<dt><em>peg</em></dt>
<dd><p>Interprets the input as a parsing expression grammar (<i class="term"><a href="../../../index.html#peg">PEG</a></i>) and
generates a tree representation for it. Both the syntax of PEGs and
the structure of the tree representation are explained in their own
manpages.</p></dd>
<dt><em>hb</em></dt>
<dd><p>Interprets the input as Tcl code as generated by the writer plugin
<em>hb</em> and generates its tree representation.</p></dd>
<dt><em>ser</em></dt>
<dd><p>Interprets the input as the serialization of a PEG, as generated by
the writer plugin <em>ser</em>, using the package
<b class="package"><a href="../modules/grammar_peg/peg.html">grammar::peg</a></b>.</p></dd>
<dt><em>lemon</em></dt>
<dd><p>Interprets the input as a grammar specification as understood by
Richard Hipp's <i class="term"><a href="../../../index.html#lemon">LEMON</a></i> parser generator and generates a tree
representation for it. Both the input syntax and the structure of the
tree representation are explained in their own manpages.</p></dd>
<dt><em>treeser</em></dt>
<dd><p>Interprets the input as the serialization of a
<b class="package"><a href="../modules/struct/struct_tree.html">struct::tree</a></b>. It is validated as such,
but nothing else. It is <em>not</em> assumed to
be the tree representation of a grammar.</p></dd>
</dl></dd>
<dt><b class="option">-w</b> <i class="arg">name</i></dt>
<dd><p>Writers. The name of the package for the plugin <i class="arg">name</i> is
"page::writer::<i class="arg">name</i>".</p>
<p>We have eight predefined plugins:</p>
<dl class="doctools_definitions">
<dt><em>identity</em></dt>
<dd><p>Simply writes the incoming data as it is, without making any
changes. This is good for inspecting the raw result of a reader or
transformation.</p></dd>
<dt><em>null</em></dt>
<dd><p>Generates nothing, and ignores the incoming data structure.</p></dd>
<dt><em>tree</em></dt>
<dd><p>Assumes that the incoming data structure is a <b class="package"><a href="../modules/struct/struct_tree.html">struct::tree</a></b>
and generates an indented textual representation of all nodes, their
parental relationships, and their attribute information.</p></dd>
<dt><em>peg</em></dt>
<dd><p>Assumes that the incoming data structure is a tree representation of a
<i class="term"><a href="../../../index.html#peg">PEG</a></i> or other other grammar and writes it out as a PEG. The
result is nicely formatted and partially simplified (strings as
sequences of characters). A pretty printer in essence, but can also be
used to obtain a canonical representation of the input grammar.</p></dd>
<dt><em>tpc</em></dt>
<dd><p>Assumes that the incoming data structure is a tree representation of a
<i class="term"><a href="../../../index.html#peg">PEG</a></i> or other other grammar and writes out Tcl code defining a
package which defines a <b class="package"><a href="../modules/grammar_peg/peg.html">grammar::peg</a></b> object containing the
grammar when it is loaded into an interpreter.</p></dd>
<dt><em>hb</em></dt>
<dd><p>This is like the writer plugin <em>tpc</em>, but it writes only the
statements which define stat expression and grammar rules. The code
making the result a package is left out.</p></dd>
<dt><em>ser</em></dt>
<dd><p>Assumes that the incoming data structure is a tree representation of a
<i class="term"><a href="../../../index.html#peg">PEG</a></i> or other other grammar, transforms it internally into a
<b class="package"><a href="../modules/grammar_peg/peg.html">grammar::peg</a></b> object and writes out its serialization.</p></dd>
<dt><em>me</em></dt>
<dd><p>Assumes that the incoming data structure is a tree representation of a
<i class="term"><a href="../../../index.html#peg">PEG</a></i> or other other grammar and writes out Tcl code defining a
package which implements a memoizing recursive descent parser based on
the match engine (ME) provided by the package <b class="package">grammar::mengine</b>.</p></dd>
</dl></dd>
<dt><b class="option">-t</b> <i class="arg">name</i></dt>
<dd><p>Transformers. The name of the package for the plugin <i class="arg">name</i> is
"page::transform::<i class="arg">name</i>".</p>
<p>We have two predefined plugins:</p>
<dl class="doctools_definitions">
<dt><em>reach</em></dt>
<dd><p>Assumes that the incoming data structure is a tree representation of a
<i class="term"><a href="../../../index.html#peg">PEG</a></i> or other other grammar. It determines which nonterminal
symbols and rules are reachable from start-symbol/expression. All
nonterminal symbols which were not reached are removed.</p></dd>
<dt><em>use</em></dt>
<dd><p>Assumes that the incoming data structure is a tree representation of a
<i class="term"><a href="../../../index.html#peg">PEG</a></i> or other other grammar. It determines which nonterminal
symbols and rules are able to generate a <em>finite</em> sequences of
terminal symbols (in the sense for a Context Free Grammar). All
nonterminal symbols which were not deemed useful in this sense are
removed.</p></dd>
</dl></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">PLUGIN LOCATIONS</a></h3>
<p>The application-specific paths searched by <b class="syscmd">page</b> either are,
or come from:</p>
<ol class="doctools_enumerated">
<li><p>The directory "<b class="file">~/.page/plugin</b>"</p></li>
<li><p>The environment variable <i class="term">PAGE_PLUGINS</i></p></li>
<li><p>The registry entry <i class="term">HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\PLUGINS</i></p></li>
<li><p>The registry entry <i class="term">HKEY_CURRENT_USER\SOFTWARE\PAGE\PLUGINS</i></p></li>
</ol>
<p>The type-specific paths searched by <b class="syscmd">page</b> either are, or come
from:</p>
<ol class="doctools_enumerated">
<li><p>The directory "<b class="file">~/.page/plugin/<TYPE></b>"</p></li>
<li><p>The environment variable <i class="term">PAGE_<TYPE>_PLUGINS</i></p></li>
<li><p>The registry entry <i class="term">HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\<TYPE>\PLUGINS</i></p></li>
<li><p>The registry entry <i class="term">HKEY_CURRENT_USER\SOFTWARE\PAGE\<TYPE>\PLUGINS</i></p></li>
</ol>
<p>Where the placeholder <i class="term"><TYPE></i> is always one of the values below,
properly capitalized.</p>
<ol class="doctools_enumerated">
<li><p>reader</p></li>
<li><p>writer</p></li>
<li><p>transform</p></li>
<li><p>config</p></li>
</ol>
<p>The registry entries are specific to the Windows(tm) platform, all
other platforms will ignore them.</p>
<p>The contents of both environment variables and registry entries are
interpreted as a list of paths, with the elements separated by either
colon (Unix), or semicolon (Windows).</p>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>page::pluginmgr</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#parser_generator">parser generator</a>, <a href="../../../index.html#text_processing">text processing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/pt.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
|
<div class='fossil-doc' data-title='pt - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt - Parser Tools Application</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Command Line</a></li>
<li class="doctools_section"><a href="#section3">PEG Specification Language</a></li>
<li class="doctools_section"><a href="#section4">JSON Grammar Exchange</a></li>
<li class="doctools_section"><a href="#section5">C Parser Embedded In Tcl</a></li>
<li class="doctools_section"><a href="#section6">C Parser</a></li>
<li class="doctools_section"><a href="#section7">Snit Parser</a></li>
<li class="doctools_section"><a href="#section8">TclOO Parser</a></li>
<li class="doctools_section"><a href="#section9">Grammar Container</a></li>
<li class="doctools_section"><a href="#section10">Example</a></li>
<li class="doctools_section"><a href="#section11">Internals</a></li>
<li class="doctools_section"><a href="#section12">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt</b> <b class="method">generate</b> <i class="arg">resultformat</i> <span class="opt">?<i class="arg">options...</i>?</span> <i class="arg">resultfile</i> <i class="arg">inputformat</i> <i class="arg">inputfile</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="../modules/pt/pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This document describes <b class="cmd">pt</b>, the main application of the module,
a <i class="term"><a href="../../../index.html#parser_generator">parser generator</a></i>. Its intended audience are people who wish
to create a parser for some language of theirs. Should you wish to
modify the application instead, please see the section about the
application's <span class="sectref"><a href="#section11">Internals</a></span> for the basic references.</p>
<p>It resides in the User Application Layer of Parser Tools.</p>
<p><img alt="arch_user_app" src="../../../image/arch_user_app.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Command Line</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt</b> <b class="method">generate</b> <i class="arg">resultformat</i> <span class="opt">?<i class="arg">options...</i>?</span> <i class="arg">resultfile</i> <i class="arg">inputformat</i> <i class="arg">inputfile</i></a></dt>
<dd><p>This sub-command of the application reads the parsing expression
grammar stored in the <i class="arg">inputfile</i> in the format <i class="arg">inputformat</i>,
converts it to the <i class="arg">resultformat</i> under the direction of the
(format-specific) set of options specified by the user and stores the
result in the <i class="arg">resultfile</i>.</p>
<p>The <i class="arg">inputfile</i> has to exist, while the <i class="arg">resultfile</i> may be
created, overwriting any pre-existing content of the file. Any missing
directory in the path to the <i class="arg">resultfile</i> will be created as well.</p>
<p>The exact form of the result for, and the set of options supported by
the known result-formats, are explained in the upcoming sections of
this document, with the list below providing an index mapping between
format name and its associated section. In alphabetical order:</p>
<dl class="doctools_definitions">
<dt><b class="const">c</b></dt>
<dd><p>A <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section6">C Parser</a></span>.</p></dd>
<dt><b class="const">container</b></dt>
<dd><p>A <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section9">Grammar Container</a></span>.</p></dd>
<dt><b class="const">critcl</b></dt>
<dd><p>A <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section5">C Parser Embedded In Tcl</a></span>.</p></dd>
<dt><b class="const">json</b></dt>
<dd><p>A <i class="term">input</i>- and <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section4">JSON Grammar Exchange</a></span>.</p></dd>
<dt><b class="const">oo</b></dt>
<dd><p>A <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section8">TclOO Parser</a></span>.</p></dd>
<dt><b class="const">peg</b></dt>
<dd><p>A <i class="term">input</i>- and <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section3">PEG Specification Language</a></span>.</p></dd>
<dt><b class="const">snit</b></dt>
<dd><p>A <i class="term">resultformat</i>. See section <span class="sectref"><a href="#section7">Snit Parser</a></span>.</p></dd>
</dl></dd>
</dl>
<p>Of the seven possible results four are parsers outright (<b class="const">c</b>,
<b class="const">critcl</b>, <b class="const">oo</b>, and <b class="const">snit</b>), one (<b class="const">container</b>)
provides code which can be used in conjunction with a generic parser
(also known as a grammar interpreter), and the last two (<b class="const">json</b>
and <b class="const">peg</b>) are doing double-duty as input formats, allowing the
transformation of grammars for exchange, reformatting, and the like.</p>
<p>The created parsers fall into three categories:</p>
<p><img alt="gen_options" src="../../../image/gen_options.png"></p>
<dl class="doctools_definitions">
<dt><b class="const">Specialized parsers implemented in C</b></dt>
<dd><p>The fastest parsers are created when using the result formats
<b class="const">c</b> and <b class="const">critcl</b>. The first returns the raw C code for the
parser, while the latter wraps it into a Tcl package using
<i class="term">CriTcl</i>.</p>
<p>This makes the latter much easier to use than the former. On the other
hand, the former can be adapted to the users' requirements through a
multitude of options, allowing for things like usage of the parser
outside of a Tcl environment, something the <b class="const">critcl</b> format
doesn't support. As such the <b class="const">c</b> format is meant for more
advanced users, or users with special needs.</p>
<p>A disadvantage of all the parsers in this section is the need to run
them through a C compiler to make them actually executable. This is
not something everyone has the necessary tools for. The parsers in the
next section are for people under such restrictions.</p></dd>
<dt><b class="const">Specialized parsers implemented in Tcl</b></dt>
<dd><p>As the parsers in this section are implemented in Tcl they are quite a
bit slower than anything from the previous section. On the other hand
this allows them to be used in pure-Tcl environments, or in
environments which allow only a limited set of binary packages. In the
latter case it will be advantageous to lobby for the inclusion of the
C-based runtime support (notes below) into the environment to reduce
the impact of Tcl's on the speed of these parsers.</p>
<p>The relevant formats are <b class="const">snit</b> and <b class="const">oo</b>. Both place their
result into a Tcl package containing a <b class="cmd">snit::type</b>, or TclOO
<b class="cmd"><a href="../../../index.html#class">class</a></b> respectively.</p>
<p>Of the supporting runtime, which is the package <b class="package"><a href="../modules/pt/pt_rdengine.html">pt::rde</a></b>, the
user has to know nothing but that it does exist and that the parsers
are dependent on it. Knowledge of the API exported by the runtime for
the parsers' consumption is <em>not</em> required by the parsers' users.</p></dd>
<dt><b class="const">Interpreted parsing implemented in Tcl</b></dt>
<dd><p>The last category, grammar interpretation. This means that an
interpreter for parsing expression grammars takes the description of
the grammar to parse input for, and uses it guide the parsing process.
This is the slowest of the available options, as the interpreter has
to continually run through the configured grammar, whereas the
specialized parsers of the previous sections have the relevant
knowledge about the grammar baked into them.</p>
<p>The only places where using interpretation make sense is where the
grammar for some input may be changed interactively by the user, as
the interpretation allows for quick turnaround after each change,
whereas the previous methods require the generation of a whole new
parser, which is not as fast.
On the other hand, wherever the grammar to use is fixed, the previous
methods are much more advantageous as the time to generate the parser
is minuscule compared to the time the parser code is in use.</p>
<p>The relevant result format is <b class="const">container</b>.
It (quickly) generates grammar descriptions (instead of a full parser)
which match the API expected by ParserTools' grammar interpreter.
The latter is provided by the package <b class="package"><a href="../modules/pt/pt_peg_interp.html">pt::peg::interp</a></b>.</p></dd>
</dl>
<p>All the parsers generated by <b class="const">critcl</b>, <b class="const">snit</b>, and
<b class="const">oo</b>, and the grammar interpreter share a common API for access
to the actual parsing functionality, making them all
plug-compatible.
It is described in the <i class="term"><a href="../modules/pt/pt_parser_api.html">Parser API</a></i> specification document.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PEG Specification Language</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
<p>For either an introduction to or the formal specification of the
language, please go and read the <i class="term"><a href="../modules/pt/pt_peg_language.html">PEG Language Tutorial</a></i>.</p>
<p>When used as a result-format this format supports the following
options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this option is a string into which to put the generated
text and the values of the other options. The various locations for
user-data are expected to be specified with the placeholders listed
below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">PEG</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated text.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">JSON Grammar Exchange</a></h2>
<p>The <b class="const">json</b> format for parsing expression grammars was written as
a data exchange format not bound to Tcl. It was defined to allow the
exchange of grammars with PackRat/PEG based parser generators for
other languages.</p>
<p>For the formal specification of the JSON grammar exchange format,
please go and read <i class="term"><a href="../modules/pt/pt_json_language.html">The JSON Grammar Exchange Format</a></i>.</p>
<p>When used as a result-format this format supports the following
options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-indented</b> boolean</dt>
<dd><p>If this option is set the system will break the generated JSON across
lines and indent it according to its inner structure, with each key of
a dictionary on a separate line.</p>
<p>If the option is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt><b class="option">-aligned</b> boolean</dt>
<dd><p>If this option is set the system will ensure that the values for the
keys in a dictionary are vertically aligned with each other, for a
nice table effect.
To make this work this also implies that <b class="option">-indented</b> is set.</p>
<p>If the option is not set (the default), the output is formatted as per
the value of <b class="variable">indented</b>, without trying to align the values for
dictionary keys.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">C Parser Embedded In Tcl</a></h2>
<p>The <b class="const">critcl</b> format is executable code, a parser for the
grammar. It is a Tcl package with the actual parser implementation
written in C and embedded in Tcl via the <b class="package">critcl</b> package.</p>
<p>This result-format supports the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-class</b> string</dt>
<dd><p>The value of this option is the name of the class to generate, without
leading colons.
The default value is <b class="const">CLASS</b>.</p>
<p>For a simple value <b class="variable">X</b> without colons, like CLASS, the parser
command will be <b class="variable">X</b>::<b class="variable">X</b>. Whereas for a namespaced value
<b class="variable">X::Y</b> the parser command will be <b class="variable">X::Y</b>.</p></dd>
<dt><b class="option">-package</b> string</dt>
<dd><p>The value of this option is the name of the package to generate.
The default value is <b class="const">PACKAGE</b>.</p></dd>
<dt><b class="option">-version</b> string</dt>
<dd><p>The value of this option is the version of the package to generate.
The default value is <b class="const">1</b>.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">C Parser</a></h2>
<p>The <b class="const">c</b> format is executable code, a parser for the grammar. The
parser implementation is written in C and can be tweaked to the users'
needs through a multitude of options.</p>
<p>The <b class="cmd">critcl</b> format, for example, is implemented as a canned
configuration of these options on top of the generator for <b class="const">c</b>.</p>
<p>This result-format supports the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this option is a string into which to put
the generated text and the other configuration settings. The various
locations for user-data are expected to be specified with the
placeholders listed below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">C/PARAM</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated Tcl code.</p></dd>
</dl>
<p>The following options are special, in that they will
occur within the generated code, and are replaced there as well.</p>
<dl class="doctools_definitions">
<dt><b class="const">@statedecl@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">state-decl</b>.</p></dd>
<dt><b class="const">@stateref@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">state-ref</b>.</p></dd>
<dt><b class="const">@strings@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">string-varname</b>.</p></dd>
<dt><b class="const">@self@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">self-command</b>.</p></dd>
<dt><b class="const">@def@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">fun-qualifier</b>.</p></dd>
<dt><b class="const">@ns@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">namespace</b>.</p></dd>
<dt><b class="const">@main@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">main</b>.</p></dd>
<dt><b class="const">@prelude@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">prelude</b>.</p></dd>
</dl></dd>
<dt><b class="option">-state-decl</b> string</dt>
<dd><p>A C string representing the argument declaration to use in the
generated parsing functions to refer to the parsing state. In essence
type and argument name.
The default value is the string <b class="const">RDE_PARAM p</b>.</p></dd>
<dt><b class="option">-state-ref</b> string</dt>
<dd><p>A C string representing the argument named used in the generated
parsing functions to refer to the parsing state.
The default value is the string <b class="const">p</b>.</p></dd>
<dt><b class="option">-self-command</b> string</dt>
<dd><p>A C string representing the reference needed to call the generated
parser function (methods ...) from another parser fonction, per the
chosen framework (template).
The default value is the empty string.</p></dd>
<dt><b class="option">-fun-qualifier</b> string</dt>
<dd><p>A C string containing the attributes to give to the generated
functions (methods ...), per the chosen framework (template).
The default value is <b class="const">static</b>.</p></dd>
<dt><b class="option">-namespace</b> string</dt>
<dd><p>The name of the C namespace the parser functions (methods, ...) shall
reside in, or a general prefix to add to the function names.
The default value is the empty string.</p></dd>
<dt><b class="option">-main</b> string</dt>
<dd><p>The name of the main function (method, ...) to be called by the chosen
framework (template) to start parsing input.
The default value is <b class="const">__main</b>.</p></dd>
<dt><b class="option">-string-varname</b> string</dt>
<dd><p>The name of the variable used for the table of strings used by the
generated parser, i.e. error messages, symbol names, etc.
The default value is <b class="const">p_string</b>.</p></dd>
<dt><b class="option">-prelude</b> string</dt>
<dd><p>A snippet of code to be inserted at the head of each generated parsing
function.
The default value is the empty string.</p></dd>
<dt><b class="option">-indent</b> integer</dt>
<dd><p>The number of characters to indent each line of the generated code by.
The default value is <b class="const">0</b>.</p></dd>
<dt><b class="option">-comments</b> boolean</dt>
<dd><p>A flag controlling the generation of code comments containing the
original parsing expression a parsing function is for.
The default value is <b class="const">on</b>.</p></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Snit Parser</a></h2>
<p>The <b class="const">snit</b> format is executable code, a parser for the
grammar. It is a Tcl package holding a <b class="cmd">snit::type</b>, i.e. a class,
whose instances are parsers for the input grammar.</p>
<p>This result-format supports the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-class</b> string</dt>
<dd><p>The value of this option is the name of the class to generate, without
leading colons. Note, it serves double-duty as the name of the package
to generate too, if option <b class="option">-package</b> is not specified, see below.
The default value is <b class="const">CLASS</b>, applying if neither option
<b class="option">-class</b> nor <b class="option">-package</b> were specified.</p></dd>
<dt><b class="option">-package</b> string</dt>
<dd><p>The value of this option is the name of the package to generate, without
leading colons. Note, it serves double-duty as the name of the class
to generate too, if option <b class="option">-class</b> is not specified, see above.
The default value is <b class="const">PACKAGE</b>, applying if neither option
<b class="option">-package</b> nor <b class="option">-class</b> were specified.</p></dd>
<dt><b class="option">-version</b> string</dt>
<dd><p>The value of this option is the version of the package to generate.
The default value is <b class="const">1</b>.</p></dd>
</dl>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">TclOO Parser</a></h2>
<p>The <b class="const">oo</b> format is executable code, a parser for the grammar. It
is a Tcl package holding a <b class="package"><a href="../../../index.html#tcloo">TclOO</a></b> class, whose instances are
parsers for the input grammar.</p>
<p>This result-format supports the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-class</b> string</dt>
<dd><p>The value of this option is the name of the class to generate, without
leading colons. Note, it serves double-duty as the name of the package
to generate too, if option <b class="option">-package</b> is not specified, see below.
The default value is <b class="const">CLASS</b>, applying if neither option
<b class="option">-class</b> nor <b class="option">-package</b> were specified.</p></dd>
<dt><b class="option">-package</b> string</dt>
<dd><p>The value of this option is the name of the package to generate, without
leading colons. Note, it serves double-duty as the name of the class
to generate too, if option <b class="option">-class</b> is not specified, see above.
The default value is <b class="const">PACKAGE</b>, applying if neither option
<b class="option">-package</b> nor <b class="option">-class</b> were specified.</p></dd>
<dt><b class="option">-version</b> string</dt>
<dd><p>The value of this option is the version of the package to generate.
The default value is <b class="const">1</b>.</p></dd>
</dl>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">Grammar Container</a></h2>
<p>The <b class="const">container</b> format is another form of describing parsing
expression grammars. While data in this format is executable it does
not constitute a parser for the grammar. It always has to be used in
conjunction with the package <b class="package"><a href="../modules/pt/pt_peg_interp.html">pt::peg::interp</a></b>, a grammar
interpreter.</p>
<p>The format represents grammars by a <b class="cmd">snit::type</b>, i.e. class,
whose instances are API-compatible to the instances of the
<b class="package"><a href="../modules/pt/pt_peg_container.html">pt::peg::container</a></b> package, and which are preloaded with the
grammar in question.</p>
<p>This result-format supports the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-mode</b> <b class="const">bulk</b>|<b class="const">incremental</b></dt>
<dd><p>The value of this option controls which methods of
<b class="package"><a href="../modules/pt/pt_peg_container.html">pt::peg::container</a></b> instances are used to specify the
grammar, i.e. preload it into the container. There are two legal
values, as listed below. The default is <b class="const">bulk</b>.</p>
<dl class="doctools_definitions">
<dt><b class="const">bulk</b></dt>
<dd><p>In this mode the methods <b class="method">start</b>, <b class="method">add</b>, <b class="method">modes</b>,
and <b class="method">rules</b> are used to specify the grammar in a bulk manner,
i.e. as a set of nonterminal symbols, and two dictionaries mapping
from the symbols to their semantic modes and parsing expressions.</p>
<p>This mode is the default.</p></dd>
<dt><b class="const">incremental</b></dt>
<dd><p>In this mode the methods <b class="method">start</b>, <b class="method">add</b>, <b class="method">mode</b>,
and <b class="method">rule</b> are used to specify the grammar piecemal, with each
nonterminal having its own block of defining commands.</p></dd>
</dl></dd>
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this option is a string into which to put the generated
code and the other configuration settings. The various locations for
user-data are expected to be specified with the placeholders listed
below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">CONTAINER</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-name</b>.</p></dd>
<dt><b class="const">@mode@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-mode</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated code.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section10" class="doctools_section"><h2><a name="section10">Example</a></h2>
<p>In this section we are working a complete example, starting with a PEG
grammar and ending with running the parser generated from it over some
input, following the outline shown in the figure below:</p>
<p><img alt="flow" src="../../../image/flow.png"></p>
<p>Our grammar, assumed to the stored in the file "<b class="file">calculator.peg</b>"
is</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>From this we create a snit-based parser
via</p>
<pre class="doctools_example">
pt generate snit calculator.tcl -class calculator -name calculator peg calculator.peg
</pre>
<p>which leaves us with the parser package and class written to the file
"<b class="file">calculator.tcl</b>".
Assuming that this package is then properly installed in a place where
Tcl can find it we can now use this class via a script like</p>
<pre class="doctools_example">
package require calculator
lassign $argv input
set channel [open $input r]
set parser [calculator]
set ast [$parser parse $channel]
$parser destroy
close $channel
... now process the returned abstract syntax tree ...
</pre>
<p>where the abstract syntax tree stored in the variable will look like</p>
<pre class="doctools_example">
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
</pre>
<p>assuming that the input file and channel contained the text</p>
<pre class="doctools_example"> 120+5 </pre>
<p>A more graphical representation of the tree would be</p>
<p><img alt="expr_ast" src="../../../image/expr_ast.png"></p>
<p>Regardless, at this point it is the user's responsibility to work with
the tree to reach whatever goal she desires. I.e. analyze it,
transform it, etc. The package <b class="package"><a href="../modules/pt/pt_astree.html">pt::ast</a></b> should be of help
here, providing commands to walk such ASTs structures in various ways.</p>
<p>One important thing to note is that the parsers used here return a
data structure representing the structure of the input per the grammar
underlying the parser. There are <em>no</em> callbacks during the
parsing process, i.e. no <i class="term">parsing actions</i>, as most other
parsers will have.</p>
<p>Going back to the last snippet of code, the execution of the parser
for some input, note how the parser instance follows the specified
<i class="term"><a href="../modules/pt/pt_parser_api.html">Parser API</a></i>.</p>
</div>
<div id="section11" class="doctools_section"><h2><a name="section11">Internals</a></h2>
<p>This section is intended for users of the application which wish to
modify or extend it. Users only interested in the generation of
parsers can ignore it.</p>
<p>The main functionality of the application is encapsulated in the
package <b class="package"><a href="../modules/pt/pt_pgen.html">pt::pgen</a></b>. Please read it for more information.</p>
</div>
<div id="section12" class="doctools_section"><h2><a name="section12">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#ebnf">EBNF</a>, <a href="../../../index.html#ll_k_">LL(k)</a>, <a href="../../../index.html#peg">PEG</a>, <a href="../../../index.html#tdpl">TDPL</a>, <a href="../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../index.html#expression">expression</a>, <a href="../../../index.html#grammar">grammar</a>, <a href="../../../index.html#matching">matching</a>, <a href="../../../index.html#parser">parser</a>, <a href="../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../index.html#state">state</a>, <a href="../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/apps/tcldocstrip.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
<div class='fossil-doc' data-title='tcldocstrip - Textprocessing toolbox'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../toc.html">Main Table Of Contents</a>
| <a href="../../toc.html">Table Of Contents</a>
| <a href="../../../index.html">Keyword Index</a>
| <a href="../../../toc0.html">Categories</a>
| <a href="../../../toc1.html">Modules</a>
| <a href="../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcldocstrip - Tcl-based Docstrip Processor</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">USE CASES</a></li>
<li class="doctools_subsection"><a href="#subsection2">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">tcldocstrip</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">input</i> <span class="opt">?<i class="arg">guards</i>?</span></a></li>
<li><a href="#2"><b class="cmd">tcldocstrip</b> <span class="opt">?options?</span> <i class="arg">output</i> (<span class="opt">?options?</span> <i class="arg">input</i> <i class="arg">guards</i>)...</a></li>
<li><a href="#3"><b class="cmd">tcldocstrip</b> <b class="option">-guards</b> <i class="arg">input</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The application described by this document, <b class="syscmd">tcldocstrip</b>, is a
relative of <b class="syscmd"><a href="../modules/docstrip/docstrip.html">docstrip</a></b>, a simple literate programming tool for
LaTeX.</p>
<p><b class="syscmd">tcldocstrip</b> is based upon the package <b class="package"><a href="../modules/docstrip/docstrip.html">docstrip</a></b>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">USE CASES</a></h3>
<p><b class="syscmd">tcldocstrip</b> was written with the following three use cases in
mind.</p>
<ol class="doctools_enumerated">
<li><p>Conversion of a single input file according to the listed guards into
the stripped output. This handles the most simple case of a set of
guards specifying a single document found in a single input file.</p></li>
<li><p>Stitching, or the assembly of an output from several sets of guards,
in a specific order, and possibly from different files. This is the
second common case. One document spread over several inputs, and/or
spread over different guard sets.</p></li>
<li><p>Extraction and listing of all the unique guard expressions and guards
used within a document to help a person which did not author the
document in question in familiarizing itself with it.</p></li>
</ol>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">tcldocstrip</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">input</i> <span class="opt">?<i class="arg">guards</i>?</span></a></dt>
<dd><p>This is the form for use case [1]. It converts the <i class="arg">input</i>
file according to the specified <i class="arg">guards</i> and options. The result
is written to the named <i class="arg">output</i> file.
Usage of the string <b class="const">-</b> as the name of the output signals that
the result should be written to <b class="const">stdout</b>. The guards are
document-specific and have to be known to the caller. The
<i class="arg">options</i> will be explained later, in section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p>
<dl class="doctools_arguments">
<dt>path <i class="arg">output</i> (in)</dt>
<dd><p>This argument specifies where to write the generated document. It can
be the path to a file or directory, or <b class="const">-</b>.
The last value causes the application to write the generated
documented to <b class="const">stdout</b>.</p>
<p>If the <i class="arg">output</i> does not exist then [file dirname $output]
has to exist and must be a writable directory.</p></dd>
<dt>path <i class="arg">inputfile</i> (in)</dt>
<dd><p>This argument specifies the path to the file to process. It has to
exist, must be readable, and written in <i class="term"><a href="../../../index.html#docstrip">docstrip</a></i> format.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">tcldocstrip</b> <span class="opt">?options?</span> <i class="arg">output</i> (<span class="opt">?options?</span> <i class="arg">input</i> <i class="arg">guards</i>)...</a></dt>
<dd><p>This is the form for use case [2]. It differs from the form for
use case [1] by the possibility of having options before the
output file, which apply in general, and specifying more than one
inputfile, each with its own set of input specific options and guards.</p>
<p>It extracts data from the various <i class="arg">input</i> files, according to the
specified <i class="arg">options</i> and <i class="arg">guards</i>, and writes the result to the
given <i class="arg">output</i>, in the order of their specification on the command
line. Options specified before the output are global settings, whereas
the options specified before each input are valid only just for this
input file. Unspecified values are taken from the global settings, or
defaults. As for form [1] using the string <b class="const">-</b> as output
causes the application to write to stdout.
Using the string <b class="const">.</b> for an input file signals that the last
input file should be used again. This enables the assembly of the
output from one input file using multiple and different sets of
guards, without having to specify the full name of the file every
time.</p></dd>
<dt><a name="3"><b class="cmd">tcldocstrip</b> <b class="option">-guards</b> <i class="arg">input</i></a></dt>
<dd><p>This is the form for use case [3].
It determines the guards, and unique guard expressions used within the
provided <i class="arg">input</i> document. The found strings are written to
stdout, one string per line.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application, with the exception of the option <b class="option">-guards</b>. This
option was described already, in section <span class="sectref"><a href="#subsection2">COMMAND LINE</a></span>.</p>
<dl class="doctools_options">
<dt><b class="option">-metaprefix</b> string</dt>
<dd><p>This option is inherited from the command <b class="cmd">docstrip::extract</b>
provided by the package <b class="package"><a href="../modules/docstrip/docstrip.html">docstrip</a></b>.</p>
<p>It specifies the string by which the '%%' prefix of a metacomment line
will be replaced. Defaults to '%%'. For Tcl code this would typically
be '#'.</p></dd>
<dt><b class="option">-onerror</b> mode</dt>
<dd><p>This option is inherited from the command <b class="cmd">docstrip::extract</b>
provided by the package <b class="package"><a href="../modules/docstrip/docstrip.html">docstrip</a></b>.</p>
<p>It controls what will be done when a format error in the <i class="arg">text</i>
being processed is detected. The settings are:</p>
<dl class="doctools_definitions">
<dt><b class="const">ignore</b></dt>
<dd><p>Just ignore the error; continue as if nothing happened.</p></dd>
<dt><b class="const">puts</b></dt>
<dd><p>Write an error message to <b class="const">stderr</b>, then continue processing.</p></dd>
<dt><b class="const">throw</b></dt>
<dd><p>Throw an error. <b class="variable">::errorCode</b> is set to a list whose first element
is <b class="const">DOCSTRIP</b>, second element is the type of error, and third
element is the line number where the error is detected. This is the
default.</p></dd>
</dl></dd>
<dt><b class="option">-trimlines</b> bool</dt>
<dd><p>This option is inherited from the command <b class="cmd">docstrip::extract</b>
provided by the package <b class="package"><a href="../modules/docstrip/docstrip.html">docstrip</a></b>.</p>
<p>Controls whether <em>spaces</em> at the end of a line should be trimmed
away before the line is processed. Defaults to <b class="const">true</b>.</p></dd>
<dt><b class="option">-preamble</b> text</dt>
<dd></dd>
<dt><b class="option">-postamble</b> text</dt>
<dd></dd>
<dt><b class="option">-nopreamble</b></dt>
<dd></dd>
<dt><b class="option">-nopostamble</b></dt>
<dd><p>The -no*amble options deactivate file pre- and postambles altogether,
whereas the -*amble options specify the <em>user</em> part of the file
pre- and postambles. This part can be empty, in that case only the
standard parts are shown. This is the default.</p>
<p>Preambles, when active, are written before the actual content of a
generated file. In the same manner postambles are, when active,
written after the actual content of a generated file.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>docstrip</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../modules/docstrip/docstrip.html">docstrip</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../index.html#_dtx">.dtx</a>, <a href="../../../index.html#latex">LaTeX</a>, <a href="../../../index.html#conversion">conversion</a>, <a href="../../../index.html#docstrip">docstrip</a>, <a href="../../../index.html#documentation">documentation</a>, <a href="../../../index.html#literate_programming">literate programming</a>, <a href="../../../index.html#markup">markup</a>, <a href="../../../index.html#source">source</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/aes/aes.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
<div class='fossil-doc' data-title='aes - Advanced Encryption Standard (AES)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">aes(n) 1.2.1 tcllib "Advanced Encryption Standard (AES)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>aes - Implementation of the AES block cipher</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">MODES OF OPERATION</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">REFERENCES</a></li>
<li class="doctools_section"><a href="#section7">AUTHORS</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">aes <span class="opt">?1.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::aes::aes</b> <span class="opt">?<i class="arg">-mode [ecb|cbc]</i>?</span> <span class="opt">?<i class="arg">-dir [encrypt|decrypt]</i>?</span> <i class="arg">-key keydata</i> <span class="opt">?<i class="arg">-iv vector</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-in channel</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">data</i> ]</a></li>
<li><a href="#2"><b class="cmd">::aes::Init</b> <i class="arg">mode</i> <i class="arg">keydata</i> <i class="arg">iv</i></a></li>
<li><a href="#3"><b class="cmd">::aes::Encrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::aes::Decrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::aes::Reset</b> <i class="arg">Key</i> <i class="arg">iv</i></a></li>
<li><a href="#6"><b class="cmd">::aes::Final</b> <i class="arg">Key</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This is an implementation in Tcl of the Advanced Encryption Standard
(AES) as published by the U.S. National Institute of Standards and
Technology [1]. AES is a 128-bit block cipher with a variable
key size of 128, 192 or 256 bits. This implementation supports ECB and
CBC modes.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::aes::aes</b> <span class="opt">?<i class="arg">-mode [ecb|cbc]</i>?</span> <span class="opt">?<i class="arg">-dir [encrypt|decrypt]</i>?</span> <i class="arg">-key keydata</i> <span class="opt">?<i class="arg">-iv vector</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-in channel</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">data</i> ]</a></dt>
<dd><p>Perform the <b class="package">aes</b> algorithm on either the data provided
by the argument or on the data read from the <i class="arg">-in</i> channel. If
an <i class="arg">-out</i> channel is given then the result will be written to
this channel.</p>
<p>The <i class="arg">-key</i> option must be given. This parameter takes a binary
string of either 16, 24 or 32 bytes in length and is used to generate the
key schedule.</p>
<p>The <i class="arg">-mode</i> and <i class="arg">-dir</i> options are optional and default to cbc
mode and encrypt respectively. The initialization vector <i class="arg">-iv</i>
takes a 16 byte binary argument which defaults to all zeros.
See <span class="sectref"><a href="#section4">MODES OF OPERATION</a></span> for more about available modes and
their uses.</p>
<p>AES is a 128-bit block cipher. This means that the data must be
provided in units that are a multiple of 16 bytes.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>Internal state is maintained in an opaque structure that is returned
from the <b class="cmd">Init</b> function. In ECB mode the state is not affected by
the input but for CBC mode some input dependent state is maintained
and may be reset by calling the <b class="cmd">Reset</b> function with a new
initialization vector value.</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::aes::Init</b> <i class="arg">mode</i> <i class="arg">keydata</i> <i class="arg">iv</i></a></dt>
<dd><p>Construct a new AES key schedule using the specified key data and the
given initialization vector. The initialization vector is not used
with ECB mode but is important for CBC mode.
See <span class="sectref"><a href="#section4">MODES OF OPERATION</a></span> for details about cipher modes.</p></dd>
<dt><a name="3"><b class="cmd">::aes::Encrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Use a prepared key acquired by calling <b class="cmd">Init</b> to encrypt the
provided data. The data argument should be a binary array that is a
multiple of the AES block size of 16 bytes. The result is a binary
array the same size as the input of encrypted data.</p></dd>
<dt><a name="4"><b class="cmd">::aes::Decrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Decipher data using the key. Note that the same key may be used to
encrypt and decrypt data provided that the initialization vector is
reset appropriately for CBC mode.</p></dd>
<dt><a name="5"><b class="cmd">::aes::Reset</b> <i class="arg">Key</i> <i class="arg">iv</i></a></dt>
<dd><p>Reset the initialization vector. This permits the programmer to re-use
a key and avoid the cost of re-generating the key schedule where the
same key data is being used multiple times.</p></dd>
<dt><a name="6"><b class="cmd">::aes::Final</b> <i class="arg">Key</i></a></dt>
<dd><p>This should be called to clean up resources associated with <i class="arg">Key</i>.
Once this function has been called the key may not be used again.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">MODES OF OPERATION</a></h2>
<dl class="doctools_definitions">
<dt>Electronic Code Book (ECB)</dt>
<dd><p>ECB is the basic mode of all block ciphers. Each block is encrypted
independently and so identical plain text will produce identical
output when encrypted with the same key. Any encryption errors will
only affect a single block however this is vulnerable to known
plaintext attacks.</p></dd>
<dt>Cipher Block Chaining (CBC)</dt>
<dd><p>CBC mode uses the output of the last block encryption to affect the
current block. An initialization vector of the same size as the cipher
block size is used to handle the first block. The initialization
vector should be chosen randomly and transmitted as the first block of
the output. Errors in encryption affect the current block and the next
block after which the cipher will correct itself. CBC is the most
commonly used mode in software encryption. This is the default mode
of operation for this module.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<pre class="doctools_example">
% set nil_block [string repeat \\0 16]
% aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block
66e94bd4ef8a2c3b884cfa59ca342b2e
</pre>
<pre class="doctools_example">
set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv]
append ciphertext [aes::Encrypt $Key $plaintext]
append ciphertext [aes::Encrypt $Key $additional_plaintext]
aes::Final $Key
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>"Advanced Encryption Standard",
Federal Information Processing Standards Publication 197, 2001
(<a href="http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf">http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf</a>)</p></li>
</ol>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">AUTHORS</a></h2>
<p>Thorsten Schloermann, Pat Thoyts</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>aes</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../blowfish/blowfish.html">blowfish(n)</a>, <a href="../des/des.html">des(n)</a>, <a href="../md5/md5.html">md5(n)</a>, <a href="../sha1/sha1.html">sha1(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#aes">aes</a>, <a href="../../../../index.html#block_cipher">block cipher</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005, Pat Thoyts <[email protected]><br>
Copyright © 2012-2014, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/amazon-s3/S3.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
|
<div class='fossil-doc' data-title='S3 - Amazon S3 Web Service Utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">S3(n) 1.0.3 tcllib "Amazon S3 Web Service Utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>S3 - Amazon S3 Web Service Interface</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">ERROR REPORTING</a></li>
<li class="doctools_section"><a href="#section3">COMMANDS</a></li>
<li class="doctools_section"><a href="#section4">LOW LEVEL COMMANDS</a></li>
<li class="doctools_section"><a href="#section5">HIGH LEVEL COMMANDS</a></li>
<li class="doctools_section"><a href="#section6">LIMITATIONS</a></li>
<li class="doctools_section"><a href="#section7">USAGE SUGGESTIONS</a></li>
<li class="doctools_section"><a href="#section8">FUTURE DEVELOPMENTS</a></li>
<li class="doctools_section"><a href="#section9">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section10">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">S3 <span class="opt">?1.0.3?</span></b></li>
<li>package require <b class="pkgname">sha1 1.0</b></li>
<li>package require <b class="pkgname">md5 2.0</b></li>
<li>package require <b class="pkgname">base64 2.3</b></li>
<li>package require <b class="pkgname">xsxp 1.0</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">S3::Configure</b> <span class="opt">?<b class="option">-reset</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-retries</b> <i class="arg">integer</i>?</span> <span class="opt">?<b class="option">-accesskeyid</b> <i class="arg">idstring</i>?</span> <span class="opt">?<b class="option">-secretaccesskey</b> <i class="arg">idstring</i>?</span> <span class="opt">?<b class="option">-service-access-point</b> <i class="arg">FQDN</i>?</span> <span class="opt">?<b class="option">-use-tls</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-default-compare</b> <i class="arg">always|never|exists|missing|newer|date|checksum|different</i>?</span> <span class="opt">?<b class="option">-default-separator</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-default-acl</b> <i class="arg">private|public-read|public-read-write|authenticated-read|keep|calc</i>?</span> <span class="opt">?<b class="option">-default-bucket</b> <i class="arg">bucketname</i>?</span></a></li>
<li><a href="#2"><b class="cmd">S3::SuggestBucket</b> <span class="opt">?<i class="arg">name</i>?</span></a></li>
<li><a href="#3"><b class="cmd">S3::REST</b> <i class="arg">dict</i></a></li>
<li><a href="#4"><b class="cmd">S3::ListAllMyBuckets</b> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-parse-xml</b> <i class="arg">xmlstring</i>?</span> <span class="opt">?<b class="option">-result-type</b> <i class="arg">REST|xml|pxml|dict|names|owner</i>?</span></a></li>
<li><a href="#5"><b class="cmd">S3::PutBucket</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-acl</b> <i class="arg">{}|private|public-read|public-read-write|authenticated-read</i>?</span></a></li>
<li><a href="#6"><b class="cmd">S3::DeleteBucket</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span></a></li>
<li><a href="#7"><b class="cmd">S3::GetBucket</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-parse-xml</b> <i class="arg">xmlstring</i>?</span> <span class="opt">?<b class="option">-max-count</b> <i class="arg">integer</i>?</span> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefixstring</i>?</span> <span class="opt">?<b class="option">-delimiter</b> <i class="arg">delimiterstring</i>?</span> <span class="opt">?<b class="option">-result-type</b> <i class="arg">REST|xml|pxml|names|dict</i>?</span></a></li>
<li><a href="#8"><b class="cmd">S3::Put</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-file</b> <i class="arg">filename</i>?</span> <span class="opt">?<b class="option">-content</b> <i class="arg">contentstring</i>?</span> <span class="opt">?<b class="option">-acl</b> <i class="arg">private|public-read|public-read-write|authenticated-read|calc|keep</i>?</span> <span class="opt">?<b class="option">-content-type</b> <i class="arg">contenttypestring</i>?</span> <span class="opt">?<b class="option">-x-amz-meta-*</b> <i class="arg">metadatatext</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span></a></li>
<li><a href="#9"><b class="cmd">S3::Get</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span> <span class="opt">?<b class="option">-file</b> <i class="arg">filename</i>?</span> <span class="opt">?<b class="option">-content</b> <i class="arg">contentvarname</i>?</span> <span class="opt">?<b class="option">-timestamp</b> <i class="arg">aws|now</i>?</span> <span class="opt">?<b class="option">-headers</b> <i class="arg">headervarname</i>?</span></a></li>
<li><a href="#10"><b class="cmd">S3::Head</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-dict</b> <i class="arg">dictvarname</i>?</span> <span class="opt">?<b class="option">-headers</b> <i class="arg">headersvarname</i>?</span> <span class="opt">?<b class="option">-status</b> <i class="arg">statusvarname</i>?</span></a></li>
<li><a href="#11"><b class="cmd">S3::GetAcl</b> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-result-type</b> <i class="arg">REST|xml|pxml</i>?</span></a></li>
<li><a href="#12"><b class="cmd">S3::PutAcl</b> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-acl</b> <i class="arg">new-acl</i>?</span></a></li>
<li><a href="#13"><b class="cmd">S3::Delete</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-status</b> <i class="arg">statusvar</i>?</span></a></li>
<li><a href="#14"><b class="cmd">S3::Push</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-directory</b> <i class="arg">directoryname</i> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefixstring</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span> <span class="opt">?<b class="option">-x-amz-meta-*</b> <i class="arg">metastring</i>?</span> <span class="opt">?<b class="option">-acl</b> <i class="arg">aclcode</i>?</span> <span class="opt">?<b class="option">-delete</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">throw|break|continue</i>?</span> <span class="opt">?<b class="option">-progress</b> <i class="arg">scriptprefix</i>?</span></a></li>
<li><a href="#15"><b class="cmd">S3::Pull</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-directory</b> <i class="arg">directoryname</i> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefixstring</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span> <span class="opt">?<b class="option">-delete</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-timestamp</b> <i class="arg">aws|now</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">throw|break|continue</i>?</span> <span class="opt">?<b class="option">-progress</b> <i class="arg">scriptprefix</i>?</span></a></li>
<li><a href="#16"><b class="cmd">S3::Toss</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-prefix</b> <i class="arg">prefixstring</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">throw|break|continue</i>?</span> <span class="opt">?<b class="option">-progress</b> <i class="arg">scriptprefix</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides access to Amazon's Simple Storage Solution web service.</p>
<p>As a quick summary, Amazon Simple Storage Solution
provides a for-fee web service allowing the storage of arbitrary data as
"resources" within "buckets" online.
See <a href="http://www.amazonaws.com/">http://www.amazonaws.com/</a> for details on that system.
Access to the service is via HTTP (SOAP or REST). Much of this
documentation will not make sense if you're not familiar with
the terms and functionality of the Amazon S3 service.</p>
<p>This package provides services for reading and writing
the data items via the REST interface. It also provides some
higher-level operations. Other packages in the same distribution
provide for even more functionality.</p>
<p>Copyright 2006 Darren New. All Rights Reserved.
NO WARRANTIES OF ANY TYPE ARE PROVIDED.
COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS.
This software is licensed under essentially the same
terms as Tcl. See LICENSE.txt for the terms.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">ERROR REPORTING</a></h2>
<p>The error reporting from this package makes use of $errorCode to
provide more details on what happened than simply throwing an error.
Any error caught by the S3 package (and we try to catch them all)
will return with an $errorCode being a list having at least three
elements. In all cases, the first element will be "S3". The second
element will take on one of six values, with that element defining
the value of the third and subsequent elements. S3::REST does not
throw an error, but rather returns a dictionary with the keys "error",
"errorInfo", and "errorCode" set. This allows for reliable background
use. The possible second elements are these:</p>
<dl class="doctools_definitions">
<dt>usage</dt>
<dd><p>The usage of the package is incorrect. For example,
a command has been invoked which requires the library to be configured
before the library has been configured, or an invalid combination of
options has been specified. The third element of $errorCode supplies
the name of the parameter that was wrong. The fourth usually provides
the arguments that were actually supplied to the throwing proc, unless
the usage error isn't confined to a single proc.</p></dd>
<dt>local</dt>
<dd><p>Something happened on the local system which threw
an error. For example, a request to upload or download a file was made
and the file permissions denied that sort of access. The third element
of $errorCode is the original $errorCode.</p></dd>
<dt>socket</dt>
<dd><p>Something happened with the socket. It closed
prematurely, or some other condition of failure-to-communicate-with-Amazon
was detected. The third element of $errorCode is the original $errorCode,
or sometimes the message from fcopy, or ...?</p></dd>
<dt>remote</dt>
<dd><p>The Amazon web service returned an error code outside
the 2xx range in the HTTP header. In other words, everything went as
documented, except this particular case was documented not to work.
The third element is the dictionary returned from <b class="cmd">::S3::REST</b>.
Note that S3::REST itself never throws this error, but just returns
the dictionary. Most of the higher-level commands throw for convenience,
unless an argument indicates they should not. If something is documented
as "not throwing an S3 remote error", it means a status return is set
rather than throwing an error if Amazon returns a non-2XX HTTP result code.</p></dd>
<dt>notyet</dt>
<dd><p>The user obeyed the documentation, but the author
has not yet gotten around to implementing this feature. (Right now,
only TLS support and sophisticated permissions fall into this category,
as well as the S3::Acl command.)</p></dd>
<dt>xml</dt>
<dd><p>The service has returned invalid XML, or XML whose
schema is unexpected. For the high-level commands that accept
service XML as input for parsing, this may also be thrown.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">COMMANDS</a></h2>
<p>This package provides several separate levels of complexity.</p>
<ul class="doctools_itemized">
<li><p>The lowest level simply takes arguments to be sent to the service,
sends them, retrieves the result, and provides it to the caller.
<em>Note:</em> This layer allows both synchronous and event-driven
processing. It depends on the MD5 and SHA1 and base64 packages
from Tcllib (available at <a href="http://core.tcl.tk/tcllib/">http://core.tcl.tk/tcllib/</a>).
Note that <b class="cmd">S3::Configure</b> is required for <b class="cmd">S3::REST</b> to
work due to the authentication portion, so we put that in the "lowest level."</p></li>
<li><p>The next layer parses the results of calls, allowing for functionality
such as uploading only changed files, synchronizing directories,
and so on. This layer depends on the <b class="package">TclXML</b> package as well as the
included <b class="package"><a href="xsxp.html">xsxp</a></b> package. These packages are package required when
these more-sophisticated routines are called, so nothing breaks if
they are not correctly installed.</p></li>
<li><p>Also included is a separate program that uses the library.
It provides code to parse $argv0 and $argv from the
command line, allowing invocation as a tclkit, etc.
(Not yet implmented.)</p></li>
<li><p>Another separate program provides a GUI interface allowing drag-and-drop
and other such functionality. (Not yet implemented.)</p></li>
<li><p>Also built on this package is the OddJob program. It is
a separate program designed to allow distribution of
computational work units over Amazon's Elastic Compute
Cloud web service.</p></li>
</ul>
<p>The goal is to have at least the bottom-most layers implemented in
pure Tcl using only that which comes from widely-available sources,
such as Tcllib.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">LOW LEVEL COMMANDS</a></h2>
<p>These commands do not require any packages not listed above.
They talk directly to the service, or they are utility or
configuration routines. Note that the "xsxp" package was
written to support this package, so it should be available
wherever you got this package.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">S3::Configure</b> <span class="opt">?<b class="option">-reset</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-retries</b> <i class="arg">integer</i>?</span> <span class="opt">?<b class="option">-accesskeyid</b> <i class="arg">idstring</i>?</span> <span class="opt">?<b class="option">-secretaccesskey</b> <i class="arg">idstring</i>?</span> <span class="opt">?<b class="option">-service-access-point</b> <i class="arg">FQDN</i>?</span> <span class="opt">?<b class="option">-use-tls</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-default-compare</b> <i class="arg">always|never|exists|missing|newer|date|checksum|different</i>?</span> <span class="opt">?<b class="option">-default-separator</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-default-acl</b> <i class="arg">private|public-read|public-read-write|authenticated-read|keep|calc</i>?</span> <span class="opt">?<b class="option">-default-bucket</b> <i class="arg">bucketname</i>?</span></a></dt>
<dd><p>There is one command for configuration, and that is <b class="cmd">S3::Configure</b>.
If called with no arguments, it returns a
dictionary of key/value pairs listing all current settings. If called
with one argument, it returns the value of that single argument. If
called with two or more arguments, it must be called with pairs of
arguments, and it applies the changes in order. There is only one set
of configuration information per interpreter.</p>
<p>The following options are accepted:</p>
<dl class="doctools_definitions">
<dt><b class="option">-reset</b> <i class="arg">boolean</i></dt>
<dd><p>By default, false. If true, any previous changes and any changes on the
same call before the reset option will be returned to default values.</p></dd>
<dt><b class="option">-retries</b> <i class="arg">integer</i></dt>
<dd><p>Default value is 3.
If Amazon returns a 500 error, a retry after an exponential
backoff delay will be tried this many times before finally
throwing the 500 error. This applies to each call to <b class="cmd">S3::REST</b>
from the higher-level commands, but not to <b class="cmd">S3::REST</b> itself.
That is, <b class="cmd">S3::REST</b> will always return httpstatus 500 if that's
what it receives. Functions like <b class="cmd">S3::Put</b> will retry the PUT call,
and will also retry the GET and HEAD calls used to do content comparison.
Changing this to 0 will prevent retries and their associated delays.
In addition, socket errors (i.e., errors whose errorCode starts with
"S3 socket") will be similarly retried after backoffs.</p></dd>
<dt><b class="option">-accesskeyid</b> <i class="arg">idstring</i></dt>
<dd></dd>
<dt><b class="option">-secretaccesskey</b> <i class="arg">idstring</i></dt>
<dd><p>Each defaults to an empty string.
These must be set before any calls are made. This is your S3 ID.
Once you sign up for an account, go to <a href="http://www.amazonaws.com/">http://www.amazonaws.com/</a>,
sign in, go to the "Your Web Services Account" button, pick "AWS
Access Identifiers", and your access key ID and secret access keys
will be available. All <b class="cmd">S3::REST</b> calls are authenticated.
Blame Amazon for the poor choice of names.</p></dd>
<dt><b class="option">-service-access-point</b> <i class="arg">FQDN</i></dt>
<dd><p>Defaults to "s3.amazonaws.com". This is the fully-qualified domain
name of the server to contact for <b class="cmd">S3::REST</b> calls. You should
probably never need to touch this, unless someone else implements
a compatible service, or you wish to test something by pointing
the library at your own service.</p></dd>
<dt><b class="option">-slop-seconds</b> <i class="arg">integer</i></dt>
<dd><p>When comparing dates between Amazon and the local machine,
two dates within this many seconds of each other are considered
the same. Useful for clock drift correction, processing overhead
time, and so on.</p></dd>
<dt><b class="option">-use-tls</b> <i class="arg">boolean</i></dt>
<dd><p>Defaults to false. This is not yet implemented. If true, <b class="cmd">S3::REST</b> will
negotiate a TLS connection to Amazon. If false, unencrypted connections
are used.</p></dd>
<dt><b class="option">-bucket-prefix</b> <i class="arg">string</i></dt>
<dd><p>Defaults to "TclS3". This string is used by <b class="cmd">S3::SuggestBucketName</b>
if that command is passed an empty string as an argument. It is used
to distinguish different applications using the Amazon service.
Your application should always set this to keep from interfering with
the buckets of other users of Amazon S3 or with other buckets of the
same user.</p></dd>
<dt><b class="option">-default-compare</b> <i class="arg">always|never|exists|missing|newer|date|checksum|different</i></dt>
<dd><p>Defaults to "always." If no -compare is specified on
<b class="cmd">S3::Put</b>, <b class="cmd">S3::Get</b>, or <b class="cmd">S3::Delete</b>, this comparison is used.
See those commands for a description of the meaning.</p></dd>
<dt><b class="option">-default-separator</b> <i class="arg">string</i></dt>
<dd><p>Defaults to "/". This is currently unused. It might make sense to use
this for <b class="cmd">S3::Push</b> and <b class="cmd">S3::Pull</b>, but allowing resources to
have slashes in their names that aren't marking directories would be
problematic. Hence, this currently does nothing.</p></dd>
<dt><b class="option">-default-acl</b> <i class="arg">private|public-read|public-read-write|authenticated-read|keep|calc</i></dt>
<dd><p>Defaults to an empty string. If no -acl argument is provided to <b class="cmd">S3::Put</b> or
<b class="cmd">S3::Push</b>, this string is used
(given as the x-amz-acl header if not keep or calc). If this is also
empty, no x-amz-acl header is generated.
This is <em>not</em> used by <b class="cmd">S3::REST</b>.</p></dd>
<dt><b class="option">-default-bucket</b> <i class="arg">bucketname</i></dt>
<dd><p>If no bucket is given to <b class="cmd">S3::GetBucket</b>, <b class="cmd">S3::PutBucket</b>,
<b class="cmd">S3::Get</b>, <b class="cmd">S3::Put</b>,
<b class="cmd">S3::Head</b>, <b class="cmd">S3::Acl</b>,
<b class="cmd">S3::Delete</b>, <b class="cmd">S3::Push</b>,
<b class="cmd">S3::Pull</b>, or <b class="cmd">S3::Toss</b>, and if this configuration variable
is not an empty string (and not simply "/"), then this value
will be used for the bucket. This is useful if one program does
a large amount of resource manipulation within a single bucket.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">S3::SuggestBucket</b> <span class="opt">?<i class="arg">name</i>?</span></a></dt>
<dd><p>The <b class="cmd">S3::SuggestBucket</b> command accepts an optional string as
a prefix and returns a valid bucket containing the <i class="arg">name</i> argument
and the Access Key ID. This makes the name unique to the owner and
to the application (assuming the application picks a good <i class="arg">name</i> argument).
If no name is provided,
the name from <b class="cmd">S3::Configure</b> <i class="arg">-bucket-prefix</i> is used.
If that too is empty (which is not the default), an error is thrown.</p></dd>
<dt><a name="3"><b class="cmd">S3::REST</b> <i class="arg">dict</i></a></dt>
<dd><p>The <b class="cmd">S3::REST</b> command takes as an argument a dictionary and
returns a dictionary. The return dictionary has the same keys
as the input dictionary, and includes additional keys as the result.
The presence or absence of keys in the input dictionary can control
the behavior of the routine. It never throws an error directly, but
includes keys "error", "errorInfo", and "errorCode" if necessary.
Some keys are required, some optional. The routine can run either
in blocking or non-blocking mode, based on the presense
of <b class="option">resultvar</b> in the input dictionary. This requires
the <i class="arg">-accesskeyid</i> and <i class="arg">-secretaccesskey</i> to be configured via
<b class="cmd">S3::Configure</b> before being called.</p>
<p>The possible input keys are these:</p>
<dl class="doctools_definitions">
<dt><b class="option">verb</b> <i class="arg">GET|PUT|DELETE|HEAD</i></dt>
<dd><p>This required item indicates the verb to be used.</p></dd>
<dt><b class="option">resource</b> <i class="arg">string</i></dt>
<dd><p>This required item indicates the resource to be accessed.
A leading / is added if not there already. It will
be URL-encoded for you if necessary. Do not supply a
resource name that is already URL-encoded.</p></dd>
<dt><span class="opt">?<b class="option">rtype</b> <i class="arg">torrent|acl</i>?</span></dt>
<dd><p>This indicates a torrent or acl resource is being manipulated.
Do not include this in the <b class="option">resource</b> key, or the
"?" separator will get URL-encoded.</p></dd>
<dt><span class="opt">?<b class="option">parameters</b> <i class="arg">dict</i>?</span></dt>
<dd><p>This optional dictionary provides parameters added to the URL
for the transaction. The keys must be in the correct case
(which is confusing in the Amazon documentation) and the
values must be valid. This can be an empty dictionary or
omitted entirely if no parameters are desired. No other
error checking on parameters is performed.</p></dd>
<dt><span class="opt">?<b class="option">headers</b> <i class="arg">dict</i>?</span></dt>
<dd><p>This optional dictionary provides headers to be added
to the HTTP request. The keys must be in <em>lower case</em>
for the authentication to work. The values must not contain
embedded newlines or carriage returns. This is primarily
useful for adding x-amz-* headers. Since authentication
is calculated by <b class="cmd">S3::REST</b>, do not add that header here.
Since content-type gets its own key, also do not add
that header here.</p></dd>
<dt><span class="opt">?<b class="option">inbody</b> <i class="arg">contentstring</i>?</span></dt>
<dd><p>This optional item, if provided, gives the content that will
be sent. It is sent with a tranfer encoding of binary, and
only the low bytes are used, so use [encoding convertto utf-8]
if the string is a utf-8 string. This is written all in one blast,
so if you are using non-blocking mode and the <b class="option">inbody</b> is
especially large, you may wind up blocking on the write socket.</p></dd>
<dt><span class="opt">?<b class="option">infile</b> <i class="arg">filename</i>?</span></dt>
<dd><p>This optional item, if provided, and if <b class="option">inbody</b> is not provided,
names the file from which the body of the HTTP message will be
constructed. The file is opened for reading and sent progressively
by [fcopy], so it should not block in non-blocking mode
even if the file is very large. The file is transfered in
binary mode, so the bytes on your disk will match the bytes
in your resource. Due to HTTP restrictions, it must be possible to
use [file size] on this file to determine the size at the
start of the transaction.</p></dd>
<dt><span class="opt">?<b class="option">S3chan</b> <i class="arg">channel</i>?</span></dt>
<dd><p>This optional item, if provided, indicates the already-open socket
over which the transaction should be conducted. If not provided,
a connection is made to the service access point specified via
<b class="cmd">S3::Configure</b>, which is normally s3.amazonaws.com. If this
is provided, the channel is not closed at the end of the transaction.</p></dd>
<dt><span class="opt">?<b class="option">outchan</b> <i class="arg">channel</i>?</span></dt>
<dd><p>This optional item, if provided, indicates the already-open channel
to which the body returned from S3 should be written. That is,
to retrieve a large resource, open a file, set the translation mode,
and pass the channel as the value of the key outchan. Output
will be written to the channel in pieces so memory does not fill
up unnecessarily. The channel is not closed at the end of the transaction.</p></dd>
<dt><span class="opt">?<b class="option">resultvar</b> <i class="arg">varname</i>?</span></dt>
<dd><p>This optional item, if provided, indicates that <b class="cmd">S3::REST</b> should
run in non-blocking mode. The <i class="arg">varname</i> should be fully qualified
with respect to namespaces and cannot be local to a proc. If provided,
the result of the <b class="cmd">S3::REST</b> call is assigned to this variable once
everything has completed; use trace or vwait to know when this has happened.
If this key is not provided, the result is simply returned from the
call to <b class="cmd">S3::REST</b> and no calls to the eventloop are invoked from
within this call.</p></dd>
<dt><span class="opt">?<b class="option">throwsocket</b> <i class="arg">throw|return</i>?</span></dt>
<dd><p>This optional item, if provided, indicates that <b class="cmd">S3::REST</b> should
throw an error if throwmode is throw and a socket error is encountered.
It indicates that <b class="cmd">S3::REST</b> should return the error code in the
returned dictionary if a socket error is encountered and this is
set to return. If <b class="option">throwsocket</b> is set to <i class="arg">return</i> or
if the call is not blocking, then a socket error (i.e., an error
whose error code starts with "S3 socket" will be returned in the
dictionary as <b class="option">error</b>, <b class="option">errorInfo</b>, and <b class="option">errorCode</b>.
If a foreground call is made (i.e., <b class="option">resultvar</b> is not provided),
and this option is not provided or is set to <i class="arg">throw</i>, then
<b class="cmd"><a href="../../../../index.html#error">error</a></b> will be invoked instead.</p></dd>
</dl>
<p>Once the call to <b class="cmd">S3::REST</b> completes, a new dict is returned,
either in the <i class="arg">resultvar</i> or as the result of execution. This dict is
a copy of the original dict with the results added as new keys. The possible
new keys are these:</p>
<dl class="doctools_definitions">
<dt><b class="option">error</b> <i class="arg">errorstring</i></dt>
<dd></dd>
<dt><b class="option">errorInfo</b> <i class="arg">errorstring</i></dt>
<dd></dd>
<dt><b class="option">errorCode</b> <i class="arg">errorstring</i></dt>
<dd><p>If an error is caught, these three keys will be set in the result.
Note that <b class="cmd">S3::REST</b> does <em>not</em> consider a non-2XX HTTP
return code as an error. The <b class="option">errorCode</b> value will be
formatted according to the <span class="sectref"><a href="#section2">ERROR REPORTING</a></span> description.
If these are present, other keys described here might not be.</p></dd>
<dt><b class="option">httpstatus</b> <i class="arg">threedigits</i></dt>
<dd><p>The three-digit code from the HTTP transaction. 2XX for good,
5XX for server error, etc.</p></dd>
<dt><b class="option">httpmessage</b> <i class="arg">text</i></dt>
<dd><p>The textual result after the status code. "OK" or "Forbidden"
or etc.</p></dd>
<dt><b class="option">outbody</b> <i class="arg">contentstring</i></dt>
<dd><p>If <i class="arg">outchan</i> was not specified, this key will hold a
reference to the (unencoded) contents of the body returned.
If Amazon returned an error (a la the httpstatus not a 2XX value),
the error message will be in <b class="option">outbody</b> or written to
<b class="option">outchan</b> as appropriate.</p></dd>
<dt><b class="option">outheaders</b> <i class="arg">dict</i></dt>
<dd><p>This contains a dictionary of headers returned by Amazon.
The keys are always lower case. It's mainly useful for
finding the x-amz-meta-* headers, if any, although things
like last-modified and content-type are also useful.
The keys of this dictionary are always lower case.
Both keys and values are trimmed of extraneous whitespace.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">HIGH LEVEL COMMANDS</a></h2>
<p>The routines in this section all make use of one or more calls
to <b class="cmd">S3::REST</b> to do their work, then parse and manage the data
in a convenient way. All these commands throw errors
as described in <span class="sectref"><a href="#section2">ERROR REPORTING</a></span> unless otherwise noted.</p>
<p>In all these commands, all arguments are presented as name/value pairs,
in any order. All the argument names start with a hyphen.</p>
<p>There are a few options that are common to many
of the commands, and those common options are documented here.</p>
<dl class="doctools_definitions">
<dt><b class="option">-blocking</b> <i class="arg">boolean</i></dt>
<dd><p>If provided and specified as false,
then any calls to <b class="cmd">S3:REST</b> will be non-blocking,
and internally these routines will call [vwait] to get
the results. In other words, these routines will return the
same value, but they'll have event loops running while waiting
for Amazon.</p></dd>
<dt><b class="option">-parse-xml</b> <i class="arg">xmlstring</i></dt>
<dd><p>If provided, the routine skips actually communicating with
Amazon, and instead behaves as if the XML string provided
was returned as the body of the call. Since several of
these routines allow the return of data in various formats,
this argument can be used to parse existing XML to extract
the bits of information that are needed. It's also helpful
for testing.</p></dd>
<dt><b class="option">-bucket</b> <i class="arg">bucketname</i></dt>
<dd><p>Almost every high-level command needs to know what bucket
the resources are in. This option specifies that. (Only the
command to list available buckets does not require this parameter.)
This does not need to be URL-encoded, even if it contains
special or non-ASCII characters. May or may not contain leading
or trailing spaces - commands normalize the bucket. If this is
not supplied, the value is taken from <b class="cmd">S3::Configure -default-bucket</b>
if that string isn't empty. Note that spaces and slashes are
always trimmed from both ends and the rest must leave a valid bucket.</p></dd>
<dt><b class="option">-resource</b> <i class="arg">resourcename</i></dt>
<dd><p>This specifies the resource of interest within the bucket.
It may or may not start with a slash - both cases are handled.
This does not need to be URL-encoded, even if it contains
special or non-ASCII characters.</p></dd>
<dt><b class="option">-compare</b> <i class="arg">always|never|exists|missing|newer|date|checksum|different</i></dt>
<dd><p>When commands copy resources to files or files to resources, the caller may specify that the copy should be skipped if the contents are the same. This argument specifies the conditions under which the files should be copied. If it is not passed, the result of <b class="cmd">S3::Configure -default-compare</b> is used, which in turn defaults to "always." The meanings of the various values are these:</p>
<dl class="doctools_definitions">
<dt><i class="arg">always</i></dt>
<dd><p>Always copy the data. This is the default.</p></dd>
<dt><i class="arg">never</i></dt>
<dd><p>Never copy the data. This is essentially a no-op, except in <b class="cmd">S3::Push</b> and <b class="cmd">S3::Pull</b> where the -delete flag might make a difference.</p></dd>
<dt><i class="arg">exists</i></dt>
<dd><p>Copy the data only if the destination already exists.</p></dd>
<dt><i class="arg">missing</i></dt>
<dd><p>Copy the data only if the destination does not already exist.</p></dd>
<dt><i class="arg">newer</i></dt>
<dd><p>Copy the data if the destination is missing, or if the date on the source is
newer than the date on the destination by at
least <b class="cmd">S3::Configure -slop-seconds</b> seconds. If the source is
Amazon, the date is taken from the Last-Modified header. If the
source is local, it is taken as the mtime of the file. If the source data
is specified in a string rather than a file, it is taken as right now,
via [clock seconds].</p></dd>
<dt><i class="arg">date</i></dt>
<dd><p>Like <i class="arg">newer</i>, except copy if the date is newer <em>or</em> older.</p></dd>
<dt><i class="arg">checksum</i></dt>
<dd><p>Calculate the MD5 checksum on the local file or string, ask Amazon for the eTag
of the resource, and copy the data if they're different. Copy the data
also if the destination is missing. Note that this can be slow with
large local files unless the C version of the MD5 support is available.</p></dd>
<dt><i class="arg">different</i></dt>
<dd><p>Copy the data if the destination does not exist.
If the destination exists and an actual file name was specified
(rather than a content string),
and the date on the file differs from the date on the resource,
copy the data.
If the data is provided as a content string, the "date" is treated
as "right now", so it will likely always differ unless slop-seconds is large.
If the dates are the same, the MD5 checksums are compared, and the
data is copied if the checksums differ.</p></dd>
</dl>
<p>Note that "newer" and "date" don't care about the contents, and "checksum" doesn't care about the dates, but "different" checks both.</p></dd>
<dt><a name="4"><b class="cmd">S3::ListAllMyBuckets</b> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-parse-xml</b> <i class="arg">xmlstring</i>?</span> <span class="opt">?<b class="option">-result-type</b> <i class="arg">REST|xml|pxml|dict|names|owner</i>?</span></a></dt>
<dd><p>This routine performs a GET on the Amazon S3 service, which is
defined to return a list of buckets owned by the account identified
by the authorization header. (Blame Amazon for the dumb names.)</p>
<dl class="doctools_definitions">
<dt><b class="option">-blocking</b> <i class="arg">boolean</i></dt>
<dd><p>See above for standard definition.</p></dd>
<dt><b class="option">-parse-xml</b> <i class="arg">xmlstring</i></dt>
<dd><p>See above for standard definition.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">REST</i></dt>
<dd><p>The dictionary returned by <b class="cmd">S3::REST</b> is the return value of <b class="cmd">S3::ListAllMyBuckets</b>. In this case, a non-2XX httpstatus will not throw an error. You may not combine this with <i class="arg">-parse-xml</i>.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">xml</i></dt>
<dd><p>The raw XML of the body is returned as the result (with no encoding applied).</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">pxml</i></dt>
<dd><p>The XML of the body as parsed by <b class="cmd">xsxp::parse</b> is returned.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">dict</i></dt>
<dd><p>A dictionary of interesting portions of the XML is returned. The dictionary contains the following keys:</p>
<dl class="doctools_definitions">
<dt>Owner/ID</dt>
<dd><p>The Amazon AWS ID (in hex) of the owner of the bucket.</p></dd>
<dt>Owner/DisplayName</dt>
<dd><p>The Amazon AWS ID's Display Name.</p></dd>
<dt>Bucket/Name</dt>
<dd><p>A list of names, one for each bucket.</p></dd>
<dt>Bucket/CreationDate</dt>
<dd><p>A list of dates, one for each bucket,
in the same order as Bucket/Name, in ISO format (as returned by Amazon).</p></dd>
</dl></dd>
<dt><b class="option">-result-type</b> <i class="arg">names</i></dt>
<dd><p>A list of bucket names is returned with all other information stripped out.
This is the default result type for this command.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">owner</i></dt>
<dd><p>A list containing two elements is returned. The first element is
the owner's ID, and the second is the owner's display name.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">S3::PutBucket</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-acl</b> <i class="arg">{}|private|public-read|public-read-write|authenticated-read</i>?</span></a></dt>
<dd><p>This command creates a bucket if it does not already exist. Bucket names are
globally unique, so you may get a "Forbidden" error from Amazon even if you
cannot see the bucket in <b class="cmd">S3::ListAllMyBuckets</b>. See <b class="cmd">S3::SuggestBucket</b> for ways to minimize this risk. The x-amz-acl header comes from the <b class="option">-acl</b> option, or from <b class="cmd">S3::Configure -default-acl</b> if not specified.</p></dd>
<dt><a name="6"><b class="cmd">S3::DeleteBucket</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span></a></dt>
<dd><p>This command deletes a bucket if it is empty and you have such permission.
Note that Amazon's list of buckets is a global resource, requiring
far-flung synchronization. If you delete a bucket, it may be quite
a few minutes (or hours) before you can recreate it, yielding "Conflict"
errors until then.</p></dd>
<dt><a name="7"><b class="cmd">S3::GetBucket</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-parse-xml</b> <i class="arg">xmlstring</i>?</span> <span class="opt">?<b class="option">-max-count</b> <i class="arg">integer</i>?</span> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefixstring</i>?</span> <span class="opt">?<b class="option">-delimiter</b> <i class="arg">delimiterstring</i>?</span> <span class="opt">?<b class="option">-result-type</b> <i class="arg">REST|xml|pxml|names|dict</i>?</span></a></dt>
<dd><p>This lists the contents of a bucket. That is, it returns a directory
listing of resources within a bucket, rather than transfering any
user data.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b> <i class="arg">bucketname</i></dt>
<dd><p>The standard bucket argument.</p></dd>
<dt><b class="option">-blocking</b> <i class="arg">boolean</i></dt>
<dd><p>The standard blocking argument.</p></dd>
<dt><b class="option">-parse-xml</b> <i class="arg">xmlstring</i></dt>
<dd><p>The standard parse-xml argument.</p></dd>
<dt><b class="option">-max-count</b> <i class="arg">integer</i></dt>
<dd><p>If supplied, this is the most number of records to be returned.
If not supplied, the code will iterate until all records have been found.
Not compatible with -parse-xml. Note that if this is supplied, only
one call to <b class="cmd">S3::REST</b> will be made. Otherwise, enough calls
will be made to exhaust the listing, buffering results in memory,
so take care if you may have huge buckets.</p></dd>
<dt><b class="option">-prefix</b> <i class="arg">prefixstring</i></dt>
<dd><p>If present, restricts listing to resources with a particular prefix. One
leading / is stripped if present.</p></dd>
<dt><b class="option">-delimiter</b> <i class="arg">delimiterstring</i></dt>
<dd><p>If present, specifies a delimiter for the listing.
The presence of this will summarize multiple resources
into one entry, as if S3 supported directories. See the
Amazon documentation for details.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">REST|xml|pxml|names|dict</i></dt>
<dd><p>This indicates the format of the return result of the command.</p>
<dl class="doctools_definitions">
<dt>REST</dt>
<dd><p>If <i class="arg">-max-count</i> is specified, the dictionary returned
from <b class="cmd">S3::REST</b> is returned. If <i class="arg">-max-count</i> is
not specified, a list of all the dictionaries returned from
the one or more calls to <b class="cmd">S3::REST</b> is returned.</p></dd>
<dt>xml</dt>
<dd><p>If <i class="arg">-max-count</i> is specified, the body returned
from <b class="cmd">S3::REST</b> is returned. If <i class="arg">-max-count</i> is
not specified, a list of all the bodies returned from
the one or more calls to <b class="cmd">S3::REST</b> is returned.</p></dd>
<dt>pxml</dt>
<dd><p>If <i class="arg">-max-count</i> is specified, the body returned
from <b class="cmd">S3::REST</b> is passed throught <b class="cmd">xsxp::parse</b> and then returned.
If <i class="arg">-max-count</i> is
not specified, a list of all the bodies returned from
the one or more calls to <b class="cmd">S3::REST</b> are each passed through
<b class="cmd">xsxp::parse</b> and then returned.</p></dd>
<dt>names</dt>
<dd><p>Returns a list of all names found in either the Contents/Key fields or
the CommonPrefixes/Prefix fields. If no <i class="arg">-delimiter</i> is specified
and no <i class="arg">-max-count</i> is specified, this returns a list of all
resources with the specified <i class="arg">-prefix</i>.</p></dd>
<dt>dict</dt>
<dd><p>Returns a dictionary. (Returns only one dictionary even if <i class="arg">-max-count</i>
wasn't specified.) The keys of the dictionary are as follows:</p>
<dl class="doctools_definitions">
<dt>Name</dt>
<dd><p>The name of the bucket (from the final call to <b class="cmd">S3::REST</b>).</p></dd>
<dt>Prefix</dt>
<dd><p>From the final call to <b class="cmd">S3::REST</b>.</p></dd>
<dt>Marker</dt>
<dd><p>From the final call to <b class="cmd">S3::REST</b>.</p></dd>
<dt>MaxKeys</dt>
<dd><p>From the final call to <b class="cmd">S3::REST</b>.</p></dd>
<dt>IsTruncated</dt>
<dd><p>From the final call to <b class="cmd">S3::REST</b>, so
always false if <i class="arg">-max-count</i> is not specified.</p></dd>
<dt>NextMarker</dt>
<dd><p>Always provided if IsTruncated is true, and
calculated of Amazon does not provide it. May be empty if IsTruncated is false.</p></dd>
<dt>Key</dt>
<dd><p>A list of names of resources in the bucket matching the <i class="arg">-prefix</i> and <i class="arg">-delimiter</i> restrictions.</p></dd>
<dt>LastModified</dt>
<dd><p>A list of times of resources in the bucket, in the same
order as Key, in the format returned by Amazon. (I.e., it is not parsed into
a seconds-from-epoch.)</p></dd>
<dt>ETag</dt>
<dd><p>A list of entity tags (a.k.a. MD5 checksums) in the same order as Key.</p></dd>
<dt>Size</dt>
<dd><p>A list of sizes in bytes of the resources, in the same order as Key.</p></dd>
<dt>Owner/ID</dt>
<dd><p>A list of owners of the resources in the bucket, in the same order as Key.</p></dd>
<dt>Owner/DisplayName</dt>
<dd><p>A list of owners of the resources in the bucket, in the same order as Key. These are the display names.</p></dd>
<dt>CommonPrefixes/Prefix</dt>
<dd><p>A list of prefixes common to multiple entities. This is present only if <i class="arg">-delimiter</i> was supplied.</p></dd>
</dl></dd>
</dl></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">S3::Put</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-file</b> <i class="arg">filename</i>?</span> <span class="opt">?<b class="option">-content</b> <i class="arg">contentstring</i>?</span> <span class="opt">?<b class="option">-acl</b> <i class="arg">private|public-read|public-read-write|authenticated-read|calc|keep</i>?</span> <span class="opt">?<b class="option">-content-type</b> <i class="arg">contenttypestring</i>?</span> <span class="opt">?<b class="option">-x-amz-meta-*</b> <i class="arg">metadatatext</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span></a></dt>
<dd><p>This command sends data to a resource on Amazon's servers for storage,
using the HTTP PUT command. It returns 0 if the <b class="option">-compare</b> mode
prevented the transfer, 1 if the transfer worked, or throws an error
if the transfer was attempted but failed.
Server 5XX errors and S3 socket errors are retried
according to <b class="cmd">S3:Configure -retries</b> settings before throwing an error;
other errors throw immediately.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b></dt>
<dd><p>This specifies the bucket into which the resource will be written.
Leading and/or trailing slashes are removed for you, as are spaces.</p></dd>
<dt><b class="option">-resource</b></dt>
<dd><p>This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash.
Spaces are not trimmed.</p></dd>
<dt><b class="option">-blocking</b></dt>
<dd><p>The standard blocking flag.</p></dd>
<dt><b class="option">-file</b></dt>
<dd><p>If this is specified, the <i class="arg">filename</i> must exist, must be readable,
and must not be a special or directory file. [file size] must
apply to it and must not change for the lifetime of the call. The
default content-type is calculated based on the name and/or contents
of the file. Specifying this is an error if <b class="option">-content</b> is
also specified, but at least one of <b class="option">-file</b> or <b class="option">-content</b> must
be specified. (The file is allowed to not exist or not be readable if
<b class="option">-compare</b> <i class="arg">never</i> is specified.)</p></dd>
<dt><b class="option">-content</b></dt>
<dd><p>If this is specified, the <i class="arg">contentstring</i> is sent as the body
of the resource. The content-type defaults to "application/octet-string".
Only the low bytes are sent, so non-ASCII should use the appropriate encoding
(such as [encoding convertto utf-8]) before passing it
to this routine, if necessary. Specifying this is an error if <b class="option">-file</b>
is also specified, but at least one of <b class="option">-file</b> or <b class="option">-content</b> must
be specified.</p></dd>
<dt><b class="option">-acl</b></dt>
<dd><p>This defaults to <b class="cmd">S3::Configure -default-acl</b> if not specified.
It sets the x-amz-acl header on the PUT operation.
If the value provided is <i class="arg">calc</i>, the x-amz-acl header is
calculated based on the I/O permissions of the file to be uploaded;
it is an error to specify <i class="arg">calc</i> and <b class="option">-content</b>.
If the value provided is <i class="arg">keep</i>, the acl of the resource
is read before the PUT (or the default is used if the
resource does not exist), then set back to what it
was after the PUT (if it existed). An error will occur if
the resource is successfully written but the kept ACL cannot
be then applied. This should never happen.
<em>Note:</em> <i class="arg">calc</i> is not currently fully implemented.</p></dd>
<dt><b class="option">-x-amz-meta-*</b></dt>
<dd><p>If any header starts with "-x-amz-meta-", its contents are added to the
PUT command to be stored as metadata with the resource. Again, no
encoding is performed, and the metadata should not contain characters
like newlines, carriage returns, and so on. It is best to stick with
simple ASCII strings, or to fix the library in several places.</p></dd>
<dt><b class="option">-content-type</b></dt>
<dd><p>This overrides the content-type calculated by <b class="option">-file</b> or
sets the content-type for <b class="option">-content</b>.</p></dd>
<dt><b class="option">-compare</b></dt>
<dd><p>This is the standard compare mode argument. <b class="cmd">S3::Put</b> returns
1 if the data was copied or 0 if the data was skipped due to
the comparison mode so indicating it should be skipped.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">S3::Get</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span> <span class="opt">?<b class="option">-file</b> <i class="arg">filename</i>?</span> <span class="opt">?<b class="option">-content</b> <i class="arg">contentvarname</i>?</span> <span class="opt">?<b class="option">-timestamp</b> <i class="arg">aws|now</i>?</span> <span class="opt">?<b class="option">-headers</b> <i class="arg">headervarname</i>?</span></a></dt>
<dd><p>This command retrieves data from a resource on Amazon's S3 servers,
using the HTTP GET command. It returns 0 if the <b class="option">-compare</b> mode
prevented the transfer, 1 if the transfer worked, or throws an error
if the transfer was attempted but failed. Server 5XX errors and S3 socket
errors are are retried
according to <b class="cmd">S3:Configure</b> settings before throwing an error;
other errors throw immediately. Note that this is always authenticated
as the user configured in via <b class="cmd">S3::Configure -accesskeyid</b>. Use
the Tcllib http for unauthenticated GETs.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b></dt>
<dd><p>This specifies the bucket from which the resource will be read.
Leading and/or trailing slashes are removed for you, as are spaces.</p></dd>
<dt><b class="option">-resource</b></dt>
<dd><p>This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash.
Spaces are not trimmed.</p></dd>
<dt><b class="option">-blocking</b></dt>
<dd><p>The standard blocking flag.</p></dd>
<dt><b class="option">-file</b></dt>
<dd><p>If this is specified, the body of the resource will be read into this file,
incrementally without pulling it entirely into memory first. The parent
directory must already exist. If the file already exists, it must be
writable. If an error is thrown part-way through the process and the
file already existed, it may be clobbered. If an error is thrown part-way
through the process and the file did not already exist, any partial
bits will be deleted. Specifying this is an error if <b class="option">-content</b>
is also specified, but at least one of <b class="option">-file</b> or <b class="option">-content</b> must
be specified.</p></dd>
<dt><b class="option">-timestamp</b></dt>
<dd><p>This is only valid in conjunction with <b class="option">-file</b>. It may be specified
as <i class="arg">now</i> or <i class="arg">aws</i>. The default is <i class="arg">now</i>. If <i class="arg">now</i>, the file's
modification date is left up to the system. If <i class="arg">aws</i>, the file's
mtime is set to match the Last-Modified header on the resource, synchronizing
the two appropriately for <b class="option">-compare</b> <i class="arg">date</i> or
<b class="option">-compare</b> <i class="arg">newer</i>.</p></dd>
<dt><b class="option">-content</b></dt>
<dd><p>If this is specified, the <i class="arg">contentvarname</i> is a variable in the caller's
scope (not necessarily global) that receives the value of the body of
the resource. No encoding is done, so if the resource (for example) represents
a UTF-8 byte sequence, use [encoding convertfrom utf-8] to get a valid
UTF-8 string. If this is specified, the <b class="option">-compare</b> is ignored unless
it is <i class="arg">never</i>, in which case no assignment to <i class="arg">contentvarname</i> is
performed. Specifying this is an error if <b class="option">-file</b> is also specified,
but at least one of <b class="option">-file</b> or <b class="option">-content</b> must be specified.</p></dd>
<dt><b class="option">-compare</b></dt>
<dd><p>This is the standard compare mode argument. <b class="cmd">S3::Get</b> returns
1 if the data was copied or 0 if the data was skipped due to
the comparison mode so indicating it should be skipped.</p></dd>
<dt><b class="option">-headers</b></dt>
<dd><p>If this is specified, the headers resulting from the fetch are stored
in the provided variable, as a dictionary. This will include content-type
and x-amz-meta-* headers, as well as the usual HTTP headers, the x-amz-id
debugging headers, and so on. If no file is fetched (due to <b class="option">-compare</b>
or other errors), no assignment to this variable is performed.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">S3::Head</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-dict</b> <i class="arg">dictvarname</i>?</span> <span class="opt">?<b class="option">-headers</b> <i class="arg">headersvarname</i>?</span> <span class="opt">?<b class="option">-status</b> <i class="arg">statusvarname</i>?</span></a></dt>
<dd><p>This command requests HEAD from the resource.
It returns whether a 2XX code was returned as a result
of the request, never throwing an S3 remote error.
That is, if this returns 1, the resource exists and is
accessible. If this returns 0, something went wrong, and the
<b class="option">-status</b> result can be consulted for details.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b></dt>
<dd><p>This specifies the bucket from which the resource will be read.
Leading and/or trailing slashes are removed for you, as are spaces.</p></dd>
<dt><b class="option">-resource</b></dt>
<dd><p>This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash.
Spaces are not trimmed.</p></dd>
<dt><b class="option">-blocking</b></dt>
<dd><p>The standard blocking flag.</p></dd>
<dt><b class="option">-dict</b></dt>
<dd><p>If specified, the resulting dictionary from the <b class="cmd">S3::REST</b>
call is assigned to the indicated (not necessarily global) variable
in the caller's scope.</p></dd>
<dt><b class="option">-headers</b></dt>
<dd><p>If specified, the dictionary of headers from the result are assigned
to the indicated (not necessarily global) variable in the caller's scope.</p></dd>
<dt><b class="option">-status</b></dt>
<dd><p>If specified, the indicated (not necessarily global) variable in
the caller's scope is assigned a 2-element list. The first element is
the 3-digit HTTP status code, while the second element is
the HTTP message (such as "OK" or "Forbidden").</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">S3::GetAcl</b> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-result-type</b> <i class="arg">REST|xml|pxml</i>?</span></a></dt>
<dd><p>This command gets the ACL of the indicated resource or throws an
error if it is unavailable.</p>
<dl class="doctools_definitions">
<dt><b class="option">-blocking</b> <i class="arg">boolean</i></dt>
<dd><p>See above for standard definition.</p></dd>
<dt><b class="option">-bucket</b></dt>
<dd><p>This specifies the bucket from which the resource will be read.
Leading and/or trailing slashes are removed for you, as are spaces.</p></dd>
<dt><b class="option">-resource</b></dt>
<dd><p>This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash.
Spaces are not trimmed.</p></dd>
<dt><b class="option">-parse-xml</b> <i class="arg">xml</i></dt>
<dd><p>The XML from a previous GetACL can be passed in to be parsed into
dictionary form. In this case, -result-type must be pxml or dict.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">REST</i></dt>
<dd><p>The dictionary returned by <b class="cmd">S3::REST</b> is the return value of
<b class="cmd">S3::GetAcl</b>. In this case, a non-2XX httpstatus will not throw an
error.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">xml</i></dt>
<dd><p>The raw XML of the body is returned as the result (with no encoding applied).</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">pxml</i></dt>
<dd><p>The XML of the body as parsed by <b class="cmd">xsxp::parse</b> is returned.</p></dd>
<dt><b class="option">-result-type</b> <i class="arg">dict</i></dt>
<dd><p>This fetches the ACL, parses it, and returns a dictionary of two elements.</p>
<p>The first element has the key "owner" whose value is the canonical ID of the owner of the resource.</p>
<p>The second element has the key "acl" whose value is a dictionary. Each
key in the dictionary is one of Amazon's permissions, namely "READ",
"WRITE", "READ_ACP", "WRITE_ACP", or "FULL_CONTROL". Each value of each
key is a list of canonical IDs or group URLs that have that permission.
Elements are not in the list in any particular order, and not all keys
are necessarily present. Display names are not returned, as they are
not especially useful; use pxml to obtain them if necessary.</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">S3::PutAcl</b> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-acl</b> <i class="arg">new-acl</i>?</span></a></dt>
<dd><p>This sets the ACL on the indicated resource. It returns the XML written to the ACL, or throws an error if anything went wrong.</p>
<dl class="doctools_definitions">
<dt><b class="option">-blocking</b> <i class="arg">boolean</i></dt>
<dd><p>See above for standard definition.</p></dd>
<dt><b class="option">-bucket</b></dt>
<dd><p>This specifies the bucket from which the resource will be read.
Leading and/or trailing slashes are removed for you, as are spaces.</p></dd>
<dt><b class="option">-resource</b></dt>
<dd><p>This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash.
Spaces are not trimmed.</p></dd>
<dt><b class="option">-owner</b></dt>
<dd><p>If this is provided, it is assumed to match the owner of the resource.
Otherwise, a GET may need to be issued against the resource to find
the owner. If you already have the owner (such as from a call
to <b class="cmd">S3::GetAcl</b>, you can pass the value of the "owner" key
as the value of this option, and it will be used in the construction
of the XML.</p></dd>
<dt><b class="option">-acl</b></dt>
<dd><p>If this option is specified, it provides the ACL the caller wishes
to write to the resource. If this is not supplied or is empty,
the value is taken from <b class="cmd">S3::Configure -default-acl</b>.
The ACL is written with a PUT to the ?acl resource.</p>
<p>If the value passed to this option
starts with "<", it is taken to be a body to be PUT to the ACL resource.</p>
<p>If the value matches one of the standard Amazon x-amz-acl headers (i.e.,
a canned access policy), that header is translated to XML and then
applied. The canned access policies are private, public-read,
public-read-write, and authenticated-read (in lower case).</p>
<p>Otherwise, the value is assumed to be a dictionary formatted as the
"acl" sub-entry within the dict returns by <b class="cmd">S3::GetAcl -result-type dict</b>.
The proper XML is generated and applied to the resource. Note that a
value containing "//" is assumed to be a group, a value containing "@"
is assumed to be an AmazonCustomerByEmail, and otherwise the value is
assumed to be a canonical Amazon ID.</p>
<p>Note that you cannot change the owner, so calling GetAcl on a resource
owned by one user and applying it via PutAcl on a resource owned by
another user may not do exactly what you expect.</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">S3::Delete</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-resource</b> <i class="arg">resourcename</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-status</b> <i class="arg">statusvar</i>?</span></a></dt>
<dd><p>This command deletes the specified resource from the specified bucket.
It returns 1 if the resource was deleted successfully, 0 otherwise.
It returns 0 rather than throwing an S3 remote error.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b></dt>
<dd><p>This specifies the bucket from which the resource will be deleted.
Leading and/or trailing slashes are removed for you, as are spaces.</p></dd>
<dt><b class="option">-resource</b></dt>
<dd><p>This is the full name of the resource within the bucket. A single
leading slash is removed, but not a trailing slash.
Spaces are not trimmed.</p></dd>
<dt><b class="option">-blocking</b></dt>
<dd><p>The standard blocking flag.</p></dd>
<dt><b class="option">-status</b></dt>
<dd><p>If specified, the indicated (not necessarily global) variable
in the caller's scope is set to a two-element list. The first
element is the 3-digit HTTP status code. The second element
is the HTTP message (such as "OK" or "Forbidden"). Note that
Amazon's DELETE result is 204 on success, that being the
code indicating no content in the returned body.</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">S3::Push</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-directory</b> <i class="arg">directoryname</i> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefixstring</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span> <span class="opt">?<b class="option">-x-amz-meta-*</b> <i class="arg">metastring</i>?</span> <span class="opt">?<b class="option">-acl</b> <i class="arg">aclcode</i>?</span> <span class="opt">?<b class="option">-delete</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">throw|break|continue</i>?</span> <span class="opt">?<b class="option">-progress</b> <i class="arg">scriptprefix</i>?</span></a></dt>
<dd><p>This synchronises a local directory with a remote bucket
by pushing the differences using <b class="cmd">S3::Put</b>. Note that
if something has changed in the bucket but not locally,
those changes could be lost. Thus, this is not a general
two-way synchronization primitive. (See <b class="cmd">S3::Sync</b>
for that.) Note too that resource names are case sensitive,
so changing the case of a file on a Windows machine may lead
to otherwise-unnecessary transfers.
Note that only regular files are considered, so devices, pipes, symlinks,
and directories are not copied.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b></dt>
<dd><p>This names the bucket into which data will be pushed.</p></dd>
<dt><b class="option">-directory</b></dt>
<dd><p>This names the local directory from which files will be taken.
It must exist, be readable via [glob] and so on. If only
some of the files therein are readable, <b class="cmd">S3::Push</b> will PUT
those files that are readable and return in its results the list
of files that could not be opened.</p></dd>
<dt><b class="option">-prefix</b></dt>
<dd><p>This names the prefix that will be added to all resources.
That is, it is the remote equivalent of <b class="option">-directory</b>.
If it is not specified, the root of the bucket will be treated
as the remote directory. An example may clarify.</p>
<pre class="doctools_example">
S3::Push -bucket test -directory /tmp/xyz -prefix hello/world
</pre>
<p>In this example, /tmp/xyz/pdq.html will be stored as
http://s3.amazonaws.com/test/hello/world/pdq.html in Amazon's servers. Also,
/tmp/xyz/abc/def/Hello will be stored as
http://s3.amazonaws.com/test/hello/world/abc/def/Hello in Amazon's servers.
Without the <b class="option">-prefix</b> option, /tmp/xyz/pdq.html would be stored
as http://s3.amazonaws.com/test/pdq.html.</p></dd>
<dt><b class="option">-blocking</b></dt>
<dd><p>This is the standard blocking option.</p></dd>
<dt><b class="option">-compare</b></dt>
<dd><p>If present, this is passed to each invocation of <b class="cmd">S3::Put</b>.
Naturally, <b class="cmd">S3::Configure -default-compare</b> is used
if this is not specified.</p></dd>
<dt><b class="option">-x-amz-meta-*</b></dt>
<dd><p>If present, this is passed to each invocation of <b class="cmd">S3::Put</b>. All copied
files will have the same metadata.</p></dd>
<dt><b class="option">-acl</b></dt>
<dd><p>If present, this is passed to each invocation of <b class="cmd">S3::Put</b>.</p></dd>
<dt><b class="option">-delete</b></dt>
<dd><p>This defaults to false. If true, resources in the destination that
are not in the source directory are deleted with <b class="cmd">S3::Delete</b>.
Since only regular files are considered, the existance of a symlink,
pipe, device, or directory in the local source will <em>not</em>
prevent the deletion of a remote resource with a corresponding name.</p></dd>
<dt><b class="option">-error</b></dt>
<dd><p>This controls the behavior of <b class="cmd">S3::Push</b> in the event that
<b class="cmd">S3::Put</b> throws an error. Note that
errors encountered on the local file system or in reading the
list of resources in the remote bucket always throw errors.
This option allows control over "partial" errors, when some
files were copied and some were not. <b class="cmd">S3::Delete</b> is always
finished up, with errors simply recorded in the return result.</p>
<dl class="doctools_definitions">
<dt>throw</dt>
<dd><p>The error is rethrown with the same errorCode.</p></dd>
<dt>break</dt>
<dd><p>Processing stops without throwing an error, the error is recorded
in the return value, and the command returns with a normal return.
The calls to <b class="cmd">S3::Delete</b> are not started.</p></dd>
<dt>continue</dt>
<dd><p>This is the default. Processing continues without throwing,
recording the error in the return result, and resuming with the
next file in the local directory to be copied.</p></dd>
</dl></dd>
<dt><b class="option">-progress</b></dt>
<dd><p>If this is specified and the indicated script prefix is not empty, the
indicated script prefix will be invoked several times in the caller's
context with additional arguments at various points in the processing.
This allows progress reporting without backgrounding. The provided
prefix will be invoked with additional arguments, with the first
additional argument indicating what part of the process is being
reported on. The prefix is initially invoked with <i class="arg">args</i> as the
first additional argument and a dictionary representing the normalized
arguments to the <b class="cmd">S3::Push</b> call as the second additional argument.
Then the prefix is invoked with <i class="arg">local</i> as the first additional
argument and a list of suffixes of the files to be considered as the
second argument. Then the prefix is invoked with <i class="arg">remote</i> as the
first additional argument and a list of suffixes existing in the remote
bucket as the second additional argument. Then, for each file in the
local list, the prefix will be invoked with <i class="arg">start</i> as the first
additional argument and the common suffix as the second additional
argument. When <b class="cmd">S3::Put</b> returns for that file, the prefix will be
invoked with <i class="arg">copy</i> as the first additional argument, the common
suffix as the second additional argument, and a third argument that will
be "copied" (if <b class="cmd">S3::Put</b> sent the resource), "skipped" (if
<b class="cmd">S3::Put</b> decided not to based on <b class="option">-compare</b>), or the errorCode
that <b class="cmd">S3::Put</b> threw due to unexpected errors (in which case the
third argument is a list that starts with "S3"). When all files have
been transfered, the prefix may be invoked zero or more times with
<i class="arg">delete</i> as the first additional argument and the suffix of the
resource being deleted as the second additional argument, with a third
argument being either an empty string (if the delete worked) or the
errorCode from <b class="cmd">S3::Delete</b> if it failed. Finally, the prefix
will be invoked with <i class="arg">finished</i> as the first additional argument
and the return value as the second additional argument.</p></dd>
</dl>
<p>The return result from this command is a dictionary. They keys are the
suffixes (i.e., the common portion of the path after the <b class="option">-directory</b>
and <b class="option">-prefix</b>), while the values are either "copied", "skipped" (if
<b class="option">-compare</b> indicated not to copy the file), or the errorCode
thrown by <b class="cmd">S3::Put</b>, as appropriate. If <b class="option">-delete</b> was true,
there may also be entries for suffixes with the value "deleted" or
"notdeleted", indicating whether the attempted <b class="cmd">S3::Delete</b>
worked or not, respectively. There is one additional pair in the return
result, whose key is the empty string and whose value is a nested dictionary.
The keys of this nested dictionary include "filescopied" (the number of
files successfully copied), "bytescopied" (the number of data bytes in
the files copied, excluding headers, metadata, etc), "compareskipped" (the
number of files not copied due to <b class="option">-compare</b> mode), "errorskipped"
(the number of files not copied due to thrown errors), "filesdeleted"
(the number of resources deleted due to not having corresponding files
locally, or 0 if <b class="option">-delete</b> is false), and "filesnotdeleted"
(the number of resources whose deletion was attempted but failed).</p>
<p>Note that this is currently implemented somewhat inefficiently.
It fetches the bucket listing (including timestamps and eTags),
then calls <b class="cmd">S3::Put</b>, which uses HEAD to find the timestamps
and eTags again. Correcting this with no API change
is planned for a future upgrade.</p></dd>
<dt><a name="15"><b class="cmd">S3::Pull</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-directory</b> <i class="arg">directoryname</i> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefixstring</i>?</span> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-compare</b> <i class="arg">comparemode</i>?</span> <span class="opt">?<b class="option">-delete</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-timestamp</b> <i class="arg">aws|now</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">throw|break|continue</i>?</span> <span class="opt">?<b class="option">-progress</b> <i class="arg">scriptprefix</i>?</span></a></dt>
<dd><p>This synchronises a remote bucket with a local directory by pulling the
differences using <b class="cmd">S3::Get</b> If something has been changed locally but not
in the bucket, those difference may be lost. This is not a general two-way
synchronization mechanism. (See <b class="cmd">S3::Sync</b> for that.)
This creates directories
if needed; new directories are created with default permissions. Note that
resource names are case sensitive, so changing the case of a file on a
Windows machine may lead to otherwise-unnecessary transfers. Also, try not
to store data in resources that end with a slash, or which are prefixes of
resources that otherwise would start with a slash; i.e., don't use this if
you store data in resources whose names have to be directories locally.</p>
<p>Note that this is currently implemented somewhat inefficiently.
It fetches the bucket listing (including timestamps and eTags),
then calls <b class="cmd">S3::Get</b>, which uses HEAD to find the timestamps
and eTags again. Correcting this with no API change
is planned for a future upgrade.</p>
<dl class="doctools_definitions">
<dt><b class="option">-bucket</b></dt>
<dd><p>This names the bucket from which data will be pulled.</p></dd>
<dt><b class="option">-directory</b></dt>
<dd><p>This names the local directory into which files will be written
It must exist, be readable via [glob], writable for file creation,
and so on. If only some of the files therein are writable,
<b class="cmd">S3::Pull</b> will GET
those files that are writable and return in its results the list
of files that could not be opened.</p></dd>
<dt><b class="option">-prefix</b></dt>
<dd><p>The prefix of resources that will be considered for retrieval.
See <b class="cmd">S3::Push</b> for more details, examples, etc. (Of course,
<b class="cmd">S3::Pull</b> reads rather than writes, but the prefix is
treated similarly.)</p></dd>
<dt><b class="option">-blocking</b></dt>
<dd><p>This is the standard blocking option.</p></dd>
<dt><b class="option">-compare</b></dt>
<dd><p>This is passed to each invocation of <b class="cmd">S3::Get</b> if provided.
Naturally, <b class="cmd">S3::Configure -default-compare</b> is
used if this is not provided.</p></dd>
<dt><b class="option">-timestamp</b></dt>
<dd><p>This is passed to each invocation of <b class="cmd">S3::Get</b> if provided.</p></dd>
<dt><b class="option">-delete</b></dt>
<dd><p>If this is specified and true, files that exist in the <b class="option">-directory</b>
that are not in the <b class="option">-prefix</b> will be deleted after all resources
have been copied. In addition, empty directories (other than the
top-level <b class="option">-directory</b>) will be deleted, as
Amazon S3 has no concept of an empty directory.</p></dd>
<dt><b class="option">-error</b></dt>
<dd><p>See <b class="cmd">S3::Push</b> for a description of this option.</p></dd>
<dt><b class="option">-progress</b></dt>
<dd><p>See <b class="cmd">S3::Push</b> for a description of this option.
It differs slightly in that local directories may be included
with a trailing slash to indicate they are directories.</p></dd>
</dl>
<p>The return value from this command is a dictionary. It
is identical in form and meaning to the description of the
return result of <b class="cmd">S3::Push</b>. It differs only in that
directories may be included, with a trailing slash in their name,
if they are empty and get deleted.</p></dd>
<dt><a name="16"><b class="cmd">S3::Toss</b> <span class="opt">?<b class="option">-bucket</b> <i class="arg">bucketname</i>?</span> <b class="option">-prefix</b> <i class="arg">prefixstring</i> <span class="opt">?<b class="option">-blocking</b> <i class="arg">boolean</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">throw|break|continue</i>?</span> <span class="opt">?<b class="option">-progress</b> <i class="arg">scriptprefix</i>?</span></a></dt>
<dd><p>This deletes some or all resources within a bucket. It would be
considered a "recursive delete" had Amazon implemented actual
directories.</p>
<dl class="doctools_options">
<dt><b class="option">-bucket</b></dt>
<dd><p>The bucket from which resources will be deleted.</p></dd>
<dt><b class="option"><b class="option">-blocking</b></b></dt>
<dd><p>The standard blocking option.</p></dd>
<dt><b class="option"><b class="option">-prefix</b></b></dt>
<dd><p>The prefix for resources to be deleted. Any resource that
starts with this string will be deleted. This is required.
To delete everything in the bucket, pass an empty string
for the prefix.</p></dd>
<dt><b class="option"><b class="option">-error</b></b></dt>
<dd><p>If this is "throw", <b class="cmd">S3::Toss</b> rethrows any errors
it encounters. If this is "break", <b class="cmd">S3::Toss</b> returns
with a normal return after the first error, recording that
error in the return result. If this is "continue", which is
the default, <b class="cmd">S3::Toss</b> continues on and lists all
errors in the return result.</p></dd>
<dt><b class="option"><b class="option">-progress</b></b></dt>
<dd><p>If this is specified and not an empty string, the script
prefix will be invoked several times in the context of the caller
with additional arguments appended. Initially, it will be invoked
with the first additional argument being <i class="arg">args</i> and the second
being the processed list of arguments to <b class="cmd">S3::Toss</b>. Then it
is invoked with <i class="arg">remote</i> as the first additional argument and
the list of suffixes in the bucket to be deleted as the second
additional argument. Then it is invoked with the first additional
argument being <i class="arg">delete</i> and the second additional argument being
the suffix deleted and the third additional argument being "deleted"
or "notdeleted" depending on whether <b class="cmd">S3::Delete</b> threw an error.
Finally, the script prefix is invoked with a first additional argument
of "finished" and a second additional argument of the return value.</p></dd>
</dl>
<p>The return value is a dictionary. The keys are the suffixes of files
that <b class="cmd">S3::Toss</b> attempted to delete, and whose values are either
the string "deleted" or "notdeleted". There is also one additional
pair, whose key is the empty string and whose value is an embedded
dictionary. The keys of this embedded dictionary include
"filesdeleted" and "filesnotdeleted", each of which has integer values.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">LIMITATIONS</a></h2>
<ul class="doctools_itemized">
<li><p>The pure-Tcl MD5 checking is slow. If you are processing
files in the megabyte range, consider ensuring binary support is available.</p></li>
<li><p>The commands <b class="cmd">S3::Pull</b> and <b class="cmd">S3::Push</b> fetch a
directory listing which includes timestamps and MD5 hashes,
then invoke <b class="cmd">S3::Get</b> and <b class="cmd">S3::Put</b>. If
a complex <b class="option">-compare</b> mode is specified, <b class="cmd">S3::Get</b> and
<b class="cmd">S3::Put</b> will invoke a HEAD operation for each file to fetch
timestamps and MD5 hashes of each resource again. It is expected that
a future release of this package will solve this without any API changes.</p></li>
<li><p>The commands <b class="cmd">S3::Pull</b> and <b class="cmd">S3::Push</b> fetch a
directory listing without using <b class="option">-max-count</b>. The entire
directory is pulled into memory at once. For very large buckets,
this could be a performance problem. The author, at this time,
does not plan to change this behavior. Welcome to Open Source.</p></li>
<li><p><b class="cmd">S3::Sync</b> is neither designed nor implemented yet.
The intention would be to keep changes synchronised, so changes
could be made to both the bucket and the local directory and
be merged by <b class="cmd">S3::Sync</b>.</p></li>
<li><p>Nor is
<b class="option">-compare</b> <i class="arg">calc</i> fully implemented. This is primarily due to
Windows not providing a convenient method for distinguishing between
local files that are "public-read" or "public-read-write". Assistance
figuring out TWAPI for this would be appreciated. The U**X semantics
are difficult to map directly as well. See the source for details.
Note that there are not tests for calc, since it isn't done yet.</p></li>
<li><p>The HTTP processing is implemented within the library,
rather than using a "real" HTTP package. Hence, multi-line headers
are not (yet) handled correctly. Do not include carriage returns or
linefeeds in x-amz-meta-* headers, content-type values, and so on.
The author does not at this time expect to improve this.</p></li>
<li><p>Internally, <b class="cmd">S3::Push</b> and <b class="cmd">S3::Pull</b> and <b class="cmd">S3::Toss</b>
are all very similar and should be refactored.</p></li>
<li><p>The idea of using <b class="option">-compare</b> <i class="arg">never</i>
<b class="option">-delete</b> <i class="arg">true</i> to delete files that have been
deleted from one place but not the other yet not copying
changed files is untested.</p></li>
</ul>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">USAGE SUGGESTIONS</a></h2>
<p>To fetch a "directory" out of a bucket, make changes, and store it back:</p>
<pre class="doctools_example">
file mkdir ./tempfiles
S3::Pull -bucket sample -prefix of/interest -directory ./tempfiles \
-timestamp aws
do_my_process ./tempfiles other arguments
S3::Push -bucket sample -prefix of/interest -directory ./tempfiles \
-compare newer -delete true
</pre>
<p>To delete files locally that were deleted off of S3 but not otherwise
update files:</p>
<pre class="doctools_example">
S3::Pull -bucket sample -prefix of/interest -directory ./myfiles \
-compare never -delete true
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">FUTURE DEVELOPMENTS</a></h2>
<p>The author intends to work on several additional projects related to
this package, in addition to finishing the unfinished features.</p>
<p>First, a command-line program allowing browsing of buckets and
transfer of files from shell scripts and command prompts is useful.</p>
<p>Second, a GUI-based program allowing visual manipulation of
bucket and resource trees not unlike Windows Explorer would
be useful.</p>
<p>Third, a command-line (and perhaps a GUI-based) program called
"OddJob" that will use S3 to synchronize computation amongst
multiple servers running OddJob. An S3 bucket will be set up
with a number of scripts to run, and the OddJob program can
be invoked on multiple machines to run scripts on all the machines,
each moving on to the next unstarted task as it finishes each.
This is still being designed, and it is intended primarily
to be run on Amazon's Elastic Compute Cloud.</p>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section10" class="doctools_section"><h2><a name="section10">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>amazon-s3</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#amazon">amazon</a>, <a href="../../../../index.html#cloud">cloud</a>, <a href="../../../../index.html#s3">s3</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms.</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/amazon-s3/xsxp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<div class='fossil-doc' data-title='xsxp - Amazon S3 Web Service Utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">xsxp(n) 1.0 tcllib "Amazon S3 Web Service Utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>xsxp - eXtremely Simple Xml Parser</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">xsxp 1</b></li>
<li>package require <b class="pkgname">xml</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">xsxp::parse</b> <i class="arg">xml</i></a></li>
<li><a href="#2"><b class="cmd">xsxp::fetch</b> <i class="arg">pxml</i> <i class="arg">path</i> <span class="opt">?<i class="arg">part</i>?</span></a></li>
<li><a href="#3"><b class="cmd">xsxp::fetchall</b> <i class="arg">pxml_list</i> <i class="arg">path</i> <span class="opt">?<i class="arg">part</i>?</span></a></li>
<li><a href="#4"><b class="cmd">xsxp::only</b> <i class="arg">pxml</i> <i class="arg">tagname</i></a></li>
<li><a href="#5"><b class="cmd">xsxp::prettyprint</b> <i class="arg">pxml</i> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a simple interface to parse XML into a pure-value list.
It also provides accessor routines to pull out specific subtags,
not unlike DOM access.
This package was written for and is used by Darren New's Amazon S3 access package.</p>
<p>This is pretty lame, but I needed something like this for S3,
and at the time, TclDOM would not work with the new 8.5 Tcl
due to version number problems.</p>
<p>In addition, this is a pure-value implementation. There is no
garbage to clean up in the event of a thrown error, for example.
This simplifies the code for sufficiently small XML documents,
which is what Amazon's S3 guarantees.</p>
<p>Copyright 2006 Darren New. All Rights Reserved.
NO WARRANTIES OF ANY TYPE ARE PROVIDED.
COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS.
This software is licensed under essentially the same
terms as Tcl. See LICENSE.txt for the terms.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<p>The package implements five rather simple procedures.
One parses, one is for debugging, and the rest pull various
parts of the parsed document out for processing.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">xsxp::parse</b> <i class="arg">xml</i></a></dt>
<dd><p>This parses an XML document (using the standard xml tcllib module in a SAX sort of way) and builds a data structure which it returns if the parsing succeeded. The return value is referred to herein as a "pxml", or "parsed xml". The list consists of two or more elements:</p>
<ul class="doctools_itemized">
<li><p>The first element is the name of the tag.</p></li>
<li><p>The second element is an array-get formatted list of key/value pairs. The keys are attribute names and the values are attribute values. This is an empty list if there are no attributes on the tag.</p></li>
<li><p>The third through end elements are the children of the node, if any. Each child is, recursively, a pxml.</p></li>
<li><p>Note that if the zero'th element, i.e. the tag name, is "%PCDATA", then
the attributes will be empty and the third element will be the text of the element. In addition, if an element's contents consists only of PCDATA, it will have only one child, and all the PCDATA will be concatenated. In other words,
this parser works poorly for XML with elements that contain both child tags and PCDATA. Since Amazon S3 does not do this (and for that matter most
uses of XML where XML is a poor choice don't do this), this is probably
not a serious limitation.</p></li>
</ul></dd>
<dt><a name="2"><b class="cmd">xsxp::fetch</b> <i class="arg">pxml</i> <i class="arg">path</i> <span class="opt">?<i class="arg">part</i>?</span></a></dt>
<dd><p><i class="arg">pxml</i> is a parsed XML, as returned from xsxp::parse.
<i class="arg">path</i> is a list of element tag names. Each element is the name
of a child to look up, optionally followed by a
hash ("#") and a string of digits. An empty list or an initial empty element
selects <i class="arg">pxml</i>. If no hash sign is present, the behavior is as if "#0"
had been appended to that element. (In addition to a list, slashes can separate subparts where convenient.)</p>
<p>An element of <i class="arg">path</i> scans the children at the indicated level
for the n'th instance of a child whose tag matches the part of the
element before the hash sign. If an element is simply "#" followed
by digits, that indexed child is selected, regardless of the tags
in the children. Hence, an element of "#3" will always select
the fourth child of the node under consideration.</p>
<p><i class="arg">part</i> defaults to "%ALL". It can be one of the following case-sensitive terms:</p>
<dl class="doctools_definitions">
<dt>%ALL</dt>
<dd><p>returns the entire selected element.</p></dd>
<dt>%TAGNAME</dt>
<dd><p>returns lindex 0 of the selected element.</p></dd>
<dt>%ATTRIBUTES</dt>
<dd><p>returns index 1 of the selected element.</p></dd>
<dt>%CHILDREN</dt>
<dd><p>returns lrange 2 through end of the selected element,
resulting in a list of elements being returned.</p></dd>
<dt>%PCDATA</dt>
<dd><p>returns a concatenation of all the bodies of
direct children of this node whose tag is %PCDATA.
It throws an error if no such children are found. That
is, part=%PCDATA means return the textual content found
in that node but not its children nodes.</p></dd>
<dt>%PCDATA?</dt>
<dd><p>is like %PCDATA, but returns an empty string if
no PCDATA is found.</p></dd>
</dl>
<p>For example, to fetch the first bold text from the fifth paragraph of the body of your HTML file,</p>
<pre class="doctools_example">xsxp::fetch $pxml {body p#4 b} %PCDATA</pre>
</dd>
<dt><a name="3"><b class="cmd">xsxp::fetchall</b> <i class="arg">pxml_list</i> <i class="arg">path</i> <span class="opt">?<i class="arg">part</i>?</span></a></dt>
<dd><p>This iterates over each PXML in <i class="arg">pxml_list</i> (which must be a list
of pxmls) selecting the indicated path from it, building a new list
with the selected data, and returning that new list.</p>
<p>For example, <i class="arg">pxml_list</i> might be
the %CHILDREN of a particular element, and the <i class="arg">path</i> and <i class="arg">part</i>
might select from each child a sub-element in which we're interested.</p></dd>
<dt><a name="4"><b class="cmd">xsxp::only</b> <i class="arg">pxml</i> <i class="arg">tagname</i></a></dt>
<dd><p>This iterates over the direct children of <i class="arg">pxml</i> and selects only
those with <i class="arg">tagname</i> as their tag. Returns a list of matching
elements.</p></dd>
<dt><a name="5"><b class="cmd">xsxp::prettyprint</b> <i class="arg">pxml</i> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>This outputs to <i class="arg">chan</i> (default stdout) a pretty-printed
version of <i class="arg">pxml</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>amazon-s3</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#dom">dom</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#xml">xml</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>2006 Darren New. All Rights Reserved.</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/asn/asn.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
|
<div class='fossil-doc' data-title='asn - ASN.1 processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">asn(n) 0.8 tcllib "ASN.1 processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>asn - ASN.1 BER encoder/decoder</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">ENCODER</a></li>
<li class="doctools_subsection"><a href="#subsection2">DECODER</a></li>
<li class="doctools_subsection"><a href="#subsection3">HANDLING TAGS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">asn <span class="opt">?0.8.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::asn::asnSequence</b> <i class="arg">evalue</i>...</a></li>
<li><a href="#2"><b class="cmd">::asn::asnSequenceFromList</b> <i class="arg">elist</i></a></li>
<li><a href="#3"><b class="cmd">::asn::asnSet</b> <i class="arg">evalue</i>...</a></li>
<li><a href="#4"><b class="cmd">::asn::asnSetFromList</b> <i class="arg">elist</i></a></li>
<li><a href="#5"><b class="cmd">::asn::asnApplicationConstr</b> <i class="arg">appNumber</i> <i class="arg">evalue</i>...</a></li>
<li><a href="#6"><b class="cmd">::asn::asnApplication</b> <i class="arg">appNumber</i> <i class="arg">data</i></a></li>
<li><a href="#7"><b class="cmd">::asn::asnChoice</b> <i class="arg">appNumber</i> <i class="arg">evalue</i>...</a></li>
<li><a href="#8"><b class="cmd">::asn::asnChoiceConstr</b> <i class="arg">appNumber</i> <i class="arg">evalue</i>...</a></li>
<li><a href="#9"><b class="cmd">::asn::asnInteger</b> <i class="arg">number</i></a></li>
<li><a href="#10"><b class="cmd">::asn::asnEnumeration</b> <i class="arg">number</i></a></li>
<li><a href="#11"><b class="cmd">::asn::asnBoolean</b> <i class="arg">bool</i></a></li>
<li><a href="#12"><b class="cmd">::asn::asnContext</b> <i class="arg">context</i> <i class="arg">data</i></a></li>
<li><a href="#13"><b class="cmd">::asn::asnContextConstr</b> <i class="arg">context</i> <i class="arg">evalue</i>...</a></li>
<li><a href="#14"><b class="cmd">::asn::asnObjectIdentifier</b> <i class="arg">idlist</i></a></li>
<li><a href="#15"><b class="cmd">::asn::asnUTCTime</b> <i class="arg">utcstring</i></a></li>
<li><a href="#16"><b class="cmd">::asn::asnNull</b></a></li>
<li><a href="#17"><b class="cmd">::asn::asnBitString</b> <i class="arg">string</i></a></li>
<li><a href="#18"><b class="cmd">::asn::asnOctetString</b> <i class="arg">string</i></a></li>
<li><a href="#19"><b class="cmd">::asn::asnNumericString</b> <i class="arg">string</i></a></li>
<li><a href="#20"><b class="cmd">::asn::asnPrintableString</b> <i class="arg">string</i></a></li>
<li><a href="#21"><b class="cmd">::asn::asnIA5String</b> <i class="arg">string</i></a></li>
<li><a href="#22"><b class="cmd">::asn::asnBMPString</b> <i class="arg">string</i></a></li>
<li><a href="#23"><b class="cmd">::asn::asnUTF8String</b> <i class="arg">string</i></a></li>
<li><a href="#24"><b class="cmd">::asn::asnString</b> <i class="arg">string</i></a></li>
<li><a href="#25"><b class="cmd">::asn::defaultStringType</b> <span class="opt">?<i class="arg">type</i>?</span></a></li>
<li><a href="#26"><b class="cmd">::asn::asnPeekByte</b> <i class="arg">data_var</i> <i class="arg">byte_var</i></a></li>
<li><a href="#27"><b class="cmd">::asn::asnGetLength</b> <i class="arg">data_var</i> <i class="arg">length_var</i></a></li>
<li><a href="#28"><b class="cmd">::asn::asnGetResponse</b> <i class="arg">chan</i> <i class="arg">data_var</i></a></li>
<li><a href="#29"><b class="cmd">::asn::asnGetInteger</b> <i class="arg">data_var</i> <i class="arg">int_var</i></a></li>
<li><a href="#30"><b class="cmd">::asn::asnGetEnumeration</b> <i class="arg">data_var</i> <i class="arg">enum_var</i></a></li>
<li><a href="#31"><b class="cmd">::asn::asnGetOctetString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></li>
<li><a href="#32"><b class="cmd">::asn::asnGetString</b> <i class="arg">data_var</i> <i class="arg">string_var</i> <span class="opt">?<i class="arg">type_var</i>?</span></a></li>
<li><a href="#33"><b class="cmd">::asn::asnGetNumericString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></li>
<li><a href="#34"><b class="cmd">::asn::asnGetPrintableString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></li>
<li><a href="#35"><b class="cmd">::asn::asnGetIA5String</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></li>
<li><a href="#36"><b class="cmd">::asn::asnGetBMPString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></li>
<li><a href="#37"><b class="cmd">::asn::asnGetUTF8String</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></li>
<li><a href="#38"><b class="cmd">::asn::asnGetUTCTime</b> <i class="arg">data_var</i> <i class="arg">utc_var</i></a></li>
<li><a href="#39"><b class="cmd">::asn::asnGetBitString</b> <i class="arg">data_var</i> <i class="arg">bits_var</i></a></li>
<li><a href="#40"><b class="cmd">::asn::asnGetObjectIdentifier</b> <i class="arg">data_var</i> <i class="arg">oid_var</i></a></li>
<li><a href="#41"><b class="cmd">::asn::asnGetBoolean</b> <i class="arg">data_var</i> <i class="arg">bool_var</i></a></li>
<li><a href="#42"><b class="cmd">::asn::asnGetNull</b> <i class="arg">data_var</i></a></li>
<li><a href="#43"><b class="cmd">::asn::asnGetSequence</b> <i class="arg">data_var</i> <i class="arg">sequence_var</i></a></li>
<li><a href="#44"><b class="cmd">::asn::asnGetSet</b> <i class="arg">data_var</i> <i class="arg">set_var</i></a></li>
<li><a href="#45"><b class="cmd">::asn::asnGetApplication</b> <i class="arg">data_var</i> <i class="arg">appNumber_var</i> <span class="opt">?<i class="arg">content_var</i>?</span> <span class="opt">?<i class="arg">encodingType_var</i>?</span></a></li>
<li><a href="#46"><b class="cmd">::asn::asnGetContext</b> <i class="arg">data_var</i> <i class="arg">contextNumber_var</i> <span class="opt">?<i class="arg">content_var</i>?</span> <span class="opt">?<i class="arg">encodingType_var</i>?</span></a></li>
<li><a href="#47"><b class="cmd">::asn::asnPeekTag</b> <i class="arg">data_var</i> <i class="arg">tag_var</i> <i class="arg">tagtype_var</i> <i class="arg">constr_var</i></a></li>
<li><a href="#48"><b class="cmd">::asn::asnTag</b> <i class="arg">tagnumber</i> <span class="opt">?<i class="arg">class</i>?</span> <span class="opt">?<i class="arg">tagstyle</i>?</span></a></li>
<li><a href="#49"><b class="cmd">::asn::asnRetag</b> <i class="arg">data_var</i> <i class="arg">newTag</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">asn</b> package provides <em>partial</em> de- and encoder
commands for BER encoded ASN.1 data. It can also be used for
decoding DER, which is a restricted subset of BER.</p>
<p>ASN.1 is a standard <i class="term">Abstract Syntax Notation</i>, and BER are its
<i class="term">Basic Encoding Rules</i>.</p>
<p>See <a href="http://asn1.elibel.tm.fr/en/standards/index.htm">http://asn1.elibel.tm.fr/en/standards/index.htm</a> for more
information about the standard.</p>
<p>Also see <a href="http://luca.ntop.org/Teaching/Appunti/asn1.html">http://luca.ntop.org/Teaching/Appunti/asn1.html</a> for
<em>A Layman's Guide to a Subset of ASN.1, BER, and DER</em>, an RSA
Laboratories Technical Note by Burton S. Kaliski Jr. (Revised November
1, 1993). A text version of this note is part of the module sources
and should be read by any implementor.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">ENCODER</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::asn::asnSequence</b> <i class="arg">evalue</i>...</a></dt>
<dd><p>Takes zero or more encoded values, packs them into an ASN sequence and
returns its encoded binary form.</p></dd>
<dt><a name="2"><b class="cmd">::asn::asnSequenceFromList</b> <i class="arg">elist</i></a></dt>
<dd><p>Takes a list of encoded values, packs them into an ASN sequence and
returns its encoded binary form.</p></dd>
<dt><a name="3"><b class="cmd">::asn::asnSet</b> <i class="arg">evalue</i>...</a></dt>
<dd><p>Takes zero or more encoded values, packs them into an ASN set and
returns its encoded binary form.</p></dd>
<dt><a name="4"><b class="cmd">::asn::asnSetFromList</b> <i class="arg">elist</i></a></dt>
<dd><p>Takes a list of encoded values, packs them into an ASN set and
returns its encoded binary form.</p></dd>
<dt><a name="5"><b class="cmd">::asn::asnApplicationConstr</b> <i class="arg">appNumber</i> <i class="arg">evalue</i>...</a></dt>
<dd><p>Takes zero or more encoded values, packs them into an ASN application
construct and returns its encoded binary form.</p></dd>
<dt><a name="6"><b class="cmd">::asn::asnApplication</b> <i class="arg">appNumber</i> <i class="arg">data</i></a></dt>
<dd><p>Takes a single encoded value <i class="arg">data</i>, packs it into an ASN
application construct and returns its encoded binary form.</p></dd>
<dt><a name="7"><b class="cmd">::asn::asnChoice</b> <i class="arg">appNumber</i> <i class="arg">evalue</i>...</a></dt>
<dd><p>Takes zero or more encoded values, packs them into an ASN choice
construct and returns its encoded binary form.</p></dd>
<dt><a name="8"><b class="cmd">::asn::asnChoiceConstr</b> <i class="arg">appNumber</i> <i class="arg">evalue</i>...</a></dt>
<dd><p>Takes zero or more encoded values, packs them into an ASN choice
construct and returns its encoded binary form.</p></dd>
<dt><a name="9"><b class="cmd">::asn::asnInteger</b> <i class="arg">number</i></a></dt>
<dd><p>Returns the encoded form of the specified integer
<i class="arg">number</i>.</p></dd>
<dt><a name="10"><b class="cmd">::asn::asnEnumeration</b> <i class="arg">number</i></a></dt>
<dd><p>Returns the encoded form of the specified enumeration id
<i class="arg">number</i>.</p></dd>
<dt><a name="11"><b class="cmd">::asn::asnBoolean</b> <i class="arg">bool</i></a></dt>
<dd><p>Returns the encoded form of the specified boolean value
<i class="arg">bool</i>.</p></dd>
<dt><a name="12"><b class="cmd">::asn::asnContext</b> <i class="arg">context</i> <i class="arg">data</i></a></dt>
<dd><p>Takes an encoded value and packs it into a constructed value with
application tag, the <i class="arg">context</i> number.</p></dd>
<dt><a name="13"><b class="cmd">::asn::asnContextConstr</b> <i class="arg">context</i> <i class="arg">evalue</i>...</a></dt>
<dd><p>Takes zero or more encoded values and packs them into a constructed
value with application tag, the <i class="arg">context</i> number.</p></dd>
<dt><a name="14"><b class="cmd">::asn::asnObjectIdentifier</b> <i class="arg">idlist</i></a></dt>
<dd><p>Takes a list of at least 2 integers describing an object identifier
(OID) value, and returns the encoded value.</p></dd>
<dt><a name="15"><b class="cmd">::asn::asnUTCTime</b> <i class="arg">utcstring</i></a></dt>
<dd><p>Returns the encoded form of the specified UTC time string.</p></dd>
<dt><a name="16"><b class="cmd">::asn::asnNull</b></a></dt>
<dd><p>Returns the NULL encoding.</p></dd>
<dt><a name="17"><b class="cmd">::asn::asnBitString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the encoded form of the specified <i class="arg">string</i>.</p></dd>
<dt><a name="18"><b class="cmd">::asn::asnOctetString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the encoded form of the specified <i class="arg">string</i>.</p></dd>
<dt><a name="19"><b class="cmd">::asn::asnNumericString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the <i class="arg">string</i> encoded as ASN.1 NumericString. Raises an
error if the <i class="arg">string</i> contains characters other than decimal
numbers and space.</p></dd>
<dt><a name="20"><b class="cmd">::asn::asnPrintableString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the <i class="arg">string</i> encoding as ASN.1 PrintableString. Raises an
error if the <i class="arg">string</i> contains characters which are not allowed by
the Printable String datatype. The allowed characters are A-Z, a-z,
0-9, space, apostrophe, colon, parentheses, plus, minus, comma,
period, forward slash, question mark, and the equals sign.</p></dd>
<dt><a name="21"><b class="cmd">::asn::asnIA5String</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the <i class="arg">string</i> encoded as ASN.1 IA5String. Raises an error
if the <i class="arg">string</i> contains any characters outside of the US-ASCII
range.</p></dd>
<dt><a name="22"><b class="cmd">::asn::asnBMPString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the <i class="arg">string</i> encoded as ASN.1 Basic Multilingual Plane
string (Which is essentialy big-endian UCS2).</p></dd>
<dt><a name="23"><b class="cmd">::asn::asnUTF8String</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the <i class="arg">string</i> encoded as UTF8 String. Note that some legacy
applications such as Windows CryptoAPI do not like UTF8 strings. Use
BMPStrings if you are not sure.</p></dd>
<dt><a name="24"><b class="cmd">::asn::asnString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns an encoded form of <i class="arg">string</i>, choosing the most restricted
ASN.1 string type possible. If the string contains non-ASCII
characters, then there is more than one string type which can be
used. See <b class="cmd">::asn::defaultStringType</b>.</p></dd>
<dt><a name="25"><b class="cmd">::asn::defaultStringType</b> <span class="opt">?<i class="arg">type</i>?</span></a></dt>
<dd><p>Selects the string type to use for the encoding of non-ASCII
strings. Returns current default when called without argument. If the
argument <i class="arg">type</i> is supplied, it should be either <b class="const">UTF8</b> or
<b class="const">BMP</b> to choose UTF8String or BMPString respectively.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">DECODER</a></h3>
<p>General notes:</p>
<ol class="doctools_enumerated">
<li><p>Nearly all decoder commands take two arguments. These arguments are variable
names, except for <b class="cmd">::asn::asnGetResponse</b>. The first variable
contains the encoded ASN value to decode at the beginning, and more,
and the second variable is where the value is stored to. The remainder
of the input after the decoded value is stored back into the
datavariable.</p></li>
<li><p>After extraction the data variable is always modified first, before by
writing the extracted value to its variable. This means that if both
arguments refer to the same variable, it will always contain the
extracted value after the call, and not the remainder of the input.</p></li>
</ol>
<dl class="doctools_definitions">
<dt><a name="26"><b class="cmd">::asn::asnPeekByte</b> <i class="arg">data_var</i> <i class="arg">byte_var</i></a></dt>
<dd><p>Retrieve the first byte of the data, without modifing <i class="arg">data_var</i>.
This can be used to check for implicit tags.</p></dd>
<dt><a name="27"><b class="cmd">::asn::asnGetLength</b> <i class="arg">data_var</i> <i class="arg">length_var</i></a></dt>
<dd><p>Decode the length information for a block of BER data. The tag has already
to be removed from the data.</p></dd>
<dt><a name="28"><b class="cmd">::asn::asnGetResponse</b> <i class="arg">chan</i> <i class="arg">data_var</i></a></dt>
<dd><p>Reads an encoded ASN <em>sequence</em> from the channel <i class="arg">chan</i> and
stores it into the variable named by <i class="arg">data_var</i>.</p></dd>
<dt><a name="29"><b class="cmd">::asn::asnGetInteger</b> <i class="arg">data_var</i> <i class="arg">int_var</i></a></dt>
<dd><p>Assumes that an encoded integer value is at the front of the data
stored in the variable named <i class="arg">data_var</i>, extracts and stores it
into the variable named by <i class="arg">int_var</i>. Additionally removes all
bytes associated with the value from the data for further processing
by the following decoder commands.</p></dd>
<dt><a name="30"><b class="cmd">::asn::asnGetEnumeration</b> <i class="arg">data_var</i> <i class="arg">enum_var</i></a></dt>
<dd><p>Assumes that an enumeration id is at the front of the data stored in
the variable named <i class="arg">data_var</i>, and stores it into the variable
named by <i class="arg">enum_var</i>. Additionally removes all bytes associated
with the value from the data for further processing by the following
decoder commands.</p></dd>
<dt><a name="31"><b class="cmd">::asn::asnGetOctetString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></dt>
<dd><p>Assumes that a string is at the front of the data stored in the
variable named <i class="arg">data_var</i>, and stores it into the variable named
by <i class="arg">string_var</i>. Additionally removes all bytes associated with
the value from the data for further processing by the following
decoder commands.</p></dd>
<dt><a name="32"><b class="cmd">::asn::asnGetString</b> <i class="arg">data_var</i> <i class="arg">string_var</i> <span class="opt">?<i class="arg">type_var</i>?</span></a></dt>
<dd><p>Decodes a user-readable string. This is a convenience function which
is able to automatically distinguish all supported ASN.1 string types
and convert the input value appropriately.
See <b class="cmd">::asn::asnGetPrintableString</b>, <b class="cmd">::asnGetIA5String</b>, etc.
below for the type-specific conversion commands.</p>
<p>If the optional third argument <i class="arg">type_var</i> is supplied, then the
type of the incoming string is stored in the variable named by it.</p>
<p>The function throws the error
"Invalid command name asnGetSome<b class="variable">UnsupportedString</b>" if the
unsupported string type <b class="variable">Unsupported</b> is encountered. You can
create the appropriate function
"asn::asnGetSome<b class="variable">UnsupportedString</b>" in your application if
neccessary.</p></dd>
<dt><a name="33"><b class="cmd">::asn::asnGetNumericString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></dt>
<dd><p>Assumes that a numeric string value is at the front of the data stored
in the variable named <i class="arg">data_var</i>, and stores it into the variable
named by <i class="arg">string_var</i>. Additionally removes all bytes associated
with the value from the data for further processing by the following
decoder commands.</p></dd>
<dt><a name="34"><b class="cmd">::asn::asnGetPrintableString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></dt>
<dd><p>Assumes that a printable string value is at the front of the data
stored in the variable named <i class="arg">data_var</i>, and stores it into the
variable named by <i class="arg">string_var</i>. Additionally removes all bytes
associated with the value from the data for further processing by the
following decoder commands.</p></dd>
<dt><a name="35"><b class="cmd">::asn::asnGetIA5String</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></dt>
<dd><p>Assumes that a IA5 (ASCII) string value is at the front of the data
stored in the variable named <i class="arg">data_var</i>, and stores it into the
variable named by <i class="arg">string_var</i>. Additionally removes all bytes
associated with the value from the data for further processing by the
following decoder commands.</p></dd>
<dt><a name="36"><b class="cmd">::asn::asnGetBMPString</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></dt>
<dd><p>Assumes that a BMP (two-byte unicode) string value is at the front of
the data stored in the variable named <i class="arg">data_var</i>, and stores it
into the variable named by <i class="arg">string_var</i>, converting it into a
proper Tcl string. Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands.</p></dd>
<dt><a name="37"><b class="cmd">::asn::asnGetUTF8String</b> <i class="arg">data_var</i> <i class="arg">string_var</i></a></dt>
<dd><p>Assumes that a UTF8 string value is at the front of the data stored in
the variable named <i class="arg">data_var</i>, and stores it into the variable
named by <i class="arg">string_var</i>, converting it into a proper Tcl string.
Additionally removes all bytes associated with the value from the data
for further processing by the following decoder commands.</p></dd>
<dt><a name="38"><b class="cmd">::asn::asnGetUTCTime</b> <i class="arg">data_var</i> <i class="arg">utc_var</i></a></dt>
<dd><p>Assumes that a UTC time value is at the front of the data stored in the
variable named <i class="arg">data_var</i>, and stores it into the variable named
by <i class="arg">utc_var</i>. The UTC time value is stored as a string, which has to
be decoded with the usual clock scan commands.
Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands.</p></dd>
<dt><a name="39"><b class="cmd">::asn::asnGetBitString</b> <i class="arg">data_var</i> <i class="arg">bits_var</i></a></dt>
<dd><p>Assumes that a bit string value is at the front of the data stored in the
variable named <i class="arg">data_var</i>, and stores it into the variable named
by <i class="arg">bits_var</i> as a string containing only 0 and 1.
Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands.</p></dd>
<dt><a name="40"><b class="cmd">::asn::asnGetObjectIdentifier</b> <i class="arg">data_var</i> <i class="arg">oid_var</i></a></dt>
<dd><p>Assumes that a object identifier (OID) value is at the front of the data
stored in the variable named <i class="arg">data_var</i>, and stores it into the variable
named by <i class="arg">oid_var</i> as a list of integers.
Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands.</p></dd>
<dt><a name="41"><b class="cmd">::asn::asnGetBoolean</b> <i class="arg">data_var</i> <i class="arg">bool_var</i></a></dt>
<dd><p>Assumes that a boolean value is at the front of the data stored in the
variable named <i class="arg">data_var</i>, and stores it into the variable named
by <i class="arg">bool_var</i>. Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands.</p></dd>
<dt><a name="42"><b class="cmd">::asn::asnGetNull</b> <i class="arg">data_var</i></a></dt>
<dd><p>Assumes that a NULL value is at the front of the data stored in the
variable named <i class="arg">data_var</i> and removes the bytes used to encode it
from the data.</p></dd>
<dt><a name="43"><b class="cmd">::asn::asnGetSequence</b> <i class="arg">data_var</i> <i class="arg">sequence_var</i></a></dt>
<dd><p>Assumes that an ASN sequence is at the front of the data stored in the
variable named <i class="arg">data_var</i>, and stores it into the variable named
by <i class="arg">sequence_var</i>. Additionally removes all bytes associated with
the value from the data for further processing by the following
decoder commands.</p>
<p>The data in <i class="arg">sequence_var</i> is encoded binary and has to be
further decoded according to the definition of the sequence, using the
decoder commands here.</p></dd>
<dt><a name="44"><b class="cmd">::asn::asnGetSet</b> <i class="arg">data_var</i> <i class="arg">set_var</i></a></dt>
<dd><p>Assumes that an ASN set is at the front of the data stored in the
variable named <i class="arg">data_var</i>, and stores it into the variable named
by <i class="arg">set_var</i>. Additionally removes all bytes associated with the
value from the data for further processing by the following decoder
commands.</p>
<p>The data in <i class="arg">set_var</i> is encoded binary and has to be further
decoded according to the definition of the set, using the decoder
commands here.</p></dd>
<dt><a name="45"><b class="cmd">::asn::asnGetApplication</b> <i class="arg">data_var</i> <i class="arg">appNumber_var</i> <span class="opt">?<i class="arg">content_var</i>?</span> <span class="opt">?<i class="arg">encodingType_var</i>?</span></a></dt>
<dd><p>Assumes that an ASN application construct is at the front of the data
stored in the variable named <i class="arg">data_var</i>, and stores its id into
the variable named by <i class="arg">appNumber_var</i>. Additionally removes all
bytes associated with the value from the data for further processing
by the following decoder commands.
If a <i class="arg">content_var</i> is specified, then the command places all data
associated with it into the named variable, in the binary form which
can be processed using the decoder commands of this package.
If a <i class="arg">encodingType_var</i> is specified, then that var is set to 1 if
the encoding is constructed and 0 if it is primitive.</p>
<p>Otherwise it is the responsibility of the caller to decode the
remainder of the application construct based on the id retrieved by
this command, using the decoder commands of this package.</p></dd>
<dt><a name="46"><b class="cmd">::asn::asnGetContext</b> <i class="arg">data_var</i> <i class="arg">contextNumber_var</i> <span class="opt">?<i class="arg">content_var</i>?</span> <span class="opt">?<i class="arg">encodingType_var</i>?</span></a></dt>
<dd><p>Assumes that an ASN context tag construct is at the front of the data
stored in the variable named <i class="arg">data_var</i>, and stores its id into
the variable named by <i class="arg">contextNumber_var</i>. Additionally removes all
bytes associated with the value from the data for further processing
by the following decoder commands.
If a <i class="arg">content_var</i> is specified, then the command places all data
associated with it into the named variable, in the binary form which
can be processed using the decoder commands of this package.
If a <i class="arg">encodingType_var</i> is specified, then that var is set to 1 if
the encoding is constructed and 0 if it is primitive.</p>
<p>Otherwise it is the responsibility of the caller to decode the
remainder of the construct based on the id retrieved by this command,
using the decoder commands of this package.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">HANDLING TAGS</a></h3>
<p>Working with ASN.1 you often need to decode tagged values, which use a tag thats different
from the universal tag for a type. In those cases you have to replace the tag with the universal tag
used for the type, to decode the value.
To decode a tagged value use the <b class="cmd">::asn::asnRetag</b> to change the tag to the appropriate type
to use one of the decoders for primitive values.
To help with this the module contains three functions:</p>
<dl class="doctools_definitions">
<dt><a name="47"><b class="cmd">::asn::asnPeekTag</b> <i class="arg">data_var</i> <i class="arg">tag_var</i> <i class="arg">tagtype_var</i> <i class="arg">constr_var</i></a></dt>
<dd><p>The <b class="cmd">::asn::asnPeekTag</b> command can be used to take a peek at the data and decode the tag value, without
removing it from the data. The <i class="arg">tag_var</i> gets set to the tag number, while the <i class="arg">tagtype_var</i> gets set
to the class of the tag. (Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE). The <i class="arg">constr_var</i> is set to 1 if the
tag is for a constructed value, and to 0 for not constructed. It returns the length of the tag.</p></dd>
<dt><a name="48"><b class="cmd">::asn::asnTag</b> <i class="arg">tagnumber</i> <span class="opt">?<i class="arg">class</i>?</span> <span class="opt">?<i class="arg">tagstyle</i>?</span></a></dt>
<dd><p>The <b class="cmd">::asn::asnTag</b> can be used to create a tag value. The <i class="arg">tagnumber</i> gives the number of the tag, while
the <i class="arg">class</i> gives one of the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The class may be abbreviated to just the first letter (U,C,A,P),
default is UNIVERSAL.
The <i class="arg">tagstyle</i> is either C for Constructed encoding, or P for primitve encoding. It defaults to P. You can also use 1 instead of C and
0 instead of P for direct use of the values returned by <b class="cmd">::asn::asnPeekTag</b>.</p></dd>
<dt><a name="49"><b class="cmd">::asn::asnRetag</b> <i class="arg">data_var</i> <i class="arg">newTag</i></a></dt>
<dd><p>Replaces the tag in front of the data in <i class="arg">data_var</i> with <i class="arg">newTag</i>. The new Tag can be created using the <b class="cmd">::asn::asnTag</b> command.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>Examples for the usage of this package can be found in the
implementation of package <b class="package"><a href="../ldap/ldap.html">ldap</a></b>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>asn</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#asn">asn</a>, <a href="../../../../index.html#ber">ber</a>, <a href="../../../../index.html#cer">cer</a>, <a href="../../../../index.html#der">der</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#protocol">protocol</a>, <a href="../../../../index.html#x_208">x.208</a>, <a href="../../../../index.html#x_209">x.209</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Andreas Kupries <[email protected]><br>
Copyright © 2004 Jochen Loewer <[email protected]><br>
Copyright © 2004-2011 Michael Schlenker <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base32/base32.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
<div class='fossil-doc' data-title='base32 - Base32 encoding'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">base32(n) 0.1 tcllib "Base32 encoding"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>base32 - base32 standard encoding</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Code map</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">base32::core <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">base32 <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::base32::encode</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::base32::decode</b> <i class="arg">estring</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for encoding and decoding of strings
into and out of the standard base32 encoding as specified in RFC 3548.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::base32::encode</b> <i class="arg">string</i></a></dt>
<dd><p>This command encodes the given <i class="arg">string</i> in base32 and returns the
encoded string as its result. The result may be padded with the
character <b class="const">=</b> to signal a partial encoding at the end of the
input string.</p></dd>
<dt><a name="2"><b class="cmd">::base32::decode</b> <i class="arg">estring</i></a></dt>
<dd><p>This commands takes the <i class="arg">estring</i> and decodes it under the
assumption that it is a valid base32 encoded string. The result of the
decoding is returned as the result of the command.</p>
<p>Note that while the encoder will generate only uppercase characters
this decoder accepts input in lowercase as well.</p>
<p>The command will always throw an error whenever encountering
conditions which signal some type of bogus input, namely if</p>
<ol class="doctools_enumerated">
<li><p>the input contains characters which are not valid output of a base32 encoder,</p></li>
<li><p>the length of the input is not a multiple of eight,</p></li>
<li><p>padding appears not at the end of input, but in the middle,</p></li>
<li><p>the padding has not of length six, four, three, or one characters,</p></li>
</ol></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Code map</a></h2>
<p>The code map used to convert 5-bit sequences is shown below, with the
numeric id of the bit sequences to the left and the character used to
encode it to the right. It should be noted that the characters "0" and
"1" are not used by the encoding. This is done as these characters can
be easily confused with "O", "o" and "l" (L).</p>
<pre class="doctools_example">
0 A 9 J 18 S 27 3
1 B 10 K 19 T 28 4
2 C 11 L 20 U 29 5
3 D 12 M 21 V 30 6
4 E 13 N 22 W 31 7
5 F 14 O 23 X
6 G 15 P 24 Y
7 H 16 Q 25 Z
8 I 17 R 26 2
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base32</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#base32">base32</a>, <a href="../../../../index.html#rfc3548">rfc3548</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Public domain</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base32/base32core.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<div class='fossil-doc' data-title='base32::core - Base32 encoding'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">base32::core(n) 0.1 tcllib "Base32 encoding"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>base32::core - Expanding basic base32 maps</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">base32::core <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::base32::core::define</b> <i class="arg">map</i> <i class="arg">forwvar</i> <i class="arg">backwvar</i> <i class="arg">ivar</i></a></li>
<li><a href="#2"><b class="cmd">::base32::core::valid</b> <i class="arg">string</i> <i class="arg">pattern</i> <i class="arg">mvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides generic commands for the construction of full
base32 mappings from a basic mapping listing just the codes and
associated characters. The full mappings, regular and inverse, created
here map to and from bit sequences, and also handle the partial
mappings at the end of a string.</p>
<p>This is in essence an internal package to be used by implementors of a
base32 en- and decoder. A regular user has no need of this package at
all.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::base32::core::define</b> <i class="arg">map</i> <i class="arg">forwvar</i> <i class="arg">backwvar</i> <i class="arg">ivar</i></a></dt>
<dd><p>This command computes full forward and backward (inverse) mappings
from the basic <i class="arg">map</i> and stores them in the variables named by
<i class="arg">forwvar</i> and <i class="arg">backwvar</i> resp. It also constructs a regexp
pattern for the detection of invalid characters in supposedly base32
encoded input and stores it in the variable named by <i class="arg">ivar</i>.</p></dd>
<dt><a name="2"><b class="cmd">::base32::core::valid</b> <i class="arg">string</i> <i class="arg">pattern</i> <i class="arg">mvar</i></a></dt>
<dd><p>This command checks if the input <i class="arg">string</i> is a valid base32
encoded string, based on the <i class="arg">pattern</i> of invalid characters as
generated by <b class="cmd">::base32::core::define</b>, and some other general
rules.</p>
<p>The result of the command is a boolean flag. Its value is <b class="const">True</b>
for a valid <i class="arg">string</i>, and <b class="const">False</b> otherwise. In the latter
case an error message describing the problem with the input is stored
into the variable named by <i class="arg">mvar</i>. The variable is not touched if
the input was found to be valid.</p>
<p>The rules checked by the command, beyond rejection of bad characters,
are:</p>
<ol class="doctools_enumerated">
<li><p>The length of the input is not a multiple of eight,</p></li>
<li><p>The padding appears not at the end of input, but in the middle,</p></li>
<li><p>The padding has not of length six, four, three, or one characters,</p></li>
</ol></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base32</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#base32">base32</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Public domain</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base32/base32hex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<div class='fossil-doc' data-title='base32::hex - Base32 encoding'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">base32::hex(n) 0.1 tcllib "Base32 encoding"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>base32::hex - base32 extended hex encoding</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Code map</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">base32::core <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">base32::hex <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::base32::hex::encode</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::base32::hex::decode</b> <i class="arg">estring</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for encoding and decoding of strings
into and out of the extended hex base32 encoding as specified in the
RFC 3548bis draft.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::base32::hex::encode</b> <i class="arg">string</i></a></dt>
<dd><p>This command encodes the given <i class="arg">string</i> in extended hex base32 and
returns the encoded string as its result. The result may be padded
with the character <b class="const">=</b> to signal a partial encoding at the end
of the input string.</p></dd>
<dt><a name="2"><b class="cmd">::base32::hex::decode</b> <i class="arg">estring</i></a></dt>
<dd><p>This commands takes the <i class="arg">estring</i> and decodes it under the
assumption that it is a valid extended hex base32 encoded string. The
result of the decoding is returned as the result of the command.</p>
<p>Note that while the encoder will generate only uppercase characters
this decoder accepts input in lowercase as well.</p>
<p>The command will always throw an error whenever encountering
conditions which signal some type of bogus input, namely if</p>
<ol class="doctools_enumerated">
<li><p>the input contains characters which are not valid output
of a extended hex base32 encoder,</p></li>
<li><p>the length of the input is not a multiple of eight,</p></li>
<li><p>padding appears not at the end of input, but in the middle,</p></li>
<li><p>the padding has not of length six, four, three, or one characters,</p></li>
</ol></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Code map</a></h2>
<p>The code map used to convert 5-bit sequences is shown below, with the
numeric id of the bit sequences to the left and the character used to
encode it to the right. The important feature of the extended hex
mapping is that the first 16 codes map to the digits and hex
characters.</p>
<pre class="doctools_example">
0 0 9 9 18 I 27 R
1 1 10 A 19 J 28 S
2 2 11 B 20 K 29 T
3 3 12 C 21 L 30 U
4 4 13 D 22 M 31 V
5 5 14 E 23 N
6 6 15 F 24 O
7 7 16 G 25 P
8 8 17 H 26 Q
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base32</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#base32">base32</a>, <a href="../../../../index.html#hex">hex</a>, <a href="../../../../index.html#rfc3548">rfc3548</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Public domain</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base64/ascii85.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
<div class='fossil-doc' data-title='ascii85 - Text encoding & decoding binary data'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ascii85(n) 1.0 tcllib "Text encoding & decoding binary data"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ascii85 - ascii85-encode/decode binary data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">ascii85 <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ascii85::encode</b> <span class="opt">?<b class="option">-maxlen</b> <i class="arg">maxlen</i>?</span> <span class="opt">?<b class="option">-wrapchar</b> <i class="arg">wrapchar</i>?</span> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::ascii85::decode</b> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides procedures to encode binary data into ascii85 and back.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ascii85::encode</b> <span class="opt">?<b class="option">-maxlen</b> <i class="arg">maxlen</i>?</span> <span class="opt">?<b class="option">-wrapchar</b> <i class="arg">wrapchar</i>?</span> <i class="arg">string</i></a></dt>
<dd><p>Ascii85 encodes the given binary <i class="arg">string</i> and returns the encoded
result. Inserts the character <i class="arg">wrapchar</i> every <i class="arg">maxlen</i>
characters of output. <i class="arg">wrapchar</i> defaults to newline. <i class="arg">maxlen</i>
defaults to <b class="const">76</b>.</p>
<p><em>Note well</em>: If your string is not simple ascii you should fix
the string encoding before doing ascii85 encoding. See the examples.</p>
<p>The command will throw an error for negative values of <i class="arg">maxlen</i>,
or if <i class="arg">maxlen</i> is not an integer number.</p></dd>
<dt><a name="2"><b class="cmd">::ascii85::decode</b> <i class="arg">string</i></a></dt>
<dd><p>Ascii85 decodes the given <i class="arg">string</i> and returns the binary data.
The decoder ignores whitespace in the string, as well as tabs and
newlines.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<pre class="doctools_example">
% ascii85::encode "Hello, world"
87cURD_*#TDfTZ)
</pre>
<pre class="doctools_example">
% ascii85::encode [string repeat xyz 24]
G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G
^4U[H$X^\H?a^]
% ascii85::encode -wrapchar "" [string repeat xyz 24]
G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]
</pre>
<pre class="doctools_example">
# NOTE: ascii85 encodes BINARY strings.
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [ascii85::encode $chemical]
6fN]R8E,5Pidu\UiduhZidua
% set caffeine [encoding convertfrom utf-8 [ascii85::decode $encoded]]
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://en.wikipedia.org/wiki/Ascii85">http://en.wikipedia.org/wiki/Ascii85</a></p></li>
<li><p>Postscript Language Reference Manual, 3rd Edition, page 131.
<a href="http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf">http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf</a></p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base64</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ascii85">ascii85</a>, <a href="../../../../index.html#encoding">encoding</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010, Emiliano Gavilán</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base64/base64.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
<div class='fossil-doc' data-title='base64 - Text encoding & decoding binary data'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">base64(n) 2.4.2 tcllib "Text encoding & decoding binary data"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>base64 - base64-encode/decode binary data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">base64 <span class="opt">?2.4.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::base64::encode</b> <span class="opt">?<b class="option">-maxlen</b> <i class="arg">maxlen</i>?</span> <span class="opt">?<b class="option">-wrapchar</b> <i class="arg">wrapchar</i>?</span> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::base64::decode</b> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides procedures to encode binary data into base64 and back.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::base64::encode</b> <span class="opt">?<b class="option">-maxlen</b> <i class="arg">maxlen</i>?</span> <span class="opt">?<b class="option">-wrapchar</b> <i class="arg">wrapchar</i>?</span> <i class="arg">string</i></a></dt>
<dd><p>Base64 encodes the given binary <i class="arg">string</i> and returns the encoded
result. Inserts the character <i class="arg">wrapchar</i> every <i class="arg">maxlen</i>
characters of output. <i class="arg">wrapchar</i> defaults to newline. <i class="arg">maxlen</i>
defaults to <b class="const">76</b>.</p>
<p><em>Note</em> that if <i class="arg">maxlen</i> is set to <b class="const">0</b>, the
output will not be wrapped at all.</p>
<p><em>Note well</em>: If your string is not simple ascii you should fix
the string encoding before doing base64 encoding. See the examples.</p>
<p>The command will throw an error for negative values of <i class="arg">maxlen</i>,
or if <i class="arg">maxlen</i> is not an integer number.</p></dd>
<dt><a name="2"><b class="cmd">::base64::decode</b> <i class="arg">string</i></a></dt>
<dd><p>Base64 decodes the given <i class="arg">string</i> and returns the binary data.
The decoder ignores whitespace in the string.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<pre class="doctools_example">
% base64::encode "Hello, world"
SGVsbG8sIHdvcmxk
</pre>
<pre class="doctools_example">
% base64::encode [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
eHl6eHl6eHl6
% base64::encode -wrapchar "" [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
</pre>
<pre class="doctools_example">
# NOTE: base64 encodes BINARY strings.
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [base64::encode $chemical]
Q+KCiEjigoHigoBO4oKET+KCgg==
% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base64</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#base64">base64</a>, <a href="../../../../index.html#encoding">encoding</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2000, Eric Melski<br>
Copyright © 2001, Miguel Sofer</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base64/uuencode.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<div class='fossil-doc' data-title='uuencode - Text encoding & decoding binary data'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">uuencode(n) 1.1.4 tcllib "Text encoding & decoding binary data"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>uuencode - UU-encode/decode binary data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OPTIONS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">uuencode <span class="opt">?1.1.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::uuencode::encode</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::uuencode::decode</b> <i class="arg">string</i></a></li>
<li><a href="#3"><b class="cmd">::uuencode::uuencode</b> <span class="opt">?<b class="option">-name</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-mode</b> <i class="arg">octal</i>?</span> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></li>
<li><a href="#4"><b class="cmd">::uuencode::uudecode</b> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a Tcl-only implementation of the
<b class="syscmd">uuencode(1)</b> and <b class="syscmd">uudecode(1)</b> commands. This encoding
packs binary data into printable ASCII characters.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::uuencode::encode</b> <i class="arg">string</i></a></dt>
<dd><p>returns the uuencoded data. This will encode all the data passed in
even if this is longer than the uuencode maximum line length. If the
number of input bytes is not a multiple of 3 then additional 0 bytes
are added to pad the string.</p></dd>
<dt><a name="2"><b class="cmd">::uuencode::decode</b> <i class="arg">string</i></a></dt>
<dd><p>Decodes the given encoded data. This will return any padding
characters as well and it is the callers responsibility to deal with
handling the actual length of the encoded data. (see uuencode).</p></dd>
<dt><a name="3"><b class="cmd">::uuencode::uuencode</b> <span class="opt">?<b class="option">-name</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-mode</b> <i class="arg">octal</i>?</span> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></dt>
<dd></dd>
<dt><a name="4"><b class="cmd">::uuencode::uudecode</b> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></dt>
<dd><p>UUDecode a file or block of data. A file may contain more than one
embedded file so the result is a list where each element is a three
element list of filename, mode value and data.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt>-filename name</dt>
<dd><p>Cause the uuencode or uudecode commands to read their data from the
named file rather that taking a string parameter.</p></dd>
<dt>-name string</dt>
<dd><p>The uuencoded data header line contains the suggested file name to be
used when unpacking the data. Use this option to change this from the
default of "data.dat".</p></dd>
<dt>-mode octal</dt>
<dd><p>The uuencoded data header line contains a suggested permissions bit
pattern expressed as an octal string. To change the default of 0644
you can set this option. For instance, 0755 would be suitable for an
executable. See <b class="syscmd">chmod(1)</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
% set d [uuencode::encode "Hello World!"]
2&5L;&\\@5V]R;&0A
</pre>
<pre class="doctools_example">
% uuencode::uudecode $d
Hello World!
</pre>
<pre class="doctools_example">
% set d [uuencode::uuencode -name hello.txt "Hello World"]
begin 644 hello.txt
+2&5L;&\@5V]R;&0`
`
end
</pre>
<pre class="doctools_example">
% uuencode::uudecode $d
{hello.txt 644 {Hello World}}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base64</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#encoding">encoding</a>, <a href="../../../../index.html#uuencode">uuencode</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/base64/yencode.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<div class='fossil-doc' data-title='yencode - Text encoding & decoding binary data'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">yencode(n) 1.1.2 tcllib "Text encoding & decoding binary data"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>yencode - Y-encode/decode binary data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OPTIONS</a></li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">yencode <span class="opt">?1.1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::yencode::encode</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::yencode::decode</b> <i class="arg">string</i></a></li>
<li><a href="#3"><b class="cmd">::yencode::yencode</b> <span class="opt">?<b class="option">-name</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-line</b> <i class="arg">integer</i>?</span> <span class="opt">?<b class="option">-crc32</b> <i class="arg">boolean</i>?</span> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></li>
<li><a href="#4"><b class="cmd">::yencode::ydecode</b> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a Tcl-only implementation of the yEnc file
encoding. This is a recently introduced method of encoding binary
files for transmission through Usenet. This encoding packs binary data
into a format that requires an 8-bit clean transmission layer but that
escapes characters special to the <i class="term"><a href="../../../../index.html#nntp">NNTP</a></i> posting protocols. See
<a href="http://www.yenc.org/">http://www.yenc.org/</a> for details concerning the algorithm.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::yencode::encode</b> <i class="arg">string</i></a></dt>
<dd><p>returns the yEnc encoded data.</p></dd>
<dt><a name="2"><b class="cmd">::yencode::decode</b> <i class="arg">string</i></a></dt>
<dd><p>Decodes the given yEnc encoded data.</p></dd>
<dt><a name="3"><b class="cmd">::yencode::yencode</b> <span class="opt">?<b class="option">-name</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-line</b> <i class="arg">integer</i>?</span> <span class="opt">?<b class="option">-crc32</b> <i class="arg">boolean</i>?</span> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></dt>
<dd><p>Encode a file or block of data.</p></dd>
<dt><a name="4"><b class="cmd">::yencode::ydecode</b> (<b class="option">-file</b> <i class="arg">filename</i> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i>)</a></dt>
<dd><p>Decode a file or block of data. A file may contain more than one
embedded file so the result is a list where each element is a three
element list of filename, file size and data.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt>-filename name</dt>
<dd><p>Cause the yencode or ydecode commands to read their data from the
named file rather that taking a string parameter.</p></dd>
<dt>-name string</dt>
<dd><p>The encoded data header line contains the suggested file name to be
used when unpacking the data. Use this option to change this from the
default of "data.dat".</p></dd>
<dt>-line integer</dt>
<dd><p>The yencoded data header line contains records the line length used
during the encoding. Use this option to select a line length other
that the default of 128. Note that NNTP imposes a 1000 character line
length limit and some gateways may have trouble with more than 255
characters per line.</p></dd>
<dt>-crc32 boolean</dt>
<dd><p>The yEnc specification recommends the inclusion of a cyclic redundancy
check value in the footer. Use this option to change the default from
<i class="arg">true</i> to <i class="arg">false</i>.</p></dd>
</dl>
<pre class="doctools_example">
% set d [yencode::yencode -file testfile.txt]
=ybegin line=128 size=584 name=testfile.txt
-o- data not shown -o-
=yend size=584 crc32=ded29f4f
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://www.yenc.org/yenc-draft.1.3.txt">http://www.yenc.org/yenc-draft.1.3.txt</a></p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>base64</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#encoding">encoding</a>, <a href="../../../../index.html#yenc">yEnc</a>, <a href="../../../../index.html#ydecode">ydecode</a>, <a href="../../../../index.html#yencode">yencode</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bee/bee.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
|
<div class='fossil-doc' data-title='bee - BitTorrent'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bee(n) 0.1 tcllib "BitTorrent"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bee - BitTorrent Serialization Format Encoder/Decoder</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">ENCODER</a></li>
<li class="doctools_subsection"><a href="#subsection2">DECODER</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">FORMAT DEFINITION</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">bee <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::bee::encodeString</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::bee::encodeNumber</b> <i class="arg">integer</i></a></li>
<li><a href="#3"><b class="cmd">::bee::encodeListArgs</b> <i class="arg">value</i>...</a></li>
<li><a href="#4"><b class="cmd">::bee::encodeList</b> <i class="arg">list</i></a></li>
<li><a href="#5"><b class="cmd">::bee::encodeDictArgs</b> <i class="arg">key</i> <i class="arg">value</i>...</a></li>
<li><a href="#6"><b class="cmd">::bee::encodeDict</b> <i class="arg">dict</i></a></li>
<li><a href="#7"><b class="cmd">::bee::decode</b> <i class="arg">string</i> <span class="opt">?<i class="arg">endvar</i>?</span> <span class="opt">?<i class="arg">start</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::bee::decodeIndices</b> <i class="arg">string</i> <span class="opt">?<i class="arg">endvar</i>?</span> <span class="opt">?<i class="arg">start</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::bee::decodeChannel</b> <i class="arg">chan</i> <b class="option">-command</b> <i class="arg">cmdprefix</i> <span class="opt">?<b class="option">-exact</b>?</span> <span class="opt">?<b class="option">-prefix</b> <i class="arg">data</i>?</span></a></li>
<li><a href="#10"><b class="cmd">cmdprefix</b> <b class="method">eof</b> <i class="arg">token</i></a></li>
<li><a href="#11"><b class="cmd">cmdprefix</b> <b class="method">error</b> <i class="arg">token</i> <i class="arg">message</i></a></li>
<li><a href="#12"><b class="cmd">cmdprefix</b> <b class="method">value</b> <i class="arg">token</i> <i class="arg">value</i></a></li>
<li><a href="#13"><b class="cmd">::bee::decodeCancel</b> <i class="arg">token</i></a></li>
<li><a href="#14"><b class="cmd">::bee::decodePush</b> <i class="arg">token</i> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">bee</b> package provides de- and encoder commands for data
in bencoding (speak 'bee'), the serialization format for data and
messages used by the BitTorrent protocol.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">ENCODER</a></h3>
<p>The package provides one encoder command for each of the basic forms,
and two commands per container, one taking a proper tcl data structure
to encode in the container, the other taking the same information as
several arguments.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::bee::encodeString</b> <i class="arg">string</i></a></dt>
<dd><p>Returns the bee-encoding of the <i class="arg">string</i>.</p></dd>
<dt><a name="2"><b class="cmd">::bee::encodeNumber</b> <i class="arg">integer</i></a></dt>
<dd><p>Returns the bee-encoding of the <i class="arg">integer</i> number.</p></dd>
<dt><a name="3"><b class="cmd">::bee::encodeListArgs</b> <i class="arg">value</i>...</a></dt>
<dd><p>Takes zero or more bee-encoded values and returns the bee-encoding of
their list.</p></dd>
<dt><a name="4"><b class="cmd">::bee::encodeList</b> <i class="arg">list</i></a></dt>
<dd><p>Takes a list of bee-encoded values and returns the bee-encoding of the
list.</p></dd>
<dt><a name="5"><b class="cmd">::bee::encodeDictArgs</b> <i class="arg">key</i> <i class="arg">value</i>...</a></dt>
<dd><p>Takes zero or more pairs of keys and values and returns the
bee-encoding of the dictionary they form. The values are expected to
be already bee-encoded, but the keys must not be. Their encoding will
be done by the command itself.</p></dd>
<dt><a name="6"><b class="cmd">::bee::encodeDict</b> <i class="arg">dict</i></a></dt>
<dd><p>Takes a dictionary list of string keys and bee-encoded values and
returns the bee-encoding of the list. Note that the keys in the input
must not be bee-encoded already. This will be done by the command
itself.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">DECODER</a></h3>
<p>The package provides two main decoder commands, one for decoding a
string expected to contain a complete data structure, the other for
the incremental decoding of bee-values arriving on a channel. The
latter command is asynchronous and provides the completed decoded
values to the user through a command callback.</p>
<dl class="doctools_definitions">
<dt><a name="7"><b class="cmd">::bee::decode</b> <i class="arg">string</i> <span class="opt">?<i class="arg">endvar</i>?</span> <span class="opt">?<i class="arg">start</i>?</span></a></dt>
<dd><p>Takes the bee-encoding in the string and returns one decoded value. In
the case of this being a container all contained values are decoded
recursively as well and the result is a properly nested tcl list
and/or dictionary.</p>
<p>If the optional <i class="arg">endvar</i> is set then it is the name of a variable
to store the index of the first character <em>after</em> the decoded
value into. In other words, if the string contains more than one value
then <i class="arg">endvar</i> can be used to obtain the position of the bee-value
after the bee-value currently decoded. together with <i class="arg">start</i>, see
below, it is possible to iterate over the string to extract all
contained values.</p>
<p>The optional <i class="arg">start</i> index defaults to <b class="const">0</b>, i.e. the
beginning of the string. It is the index of the first character of the
bee-encoded value to extract.</p></dd>
<dt><a name="8"><b class="cmd">::bee::decodeIndices</b> <i class="arg">string</i> <span class="opt">?<i class="arg">endvar</i>?</span> <span class="opt">?<i class="arg">start</i>?</span></a></dt>
<dd><p>Takes the same arguments as <b class="cmd">::bee::decode</b> and returns the same
information in <i class="arg">endvar</i>. The result however is different. Instead
of the tcl value contained in the <i class="arg">string</i> it returns a list
describing the value with respect to type and location (indices for
the first and last character of the bee-value). In case of a container
the structure also contains the same information for all the embedded
values.</p>
<p>Formally the results for the various types of bee-values are:</p>
<dl class="doctools_definitions">
<dt>string</dt>
<dd><p>A list containing three elements:</p>
<ul class="doctools_itemized">
<li><p>The constant string <b class="const">string</b>, denoting the type of the value.</p></li>
<li><p>An integer number greater than or equal to zero. This is the index of
the first character of the bee-value in the input <i class="arg">string</i>.</p></li>
<li><p>An integer number greater than or equal to zero. This is the index of
the last character of the bee-value in the input <i class="arg">string</i>.</p></li>
</ul>
<p><em>Note</em> that this information is present in the results for all
four types of bee-values, with only the first element changing
according to the type of the value.</p></dd>
<dt>integer</dt>
<dd><p>The result is like for strings, except that the type element contains
the constant string <b class="const">integer</b>.</p></dd>
<dt>list</dt>
<dd><p>The result is like before, with two exceptions: One, the type element
contains the constant string <b class="const">list</b>. And two, the result
actually contains four elements. The last element is new, and contains
the index data as described here for all elements of the bee-list.</p></dd>
<dt>dictionary</dt>
<dd><p>The result is like for strings, except that the type element contains
the constant string <b class="const">dict</b>. A fourth element is present as well,
with a slightly different structure than for lists. The element is a
dictionary mapping from the strings keys of the bee-dictionary to a
list containing two elements. The first of them is the index
information for the key, and the second element is the index
information for the value the key maps to. This structure is the only
which contains not only index data, but actual values from the
bee-string. While the index information of the keys is unique enough,
i.e. serviceable as keys, they are not easy to navigate when trying to
find particular element. Using the actual keys makes this much easier.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::bee::decodeChannel</b> <i class="arg">chan</i> <b class="option">-command</b> <i class="arg">cmdprefix</i> <span class="opt">?<b class="option">-exact</b>?</span> <span class="opt">?<b class="option">-prefix</b> <i class="arg">data</i>?</span></a></dt>
<dd><p>The command creates a decoder for a series of bee-values arriving on
the channel <i class="arg">chan</i> and returns its handle. This handle can be used
to remove the decoder again.
Setting up another bee decoder on <i class="arg">chan</i> while a bee decoder is
still active will fail with an error message.</p>
<dl class="doctools_definitions">
<dt><b class="option">-command</b></dt>
<dd><p>The command prefix <i class="arg">cmdprefix</i> specified by the <em>required</em>
option <b class="option">-command</b> is used to report extracted values and
exceptional situations (error, and EOF on the channel).
The callback will be executed at the global level of the interpreter,
with two or three arguments. The exact call signatures are</p>
<dl class="doctools_definitions">
<dt><a name="10"><b class="cmd">cmdprefix</b> <b class="method">eof</b> <i class="arg">token</i></a></dt>
<dd><p>The decoder has reached eof on the channel <i class="arg">chan</i>. No further
invocations of the callback will be made after this. The channel has
already been closed at the time of the call, and the <i class="arg">token</i> is
not valid anymore as well.</p></dd>
<dt><a name="11"><b class="cmd">cmdprefix</b> <b class="method">error</b> <i class="arg">token</i> <i class="arg">message</i></a></dt>
<dd><p>The decoder encountered an error, which is not eof. For example a
malformed bee-value. The <i class="arg">message</i> provides details about the
error. The decoder token is in the same state as for eof,
i.e. invalid. The channel however is kept open.</p></dd>
<dt><a name="12"><b class="cmd">cmdprefix</b> <b class="method">value</b> <i class="arg">token</i> <i class="arg">value</i></a></dt>
<dd><p>The decoder received and successfully decoded a bee-value.
The format of the equivalent tcl <i class="arg">value</i> is the same as returned
by <b class="cmd">::bee::decode</b>. The channel is still open and the decoder
token is valid. This means that the callback is able to remove the
decoder.</p></dd>
</dl></dd>
<dt><b class="option">-exact</b></dt>
<dd><p>By default the decoder assumes that the remainder of the data in the
channel consists only of bee-values, and reads as much as possible per
event, without regard for boundaries between bee-values. This means
that if the the input contains non-bee data after a series of
bee-value the beginning of that data may be lost because it was
already read by the decoder, but not processed.</p>
<p>The <b class="option">-exact</b> was made for this situation. When specified the
decoder will take care to not read any characters behind the currently
processed bee-value, so that any non-bee data is kept in the channel
for further processing after removal of the decoder.</p></dd>
<dt><b class="option">-prefix</b></dt>
<dd><p>If this option is specified its value is assumed to be the beginning
of the bee-value and used to initialize the internal decoder
buffer. This feature is required if the creator of the decoder used
data from the channel to determine if it should create the decoder or
not. Without the option this data would be lost to the decoding.</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::bee::decodeCancel</b> <i class="arg">token</i></a></dt>
<dd><p>This command cancels the decoder set up by <b class="cmd">::bee::decodeChannel</b>
and represented by the handle <i class="arg">token</i>.</p></dd>
<dt><a name="14"><b class="cmd">::bee::decodePush</b> <i class="arg">token</i> <i class="arg">string</i></a></dt>
<dd><p>This command appends the <i class="arg">string</i> to the internal decoder
buffer. It is the runtime equivalent of the option <b class="option">-prefix</b> of
<b class="cmd">::bee::decodeChannel</b>. Use it to push data back into the decoder
when the <b class="method">value</b> callback used data from the channel to
determine if it should decode another bee-value or not.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FORMAT DEFINITION</a></h2>
<p>Data in the bee serialization format is constructed from two basic
forms, and two container forms. The basic forms are strings and
integer numbers, and the containers are lists and dictionaries.</p>
<dl class="doctools_definitions">
<dt>String <i class="arg">S</i></dt>
<dd><p>A string <i class="arg">S</i> of length <i class="arg">L</i> is encoded by the string
"<i class="arg">L</i><b class="const">:</b><i class="arg">S</i>", where the length is written out in textual
form.</p></dd>
<dt>Integer <i class="arg">N</i></dt>
<dd><p>An integer number <i class="arg">N</i> is encoded by the string
"<b class="const">i</b><i class="arg">N</i><b class="const">e</b>".</p></dd>
<dt>List <i class="arg">v1</i> ... <i class="arg">vn</i></dt>
<dd><p>A list of the values <i class="arg">v1</i> to <i class="arg">vn</i> is encoded by the string
"<b class="const">l</b><i class="arg">BV1</i>...<i class="arg">BVn</i><b class="const">e</b>"
where "BV<b class="variable">i</b>" is the bee-encoding of the value "v<b class="variable">i</b>".</p></dd>
<dt>Dict <i class="arg">k1</i> -> <i class="arg">v1</i> ...</dt>
<dd><p>A dictionary mapping the string key <i class="arg">k</i><b class="variable">i</b> to the value
<i class="arg">v</i><b class="variable">i</b>, for <b class="variable">i</b> in <b class="const">1</b> ... <b class="variable">n</b>
is encoded by the string
"<b class="const">d</b><i class="arg">BK</i><b class="variable">i</b><i class="arg">BV</i><b class="variable">i</b>...<b class="const">e</b>"
for i in <b class="const">1</b> ... <b class="variable">n</b>, where "BK<b class="variable">i</b>" is the bee-encoding
of the key string "k<b class="variable">i</b>". and "BV<b class="variable">i</b>" is the bee-encoding of
the value "v<b class="variable">i</b>".</p>
<p><em>Note</em>: The bee-encoding does not retain the order of the keys in
the input, but stores in a sorted order. The sorting is done for the
"raw strings".</p></dd>
</dl>
<p>Note that the type of each encoded item can be determined immediately
from the first character of its representation:</p>
<dl class="doctools_definitions">
<dt>i</dt>
<dd><p>Integer.</p></dd>
<dt>l</dt>
<dd><p>List.</p></dd>
<dt>d</dt>
<dd><p>Dictionary.</p></dd>
<dt>[0-9]</dt>
<dd><p>String.</p></dd>
</dl>
<p>By wrapping an integer number into <b class="const">i</b>...<b class="const">e</b> the format
makes sure that they are different from strings, which all begin with
a digit.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bee</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bittorrent">BitTorrent</a>, <a href="../../../../index.html#bee">bee</a>, <a href="../../../../index.html#bittorrent">bittorrent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#torrent">torrent</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
|
<div class='fossil-doc' data-title='bench - Benchmarking/Performance tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench(n) 0.4 tcllib "Benchmarking/Performance tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench - bench - Processing benchmark suites</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Benchmark execution</a></li>
<li class="doctools_subsection"><a href="#subsection2">Result manipulation</a></li>
<li class="doctools_subsection"><a href="#subsection3">Result format</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">bench <span class="opt">?0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::bench::locate</b> <i class="arg">pattern</i> <i class="arg">paths</i></a></li>
<li><a href="#2"><b class="cmd">::bench::run</b> <span class="opt">?<i class="arg">option value</i>...?</span> <i class="arg">interp_list</i> <i class="arg">file</i>...</a></li>
<li><a href="#3"><b class="cmd">::bench::versions</b> <i class="arg">interp_list</i></a></li>
<li><a href="#4"><b class="cmd">::bench::del</b> <i class="arg">bench_result</i> <i class="arg">column</i></a></li>
<li><a href="#5"><b class="cmd">::bench::edit</b> <i class="arg">bench_result</i> <i class="arg">column</i> <i class="arg">newvalue</i></a></li>
<li><a href="#6"><b class="cmd">::bench::merge</b> <i class="arg">bench_result</i>...</a></li>
<li><a href="#7"><b class="cmd">::bench::norm</b> <i class="arg">bench_result</i> <i class="arg">column</i></a></li>
<li><a href="#8"><b class="cmd">::bench::out::raw</b> <i class="arg">bench_result</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for the execution of benchmarks written
in the bench language, and for the processing of results generated by
such execution.</p>
<p>A reader interested in the bench language itself should start with the
<i class="term"><a href="bench_lang_intro.html">bench language introduction</a></i> and proceed from there to the
formal <i class="term"><a href="bench_lang_spec.html">bench language specification</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Benchmark execution</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::bench::locate</b> <i class="arg">pattern</i> <i class="arg">paths</i></a></dt>
<dd><p>This command locates Tcl interpreters and returns a list containing
their paths. It searches them in the list of <i class="arg">paths</i> specified by
the caller, using the glob <i class="arg">pattern</i>.</p>
<p>The command resolves soft links to find the actual executables
matching the pattern. Note that only interpreters which are marked as
executable and are actually executable on the current platform are put
into the result.</p></dd>
<dt><a name="2"><b class="cmd">::bench::run</b> <span class="opt">?<i class="arg">option value</i>...?</span> <i class="arg">interp_list</i> <i class="arg">file</i>...</a></dt>
<dd><p>This command executes the benchmarks declared in the set of files,
once per Tcl interpreter specified via the <i class="arg">interp_list</i>, and per
the configuration specified by the options, and then returns the
accumulated timing results. The format of this result is described in
section <span class="sectref"><a href="#subsection3">Result format</a></span>.</p>
<p>It is assumed that the contents of the files are written in the bench
language.</p>
<p>The available options are</p>
<dl class="doctools_options">
<dt><b class="option">-errors</b> <i class="arg">flag</i></dt>
<dd><p>The argument is a boolean value. If set errors in benchmarks are
propagated to the command, aborting benchmark execution. Otherwise
they are recorded in the timing result via a special result code. The
default is to propagate and abort.</p></dd>
<dt><b class="option">-threads</b> <i class="arg">n</i></dt>
<dd><p>The argument is a non-negative integer value declaring the number of
threads to use while executing the benchmarks. The default value is
<b class="const">0</b>, to not use threads.</p></dd>
<dt><b class="option">-match</b> <i class="arg">pattern</i></dt>
<dd><p>The argument is a glob pattern. Only benchmarks whose description
matches the pattern are executed. The default is the empty string, to
execute all patterns.</p></dd>
<dt><b class="option">-rmatch</b> <i class="arg">pattern</i></dt>
<dd><p>The argument is a regular expression pattern. Only benchmarks whose
description matches the pattern are executed. The default is the empty
string, to execute all patterns.</p></dd>
<dt><b class="option">-iters</b> <i class="arg">n</i></dt>
<dd><p>The argument is positive integer number, the maximal number of
iterations for any benchmark. The default is <b class="const">1000</b>. Individual
benchmarks can override this.</p></dd>
<dt><b class="option">-pkgdir</b> <i class="arg">path</i></dt>
<dd><p>The argument is a path to an existing, readable directory. Multiple
paths can be specified, simply use the option multiple times, each
time with one of the paths to use.</p>
<p>If no paths were specified the system will behave as before.
If one or more paths are specified, say <b class="variable">N</b>, each of the specified
interpreters will be invoked <b class="variable">N</b> times, with one of the specified
paths. The chosen path is put into the interpreters' <b class="variable">auto_path</b>,
thus allowing it to find specific versions of a package.</p>
<p>In this way the use of <b class="option">-pkgdir</b> allows the user to benchmark
several different versions of a package, against one or more interpreters.</p>
<p><em>Note:</em> The empty string is allowed as a path and causes the system to
run the specified interpreters with an unmodified <b class="variable">auto_path</b>. In case
the package in question is available there as well.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::bench::versions</b> <i class="arg">interp_list</i></a></dt>
<dd><p>This command takes a list of Tcl interpreters, identified by their
path, and returns a dictionary mapping from the interpreters to their
versions. Interpreters which are not actually executable, or fail when
interrogated, are not put into the result. I.e the result may contain
less interpreters than there in the input list.</p>
<p>The command uses builtin command <b class="cmd">info patchlevel</b> to determine
the version of each interpreter.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Result manipulation</a></h3>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">::bench::del</b> <i class="arg">bench_result</i> <i class="arg">column</i></a></dt>
<dd><p>This command removes a column, i.e. all benchmark results for a
specific Tcl interpreter, from the specified benchmark result and
returns the modified result.</p>
<p>The benchmark results are in the format described in section
<span class="sectref"><a href="#subsection3">Result format</a></span>.</p>
<p>The column is identified by an integer number.</p></dd>
<dt><a name="5"><b class="cmd">::bench::edit</b> <i class="arg">bench_result</i> <i class="arg">column</i> <i class="arg">newvalue</i></a></dt>
<dd><p>This command renames a column in the specified benchmark result and
returns the modified result. This means that the path of the Tcl
interpreter in the identified column is changed to an arbitrary
string.</p>
<p>The benchmark results are in the format described in section
<span class="sectref"><a href="#subsection3">Result format</a></span>.</p>
<p>The column is identified by an integer number.</p></dd>
<dt><a name="6"><b class="cmd">::bench::merge</b> <i class="arg">bench_result</i>...</a></dt>
<dd><p>This commands takes one or more benchmark results, merges them into
one big result, and returns that as its result.</p>
<p>All benchmark results are in the format described in section
<span class="sectref"><a href="#subsection3">Result format</a></span>.</p></dd>
<dt><a name="7"><b class="cmd">::bench::norm</b> <i class="arg">bench_result</i> <i class="arg">column</i></a></dt>
<dd><p>This command normalizes the timing results in the specified benchmark
result and returns the modified result. This means that the cell
values are not times anymore, but factors showing how much faster or
slower the execution was relative to the baseline.</p>
<p>The baseline against which the command normalizes are the timing
results in the chosen column. This means that after the normalization
the values in this column are all <b class="const">1</b>, as these benchmarks are
neither faster nor slower than the baseline.</p>
<p>A factor less than <b class="const">1</b> indicates a benchmark which was faster
than the baseline, whereas a factor greater than <b class="const">1</b> indicates a
slower execution.</p>
<p>The benchmark results are in the format described in section
<span class="sectref"><a href="#subsection3">Result format</a></span>.</p>
<p>The column is identified by an integer number.</p></dd>
<dt><a name="8"><b class="cmd">::bench::out::raw</b> <i class="arg">bench_result</i></a></dt>
<dd><p>This command formats the specified benchmark result for output to a
file, socket, etc. This specific command does no formatting at all,
it passes the input through unchanged.</p>
<p>For other formatting styles see the packages <b class="package"><a href="bench_wtext.html">bench::out::text</a></b>
and <b class="package"><a href="bench_wcsv.html">bench::out::csv</a></b> which provide commands to format
benchmark results for human consumption, or as CSV data importable by
spread sheets, respectively.</p>
<p>Complementary, to read benchmark results from files, sockets etc. look
for the package <b class="package"><a href="bench_read.html">bench::in</a></b> and the commands provided by it.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Result format</a></h3>
<p>After the execution of a set of benchmarks the raw result returned by
this package is a Tcl dictionary containing all the relevant
information.
The dictionary is a compact representation, i.e. serialization, of a
2-dimensional table which has Tcl interpreters as columns and
benchmarks as rows. The cells of the table contain the timing
results.
The Tcl interpreters / columns are identified by their paths.
The benchmarks / rows are identified by their description.</p>
<p>The possible keys are all valid Tcl lists of two or three elements and
have one of the following forms:</p>
<dl class="doctools_definitions">
<dt>{interp *}</dt>
<dd><p>The set of keys matching this glob pattern capture the information
about all the Tcl interpreters used to run the benchmarks. The second
element of the key is the path to the interpreter.</p>
<p>The associated value is the version of the Tcl interpreter.</p></dd>
<dt>{desc *}</dt>
<dd><p>The set of keys matching this glob pattern capture the information
about all the benchmarks found in the executed benchmark suite. The
second element of the key is the description of the benchmark, which
has to be unique.</p>
<p>The associated value is irrelevant, and set to the empty string.</p></dd>
<dt>{usec * *}</dt>
<dd><p>The set of keys matching this glob pattern capture the performance
information, i.e. timing results. The second element of the key is the
description of the benchmark, the third element the path of the Tcl
interpreter which was used to run it.</p>
<p>The associated value is either one of several special result codes, or
the time it took to execute the benchmark, in microseconds. The
possible special result codes are</p>
<dl class="doctools_definitions">
<dt>ERR</dt>
<dd><p>Benchmark could not be executed, failed with a Tcl error.</p></dd>
<dt>BAD_RES</dt>
<dd><p>The benchmark could be executed, however the result from its body did
not match the declared expectations.</p></dd>
</dl></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench_intro.html">bench_intro</a>, <a href="bench_lang_intro.html">bench_lang_intro</a>, <a href="bench_lang_spec.html">bench_lang_spec</a>, bench_read, bench_wcsv, bench_wtext</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#merging">merging</a>, <a href="../../../../index.html#normalization">normalization</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#testing">testing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<div class='fossil-doc' data-title='bench_intro - Benchmarking/Performance tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench_intro(n) 1.0 tcllib "Benchmarking/Performance tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench_intro - bench introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">HISTORICAL NOTES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <i class="term"><a href="bench.html">bench</a></i> (short for <em>benchmark tools</em>), is a set of
related, yet different, entities which are working together for the
easy creation and execution of performance test suites, also known as
benchmarks. These are</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the declaration of test cases. A test case is
represented by a tcl command declaring the various parts needed to
execute it, like setup, cleanup, the commands to test, etc.</p></li>
<li><p>A package providing the ability to execute test cases written in that
language.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the benchmarking process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of benchmarks has to understand the bench language
itself. A beginner to bench should read the more informally written
<i class="term"><a href="bench_lang_intro.html">bench language introduction</a></i> first. Having digested this the
formal <i class="term"><a href="bench_lang_spec.html">bench language specification</a></i> should become
understandable. A writer experienced with bench may only need this
last document from time to time, to refresh her memory.</p></li>
<li><p>A <i class="term">user</i> of benchmark suites written in the <i class="term"><a href="bench.html">bench</a></i> language
has to know which tools are available for use.
At the bottom level sits the package <b class="package"><a href="bench.html">bench</a></b>, providing the
basic facilities to read and execute files containing benchmarks
written in the bench language, and to manipulate benchmark results.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">HISTORICAL NOTES</a></h2>
<p>This module and package have been derived from Jeff Hobbs'
<b class="syscmd">tclbench</b> application for the benchmarking of the Tcl core and
its ancestor "<b class="file">runbench.tcl</b>".</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench.html">bench</a>, bench_lang_faq, <a href="bench_lang_intro.html">bench_lang_intro</a>, <a href="bench_lang_spec.html">bench_lang_spec</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bench_language">bench language</a>, <a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#testing">testing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench_lang_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
<div class='fossil-doc' data-title='bench_lang_intro - Benchmarking/Performance tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench_lang_intro(n) 1.0 tcllib "Benchmarking/Performance tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench_lang_intro - bench language introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Fundamentals</a></li>
<li class="doctools_subsection"><a href="#subsection2">Basics</a></li>
<li class="doctools_subsection"><a href="#subsection3">Pre- and postprocessing</a></li>
<li class="doctools_subsection"><a href="#subsection4">Advanced pre- and postprocessing</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">FURTHER READING</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is an informal introduction to version 1 of the bench
language based on a multitude of examples. After reading this a
benchmark writer should be ready to understand the formal
<i class="term"><a href="bench_lang_spec.html">bench language specification</a></i>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Fundamentals</a></h3>
<p>In the broadest terms possible the <i class="term"><a href="../../../../index.html#bench_language">bench language</a></i> is
essentially Tcl, plus a number of commands to support the declaration
of benchmarks.
A document written in this language is a Tcl script and has the same
syntax.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basics</a></h3>
<p>One of the most simplest benchmarks which can be written in bench is</p>
<pre class="doctools_example">
bench -desc LABEL -body {
set a b
}
</pre>
<p>This code declares a benchmark named <b class="const">LABEL</b> which measures the
time it takes to assign a value to a variable. The Tcl code doing this
assignment is the <b class="option">-body</b> of the benchmark.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Pre- and postprocessing</a></h3>
<p>Our next example demonstrates how to declare <i class="term">initialization</i> and
<i class="term"><a href="../../../../index.html#cleanup">cleanup</a></i> code, i.e. code computing information for the use of
the <b class="option">-body</b>, and for releasing such resources after the
measurement is done.
They are the <b class="option">-pre</b>- and the <b class="option">-post</b>-body, respectively.</p>
<p>In our example, directly drawn from the benchmark suite of Tcllib's
<b class="package"><a href="../aes/aes.html">aes</a></b> package, the concrete initialization code constructs the
key schedule used by the encryption command whose speed we measure,
and the cleanup code releases any resources bound to that schedule.</p>
<pre class="doctools_example">
bench -desc "AES-${len} ECB encryption core" <b class="option">-pre</b> {
set key [aes::Init ecb $k $i]
} -body {
aes::Encrypt $key $p
} <b class="option">-post</b> {
aes::Final $key
}
</pre>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Advanced pre- and postprocessing</a></h3>
<p>Our last example again deals with initialization and cleanup code. To
see the difference to the regular initialization and cleanup discussed
in the last section it is necessary to know a bit more about how bench
actually measures the speed of the the <b class="option">-body</b>.</p>
<p>Instead of running the <b class="option">-body</b> just once the system actually
executes the <b class="option">-body</b> several hundred times and then returns the
average of the found execution times. This is done to remove
environmental effects like machine load from the result as much as
possible, with outliers canceling each other out in the average.</p>
<p>The drawback of doing things this way is that when we measure
operations which are not idempotent we will most likely not measure
the time for the operation we want, but of the state(s) the system is
in after the first iteration, a mixture of things we have no interest
in.</p>
<p>Should we wish, for example, to measure the time it takes to include
an element into a set, with the element not yet in the set, and the
set having specific properties like being a shared Tcl_Obj, then the
first iteration will measure the time for this. <em>However</em> all
subsequent iterations will measure the time to include an element
which is already in the set, and the Tcl_Obj holding the set will not
be shared anymore either. In the end the timings taken for the several
hundred iterations of this state will overwhelm the time taken from
the first iteration, the only one which actually measured what we
wanted.</p>
<p>The advanced initialization and cleanup codes, <b class="option">-ipre</b>- and the
<b class="option">-ipost</b>-body respectively, are present to solve this very
problem. While the regular initialization and cleanup codes are
executed before and after the whole series of iterations the advanced
codes are executed before and after each iteration of the body,
without being measured themselves. This allows them to bring the
system into the exact state the body wishes to measure.</p>
<p>Our example, directly drawn from the benchmark suite of Tcllib's
<b class="package"><a href="../struct/struct_set.html">struct::set</a></b> package, is for exactly the example we used
above to demonstrate the necessity for the advanced initialization and
cleanup. Its concrete initialization code constructs a variable
refering to a set with specific properties (The set has a string
representation, which is shared) affecting the speed of the inclusion
command, and the cleanup code releases the temporary variables created
by this initialization.</p>
<pre class="doctools_example">
bench -desc "set include, missing <SC> x$times $n" <b class="option">-ipre</b> {
set A $sx($times,$n)
set B $A
} -body {
struct::set include A x
} <b class="option">-ipost</b> {
unset A B
}
</pre>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">FURTHER READING</a></h2>
<p>Now that this document has been digested the reader, assumed to be a
<i class="term">writer</i> of benchmarks, he should be fortified enough to be able
to understand the formal <i class="term">bench language specfication</i>. It will
also serve as the detailed specification and cheat sheet for all
available commands and their syntax.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench_intro.html">bench_intro</a>, <a href="bench_lang_spec.html">bench_lang_spec</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bench_language">bench language</a>, <a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#examples">examples</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#testing">testing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench_lang_spec.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
<div class='fossil-doc' data-title='bench_lang_spec - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench_lang_spec(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench_lang_spec - bench language specification</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">bench_rm</b> <i class="arg">path</i>...</a></li>
<li><a href="#2"><b class="cmd">bench_tmpfile</b></a></li>
<li><a href="#3"><b class="cmd"><a href="bench.html">bench</a></b> <i class="arg">options</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document specifies both names and syntax of all the commands
which together are the bench language, version 1.
As this document is intended to be a reference the commands are listed
in alphabetical order, and the descriptions are relatively short.
A beginner should read the more informally written
<i class="term"><a href="bench_lang_intro.html">bench language introduction</a></i> first.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">bench_rm</b> <i class="arg">path</i>...</a></dt>
<dd><p>This command silently removes the files specified as its arguments and
then returns the empty string as its result.
The command is <em>trusted</em>, there is no checking if the specified
files are outside of whatever restricted area the benchmarks are run
in.</p></dd>
<dt><a name="2"><b class="cmd">bench_tmpfile</b></a></dt>
<dd><p>This command returns the path to a bench specific unique temporary
file. The uniqueness means that multiple calls will return different
paths. While the path may exist from previous runs, the command itself
does <em>not</em> create aynthing.</p>
<p>The base location of the temporary files is platform dependent:</p>
<dl class="doctools_definitions">
<dt>Unix, and indeterminate platform</dt>
<dd><p>"<b class="file">/tmp</b>"</p></dd>
<dt>Windows</dt>
<dd><p><b class="variable">$TEMP</b></p></dd>
<dt>Anything else</dt>
<dd><p>The current working directory.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd"><a href="bench.html">bench</a></b> <i class="arg">options</i>...</a></dt>
<dd><p>This command declares a single benchmark. Its result is the empty
string. All parts of the benchmark are declared via options, and their
values. The options can occur in any order. The accepted options are:</p>
<dl class="doctools_options">
<dt><b class="option">-body</b> script</dt>
<dd><p>The argument of this option declares the body of the benchmark, the
Tcl script whose performance we wish to measure. This option, and
<b class="option">-desc</b>, are the two required parts of each benchmark.</p></dd>
<dt><b class="option">-desc</b> msg</dt>
<dd><p>The argument of this option declares the name of the benchmark. It has
to be unique, or timing data from different benchmarks will be mixed
together.</p>
<p><em>Beware!</em> This requirement is not checked when benchmarks are
executed, and the system will silently produce bogus data. This
option, and <b class="option">-body</b>, are the two required parts of each
benchmark.</p></dd>
<dt><b class="option">-ipost</b> script</dt>
<dd><p>The argument of this option declares a script which is run immediately
<em>after</em> each iteration of the body. Its responsibility is to
release resources created by the body, or <b class="option">-ipre</b>-bodym which
we do not wish to live into the next iteration.</p></dd>
<dt><b class="option">-ipre</b> script</dt>
<dd><p>The argument of this option declares a script which is run immediately
<em>before</em> each iteration of the body. Its responsibility is to
create the state of the system expected by the body so that we measure
the right thing.</p></dd>
<dt><b class="option">-iterations</b> num</dt>
<dd><p>The argument of this option declares the maximum number of times to
run the <b class="option">-body</b> of the benchmark. During execution this and the
global maximum number of iterations are compared and the smaller of
the two values is used.</p>
<p>This option should be used only for benchmarks which are expected or
known to take a long time per run. I.e. reduce the number of times
they are run to keep the overall time for the execution of the whole
benchmark within manageable limits.</p></dd>
<dt><b class="option">-post</b> script</dt>
<dd><p>The argument of this option declares a script which is run
<em>after</em> all iterations of the body have been run. Its
responsibility is to release resources created by the body,
or <b class="option">-pre</b>-body.</p></dd>
<dt><b class="option">-pre</b> script</dt>
<dd><p>The argument of this option declares a script which is run
<em>before</em> any of the iterations of the body are run. Its
responsibility is to create whatever resources are needed by the body
to run without failing.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench_intro.html">bench_intro</a>, <a href="bench_lang_intro.html">bench_lang_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bench_language">bench language</a>, <a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#specification">specification</a>, <a href="../../../../index.html#testing">testing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench_read.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='bench::in - Benchmarking/Performance tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench::in(n) 0.1 tcllib "Benchmarking/Performance tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench::in - bench::in - Reading benchmark results</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">csv</b></li>
<li>package require <b class="pkgname">bench::in <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::bench::in::read</b> <i class="arg">file</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a command for reading benchmark results from
files, sockets, etc.</p>
<p>A reader interested in the creation, processing or writing of such
results should go and read
<i class="term"><a href="bench.html">bench - Processing benchmark suites</a></i> instead.</p>
<p>If the bench language itself is the actual interest please start with
the <i class="term"><a href="bench_lang_intro.html">bench language introduction</a></i> and then proceed from there
to the formal <i class="term"><a href="bench_lang_spec.html">bench language specification</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::bench::in::read</b> <i class="arg">file</i></a></dt>
<dd><p>This command reads a benchmark result from the specified <i class="arg">file</i>
and returns it as its result. The command understands the three
formats created by the commands</p>
<dl class="doctools_commands">
<dt><b class="cmd">bench::out::raw</b></dt>
<dd><p>Provided by package <b class="package"><a href="bench.html">bench</a></b>.</p></dd>
<dt><b class="cmd"><a href="bench_wcsv.html">bench::out::csv</a></b></dt>
<dd><p>Provided by package <b class="package"><a href="bench_wcsv.html">bench::out::csv</a></b>.</p></dd>
<dt><b class="cmd"><a href="bench_wtext.html">bench::out::text</a></b></dt>
<dd><p>Provided by package <b class="package"><a href="bench_wtext.html">bench::out::text</a></b>.</p></dd>
</dl>
<p>and automatically detects which format is used by the input file.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench.html">bench</a>, <a href="bench_wcsv.html">bench::out::csv</a>, <a href="bench_wtext.html">bench::out::text</a>, <a href="bench_intro.html">bench_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#csv">csv</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#human_readable">human readable</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#reading">reading</a>, <a href="../../../../index.html#testing">testing</a>, <a href="../../../../index.html#text">text</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench_wcsv.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<div class='fossil-doc' data-title='bench::out::csv - Benchmarking/Performance tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench::out::csv(n) 0.1.2 tcllib "Benchmarking/Performance tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench::out::csv - bench::out::csv - Formatting benchmark results as CSV</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">bench::out::csv <span class="opt">?0.1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::bench::out::csv</b> <i class="arg">bench_result</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for fomatting of benchmark results into
a CSV table importable by spread sheets.</p>
<p>A reader interested in the generation or processing of such results should
go and read <i class="term"><a href="bench.html">bench - Processing benchmark suites</a></i> instead.</p>
<p>If the bench language itself is the actual interest please start with
the <i class="term"><a href="bench_lang_intro.html">bench language introduction</a></i> and then proceed from there
to the formal <i class="term"><a href="bench_lang_spec.html">bench language specification</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::bench::out::csv</b> <i class="arg">bench_result</i></a></dt>
<dd><p>This command formats the specified benchmark result for output to a
file, socket, etc. This specific command generates CSV data importable
by spread sheets.</p>
<p>For other formatting styles see the packages <b class="package"><a href="bench.html">bench</a></b> and
<b class="package"><a href="bench_wtext.html">bench::out::text</a></b> which provide commands to format benchmark
results in raw form, or for human consumption, respectively.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench.html">bench</a>, <a href="bench_wtext.html">bench::out::text</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#csv">csv</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#testing">testing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bench/bench_wtext.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<div class='fossil-doc' data-title='bench::out::text - Benchmarking/Performance tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bench::out::text(n) 0.1.2 tcllib "Benchmarking/Performance tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bench::out::text - bench::out::text - Formatting benchmark results as human readable text</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">bench::out::text <span class="opt">?0.1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::bench::out::text</b> <i class="arg">bench_result</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for fomatting of benchmark results into
human readable text.</p>
<p>A reader interested in the generation or processing of such results should
go and read <i class="term"><a href="bench.html">bench - Processing benchmark suites</a></i> instead.</p>
<p>If the bench language itself is the actual interest please start with
the <i class="term"><a href="bench_lang_intro.html">bench language introduction</a></i> and then proceed from there
to the formal <i class="term"><a href="bench_lang_spec.html">bench language specification</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::bench::out::text</b> <i class="arg">bench_result</i></a></dt>
<dd><p>This command formats the specified benchmark result for output to a
file, socket, etc. This specific command generates human readable
text.</p>
<p>For other formatting styles see the packages <b class="package"><a href="bench.html">bench</a></b> and
<b class="package"><a href="bench_wcsv.html">bench::out::csv</a></b> which provide commands to format benchmark
results in raw form, or as importable CSV data, respectively.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bench</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="bench.html">bench</a>, <a href="bench_wcsv.html">bench::out::csv</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#benchmark">benchmark</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#human_readable">human readable</a>, <a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#testing">testing</a>, <a href="../../../../index.html#text">text</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Benchmark tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/bibtex/bibtex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
<div class='fossil-doc' data-title='bibtex - bibtex'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">bibtex(n) 0.6 tcllib "bibtex"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>bibtex - Parse bibtex files</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">bibtex <span class="opt">?0.6?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::bibtex::parse</b> <span class="opt">?<i class="arg">options</i>?</span> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::bibtex::parse</b> <i class="arg">text</i></a></li>
<li><a href="#3"><b class="cmd">::bibtex::parse</b> <span class="opt">?<b class="option">-command</b> <i class="arg">cmd</i>?</span> <b class="option">-channel</b> <i class="arg">chan</i></a></li>
<li><a href="#4"><b class="cmd">::bibtex::parse</b> <span class="opt">?<b class="option">-recordcommand</b> <i class="arg">recordcmd</i>?</span> <span class="opt">?<b class="option">-preamblecommand</b> <i class="arg">preamblecmd</i>?</span> <span class="opt">?<b class="option">-stringcommand</b> <i class="arg">stringcmd</i>?</span> <span class="opt">?<b class="option">-commentcommand</b> <i class="arg">commentcmd</i>?</span> <span class="opt">?<b class="option">-progresscommand</b> <i class="arg">progresscmd</i>?</span> <span class="opt">?<b class="option">-casesensitivestrings</b> <i class="arg">bool</i>?</span> (<i class="arg">text</i> | <b class="option">-channel</b> <i class="arg">chan</i>)</a></li>
<li><a href="#5"><b class="cmd">::bibtex::wait</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::bibtex::destroy</b> <i class="arg">token</i></a></li>
<li><a href="#7"><b class="cmd">::bibtex::addStrings</b> <i class="arg">token</i> <i class="arg">stringdict</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for the parsing of bibliographies in
BibTeX format.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::bibtex::parse</b> <span class="opt">?<i class="arg">options</i>?</span> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This is the general form of the command for parsing a
bibliography. Depending on the options used to invoke it it will
either return a token for the parser, or the parsed entries of the
input bibliography. Instead of performing an immediate parse returning
a predefined format the command can also enter an event-based parsing
style where all relevant entries in the input are reported through
callback commands, in the style of SAX.</p></dd>
<dt><a name="2"><b class="cmd">::bibtex::parse</b> <i class="arg">text</i></a></dt>
<dd><p>In this form the command will assume that the specified <i class="arg">text</i> is
a bibliography in BibTeX format, parse it, and then return a list
containing one element per record found in the bibliography. Note that
comments, string definitions, preambles, etc. will not show up in the
result. Each element will be a list containing record type,
bibliography key and record data, in this order. The record data will
be a dictionary, its keys the keys of the record, with the associated
values.</p></dd>
<dt><a name="3"><b class="cmd">::bibtex::parse</b> <span class="opt">?<b class="option">-command</b> <i class="arg">cmd</i>?</span> <b class="option">-channel</b> <i class="arg">chan</i></a></dt>
<dd><p>In this form the command will reads the bibliography from the
specified Tcl channel <i class="arg">chan</i> and then returns the same data
structure as described above.</p>
<p>If however the option <b class="option">-command</b> is specified the result will be a
handle for the parser instead and all processing will be incremental
and happen in the background. When the input has been exhausted the
callback <i class="arg">cmd</i> will be invoked with the result of the parse. The
exact definition for the callback is</p>
<dl class="doctools_definitions">
<dt><b class="cmd">cmd</b> <i class="arg">token</i> <i class="arg">parseresult</i></dt>
<dd><p>The parse result will have the structure explained above, for the
simpler forms of the parser.</p></dd>
</dl>
<p><em>Note</em> that the parser will <em>not</em> close the channel after it
has exhausted it. This is still the responsibility of the user of the
parser.</p></dd>
<dt><a name="4"><b class="cmd">::bibtex::parse</b> <span class="opt">?<b class="option">-recordcommand</b> <i class="arg">recordcmd</i>?</span> <span class="opt">?<b class="option">-preamblecommand</b> <i class="arg">preamblecmd</i>?</span> <span class="opt">?<b class="option">-stringcommand</b> <i class="arg">stringcmd</i>?</span> <span class="opt">?<b class="option">-commentcommand</b> <i class="arg">commentcmd</i>?</span> <span class="opt">?<b class="option">-progresscommand</b> <i class="arg">progresscmd</i>?</span> <span class="opt">?<b class="option">-casesensitivestrings</b> <i class="arg">bool</i>?</span> (<i class="arg">text</i> | <b class="option">-channel</b> <i class="arg">chan</i>)</a></dt>
<dd><p>This is the most low-level form for the parser. The returned result
will be a handle for the parser. During processing it will invoke the
invoke the specified callback commands for each type of data found in
the bibliography.</p>
<p>The processing will be incremental and happen in the background if,
and only if a Tcl channel <i class="arg">chan</i> is specified. For a <i class="arg">text</i>
the processing will happen immediately and all callbacks will be
invoked before the command itself returns.</p>
<p>The callbacks, i.e. <i class="arg">*cmd</i>, are all command prefixes and will be
invoked with additional arguments appended to them. The meaning of the
arguments depends on the callback and is explained below. The first
argument will however always be the handle of the parser invoking the
callback.</p>
<dl class="doctools_definitions">
<dt><b class="option">-casesensitivestrings</b></dt>
<dd><p>This option takes a boolean value. When set string macro processing
becomes case-sensitive. The default is case-insensitive string macro
processing.</p></dd>
<dt><b class="cmd">recordcmd</b> <i class="arg">token</i> <i class="arg">type</i> <i class="arg">key</i> <i class="arg">recorddict</i></dt>
<dd><p>This callback is invoked whenever the parser detects a bibliography
record in the input. Its arguments are the record type, the
bibliography key for the record, and a dictionary containing the keys
and values describing the record. Any string macros known to the
parser have already been expanded.</p></dd>
<dt><b class="cmd">preamblecmd</b> <i class="arg">token</i> <i class="arg">preambletext</i></dt>
<dd><p>This callback is invoked whenever the parser detects an @preamble
block in the input. The only additional argument is the text found in
the preamble block. By default such entries are ignored.</p></dd>
<dt><b class="cmd">stringcmd</b> <i class="arg">token</i> <i class="arg">stringdict</i></dt>
<dd><p>This callback is invoked whenever the parser detects an @string-based
macro definition in the input. The argument is a dictionary with the
macro names as keys and their replacement strings as values. By
default such definitions are added to the parser state for use in
future bibliography records.</p></dd>
<dt><b class="cmd">commentcmd</b> <i class="arg">token</i> <i class="arg">commenttext</i></dt>
<dd><p>This callback is invoked whenever the parser detects a comment in the
input. The only additional argument is the comment text. By default
such entries are ignored.</p></dd>
<dt><b class="cmd">progresscmd</b> <i class="arg">token</i> <i class="arg">percent</i></dt>
<dd><p>This callback is invoked during processing to tell the user about the
progress which has been made. Its argument is the percentage of data
processed, as integer number between <b class="const">0</b> and <b class="const">100</b>.
In the case of incremental processing the perecentage will always be
<b class="const">-1</b> as the total number of entries is not known beforehand.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::bibtex::wait</b> <i class="arg">token</i></a></dt>
<dd><p>This command waits for the parser represented by the <i class="arg">token</i> to
complete and then returns. The returned result is the empty string.</p></dd>
<dt><a name="6"><b class="cmd">::bibtex::destroy</b> <i class="arg">token</i></a></dt>
<dd><p>This command cleans up all internal state associated with the parser
represented by the handle <i class="arg">token</i>, effectively destroying it. This
command can be called from within the parser callbacks to terminate
processing.</p></dd>
<dt><a name="7"><b class="cmd">::bibtex::addStrings</b> <i class="arg">token</i> <i class="arg">stringdict</i></a></dt>
<dd><p>This command adds the macro definitions stored in the
dictionary <i class="arg">stringdict</i> to the parser represented
by the handle <i class="arg">token</i>.</p>
<p>The dictionary keys are the macro names and the values their
replacement strings. This command has the correct signature for use as
a <b class="option">-stringcommand</b> callback in an invokation of the command
<b class="cmd">::bibtex::parse</b>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>bibtex</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bibliography">bibliography</a>, <a href="../../../../index.html#bibtex">bibtex</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#text_processing">text processing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 for documentation, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/blowfish/blowfish.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
<div class='fossil-doc' data-title='blowfish - Blowfish Block Cipher'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">blowfish(n) 1.0.3 tcllib "Blowfish Block Cipher"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>blowfish - Implementation of the Blowfish block cipher</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">MODES OF OPERATION</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">REFERENCES</a></li>
<li class="doctools_section"><a href="#section7">AUTHORS</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">blowfish <span class="opt">?1.0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::blowfish::blowfish</b> <span class="opt">?<i class="arg">-mode [ecb|cbc]</i>?</span> <span class="opt">?<i class="arg">-dir [encrypt|decrypt]</i>?</span> <i class="arg">-key keydata</i> <span class="opt">?<i class="arg">-iv vector</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> <span class="opt">?<i class="arg">-pad padchar</i>?</span> [ <i class="arg">-in channel</i> | <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">data</i> ]</a></li>
<li><a href="#2"><b class="cmd">::blowfish::Init</b> <i class="arg">mode</i> <i class="arg">keydata</i> <i class="arg">iv</i></a></li>
<li><a href="#3"><b class="cmd">::blowfish::Encrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::blowfish::Decrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::blowfish::Reset</b> <i class="arg">Key</i> <i class="arg">iv</i></a></li>
<li><a href="#6"><b class="cmd">::blowfish::Final</b> <i class="arg">Key</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the Blowfish algorithm
developed by Bruce Schneier [1]. Blowfish is a 64-bit block cipher
designed to operate quickly on 32 bit architectures and accepting a
variable key length. This implementation supports ECB and CBC mode
blowfish encryption.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::blowfish::blowfish</b> <span class="opt">?<i class="arg">-mode [ecb|cbc]</i>?</span> <span class="opt">?<i class="arg">-dir [encrypt|decrypt]</i>?</span> <i class="arg">-key keydata</i> <span class="opt">?<i class="arg">-iv vector</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> <span class="opt">?<i class="arg">-pad padchar</i>?</span> [ <i class="arg">-in channel</i> | <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">data</i> ]</a></dt>
<dd><p>Perform the <b class="package">blowfish</b> algorithm on either the data provided
by the argument or on the data read from the <i class="arg">-in</i> channel. If
an <i class="arg">-out</i> channel is given then the result will be written to
this channel.</p>
<p>The <i class="arg">-key</i> option must be given. This parameter takes a binary
string of variable length and is used to generate the <b class="package">blowfish</b>
key schedule. You should be aware that creating a key
schedule is quite an expensive operation in blowfish so it is worth
reusing the key where possible. See <b class="cmd">Reset</b>.</p>
<p>The <i class="arg">-mode</i> and <i class="arg">-dir</i> options are optional and default to cbc
mode and encrypt respectively. The initialization vector <i class="arg">-iv</i>
takes an 8 byte binary argument which defaults to 8 zeros.
See <span class="sectref"><a href="#section4">MODES OF OPERATION</a></span> for more about available modes and
their uses.</p>
<p>Blowfish is a 64-bit block cipher. This means that the data must be
provided in units that are a multiple of 8 bytes. The <b class="cmd">blowfish</b>
command will by default add nul characters to pad the input data to a
multiple of 8 bytes if necessary. The programming api commands will
never add padding and instead will raise an error if the input is not
a multiple of the block size. The <i class="arg">-pad</i> option can be used to
change the padding character or to disable padding if the empty string
is provided as the argument.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::blowfish::Init</b> <i class="arg">mode</i> <i class="arg">keydata</i> <i class="arg">iv</i></a></dt>
<dd><p>Construct a new blowfish key schedule using the specified key data and
the given initialization vector. The initialization vector is not used
with ECB mode but is important for CBC mode.
See <span class="sectref"><a href="#section4">MODES OF OPERATION</a></span> for details about cipher modes.</p></dd>
<dt><a name="3"><b class="cmd">::blowfish::Encrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Use a prepared key acquired by calling <b class="cmd">Init</b> to encrypt the
provided data. The data argument should be a binary array that is a
multiple of the block size of 8 bytes. The result is a binary
array the same size as the input of encrypted data.</p></dd>
<dt><a name="4"><b class="cmd">::blowfish::Decrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Decipher data using the key. Note that the same key may be used to
encrypt and decrypt data provided that the initialization vector is
reset appropriately for CBC mode.</p></dd>
<dt><a name="5"><b class="cmd">::blowfish::Reset</b> <i class="arg">Key</i> <i class="arg">iv</i></a></dt>
<dd><p>Reset the initialization vector. This permits the programmer to re-use
a key and avoid the cost of re-generating the key schedule where the
same key data is being used multiple times.</p></dd>
<dt><a name="6"><b class="cmd">::blowfish::Final</b> <i class="arg">Key</i></a></dt>
<dd><p>This should be called to clean up resources associated with <i class="arg">Key</i>.
Once this function has been called the key may not be used again.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">MODES OF OPERATION</a></h2>
<dl class="doctools_definitions">
<dt>Electronic Code Book (ECB)</dt>
<dd><p>ECB is the basic mode of all block ciphers. Each block is encrypted
independently and so identical plain text will produce identical
output when encrypted with the same key. Any encryption errors will
only affect a single block however this is vulnerable to known
plaintext attacks.</p></dd>
<dt>Cipher Block Chaining (CBC)</dt>
<dd><p>CBC mode uses the output of the last block encryption to affect the
current block. An initialization vector of the same size as the cipher
block size is used to handle the first block. The initialization
vector should be chosen randomly and transmitted as the first block of
the output. Errors in encryption affect the current block and the next
block after which the cipher will correct itself. CBC is the most
commonly used mode in software encryption.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<pre class="doctools_example">
% blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!"
d0d8f27e7a374b9e2dbd9938dd04195a
</pre>
<pre class="doctools_example">
set Key [blowfish::Init cbc $eight_bytes_key_data $eight_byte_iv]
append ciphertext [blowfish::Encrypt $Key $plaintext]
append ciphertext [blowfish::Encrypt $Key $additional_plaintext]
blowfish::Final $Key
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Schneier, B. "Applied Cryptography, 2nd edition", 1996,
ISBN 0-471-11709-9, pub. John Wiley & Sons.</p></li>
</ol>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">AUTHORS</a></h2>
<p>Frank Pilhofer, Pat Thoyts</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>blowfish</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>3des, <a href="../des/des.html">des</a>, <a href="../rc4/rc4.html">rc4</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#block_cipher">block cipher</a>, <a href="../../../../index.html#blowfish">blowfish</a>, <a href="../../../../index.html#cryptography">cryptography</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/cache/async.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<div class='fossil-doc' data-title='cache::async - In-memory caches'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">cache::async(n) 0.3.1 tcllib "In-memory caches"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>cache::async - Asynchronous in-memory cache</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">cache::async <span class="opt">?0.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::cache::async</b> <i class="arg">objectName</i> <i class="arg">commandprefix</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">get</b> <i class="arg">key</i> <i class="arg">donecmdprefix</i></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">set</b> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">unset</b> <i class="arg">key</i></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">exists</b> <i class="arg">key</i></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">clear</b> <span class="opt">?<i class="arg">key</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects which cache data in memory, and operate
asynchronously with regard to request and responses. The objects are
agnostic with regard to cache keys and values, and unknown methods are
delegated to the provider of cached data. These two properties make it
easy to use caches as a facade for any data provider.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports a class, <b class="class">cache::async</b>, as specified
below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::cache::async</b> <i class="arg">objectName</i> <i class="arg">commandprefix</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>The command creates a new <i class="term"><a href="../../../../index.html#cache">cache</a></i> object with an associated
global Tcl command whose name is <i class="arg">objectName</i>. This command may
be used to invoke various operations on the object.</p>
<p>The <i class="arg">commandprefix</i> is the action to perform when an user asks for
data in the cache and the cache doesn't yet know about the key. When
run the commandprefix is given three additional arguments, the string
<b class="const">get</b>, the key requested, and the cache object itself, in the
form of its object command, in this order. The execution of the action
is done in an idle-handler, decoupling it from the original request.</p>
<p>The only supported option is</p>
<dl class="doctools_options">
<dt><b class="option">-full-async-results</b></dt>
<dd><p>This option defines the behaviour of the cache for when requested keys
are known to the cache at the time of <b class="method">get</b> request. By default
such requeste are responded to asynchronously as well. Setting this
option to <b class="const">false</b> forces the cache to respond to them
synchronuously, although still through the specified callback.</p></dd>
</dl></dd>
</dl>
<p>The object commands created by the class commands above have
the form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">get</b> <i class="arg">key</i> <i class="arg">donecmdprefix</i></a></dt>
<dd><p>This method requests the data for the <i class="arg">key</i> from the cache. If the
data is not yet known the command prefix specified during construction
of the cache object is used to ask for this information.</p>
<p>Whenever the information is/becomes available the <i class="arg">donecmdprefix</i>
will be run to transfer the result to the caller. This command prefix
is invoked with either 2 or 3 arguments, i.e.</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">set</b>, the <i class="arg">key</i>, and the value.</p></li>
<li><p>The string <b class="const">unset</b>, and the <i class="arg">key</i>.</p></li>
</ol>
<p>These two possibilities are used to either signal the value for the
<i class="arg">key</i>, or that the <i class="arg">key</i> has no value defined for it. The
latter is distinct from the cache not knowing about the <i class="arg">key</i>.</p>
<p>For a cache object configured to be fully asynchronous (default) the
<i class="arg">donecmdprefix</i> is always run in an idle-handler, decoupling it
from the request. Otherwise the callback will be invoked synchronously
when the <i class="arg">key</i> is known to the cache at the time of the
invokation.</p>
<p>Another important part of the cache's behaviour, as it is asynchronous
it is possible that multiple <b class="method">get</b> requests are issued for the
same <i class="arg">key</i> before it can respond. In that case the cache will
issue only one data request to the provider, for the first of these,
and suspend the others, and then notify all of them when the data
becomes available.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">set</b> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">unset</b> <i class="arg">key</i></a></dt>
<dd><p>These two methods are provided to allow users of the cache to make
keys known to the cache, as either having a <i class="arg">value</i>, or as
undefined.</p>
<p>It is expected that the data provider (see <i class="arg">commandprefix</i> of the
constructor) uses them in response to data requests for unknown keys.</p>
<p>Note how this matches the cache's own API towards its caller, calling
the <i class="arg">donecmd</i> of <b class="method">get</b>-requests issued to itself with
either "set key value" or "unset key", versus issuing
<b class="method">get</b>-requests to its own provider with itself in the place of
the <i class="arg">donecmd</i>, expecting to be called with either "set key value"
or "unset key".</p>
<p>This also means that these methods invoke the <i class="arg">donecmd</i> of all
<b class="method">get</b>-requests waiting for information about the modified
<i class="arg">key</i>.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">exists</b> <i class="arg">key</i></a></dt>
<dd><p>This method queries the cache for knowledge about the <i class="arg">key</i> and
returns a boolean value. The result is <b class="const">true</b> if the key is
known, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">clear</b> <span class="opt">?<i class="arg">key</i>?</span></a></dt>
<dd><p>This method resets the state of either the specified <i class="arg">key</i> or of
all keys known to the cache, making it unkown. This forces future
<b class="method">get</b>-requests to reload the information from the provider.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>cache</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#asynchronous">asynchronous</a>, <a href="../../../../index.html#cache">cache</a>, <a href="../../../../index.html#callback">callback</a>, <a href="../../../../index.html#synchronous">synchronous</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/clock/iso8601.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<div class='fossil-doc' data-title='clock_iso8601 - Date/Time Utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">clock_iso8601(n) 0.1 tcllib "Date/Time Utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>clock_iso8601 - Parsing ISO 8601 dates/times</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">clock::iso8601 <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::clock::iso8601 parse_date</b> <i class="arg">date</i> <i class="arg">options...</i></a></li>
<li><a href="#2"><b class="cmd">::clock::iso8601 parse_time</b> <i class="arg">time</i> <i class="arg">options...</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides functionality to parse dates and times in
ISO 8601 format.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::clock::iso8601 parse_date</b> <i class="arg">date</i> <i class="arg">options...</i></a></dt>
<dd><p>This command parses an ISO8601 date string in an unknown variant and
returns the given date/time in seconds since epoch.</p>
<p>The acceptable options are
<b class="option">-base</b>,
<b class="option">-gmt</b>,
<b class="option">-locale</b>, and
<b class="option">-timezone</b>
of the builtin command <b class="cmd">clock scan</b>.</p></dd>
<dt><a name="2"><b class="cmd">::clock::iso8601 parse_time</b> <i class="arg">time</i> <i class="arg">options...</i></a></dt>
<dd><p>This command parses a full ISO8601 timestamp string (date and time) in
an unknown variant and returns the given time in seconds since epoch.</p>
<p>The acceptable options are
<b class="option">-base</b>,
<b class="option">-gmt</b>,
<b class="option">-locale</b>, and
<b class="option">-timezone</b>
of the builtin command <b class="cmd">clock scan</b>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>clock::iso8601</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/clock/rfc2822.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
<div class='fossil-doc' data-title='clock_rfc2822 - Date/Time Utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">clock_rfc2822(n) 0.1 tcllib "Date/Time Utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>clock_rfc2822 - Parsing ISO 8601 dates/times</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">clock::rfc2822 <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::clock::rfc2822 parse_date</b> <i class="arg">date</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides functionality to parse dates in
RFC 2822 format.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::clock::rfc2822 parse_date</b> <i class="arg">date</i></a></dt>
<dd><p>This command parses an RFC2822 date string and returns
the given date in seconds since epoch. An error is thrown
if the command is unable to parse the date.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>clock::rfc2822</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/cmdline/cmdline.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<div class='fossil-doc' data-title='cmdline - Command line and option processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">cmdline(n) 1.5 tcllib "Command line and option processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>cmdline - Procedures to process command lines and options.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">::argv handling</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Error Codes</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">cmdline <span class="opt">?1.3.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::cmdline::getopt</b> <i class="arg">argvVar</i> <i class="arg">optstring</i> <i class="arg">optVar</i> <i class="arg">valVar</i></a></li>
<li><a href="#2"><b class="cmd">::cmdline::getKnownOpt</b> <i class="arg">argvVar</i> <i class="arg">optstring</i> <i class="arg">optVar</i> <i class="arg">valVar</i></a></li>
<li><a href="#3"><b class="cmd">::cmdline::getoptions</b> <i class="arg">arglistVar</i> <i class="arg">optlist</i> <span class="opt">?<i class="arg">usage</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::cmdline::getKnownOptions</b> <i class="arg">arglistVar</i> <i class="arg">optlist</i> <span class="opt">?<i class="arg">usage</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::cmdline::usage</b> <i class="arg">optlist</i> <span class="opt">?<i class="arg">usage</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::cmdline::getfiles</b> <i class="arg">patterns</i> <i class="arg">quiet</i></a></li>
<li><a href="#7"><b class="cmd">::cmdline::getArgv0</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to parse command lines and options.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">::argv handling</a></h2>
<p>One of the most common variables this package will be used with is
<b class="variable">::argv</b>, which holds the command line of the current
application. This variable has a companion <b class="variable">::argc</b> which is
initialized to the number of elements in <b class="variable">::argv</b> at the beginning
of the application.</p>
<p>The commands in this package will <em>not</em> modify the <b class="variable">::argc</b>
companion when called with <b class="variable">::argv</b>. Keeping the value consistent,
if such is desired or required, is the responsibility of the caller.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::cmdline::getopt</b> <i class="arg">argvVar</i> <i class="arg">optstring</i> <i class="arg">optVar</i> <i class="arg">valVar</i></a></dt>
<dd><p>This command works in a fashion like the standard C based <b class="cmd">getopt</b>
function. Given an option string and a pointer to an array of args
this command will process the first argument and return info on how to
proceed. The command returns 1 if an option was found, 0 if no more
options were found, and -1 if an error occurred.</p>
<p><i class="arg">argvVar</i> contains the name of the list of arguments to
process. If options are found the list is modified and the processed
arguments are removed from the start of the list.</p>
<p><i class="arg">optstring</i> contains a list of command options that the
application will accept. If the option ends in ".arg" the command
will use the next argument as an argument to the option, or extract it
from the current argument, if it is of the form "option=value".
Otherwise the option is a boolean that is set to 1 if present.</p>
<p><i class="arg">optVar</i> refers to the variable the command will store the found
option into (without the leading '-' and without the .arg extension).</p>
<p><i class="arg">valVar</i> refers to the variable to store either the value for the
specified option into upon success or an error message in the case of
failure. The stored value comes from the command line for .arg
options, otherwise the value is 1.</p></dd>
<dt><a name="2"><b class="cmd">::cmdline::getKnownOpt</b> <i class="arg">argvVar</i> <i class="arg">optstring</i> <i class="arg">optVar</i> <i class="arg">valVar</i></a></dt>
<dd><p>Like <b class="cmd">::cmdline::getopt</b>, but ignores any unknown options in the
input.</p></dd>
<dt><a name="3"><b class="cmd">::cmdline::getoptions</b> <i class="arg">arglistVar</i> <i class="arg">optlist</i> <span class="opt">?<i class="arg">usage</i>?</span></a></dt>
<dd><p>Processes the set of command line options found in the list variable
named by <i class="arg">arglistVar</i> and fills in defaults for those not
specified. This also generates an error message that lists the
allowed flags if an incorrect flag is specified. The optional
<i class="arg">usage</i>-argument contains a string to include in front of the
generated message. If not present it defaults to "options:".</p>
<p><i class="arg">optlist</i> contains a list of lists where each element specifies an
option in the form: <i class="arg">flag</i> <i class="arg">default</i> <i class="arg">comment</i>.</p>
<p>If <i class="arg">flag</i> ends in ".arg" then the value is taken from the command
line. Otherwise it is a boolean and appears in the result if present
on the command line. If <i class="arg">flag</i> ends in ".secret", it will not be
displayed in the usage.</p>
<p>The options <b class="option">-?</b>, <b class="option">-help</b>, and <b class="option">--</b> are
implicitly understood. The first two abort option processing by
throwing an error and force the generation of the usage message,
whereas the the last aborts option processing without an error,
leaving all arguments coming after for regular processing, even if
starting with a dash.</p>
<p>The result of the command is a dictionary mapping all options to their
values, be they user-specified or defaults.</p></dd>
<dt><a name="4"><b class="cmd">::cmdline::getKnownOptions</b> <i class="arg">arglistVar</i> <i class="arg">optlist</i> <span class="opt">?<i class="arg">usage</i>?</span></a></dt>
<dd><p>Like <b class="cmd">::cmdline::getoptions</b>, but ignores any unknown options in the
input.</p></dd>
<dt><a name="5"><b class="cmd">::cmdline::usage</b> <i class="arg">optlist</i> <span class="opt">?<i class="arg">usage</i>?</span></a></dt>
<dd><p>Generates and returns an error message that lists the allowed
flags. <i class="arg">optlist</i> is defined as for
<b class="cmd">::cmdline::getoptions</b>. The optional <i class="arg">usage</i>-argument
contains a string to include in front of the generated message. If not
present it defaults to "options:".</p></dd>
<dt><a name="6"><b class="cmd">::cmdline::getfiles</b> <i class="arg">patterns</i> <i class="arg">quiet</i></a></dt>
<dd><p>Given a list of file <i class="arg">patterns</i> this command computes the set of
valid files. On windows, file globbing is performed on each argument.
On Unix, only file existence is tested. If a file argument produces
no valid files, a warning is optionally generated (set <i class="arg">quiet</i> to
true).</p>
<p>This code also uses the full path for each file. If not given it
prepends the current working directory to the filename. This ensures
that these files will never conflict with files in a wrapped zip
file. The last sentence refers to the pro-tools.</p></dd>
<dt><a name="7"><b class="cmd">::cmdline::getArgv0</b></a></dt>
<dd><p>This command returns the "sanitized" version of <i class="arg">argv0</i>. It will
strip off the leading path and removes the extension ".bin". The
latter is used by the pro-apps because they must be wrapped by a shell
script.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Error Codes</a></h3>
<p>Starting with version 1.5 all errors thrown by the package have a
proper <b class="variable">::errorCode</b> for use with Tcl's <b class="cmd"><a href="../try/tcllib_try.html">try</a></b> command. This
code always has the word <b class="const">CMDLINE</b> as its first element.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
package require Tcl 8.5
package require try ;# Tcllib.
package require cmdline 1.5 ;# First version with proper error-codes.
# Notes:
# - Tcl 8.6+ has 'try' as a builtin command and therefore does not
# need the 'try' package.
# - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
# This then requires a dedicated test (if) on the contents of
# ::errorCode to separate the CMDLINE USAGE signal from actual errors.
set options {
{a "set the atime only"}
{m "set the mtime only"}
{c "do not create non-existent files"}
{r.arg "" "use time from ref_file"}
{t.arg -1 "use specified time"}
}
set usage ": MyCommandName \[options] filename ...\noptions:"
try {
array set params [::cmdline::getoptions argv $options $usage]
} trap {CMDLINE USAGE} {msg o} {
# Trap the usage signal, print the message, and exit the application.
# Note: Other errors are not caught and passed through to higher levels!
puts $msg
exit 1
}
if { $params(a) } { set set_atime "true" }
set has_t [expr {$params(t) != -1}]
set has_r [expr {[string length $params(r)] > 0}]
if {$has_t && $has_r} {
return -code error "Cannot specify both -r and -t"
} elseif {$has_t} {
...
}
</pre>
<p>This example, taken (and slightly modified) from the package
<b class="package"><a href="../fileutil/fileutil.html">fileutil</a></b>, shows how to use cmdline. First, a list of
options is created, then the 'args' list is passed to cmdline for
processing. Subsequently, different options are checked to see if
they have been passed to the script, and what their value is.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>cmdline</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#argument_processing">argument processing</a>, <a href="../../../../index.html#argv">argv</a>, <a href="../../../../index.html#argv0">argv0</a>, <a href="../../../../index.html#cmdline_processing">cmdline processing</a>, <a href="../../../../index.html#command_line_processing">command line processing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/comm/comm.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
|
<div class='fossil-doc' data-title='comm - Remote communication'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">comm(n) 4.6.3 tcllib "Remote communication"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>comm - A remote communication facility for Tcl (8.3 and later)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Eval Semantics</a></li>
<li class="doctools_subsection"><a href="#subsection3">Multiple Channels</a></li>
<li class="doctools_subsection"><a href="#subsection4">Channel Configuration</a></li>
<li class="doctools_subsection"><a href="#subsection5">Id/port Assignments</a></li>
<li class="doctools_subsection"><a href="#subsection6">Execution Environment</a></li>
<li class="doctools_subsection"><a href="#subsection7">Remote Interpreters</a></li>
<li class="doctools_subsection"><a href="#subsection8">Closing Connections</a></li>
<li class="doctools_subsection"><a href="#subsection9">Callbacks</a></li>
<li class="doctools_subsection"><a href="#subsection10">Unsupported</a></li>
<li class="doctools_subsection"><a href="#subsection11">Security</a></li>
<li class="doctools_subsection"><a href="#subsection12">Blocking Semantics</a></li>
<li class="doctools_subsection"><a href="#subsection13">Asynchronous Result Generation</a></li>
<li class="doctools_subsection"><a href="#subsection14">Compatibility</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section3">Author</a></li>
<li class="doctools_section"><a href="#section4">License</a></li>
<li class="doctools_section"><a href="#section5">Bugs</a></li>
<li class="doctools_section"><a href="#section6">On Using Old Versions Of Tcl</a></li>
<li class="doctools_section"><a href="#section7">Related Work</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">comm <span class="opt">?4.6.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::comm::comm send</b> <span class="opt">?-async?</span> <span class="opt">?-command <i class="arg">callback</i>?</span> <i class="arg">id</i> <i class="arg">cmd</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::comm::comm self</b></a></li>
<li><a href="#3"><b class="cmd">::comm::comm interps</b></a></li>
<li><a href="#4"><b class="cmd">::comm::comm connect</b> <span class="opt">?<i class="arg">id</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::comm::comm new</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">name value ...</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::comm::comm channels</b></a></li>
<li><a href="#7"><b class="cmd">::comm::comm config</b></a></li>
<li><a href="#8"><b class="cmd">::comm::comm config</b> <i class="arg">name</i></a></li>
<li><a href="#9"><b class="cmd">::comm::comm config</b> <span class="opt">?<i class="arg">name</i> <i class="arg">value</i> <i class="arg">...</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::comm::comm shutdown</b> <i class="arg">id</i></a></li>
<li><a href="#11"><b class="cmd">::comm::comm abort</b></a></li>
<li><a href="#12"><b class="cmd">::comm::comm destroy</b></a></li>
<li><a href="#13"><b class="cmd">::comm::comm hook</b> <i class="arg">event</i> <span class="opt">?<b class="const">+</b>?</span> <span class="opt">?<i class="arg">script</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::comm::comm remoteid</b></a></li>
<li><a href="#15"><b class="cmd">::comm::comm_send</b></a></li>
<li><a href="#16"><b class="cmd">::comm::comm return_async</b></a></li>
<li><a href="#17"><b class="cmd">$future</b> <b class="method">return</b> <span class="opt">?<b class="option">-code</b> <i class="arg">code</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#18"><b class="cmd">$future</b> <b class="method">configure</b> <span class="opt">?<b class="option">-command</b> <span class="opt">?<i class="arg">cmdprefix</i>?</span>?</span></a></li>
<li><a href="#19"><b class="cmd">$future</b> <b class="method">cget</b> <b class="option">-command</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">comm</b> command provides an inter-interpreter remote
execution facility much like Tk's <b class="cmd">send(n)</b>, except that it uses
sockets rather than the X server for the communication path. As a
result, <b class="package">comm</b> works with multiple interpreters, works on
Windows and Macintosh systems, and provides control over the remote
execution path.</p>
<p>These commands work just like <b class="cmd"><a href="../../../../index.html#send">send</a></b> and <b class="cmd">winfo interps</b> :</p>
<pre class="doctools_example">
::comm::comm send ?-async? id cmd ?arg arg ...?
::comm::comm interps
</pre>
<p>This is all that is really needed to know in order to use
<b class="package">comm</b></p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Commands</a></h3>
<p>The package initializes <b class="cmd">::comm::comm</b> as the default <em>chan</em>.</p>
<p><b class="package">comm</b> names communication endpoints with an <em>id</em> unique
to each machine. Before sending commands, the <em>id</em> of another
interpreter is needed. Unlike Tk's send, <b class="package">comm</b> doesn't
implicitly know the <em>id</em>'s of all the interpreters on the system.
The following four methods make up the basic <b class="package">comm</b> interface.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::comm::comm send</b> <span class="opt">?-async?</span> <span class="opt">?-command <i class="arg">callback</i>?</span> <i class="arg">id</i> <i class="arg">cmd</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>This invokes the given command in the interpreter named by <i class="arg">id</i>. The
command waits for the result and remote errors are returned unless the
<b class="option">-async</b> or <b class="option">-command</b> option is given. If <b class="option">-async</b>
is given, send returns immediately and there is no further notification of
result. If <b class="option">-command</b> is used, <em>callback</em> specifies a command
to invoke when the result is received. These options are mutually
exclusive. The callback will receive arguments in the form
<em>-option value</em>, suitable for <b class="cmd">array set</b>.
The options are: <em>-id</em>, the comm id of the interpreter that received
the command; <em>-serial</em>, a unique serial for each command sent to a
particular comm interpreter; <em>-chan</em>, the comm channel name;
<em>-code</em>, the result code of the command; <em>-errorcode</em>, the
errorcode, if any, of the command; <em>-errorinfo</em>, the errorinfo, if
any, of the command; and <em>-result</em>, the return value of the command.
If connection is lost before a reply is received, the callback will be
invoked with a connection lost message with -code equal to -1. When
<b class="option">-command</b> is used, the command returns the unique serial for the
command.</p></dd>
<dt><a name="2"><b class="cmd">::comm::comm self</b></a></dt>
<dd><p>Returns the <em>id</em> for this channel.</p></dd>
<dt><a name="3"><b class="cmd">::comm::comm interps</b></a></dt>
<dd><p>Returns a list of all the remote <em>id</em>'s to which this channel is
connected. <b class="package">comm</b> learns a new remote <em>id</em> when a command
is first issued it, or when a remote <em>id</em> first issues a command
to this comm channel. <b class="cmd">::comm::comm ids</b> is an alias for this
method.</p></dd>
<dt><a name="4"><b class="cmd">::comm::comm connect</b> <span class="opt">?<i class="arg">id</i>?</span></a></dt>
<dd><p>Whereas <b class="cmd">::comm::comm send</b> will automatically connect to the
given <i class="arg">id</i>, this forces a connection to a remote <em>id</em> without
sending a command. After this, the remote <em>id</em> will appear in
<b class="cmd">::comm::comm interps</b>.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Eval Semantics</a></h3>
<p>The evaluation semantics of <b class="cmd">::comm::comm send</b> are intended to
match Tk's <b class="cmd"><a href="../../../../index.html#send">send</a></b> <em>exactly</em>. This means that <b class="package">comm</b>
evaluates arguments on the remote side.</p>
<p>If you find that <b class="cmd">::comm::comm send</b> doesn't work for a
particular command, try the same thing with Tk's send and see if the
result is different. If there is a problem, please report it. For
instance, there was had one report that this command produced an
error. Note that the equivalent <b class="cmd"><a href="../../../../index.html#send">send</a></b> command also produces the
same error.</p>
<pre class="doctools_example">
% ::comm::comm send id llength {a b c}
wrong # args: should be "llength list"
% send name llength {a b c}
wrong # args: should be "llength list"
</pre>
<p>The <b class="cmd">eval</b> hook (described below) can be used to change from
<b class="cmd"><a href="../../../../index.html#send">send</a></b>'s double eval semantics to single eval semantics.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Multiple Channels</a></h3>
<p>More than one <b class="cmd">comm</b> channel (or <em>listener</em>) can be created
in each Tcl interpreter. This allows flexibility to create full and
restricted channels. For instance, <i class="term"><a href="../../../../index.html#hook">hook</a></i> scripts are specific
to the channel they are defined against.</p>
<dl class="doctools_definitions">
<dt><a name="5"><b class="cmd">::comm::comm new</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">name value ...</i>?</span></a></dt>
<dd><p>This creates a new channel and Tcl command with the given channel
name. This new command controls the new channel and takes all the
same arguments as <b class="cmd">::comm::comm</b>. Any remaining arguments are
passed to the <b class="cmd">config</b> method. The fully qualified channel
name is returned.</p></dd>
<dt><a name="6"><b class="cmd">::comm::comm channels</b></a></dt>
<dd><p>This lists all the channels allocated in this Tcl interpreter.</p></dd>
</dl>
<p>The default configuration parameters for a new channel are:</p>
<pre class="doctools_example">
"-port 0 -local 1 -listen 0 -silent 0"
</pre>
<p>The default channel <b class="cmd">::comm::comm</b> is created with:</p>
<pre class="doctools_example">
"::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
</pre>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Channel Configuration</a></h3>
<p>The <b class="cmd">config</b> method acts similar to <b class="cmd">fconfigure</b> in that it
sets or queries configuration variables associated with a channel.</p>
<dl class="doctools_definitions">
<dt><a name="7"><b class="cmd">::comm::comm config</b></a></dt>
<dd></dd>
<dt><a name="8"><b class="cmd">::comm::comm config</b> <i class="arg">name</i></a></dt>
<dd></dd>
<dt><a name="9"><b class="cmd">::comm::comm config</b> <span class="opt">?<i class="arg">name</i> <i class="arg">value</i> <i class="arg">...</i>?</span></a></dt>
<dd><p>When given no arguments, <b class="cmd">config</b> returns a list of all variables
and their value With one argument, <b class="cmd">config</b> returns the value of
just that argument. With an even number of arguments, the given
variables are set to the given values.</p></dd>
</dl>
<p>These configuration variables can be changed (descriptions of them are
elsewhere in this manual page):</p>
<dl class="doctools_definitions">
<dt><b class="option">-listen</b> <span class="opt">?<i class="arg">0|1</i>?</span></dt>
<dd></dd>
<dt><b class="option">-local</b> <span class="opt">?<i class="arg">0|1</i>?</span></dt>
<dd></dd>
<dt><b class="option">-port</b> <span class="opt">?<i class="arg">port</i>?</span></dt>
<dd></dd>
<dt><b class="option">-silent</b> <span class="opt">?<i class="arg">0|1</i>?</span></dt>
<dd></dd>
<dt><b class="option">-socketcmd</b> <span class="opt">?<i class="arg">commandname</i>?</span></dt>
<dd></dd>
<dt><b class="option">-interp</b> <span class="opt">?<i class="arg">interpreter</i>?</span></dt>
<dd></dd>
<dt><b class="option">-events</b> <span class="opt">?<i class="arg">eventlist</i>?</span></dt>
<dd></dd>
</dl>
<p>These configuration variables are read only:</p>
<dl class="doctools_definitions">
<dt><b class="option">-chan</b> <i class="arg">chan</i></dt>
<dd></dd>
<dt><b class="option">-serial</b> <i class="arg">n</i></dt>
<dd></dd>
<dt><b class="option">-socket</b> sock<i class="arg">In</i></dt>
<dd></dd>
</dl>
<p>When <b class="cmd">config</b> changes the parameters of an existing channel (with
the exception of <b class="option">-interp</b> and <b class="option">-events</b>), it closes and
reopens the listening socket.
An automatically assigned channel <em>id</em> will change when this
happens.
Recycling the socket is done by invoking <b class="cmd">::comm::comm abort</b>,
which causes all active sends to terminate.</p>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Id/port Assignments</a></h3>
<p><b class="package">comm</b> uses a TCP port for endpoint <em>id</em>. The
<b class="method">interps</b> (or <b class="method">ids</b>) method merely lists all the TCP ports
to which the channel is connected. By default, each channel's
<em>id</em> is randomly assigned by the operating system (but usually
starts at a low value around 1024 and increases each time a new socket
is opened). This behavior is accomplished by giving the
<b class="option">-port</b> config option a value of 0. Alternately, a specific
TCP port number may be provided for a given channel. As a special
case, comm contains code to allocate a a high-numbered TCP port
(>10000) by using <b class="option">-port {}</b>. Note that a channel won't be
created and initialized unless the specific port can be allocated.</p>
<p>As a special case, if the channel is configured with
<b class="option">-listen 0</b>, then it will not create a listening socket and
will use an id of <b class="const">0</b> for itself. Such a channel is only good
for outgoing connections (although once a connection is established,
it can carry send traffic in both directions).
As another special case, if the channel is configured with
<b class="option">-silent 0</b>, then the listening side will ignore connection
attempts where the protocol negotiation phase failed, instead of
throwing an error.</p>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Execution Environment</a></h3>
<p>A communication channel in its default configuration will use the
current interpreter for the execution of all received scripts, and of
the event scripts associated with the various hooks.</p>
<p>This insecure setup can be changed by the user via the two options
<b class="option">-interp</b>, and <b class="option">-events</b>.</p>
<p>When <b class="option">-interp</b> is set all received scripts are executed in the
slave interpreter specified as the value of the option. This
interpreter is expected to exist before configuration. I.e. it is the
responsibility of the user to create it. However afterward the
communication channel takes ownership of this interpreter, and will
destroy it when the communication channel is destroyed.
Note that reconfiguration of the communication channel to either a
different interpreter or the empty string will release the ownership
<em>without</em> destroying the previously configured interpreter. The
empty string has a special meaning, it restores the default behaviour
of executing received scripts in the current interpreter.</p>
<p><em>Also of note</em> is that replies and callbacks (a special form of
reply) are <em>not</em> considered as received scripts. They are
trusted, part of the internal machinery of comm, and therefore always
executed in the current interpreter.</p>
<p>Even if an interpreter has been configured as the execution
environment for received scripts the event scripts associated with the
various hooks will by default still be executed in the current
interpreter. To change this use the option <b class="option">-events</b> to declare
a list of the events whose scripts should be executed in the declared
interpreter as well. The contents of this option are ignored if the
communication channel is configured to execute received scripts in the
current interpreter.</p>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Remote Interpreters</a></h3>
<p>By default, each channel is restricted to accepting connections from
the local system. This can be overridden by using the
<b class="option">-local 0</b> configuration option For such channels, the
<em>id</em> parameter takes the form <em>{ id host }</em>.</p>
<p><em>WARNING</em>: The <em>host</em> must always be specified in the same
form (e.g., as either a fully qualified domain name, plain hostname or
an IP address).</p>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Closing Connections</a></h3>
<p>These methods give control over closing connections:</p>
<dl class="doctools_definitions">
<dt><a name="10"><b class="cmd">::comm::comm shutdown</b> <i class="arg">id</i></a></dt>
<dd><p>This closes the connection to <i class="arg">id</i>, aborting all outstanding
commands in progress. Note that nothing prevents the connection from
being immediately reopened by another incoming or outgoing command.</p></dd>
<dt><a name="11"><b class="cmd">::comm::comm abort</b></a></dt>
<dd><p>This invokes shutdown on all open connections in this comm channel.</p></dd>
<dt><a name="12"><b class="cmd">::comm::comm destroy</b></a></dt>
<dd><p>This aborts all connections and then destroys the this comm channel
itself, including closing the listening socket. Special code allows
the default <b class="cmd">::comm::comm</b> channel to be closed such that the
<b class="cmd">::comm::comm</b> command it is not destroyed. Doing so closes the
listening socket, preventing both incoming and outgoing commands on
the channel. This sequence reinitializes the default channel:</p>
<pre class="doctools_example">
"::comm::comm destroy; ::comm::comm new ::comm::comm"
</pre>
</dd>
</dl>
<p>When a remote connection is lost (because the remote exited or called
<b class="cmd">shutdown</b>), <b class="package">comm</b> can invoke an application callback.
This can be used to cleanup or restart an ancillary process, for
instance. See the <i class="term">lost</i> callback below.</p>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Callbacks</a></h3>
<p>This is a mechanism for setting hooks for particular events:</p>
<dl class="doctools_definitions">
<dt><a name="13"><b class="cmd">::comm::comm hook</b> <i class="arg">event</i> <span class="opt">?<b class="const">+</b>?</span> <span class="opt">?<i class="arg">script</i>?</span></a></dt>
<dd><p>This uses a syntax similar to Tk's <b class="cmd"><a href="../../../../index.html#bind">bind</a></b> command. Prefixing
<i class="arg">script</i> with a <b class="const">+</b> causes the new script to be appended.
Without this, a new <i class="arg">script</i> replaces any existing script. When
invoked without a script, no change is made. In all cases, the new
hook script is returned by the command.</p>
<p>When an <i class="arg">event</i> occurs, the <i class="arg">script</i> associated with it is
evaluated with the listed variables in scope and available. The
return code (<em>not</em> the return value) of the script is commonly
used decide how to further process after the hook.</p>
<p>Common variables include:</p>
<dl class="doctools_definitions">
<dt><b class="variable">chan</b></dt>
<dd><p>the name of the comm channel (and command)</p></dd>
<dt><b class="variable">id</b></dt>
<dd><p>the id of the remote in question</p></dd>
<dt><b class="variable">fid</b></dt>
<dd><p>the file id for the socket of the connection</p></dd>
</dl></dd>
</dl>
<p>These are the defined <em>events</em>:</p>
<dl class="doctools_definitions">
<dt><b class="const">connecting</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">id</b></p>
<p>This hook is invoked before making a connection to the remote named in
<i class="arg">id</i>. An error return (via <b class="cmd"><a href="../../../../index.html#error">error</a></b>) will abort the connection
attempt with the error. Example:</p>
<pre class="doctools_example">
% ::comm::comm hook connecting {
if {[string match {*[02468]} $id]} {
error "Can't connect to even ids"
}
}
% ::comm::comm send 10000 puts ok
Connect to remote failed: Can't connect to even ids
%
</pre>
</dd>
<dt><b class="const">connected</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">fid</b>, <b class="variable">id</b>, <b class="variable">host</b>, and <b class="variable">port</b>.</p>
<p>This hook is invoked immediately after making a remote connection to
<i class="arg">id</i>, allowing arbitrary authentication over the socket named by
<i class="arg">fid</i>. An error return (via <b class="cmd"><a href="../../../../index.html#error">error</a></b> ) will close the
connection with the error. <i class="arg">host</i> and <i class="arg">port</i> are merely
extracted from the <i class="arg">id</i>; changing any of these will have no effect
on the connection, however. It is also possible to substitute and
replace <i class="arg">fid</i>.</p></dd>
<dt><b class="const">incoming</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">fid</b>, <b class="variable">addr</b>, and <b class="variable">remport</b>.</p>
<p>Hook invoked when receiving an incoming connection, allowing arbitrary
authentication over socket named by <i class="arg">fid</i>. An error return (via
<b class="cmd"><a href="../../../../index.html#error">error</a></b>) will close the connection with the error. Note that the
peer is named by <i class="arg">remport</i> and <i class="arg">addr</i> but that the remote
<em>id</em> is still unknown. Example:</p>
<pre class="doctools_example">
::comm::comm hook incoming {
if {[string match 127.0.0.1 $addr]} {
error "I don't talk to myself"
}
}
</pre>
</dd>
<dt><b class="const">eval</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">id</b>, <b class="variable">cmd</b>, and <b class="variable">buffer</b>.</p>
<p>This hook is invoked after collecting a complete script from a remote
but <em>before</em> evaluating it. This allows complete control over
the processing of incoming commands. <i class="arg">cmd</i> contains either
<b class="const">send</b> or <b class="const">async</b>. <i class="arg">buffer</i> holds the script to
evaluate. At the time the hook is called, <i class="arg">$chan remoteid</i> is
identical in value to <i class="arg">id</i>.</p>
<p>By changing <i class="arg">buffer</i>, the hook can change the script to be
evaluated. The hook can short circuit evaluation and cause a value to
be immediately returned by using <b class="cmd"><a href="../../../../index.html#return">return</a></b> <i class="arg">result</i> (or, from
within a procedure, <b class="cmd">return -code return</b> <i class="arg">result</i>). An
error return (via <b class="cmd"><a href="../../../../index.html#error">error</a></b>) will return an error result, as is if
the script caused the error. Any other return will evaluate the
script in <i class="arg">buffer</i> as normal. For compatibility with 3.2,
<b class="cmd">break</b> and <b class="cmd">return -code break</b> <i class="arg">result</i> is supported,
acting similarly to <b class="cmd">return {}</b> and <b class="cmd">return -code return</b>
<i class="arg">result</i>.</p>
<p>Examples:</p>
<ol class="doctools_enumerated">
<li><p>augmenting a command</p>
<pre class="doctools_example">
% ::comm::comm send [::comm::comm self] pid
5013
% ::comm::comm hook eval {puts "going to execute $buffer"}
% ::comm::comm send [::comm::comm self] pid
going to execute pid
5013
</pre>
</li>
<li><p>short circuiting a command</p>
<pre class="doctools_example">
% ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
% ::comm::comm send [::comm::comm self] pid
would have executed pid
0
</pre>
</li>
<li><p>Replacing double eval semantics</p>
<pre class="doctools_example">
% ::comm::comm send [::comm::comm self] llength {a b c}
wrong # args: should be "llength list"
% ::comm::comm hook eval {return [uplevel #0 $buffer]}
return [uplevel #0 $buffer]
% ::comm::comm send [::comm::comm self] llength {a b c}
3
</pre>
</li>
<li><p>Using a slave interpreter</p>
<pre class="doctools_example">
% interp create foo
% ::comm::comm hook eval {return [foo eval $buffer]}
% ::comm::comm send [::comm::comm self] set myvar 123
123
% set myvar
can't read "myvar": no such variable
% foo eval set myvar
123
</pre>
</li>
<li><p>Using a slave interpreter (double eval)</p>
<pre class="doctools_example">
% ::comm::comm hook eval {return [eval foo eval $buffer]}
</pre>
</li>
<li><p>Subverting the script to execute</p>
<pre class="doctools_example">
% ::comm::comm hook eval {
switch -- $buffer {
a {return A-OK}
b {return B-OK}
default {error "$buffer is a no-no"}
}
}
% ::comm::comm send [::comm::comm self] pid
pid is a no-no
% ::comm::comm send [::comm::comm self] a
A-OK
</pre>
</li>
</ol></dd>
<dt><b class="const">reply</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">id</b>, <b class="variable">buffer</b>, <b class="variable">ret</b>, and <b class="variable">return()</b>.</p>
<p>This hook is invoked after collecting a complete reply script from a
remote but <em>before</em> evaluating it. This allows complete
control over the processing of replies to sent commands. The reply
<i class="arg">buffer</i> is in one of the following forms</p>
<ul class="doctools_itemized">
<li><p>return result</p></li>
<li><p>return -code code result</p></li>
<li><p>return -code code -errorinfo info -errorcode ecode msg</p></li>
</ul>
<p>For safety reasons, this is decomposed. The return result is in
<i class="arg">ret</i>, and the return switches are in the return array:</p>
<ul class="doctools_itemized">
<li><p><em>return(-code)</em></p></li>
<li><p><em>return(-errorinfo)</em></p></li>
<li><p><em>return(-errorcode)</em></p></li>
</ul>
<p>Any of these may be the empty string. Modifying these four variables
can change the return value, whereas modifying <i class="arg">buffer</i> has no
effect.</p></dd>
<dt><b class="const">callback</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">id</b>, <b class="variable">buffer</b>, <b class="variable">ret</b>, and <b class="variable">return()</b>.</p>
<p>Similar to <em>reply</em>, but used for callbacks.</p></dd>
<dt><b class="const">lost</b></dt>
<dd><p>Variables:
<b class="variable">chan</b>, <b class="variable">id</b>, and <b class="variable">reason</b>.</p>
<p>This hook is invoked when the connection to <b class="variable">id</b> is lost. Return
value (or thrown error) is ignored. <i class="arg">reason</i> is an explanatory
string indicating why the connection was lost. Example:</p>
<pre class="doctools_example">
::comm::comm hook lost {
global myvar
if {$myvar(id) == $id} {
myfunc
return
}
}
</pre>
</dd>
</dl>
</div>
<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Unsupported</a></h3>
<p>These interfaces may change or go away in subsequence releases.</p>
<dl class="doctools_definitions">
<dt><a name="14"><b class="cmd">::comm::comm remoteid</b></a></dt>
<dd><p>Returns the <i class="arg">id</i> of the sender of the last remote command
executed on this channel. If used by a proc being invoked remotely,
it must be called before any events are processed. Otherwise, another
command may get invoked and change the value.</p></dd>
<dt><a name="15"><b class="cmd">::comm::comm_send</b></a></dt>
<dd><p>Invoking this procedure will substitute the Tk <b class="cmd"><a href="../../../../index.html#send">send</a></b> and
<b class="cmd">winfo interps</b> commands with these equivalents that use
<b class="cmd">::comm::comm</b>.</p>
<pre class="doctools_example">
proc send {args} {
eval ::comm::comm send $args
}
rename winfo tk_winfo
proc winfo {cmd args} {
if {![string match in* $cmd]} {
return [eval [list tk_winfo $cmd] $args]
}
return [::comm::comm interps]
}
</pre>
</dd>
</dl>
</div>
<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Security</a></h3>
<p>Starting with version 4.6 of the package an option <b class="option">-socketcmd</b>
is supported, allowing the user of a comm channel to specify which
command to use when opening a socket. Anything which is API-compatible
with the builtin <b class="cmd">::socket</b> (the default) can be used.</p>
<p>The envisioned main use is the specification of the <b class="cmd">tls::socket</b>
command, see package <b class="package"><a href="../../../../index.html#tls">tls</a></b>, to secure the communication.</p>
<pre class="doctools_example">
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured comm channel
::comm::comm new SECURE -socketcmd tls::socket -listen 1
...
</pre>
<p>The sections <span class="sectref"><a href="#subsection6">Execution Environment</a></span> and <span class="sectref"><a href="#subsection9">Callbacks</a></span>
are also relevant to the security of the system, providing means to
restrict the execution to a specific environment, perform additional
authentication, and the like.</p>
</div>
<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Blocking Semantics</a></h3>
<p>There is one outstanding difference between <b class="package">comm</b> and
<b class="cmd"><a href="../../../../index.html#send">send</a></b>. When blocking in a synchronous remote command, <b class="cmd"><a href="../../../../index.html#send">send</a></b>
uses an internal C hook (Tk_RestrictEvents) to the event loop to look
ahead for send-related events and only process those without
processing any other events. In contrast, <b class="package">comm</b> uses the
<b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b> command as a semaphore to indicate the return message has
arrived. The difference is that a synchronous <b class="cmd"><a href="../../../../index.html#send">send</a></b> will block
the application and prevent all events (including window related ones)
from being processed, while a synchronous <b class="cmd">::comm::comm send</b>
will block the application but still allow other events to get
processed. In particular, <b class="cmd">after idle</b> handlers will fire
immediately when comm blocks.</p>
<p>What can be done about this? First, note that this behavior will come
from any code using <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b> to block and wait for an event to
occur. At the cost of multiple channel support, <b class="package">comm</b> could
be changed to do blocking I/O on the socket, giving send-like blocking
semantics. However, multiple channel support is a very useful feature
of comm that it is deemed too important to lose. The remaining
approaches involve a new loadable module written in C (which is
somewhat against the philosophy of <b class="cmd">comm</b>) One way would be to
create a modified version of the <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b> command that allow the
event flags passed to Tcl_DoOneEvent to be specified. For <b class="cmd">comm</b>,
just the TCL_FILE_EVENTS would be processed. Another way would be to
implement a mechanism like Tk_RestrictEvents, but apply it to the Tcl
event loop (since <b class="package">comm</b> doesn't require Tk). One of these
approaches will be available in a future <b class="package">comm</b> release as an
optional component.</p>
</div>
<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Asynchronous Result Generation</a></h3>
<p>By default the result returned by a remotely invoked command is the
result sent back to the invoker. This means that the result is
generated synchronously, and the server handling the call is blocked
for the duration of the command.</p>
<p>While this is tolerable as long as only short-running commands are
invoked on the server long-running commands, like database queries
make this a problem. One command can prevent the processing requests
of all other clients for an arbitrary period of time.</p>
<p>Before version 4.5 of comm the only solution was to rewrite the server
command to use the Tcl builtin command <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>, or one of its
relatives like <b class="cmd">tkwait</b>, to open a new event loop which processes
requests while the long-running operation is executed. This however
has its own perils, as this makes it possible to both overflow the Tcl
stack with a large number of event loop, and to have a newer requests
block the return of older ones, as the eventloop have to be unwound in
the order of their creation.</p>
<p>The proper solution is to have the invoked command indicate to
<b class="package">comm</b> that it cannot or will not deliver an immediate,
synchronous result, but will do so later. At that point the framework
can put sending the actual result on hold and continue processing
requests using the main event loop. No blocking, no nesting of event
loops. At some future date the long running operation delivers the
result to comm, via the future object, which is then forwarded to the
invoker as usual.</p>
<p>The necessary support for this solution has been added to comm since
version 4.5, in the form of the new method <b class="method">return_async</b>.</p>
<dl class="doctools_definitions">
<dt><a name="16"><b class="cmd">::comm::comm return_async</b></a></dt>
<dd><p>This command is used by a remotely invoked script to notify the comm
channel which invoked it that the result to send back to the invoker
is not generated synchronously. If this command is not called the
default/standard behaviour of comm is to send the synchronously
generated result of the script itself to the invoker.</p>
<p>The result of <b class="cmd">return_async</b> is an object. This object, called a
<i class="term">future</i> is where the result of the script has to be delivered to
when it becomes ready. When that happens it will take all the
necessary actions to deliver the result to the invoker of the script,
and then destroy itself. Should comm have lost the connection to the
invoker while the result is being computed the future will not try to
deliver the result it got, but just destroy itself. The future can be
configured with a command to call when the invoker is lost. This
enables the user to implement an early abort of the long-running
operation, should this be supported by it.</p>
<p>An example:</p>
<pre class="doctools_example">
# Procedure invoked by remote clients to run database operations.
proc select {sql} {
# Signal the async generation of the result
set future [::comm::comm return_async]
# Generate an async db operation and tell it where to deliver the result.
set query [db query -command [list $future return] $sql]
# Tell the database system which query to cancel if the connection
# goes away while it is running.
$future configure -command [list db cancel $query]
# Note: The above will work without problem only if the async
# query will nover run its completion callback immediately, but
# only from the eventloop. Because otherwise the future we wish to
# configure may already be gone. If that is possible use 'catch'
# to prevent the error from propagating.
return
}
</pre>
<p>The API of a future object is:</p>
<dl class="doctools_definitions">
<dt><a name="17"><b class="cmd">$future</b> <b class="method">return</b> <span class="opt">?<b class="option">-code</b> <i class="arg">code</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Use this method to tell the future that long-running operation has
completed. Arguments are an optional return value (defaults to the
empty string), and the Tcl return code (defaults to OK).</p>
<p>The future will deliver this information to invoker, if the connection
was not lost in the meantime, and then destroy itself. If the
connection was lost it will do nothing but destroy itself.</p></dd>
<dt><a name="18"><b class="cmd">$future</b> <b class="method">configure</b> <span class="opt">?<b class="option">-command</b> <span class="opt">?<i class="arg">cmdprefix</i>?</span>?</span></a></dt>
<dd></dd>
<dt><a name="19"><b class="cmd">$future</b> <b class="method">cget</b> <b class="option">-command</b></a></dt>
<dd><p>These methods allow the user to retrieve and set a command to be
called if the connection the future belongs to has been lost.</p></dd>
</dl></dd>
</dl>
</div>
<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Compatibility</a></h3>
<p><b class="package">comm</b> exports itself as a package. The package version number
is in the form <em>major . minor</em>, where the major version will
only change when a non-compatible change happens to the API or
protocol. Minor bug fixes and changes will only affect the minor
version. To load <b class="package">comm</b> this command is usually used:</p>
<pre class="doctools_example">
package require comm 3
</pre>
<p>Note that requiring no version (or a specific version) can also be done.</p>
<p>The revision history of <b class="package">comm</b> includes these releases:</p>
<dl class="doctools_definitions">
<dt>4.6.3</dt>
<dd><p>Fixed ticket [ced0d60fc9]. Added proper detection of eof on a
socket, properly closing it.</p></dd>
<dt>4.6.2</dt>
<dd><p>Fixed bugs 2972571 and 3066872, the first a misdetection of quoted
brace after double backslash, the other a blocking gets making for an
obvious (hinsight) DoS attack on comm channels.</p></dd>
<dt>4.6.1</dt>
<dd><p>Changed the implementation of <b class="cmd">comm::commCollect</b> to emulate
lindex's pre-Tcl 8 behaviour, i.e. it was given the ability to parse
out the first word of a list, even if the whole buffer is not a
well-formed list. Without this change the first word could only be
extracted if the whole buffer was a well-formed list (ever since Tcl
8), and in a ver-high-load situation, i.e. a server sending lots
and/or large commands very fast, this may never happen, eventually
crashing the receiver when it runs out of memory. With the change the
receiver is always able to process the first word when it becomes
well-formed, regardless of the structure of the remainder of the
buffer.</p></dd>
<dt>4.6</dt>
<dd><p>Added the option <b class="option">-socketcmd</b> enabling users to override how a
socket is opened. The envisioned main use is the specification of the
<b class="cmd">tls::socket</b> command, see package <b class="package"><a href="../../../../index.html#tls">tls</a></b>, to secure the
communication.</p></dd>
<dt>4.5.7</dt>
<dd><p>Changed handling of ports already in use to provide a proper error
message.</p></dd>
<dt>4.5.6</dt>
<dd><p>Bugfix in the replacement for <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>, made robust against of
variable names containing spaces.</p></dd>
<dt>4.5.5</dt>
<dd><p>Bugfix in the handling of hooks, typo in variable name.</p></dd>
<dt>4.5.4</dt>
<dd><p>Bugfix in the handling of the result received by the <b class="method">send</b>
method. Replaced an <em>after idle unset result</em> with an immediate
<b class="cmd">unset</b>, with the information saved to a local variable.</p>
<p>The <b class="cmd">after idle</b> can spill into a forked child process if there
is no event loop between its setup and the fork. This may bork the
child if the next event loop is the <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b> of <b class="package">comm</b>'s
<b class="method">send</b> a few lines above the <b class="cmd">after idle</b>, and the child
used the same serial number for its next request. In that case the
parent's <b class="cmd">after idle unset</b> will delete the very array element
the child is waiting for, unlocking the <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>, causing it to
access a now missing array element, instead of the expected result.</p></dd>
<dt>4.5.3</dt>
<dd><p>Bugfixes in the wrappers for the builtin <b class="cmd"><a href="../../../../index.html#update">update</a></b> and <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>
commands.</p></dd>
<dt>4.5.2</dt>
<dd><p>Bugfix in the wrapper for the builtin <b class="cmd"><a href="../../../../index.html#update">update</a></b> command.</p></dd>
<dt>4.5.1</dt>
<dd><p>Bugfixes in the handling of -interp for regular scripts. The handling
of the buffer was wrong for scripts which are a single statement as
list. Fixed missing argument to new command <b class="cmd">commSendReply</b>,
introduced by version 4.5. Affected debugging.</p></dd>
<dt>4.5</dt>
<dd><p>New server-side feature. The command invoked on the server can now
switch comm from the standard synchronous return of its result to an
asynchronous (defered) return. Due to the use of snit to implement the
<i class="term">future</i> objects used by this feature from this version on comm
requires at least Tcl 8.3 to run. Please read the section
<span class="sectref"><a href="#subsection13">Asynchronous Result Generation</a></span> for more details.</p></dd>
<dt>4.4.1</dt>
<dd><p>Bugfix in the execution of hooks.</p></dd>
<dt>4.4</dt>
<dd><p>Bugfixes in the handling of -interp for regular and hook
scripts. Bugfixes in channel cleanup.</p></dd>
<dt>4.3.1</dt>
<dd><p>Introduced -interp and -events to enable easy use of a slave interp
for execution of received scripts, and of event scripts.</p></dd>
<dt>4.3</dt>
<dd><p>Bugfixes, and introduces -silent to allow the user to force the
server/listening side to silently ignore connection attempts where the
protocol negotiation failed.</p></dd>
<dt>4.2</dt>
<dd><p>Bugfixes, and most important, switched to utf-8 as default encoding
for full i18n without any problems.</p></dd>
<dt>4.1</dt>
<dd><p>Rewrite of internal code to remove old pseudo-object model. Addition
of send -command asynchronous callback option.</p></dd>
<dt>4.0</dt>
<dd><p>Per request by John LoVerso. Improved handling of error for async
invoked commands.</p></dd>
<dt>3.7</dt>
<dd><p>Moved into tcllib and placed in a proper namespace.</p></dd>
<dt>3.6</dt>
<dd><p>A bug in the looking up of the remoteid for a executed command could
be triggered when the connection was closed while several asynchronous
sends were queued to be executed.</p></dd>
<dt>3.5</dt>
<dd><p>Internal change to how reply messages from a <b class="cmd"><a href="../../../../index.html#send">send</a></b> are handled.
Reply messages are now decoded into the <i class="arg">value</i> to pass to
<b class="cmd"><a href="../../../../index.html#return">return</a></b>; a new return statement is then cons'd up to with this
value. Previously, the return code was passed in from the remote as a
command to evaluate. Since the wire protocol has not changed, this is
still the case. Instead, the reply handling code decodes the
<b class="const">reply</b> message.</p></dd>
<dt>3.4</dt>
<dd><p>Added more source commentary, as well as documenting config variables
in this man page. Fixed bug were loss of connection would give error
about a variable named <b class="variable">pending</b> rather than the message about
the lost connection. <b class="cmd">comm ids</b> is now an alias for
<b class="cmd">comm interps</b> (previously, it an alias for <b class="cmd">comm chans</b>).
Since the method invocation change of 3.0, break and other exceptional
conditions were not being returned correctly from <b class="cmd">comm send</b>.
This has been fixed by removing the extra level of indirection into
the internal procedure <b class="cmd">commSend</b>. Also added propagation of
the <i class="arg">errorCode</i> variable. This means that these commands return
exactly as they would with <b class="cmd"><a href="../../../../index.html#send">send</a></b>:</p>
<pre class="doctools_example">
comm send id break
catch {comm send id break}
comm send id expr 1 / 0
</pre>
<p>Added a new hook for reply messages. Reworked method invocation to
avoid the use of comm:* procedures; this also cut the invocation time
down by 40%. Documented <b class="cmd">comm config</b> (as this manual page
still listed the defunct <b class="cmd">comm init</b>!)</p></dd>
<dt>3.3</dt>
<dd><p>Some minor bugs were corrected and the documentation was cleaned up.
Added some examples for hooks. The return semantics of the <b class="cmd">eval</b>
hook were changed.</p></dd>
<dt>3.2</dt>
<dd><p>A new wire protocol, version 3, was added. This is backwards
compatible with version 2 but adds an exchange of supported protocol
versions to allow protocol negotiation in the future. Several bugs
with the hook implementation were fixed. A new section of the man
page on blocking semantics was added.</p></dd>
<dt>3.1</dt>
<dd><p>All the documented hooks were implemented. <b class="cmd">commLostHook</b> was
removed. A bug in <b class="cmd">comm new</b> was fixed.</p></dd>
<dt>3.0</dt>
<dd><p>This is a new version of <b class="package">comm</b> with several major changes.
There is a new way of creating the methods available under the
<b class="cmd">comm</b> command. The <b class="cmd">comm init</b> method has been retired
and is replaced by <b class="cmd">comm configure</b> which allows access to many
of the well-defined internal variables. This also generalizes the
options available to <b class="cmd">comm new</b>. Finally, there is now a
protocol version exchanged when a connection is established. This
will allow for future on-wire protocol changes. Currently, the
protocol version is set to 2.</p></dd>
<dt>2.3</dt>
<dd><p><b class="cmd">comm ids</b> was renamed to <b class="cmd">comm channels</b>. General
support for <b class="cmd">comm hook</b> was fully implemented, but only the
<i class="term">lost</i> hook exists, and it was changed to follow the general
hook API. <b class="cmd">commLostHook</b> was unsupported (replaced by
<b class="cmd">comm hook lost</b>) and <b class="cmd">commLost</b> was removed.</p></dd>
<dt>2.2</dt>
<dd><p>The <i class="term">died</i> hook was renamed <i class="term">lost</i>, to be accessed by
<b class="cmd">commLostHook</b> and an early implementation of
<b class="cmd">comm lost hook</b>. As such, <b class="cmd">commDied</b> is now
<b class="cmd">commLost</b>.</p></dd>
<dt>2.1</dt>
<dd><p>Unsupported method <b class="cmd">comm remoteid</b> was added.</p></dd>
<dt>2.0</dt>
<dd><p><b class="package">comm</b> has been rewritten from scratch (but is fully compatible
with Comm 1.0, without the requirement to use obTcl).</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Author</a></h2>
<p>John LoVerso, [email protected]</p>
<p><em>http://www.opengroup.org/~loverso/tcl-tk/#comm</em></p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">License</a></h2>
<p>Please see the file <em>comm.LICENSE</em> that accompanied this source,
or
<a href="http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html">http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html</a>.</p>
<p>This license for <b class="package">comm</b>, new as of version 3.2, allows it to be
used for free, without any licensing fee or royalty.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs</a></h2>
<ul class="doctools_itemized">
<li><p>If there is a failure initializing a channel created with
<b class="cmd">::comm::comm new</b>, then the channel should be destroyed.
Currently, it is left in an inconsistent state.</p></li>
<li><p>There should be a way to force a channel to quiesce when changing the
configuration.</p></li>
</ul>
<p>The following items can be implemented with the existing hooks and are
listed here as a reminder to provide a sample hook in a future
version.</p>
<ul class="doctools_itemized">
<li><p>Allow easier use of a slave interp for actual command execution
(especially when operating in "not local" mode).</p></li>
<li><p>Add host list (xhost-like) or "magic cookie" (xauth-like)
authentication to initial handshake.</p></li>
</ul>
<p>The following are outstanding todo items.</p>
<ul class="doctools_itemized">
<li><p>Add an interp discovery and name->port mapping. This is likely to be
in a separate, optional nameserver. (See also the related work,
below.)</p></li>
<li><p>Fix the <em>{id host}</em> form so as not to be dependent upon
canonical hostnames. This requires fixes to Tcl to resolve hostnames!</p></li>
</ul>
<p>This man page is bigger than the source file.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">On Using Old Versions Of Tcl</a></h2>
<p>Tcl7.5 under Windows contains a bug that causes the interpreter to
hang when EOF is reached on non-blocking sockets. This can be
triggered with a command such as this:</p>
<pre class="doctools_example">
"comm send $other exit"
</pre>
<p>Always make sure the channel is quiescent before closing/exiting or
use at least Tcl7.6 under Windows.</p>
<p>Tcl7.6 on the Mac contains several bugs. It is recommended you use
at least Tcl7.6p2.</p>
<p>Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended
you use Tcl8.0p1 (or Tcl7.6p2).</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Related Work</a></h2>
<p>Tcl-DP provides an RPC-based remote execution interface, but is a
compiled Tcl extension. See
<a href="http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html">http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html</a>.</p>
<p>Michael Doyle <[email protected]> has code that implements the Tcl-DP
RPC interface using standard Tcl sockets, much like <b class="package">comm</b>.
The DpTcl package is available at
<a href="http://chiselapp.com/user/gwlester/repository/DpTcl">http://chiselapp.com/user/gwlester/repository/DpTcl</a>.</p>
<p>Andreas Kupries <[email protected]> uses
<b class="package">comm</b> and has built a simple nameserver as part of his Pool
library. See <a href="http://www.purl.org/net/akupries/soft/pool/index.htm">http://www.purl.org/net/akupries/soft/pool/index.htm</a>.</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>comm</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>send(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comm">comm</a>, <a href="../../../../index.html#communication">communication</a>, <a href="../../../../index.html#ipc">ipc</a>, <a href="../../../../index.html#message">message</a>, <a href="../../../../index.html#remote_communication">remote communication</a>, <a href="../../../../index.html#remote_execution">remote execution</a>, <a href="../../../../index.html#rpc">rpc</a>, <a href="../../../../index.html#secure">secure</a>, <a href="../../../../index.html#send">send</a>, <a href="../../../../index.html#socket">socket</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 1995-1998 The Open Group. All Rights Reserved.<br>
Copyright © 2003-2004 ActiveState Corporation.<br>
Copyright © 2006-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/comm/comm_wire.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
<div class='fossil-doc' data-title='comm_wire - Remote communication'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">comm_wire(n) 3 tcllib "Remote communication"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>comm_wire - The comm wire protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Wire Protocol Version 3</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Basic Layer</a></li>
<li class="doctools_subsection"><a href="#subsection2">Basic Message Layer</a></li>
<li class="doctools_subsection"><a href="#subsection3">Negotiation Messages - Initial Handshake</a></li>
<li class="doctools_subsection"><a href="#subsection4">Script/Command Messages</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">comm</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package"><a href="comm.html">comm</a></b> command provides an inter-interpreter remote
execution facility much like Tk's <b class="cmd">send(n)</b>, except that it uses
sockets rather than the X server for the communication path. As a
result, <b class="package"><a href="comm.html">comm</a></b> works with multiple interpreters, works on
Windows and Macintosh systems, and provides control over the remote
execution path.</p>
<p>This document contains a specification of the various versions of the
wire protocol used by comm internally for the communication between
its endpoints. It has no relevance to users of <b class="package"><a href="comm.html">comm</a></b>, only to
developers who wish to modify the package, write a compatible facility
in a different language, or some other facility based on the same
protocol.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Wire Protocol Version 3</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Basic Layer</a></h3>
<p>The basic encoding for <em>all</em> data is UTF-8. Because of this
binary data, including the NULL character, can be sent over the wire
as is, without the need for armoring it.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic Message Layer</a></h3>
<p>On top of the <span class="sectref"><a href="#subsection1">Basic Layer</a></span> we have a
<i class="term">message oriented</i> exchange of data.
The totality of all characters written to the channel is a Tcl list,
with each element a separate <i class="term"><a href="../../../../index.html#message">message</a></i>, each itself a list. The
messages in the overall list are separated by EOL. Note that EOL
characters can occur within the list as well. They can be
distinguished from the message-separating EOL by the fact that the
data from the beginning up to their location is not a valid Tcl list.</p>
<p>EOL is signaled through the linefeed character, i.e <b class="const">LF</b>, or,
hex <b class="const">0x0a</b>. This is following the unix convention for
line-endings.</p>
<p>As a list each message is composed of <i class="term">words</i>. Their meaning
depends on when the message was sent in the overall exchange. This is
described in the upcoming sections.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Negotiation Messages - Initial Handshake</a></h3>
<p>The command protocol is defined like this:</p>
<ul class="doctools_itemized">
<li><p>The first message send by a client to a server, when opening the
connection, contains two words. The first word is a list as well, and
contains the versions of the wire protocol the client is willing to
accept, with the most preferred version first. The second word is the
TCP port the client is listening on for connections to itself. The
value <b class="const">0</b> is used here to signal that the client will not listen
for connections, i.e. that it is purely for sending commands, and not
receiving them.</p></li>
<li><p>The first message sent by the server to the client, in response to the
message above contains only one word. This word is a list, containing
the string <b class="const">vers</b> as its first element, and the version of the
wire protocol the server has selected from the offered versions as the
second.</p></li>
</ul>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Script/Command Messages</a></h3>
<p>All messages coming after the <span class="sectref"><a href="#subsection3">initial handshake</a></span>
consist of three words. These are an instruction, a transaction id,
and the payload. The valid instructions are shown below. The
transaction ids are used by the client to match any incoming replies
to the command messages it sent. This means that a server has to copy
the transaction id from a command message to the reply it sends for
that message.</p>
<dl class="doctools_definitions">
<dt><b class="const">send</b></dt>
<dd></dd>
<dt><b class="const">async</b></dt>
<dd></dd>
<dt><b class="const">command</b></dt>
<dd><p>The payload is the Tcl script to execute on the server. It is actually
a list containing the script fragments. These fragment are
<b class="cmd">concat</b>enated together by the server to form the full script to
execute on the server side.
This emulates the Tcl "eval" semantics.
In most cases it is best to have only one word in the list, a list
containing the exact command.</p>
<p>Examples:</p>
<pre class="doctools_example">
(a) {send 1 {{array get tcl_platform}}}
(b) {send 1 {array get tcl_platform}}
(c) {send 1 {array {get tcl_platform}}}
are all valid representations of the same command. They are
generated via
(a') send {array get tcl_platform}
(b') send array get tcl_platform
(c') send array {get tcl_platform}
respectively
</pre>
<p>Note that (a), generated by (a'), is the usual form, if only single
commands are sent by the client.
For example constructed using <b class="cmd"><a href="../../../../index.html#list">list</a></b>, if the command contains
variable arguments. Like</p>
<pre class="doctools_example">
send [list array get $the_variable]
</pre>
<p>These three instructions all invoke the script on the server
side. Their difference is in the treatment of result values, and thus
determines if a reply is expected.</p>
<dl class="doctools_definitions">
<dt><b class="const">send</b></dt>
<dd><p>A reply is expected. The sender is waiting for the result.</p></dd>
<dt><b class="const">async</b></dt>
<dd><p>No reply is expected, the sender has no interest in the result and is
not waiting for any.</p></dd>
<dt><b class="const">command</b></dt>
<dd><p>A reply is expected, but the sender is not waiting for it. It has
arranged to get a process-internal notification when the result
arrives.</p></dd>
</dl></dd>
<dt><b class="const">reply</b></dt>
<dd><p>Like the previous three command, however the tcl script in the payload
is highly restricted.
It has to be a syntactically valid Tcl <b class="cmd"><a href="../../../../index.html#return">return</a></b> command. This
contains result code, value, error code, and error info.</p>
<p>Examples:</p>
<pre class="doctools_example">
{reply 1 {return -code 0 {}}}
{reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}
</pre>
</dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>comm</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="comm.html">comm</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comm">comm</a>, <a href="../../../../index.html#communication">communication</a>, <a href="../../../../index.html#ipc">ipc</a>, <a href="../../../../index.html#message">message</a>, <a href="../../../../index.html#remote_communication">remote communication</a>, <a href="../../../../index.html#remote_execution">remote execution</a>, <a href="../../../../index.html#rpc">rpc</a>, <a href="../../../../index.html#socket">socket</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Docs. Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/control/control.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
<div class='fossil-doc' data-title='control - Tcl Control Flow Commands'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">control(n) 0.1.3 tcllib "Tcl Control Flow Commands"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>control - Procedures for control flow structures.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">LIMITATIONS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">control <span class="opt">?0.1.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">control::control</b> <i class="arg">command</i> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">control::assert</b> <i class="arg">expr</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">control::do</b> <i class="arg">body</i> <span class="opt">?<i class="arg">option test</i>?</span></a></li>
<li><a href="#4"><b class="cmd">control::no-op</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">control</b> package provides a variety of commands that provide
additional flow of control structures beyond the built-in ones
provided by Tcl. These are commands that in many programming
languages might be considered <em>keywords</em>, or a part of the
language itself. In Tcl, control flow structures are just commands
like everything else.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">control::control</b> <i class="arg">command</i> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The <b class="cmd">control</b> command is used as a configuration command for
customizing the other public commands of the control package. The
<i class="arg">command</i> argument names the command to be customized. The set of
valid <i class="arg">option</i> and subsequent arguments are determined by the
command being customized, and are documented with the command.</p></dd>
<dt><a name="2"><b class="cmd">control::assert</b> <i class="arg">expr</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>When disabled, the <b class="cmd"><a href="../../../../index.html#assert">assert</a></b> command behaves exactly like the
<b class="cmd"><a href="../../../../index.html#no_op">no-op</a></b> command.</p>
<p>When enabled, the <b class="cmd"><a href="../../../../index.html#assert">assert</a></b> command evaluates <i class="arg">expr</i> as an
expression (in the same way that <b class="cmd">expr</b> evaluates its argument).
If evaluation reveals that <i class="arg">expr</i> is not a valid boolean
expression (according to [<b class="cmd">string is boolean -strict</b>]),
an error is raised. If <i class="arg">expr</i> evaluates to a true boolean value
(as recognized by <b class="cmd">if</b>), then <b class="cmd"><a href="../../../../index.html#assert">assert</a></b> returns an empty
string. Otherwise, the remaining arguments to <b class="cmd"><a href="../../../../index.html#assert">assert</a></b> are used
to construct a message string. If there are no arguments, the message
string is "assertion failed: $expr". If there are arguments, they are
joined by <b class="cmd"><a href="../../../../index.html#join">join</a></b> to form the message string. The message string
is then appended as an argument to a callback command, and the
completed callback command is evaluated in the global namespace.</p>
<p>The <b class="cmd"><a href="../../../../index.html#assert">assert</a></b> command can be customized by the <b class="cmd">control</b>
command in two ways:</p>
<p>[<b class="cmd">control::control assert enabled</b> <span class="opt">?<i class="arg">boolean</i>?</span>]
queries or sets whether <b class="cmd">control::assert</b> is enabled. When called
without a <i class="arg">boolean</i> argument, a boolean value is returned
indicating whether the <b class="cmd">control::assert</b> command is enabled. When
called with a valid boolean value as the <i class="arg">boolean</i> argument, the
<b class="cmd">control::assert</b> command is enabled or disabled to match the
argument, and an empty string is returned.</p>
<p>[<b class="cmd">control::control assert callback</b> <span class="opt">?<i class="arg">command</i>?</span>]
queries or sets the callback command that will be called by an enabled
<b class="cmd"><a href="../../../../index.html#assert">assert</a></b> on assertion failure. When called without a
<i class="arg">command</i> argument, the current callback command is returned.
When called with a <i class="arg">command</i> argument, that argument becomes the
new assertion failure callback command. Note that an assertion
failure callback command is always defined, even when <b class="cmd"><a href="../../../../index.html#assert">assert</a></b>
is disabled. The default callback command is
[<b class="cmd">return -code error</b>].</p>
<p>Note that <b class="cmd">control::assert</b> has been written so that in
combination with [<b class="cmd">namespace import</b>], it is possible to
use enabled <b class="cmd"><a href="../../../../index.html#assert">assert</a></b> commands in some namespaces and disabled
<b class="cmd"><a href="../../../../index.html#assert">assert</a></b> commands in other namespaces at the same time. This
capability is useful so that debugging efforts can be independently
controlled module by module.</p>
<pre class="doctools_example">
% package require control
% control::control assert enabled 1
% namespace eval one namespace import ::control::assert
% control::control assert enabled 0
% namespace eval two namespace import ::control::assert
% one::assert {1 == 0}
assertion failed: 1 == 0
% two::assert {1 == 0}
</pre>
</dd>
<dt><a name="3"><b class="cmd">control::do</b> <i class="arg">body</i> <span class="opt">?<i class="arg">option test</i>?</span></a></dt>
<dd><p>The <b class="cmd"><a href="../../../../index.html#do">do</a></b> command evaluates the script <i class="arg">body</i> repeatedly
<em>until</em> the expression <i class="arg">test</i> becomes true or as long as
(<em>while</em>) <i class="arg">test</i> is true, depending on the value of
<i class="arg">option</i> being <b class="const">until</b> or <b class="const">while</b>. If
<i class="arg">option</i> and <i class="arg">test</i> are omitted the body is evaluated exactly
once. After normal completion, <b class="cmd"><a href="../../../../index.html#do">do</a></b> returns an empty string.
Exceptional return codes (<b class="cmd">break</b>, <b class="cmd">continue</b>, <b class="cmd"><a href="../../../../index.html#error">error</a></b>,
etc.) during the evaluation of <i class="arg">body</i> are handled in the same way
the <b class="cmd">while</b> command handles them, except as noted in
<span class="sectref"><a href="#section3">LIMITATIONS</a></span>, below.</p></dd>
<dt><a name="4"><b class="cmd">control::no-op</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The <b class="cmd"><a href="../../../../index.html#no_op">no-op</a></b> command takes any number of arguments and does
nothing. It returns an empty string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">LIMITATIONS</a></h2>
<p>Several of the commands provided by the <b class="cmd">control</b> package accept
arguments that are scripts to be evaluated. Due to fundamental
limitations of Tcl's <b class="cmd">catch</b> and <b class="cmd"><a href="../../../../index.html#return">return</a></b> commands, it is not
possible for these commands to properly evaluate the command
[<b class="cmd">return -code $code</b>] within one of those script
arguments for any value of <i class="arg">$code</i> other than <i class="arg">ok</i>. In this
way, the commands of the <b class="cmd">control</b> package are limited as compared
to Tcl's built-in control flow commands (such as <b class="cmd">if</b>,
<b class="cmd">while</b>, etc.) and those control flow commands that can be
provided by packages coded in C. An example of this difference:</p>
<pre class="doctools_example">
% package require control
% proc a {} {while 1 {return -code error a}}
% proc b {} {control::do {return -code error b} while 1}
% catch a
1
% catch b
0
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>control</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>break, continue, expr, if, <a href="../../../../index.html#join">join</a>, namespace, <a href="../../../../index.html#return">return</a>, <a href="../../../../index.html#string">string</a>, while</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#assert">assert</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#do">do</a>, <a href="../../../../index.html#flow">flow</a>, <a href="../../../../index.html#no_op">no-op</a>, <a href="../../../../index.html#structure">structure</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/coroutine/coro_auto.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<div class='fossil-doc' data-title='coroutine::auto - Coroutine utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">coroutine::auto(n) 1.1.3 tcllib "Coroutine utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>coroutine::auto - Automatic event and IO coroutine awareness</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">coroutine::auto 1.1.3</b></li>
<li>package require <b class="pkgname">coroutine 1.1</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">coroutine::auto</b> package provides no commands or other
directly visible functionality.
Built on top of the package <b class="package"><a href="tcllib_coroutine.html">coroutine</a></b>, it intercepts various
builtin commands of the Tcl core to make any code using them
coroutine-oblivious, i.e. able to run inside and outside of a
coroutine without changes.</p>
<p>The commands so affected by this package are</p>
<dl class="doctools_definitions">
<dt><b class="cmd"><a href="../../../../index.html#after">after</a></b></dt>
<dd></dd>
<dt><b class="cmd"><a href="../../../../index.html#exit">exit</a></b></dt>
<dd></dd>
<dt><b class="cmd"><a href="../../../../index.html#gets">gets</a></b></dt>
<dd></dd>
<dt><b class="cmd"><a href="../../../../index.html#global">global</a></b></dt>
<dd></dd>
<dt><b class="cmd"><a href="../../../../index.html#read">read</a></b></dt>
<dd></dd>
<dt><b class="cmd"><a href="../../../../index.html#update">update</a></b></dt>
<dd></dd>
<dt><b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b></dt>
<dd></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>coroutine</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#after">after</a>, <a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#coroutine">coroutine</a>, <a href="../../../../index.html#events">events</a>, <a href="../../../../index.html#exit">exit</a>, <a href="../../../../index.html#gets">gets</a>, <a href="../../../../index.html#global">global</a>, <a href="../../../../index.html#green_threads">green threads</a>, <a href="../../../../index.html#read">read</a>, <a href="../../../../index.html#threads">threads</a>, <a href="../../../../index.html#update">update</a>, <a href="../../../../index.html#vwait">vwait</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Coroutine</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010-2014 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
<div class='fossil-doc' data-title='coroutine - Coroutine utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">coroutine(n) 1.2 tcllib "Coroutine utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>coroutine - Coroutine based event and IO handling</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">coroutine 1.2</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">coroutine::util after</b> <i class="arg">delay</i></a></li>
<li><a href="#2"><b class="cmd">coroutine::util await</b> <i class="arg">varname</i>...</a></li>
<li><a href="#3"><b class="cmd">coroutine::util create</b> <i class="arg">arg</i>...</a></li>
<li><a href="#4"><b class="cmd">coroutine::util exit</b> <span class="opt">?<i class="arg">status</i>?</span></a></li>
<li><a href="#5"><b class="cmd">coroutine::util gets</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">varname</i>?</span></a></li>
<li><a href="#6"><b class="cmd">coroutine::util gets_safety</b> <i class="arg">chan</i> <i class="arg">limit</i> <i class="arg">varname</i></a></li>
<li><a href="#7"><b class="cmd">coroutine::util global</b> <i class="arg">varname</i>...</a></li>
<li><a href="#8"><b class="cmd">coroutine::util read</b> <b class="option">-nonewline</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#9"><b class="cmd">coroutine::util update</b> <span class="opt">?<b class="const">idletasks</b>?</span></a></li>
<li><a href="#10"><b class="cmd">coroutine::util vwait</b> <i class="arg">varname</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">coroutine</b> package provides coroutine-aware
implementations of various event- and channel related commands. It can
be in multiple modes:</p>
<ol class="doctools_enumerated">
<li><p>Call the commands through their ensemble, in code which is
explicitly written for use within coroutines.</p></li>
<li><p>Import the commands into a namespace, either directly, or
through <b class="cmd">namespace path</b>. This allows the use from within code
which is not coroutine-aware per se and restricted to specific
namespaces.</p></li>
</ol>
<p>A more agressive form of making code coroutine-oblivious than point 2
above is available through the package <b class="package"><a href="coro_auto.html">coroutine::auto</a></b>,
which intercepts the relevant builtin commands and changes their
implementation dependending on the context they are run in, i.e.
inside or outside of a coroutine.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>All the commands listed below are synchronous with respect to the
coroutine invoking them, i.e. this coroutine blocks until the result
is available. The overall eventloop is not blocked however.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">coroutine::util after</b> <i class="arg">delay</i></a></dt>
<dd><p>This command delays the coroutine invoking it by <i class="arg">delay</i>
milliseconds.</p></dd>
<dt><a name="2"><b class="cmd">coroutine::util await</b> <i class="arg">varname</i>...</a></dt>
<dd><p>This command is an extension form of the <b class="cmd">coroutine::util vwait</b>
command (see below) which waits on a write to one of many named
namespace variables.</p></dd>
<dt><a name="3"><b class="cmd">coroutine::util create</b> <i class="arg">arg</i>...</a></dt>
<dd><p>This command creates a new coroutine with an automatically assigned
name and causes it to run the code specified by the arguments.</p></dd>
<dt><a name="4"><b class="cmd">coroutine::util exit</b> <span class="opt">?<i class="arg">status</i>?</span></a></dt>
<dd><p>This command exits the current coroutine, causing it to return
<i class="arg">status</i>. If no status was specified the default <i class="arg">0</i> is
returned.</p></dd>
<dt><a name="5"><b class="cmd">coroutine::util gets</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">varname</i>?</span></a></dt>
<dd><p>This command reads a line from the channel <i class="arg">chan</i> and returns it
either as its result, or, if a <i class="arg">varname</i> was specified, writes it
to the named variable and returns the number of characters read.</p></dd>
<dt><a name="6"><b class="cmd">coroutine::util gets_safety</b> <i class="arg">chan</i> <i class="arg">limit</i> <i class="arg">varname</i></a></dt>
<dd><p>This command reads a line from the channel <i class="arg">chan</i> up to size <i class="arg">limit</i>
and stores the result in <i class="arg">varname</i>. Of <i class="arg">limit</i> is reached before the
set first newline, an error is thrown. The command returns the number of
characters read.</p></dd>
<dt><a name="7"><b class="cmd">coroutine::util global</b> <i class="arg">varname</i>...</a></dt>
<dd><p>This command imports the named global variables of the coroutine into
the current scope. From the technical point of view these variables
reside in level <b class="const">#1</b> of the Tcl stack. I.e. these are not the
regular global variable in to the global namespace, and each coroutine
can have their own set, independent of all others.</p></dd>
<dt><a name="8"><b class="cmd">coroutine::util read</b> <b class="option">-nonewline</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>This command reads <i class="arg">n</i> characters from the channel <i class="arg">chan</i> and
returns them as its result. If <i class="arg">n</i> is not specified the command
will read the channel until EOF is reached.</p></dd>
<dt><a name="9"><b class="cmd">coroutine::util update</b> <span class="opt">?<b class="const">idletasks</b>?</span></a></dt>
<dd><p>This command causes the coroutine invoking it to run pending events or
idle handlers before proceeding.</p></dd>
<dt><a name="10"><b class="cmd">coroutine::util vwait</b> <i class="arg">varname</i></a></dt>
<dd><p>This command causes the coroutine calling it to wait for a write to
the named namespace variable <i class="arg">varname</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>coroutine</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#after">after</a>, <a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#coroutine">coroutine</a>, <a href="../../../../index.html#events">events</a>, <a href="../../../../index.html#exit">exit</a>, <a href="../../../../index.html#gets">gets</a>, <a href="../../../../index.html#global">global</a>, <a href="../../../../index.html#green_threads">green threads</a>, <a href="../../../../index.html#read">read</a>, <a href="../../../../index.html#threads">threads</a>, <a href="../../../../index.html#update">update</a>, <a href="../../../../index.html#vwait">vwait</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Coroutine</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010-2015 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/counter/counter.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
|
<div class='fossil-doc' data-title='counter - Counters and Histograms'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">counter(n) 2.0.4 tcllib "Counters and Histograms"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>counter - Procedures for counters and histograms</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">counter <span class="opt">?2.0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::counter::init</b> <i class="arg">tag args</i></a></li>
<li><a href="#2"><b class="cmd">::counter::count</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">delta</i>?</span> <span class="opt">?<i class="arg">instance</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::counter::start</b> <i class="arg">tag instance</i></a></li>
<li><a href="#4"><b class="cmd">::counter::stop</b> <i class="arg">tag instance</i></a></li>
<li><a href="#5"><b class="cmd">::counter::get</b> <i class="arg">tag args</i></a></li>
<li><a href="#6"><b class="cmd">::counter::exists</b> <i class="arg">tag</i></a></li>
<li><a href="#7"><b class="cmd">::counter::names</b></a></li>
<li><a href="#8"><b class="cmd">::counter::histHtmlDisplay</b> <i class="arg">tag args</i></a></li>
<li><a href="#9"><b class="cmd">::counter::reset</b> <i class="arg">tag args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">counter</b> package provides a counter facility and can
compute statistics and histograms over the collected data.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::counter::init</b> <i class="arg">tag args</i></a></dt>
<dd><p>This defines a counter with the name <i class="arg">tag</i>. The <i class="arg">args</i>
determines the characteristics of the counter. The <i class="arg">args</i> are</p>
<dl class="doctools_definitions">
<dt><b class="option">-group</b> <i class="arg">name</i></dt>
<dd><p>Keep a grouped counter where the name of the histogram bucket is
passed into <b class="cmd">::counter::count</b>.</p></dd>
<dt><b class="option">-hist</b> <i class="arg">bucketsize</i></dt>
<dd><p>Accumulate the counter into histogram buckets of size
<i class="arg">bucketsize</i>. For example, if the samples are millisecond time
values and <i class="arg">bucketsize</i> is 10, then each histogram bucket
represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec,
and so on.</p></dd>
<dt><b class="option">-hist2x</b> <i class="arg">bucketsize</i></dt>
<dd><p>Accumulate the statistic into histogram buckets. The size of the
first bucket is <i class="arg">bucketsize</i>, each other bucket holds values 2
times the size of the previous bucket. For example, if
<i class="arg">bucketsize</i> is 10, then each histogram bucket represents time
values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec,
and so on.</p></dd>
<dt><b class="option">-hist10x</b> <i class="arg">bucketsize</i></dt>
<dd><p>Accumulate the statistic into histogram buckets. The size of the
first bucket is <i class="arg">bucketsize</i>, each other bucket holds values 10
times the size of the previous bucket. For example, if
<i class="arg">bucketsize</i> is 10, then each histogram bucket represents time
values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on.</p></dd>
<dt><b class="option">-lastn</b> <i class="arg">N</i></dt>
<dd><p>Save the last <i class="arg">N</i> values of the counter to maintain a "running
average" over the last <i class="arg">N</i> values.</p></dd>
<dt><b class="option">-timehist</b> <i class="arg">secsPerMinute</i></dt>
<dd><p>Keep a time-based histogram. The counter is summed into a histogram
bucket based on the current time. There are 60 per-minute buckets
that have a size determined by <i class="arg">secsPerMinute</i>, which is normally
60, but for testing purposes can be less. Every "hour" (i.e., 60
"minutes") the contents of the per-minute buckets are summed into the
next hourly bucket. Every 24 "hours" the contents of the per-hour
buckets are summed into the next daily bucket. The counter package
keeps all time-based histograms in sync, so the first
<i class="arg">secsPerMinute</i> value seen by the package is used for all
subsequent time-based histograms.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::counter::count</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">delta</i>?</span> <span class="opt">?<i class="arg">instance</i>?</span></a></dt>
<dd><p>Increment the counter identified by <i class="arg">tag</i>. The default increment
is 1, although you can increment by any value, integer or real, by
specifying <i class="arg">delta</i>. You must declare each counter with
<b class="cmd">::counter::init</b> to define the characteristics of counter before
you start to use it. If the counter type is <b class="option">-group</b>, then the
counter identified by <i class="arg">instance</i> is incremented.</p></dd>
<dt><a name="3"><b class="cmd">::counter::start</b> <i class="arg">tag instance</i></a></dt>
<dd><p>Record the starting time of an interval. The <i class="arg">tag</i> is the name of
the counter defined as a <b class="option">-hist</b> value-based histogram. The
<i class="arg">instance</i> is used to distinguish this interval from any other
intervals that might be overlapping this one.</p></dd>
<dt><a name="4"><b class="cmd">::counter::stop</b> <i class="arg">tag instance</i></a></dt>
<dd><p>Record the ending time of an interval. The delta time since the
corresponding <b class="cmd">::counter::start</b> call for <i class="arg">instance</i> is
recorded in the histogram identified by <i class="arg">tag</i>.</p></dd>
<dt><a name="5"><b class="cmd">::counter::get</b> <i class="arg">tag args</i></a></dt>
<dd><p>Return statistics about a counter identified by <i class="arg">tag</i>. The
<i class="arg">args</i> determine what value to return:</p>
<dl class="doctools_definitions">
<dt><b class="option">-total</b></dt>
<dd><p>Return the total value of the counter. This is the default if
<i class="arg">args</i> is not specified.</p></dd>
<dt><b class="option">-totalVar</b></dt>
<dd><p>Return the name of the total variable. Useful for specifying with
-textvariable in a Tk widget.</p></dd>
<dt><b class="option">-N</b></dt>
<dd><p>Return the number of samples accumulated into the counter.</p></dd>
<dt><b class="option">-avg</b></dt>
<dd><p>Return the average of samples accumulated into the counter.</p></dd>
<dt><b class="option">-avgn</b></dt>
<dd><p>Return the average over the last <i class="arg">N</i> samples taken. The <i class="arg">N</i>
value is set in the <b class="cmd">::counter::init</b> call.</p></dd>
<dt><b class="option">-hist</b> <i class="arg">bucket</i></dt>
<dd><p>If <i class="arg">bucket</i> is specified, then the value in that bucket of the
histogram is returned. Otherwise the complete histogram is returned
in array get format sorted by bucket.</p></dd>
<dt><b class="option">-histVar</b></dt>
<dd><p>Return the name of the histogram array variable.</p></dd>
<dt><b class="option">-histHour</b></dt>
<dd><p>Return the complete hourly histogram in array get format sorted by
bucket.</p></dd>
<dt><b class="option">-histHourVar</b></dt>
<dd><p>Return the name of the hourly histogram array variable.</p></dd>
<dt><b class="option">-histDay</b></dt>
<dd><p>Return the complete daily histogram in array get format sorted by
bucket.</p></dd>
<dt><b class="option">-histDayVar</b></dt>
<dd><p>Return the name of the daily histogram array variable.</p></dd>
<dt><b class="option">-resetDate</b></dt>
<dd><p>Return the clock seconds value recorded when the
counter was last reset.</p></dd>
<dt><b class="option">-all</b></dt>
<dd><p>Return an array get of the array used to store the counter. This
includes the total, the number of samples (N), and any type-specific
information. This does not include the histogram array.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::counter::exists</b> <i class="arg">tag</i></a></dt>
<dd><p>Returns 1 if the counter is defined.</p></dd>
<dt><a name="7"><b class="cmd">::counter::names</b></a></dt>
<dd><p>Returns a list of all counters defined.</p></dd>
<dt><a name="8"><b class="cmd">::counter::histHtmlDisplay</b> <i class="arg">tag args</i></a></dt>
<dd><p>Generate HTML to display a histogram for a counter. The <i class="arg">args</i>
control the format of the display. They are:</p>
<dl class="doctools_definitions">
<dt><b class="option">-title</b> <i class="arg">string</i></dt>
<dd><p>Label to display above bar chart</p></dd>
<dt><b class="option">-unit</b> <i class="arg">unit</i></dt>
<dd><p>Specify <b class="const">minutes</b>, <b class="const">hours</b>, or <b class="const">days</b> for the
time-base histograms. For value-based histograms, the <i class="arg">unit</i> is
used in the title.</p></dd>
<dt><b class="option">-images</b> <i class="arg">url</i></dt>
<dd><p>URL of /images directory.</p></dd>
<dt><b class="option">-gif</b> <i class="arg">filename</i></dt>
<dd><p>Image for normal histogram bars. The <i class="arg">filename</i> is relative to
the <b class="option">-images</b> directory.</p></dd>
<dt><b class="option">-ongif</b> <i class="arg">filename</i></dt>
<dd><p>Image for the active histogram bar. The <i class="arg">filename</i> is relative to
the <b class="option">-images</b> directory.</p></dd>
<dt><b class="option">-max</b> <i class="arg">N</i></dt>
<dd><p>Maximum number of value-based buckets to display.</p></dd>
<dt><b class="option">-height</b> <i class="arg">N</i></dt>
<dd><p>Pixel height of the highest bar.</p></dd>
<dt><b class="option">-width</b> <i class="arg">N</i></dt>
<dd><p>Pixel width of each bar.</p></dd>
<dt><b class="option">-skip</b> <i class="arg">N</i></dt>
<dd><p>Buckets to skip when labeling value-based histograms.</p></dd>
<dt><b class="option">-format</b> <i class="arg">string</i></dt>
<dd><p>Format used to display labels of buckets.</p></dd>
<dt><b class="option">-text</b> <i class="arg">boolean</i></dt>
<dd><p>If 1, a text version of the histogram is dumped, otherwise a graphical
one is generated.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::counter::reset</b> <i class="arg">tag args</i></a></dt>
<dd><p>Resets the counter with the name <i class="arg">tag</i> to an initial state. The
<i class="arg">args</i> determine the new characteristics of the counter. They have
the same meaning as described for <b class="cmd">::counter::init</b>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>counter</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#counting">counting</a>, <a href="../../../../index.html#histogram">histogram</a>, <a href="../../../../index.html#statistics">statistics</a>, <a href="../../../../index.html#tallying">tallying</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/crc/cksum.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<div class='fossil-doc' data-title='cksum - Cyclic Redundancy Checks'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">cksum(n) 1.1.4 tcllib "Cyclic Redundancy Checks"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>cksum - Calculate a cksum(1) compatible checksum</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">AUTHORS</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">cksum <span class="opt">?1.1.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::crc::cksum</b> <span class="opt">?<i class="arg">-format format</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-channel chan</i> | <i class="arg">-filename file</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::crc::CksumInit</b></a></li>
<li><a href="#3"><b class="cmd">::crc::CksumUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::crc::CksumFinal</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a Tcl implementation of the cksum(1) algorithm
based upon information provided at in the GNU implementation of this
program as part of the GNU Textutils 2.0 package.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::crc::cksum</b> <span class="opt">?<i class="arg">-format format</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-channel chan</i> | <i class="arg">-filename file</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>The command takes string data or a channel or file name and returns a
checksum value calculated using the <b class="syscmd">cksum(1)</b> algorithm. The
result is formatted using the <i class="arg">format</i>(n) specifier provided or as
an unsigned integer (%u) by default.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt>-channel <i class="arg">name</i></dt>
<dd><p>Return a checksum for the data read from a channel. The command will
read data from the channel until the <b class="cmd">eof</b> is true. If you need
to be able to process events during this calculation see the
<span class="sectref"><a href="#section4">PROGRAMMING INTERFACE</a></span> section</p></dd>
<dt>-filename <i class="arg">name</i></dt>
<dd><p>This is a convenience option that opens the specified file, sets the
encoding to binary and then acts as if the <i class="arg">-channel</i> option had
been used. The file is closed on completion.</p></dd>
<dt>-format <i class="arg">string</i></dt>
<dd><p>Return the checksum using an alternative format template.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PROGRAMMING INTERFACE</a></h2>
<p>The cksum package implements the checksum using a context variable to
which additional data can be added at any time. This is expecially
useful in an event based environment such as a Tk application or a web
server package. Data to be checksummed may be handled incrementally
during a <b class="cmd">fileevent</b> handler in discrete chunks. This can improve
the interactive nature of a GUI application and can help to avoid
excessive memory consumption.</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::crc::CksumInit</b></a></dt>
<dd><p>Begins a new cksum context. Returns a token ID that must be used for the
remaining functions. An optional seed may be specified if required.</p></dd>
<dt><a name="3"><b class="cmd">::crc::CksumUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the checksum identified by token. Calling
<em>CksumUpdate $token "abcd"</em> is equivalent to calling
<em>CksumUpdate $token "ab"</em> followed by
<em>CksumUpdate $token "cb"</em>. See <span class="sectref"><a href="#section5">EXAMPLES</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::crc::CksumFinal</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the checksum value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a 32 bit integer value.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<pre class="doctools_example">
% crc::cksum "Hello, World!"
2609532967
</pre>
<pre class="doctools_example">
% crc::cksum -format 0x%X "Hello, World!"
0x9B8A5027
</pre>
<pre class="doctools_example">
% crc::cksum -file cksum.tcl
1828321145
</pre>
<pre class="doctools_example">
% set tok [crc::CksumInit]
% crc::CksumUpdate $tok "Hello, "
% crc::CksumUpdate $tok "World!"
% crc::CksumFinal $tok
2609532967
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>crc</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="crc32.html">crc32(n)</a>, <a href="sum.html">sum(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checksum">checksum</a>, <a href="../../../../index.html#cksum">cksum</a>, <a href="../../../../index.html#crc">crc</a>, <a href="../../../../index.html#crc32">crc32</a>, <a href="../../../../index.html#cyclic_redundancy_check">cyclic redundancy check</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/crc/crc16.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
<div class='fossil-doc' data-title='crc16 - Cyclic Redundancy Checks'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">crc16(n) 1.1.3 tcllib "Cyclic Redundancy Checks"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>crc16 - Perform a 16bit Cyclic Redundancy Check</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">crc16 <span class="opt">?1.1.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::crc::crc16</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> <b class="const">--</b> <i class="arg">message</i></a></li>
<li><a href="#2"><b class="cmd">::crc::crc16</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> -filename <i class="arg">file</i></a></li>
<li><a href="#3"><b class="cmd">::crc::crc-ccitt</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> <b class="const">--</b> <i class="arg">message</i></a></li>
<li><a href="#4"><b class="cmd">::crc::crc-ccitt</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> -filename <i class="arg">file</i></a></li>
<li><a href="#5"><b class="cmd">::crc::xmodem</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> <b class="const">--</b> <i class="arg">message</i></a></li>
<li><a href="#6"><b class="cmd">::crc::xmodem</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> -filename <i class="arg">file</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a Tcl-only implementation of the CRC
algorithms based upon information provided at
http://www.microconsultants.com/tips/crc/crc.txt
There are a number of permutations available for calculating CRC
checksums and this package can handle all of them. Defaults are set up
for the most common cases.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::crc::crc16</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> <b class="const">--</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="2"><b class="cmd">::crc::crc16</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> -filename <i class="arg">file</i></a></dt>
<dd></dd>
<dt><a name="3"><b class="cmd">::crc::crc-ccitt</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> <b class="const">--</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="4"><b class="cmd">::crc::crc-ccitt</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> -filename <i class="arg">file</i></a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">::crc::xmodem</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> <b class="const">--</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="6"><b class="cmd">::crc::xmodem</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> <span class="opt">?-implementation <i class="arg">procname</i>?</span> -filename <i class="arg">file</i></a></dt>
<dd><p>The command takes either string data or a file name and returns a checksum
value calculated using the CRC algorithm. The command used sets up the
CRC polynomial, initial value and bit ordering for the desired
standard checksum calculation. The result is formatted
using the <i class="arg">format</i>(n) specifier provided or as an unsigned integer
(%u) by default.</p>
<p>A number of common polynomials are in use with the CRC algorithm and
the most commonly used of these are included in this package. For
convenience each of these has a command alias in the crc namespace.</p>
<p>It is possible to implement the CRC-32 checksum using this crc16
package as the implementation is sufficiently generic to extend to 32
bit checksums. As an example this has been done already - however this
is not the fastest method to implement this algorithm in Tcl and a
separate <b class="package"><a href="crc32.html">crc32</a></b> package is available.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt>-filename <i class="arg">name</i></dt>
<dd><p>Return a checksum for the file contents instead of for parameter data.</p></dd>
<dt>-format <i class="arg">string</i></dt>
<dd><p>Return the checksum using an alternative format template.</p></dd>
<dt>-seed <i class="arg">value</i></dt>
<dd><p>Select an alternative seed value for the CRC calculation. The default
is 0 for the CRC16 calculation and 0xFFFF for the CCITT version.
This can be useful for calculating the CRC for data
structures without first converting the whole structure into a
string. The CRC of the previous member can be used as the seed for
calculating the CRC of the next member. It is also used for
accumulating a checksum from fragments of a large message (or file)</p></dd>
<dt>-implementation <i class="arg">procname</i></dt>
<dd><p>This hook is provided to allow users to provide their own
implementation (perhaps a C compiled extension). The
procedure specfied is called with two parameters. The first is the
data to be checksummed and the second is the seed value. An
integer is expected as the result.</p>
<p>The package provides some implementations of standard CRC polynomials
for the XMODEM, CCITT and the usual CRC-16 checksum. For convenience,
additional commands have been provided that make use of these
implementations.</p></dd>
<dt>--</dt>
<dd><p>Terminate option processing. Please note that using the option
termination flag is important when processing data from parameters. If
the binary data looks like one of the options given above then the
data will be read as an option if this marker is not included.
Always use the <i class="arg">--</i> option termination flag before giving the data
argument.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% crc::crc16 -- "Hello, World!"
64077
</pre>
<pre class="doctools_example">
% crc::crc-ccitt -- "Hello, World!"
26586
</pre>
<pre class="doctools_example">
% crc::crc16 -format 0x%X -- "Hello, World!"
0xFA4D
</pre>
<pre class="doctools_example">
% crc::crc16 -file crc16.tcl
51675
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>crc</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="cksum.html">cksum(n)</a>, <a href="crc32.html">crc32(n)</a>, <a href="sum.html">sum(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checksum">checksum</a>, <a href="../../../../index.html#cksum">cksum</a>, <a href="../../../../index.html#crc">crc</a>, <a href="../../../../index.html#crc16">crc16</a>, <a href="../../../../index.html#crc32">crc32</a>, <a href="../../../../index.html#cyclic_redundancy_check">cyclic redundancy check</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, 2017, Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/crc/crc32.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<div class='fossil-doc' data-title='crc32 - Cyclic Redundancy Checks'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">crc32(n) 1.3.2 tcllib "Cyclic Redundancy Checks"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>crc32 - Perform a 32bit Cyclic Redundancy Check</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">AUTHORS</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">crc32 <span class="opt">?1.3.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::crc::crc32</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> [ <i class="arg">-channel chan</i> | <i class="arg">-filename file</i> | <i class="arg">message</i> ]</a></li>
<li><a href="#2"><b class="cmd">::crc::Crc32Init</b> <span class="opt">?<i class="arg">seed</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::crc::Crc32Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::crc::Crc32Final</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a Tcl implementation of the CRC-32
algorithm based upon information provided at
http://www.naaccr.org/standard/crc32/document.html
If either the <b class="package">critcl</b> package or the <b class="package">Trf</b> package
are available then a compiled version may be used internally to
accelerate the checksum calculation.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::crc::crc32</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-seed <i class="arg">value</i>?</span> [ <i class="arg">-channel chan</i> | <i class="arg">-filename file</i> | <i class="arg">message</i> ]</a></dt>
<dd><p>The command takes either string data or a channel or file name and
returns a checksum value calculated using the CRC-32 algorithm. The
result is formatted using the <i class="arg">format</i>(n) specifier provided. The
default is to return the value as an unsigned integer (format %u).</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt>-channel <i class="arg">name</i></dt>
<dd><p>Return a checksum for the data read from a channel. The command will
read data from the channel until the <b class="cmd">eof</b> is true. If you need
to be able to process events during this calculation see the
<span class="sectref"><a href="#section4">PROGRAMMING INTERFACE</a></span> section</p></dd>
<dt>-filename <i class="arg">name</i></dt>
<dd><p>This is a convenience option that opens the specified file, sets the
encoding to binary and then acts as if the <i class="arg">-channel</i> option had
been used. The file is closed on completion.</p></dd>
<dt>-format <i class="arg">string</i></dt>
<dd><p>Return the checksum using an alternative format template.</p></dd>
<dt>-seed <i class="arg">value</i></dt>
<dd><p>Select an alternative seed value for the CRC calculation. The default
is 0xffffffff. This can be useful for calculating the CRC for data
structures without first converting the whole structure into a
string. The CRC of the previous member can be used as the seed for
calculating the CRC of the next member.
Note that the crc32 algorithm includes a final XOR step. If
incremental processing is desired then this must be undone before
using the output of the algorithm as the seed for further
processing. A simpler alternative is to use the
<span class="sectref"><a href="#section4">PROGRAMMING INTERFACE</a></span> which is intended for this mode of
operation.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PROGRAMMING INTERFACE</a></h2>
<p>The CRC-32 package implements the checksum using a context variable to
which additional data can be added at any time. This is expecially
useful in an event based environment such as a Tk application or a web
server package. Data to be checksummed may be handled incrementally
during a <b class="cmd">fileevent</b> handler in discrete chunks. This can improve
the interactive nature of a GUI application and can help to avoid
excessive memory consumption.</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::crc::Crc32Init</b> <span class="opt">?<i class="arg">seed</i>?</span></a></dt>
<dd><p>Begins a new CRC32 context. Returns a token ID that must be used for the
remaining functions. An optional seed may be specified if required.</p></dd>
<dt><a name="3"><b class="cmd">::crc::Crc32Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the checksum identified by token. Calling
<em>Crc32Update $token "abcd"</em> is equivalent to calling
<em>Crc32Update $token "ab"</em> followed by
<em>Crc32Update $token "cb"</em>. See <span class="sectref"><a href="#section5">EXAMPLES</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::crc::Crc32Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the checksum value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a 32 bit integer value.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<pre class="doctools_example">
% crc::crc32 "Hello, World!"
3964322768
</pre>
<pre class="doctools_example">
% crc::crc32 -format 0x%X "Hello, World!"
0xEC4AC3D0
</pre>
<pre class="doctools_example">
% crc::crc32 -file crc32.tcl
483919716
</pre>
<pre class="doctools_example">
% set tok [crc::Crc32Init]
% crc::Crc32Update $tok "Hello, "
% crc::Crc32Update $tok "World!"
% crc::Crc32Final $tok
3964322768
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>crc</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="cksum.html">cksum(n)</a>, <a href="crc16.html">crc16(n)</a>, <a href="sum.html">sum(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checksum">checksum</a>, <a href="../../../../index.html#cksum">cksum</a>, <a href="../../../../index.html#crc">crc</a>, <a href="../../../../index.html#crc32">crc32</a>, <a href="../../../../index.html#cyclic_redundancy_check">cyclic redundancy check</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/crc/sum.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<div class='fossil-doc' data-title='sum - Cyclic Redundancy Checks'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">sum(n) 1.1.2 tcllib "Cyclic Redundancy Checks"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>sum - Calculate a sum(1) compatible checksum</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">sum <span class="opt">?1.1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::crc::sum</b> <span class="opt">?<i class="arg">-bsd</i> | <i class="arg">-sysv</i>?</span> <span class="opt">?<i class="arg">-format fmt</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-filename file</i> | <i class="arg">-channel chan</i> | <i class="arg">string</i> ]</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a Tcl-only implementation of the sum(1) command
which calculates a 16 bit checksum value from the input data. The BSD
sum algorithm is used by default but the SysV algorithm is also
available.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::crc::sum</b> <span class="opt">?<i class="arg">-bsd</i> | <i class="arg">-sysv</i>?</span> <span class="opt">?<i class="arg">-format fmt</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-filename file</i> | <i class="arg">-channel chan</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>The command takes string data or a file name or a channel and returns
a checksum value calculated using the <b class="syscmd">sum(1)</b> algorithm. The
result is formatted using the <i class="arg">format</i>(n) specifier provided or as
an unsigned integer (%u) by default.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt>-sysv</dt>
<dd><p>The SysV algorithm is fairly naive. The byte values are summed and any
overflow is discarded. The lowest 16 bits are returned as the
checksum. Input with the same content but different ordering will
give the same result.</p></dd>
<dt>-bsd</dt>
<dd><p>This algorithm is similar to the SysV version but includes a bit rotation
step which provides a dependency on the order of the data values.</p></dd>
<dt>-filename <i class="arg">name</i></dt>
<dd><p>Return a checksum for the file contents instead of for parameter data.</p></dd>
<dt>-channel <i class="arg">chan</i></dt>
<dd><p>Return a checksum for the contents of the specified channel. The
channel must be open for reading and should be configured for binary
translation. The channel will no be closed on completion.</p></dd>
<dt>-chunksize <i class="arg">size</i></dt>
<dd><p>Set the block size used when reading data from either files or
channels. This value defaults to 4096.</p></dd>
<dt>-format <i class="arg">string</i></dt>
<dd><p>Return the checksum using an alternative format template.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% crc::sum "Hello, World!"
37287
</pre>
<pre class="doctools_example">
% crc::sum -format 0x%X "Hello, World!"
0x91A7
</pre>
<pre class="doctools_example">
% crc::sum -file sum.tcl
13392
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>crc</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="cksum.html">cksum(n)</a>, <a href="crc32.html">crc32(n)</a>, sum(1)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checksum">checksum</a>, <a href="../../../../index.html#cksum">cksum</a>, <a href="../../../../index.html#crc">crc</a>, <a href="../../../../index.html#crc32">crc32</a>, <a href="../../../../index.html#cyclic_redundancy_check">cyclic redundancy check</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#security">security</a>, <a href="../../../../index.html#sum">sum</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/cron/cron.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
|
<div class='fossil-doc' data-title='cron - cron'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">cron(n) 2.1 tcllib "cron"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>cron - Tool for automating the period callback of commands</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">cron <span class="opt">?2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::cron::at</b> <i class="arg">?processname?</i> <i class="arg">timecode</i> <i class="arg">command</i></a></li>
<li><a href="#2"><b class="cmd">::cron::cancel</b> <i class="arg">processname</i></a></li>
<li><a href="#3"><b class="cmd">::cron::every</b> <i class="arg">processname</i> <i class="arg">frequency</i> <i class="arg">command</i></a></li>
<li><a href="#4"><b class="cmd">::cron::in</b> <i class="arg">?processname?</i> <i class="arg">timecode</i> <i class="arg">command</i></a></li>
<li><a href="#5"><b class="cmd">::cron::object_coroutine</b> <i class="arg">object</i> <i class="arg">coroutine</i> <i class="arg">?info?</i></a></li>
<li><a href="#6"><b class="cmd">::cron::sleep</b> <i class="arg">milliseconds</i></a></li>
<li><a href="#7"><b class="cmd">::cron::task delete</b> <i class="arg">process</i></a></li>
<li><a href="#8"><b class="cmd">::cron::task exists</b> <i class="arg">process</i></a></li>
<li><a href="#9"><b class="cmd">::cron::task info</b> <i class="arg">process</i></a></li>
<li><a href="#10"><b class="cmd">::cron::task set</b> <i class="arg">process</i> <i class="arg">field</i> <i class="arg">value</i> <i class="arg">?field...?</i> <i class="arg">?value...?</i></a></li>
<li><a href="#11"><b class="cmd">::cron::wake</b> <i class="arg">?who?</i></a></li>
<li><a href="#12"><b class="cmd">::cron::clock_step</b> <i class="arg">milliseconds</i></a></li>
<li><a href="#13"><b class="cmd">::cron::clock_delay</b> <i class="arg">milliseconds</i></a></li>
<li><a href="#14"><b class="cmd">::cron::clock_sleep</b> <i class="arg">seconds</i> <i class="arg">?offset?</i></a></li>
<li><a href="#15"><b class="cmd">::cron::clock_set</b> <i class="arg">newtime</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">cron</b> package provides a Pure-tcl set of tools to allow
programs to schedule tasks to occur at regular intervals. Rather than
force each task to issue it's own call to the event loop, the cron
system mimics the cron utility in Unix: on task periodically checks to
see if something is to be done, and issues all commands for a given
time step at once.</p>
<p>Changes in version 2.0</p>
<p>While cron was originally designed to handle time scales > 1 second, the
latest version's internal understand time granularity down to the millisecond,
making it easier to integrate with other timed events.
Version 2.0 also understands how to properly integrate coroutines and objects.
It also adds a facility for an external (or script driven) clock. Note that vwait style events
won't work very well with an external clock.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::cron::at</b> <i class="arg">?processname?</i> <i class="arg">timecode</i> <i class="arg">command</i></a></dt>
<dd><p>This command registers a <i class="arg">command</i> to be called at the time specified by <i class="arg">timecode</i>.
If <i class="arg">timecode</i> is expressed as an integer, the timecode is assumed to be in unixtime. All
other inputs will be interpreted by <b class="cmd">clock scan</b> and converted to unix time.
This task can be modified by subsequent calls to
this package's commands by referencing <i class="arg">processname</i>. If <i class="arg">processname</i> exists,
it will be replaced.
If <i class="arg">processname</i> is not given, one is generated and returned by the command.</p>
<pre class="doctools_example">
::cron::at start_coffee {Tomorrow at 9:00am} {remote::exec::coffeepot power on}
::cron::at shutdown_coffee {Tomorrow at 12:00pm} {remote::exec::coffeepot power off}
</pre>
</dd>
<dt><a name="2"><b class="cmd">::cron::cancel</b> <i class="arg">processname</i></a></dt>
<dd><p>This command unregisters the process <i class="arg">processname</i> and cancels any pending commands.
Note: processname can be a process created by either <b class="cmd">::cron::at</b> or <b class="cmd">::cron::every</b>.</p>
<pre class="doctools_example">
::cron::cancel check_mail
</pre>
</dd>
<dt><a name="3"><b class="cmd">::cron::every</b> <i class="arg">processname</i> <i class="arg">frequency</i> <i class="arg">command</i></a></dt>
<dd><p>This command registers a <i class="arg">command</i> to be called at the interval of <i class="arg">frequency</i>.
<i class="arg">frequency</i> is given in seconds. This task can be modified by subsequent calls to
this package's commands by referencing <i class="arg">processname</i>. If <i class="arg">processname</i> exists,
it will be replaced.</p>
<pre class="doctools_example">
::cron::every check_mail 900 ::imap_client::check_mail
::cron::every backup_db 3600 {::backup_procedure ::mydb}
</pre>
</dd>
<dt><a name="4"><b class="cmd">::cron::in</b> <i class="arg">?processname?</i> <i class="arg">timecode</i> <i class="arg">command</i></a></dt>
<dd><p>This command registers a <i class="arg">command</i> to be called after a delay of time specified by <i class="arg">timecode</i>.
<i class="arg">timecode</i> is expressed as an seconds.
This task can be modified by subsequent calls to
this package's commands by referencing <i class="arg">processname</i>. If <i class="arg">processname</i> exists,
it will be replaced.
If <i class="arg">processname</i> is not given, one is generated and returned by the command.</p></dd>
<dt><a name="5"><b class="cmd">::cron::object_coroutine</b> <i class="arg">object</i> <i class="arg">coroutine</i> <i class="arg">?info?</i></a></dt>
<dd><p>This command registers a <i class="arg">coroutine</i>, associated with <i class="arg">object</i> to be called
given the parameters of <i class="arg">info</i>. If now parameters are given, the coroutine is assumed
to be an idle task which will self-terminate. <i class="arg">info</i> can be given in any form compadible with
<b class="cmd">::cron::task set</b></p></dd>
<dt><a name="6"><b class="cmd">::cron::sleep</b> <i class="arg">milliseconds</i></a></dt>
<dd><p>When run within a coroutine, this command will register the coroutine for a callback
at the appointed time, and immediately yield.</p>
<p>If the ::cron::time variable is > 0 this command will advance the internal time,
100ms at a time.</p>
<p>In all other cases this command will generate a fictious variable, generate an
after call, and vwait the variable:</p>
<pre class="doctools_example">
set eventid [incr ::cron::eventcount]
set var ::cron::event_#$eventid
set $var 0
::after $ms "set $var 1"
::vwait $var
::unset $var
</pre>
<p>Usage:</p>
<pre class="doctools_example">
::cron::sleep 250
</pre>
</dd>
<dt><a name="7"><b class="cmd">::cron::task delete</b> <i class="arg">process</i></a></dt>
<dd><p>Delete the process specified the <i class="arg">process</i></p></dd>
<dt><a name="8"><b class="cmd">::cron::task exists</b> <i class="arg">process</i></a></dt>
<dd><p>Returns true if <i class="arg">process</i> is registered with cron.</p></dd>
<dt><a name="9"><b class="cmd">::cron::task info</b> <i class="arg">process</i></a></dt>
<dd><p>Returns a dict describing <i class="arg">process</i>. See <b class="cmd">::cron::task set</b> for a description of the options.</p></dd>
<dt><a name="10"><b class="cmd">::cron::task set</b> <i class="arg">process</i> <i class="arg">field</i> <i class="arg">value</i> <i class="arg">?field...?</i> <i class="arg">?value...?</i></a></dt>
<dd><p>If <i class="arg">process</i> does not exist, it is created. Options Include:</p>
<dl class="doctools_definitions">
<dt><b class="cmd"><a href="../../../../index.html#command">command</a></b></dt>
<dd><p>If <b class="cmd"><a href="../coroutine/tcllib_coroutine.html">coroutine</a></b> is black, a global command which implements this process. If <b class="cmd"><a href="../coroutine/tcllib_coroutine.html">coroutine</a></b> is not
black, the command to invoke to create or recreate the coroutine.</p></dd>
<dt><b class="cmd"><a href="../coroutine/tcllib_coroutine.html">coroutine</a></b></dt>
<dd><p>The name of the coroutine (if any) which implements this process.</p></dd>
<dt><b class="cmd">frequency</b></dt>
<dd><p>If -1, this process is terminated after the next event. If 0 this process should be called during every
idle event. If positive, this process should generate events periodically. The frequency is an integer number
of milliseconds between events.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#object">object</a></b></dt>
<dd><p>The object associated with this process or coroutine.</p></dd>
<dt><b class="cmd">scheduled</b></dt>
<dd><p>If non-zero, the absolute time from the epoch (in milliseconds) that this process will trigger an event.
If zero, and the <b class="cmd">frequency</b> is also zero, this process is called every idle loop.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#running">running</a></b></dt>
<dd><p>A boolean flag. If true it indicates the process never returned or yielded during the event loop,
and will not be called again until it does so.</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::cron::wake</b> <i class="arg">?who?</i></a></dt>
<dd><p>Wake up cron, and arrange for its event loop to be run during the next Idle cycle.</p>
<pre class="doctools_example">
::cron::wake {I just did something important}
</pre>
</dd>
</dl>
<p>Several utility commands are provided that are used internally within cron and for
testing cron, but may or may not be useful in the general cases.</p>
<dl class="doctools_definitions">
<dt><a name="12"><b class="cmd">::cron::clock_step</b> <i class="arg">milliseconds</i></a></dt>
<dd><p>Return a clock time absolute to the epoch which falls on the next
border between one second and the next for the value of <i class="arg">milliseconds</i></p></dd>
<dt><a name="13"><b class="cmd">::cron::clock_delay</b> <i class="arg">milliseconds</i></a></dt>
<dd><p>Return a clock time absolute to the epoch which falls on the next
border between one second and the next <i class="arg">milliseconds</i> in the future.</p></dd>
<dt><a name="14"><b class="cmd">::cron::clock_sleep</b> <i class="arg">seconds</i> <i class="arg">?offset?</i></a></dt>
<dd><p>Return a clock time absolute to the epoch which falls exactly <i class="arg">seconds</i> in
the future. If offset is given it may be positive or negative, and will shift
the final time to before or after the second would flip.</p></dd>
<dt><a name="15"><b class="cmd">::cron::clock_set</b> <i class="arg">newtime</i></a></dt>
<dd><p>Sets the internal clock for cron. This command will advance the time in 100ms
increment, triggering events, until the internal time catches up with <i class="arg">newtime</i>.</p>
<p><i class="arg">newtime</i> is expressed in absolute milliseconds since the beginning of the epoch.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>odie</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cron">cron</a>, <a href="../../../../index.html#odie">odie</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>System</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2016-2018 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/csv/csv.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<div class='fossil-doc' data-title='csv - CSV processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">csv(n) 0.8.1 tcllib "CSV processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>csv - Procedures to handle CSV data.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">FORMAT</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">csv <span class="opt">?0.8.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::csv::iscomplete</b> <i class="arg">data</i></a></li>
<li><a href="#2"><b class="cmd">::csv::join</b> <i class="arg">values</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span> <span class="opt">?<i class="arg">delMode</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::csv::joinlist</b> <i class="arg">values</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span> <span class="opt">?<i class="arg">delMode</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::csv::joinmatrix</b> <i class="arg">matrix</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span> <span class="opt">?<i class="arg">delMode</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::csv::read2matrix</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">chan m</i> {<i class="arg">sepChar</i> ,} {<i class="arg">expand</i> none}</a></li>
<li><a href="#6"><b class="cmd">::csv::read2queue</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">chan q</i> {<i class="arg">sepChar</i> ,}</a></li>
<li><a href="#7"><b class="cmd">::csv::report</b> <i class="arg">cmd matrix</i> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::csv::split</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">line</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::csv::split2matrix</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">m line</i> {<i class="arg">sepChar</i> ,} {<i class="arg">expand</i> none}</a></li>
<li><a href="#10"><b class="cmd">::csv::split2queue</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">q line</i> {<i class="arg">sepChar</i> ,}</a></li>
<li><a href="#11"><b class="cmd">::csv::writematrix</b> <i class="arg">m chan</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::csv::writequeue</b> <i class="arg">q chan</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">csv</b> package provides commands to manipulate information
in CSV <span class="sectref"><a href="#section3">FORMAT</a></span> (CSV = Comma Separated Values).</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<p>The following commands are available:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::csv::iscomplete</b> <i class="arg">data</i></a></dt>
<dd><p>A predicate checking if the argument <i class="arg">data</i> is a complete csv
record. The result is a boolean flag indicating the completeness of
the data. The result is true if the data is complete.</p></dd>
<dt><a name="2"><b class="cmd">::csv::join</b> <i class="arg">values</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span> <span class="opt">?<i class="arg">delMode</i>?</span></a></dt>
<dd><p>Takes a list of values and returns a string in CSV format containing
these values. The separator character can be defined by the caller,
but this is optional. The default is ",". The quoting aka delimiting character can
be defined by the caller, but this is optional. The default is '"'.
By default the quoting mode <i class="arg">delMode</i> is "auto", surrounding
values with <i class="arg">delChar</i> only when needed. When set to "always"
however, values are always surrounded by the <i class="arg">delChar</i> instead.</p></dd>
<dt><a name="3"><b class="cmd">::csv::joinlist</b> <i class="arg">values</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span> <span class="opt">?<i class="arg">delMode</i>?</span></a></dt>
<dd><p>Takes a list of lists of values and returns a string in CSV format
containing these values. The separator character can be defined by the
caller, but this is optional. The default is ",". The quoting character
can be defined by the caller, but this is optional. The default is '"'.
By default the quoting mode <i class="arg">delMode</i> is "auto", surrounding
values with <i class="arg">delChar</i> only when needed. When set to "always"
however, values are always surrounded by the <i class="arg">delChar</i> instead.
Each element of the outer list is considered a record, these are
separated by newlines in the result. The elements of each record are
formatted as usual (via <b class="cmd">::csv::join</b>).</p></dd>
<dt><a name="4"><b class="cmd">::csv::joinmatrix</b> <i class="arg">matrix</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span> <span class="opt">?<i class="arg">delMode</i>?</span></a></dt>
<dd><p>Takes a <i class="arg">matrix</i> object following the API specified for the
struct::matrix package and returns a string in CSV format containing
these values. The separator character can be defined by the caller,
but this is optional. The default is ",". The quoting character
can be defined by the caller, but this is optional. The default is
'"'.
By default the quoting mode <i class="arg">delMode</i> is "auto", surrounding
values with <i class="arg">delChar</i> only when needed. When set to "always"
however, values are always surrounded by the <i class="arg">delChar</i> instead.
Each row of the matrix is considered a record, these are
separated by newlines in the result. The elements of each record are
formatted as usual (via <b class="cmd">::csv::join</b>).</p></dd>
<dt><a name="5"><b class="cmd">::csv::read2matrix</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">chan m</i> {<i class="arg">sepChar</i> ,} {<i class="arg">expand</i> none}</a></dt>
<dd><p>A wrapper around <b class="cmd">::csv::split2matrix</b> (see below) reading
CSV-formatted lines from the specified channel (until EOF) and adding
them to the given matrix. For an explanation of the <i class="arg">expand</i>
argument see <b class="cmd">::csv::split2matrix</b>.</p></dd>
<dt><a name="6"><b class="cmd">::csv::read2queue</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">chan q</i> {<i class="arg">sepChar</i> ,}</a></dt>
<dd><p>A wrapper around <b class="cmd">::csv::split2queue</b> (see below) reading
CSV-formatted lines from the specified channel (until EOF) and adding
them to the given queue.</p></dd>
<dt><a name="7"><b class="cmd">::csv::report</b> <i class="arg">cmd matrix</i> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>A report command which can be used by the matrix methods
<b class="cmd">format 2string</b> and <b class="cmd">format 2chan</b>. For the latter this
command delegates the work to <b class="cmd">::csv::writematrix</b>. <i class="arg">cmd</i> is
expected to be either <b class="method">printmatrix</b> or
<b class="method">printmatrix2channel</b>. The channel argument, <i class="arg">chan</i>, has
to be present for the latter and must not be present for the first.</p></dd>
<dt><a name="8"><b class="cmd">::csv::split</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">line</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span></a></dt>
<dd><p>converts a <i class="arg">line</i> in CSV format into a list of the values
contained in the line. The character used to separate the values from
each other can be defined by the caller, via <i class="arg">sepChar</i>, but this
is optional. The default is ",". The quoting character can be defined
by the caller, but this is optional. The default is '"'.</p>
<p>If the option <b class="option">-alternate</b> is specified a slightly different
syntax is used to parse the input. This syntax is explained below, in
the section <span class="sectref"><a href="#section3">FORMAT</a></span>.</p></dd>
<dt><a name="9"><b class="cmd">::csv::split2matrix</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">m line</i> {<i class="arg">sepChar</i> ,} {<i class="arg">expand</i> none}</a></dt>
<dd><p>The same as <b class="cmd">::csv::split</b>, but appends the resulting list as a
new row to the matrix <i class="arg">m</i>, using the method <b class="cmd">add row</b>. The
expansion mode specified via <i class="arg">expand</i> determines how the command
handles a matrix with less columns than contained in <i class="arg">line</i>. The
allowed modes are:</p>
<dl class="doctools_definitions">
<dt><b class="const">none</b></dt>
<dd><p>This is the default mode. In this mode it is the responsibility of the
caller to ensure that the matrix has enough columns to contain the
full line. If there are not enough columns the list of values is
silently truncated at the end to fit.</p></dd>
<dt><b class="const">empty</b></dt>
<dd><p>In this mode the command expands an empty matrix to hold all columns
of the specified line, but goes no further. The overall effect is that
the first of a series of lines determines the number of columns in the
matrix and all following lines are truncated to that size, as if mode
<b class="const">none</b> was set.</p></dd>
<dt><b class="const">auto</b></dt>
<dd><p>In this mode the command expands the matrix as needed to hold all
columns contained in <i class="arg">line</i>. The overall effect is that after
adding a series of lines the matrix will have enough columns to hold
all columns of the longest line encountered so far.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::csv::split2queue</b> <span class="opt">?<b class="option">-alternate</b>?</span> <i class="arg">q line</i> {<i class="arg">sepChar</i> ,}</a></dt>
<dd><p>The same as <b class="cmd">::csv::split</b>, but appending the resulting list as a
single item to the queue <i class="arg">q</i>, using the method <b class="cmd">put</b>.</p></dd>
<dt><a name="11"><b class="cmd">::csv::writematrix</b> <i class="arg">m chan</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span></a></dt>
<dd><p>A wrapper around <b class="cmd">::csv::join</b> taking all rows in the matrix
<i class="arg">m</i> and writing them CSV formatted into the channel <i class="arg">chan</i>.</p></dd>
<dt><a name="12"><b class="cmd">::csv::writequeue</b> <i class="arg">q chan</i> <span class="opt">?<i class="arg">sepChar</i>?</span> <span class="opt">?<i class="arg">delChar</i>?</span></a></dt>
<dd><p>A wrapper around <b class="cmd">::csv::join</b> taking all items in the queue
<i class="arg">q</i> (assumes that they are lists) and writing them CSV formatted
into the channel <i class="arg">chan</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FORMAT</a></h2>
<p>The format of regular CSV files is specified as</p>
<ol class="doctools_enumerated">
<li><p>Each record of a csv file (comma-separated values, as exported e.g. by
Excel) is a set of ASCII values separated by ",". For other languages
it may be ";" however, although this is not important for this case as
the functions provided here allow any separator character.</p></li>
<li><p>If and only if a value contains itself the separator ",", then it (the
value) has to be put between "". If the value does not contain the
separator character then quoting is optional.</p></li>
<li><p>If a value contains the character ", that character is represented by "".</p></li>
<li><p>The output string "" represents the value ". In other words, it is
assumed that it was created through rule 3, and only this rule,
i.e. that the value was not quoted.</p></li>
</ol>
<p>An alternate format definition mainly used by MS products specifies
that the output string "" is a representation of the empty
string. In other words, it is assumed that the output was generated
out of the empty string by quoting it (i.e. rule 2), and not through
rule 3. This is the only difference between the regular and the
alternate format.</p>
<p>The alternate format is activated through specification of the option
<b class="option">-alternate</b> to the various split commands.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLE</a></h2>
<p>Using the regular format the record</p>
<pre class="doctools_example">
123,"123,521.2","Mary says ""Hello, I am Mary""",""
</pre>
<p>is parsed into the items</p>
<pre class="doctools_example">
a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
d) "
</pre>
<p>Using the alternate format the result is</p>
<pre class="doctools_example">
a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
d) (the empty string)
</pre>
<p>instead. As can be seen only item (d) is different, now the empty string
instead of a ".</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>csv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../../../../index.html#matrix">matrix</a>, <a href="../../../../index.html#queue">queue</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#csv">csv</a>, <a href="../../../../index.html#matrix">matrix</a>, <a href="../../../../index.html#package">package</a>, <a href="../../../../index.html#queue">queue</a>, <a href="../../../../index.html#tcllib">tcllib</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002-2015 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/debug/debug.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
|
<div class='fossil-doc' data-title='debug - debug narrative'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">debug(n) 1.0.6 tcllib "debug narrative"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>debug - debug narrative - core</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">debug <span class="opt">?1.0.6?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">debug.</b><b class="variable">tag</b> <i class="arg">message</i> <span class="opt">?<i class="arg">level</i>?</span></a></li>
<li><a href="#2"><b class="cmd">debug</b> <b class="method">2array</b></a></li>
<li><a href="#3"><b class="cmd">debug</b> <b class="method">define</b> <i class="arg">tag</i></a></li>
<li><a href="#4"><b class="cmd">debug</b> <b class="method">header</b> <i class="arg">text</i></a></li>
<li><a href="#5"><b class="cmd">debug</b> <b class="method">level</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">level</i>?</span> <span class="opt">?<i class="arg">fd</i>?</span></a></li>
<li><a href="#6"><b class="cmd">debug</b> <b class="method">names</b></a></li>
<li><a href="#7"><b class="cmd">debug</b> <b class="method">off</b> <i class="arg">tag</i></a></li>
<li><a href="#8"><b class="cmd">debug</b> <b class="method">on</b> <i class="arg">tag</i></a></li>
<li><a href="#9"><b class="cmd">debug</b> <b class="method">parray</b> <i class="arg">arrayvarname</i></a></li>
<li><a href="#10"><b class="cmd">debug</b> <b class="method">pdict</b> <i class="arg">dict</i></a></li>
<li><a href="#11"><b class="cmd">debug</b> <b class="method">hexl</b> <i class="arg">data</i> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#12"><b class="cmd">debug</b> <b class="method">nl</b></a></li>
<li><a href="#13"><b class="cmd">debug</b> <b class="method">tab</b></a></li>
<li><a href="#14"><b class="cmd">debug</b> <b class="method">prefix</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#15"><b class="cmd">debug</b> <b class="method">setting</b> (<i class="arg">tag</i> <i class="arg">level</i>) ... <span class="opt">?<i class="arg">fd</i>?</span></a></li>
<li><a href="#16"><b class="cmd">debug</b> <b class="method">suffix</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#17"><b class="cmd">debug</b> <b class="method">trailer</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Debugging areas of interest are represented by 'tags' which have
independently settable levels of interest (an integer, higher is more
detailed).</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">debug.</b><b class="variable">tag</b> <i class="arg">message</i> <span class="opt">?<i class="arg">level</i>?</span></a></dt>
<dd><p>For each known tag the package creates a command with this signature
the user can then use to provide the debug narrative of the tag.
The narrative <i class="arg">message</i> is provided as a Tcl script whose value is
<b class="cmd"><a href="../../../../index.html#subst">subst</a></b>ed in the caller's scope if and only if the current level of
interest for the <i class="arg">tag</i> matches or exceeds the call's <i class="arg">level</i>
of detail. This is useful, as one can place arbitrarily complex
narrative in code without unnecessarily evaluating it.</p>
<p>See methods <b class="method">level</b> and <b class="method">setting</b> for querying
and manipulating the current level of detail for tags.</p>
<p>The actually printed text consists of not only the
<i class="arg">message</i>, but also global and tag-specific prefix and suffix,
should they exist, with each line in the message having the specified
headers and trailers.</p>
<p>All these parts are <b class="cmd"><a href="../../../../index.html#subst">subst</a></b>ableTcl scripts, which are
substituted once per message before assembly.</p></dd>
<dt><a name="2"><b class="cmd">debug</b> <b class="method">2array</b></a></dt>
<dd><p>This method returns a dictionary mapping the names of all debug tags
currently known to the package to their state and log level. The
latter are encoded in a single numeric value, where a negative number
indicates an inactive tag at the level given by the absolute value, and
a positive number is an active tag at that level.</p>
<p>See also method <b class="method">settings</b> below.</p></dd>
<dt><a name="3"><b class="cmd">debug</b> <b class="method">define</b> <i class="arg">tag</i></a></dt>
<dd><p>This method registers the named <i class="arg">tag</i> with the package. If the
tag was not known before it is placed in an inactive state. The state
of an already known tag is left untouched.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="4"><b class="cmd">debug</b> <b class="method">header</b> <i class="arg">text</i></a></dt>
<dd><p>This method defines a global <b class="cmd"><a href="../../../../index.html#subst">subst</a></b>able Tcl script which provides
a text printed before each line of output.</p>
<p>Note how this is tag-independent.</p>
<p>Further note that the header substitution happens only once per
actual printed message, i.e. all lines of the same message will have
the same actual heading text.</p>
<p>The result of the method is the specified text.</p></dd>
<dt><a name="5"><b class="cmd">debug</b> <b class="method">level</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">level</i>?</span> <span class="opt">?<i class="arg">fd</i>?</span></a></dt>
<dd><p>This method sets the detail-<i class="arg">level</i> for the <i class="arg">tag</i>, and the
channel <i class="arg">fd</i> to write the tags narration into.
The level is an integer value >= 0 defaulting to <b class="const">1</b>.
The channel defaults to <b class="const">stderr</b>.</p>
<p>The result of the method is the new detail-level for the tag.</p></dd>
<dt><a name="6"><b class="cmd">debug</b> <b class="method">names</b></a></dt>
<dd><p>This method returns a list containing the names of all debug tags
currently known to the package.</p></dd>
<dt><a name="7"><b class="cmd">debug</b> <b class="method">off</b> <i class="arg">tag</i></a></dt>
<dd><p>This method registers the named <i class="arg">tag</i> with the package and sets it
inactive.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="8"><b class="cmd">debug</b> <b class="method">on</b> <i class="arg">tag</i></a></dt>
<dd><p>This method registers the named <i class="arg">tag</i> with the package, as active.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="9"><b class="cmd">debug</b> <b class="method">parray</b> <i class="arg">arrayvarname</i></a></dt>
<dd><p>This is a convenience method formatting the named array like the
builtin command <b class="cmd">parray</b>, except it returns the resulting string
instead of writing it directly to <b class="const">stdout</b>.</p>
<p>This makes it suitable for use in debug messages.</p></dd>
<dt><a name="10"><b class="cmd">debug</b> <b class="method">pdict</b> <i class="arg">dict</i></a></dt>
<dd><p>This is a convenience method formatting the dictionary similarly to
how the builtin command <b class="cmd">parray</b> does for array, and returns the
resulting string.</p>
<p>This makes it suitable for use in debug messages.</p></dd>
<dt><a name="11"><b class="cmd">debug</b> <b class="method">hexl</b> <i class="arg">data</i> <span class="opt">?<i class="arg">prefix</i>?</span></a></dt>
<dd><p>This is a convenience method formatting arbitrary data into a hex-dump
and returns the resulting string.</p>
<p>This makes it suitable for use in debug messages.</p>
<p>Each line of the dump is prefixed with <i class="arg">prefix</i>. This prefix
defaults to the empty string.</p></dd>
<dt><a name="12"><b class="cmd">debug</b> <b class="method">nl</b></a></dt>
<dd><p>This is a convenience method to insert a linefeed character (ASCII 0x0a)
into a debug message.</p></dd>
<dt><a name="13"><b class="cmd">debug</b> <b class="method">tab</b></a></dt>
<dd><p>This is a convenience method to insert a TAB character (ASCII 0x09)
into a debug message.</p></dd>
<dt><a name="14"><b class="cmd">debug</b> <b class="method">prefix</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This method is similar to the method <b class="method">header</b> above, in that it
defines <b class="cmd"><a href="../../../../index.html#subst">subst</a></b>able Tcl script which provides more text for debug
messages.</p>
<p>In contrast to <b class="method">header</b> the generated text is added to the
user's message before it is split into lines, making it a per-message
extension.</p>
<p>Furthermore the script is tag-dependent.</p>
<p>In exception to that, a script for tag <b class="const">::</b> is applied
to all messages.</p>
<p>If both global and tag-dependent prefix exist, both are
applied, with the global prefix coming before the tag-dependent
prefix.</p>
<p>Note that the prefix substitution happens only once per
actual printed message.</p>
<p>The result of the method is the empty string.</p>
<p>If the <i class="arg">tag</i> was not known at the time of the call it is
registered, and set inactive.</p></dd>
<dt><a name="15"><b class="cmd">debug</b> <b class="method">setting</b> (<i class="arg">tag</i> <i class="arg">level</i>) ... <span class="opt">?<i class="arg">fd</i>?</span></a></dt>
<dd><p>This method is a multi-tag variant of method <b class="method">level</b> above,
with the functionality of methods <b class="method">on</b>, and <b class="method">off</b> also
folded in.</p>
<p>Each named <i class="arg">tag</i> is set to the detail-<i class="arg">level</i> following
it, with a negative level deactivating the tag, and a positive level
activating it.</p>
<p>If the last argument is not followed by a level it is not
treated as tag name, but as the channel all the named tags should
print their messages to.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="16"><b class="cmd">debug</b> <b class="method">suffix</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This method is similar to the method <b class="method">trailer</b> below, in that
it defines <b class="cmd"><a href="../../../../index.html#subst">subst</a></b>able Tcl script which provides more text for
debug messages.</p>
<p>In contrast to <b class="method">trailer</b> the generated text is added to
the user's message before it is split into lines, making it a
per-message extension.</p>
<p>Furthermore the script is tag-dependent.</p>
<p>In exception to that, a script for tag <b class="const">::</b> is applied
to all messages.</p>
<p>If both global and tag-dependent suffix exist, both are
applied, with the global suffix coming after the tag-dependent suffix.</p>
<p>Note that the suffix substitution happens only once per actual
printed message.</p>
<p>The result of the method is the empty string.</p>
<p>If the <i class="arg">tag</i> was not known at the time of the call it is
registered, and set inactive.</p></dd>
<dt><a name="17"><b class="cmd">debug</b> <b class="method">trailer</b> <i class="arg">text</i></a></dt>
<dd><p>This method defines a global <b class="cmd"><a href="../../../../index.html#subst">subst</a></b>able Tcl script which provides
a text printed after each line of output (before the EOL however).</p>
<p>Note how this is tag-independent.</p>
<p>Further note that the trailer substitution happens only once
per actual printed message, i.e. all lines of the same message will
have the same actual trailing text.</p>
<p>The result of the method is the specified text.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>debug</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#debug">debug</a>, <a href="../../../../index.html#log">log</a>, <a href="../../../../index.html#narrative">narrative</a>, <a href="../../../../index.html#trace">trace</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>debugging, tracing, and logging</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 200?, Colin McCormack, Wub Server Utilities<br>
Copyright © 2012-2014, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/debug/debug_caller.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<div class='fossil-doc' data-title='debug::caller - debug narrative'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">debug::caller(n) 1.1 tcllib "debug narrative"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>debug::caller - debug narrative - caller</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">debug::caller <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="debug.html">debug</a></b> <b class="method">caller</b> <span class="opt">?<i class="arg">args</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="debug.html">debug</a></b> <b class="method">caller</b> <span class="opt">?<i class="arg">args</i>...?</span></a></dt>
<dd><p>This method is useful in a tag-specific prefix to automatically
provide caller information for all uses of the tag. Or in a message,
when only specific places need such detail.</p>
<p>Beyond that it recognizing the various internal forms of method
calls generated by the <b class="package"><a href="../snit/snit.html">snit</a></b> OO system and rewrites these to
their original form, for better readability.
Similarly for <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>.</p>
<p>If <i class="arg">args</i> are specified then they are treated as the
integer indices of command arguments to <em>not</em> show in the
output. The referenced arguments are replaced by <b class="const">*</b> instead.
The main anticipiated use case for this is the exclusion of arguments
expected to contain large Tcl values, i.e. long lists, large
dictionaries, etc. to prevent them from overwhelming the narrative.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>debug</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#debug">debug</a>, <a href="../../../../index.html#log">log</a>, <a href="../../../../index.html#narrative">narrative</a>, <a href="../../../../index.html#trace">trace</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>debugging, tracing, and logging</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2012-2015, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/debug/debug_heartbeat.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='debug::heartbeat - debug narrative'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">debug::heartbeat(n) 1 tcllib "debug narrative"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>debug::heartbeat - debug narrative - heartbeat</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">debug::heartbeat <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">debug <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="debug.html">debug</a></b> <b class="method">heartbeat</b> <span class="opt">?<i class="arg">delta</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="debug.html">debug</a></b> <b class="method">heartbeat</b> <span class="opt">?<i class="arg">delta</i>?</span></a></dt>
<dd><p>This method activates or disables a heartbeat with which to monitor
the event loop of an event-based Tcl application.</p>
<p>It reserves the debug tag <b class="const">heartbeat</b> for its operation
and writes a message every <i class="arg">delta</i> milliseconds.</p>
<p>A <i class="arg">delta</i>-value <= 0 disables the heartbeat.</p>
<p>The message produced by the heartbeat contains a sequence
counter and the time in milliseconds since the last beat, thus
providing insight into timing variationsn and deviations from the
nominal <i class="arg">delta</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>debug</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#debug">debug</a>, <a href="../../../../index.html#heartbeat">heartbeat</a>, <a href="../../../../index.html#log">log</a>, <a href="../../../../index.html#narrative">narrative</a>, <a href="../../../../index.html#trace">trace</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>debugging, tracing, and logging</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 200?, Colin McCormack, Wub Server Utilities<br>
Copyright © 2012, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/debug/debug_timestamp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<div class='fossil-doc' data-title='debug::timestamp - debug narrative'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">debug::timestamp(n) 1 tcllib "debug narrative"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>debug::timestamp - debug narrative - timestamping</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">debug::timestamp <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">debug <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="debug.html">debug</a></b> <b class="method">timestamp</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="debug.html">debug</a></b> <b class="method">timestamp</b></a></dt>
<dd><p>This method returns millisecond timing information since a baseline or
last call, making it useful in a tag-specific prefix to automatically
provide caller information for all uses of the tag. Or in a message,
when only specific places need such detail.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>debug</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#debug">debug</a>, <a href="../../../../index.html#log">log</a>, <a href="../../../../index.html#narrative">narrative</a>, <a href="../../../../index.html#timestamps">timestamps</a>, <a href="../../../../index.html#trace">trace</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>debugging, tracing, and logging</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 200?, Colin McCormack, Wub Server Utilities<br>
Copyright © 2012, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/defer/defer.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<div class='fossil-doc' data-title='defer - Defered execution ala Go'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">defer(n) 1 tcllib "Defered execution ala Go"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>defer - Defered execution</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">defer <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::defer::defer</b> <span class="opt">?<i class="arg">command</i>?</span> <span class="opt">?<i class="arg">arg1</i>?</span> <span class="opt">?<i class="arg">arg2</i>?</span> <span class="opt">?<i class="arg">argN...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::defer::with</b> <i class="arg">variableList</i> <i class="arg">script</i></a></li>
<li><a href="#3"><b class="cmd">::defer::autowith</b> <i class="arg">script</i></a></li>
<li><a href="#4"><b class="cmd">::defer::cancel</b> <span class="opt">?<i class="arg">id...</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">defer</b> commands allow a developer to schedule actions to happen
as part of the current variable scope terminating. This is most useful
for dealing with cleanup activities. Since the defered actions always
execute, and always execute in the reverse order from which the defer
statements themselves execute, the programmer can schedule the cleanup
of a resource (for example, a channel) as soon as that resource is
acquired. Then, later if the procedure or lambda ends, either due to
an error, or an explicit return, the cleanup of that resource will
always occur.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::defer::defer</b> <span class="opt">?<i class="arg">command</i>?</span> <span class="opt">?<i class="arg">arg1</i>?</span> <span class="opt">?<i class="arg">arg2</i>?</span> <span class="opt">?<i class="arg">argN...</i>?</span></a></dt>
<dd><p>Defers execution of some code until the current variable scope
ends. Each argument is concatencated together to form the script
to execute at deferal time.
Multiple defer statements may be used, they are executed in the order
of last-in, first-out.
The return value is an identifier which can be used later with
<b class="cmd">defer::cancel</b></p></dd>
<dt><a name="2"><b class="cmd">::defer::with</b> <i class="arg">variableList</i> <i class="arg">script</i></a></dt>
<dd><p>Defers execution of a script while copying the current value of some
variables, whose names specified in <i class="arg">variableList</i>, into the script.
The script acts like a lambda but executes at the same level as the
<b class="cmd">defer::with</b>
call.
The return value is the same as
<b class="cmd">::defer::defer</b></p></dd>
<dt><a name="3"><b class="cmd">::defer::autowith</b> <i class="arg">script</i></a></dt>
<dd><p>The same as
<b class="cmd">::defer::with</b> but uses all local variables in the variable list.</p></dd>
<dt><a name="4"><b class="cmd">::defer::cancel</b> <span class="opt">?<i class="arg">id...</i>?</span></a></dt>
<dd><p>Cancels the execution of a defered action. The <i class="arg">id</i> argument is the
identifier returned by
<b class="cmd">::defer::defer</b>,
<b class="cmd">::defer::with</b>, or
<b class="cmd">::defer::autowith</b>.
Any number of arguments may be supplied, and all of the IDs supplied
will be cancelled.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
package require defer 1
apply {{} {
set fd [open /dev/null]
defer::defer close $fd
}}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Roy Keene</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>defer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cleanup">cleanup</a>, <a href="../../../../index.html#golang">golang</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2017, Roy Keene</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/des/des.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<div class='fossil-doc' data-title='des - Data Encryption Standard (DES)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">des(n) 1.1 tcllib "Data Encryption Standard (DES)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>des - Implementation of the DES and triple-DES ciphers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">MODES OF OPERATION</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">REFERENCES</a></li>
<li class="doctools_section"><a href="#section7">AUTHORS</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">des 1.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::DES::des</b> <span class="opt">?<i class="arg">-mode [ecb|cbc|cfb|ofb]</i>?</span> <span class="opt">?<i class="arg">-dir [encrypt|decrypt]</i>?</span> <i class="arg">-key keydata</i> <span class="opt">?<i class="arg">-iv vector</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-weak</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-in channel</i> | <i class="arg">data</i> ]</a></li>
<li><a href="#2"><b class="cmd">::DES::Init</b> <i class="arg">mode</i> <i class="arg">keydata</i> <i class="arg">iv</i> <span class="opt">?<i class="arg">weak</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::DES::Encrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::DES::Decrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::DES::Reset</b> <i class="arg">Key</i> <i class="arg">iv</i></a></li>
<li><a href="#6"><b class="cmd">::DES::Final</b> <i class="arg">Key</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This is an implementation in Tcl of the Data Encryption Standard (DES)
as published by the U.S. National Institute of Standards and
Technology (NIST) [1]. This implementation also supports triple
DES (3DES) extension to DES. DES is a 64-bit block cipher that uses a
56-bit key. 3DES uses a 168-bit key. DES has now officially been
superceeded by AES but is in common use in many protocols.</p>
<p>The tcllib implementation of DES and 3DES uses an implementation by
Mac Cody and is available as a separate download from [2]. For
anyone concerned about the details of exporting this code please see
the TclDES web pages. The tcllib specific code is a wrapper to the
TclDES API that presents same API for the DES cipher as for other
ciphers in the library.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::DES::des</b> <span class="opt">?<i class="arg">-mode [ecb|cbc|cfb|ofb]</i>?</span> <span class="opt">?<i class="arg">-dir [encrypt|decrypt]</i>?</span> <i class="arg">-key keydata</i> <span class="opt">?<i class="arg">-iv vector</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-weak</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> <span class="opt">?<i class="arg">-chunksize size</i>?</span> [ <i class="arg">-in channel</i> | <i class="arg">data</i> ]</a></dt>
<dd><p>Perform the <b class="package"><a href="../../../../index.html#des">DES</a></b> algorithm on either the data provided
by the argument or on the data read from the <i class="arg">-in</i> channel. If
an <i class="arg">-out</i> channel is given then the result will be written to
this channel.</p>
<p>The <i class="arg">-key</i> option must be given. This parameter takes a binary
string of 8 bytes in length and is used to generate the key schedule.
In DES only 56 bits of key data are used. The highest bit from each
byte is discarded.</p>
<p>The <i class="arg">-mode</i> and <i class="arg">-dir</i> options are optional and default to cbc
mode and encrypt respectively. The initialization vector <i class="arg">-iv</i>
takes an 8 byte binary argument. This defaults to all zeros. See
<span class="sectref"><a href="#section4">MODES OF OPERATION</a></span> for more about <i class="arg">-mode</i> and the use
of the initialization vector.</p>
<p>DES is a 64-bit block cipher. This means that the data must be
provided in units that are a multiple of 8 bytes.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>Internal state is maintained in an opaque structure that is returned
from the <b class="cmd">Init</b> function. In ECB mode the state is not affected by
the input but for other modes some input dependent state is maintained
and may be reset by calling the <b class="cmd">Reset</b> function with a new
initialization vector value.</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::DES::Init</b> <i class="arg">mode</i> <i class="arg">keydata</i> <i class="arg">iv</i> <span class="opt">?<i class="arg">weak</i>?</span></a></dt>
<dd><p>Construct a new DES key schedule using the specified key data and the
given initialization vector. The initialization vector is not used
with ECB mode but is important for other usage modes.
See <span class="sectref"><a href="#section4">MODES OF OPERATION</a></span>.</p>
<p>There are a small number of keys that are known to be weak when used
with DES. By default if such a key is passed in then an error will be
raised. If there is a need to accept such keys then the <i class="arg">weak</i>
parameter can be set true to avoid the error being thrown.</p></dd>
<dt><a name="3"><b class="cmd">::DES::Encrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Use a prepared key acquired by calling <b class="cmd">Init</b> to encrypt the
provided data. The data argument should be a binary array that is a
multiple of the DES block size of 8 bytes. The result is a binary
array the same size as the input of encrypted data.</p></dd>
<dt><a name="4"><b class="cmd">::DES::Decrypt</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Decipher data using the key. Note that the same key may be used to
encrypt and decrypt data provided that the initialization vector is
reset appropriately for CBC mode.</p></dd>
<dt><a name="5"><b class="cmd">::DES::Reset</b> <i class="arg">Key</i> <i class="arg">iv</i></a></dt>
<dd><p>Reset the initialization vector. This permits the programmer to re-use
a key and avoid the cost of re-generating the key schedule where the
same key data is being used multiple times.</p></dd>
<dt><a name="6"><b class="cmd">::DES::Final</b> <i class="arg">Key</i></a></dt>
<dd><p>This should be called to clean up resources associated with <i class="arg">Key</i>.
Once this function has been called the key may not be used again.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">MODES OF OPERATION</a></h2>
<dl class="doctools_definitions">
<dt>Electronic Code Book (ECB)</dt>
<dd><p>ECB is the basic mode of all block ciphers. Each block is encrypted
independently and so identical plain text will produce identical
output when encrypted with the same key. Any encryption errors will
only affect a single block however this is vulnerable to known
plaintext attacks.</p></dd>
<dt>Cipher Block Chaining (CBC)</dt>
<dd><p>CBC mode uses the output of the last block encryption to affect the
current block. An initialization vector of the same size as the cipher
block size is used to handle the first block. The initialization
vector should be chosen randomly and transmitted as the first block of
the output. Errors in encryption affect the current block and the next
block after which the cipher will correct itself. CBC is the most
commonly used mode in software encryption.</p></dd>
<dt>Cipher Feedback (CFB)</dt>
<dd><p>CFB mode can be used to convert block ciphers into stream ciphers. In
CFB mode the initialization vector is encrypted and the output is then
xor'd with the plaintext stream. The result is then used as the
initialization vector for the next round. Errors will affect the
current block and the next block.</p></dd>
<dt>Output Feedback (OFB)</dt>
<dd><p>OFB is similar to CFB except that the output of the cipher is fed back
into the next round and not the xor'd plain text. This means that
errors only affect a single block but the cipher is more vulnerable to
attack.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<pre class="doctools_example">
% set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext]
% set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext]
</pre>
<pre class="doctools_example">
set iv [string repeat \\0 8]
set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv]
set ciphertext [DES::Encrypt $Key "somedata"]
append ciphertext [DES::Encrypt $Key "moredata"]
DES::Reset $Key $iv
set plaintext [DES::Decrypt $Key $ciphertext]
DES::Final $Key
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>"Data Encryption Standard",
Federal Information Processing Standards Publication 46-3, 1999,
(<a href="http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf">http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf</a>)</p></li>
<li><p>"TclDES: munitions-grade Tcl scripting"
<a href="http://tcldes.sourceforge.net/">http://tcldes.sourceforge.net/</a></p></li>
</ol>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">AUTHORS</a></h2>
<p>Jochen C Loewer,
Mac Cody,
Pat Thoyts</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>des</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../aes/aes.html">aes(n)</a>, <a href="../blowfish/blowfish.html">blowfish(n)</a>, <a href="../md5/md5.html">md5(n)</a>, <a href="../rc4/rc4.html">rc4(n)</a>, <a href="../sha1/sha1.html">sha1(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#3des">3DES</a>, <a href="../../../../index.html#des">DES</a>, <a href="../../../../index.html#block_cipher">block cipher</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/des/tcldes.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
<div class='fossil-doc' data-title='tclDES - Data Encryption Standard (DES)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tclDES(n) 1.1 tcllib "Data Encryption Standard (DES)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tclDES - Implementation of the DES and triple-DES ciphers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">tclDES 1.1</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tclDES</b> package is a helper package for <b class="package"><a href="des.html">des</a></b>.</p>
<p>Please see the documentation of <b class="package"><a href="des.html">des</a></b> for details.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>des</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="des.html">des(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#3des">3DES</a>, <a href="../../../../index.html#des">DES</a>, <a href="../../../../index.html#block_cipher">block cipher</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/des/tcldesjr.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
<div class='fossil-doc' data-title='tclDESjr - Data Encryption Standard (DES)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tclDESjr(n) 1.1 tcllib "Data Encryption Standard (DES)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tclDESjr - Implementation of the DES and triple-DES ciphers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">tclDESjr 1.1</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tclDESjr</b> package is a helper package for <b class="package"><a href="des.html">des</a></b>.</p>
<p>Please see the documentation of <b class="package"><a href="des.html">des</a></b> for details.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>des</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="des.html">des(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#3des">3DES</a>, <a href="../../../../index.html#des">DES</a>, <a href="../../../../index.html#block_cipher">block cipher</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/dicttool/dicttool.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
<div class='fossil-doc' data-title='dicttool - Extensions to the standard "dict" command'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">dicttool(n) 1.0 tcllib "Extensions to the standard "dict" command"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>dicttool - Dictionary Tools</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">ladd</b> <i class="arg">varname</i> <i class="arg">args</i></a></li>
<li><a href="#2"><b class="cmd">ldelete</b> <i class="arg">varname</i> <i class="arg">args</i></a></li>
<li><a href="#3"><b class="cmd">dict getnull</b> <i class="arg">args</i></a></li>
<li><a href="#4"><b class="cmd">dict print</b> <i class="arg">dict</i></a></li>
<li><a href="#5"><b class="cmd">dict is_dict</b> <i class="arg">value</i></a></li>
<li><a href="#6"><b class="cmd">rmerge</b> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">dicttool</b> package enhances the standard <em>dict</em> command with several new
commands. In addition, the package also defines several "creature comfort" list commands as well.
Each command checks to see if a command already exists of the same name before adding itself,
just in case any of these slip into the core.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">ladd</b> <i class="arg">varname</i> <i class="arg">args</i></a></dt>
<dd><p>This command will add a new instance of each element in <i class="arg">args</i> to <i class="arg">varname</i>, but only if that element
is not already present.</p></dd>
<dt><a name="2"><b class="cmd">ldelete</b> <i class="arg">varname</i> <i class="arg">args</i></a></dt>
<dd><p>This command will add a delete all instances of each element in <i class="arg">args</i> from <i class="arg">varname</i>.</p></dd>
<dt><a name="3"><b class="cmd">dict getnull</b> <i class="arg">args</i></a></dt>
<dd><p>Operates like <b class="cmd">dict get</b>, however if the key <i class="arg">args</i> does not exist, it returns an empty
list instead of throwing an error.</p></dd>
<dt><a name="4"><b class="cmd">dict print</b> <i class="arg">dict</i></a></dt>
<dd><p>This command will produce a string representation of <i class="arg">dict</i>, with each nested branch on
a newline, and indented with two spaces for every level.</p></dd>
<dt><a name="5"><b class="cmd">dict is_dict</b> <i class="arg">value</i></a></dt>
<dd><p>This command will return true if <i class="arg">value</i> can be interpreted as a dict. The command operates in
such a way as to not force an existing dict representation to shimmer into another internal rep.</p></dd>
<dt><a name="6"><b class="cmd">rmerge</b> <i class="arg">args</i></a></dt>
<dd><p>Return a dict which is the product of a recursive merge of all of the arguments. Unlike <b class="cmd">dict merge</b>,
this command descends into all of the levels of a dict. Dict keys which end in a : indicate a leaf, which
will be interpreted as a literal value, and not descended into further.</p>
<pre class="doctools_example">
set items [dict merge {
option {color {default: green}}
} {
option {fruit {default: mango}}
} {
option {color {default: blue} fruit {widget: select values: {mango apple cherry grape}}}
}]
puts [dict print $items]
</pre>
<p>Prints the following result:</p>
<pre class="doctools_example">
option {
color {
default: blue
}
fruit {
widget: select
values: {mango apple cherry grape}
}
}
</pre>
</dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>dict</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#dict">dict</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utilities</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2017 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/dns/tcllib_dns.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
|
<div class='fossil-doc' data-title='dns - Domain Name Service'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">dns(n) 1.4.0 tcllib "Domain Name Service"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>dns - Tcl Domain Name Service Client</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">dns <span class="opt">?1.4.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::dns::resolve</b> <i class="arg">query</i> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::dns::configure</b> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::dns::name</b> <i class="arg">token</i></a></li>
<li><a href="#4"><b class="cmd">::dns::address</b> <i class="arg">token</i></a></li>
<li><a href="#5"><b class="cmd">::dns::cname</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::dns::result</b> <i class="arg">token</i></a></li>
<li><a href="#7"><b class="cmd">::dns::status</b> <i class="arg">token</i></a></li>
<li><a href="#8"><b class="cmd">::dns::error</b> <i class="arg">token</i></a></li>
<li><a href="#9"><b class="cmd">::dns::reset</b> <i class="arg">token</i></a></li>
<li><a href="#10"><b class="cmd">::dns::wait</b> <i class="arg">token</i></a></li>
<li><a href="#11"><b class="cmd">::dns::cleanup</b> <i class="arg">token</i></a></li>
<li><a href="#12"><b class="cmd">::dns::nameservers</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The dns package provides a Tcl only Domain Name Service client. You
should refer to (1) and (2) for information about the DNS protocol or
read resolver(3) to find out how the C library resolves domain names.
The intention of this package is to insulate Tcl scripts
from problems with using the system library resolver for slow name servers.
It may or may not be of practical use. Internet name resolution is a
complex business and DNS is only one part of the resolver. You may
find you are supposed to be using hosts files, NIS or WINS to name a
few other systems. This package is not a substitute for the C library
resolver - it does however implement name resolution over DNS.
The package also extends the package <b class="package"><a href="../uri/uri.html">uri</a></b> to support DNS URIs
(4) of the form <a href="dns:what.host.com">dns:what.host.com</a> or
<a href="dns://my.nameserver/what.host.com">dns://my.nameserver/what.host.com</a>. The <b class="cmd">dns::resolve</b>
command can handle DNS URIs or simple domain names as a query.</p>
<p><em>Note:</em> The package defaults to using DNS over TCP
connections. If you wish to use UDP you will need to have the
<b class="package">tcludp</b> package installed and have a version that
correctly handles binary data (> 1.0.4).
This is available at <a href="http://tcludp.sourceforge.net/">http://tcludp.sourceforge.net/</a>.
If the <b class="package">udp</b> package is present then UDP will be used by
default.</p>
<p><em>Note:</em> The package supports DNS over TLS (RFC 7858) for
enhanced privacy of DNS queries. Using this feature requires
the TLS package.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::dns::resolve</b> <i class="arg">query</i> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>Resolve a domain name using the <i class="term"><a href="../../../../index.html#dns">DNS</a></i> protocol. <i class="arg">query</i> is
the domain name to be lookup up. This should be either a fully
qualified domain name or a DNS URI.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">-nameserver</b> <i class="arg">hostname</i> or <b class="cmd">-server</b> <i class="arg">hostname</i></dt>
<dd><p>Specify an alternative name server for this request.</p></dd>
<dt><b class="cmd">-protocol</b> <i class="arg">tcp|udp</i></dt>
<dd><p>Specify the network protocol to use for this request. Can be one of
<i class="arg">tcp</i> or <i class="arg">udp</i>.</p></dd>
<dt><b class="cmd">-port</b> <i class="arg">portnum</i></dt>
<dd><p>Specify an alternative port.</p></dd>
<dt><b class="cmd">-search</b> <i class="arg">domainlist</i></dt>
<dd></dd>
<dt><b class="cmd">-timeout</b> <i class="arg">milliseconds</i></dt>
<dd><p>Override the default timeout.</p></dd>
<dt><b class="cmd">-type</b> <i class="arg">TYPE</i></dt>
<dd><p>Specify the type of DNS record you are interested in. Valid values
are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO,
MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *.
See RFC1035 for details about the return values.
See <a href="http://spf.pobox.com/">http://spf.pobox.com/</a> about SPF.
See (3) about AAAA records and RFC2782 for details of SRV records.</p></dd>
<dt><b class="cmd">-class</b> <i class="arg">CLASS</i></dt>
<dd><p>Specify the class of domain name. This is usually IN but may be one
of IN for internet domain names, CS, CH, HS or * for any class.</p></dd>
<dt><b class="cmd">-recurse</b> <i class="arg">boolean</i></dt>
<dd><p>Set to <i class="arg">false</i> if you do not want the name server to recursively
act upon your request. Normally set to <i class="arg">true</i>.</p></dd>
<dt><b class="cmd">-command</b> <i class="arg">procname</i></dt>
<dd><p>Set a procedure to be called upon request completion. The procedure
will be passed the token as its only argument.</p></dd>
<dt><b class="cmd">-usetls</b> <i class="arg">boolean</i></dt>
<dd><p>Set the <i class="arg">true</i> to use DNS over TLS. This will force the use of
TCP and change the default port to 853. Certificate validation is
required so a source of trusted certificate authority certificates
must be provided using <i class="arg">-cafile</i> or <i class="arg">-cadir</i>.</p></dd>
<dt><b class="cmd">-cafile</b> <i class="arg">filepath</i></dt>
<dd><p>Specify a file containing a collection of trusted certificate
authority certficates. See the <b class="cmd">update-ca-certificates</b> command
manual page for details or the <b class="cmd">-CAfile</b> option help from
<b class="cmd">openssl</b>.</p></dd>
<dt><b class="cmd">-cadir</b> <i class="arg">dirpath</i></dt>
<dd><p>Specify a directory containing trusted certificate authority
certificates. This must be provided if <b class="cmd">-cafile</b> is not
specified for certificate validation to work when <b class="cmd">-usetls</b> is
enabled. See the <b class="cmd">openssl</b> documentation for the required
structure of this directory.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::dns::configure</b> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>The <b class="cmd">::dns::configure</b> command is used to setup the dns
package. The server to query, the protocol and domain search path are
all set via this command. If no arguments are provided then a list of
all the current settings is returned. If only one argument then it
must the the name of an option and the value for that option is
returned.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">-nameserver</b> <i class="arg">hostname</i></dt>
<dd><p>Set the default name server to be used by all queries. The default is
<i class="term">localhost</i>.</p></dd>
<dt><b class="cmd">-protocol</b> <i class="arg">tcp|udp</i></dt>
<dd><p>Set the default network protocol to be used. Default is <i class="arg">tcp</i>.</p></dd>
<dt><b class="cmd">-port</b> <i class="arg">portnum</i></dt>
<dd><p>Set the default port to use on the name server. The default is 53.</p></dd>
<dt><b class="cmd">-search</b> <i class="arg">domainlist</i></dt>
<dd><p>Set the domain search list. This is currently not used.</p></dd>
<dt><b class="cmd">-timeout</b> <i class="arg">milliseconds</i></dt>
<dd><p>Set the default timeout value for DNS lookups. Default is 30 seconds.</p></dd>
<dt><b class="cmd">-loglevel</b> <i class="arg">level</i></dt>
<dd><p>Set the log level used for emitting diagnostic messages from this
package. The default is <i class="term">warn</i>. See the <b class="package"><a href="../log/log.html">log</a></b> package
for details of the available levels.</p></dd>
<dt><b class="cmd">-cafile</b> <i class="arg">filepath</i></dt>
<dd><p>Set the default file path to be used for the <b class="cmd">-cafile</b>
option to <b class="cmd">dns::resolve</b>.</p></dd>
<dt><b class="cmd">-cadir</b> <i class="arg">dirpath</i></dt>
<dd><p>Set the default directory path to be used for the <b class="cmd">-cadir</b>
option to <b class="cmd">dns::resolve</b>.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::dns::name</b> <i class="arg">token</i></a></dt>
<dd><p>Returns a list of all domain names returned as an answer to your query.</p></dd>
<dt><a name="4"><b class="cmd">::dns::address</b> <i class="arg">token</i></a></dt>
<dd><p>Returns a list of the address records that match your query.</p></dd>
<dt><a name="5"><b class="cmd">::dns::cname</b> <i class="arg">token</i></a></dt>
<dd><p>Returns a list of canonical names (usually just one) matching your query.</p></dd>
<dt><a name="6"><b class="cmd">::dns::result</b> <i class="arg">token</i></a></dt>
<dd><p>Returns a list of all the decoded answer records provided for your
query. This permits you to extract the result for more unusual query types.</p></dd>
<dt><a name="7"><b class="cmd">::dns::status</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the status flag. For a successfully completed query this will be
<em>ok</em>. May be <em>error</em> or <em>timeout</em> or <em>eof</em>.
See also <b class="cmd">::dns::error</b></p></dd>
<dt><a name="8"><b class="cmd">::dns::error</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the error message provided for requests whose status is <em>error</em>.
If there is no error message then an empty string is returned.</p></dd>
<dt><a name="9"><b class="cmd">::dns::reset</b> <i class="arg">token</i></a></dt>
<dd><p>Reset or cancel a DNS query.</p></dd>
<dt><a name="10"><b class="cmd">::dns::wait</b> <i class="arg">token</i></a></dt>
<dd><p>Wait for a DNS query to complete and return the status upon completion.</p></dd>
<dt><a name="11"><b class="cmd">::dns::cleanup</b> <i class="arg">token</i></a></dt>
<dd><p>Remove all state variables associated with the request.</p></dd>
<dt><a name="12"><b class="cmd">::dns::nameservers</b></a></dt>
<dd><p>Attempts to return a list of the nameservers currently configured
for the users system. On a unix machine this parses the
/etc/resolv.conf file for nameservers (if it exists) and on Windows
systems we examine certain parts of the registry. If no nameserver can
be found then the loopback address (127.0.0.1) is used as a default.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
% set tok [dns::resolve www.tcl.tk]
::dns::1
% dns::status $tok
ok
% dns::address $tok
199.175.6.239
% dns::name $tok
www.tcl.tk
% dns::cleanup $tok
</pre>
<p>Using DNS URIs as queries:</p>
<pre class="doctools_example">
% set tok [dns::resolve "dns:tcl.tk;type=MX"]
% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"]
</pre>
<p>Reverse address lookup:</p>
<pre class="doctools_example">
% set tok [dns::resolve 127.0.0.1]
::dns::1
% dns::name $tok
localhost
% dns::cleanup $tok
</pre>
<p>Using DNS over TLS (RFC 7858):</p>
<pre class="doctools_example">
% set tok [dns::resolve www.tcl.tk -nameserver dns-tls.bitwiseshift.net -usetls 1 -cafile /etc/ssl/certs/ca-certificates.crt]
::dns::12
% dns::wait $tok
ok
% dns::address $tok
104.25.119.118 104.25.120.118
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Mockapetris, P., "Domain Names - Concepts and Facilities",
RFC 1034, November 1987.
(<a href="http://www.ietf.org/rfc/rfc1034.txt">http://www.ietf.org/rfc/rfc1034.txt</a>)</p></li>
<li><p>Mockapetris, P., "Domain Names - Implementation and Specification",
RFC 1035, November 1087.
(<a href="http://www.ietf.org/rfc/rfc1035.txt">http://www.ietf.org/rfc/rfc1035.txt</a>)</p></li>
<li><p>Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6",
RFC 1886, December 1995.
(<a href="http://www.ietf.org/rfc/rfc1886.txt">http://www.ietf.org/rfc/rfc1886.txt</a>)</p></li>
<li><p>Josefsson, S., "Domain Name System Uniform Resource Identifiers",
Internet-Draft, October 2003,
(<a href="http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt">http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt</a>)</p></li>
<li><p>Gulbrandsen, A., Vixie, P. and Esibov, L.,
"A DNS RR for specifying the location of services (DNS SRV)",
RFC 2782, February 2000,
(<a href="http://www.ietf.org/rfc/rfc2782.txt">http://www.ietf.org/rfc/rfc2782.txt</a>)</p></li>
<li><p>Ohta, M. "Incremental Zone Transfer in DNS",
RFC 1995, August 1996,
(<a href="http://www.ietf.org/rfc/rfc1995.txt">http://www.ietf.org/rfc/rfc1995.txt</a>)</p></li>
<li><p>Hu, Z., etc al.
"Specification for DNS over Transport Layer Security (TLS)",
RFC 7858, May 2016,
(<a href="http://www.ietf.org/rfc/rfc7858.txt">http://www.ietf.org/rfc/rfc7858.txt</a>)</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>dns</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>resolver(5)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#dns">DNS</a>, <a href="../../../../index.html#domain_name_service">domain name service</a>, <a href="../../../../index.html#resolver">resolver</a>, <a href="../../../../index.html#rfc_1034">rfc 1034</a>, <a href="../../../../index.html#rfc_1035">rfc 1035</a>, <a href="../../../../index.html#rfc_1886">rfc 1886</a>, <a href="../../../../index.html#rfc_7858">rfc 7858</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/dns/tcllib_ip.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
|
<div class='fossil-doc' data-title='tcllib_ip - Domain Name Service'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcllib_ip(n) 1.4 tcllib "Domain Name Service"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_ip - IPv4 and IPv6 address manipulation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">ip <span class="opt">?1.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ip::version</b> <i class="arg">address</i></a></li>
<li><a href="#2"><b class="cmd">::ip::is</b> <i class="arg">class</i> <i class="arg">address</i></a></li>
<li><a href="#3"><b class="cmd">::ip::equal</b> <i class="arg">address</i> <i class="arg">address</i></a></li>
<li><a href="#4"><b class="cmd">::ip::normalize</b> <i class="arg">address</i></a></li>
<li><a href="#5"><b class="cmd">::ip::contract</b> <i class="arg">address</i></a></li>
<li><a href="#6"><b class="cmd">::ip::distance</b> <i class="arg">ipaddr1</i> <i class="arg">ipaddr2</i></a></li>
<li><a href="#7"><b class="cmd">::ip::nextIp</b> <i class="arg">ipaddr</i> <span class="opt">?<i class="arg">offset</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::ip::prefix</b> <i class="arg">address</i></a></li>
<li><a href="#9"><b class="cmd">::ip::type</b> <i class="arg">address</i></a></li>
<li><a href="#10"><b class="cmd">::ip::mask</b> <i class="arg">address</i></a></li>
<li><a href="#11"><b class="cmd">::ip::prefixToNative</b> <i class="arg">prefix</i></a></li>
<li><a href="#12"><b class="cmd">::ip::nativeToPrefix</b> <i class="arg">nativeList</i>|<i class="arg">native</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#13"><b class="cmd">::ip::intToString</b> <i class="arg">number</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#14"><b class="cmd">::ip::toInteger</b> <i class="arg">ipaddr</i></a></li>
<li><a href="#15"><b class="cmd">::ip::toHex</b> <i class="arg">ipaddr</i></a></li>
<li><a href="#16"><b class="cmd">::ip::maskToInt</b> <i class="arg">ipmask</i></a></li>
<li><a href="#17"><b class="cmd">::ip::broadcastAddress</b> <i class="arg">prefix</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#18"><b class="cmd">::ip::maskToLength</b> <i class="arg">dottedMask</i>|<i class="arg">integerMask</i>|<i class="arg">hexMask</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#19"><b class="cmd">::ip::lengthToMask</b> <i class="arg">maskLength</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#20"><b class="cmd">::ip::nextNet</b> <i class="arg">ipaddr</i> <i class="arg">ipmask</i> <span class="opt">?<i class="arg">count</i>?</span> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#21"><b class="cmd">::ip::isOverlap</b> <i class="arg">prefix</i> <i class="arg">prefix</i>...</a></li>
<li><a href="#22"><b class="cmd">::ip::isOverlapNative</b> <span class="opt">?<b class="option">-all</b>?</span> <span class="opt">?<b class="option">-inline</b>?</span> <span class="opt">?<b class="option">-ipv4</b>?</span> <i class="arg">hexipaddr</i> <i class="arg">hexipmask</i> <i class="arg">hexiplist</i></a></li>
<li><a href="#23"><b class="cmd">::ip::ipToLayer2Multicast</b> <i class="arg">ipaddr</i></a></li>
<li><a href="#24"><b class="cmd">::ip::ipHostFromPrefix</b> <i class="arg">prefix</i> <span class="opt">?<b class="option">-exclude</b> <i class="arg">prefixExcludeList</i>?</span></a></li>
<li><a href="#25"><b class="cmd">::ip::reduceToAggregates</b> <i class="arg">prefixlist</i></a></li>
<li><a href="#26"><b class="cmd">::ip::longestPrefixMatch</b> <i class="arg">ipaddr</i> <i class="arg">prefixlist</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></li>
<li><a href="#27"><b class="cmd">::ip::collapse</b> <i class="arg">prefixlist</i></a></li>
<li><a href="#28"><b class="cmd">::ip::subtract</b> <i class="arg">prefixlist</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a set of commands to help in parsing, displaying
and comparing internet addresses. The package can handle both IPv4 (1)
and IPv6 (2) address types.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ip::version</b> <i class="arg">address</i></a></dt>
<dd><p>Returns the protocol version of the address (<b class="const">4</b> or <b class="const">6</b>),
or <b class="const">-1</b> if the address is neither IPv4 or IPv6.</p></dd>
<dt><a name="2"><b class="cmd">::ip::is</b> <i class="arg">class</i> <i class="arg">address</i></a></dt>
<dd><p>Returns true if the address is a member of the given protocol
class. The class parameter may be either <b class="const">ipv4</b> or <b class="const">ipv6</b>
This is effectively a boolean equivalent of the <b class="cmd">version</b>
command. The <i class="arg">class</i> argument may be shortened to <b class="const">4</b> or
<b class="const">6</b>.</p></dd>
<dt><a name="3"><b class="cmd">::ip::equal</b> <i class="arg">address</i> <i class="arg">address</i></a></dt>
<dd><p>Compare two address specifications for equivalence. The arguments are
normalized and the address prefix determined (if a mask is
supplied). The normalized addresses are then compared bit-by-bit and
the procedure returns true if they match.</p></dd>
<dt><a name="4"><b class="cmd">::ip::normalize</b> <i class="arg">address</i></a></dt>
<dd><p>Convert an IPv4 or IPv6 address into a fully expanded version. There
are various shorthand ways to write internet addresses, missing out
redundant parts or digits. This procedure is the opposite of
<b class="cmd">contract</b>.</p></dd>
<dt><a name="5"><b class="cmd">::ip::contract</b> <i class="arg">address</i></a></dt>
<dd><p>Convert a <b class="cmd">normalize</b>d internet address into a more compact form
suitable for displaying to users.</p></dd>
<dt><a name="6"><b class="cmd">::ip::distance</b> <i class="arg">ipaddr1</i> <i class="arg">ipaddr2</i></a></dt>
<dd><p>This command computes the (integer) distance from IPv4 address
<i class="arg">ipaddr1</i> to IPv4 address <i class="arg">ipaddr2</i>, i.e. "ipaddr2 - ipaddr1"</p>
<pre class="doctools_example">
% ::ip::distance 1.1.1.1 1.1.1.5
4
</pre>
</dd>
<dt><a name="7"><b class="cmd">::ip::nextIp</b> <i class="arg">ipaddr</i> <span class="opt">?<i class="arg">offset</i>?</span></a></dt>
<dd><p>This command adds the integer <i class="arg">offset</i> to the IPv4 address <i class="arg">ipaddr</i>
and returns the new IPv4 address.</p>
<pre class="doctools_example">
% ::ip::distance 1.1.1.1 4
1.1.1.5
</pre>
</dd>
<dt><a name="8"><b class="cmd">::ip::prefix</b> <i class="arg">address</i></a></dt>
<dd><p>Returns the address prefix generated by masking the address part with
the mask if provided. If there is no mask then it is equivalent to
calling <b class="cmd">normalize</b></p></dd>
<dt><a name="9"><b class="cmd">::ip::type</b> <i class="arg">address</i></a></dt>
<dd></dd>
<dt><a name="10"><b class="cmd">::ip::mask</b> <i class="arg">address</i></a></dt>
<dd><p>If the address supplied includes a mask then this is returned
otherwise returns an empty string.</p></dd>
<dt><a name="11"><b class="cmd">::ip::prefixToNative</b> <i class="arg">prefix</i></a></dt>
<dd><p>This command converts the string <i class="arg">prefix</i> from dotted form
(<ipaddr>/<mask> format) to native (hex) form. Returns a list
containing two elements, ipaddress and mask, in this order, in
hexadecimal notation.</p>
<pre class="doctools_example">
% ip::prefixToNative 1.1.1.0/24
0x01010100 0xffffff00
</pre>
</dd>
<dt><a name="12"><b class="cmd">::ip::nativeToPrefix</b> <i class="arg">nativeList</i>|<i class="arg">native</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This command converts from native (hex) form to dotted form.
It is the complement of <b class="cmd">::ip::prefixToNative</b>.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">nativeList</i> (in)</dt>
<dd><p>List of several ip addresses in native form. The native form is a list
as returned by <b class="cmd">::ip::prefixToNative</b>.</p></dd>
<dt>list <i class="arg">native</i> (in)</dt>
<dd><p>A list as returned by <b class="cmd">::ip::prefixToNative</b>.</p></dd>
</dl>
<p>The command returns a list of addresses in dotted form if it was
called with a list of addresses. Otherwise a single address in dotted
form is returned.</p>
<pre class="doctools_example">
% ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
1.1.1.0/24
</pre>
</dd>
<dt><a name="13"><b class="cmd">::ip::intToString</b> <i class="arg">number</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This command converts from an ip address specified as integer number
to dotted form.</p>
<pre class="doctools_example">
ip::intToString 4294967295
255.255.255.255
</pre>
</dd>
<dt><a name="14"><b class="cmd">::ip::toInteger</b> <i class="arg">ipaddr</i></a></dt>
<dd><p>This command converts a dotted form ip into an integer number.</p>
<pre class="doctools_example">
% ::ip::toInteger 1.1.1.0
16843008
</pre>
</dd>
<dt><a name="15"><b class="cmd">::ip::toHex</b> <i class="arg">ipaddr</i></a></dt>
<dd><p>This command converts dotted form ip into a hexadecimal number.</p>
<pre class="doctools_example">
% ::ip::toHex 1.1.1.0
0x01010100
</pre>
</dd>
<dt><a name="16"><b class="cmd">::ip::maskToInt</b> <i class="arg">ipmask</i></a></dt>
<dd><p>This command convert an ipmask in either dotted (255.255.255.0) form
or mask length form (24) into an integer number.</p>
<pre class="doctools_example">
::ip::maskToInt 24
4294967040
</pre>
</dd>
<dt><a name="17"><b class="cmd">::ip::broadcastAddress</b> <i class="arg">prefix</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This commands returns a broadcast address in dotted form for the given
route <i class="arg">prefix</i>, either in the form "addr/mask", or in native
form. The result is in dotted form.</p>
<pre class="doctools_example">
::ip::broadcastAddress 1.1.1.0/24
1.1.1.255
::ip::broadcastAddress {0x01010100 0xffffff00}
0x010101ff
</pre>
</dd>
<dt><a name="18"><b class="cmd">::ip::maskToLength</b> <i class="arg">dottedMask</i>|<i class="arg">integerMask</i>|<i class="arg">hexMask</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This command converts the dotted or integer form of an ipmask to
the mask length form.</p>
<pre class="doctools_example">
::ip::maskToLength 0xffffff00 -ipv4
24
% ::ip::maskToLength 255.255.255.0
24
</pre>
</dd>
<dt><a name="19"><b class="cmd">::ip::lengthToMask</b> <i class="arg">maskLength</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This command converts an ipmask in mask length form to its dotted
form.</p>
<pre class="doctools_example">
::ip::lengthToMask 24
255.255.255.0
</pre>
</dd>
<dt><a name="20"><b class="cmd">::ip::nextNet</b> <i class="arg">ipaddr</i> <i class="arg">ipmask</i> <span class="opt">?<i class="arg">count</i>?</span> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This command returns an ipaddress in the same position in the
<i class="arg">count</i> next network. The default value for <i class="arg">count</i> is
<b class="const">1</b>.</p>
<p>The address can be specified as either integer number or in dotted
form. The mask can be specified as either integer number, dotted form,
or mask length form.</p>
<p>The result is in hex form.</p></dd>
<dt><a name="21"><b class="cmd">::ip::isOverlap</b> <i class="arg">prefix</i> <i class="arg">prefix</i>...</a></dt>
<dd><p>This command checks if the given ip prefixes overlap. All arguments
are in dotted "addr/mask" form. All arguments after the first prefix
are compared against the first prefix. The result is a boolean
value. It is true if an overlap was found for any of the prefixes.</p>
<pre class="doctools_example">
% ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
0
::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
1
</pre>
</dd>
<dt><a name="22"><b class="cmd">::ip::isOverlapNative</b> <span class="opt">?<b class="option">-all</b>?</span> <span class="opt">?<b class="option">-inline</b>?</span> <span class="opt">?<b class="option">-ipv4</b>?</span> <i class="arg">hexipaddr</i> <i class="arg">hexipmask</i> <i class="arg">hexiplist</i></a></dt>
<dd><p>This command is similar to <b class="cmd">::ip::isOverlap</b>, however the
arguments are in the native form, and the form of the result is under
greater control of the caller.
If the option <b class="option">-all</b> is specified it checks all addresses for
overlap, not only until the first one is found.
If the option <b class="option">-inline</b> is specified the command returns the
overlapping prefix instead of index values.</p>
<p>The result of the command is, depending on the specified options,</p>
<dl class="doctools_definitions">
<dt>no options</dt>
<dd><p>The index of the first overlap found, or 0 if there is none.</p></dd>
<dt>-all</dt>
<dd><p>A list containing the indices of all overlaps found, or an empty list
if there are none.</p></dd>
<dt>-inline</dt>
<dd><p>The first overlapping prefix, or an empoty string if there is none.</p></dd>
<dt>-all -inline</dt>
<dd><p>A list containing the prefixes of all overlaps found, or an empty list
if there are none.</p></dd>
</dl>
<pre class="doctools_example">
% ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
0
% ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
2
</pre>
</dd>
<dt><a name="23"><b class="cmd">::ip::ipToLayer2Multicast</b> <i class="arg">ipaddr</i></a></dt>
<dd><p>This command an converts ipv4 address in dotted form into a layer 2
multicast address, also in dotted form.</p>
<pre class="doctools_example">
% ::ip::ipToLayer2Multicast 224.0.0.2
01.00.5e.00.00.02
</pre>
</dd>
<dt><a name="24"><b class="cmd">::ip::ipHostFromPrefix</b> <i class="arg">prefix</i> <span class="opt">?<b class="option">-exclude</b> <i class="arg">prefixExcludeList</i>?</span></a></dt>
<dd><p>This command returns a host address from a prefix in the form
"ipaddr/masklen", also making sure that the result is not an address
found in the <i class="arg">prefixExcludeList</i>.
The result is an ip address in dotted form.</p>
<pre class="doctools_example">
%::ip::ipHostFromPrefix 1.1.1.5/24
1.1.1.1
%::ip::ipHostFromPrefix 1.1.1.1/32
1.1.1.1
</pre>
</dd>
<dt><a name="25"><b class="cmd">::ip::reduceToAggregates</b> <i class="arg">prefixlist</i></a></dt>
<dd><p>This command finds nets that overlap and filters out the more specific
nets. The prefixes are in either addr/mask form or in native format.
The result is a list containing the non-overlapping ip prefixes from
the input.</p>
<pre class="doctools_example">
% ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8 2.1.1.0/24 1.1.1.1/32 }
1.0.0.0/8 2.1.1.0/24
</pre>
</dd>
<dt><a name="26"><b class="cmd">::ip::longestPrefixMatch</b> <i class="arg">ipaddr</i> <i class="arg">prefixlist</i> <span class="opt">?<b class="option">-ipv4</b>?</span></a></dt>
<dd><p>This command finds longest prefix match from set of prefixes, given a
specific host address. The prefixes in the list are in either native
or dotted form, whereas the host address is in either ipprefix format,
dotted form, or integer form.
The result is the prefix which is the most specific match to the host
address.</p>
<pre class="doctools_example">
% ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8 2.1.1.0/24 1.1.1.0/28 }
1.1.1.0/28
</pre>
</dd>
<dt><a name="27"><b class="cmd">::ip::collapse</b> <i class="arg">prefixlist</i></a></dt>
<dd><p>This commands takes a list of prefixes and returns a list prefixes
with the largest possible subnet masks covering the input, in this
manner collapsing adjacent prefixes into larger ranges.</p>
<p>This is different from <b class="cmd">::ip::reduceToAggregates</b> in that
the latter only removes specific nets from a list when they are
covered by other elements of the input whereas this command actively
merges nets into larger ranges when they are adjacent to each other.</p>
<pre class="doctools_example">
% ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
1.2.2.0/23
</pre>
</dd>
<dt><a name="28"><b class="cmd">::ip::subtract</b> <i class="arg">prefixlist</i></a></dt>
<dd><p>This command takes a list of prefixes, some of which are prefixed by a
dash. These latter <i class="term">negative</i> prefixes are used to punch holes
into the ranges described by the other, <i class="term">positive</i>,
prefixes. I.e. the negative prefixes are subtracted frrom the positive
ones, resulting in a larger list of describes describing the covered
ranges only as positives.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
% ip::version ::1
6
% ip::version 127.0.0.1
4
</pre>
<pre class="doctools_example">
% ip::normalize 127/8
127.0.0.0/8
% ip::contract 192.168.0.0
192.168
%
% ip::normalize fec0::1
fec0:0000:0000:0000:0000:0000:0000:0001
% ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
fec0::1
</pre>
<pre class="doctools_example">
% ip::equal 192.168.0.4/16 192.168.0.0/16
1
% ip::equal fec0::1/10 fec0::fe01/10
1
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Postel, J. "Internet Protocol." RFC 791, September 1981,
(<a href="http://www.ietf.org/rfc/rfc791.txt">http://www.ietf.org/rfc/rfc791.txt</a>)</p></li>
<li><p>Hinden, R. and Deering, S.,
"Internet Protocol Version 6 (IPv6) Addressing Architecture",
RFC 3513, April 2003
(<a href="http://www.ietf.org/rfc/rfc3513.txt">http://www.ietf.org/rfc/rfc3513.txt</a>)</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>dns</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>inet(3), ip(7), ipv6(7)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#internet_address">internet address</a>, <a href="../../../../index.html#ip">ip</a>, <a href="../../../../index.html#ipv4">ipv4</a>, <a href="../../../../index.html#ipv6">ipv6</a>, <a href="../../../../index.html#rfc_3513">rfc 3513</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004, Pat Thoyts<br>
Copyright © 2005 Aamer Akhter <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/docstrip/docstrip.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
|
<div class='fossil-doc' data-title='docstrip - Literate programming tool'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docstrip(n) 1.2 tcllib "Literate programming tool"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docstrip - Docstrip style source code extraction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">File format</a></li>
<li class="doctools_section"><a href="#section3">Commands</a></li>
<li class="doctools_section"><a href="#section4">Document structure</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">docstrip <span class="opt">?1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">docstrip::extract</b> <i class="arg">text</i> <i class="arg">terminals</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#2"><b class="cmd">docstrip::sourcefrom</b> <i class="arg">filename</i> <i class="arg">terminals</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><b class="syscmd">Docstrip</b> is a tool created to support a brand of Literate
Programming. It is most common in the (La)TeX community, where it
is being used for pretty much everything from the LaTeX core and up,
but there is nothing about <b class="syscmd">docstrip</b> which prevents using it
for other types of software.</p>
<p>In short, the basic principle of literate programming is that program
source should primarily be written and structured to suit the
developers (and advanced users who want to peek "under the hood"), not
to suit the whims of a compiler or corresponding source code consumer.
This means literate sources often need some kind of "translation" to an
illiterate form that dumb software can understand.
The <b class="package">docstrip</b> Tcl package handles this translation.</p>
<p>Even for those who do not whole-hartedly subscribe to the philosophy
behind literate programming, <b class="syscmd">docstrip</b> can bring greater
clarity to in particular:</p>
<ul class="doctools_itemized">
<li><p>programs employing non-obvious mathematics</p></li>
<li><p>projects where separate pieces of code, perhaps in
different languages, need to be closely coordinated.</p></li>
</ul>
<p>The first is by providing access to much more powerful typographical
features for source code comments than are possible in plain text.
The second is because all the separate pieces of code can be kept
next to each other in the same source file.</p>
<p>The way it works is that the programmer edits directly only one or
several "master" source code files, from which <b class="syscmd">docstrip</b>
generates the more traditional "source" files compilers or the like
would expect. The master sources typically contain a large amount of
documentation of the code, sometimes even in places where the code
consumers would not allow any comments. The etymology of "docstrip"
is that this <em>doc</em>umentation was <em>strip</em>ped away (although
"code extraction" might be a better description, as it has always
been a matter of copying selected pieces of the master source rather
than deleting text from it).
The <b class="package">docstrip</b> Tcl package contains a reimplementation of
the basic extraction functionality from the <b class="syscmd">docstrip</b>
program, and thus makes it possible for a Tcl interpreter to read
and interpret the master source files directly.</p>
<p>Readers who are not previously familiar with <b class="syscmd">docstrip</b> but
want to know more about it may consult the following sources.</p>
<ol class="doctools_enumerated">
<li><p><em>The tclldoc package and class</em>,
<a href="http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/">http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/</a>.</p></li>
<li><p><em>The DocStrip utility</em>,
<a href="http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx">http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx</a>.</p></li>
<li><p><em>The doc and shortvrb Packages</em>,
<a href="http://ctan.org/tex-archive/macros/latex/base/doc.dtx">http://ctan.org/tex-archive/macros/latex/base/doc.dtx</a>.</p></li>
<li><p>Chapter 14 of
<em>The LaTeX Companion</em> (second edition),
Addison-Wesley, 2004; ISBN 0-201-36299-6.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">File format</a></h2>
<p>The basic unit <b class="syscmd">docstrip</b> operates on are the <em>lines</em> of
a master source file. Extraction consists of selecting some of these
lines to be copied from input text to output text. The basic
distinction is that between <em>code lines</em> (which are copied and
do not begin with a percent character) and <em>comment lines</em>
(which begin with a percent character and are not copied).</p>
<pre class="doctools_example">
docstrip::extract [join {
{% comment}
{% more comment !"#$%&/(}
{some command}
{ % blah $blah "Not a comment."}
{% abc; this is comment}
{# def; this is code}
{ghi}
{% jkl}
} \n] {}
</pre>
<p>returns the same sequence of lines as</p>
<pre class="doctools_example">
join {
{some command}
{ % blah $blah "Not a comment."}
{# def; this is code}
{ghi} ""
} \n
</pre>
<p>It does not matter to <b class="syscmd">docstrip</b> what format is used for the
documentation in the comment lines, but in order to do better than
plain text comments, one typically uses some markup language. Most
commonly LaTeX is used, as that is a very established standard and
also provides the best support for mathematical formulae, but the
<b class="package">docstrip::util</b> package also gives some support for
<i class="term"><a href="../../../../index.html#doctools">doctools</a></i>-like markup.</p>
<p>Besides the basic code and comment lines, there are also
<em>guard lines</em>, which begin with the two characters '%<', and
<em>meta-comment lines</em>, which begin with the two characters
'%%'. Within guard lines there is furthermore the distinction between
<em>verbatim guard lines</em>, which begin with '%<<', and ordinary
guard lines, where the '%<' is not followed by another '<'. The last
category is by far the most common.</p>
<p>Ordinary guard lines conditions extraction of the code line(s) they
guard by the value of a boolean expression; the guarded block of
code lines will only be included if the expression evaluates to true.
The syntax of an ordinary guard line is one of</p>
<pre class="doctools_example">
'%' '<' STARSLASH EXPRESSION '>'
'%' '<' PLUSMINUS EXPRESSION '>' CODE
</pre>
<p>where</p>
<pre class="doctools_example">
STARSLASH ::= '*' | '/'
PLUSMINUS ::= | '+' | '-'
EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION
| SECONDARY '|' EXPRESSION
SECONDARY ::= PRIMARY | PRIMARY '&' SECONDARY
PRIMARY ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')'
CODE ::= { any character except end-of-line }
</pre>
<p>Comma and vertical bar both denote 'or'. Ampersand denotes 'and'.
Exclamation mark denotes 'not'. A TERMINAL can be any nonempty string
of characters not containing '>', '&', '|', comma, '(', or ')',
although the <b class="syscmd">docstrip</b> manual is a bit restrictive and only
guarantees proper operation for strings of letters (although even
the LaTeX core sources make heavy use also of digits in TERMINALs).
The second argument of <b class="cmd">docstrip::extract</b> is the list of those
TERMINALs that should count as having the value 'true'; all other
TERMINALs count as being 'false' when guard expressions are evaluated.</p>
<p>In the case of a '%<*<em>EXPRESSION</em>>' guard, the lines guarded are
all lines up to the next '%</<em>EXPRESSION</em>>' guard with the same
<em>EXPRESSION</em> (compared as strings). The blocks of code delimited
by such '*' and '/' guard lines must be properly nested.</p>
<pre class="doctools_example">
set text [join {
{begin}
{%<*foo>}
{1}
{%<*bar>}
{2}
{%</bar>}
{%<*!bar>}
{3}
{%</!bar>}
{4}
{%</foo>}
{5}
{%<*bar>}
{6}
{%</bar>}
{end}
} \n]
set res [docstrip::extract $text foo]
append res [docstrip::extract $text {foo bar}]
append res [docstrip::extract $text bar]
</pre>
<p>sets $res to the result of</p>
<pre class="doctools_example">
join {
{begin}
{1}
{3}
{4}
{5}
{end}
{begin}
{1}
{2}
{4}
{5}
{6}
{end}
{begin}
{5}
{6}
{end} ""
} \n
</pre>
<p>In guard lines without a '*', '/', '+', or '-' modifier after the
'%<', the guard applies only to the CODE following the '>' on that
single line. A '+' modifier is equivalent to no modifier. A '-'
modifier is like the case with no modifier, but the expression is
implicitly negated, i.e., the CODE of a '%<-' guard line is only
included if the expression evaluates to false.</p>
<p>Metacomment lines are "comment lines which should not be stripped
away", but be extracted like code lines; these are sometimes used for
copyright notices and similar material. The '%%' prefix is however
not kept, but substituted by the current <b class="option">-metaprefix</b>, which
is customarily set to some "comment until end of line" character (or
character sequence) of the language of the code being extracted.</p>
<pre class="doctools_example">
set text [join {
{begin}
{%<foo> foo}
{%<+foo>plusfoo}
{%<-foo>minusfoo}
{middle}
{%% some metacomment}
{%<*foo>}
{%%another metacomment}
{%</foo>}
{end}
} \n]
set res [docstrip::extract $text foo -metaprefix {# }]
append res [docstrip::extract $text bar -metaprefix {#}]
</pre>
<p>sets $res to the result of</p>
<pre class="doctools_example">
join {
{begin}
{ foo}
{plusfoo}
{middle}
{# some metacomment}
{# another metacomment}
{end}
{begin}
{minusfoo}
{middle}
{# some metacomment}
{end} ""
} \n
</pre>
<p>Verbatim guards can be used to force code line
interpretation of a block of lines even if some of them happen to look
like any other type of lines to docstrip. A verbatim guard has the
form '%<<<em>END-TAG</em>' and the verbatim block is terminated by the
first line that is exactly '%<em>END-TAG</em>'.</p>
<pre class="doctools_example">
set text [join {
{begin}
{%<*myblock>}
{some stupid()}
{ #computer<program>}
{%<<QQQ-98765}
{% These three lines are copied verbatim (including percents}
{%% even if -metaprefix is something different than %%).}
{%</myblock>}
{%QQQ-98765}
{ using*strange@programming<language>}
{%</myblock>}
{end}
} \n]
set res [docstrip::extract $text myblock -metaprefix {# }]
append res [docstrip::extract $text {}]
</pre>
<p>sets $res to the result of</p>
<pre class="doctools_example">
join {
{begin}
{some stupid()}
{ #computer<program>}
{% These three lines are copied verbatim (including percents}
{%% even if -metaprefix is something different than %%).}
{%</myblock>}
{ using*strange@programming<language>}
{end}
{begin}
{end} ""
} \n
</pre>
<p>The processing of verbatim guards takes place also inside blocks of
lines which due to some outer block guard will not be copied.</p>
<p>The final piece of <b class="syscmd">docstrip</b> syntax is that extraction
stops at a line that is exactly "\endinput"; this is often used to
avoid copying random whitespace at the end of a file. In the unlikely
case that one wants such a code line, one can protect it with a
verbatim guard.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Commands</a></h2>
<p>The package defines two commands.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">docstrip::extract</b> <i class="arg">text</i> <i class="arg">terminals</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>The <b class="cmd">extract</b> command docstrips the <i class="arg">text</i> and returns the
extracted lines of code, as a string with each line terminated with
a newline. The <i class="arg">terminals</i> is the list of those guard
expression terminals which should evaluate to true.
The available options are:</p>
<dl class="doctools_options">
<dt><b class="option">-annotate</b> <i class="arg">lines</i></dt>
<dd><p>Requests the specified number of lines of annotation to follow
each extracted line in the result. Defaults to 0. Annotation lines
are mostly useful when the extracted lines are to undergo some
further transformation. A first annotation line is a list of three
elements: line type, prefix removed in extraction, and prefix
inserted in extraction. The line type is one of: 'V' (verbatim),
'M' (metacomment), '+' (+ or no modifier guard line), '-' (-
modifier guard line), '.' (normal line). A second annotation line
is the source line number. A third annotation line is the current
stack of block guards. Requesting more than three lines of
annotation is currently not supported.</p></dd>
<dt><b class="option">-metaprefix</b> <i class="arg">string</i></dt>
<dd><p>The string by which the '%%' prefix of a metacomment line will
be replaced. Defaults to '%%'. For Tcl code this would typically
be '#'.</p></dd>
<dt><b class="option">-onerror</b> <i class="arg">keyword</i></dt>
<dd><p>Controls what will be done when a format error in the <i class="arg">text</i>
being processed is detected. The settings are:</p>
<dl class="doctools_definitions">
<dt><b class="const">ignore</b></dt>
<dd><p>Just ignore the error; continue as if nothing happened.</p></dd>
<dt><b class="const">puts</b></dt>
<dd><p>Write an error message to <b class="const">stderr</b>, then continue
processing.</p></dd>
<dt><b class="const">throw</b></dt>
<dd><p>Throw an error. The <b class="option">-errorcode</b> is set to a list whose
first element is <b class="const">DOCSTRIP</b>, second element is the
type of error, and third element is the line number where
the error is detected. This is the default.</p></dd>
</dl></dd>
<dt><b class="option">-trimlines</b> <i class="arg">boolean</i></dt>
<dd><p>Controls whether <em>spaces</em> at the end of a line should be
trimmed away before the line is processed. Defaults to true.</p></dd>
</dl>
<p>It should be remarked that the <i class="arg">terminals</i> are often called
"options" in the context of the <b class="syscmd">docstrip</b> program, since
these specify which optional code fragments should be included.</p></dd>
<dt><a name="2"><b class="cmd">docstrip::sourcefrom</b> <i class="arg">filename</i> <i class="arg">terminals</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>The <b class="cmd">sourcefrom</b> command is a docstripping emulation of
<b class="cmd"><a href="../../../../index.html#source">source</a></b>. It opens the file <i class="arg">filename</i>, reads it, closes it,
docstrips the contents as specified by the <i class="arg">terminals</i>, and
evaluates the result in the local context of the caller, during
which time the <b class="cmd"><a href="../../../../index.html#info">info</a></b> <b class="method">script</b> value will be the
<i class="arg">filename</i>. The options are passed on to <b class="cmd">fconfigure</b> to
configure the file before its contents are read. The
<b class="option">-metaprefix</b> is set to '#', all other <b class="cmd">extract</b>
options have their default values.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Document structure</a></h2>
<p>The file format (as described above) determines whether a master
source code file can be processed correctly by <b class="syscmd">docstrip</b>,
but the usefulness of the format is to no little part also dependent
on that the code and comment lines together constitute a well-formed
document.</p>
<p>For a document format that does not require any non-Tcl software, see
the <b class="cmd">ddt2man</b> command in the <b class="package">docstrip::util</b> package. It
is suggested that files employing that document format are given the
suffix "<b class="file">.ddt</b>", to distinguish them from the more traditional
LaTeX-based "<b class="file">.dtx</b>" files.</p>
<p>Master source files with "<b class="file">.dtx</b>" extension are usually set up so
that they can be typeset directly by <b class="syscmd"><a href="../../../../index.html#latex">latex</a></b> without any
support from other files. This is achieved by beginning the file
with the lines</p>
<pre class="doctools_example">
% \iffalse
%<*driver>
\documentclass{tclldoc}
\begin{document}
\DocInput{<em>filename.dtx</em>}
\end{document}
%</driver>
% \fi
</pre>
<p>or some variation thereof. The trick is that the file gets read twice.
With normal LaTeX reading rules, the first two lines are comments and
therefore ignored. The third line is the document preamble, the fourth
line begins the document body, and the sixth line ends the document,
so LaTeX stops there — non-comments below that point in
the file are never subjected to the normal LaTeX reading rules. Before
that, however, the \DocInput command on the fifth line is processed,
and that does two things: it changes the interpretation of '%' from
"comment" to "ignored", and it inputs the file specified in the
argument (which is normally the name of the file the command is in).
It is this second time that the file is being read that the comments
and code in it are typeset.</p>
<p>The function of the \iffalse ... \fi is to skip lines two to seven
on this second time through; this is similar to the "if 0 { ... }"
idiom for block comments in Tcl code, and it is needed here because
(amongst other things) the \documentclass command may only be
executed once. The function of the <driver> guards is to prevent this
short piece of LaTeX code from being extracted by <b class="syscmd">docstrip</b>.
The total effect is that the file can function both as a LaTeX
document and as a <b class="syscmd">docstrip</b> master source code file.</p>
<p>It is not necessary to use the tclldoc document class, but that does
provide a number of features that are convenient for "<b class="file">.dtx</b>"
files containing Tcl code. More information on this matter can be
found in the references above.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docstrip_util.html">docstrip_util</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_dtx">.dtx</a>, <a href="../../../../index.html#latex">LaTeX</a>, <a href="../../../../index.html#docstrip">docstrip</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#literate_programming">literate programming</a>, <a href="../../../../index.html#source">source</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003–2010 Lars Hellström <Lars dot Hellstrom at residenset dot net></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/docstrip/docstrip_util.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
|
<div class='fossil-doc' data-title='docstrip_util - Literate programming tool'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docstrip_util(n) 1.3.1 tcllib "Literate programming tool"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docstrip_util - Docstrip-related utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Package indexing commands</a></li>
<li class="doctools_section"><a href="#section3">Source processing commands</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">docstrip <span class="opt">?1.2?</span></b></li>
<li>package require <b class="pkgname">docstrip::util <span class="opt">?1.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pkgProvide</b> <i class="arg">name</i> <i class="arg">version</i> <i class="arg">terminals</i></a></li>
<li><a href="#2"><b class="cmd">pkgIndex</b> <span class="opt">?<i class="arg">terminal</i> ...?</span></a></li>
<li><a href="#3"><b class="cmd">fileoptions</b> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#4"><b class="cmd">docstrip::util::index_from_catalogue</b> <i class="arg">dir</i> <i class="arg">pattern</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#5"><b class="cmd">docstrip::util::modules_from_catalogue</b> <i class="arg">target</i> <i class="arg">source</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#6"><b class="cmd">docstrip::util::classical_preamble</b> <i class="arg">metaprefix</i> <i class="arg">message</i> <i class="arg">target</i> <span class="opt">?<i class="arg">source</i> <i class="arg">terminals</i> ...?</span></a></li>
<li><a href="#7"><b class="cmd">docstrip::util::classical_postamble</b> <i class="arg">metaprefix</i> <i class="arg">message</i> <i class="arg">target</i> <span class="opt">?<i class="arg">source</i> <i class="arg">terminals</i> ...?</span></a></li>
<li><a href="#8"><b class="cmd">docstrip::util::packages_provided</b> <i class="arg">text</i> <span class="opt">?<i class="arg">setup-script</i>?</span></a></li>
<li><a href="#9"><b class="cmd">docstrip::util::ddt2man</b> <i class="arg">text</i></a></li>
<li><a href="#10"><b class="cmd">docstrip::util::guards</b> <i class="arg">subcmd</i> <i class="arg">text</i></a></li>
<li><a href="#11"><b class="cmd">docstrip::util::patch</b> <i class="arg">source-var</i> <i class="arg">terminals</i> <i class="arg">fromtext</i> <i class="arg">diff</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#12"><b class="cmd">docstrip::util::thefile</b> <i class="arg">filename</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#13"><b class="cmd">docstrip::util::import_unidiff</b> <i class="arg">diff-text</i> <span class="opt">?<i class="arg">warning-var</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">docstrip::util</b> package is meant for collecting various
utility procedures that are mainly useful at installation or
development time. It is separate from the base package to avoid
overhead when the latter is used to <b class="cmd"><a href="../../../../index.html#source">source</a></b> code.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Package indexing commands</a></h2>
<p>Like raw "<b class="file">.tcl</b>" files, code lines in docstrip source files can
be searched for package declarations and corresponding indices
constructed. A complication is however that one cannot tell from the
code blocks themselves which will fit together to make a working
package; normally that information would be found in an accompanying
"<b class="file">.ins</b>" file, but parsing one of those is not an easy task.
Therefore <b class="package">docstrip::util</b> introduces an alternative encoding
of such information, in the form of a declarative Tcl script: the
<i class="term"><a href="../../../../index.html#catalogue">catalogue</a></i> (of the contents in a source file).</p>
<p>The special commands which are available inside a catalogue are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pkgProvide</b> <i class="arg">name</i> <i class="arg">version</i> <i class="arg">terminals</i></a></dt>
<dd><p>Declares that the code for a package with name <i class="arg">name</i> and
version <i class="arg">version</i> is made up from those modules in the source
file which are selected by the <i class="arg">terminals</i> list of guard
expression terminals. This code should preferably not contain a
<b class="cmd"><a href="../../../../index.html#package">package</a></b> <b class="method">provide</b> command for the package, as one
will be provided by the package loading mechanisms.</p></dd>
<dt><a name="2"><b class="cmd">pkgIndex</b> <span class="opt">?<i class="arg">terminal</i> ...?</span></a></dt>
<dd><p>Declares that the code for a package is made up from those modules
in the source file which are selected by the listed guard
expression <i class="arg">terminal</i>s. The name and version of this package is
determined from <b class="cmd"><a href="../../../../index.html#package">package</a></b> <b class="method">provide</b> command(s) found
in that code (hence there must be such a command in there).</p></dd>
<dt><a name="3"><b class="cmd">fileoptions</b> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>Declares the <b class="cmd">fconfigure</b> options that should be in force when
reading the source; this can usually be ignored for pure ASCII
files, but if the file needs to be interpreted according to some
other <b class="option">-encoding</b> then this is how to specify it. The
command should normally appear first in the catalogue, as it takes
effect only for commands following it.</p></dd>
</dl>
<p>Other Tcl commands are supported too — a catalogue is
parsed by being evaluated in a safe interpreter — but they
are rarely needed. To allow for future extensions, unknown commands
in the catalogue are silently ignored.</p>
<p>To simplify distribution of catalogues together with their source
files, the catalogue is stored <em>in the source file itself</em> as
a module selected by the terminal '<b class="const">docstrip.tcl::catalogue</b>'.
This supports both the style of collecting all catalogue lines in one
place and the style of putting each catalogue line in close proximity
of the code that it declares.</p>
<p>Putting catalogue entries next to the code they declare may look as
follows</p>
<pre class="doctools_example">
% First there's the catalogue entry
% \begin{tcl}
%<docstrip.tcl::catalogue>pkgProvide foo::bar 1.0 {foobar load}
% \end{tcl}
% second a metacomment used to include a copyright message
% \begin{macrocode}
%<*foobar>
%% This file is placed in the public domain.
% \end{macrocode}
% third the package implementation
% \begin{tcl}
namespace eval foo::bar {
# ... some clever piece of Tcl code elided ...
% \end{tcl}
% which at some point may have variant code to make use of a
% |load|able extension
% \begin{tcl}
%<*load>
load [file rootname [info script]][info sharedlibextension]
%</load>
%<*!load>
# ... even more clever scripted counterpart of the extension
# also elided ...
%</!load>
}
%</foobar>
% \end{tcl}
% and that's it!
</pre>
<p>The corresponding set-up with <b class="cmd">pkgIndex</b> would be</p>
<pre class="doctools_example">
% First there's the catalogue entry
% \begin{tcl}
%<docstrip.tcl::catalogue>pkgIndex foobar load
% \end{tcl}
% second a metacomment used to include a copyright message
% \begin{tcl}
%<*foobar>
%% This file is placed in the public domain.
% \end{tcl}
% third the package implementation
% \begin{tcl}
package provide foo::bar 1.0
namespace eval foo::bar {
# ... some clever piece of Tcl code elided ...
% \end{tcl}
% which at some point may have variant code to make use of a
% |load|able extension
% \begin{tcl}
%<*load>
load [file rootname [info script]][info sharedlibextension]
%</load>
%<*!load>
# ... even more clever scripted counterpart of the extension
# also elided ...
%</!load>
}
%</foobar>
% \end{tcl}
% and that's it!
</pre>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">docstrip::util::index_from_catalogue</b> <i class="arg">dir</i> <i class="arg">pattern</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>This command is a sibling of the standard <b class="cmd">pkg_mkIndex</b>
command, in that it adds package entries to "<b class="file">pkgIndex.tcl</b>"
files. The difference is that it indexes <b class="syscmd"><a href="docstrip.html">docstrip</a></b>-style
source files rather than raw "<b class="file">.tcl</b>" or loadable library files.
Only packages listed in the catalogue of a file are considered.</p>
<p>The <i class="arg">dir</i> argument is the directory in which to look for files
(and whose "<b class="file">pkgIndex.tcl</b>" file should be amended).
The <i class="arg">pattern</i> argument is a <b class="cmd">glob</b> pattern of files to look
into; a typical value would be <b class="const">*.dtx</b> or
<b class="const">*.{dtx,ddt}</b>. Remaining arguments are option-value pairs,
where the supported options are:</p>
<dl class="doctools_options">
<dt><b class="option">-recursein</b> <i class="arg">dirpattern</i></dt>
<dd><p>If this option is given, then the <b class="cmd">index_from_catalogue</b>
operation will be repeated in each subdirectory whose name
matches the <i class="arg">dirpattern</i>. <b class="option">-recursein</b> <b class="const">*</b> will
cause the entire subtree rooted at <i class="arg">dir</i> to be indexed.</p></dd>
<dt><b class="option">-sourceconf</b> <i class="arg">dictionary</i></dt>
<dd><p>Specify <b class="cmd">fileoptions</b> to use when reading the catalogues of
files (and also for reading the packages if the catalogue does
not contain a <b class="cmd">fileoptions</b> command). Defaults to being
empty. Primarily useful if your system encoding is very different
from that of the source file (e.g., one is a two-byte encoding
and the other is a one-byte encoding). <b class="const">ascii</b> and
<b class="const">utf-8</b> are not very different in that sense.</p></dd>
<dt><b class="option">-options</b> <i class="arg">terminals</i></dt>
<dd><p>The <i class="arg">terminals</i> is a list of terminals in addition to
<b class="const">docstrip.tcl::catalogue</b> that should be held as true when
extracting the catalogue. Defaults to being empty. This makes it
possible to make use of "variant sections" in the catalogue
itself, e.g. gaurd some entries with an extra "experimental" and
thus prevent them from appearing in the index unless that is
generated with "experimental" among the <b class="option">-options</b>.</p></dd>
<dt><b class="option">-report</b> <i class="arg">boolean</i></dt>
<dd><p>If the <i class="arg">boolean</i> is true then the return value will be a
textual, probably multiline, report on what was done. Defaults
to false, in which case there is no particular return value.</p></dd>
<dt><b class="option">-reportcmd</b> <i class="arg">commandPrefix</i></dt>
<dd><p>Every item in the report is handed as an extra argument to the
command prefix. Since <b class="cmd">index_from_catalogue</b> would typically
be used at a rather high level in installation scripts and the
like, the <i class="arg">commandPrefix</i> defaults to
"<b class="cmd">puts</b> <b class="const">stdout</b>".
Use <b class="cmd"><a href="../../../../index.html#list">list</a></b> to effectively disable this feature. The return
values from the prefix are ignored.</p></dd>
</dl>
<p>The <b class="cmd">package ifneeded</b> scripts that are generated contain
one <b class="cmd">package require docstrip</b> command and one
<b class="cmd">docstrip::sourcefrom</b> command. If the catalogue entry was
of the <b class="cmd">pkgProvide</b> kind then the <b class="cmd">package ifneeded</b>
script also contains the <b class="cmd">package provide</b> command.</p>
<p>Note that <b class="cmd">index_from_catalogue</b> never removes anything from an
existing "<b class="file">pkgIndex.tcl</b>" file. Hence you may need to delete it
(or have <b class="cmd">pkg_mkIndex</b> recreate it from scratch) before running
<b class="cmd">index_from_catalogue</b> to update some piece of information, such
as a package version number.</p></dd>
<dt><a name="5"><b class="cmd">docstrip::util::modules_from_catalogue</b> <i class="arg">target</i> <i class="arg">source</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>This command is an alternative to <b class="cmd">index_from_catalogue</b> which
creates Tcl Module ("<b class="file">.tm</b>") files rather than
"<b class="file">pkgIndex.tcl</b>" entries. Since this action is more similar to
what <b class="syscmd"><a href="docstrip.html">docstrip</a></b> classically does, it has features for
putting pre- and postambles on the generated files.</p>
<p>The <i class="arg">source</i> argument is the name of the source file to
generate "<b class="file">.tm</b>" files from. The <i class="arg">target</i> argument is the
directory which should count as a module path, i.e., this is what
the relative paths derived from package names are joined to. The
supported options are:</p>
<dl class="doctools_options">
<dt><b class="option">-preamble</b> <i class="arg">message</i></dt>
<dd><p>A message to put in the preamble (initial block of comments) of
generated files. Defaults to a space. May be several lines, which
are then separated by newlines. Traditionally used for copyright
notices or the like, but metacomment lines provide an alternative
to that.</p></dd>
<dt><b class="option">-postamble</b> <i class="arg">message</i></dt>
<dd><p>Like <b class="option">-preamble</b>, but the message is put at the end of the
file instead of the beginning. Defaults to being empty.</p></dd>
<dt><b class="option">-sourceconf</b> <i class="arg">dictionary</i></dt>
<dd><p>Specify <b class="cmd">fileoptions</b> to use when reading the catalogue of
the <i class="arg">source</i> (and also for reading the packages if the
catalogue does not contain a <b class="cmd">fileoptions</b> command). Defaults
to being empty. Primarily useful if your system encoding is very
different from that of the source file (e.g., one is a two-byte
encoding and the other is a one-byte encoding). <b class="const">ascii</b> and
<b class="const">utf-8</b> are not very different in that sense.</p></dd>
<dt><b class="option">-options</b> <i class="arg">terminals</i></dt>
<dd><p>The <i class="arg">terminals</i> is a list of terminals in addition to
<b class="const">docstrip.tcl::catalogue</b> that should be held as true when
extracting the catalogue. Defaults to being empty. This makes it
possible to make use of "variant sections" in the catalogue
itself, e.g. gaurd some entries with an extra "experimental" guard
and thus prevent them from contributing packages unless those are
generated with "experimental" among the <b class="option">-options</b>.</p></dd>
<dt><b class="option">-formatpreamble</b> <i class="arg">commandPrefix</i></dt>
<dd><p>Command prefix used to actually format the preamble. Takes four
additional arguments <i class="arg">message</i>, <i class="arg">targetFilename</i>,
<i class="arg">sourceFilename</i>, and <i class="arg">terminalList</i> and returns a fully
formatted preamble. Defaults to using <b class="cmd">classical_preamble</b>
with a <i class="arg">metaprefix</i> of '##'.</p></dd>
<dt><b class="option">-formatpostamble</b> <i class="arg">commandPrefix</i></dt>
<dd><p>Command prefix used to actually format the postamble. Takes four
additional arguments <i class="arg">message</i>, <i class="arg">targetFilename</i>,
<i class="arg">sourceFilename</i>, and <i class="arg">terminalList</i> and returns a fully
formatted postamble. Defaults to using <b class="cmd">classical_postamble</b>
with a <i class="arg">metaprefix</i> of '##'.</p></dd>
<dt><b class="option">-report</b> <i class="arg">boolean</i></dt>
<dd><p>If the <i class="arg">boolean</i> is true (which is the default) then the return
value will be a textual, probably multiline, report on what was
done. If it is false then there is no particular return value.</p></dd>
<dt><b class="option">-reportcmd</b> <i class="arg">commandPrefix</i></dt>
<dd><p>Every item in the report is handed as an extra argument to this
command prefix. Defaults to <b class="cmd"><a href="../../../../index.html#list">list</a></b>, which effectively disables
this feature. The return values from the prefix are ignored. Use
for example "<b class="cmd">puts</b> <b class="const">stdout</b>" to get report items
written immediately to the terminal.</p></dd>
</dl>
<p>An existing file of the same name as one to be created will be
overwritten.</p></dd>
<dt><a name="6"><b class="cmd">docstrip::util::classical_preamble</b> <i class="arg">metaprefix</i> <i class="arg">message</i> <i class="arg">target</i> <span class="opt">?<i class="arg">source</i> <i class="arg">terminals</i> ...?</span></a></dt>
<dd><p>This command returns a preamble in the classical
<b class="syscmd"><a href="docstrip.html">docstrip</a></b> style</p>
<pre class="doctools_example">
##
## This is `TARGET',
## generated by the docstrip::util package.
##
## The original source files were:
##
## SOURCE (with options: `foo,bar')
##
## Some message line 1
## line2
## line3
</pre>
<p>if called as</p>
<pre class="doctools_example">
docstrip::util::classical_preamble {##}\
"\nSome message line 1\nline2\nline3" TARGET SOURCE {foo bar}
</pre>
<p>The command supports preambles for files generated from multiple
sources, even though <b class="cmd">modules_from_catalogue</b> at present does
not need that.</p></dd>
<dt><a name="7"><b class="cmd">docstrip::util::classical_postamble</b> <i class="arg">metaprefix</i> <i class="arg">message</i> <i class="arg">target</i> <span class="opt">?<i class="arg">source</i> <i class="arg">terminals</i> ...?</span></a></dt>
<dd><p>This command returns a postamble in the classical
<b class="syscmd"><a href="docstrip.html">docstrip</a></b> style</p>
<pre class="doctools_example">
## Some message line 1
## line2
## line3
##
## End of file `TARGET'.
</pre>
<p>if called as</p>
<pre class="doctools_example">
docstrip::util::classical_postamble {##}\
"Some message line 1\nline2\nline3" TARGET SOURCE {foo bar}
</pre>
<p>In other words, the <i class="arg">source</i> and <i class="arg">terminals</i> arguments are
ignored, but supported for symmetry with <b class="cmd">classical_preamble</b>.</p></dd>
<dt><a name="8"><b class="cmd">docstrip::util::packages_provided</b> <i class="arg">text</i> <span class="opt">?<i class="arg">setup-script</i>?</span></a></dt>
<dd><p>This command returns a list where every even index element is the
name of a package <b class="cmd">provide</b>d by <i class="arg">text</i> when that is
evaluated as a Tcl script, and the following odd index element is
the corresponding version. It is used to do package indexing of
extracted pieces of code, in the manner of <b class="cmd">pkg_mkIndex</b>.</p>
<p>One difference to <b class="cmd">pkg_mkIndex</b> is that the <i class="arg">text</i> gets
evaluated in a safe interpreter. <b class="cmd">package require</b> commands
are silently ignored, as are unknown commands (which includes
<b class="cmd"><a href="../../../../index.html#source">source</a></b> and <b class="cmd">load</b>). Other errors cause
processing of the <i class="arg">text</i> to stop, in which case only those
package declarations that had been encountered before the error
will be included in the return value.</p>
<p>The <i class="arg">setup-script</i> argument can be used to customise the
evaluation environment, if the code in <i class="arg">text</i> has some very
special needs. The <i class="arg">setup-script</i> is evaluated in the local
context of the <b class="cmd">packages_provided</b> procedure just before the
<i class="arg">text</i> is processed. At that time, the name of the slave
command for the safe interpreter that will do this processing is
kept in the local variable <b class="variable">c</b>. To for example copy the
contents of the <b class="variable">::env</b> array to the safe interpreter, one
might use a <i class="arg">setup-script</i> of</p>
<pre class="doctools_example"> $c eval [list array set env [array get ::env]]</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Source processing commands</a></h2>
<p>Unlike the previous group of commands, which would use
<b class="cmd">docstrip::extract</b> to extract some code lines and then process
those further, the following commands operate on text consisting of
all types of lines.</p>
<dl class="doctools_definitions">
<dt><a name="9"><b class="cmd">docstrip::util::ddt2man</b> <i class="arg">text</i></a></dt>
<dd><p>The <b class="cmd">ddt2man</b> command reformats <i class="arg">text</i> from the general
<b class="syscmd"><a href="docstrip.html">docstrip</a></b> format to <b class="package"><a href="../doctools/doctools.html">doctools</a></b> "<b class="file">.man</b>" format
(Tcl Markup Language for Manpages). The different line types are
treated as follows:</p>
<dl class="doctools_definitions">
<dt>comment and metacomment lines</dt>
<dd><p>The '%' and '%%' prefixes are removed, the rest of the text is
kept as it is.</p></dd>
<dt>empty lines</dt>
<dd><p>These are kept as they are. (Effectively this means that they will
count as comment lines after a comment line and as code lines
after a code line.)</p></dd>
<dt>code lines</dt>
<dd><p><b class="cmd">example_begin</b> and <b class="cmd">example_end</b> commands are placed
at the beginning and end of every block of consecutive code
lines. Brackets in a code line are converted to <b class="cmd">lb</b> and
<b class="cmd">rb</b> commands.</p></dd>
<dt>verbatim guards</dt>
<dd><p>These are processed as usual, so they do not show up in the
result but every line in a verbatim block is treated as a code
line.</p></dd>
<dt>other guards</dt>
<dd><p>These are treated as code lines, except that the actual guard is
<b class="cmd">emph</b>asised.</p></dd>
</dl>
<p>At the time of writing, no project has employed <b class="package"><a href="../doctools/doctools.html">doctools</a></b>
markup in master source files, so experience of what works well is
not available. A source file could however look as follows</p>
<pre class="doctools_example">
% [manpage_begin gcd n 1.0]
% [keywords divisor]
% [keywords math]
% [moddesc {Greatest Common Divisor}]
% [require gcd [opt 1.0]]
% [description]
%
% [list_begin definitions]
% [call [cmd gcd] [arg a] [arg b]]
% The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which
% must be integers and returns their greatest common divisor.
proc gcd {a b} {
% The first step is to take the absolute values of the arguments.
% This relieves us of having to worry about how signs will be treated
% by the remainder operation.
set a [expr {abs($a)}]
set b [expr {abs($b)}]
% The next line does all of Euclid's algorithm! We can make do
% without a temporary variable, since $a is substituted before the
% [lb]set a $b[rb] and thus continues to hold a reference to the
% "old" value of [var a].
while {$b>0} { set b [expr { $a % [set a $b] }] }
% In Tcl 8.3 we might want to use [cmd set] instead of [cmd return]
% to get the slight advantage of byte-compilation.
%<tcl83> set a
%<!tcl83> return $a
}
% [list_end]
%
% [manpage_end]
</pre>
<p>If the above text is fed through <b class="cmd">docstrip::util::ddt2man</b> then
the result will be a syntactically correct <b class="package"><a href="../doctools/doctools.html">doctools</a></b>
manpage, even though its purpose is a bit different.</p>
<p>It is suggested that master source code files with <b class="package"><a href="../doctools/doctools.html">doctools</a></b>
markup are given the suffix "<b class="file">.ddt</b>", hence the "ddt" in
<b class="cmd">ddt2man</b>.</p></dd>
<dt><a name="10"><b class="cmd">docstrip::util::guards</b> <i class="arg">subcmd</i> <i class="arg">text</i></a></dt>
<dd><p>The <b class="cmd">guards</b> command returns information (mostly of a
statistical nature) about the ordinary docstrip guards that occur
in the <i class="arg">text</i>. The <i class="arg">subcmd</i> selects what is returned.</p>
<dl class="doctools_definitions">
<dt><b class="method">counts</b></dt>
<dd><p>List the guard expression terminals with counts. The format of
the return value is a dictionary which maps the terminal name to
the number of occurencies of it in the file.</p></dd>
<dt><b class="method">exprcount</b></dt>
<dd><p>List the guard expressions with counts. The format of the return
value is a dictionary which maps the expression to the number of
occurencies of it in the file.</p></dd>
<dt><b class="method">exprerr</b></dt>
<dd><p>List the syntactically incorrect guard expressions (e.g.
parentheses do not match, or a terminal is missing). The return
value is a list, with the elements in no particular order.</p></dd>
<dt><b class="method">expressions</b></dt>
<dd><p>List the guard expressions. The return value is a list, with the
elements in no particular order.</p></dd>
<dt><b class="method">exprmods</b></dt>
<dd><p>List the guard expressions with modifiers. The format of the return
value is a dictionary where each index is a guard expression and
each entry is a string with one character for every guard line that
has this expression. The characters in the entry specify what
modifier was used in that line: +, -, *, /, or (for guard without
modifier:) space. This is the most primitive form of the
information gathered by <b class="cmd">guards</b>.</p></dd>
<dt><b class="method">names</b></dt>
<dd><p>List the guard expression terminals. The return value is a list,
with the elements in no particular order.</p></dd>
<dt><b class="method">rotten</b></dt>
<dd><p>List the malformed guard lines (this does not include lines where
only the expression is malformed, though). The format of the return
value is a dictionary which maps line numbers to their contents.</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">docstrip::util::patch</b> <i class="arg">source-var</i> <i class="arg">terminals</i> <i class="arg">fromtext</i> <i class="arg">diff</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>This command tries to apply a <b class="syscmd"><a href="../../../../index.html#diff">diff</a></b> file (for example a
contributed patch) that was computed for a generated file to the
<b class="syscmd"><a href="docstrip.html">docstrip</a></b> source. This can be useful if someone has
edited a generated file, thus mistaking it for being the source.
This command makes no presumptions which are specific for the case
that the generated file is a Tcl script.</p>
<p><b class="cmd"><a href="../../../../index.html#patch">patch</a></b> requires that the source file to patch is kept as a
list of lines in a variable, and the name of that variable in the
calling context is what goes into the <i class="arg">source-var</i> argument.
The <i class="arg">terminals</i> is the list of terminals used to extract the
file that has been patched. The <i class="arg">diff</i> is the actual diff to
apply (in a format as explained below) and the <i class="arg">fromtext</i> is
the contents of the file which served as "from" when the diff was
computed. Options can be used to further control the process.</p>
<p>The process works by "lifting" the hunks in the <i class="arg">diff</i> from
generated to source file, and then applying them to the elements of
the <i class="arg">source-var</i>. In order to do this lifting, it is necessary
to determine how lines in the <i class="arg">fromtext</i> correspond to elements
of the <i class="arg">source-var</i>, and that is where the <i class="arg">terminals</i> come
in; the source is first <b class="cmd">extract</b>ed under the given
<i class="arg">terminals</i>, and the result of that is then matched against
the <i class="arg">fromtext</i>. This produces a map which translates line
numbers stated in the <i class="arg">diff</i> to element numbers in
<i class="arg">source-var</i>, which is what is needed to lift the hunks.</p>
<p>The reason that both the <i class="arg">terminals</i> and the <i class="arg">fromtext</i>
must be given is twofold. First, it is very difficult to keep track
of how many lines of preamble are supplied some other way than by
copying lines from source files. Second, a generated file might
contain material from several source files. Both make it impossible
to predict what line number an extracted file would have in the
generated file, so instead the algorithm for computing the line
number map looks for a block of lines in the <i class="arg">fromtext</i> which
matches what can be extracted from the source. This matching is
affected by the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-matching</b> <i class="arg">mode</i></dt>
<dd><p>How equal must two lines be in order to match? The supported
<i class="arg">mode</i>s are:</p>
<dl class="doctools_definitions">
<dt><b class="const">exact</b></dt>
<dd><p>Lines must be equal as strings. This is the default.</p></dd>
<dt><b class="const">anyspace</b></dt>
<dd><p>All sequences of whitespace characters are converted to single
spaces before comparing.</p></dd>
<dt><b class="const">nonspace</b></dt>
<dd><p>Only non-whitespace characters are considered when comparing.</p></dd>
<dt><b class="const">none</b></dt>
<dd><p>Any two lines are considered to be equal.</p></dd>
</dl></dd>
<dt><b class="option">-metaprefix</b> <i class="arg">string</i></dt>
<dd><p>The <b class="option">-metaprefix</b> value to use when extracting. Defaults
to "%%", but for Tcl code it is more likely that "#" or "##" had
been used for the generated file.</p></dd>
<dt><b class="option">-trimlines</b> <i class="arg">boolean</i></dt>
<dd><p>The <b class="option">-trimlines</b> value to use when extracting. Defaults to
true.</p></dd>
</dl>
<p>The return value is in the form of a unified diff, containing only
those hunks which were not applied or were only partially applied;
a comment in the header of each hunk specifies which case is at
hand. It is normally necessary to manually review both the return
value from <b class="cmd"><a href="../../../../index.html#patch">patch</a></b> and the patched text itself, as this command
cannot adjust comment lines to match new content.</p>
<p>An example use would look like</p>
<pre class="doctools_example">
set sourceL [split [docstrip::util::thefile from.dtx] \n]
set terminals {foo bar baz}
set fromtext [docstrip::util::thefile from.tcl]
set difftext [exec diff --unified from.tcl to.tcl]
set leftover [docstrip::util::patch sourceL $terminals $fromtext\
[docstrip::util::import_unidiff $difftext] -metaprefix {#}]
set F [open to.dtx w]; puts $F [join $sourceL \n]; close $F
return $leftover
</pre>
<p>Here, "<b class="file">from.dtx</b>" was used as source for "<b class="file">from.tcl</b>", which
someone modified into "<b class="file">to.tcl</b>". We're trying to construct a
"<b class="file">to.dtx</b>" which can be used as source for "<b class="file">to.tcl</b>".</p></dd>
<dt><a name="12"><b class="cmd">docstrip::util::thefile</b> <i class="arg">filename</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>The <b class="cmd">thefile</b> command opens the file <i class="arg">filename</i>, reads it to
end, closes it, and returns the contents (dropping a final newline
if there is one). The option-value pairs are
passed on to <b class="cmd">fconfigure</b> to configure the open file channel
before anything is read from it.</p></dd>
<dt><a name="13"><b class="cmd">docstrip::util::import_unidiff</b> <i class="arg">diff-text</i> <span class="opt">?<i class="arg">warning-var</i>?</span></a></dt>
<dd><p>This command parses a unified (<b class="syscmd"><a href="../../../../index.html#diff">diff</a></b> flags <b class="option">-U</b> and
<b class="option">--unified</b>) format diff into the list-of-hunks format
expected by <b class="cmd">docstrip::util::patch</b>. The <i class="arg">diff-text</i>
argument is the text to parse and the <i class="arg">warning-var</i> is, if
specified, the name in the calling context of a variable to which
any warnings about parsing problems will be <b class="cmd">append</b>ed.</p>
<p>The return value is a list of <i class="term">hunks</i>. Each hunk is a list of
five elements "<i class="arg">start1</i> <i class="arg">end1</i> <i class="arg">start2</i> <i class="arg">end2</i>
<i class="arg">lines</i>". <i class="arg">start1</i> and <i class="arg">end1</i> are line numbers in the
"from" file of the first and last respectively lines of the hunk.
<i class="arg">start2</i> and <i class="arg">end2</i> are the corresponding line numbers in
the "to" file. Line numbers start at 1. The <i class="arg">lines</i> is a list
with two elements for each line in the hunk; the first specifies the
type of a line and the second is the actual line contents. The type
is <b class="const">-</b> for lines only in the "from" file, <b class="const">+</b> for lines
that are only in the "to" file, and <b class="const">0</b> for lines that are
in both.</p></dd>
</dl>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docstrip.html">docstrip</a>, <a href="../doctools/doctools.html">doctools</a>, doctools_fmt</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_ddt">.ddt</a>, <a href="../../../../index.html#_dtx">.dtx</a>, <a href="../../../../index.html#latex">LaTeX</a>, <a href="../../../../index.html#tcl_module">Tcl module</a>, <a href="../../../../index.html#catalogue">catalogue</a>, <a href="../../../../index.html#diff">diff</a>, <a href="../../../../index.html#docstrip">docstrip</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#literate_programming">literate programming</a>, <a href="../../../../index.html#module">module</a>, <a href="../../../../index.html#package_indexing">package indexing</a>, <a href="../../../../index.html#patch">patch</a>, <a href="../../../../index.html#source">source</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003–2010 Lars Hellström <Lars dot Hellstrom at residenset dot net></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/changelog.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<div class='fossil-doc' data-title='doctools::changelog - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::changelog(n) 1.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::changelog - Processing text in Emacs ChangeLog format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil</b></li>
<li>package require <b class="pkgname">doctools::changelog <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::changelog::scan</b> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">::doctools::changelog::flatten</b> <i class="arg">entries</i></a></li>
<li><a href="#3"><b class="cmd">::doctools::changelog::toDoctools</b> <i class="arg">title</i> <i class="arg">module</i> <i class="arg">version</i> <i class="arg">entries</i></a></li>
<li><a href="#4"><b class="cmd">::doctools::changelog::merge</b> <i class="arg">entries</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides Tcl commands for the processing and reformatting
of text in the "<b class="file">ChangeLog</b>" format generated by <b class="syscmd"><a href="../../../../index.html#emacs">emacs</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::changelog::scan</b> <i class="arg">text</i></a></dt>
<dd><p>The command takes the <i class="arg">text</i> and parses it under the assumption
that it contains a ChangeLog as generated by <b class="syscmd"><a href="../../../../index.html#emacs">emacs</a></b>. It
returns a data structure describing the contents of this ChangeLog.</p>
<p>This data structure is a list where each element describes one entry
in the ChangeLog. Each element/entry is then a list of three elements
describing the date of the entry, its author, and the comments made,
in this order. The last item in each element/entry, the comments, is a
list of sections. Each section is described by a list containing two
elements, a list of file names, and a string containing the true
comment associated with the files of the section.</p>
<pre class="doctools_example">
{
{
date
author
{
{
{file ...}
commenttext
}
...
}
}
{...}
}
</pre>
</dd>
<dt><a name="2"><b class="cmd">::doctools::changelog::flatten</b> <i class="arg">entries</i></a></dt>
<dd><p>This command converts a list of entries as generated by
<b class="cmd">change::scan</b> above into a simpler list of plain
text blocks each containing all the information of a
single entry.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::changelog::toDoctools</b> <i class="arg">title</i> <i class="arg">module</i> <i class="arg">version</i> <i class="arg">entries</i></a></dt>
<dd><p>This command converts the pre-parsed ChangeLog <i class="arg">entries</i> as
generated by the command <b class="cmd">::doctools::changelog::scan</b> into a
document in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format and returns it as the result of the
command.</p>
<p>The other three arguments supply the information for the header of
that document which is not available from the changelog itself.</p></dd>
<dt><a name="4"><b class="cmd">::doctools::changelog::merge</b> <i class="arg">entries</i>...</a></dt>
<dd><p>Each argument of the command is assumed to be a pre-parsed Changelog
as generated by the command <b class="cmd">::doctools::changelog::scan</b>. This
command merges all of them into a single structure, and collapses
multiple entries for the same date and author into a single entry. The
new structure is returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#changelog">changelog</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#emacs">emacs</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2013 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/cvs.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<div class='fossil-doc' data-title='doctools::cvs - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::cvs(n) 1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::cvs - Processing text in 'cvs log' format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil</b></li>
<li>package require <b class="pkgname">doctools::cvs <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::cvs::scanLog</b> <i class="arg">text</i> <i class="arg">evar</i> <i class="arg">cvar</i> <i class="arg">fvar</i></a></li>
<li><a href="#2"><b class="cmd">::doctools::cvs::toChangeLog</b> <i class="arg">evar</i> <i class="arg">cvar</i> <i class="arg">fvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides Tcl commands for the processing and reformatting
text in the format generated by the <b class="syscmd"><a href="../../../../index.html#cvs_log">cvs log</a></b> command.</p>
<p>The commands <b class="cmd">::doctools::cvs::scanLog</b>
and <b class="cmd">::doctools::cvs::toChangeLog</b> are derived from code found on
the <a href="http://wiki.tcl.tk">Tcl'ers Wiki</a>. See the references at the
end of the page.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::cvs::scanLog</b> <i class="arg">text</i> <i class="arg">evar</i> <i class="arg">cvar</i> <i class="arg">fvar</i></a></dt>
<dd><p>The command takes the <i class="arg">text</i> and parses it under the assumption
that it contains a CVS log as generated by <b class="syscmd"><a href="../../../../index.html#cvs_log">cvs log</a></b>. The
resulting information is stored in the variables whose names were
specified via <i class="arg">evar</i>, <i class="arg">cvar</i>, and <i class="arg">fvar</i>.</p>
<p>Already existing information in the referenced variables is preserved,
allowing the caller to merge data from multiple logs into one
database.</p>
<dl class="doctools_arguments">
<dt>varname <i class="arg">evar</i> (in)</dt>
<dd><p>Has to refer to a scalar variable. After the call this variable will
contain a list of all the entries found in the log file. An entry is
identified through the combination of date and author, and can be
split over multiple physical entries, one per touched file.</p>
<p>It should be noted that the entries are listed in the same order as
they were found in the <i class="arg">text</i>. This is not necessarily sorted by
date or author.</p>
<p>Each item in the list is a list containing two elements, the date of
the entry, and its author, in this order. The date is formatted as
<b class="variable">year</b>/<b class="variable">month</b>/<b class="variable">day</b>.</p></dd>
<dt>varname <i class="arg">cvar</i> (in)</dt>
<dd><p>Has to refer to an array variable. Keys are strings containing the
date and author of log entries, in this order, separated by a comma.</p>
<p>The values are lists of comments made for the entry.</p></dd>
<dt>varname <i class="arg">fvar</i> (in)</dt>
<dd><p>Has to refer to an array variable. Keys are strings containing
date, author of a log entry, and a comment for that entry, in this
order, separated by commas.</p>
<p>The values are lists of the files the entry is touching.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::doctools::cvs::toChangeLog</b> <i class="arg">evar</i> <i class="arg">cvar</i> <i class="arg">fvar</i></a></dt>
<dd><p>The three arguments for this command are the same as the last three
arguments of the command <b class="cmd">::doctools::cvs::scanLog</b>. This command
however expects them to be filled with information about one or more
logs. It takes this information and converts it into a text in the
format of a ChangeLog as accepted and generated by <b class="syscmd"><a href="../../../../index.html#emacs">emacs</a></b>. The
constructed text is returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>[uri, http://wiki.tcl.tk/log2changelog</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#changelog">changelog</a>, <a href="../../../../index.html#cvs">cvs</a>, <a href="../../../../index.html#cvs_log">cvs log</a>, <a href="../../../../index.html#emacs">emacs</a>, <a href="../../../../index.html#log">log</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
<div class='fossil-doc' data-title='doctools::idx - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx(n) 1.0.8 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx - docidx - Processing indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">PACKAGE COMMANDS</a></li>
<li class="doctools_subsection"><a href="#subsection2">OBJECT COMMAND</a></li>
<li class="doctools_subsection"><a href="#subsection3">OBJECT METHODS</a></li>
<li class="doctools_subsection"><a href="#subsection4">OBJECT CONFIGURATION</a></li>
<li class="doctools_subsection"><a href="#subsection5">FORMAT MAPPING</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PREDEFINED ENGINES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools::idx <span class="opt">?1.0.8?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx::new</b> <i class="arg">objectName</i> <span class="opt">?<b class="option">-option</b> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::idx::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::idx::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">format</b> <i class="arg">text</i></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">map</b> <i class="arg">symbolic</i> <i class="arg">actual</i></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">parameters</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">search</b> <i class="arg">path</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">setparam</b> <i class="arg">name</i> <i class="arg">value</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">warnings</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the creation of objects able to
process and convert text written in the <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> markup language
into any output format X for which a <i class="term"><a href="../../../../index.html#formatting_engine">formatting engine</a></i> is
available.</p>
<p>A reader interested in the markup language itself should start with
the <i class="term"><a href="docidx_lang_intro.html">docidx language introduction</a></i> and proceed from there to
the formal specifications, i.e. the <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i>
and the <i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i>.</p>
<p>If on the other hand the reader wishes to write her own formatting
engine for some format, i.e. is a <i class="term">plugin writer</i> then reading
and understanding the <i class="term"><a href="docidx_plugin_apiref.html">docidx plugin API reference</a></i> is an
absolute necessity, as that document specifies the interaction between
this package and its plugins, i.e. the formatting engines, in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">PACKAGE COMMANDS</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx::new</b> <i class="arg">objectName</i> <span class="opt">?<b class="option">-option</b> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>This command creates a new docidx object with an associated Tcl
command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command is
explained in full detail in the sections <span class="sectref"><a href="#subsection2">OBJECT COMMAND</a></span>
and <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p>
<p>The options and their values coming after the name of the object are
used to set the initial configuration of the object.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::idx::help</b></a></dt>
<dd><p>This is a convenience command for applications wishing to provide
their user with a short description of the available formatting
commands and their meanings. It returns a string containing a standard
help text.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::idx::search</b> <i class="arg">path</i></a></dt>
<dd><p>Whenever an object created by this the package has to map the name of
a format to the file containing the code for its formatting engine it
will search for the file in a number of directories stored in a
list. See section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span> for more explanations.</p>
<p>This list not only contains three default directories which are
declared by the package itself, but is also extensible user of the
package.
This command is the means to do so. When given a <i class="arg">path</i> to an
existing and readable directory it will prepend that directory to the
list of directories to search. This means that the <i class="arg">path</i> added
last is later searched through first.</p>
<p>An error will be thrown if the <i class="arg">path</i> either does not exist, is
not a directory, or is not readable.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">OBJECT COMMAND</a></h3>
<p>All commands created by <b class="cmd">::doctools::idx::new</b> have the following
general form and may be used to invoke various operations on their
docidx converter object.</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the exact
behavior of the command. See section <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span> for
the detailed specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OBJECT METHODS</a></h3>
<dl class="doctools_definitions">
<dt><a name="5"><i class="arg">objectName</i> <b class="method">configure</b></a></dt>
<dd><p>The method returns a list of all known options and their current
values when called without any arguments.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>The method behaves like the method <b class="method">cget</b> when called with a
single argument and returns the value of the option specified by said
argument.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>The method reconfigures the specified <b class="option">option</b>s of the object,
setting them to the associated <i class="arg">value</i>s, when called with an even
number of arguments, at least two.</p>
<p>The legal options are described in the section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></dt>
<dd><p>This method expects a legal configuration option as argument and will
return the current value of that option for the object the method was
invoked for.</p>
<p>The legal configuration options are described in section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">format</b> <i class="arg">text</i></a></dt>
<dd><p>This method runs the <i class="arg">text</i> through the configured formatting
engine and returns the generated string as its result. An error will
be thrown if no <b class="option">-format</b> was configured for the object.</p>
<p>The method assumes that the <i class="arg">text</i> is in <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> format as
specified in the companion document <i class="term">docidx_fmt</i>. Errors will be
thrown otherwise.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">map</b> <i class="arg">symbolic</i> <i class="arg">actual</i></a></dt>
<dd><p>This methods add one entry to the per-object mapping from
<i class="arg">symbolic</i> filenames to the <i class="arg">actual</i> uris.
The object just stores this mapping and makes it available to the
configured formatting engine through the command <b class="cmd">dt_fmap</b>.
This command is described in more detail in the
<i class="term"><a href="docidx_plugin_apiref.html">docidx plugin API reference</a></i> which specifies the interaction
between the objects created by this package and index formatting
engines.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">parameters</b></a></dt>
<dd><p>This method returns a list containing the names of all engine
parameters provided by the configured formatting engine. It will
return an empty list if the object is not yet configured for a
specific format.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">search</b> <i class="arg">path</i></a></dt>
<dd><p>This method extends the per-object list of paths searched for index
formatting engines. See also the command <b class="cmd">::doctools::idx::search</b>
on how to extend the per-package list of paths. Note that the path
entered last will be searched first.
For more details see section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span>.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">setparam</b> <i class="arg">name</i> <i class="arg">value</i></a></dt>
<dd><p>This method sets the <i class="arg">name</i>d engine parameter to the specified
<i class="arg">value</i>.
It will throw an error if the object is either not yet configured for
a specific format, or if the formatting engine for the configured
format does not provide a parameter with the given <i class="arg">name</i>.
The list of parameters provided by the configured formatting engine
can be retrieved through the method <b class="method">parameters</b>.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">warnings</b></a></dt>
<dd><p>This method returns a list containing all the warnings which were
generated by the configured formatting engine during the last
invocation of the method <b class="method">format</b>.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">OBJECT CONFIGURATION</a></h3>
<p>All docidx objects understand the following configuration options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> <i class="arg">file</i></dt>
<dd><p>The argument of this option is stored in the object and made available
to the configured formatting engine through the command <b class="cmd">dt_file</b>.
This command is described in more detail in the companion document
<i class="term">docidx_api</i> which specifies the API between the object and
formatting engines.</p>
<p>The default value of this option is the empty string.</p>
<p>The configured formatting engine should interpret the value as the
name of the file containing the document which is currently processed.</p></dd>
<dt><b class="option">-format</b> <i class="arg">text</i></dt>
<dd><p>The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the
method <b class="method">format</b>. Its default value is the empty string. The
method <b class="method">format</b> cannot be used if this option is not set to a
valid value at least once.</p>
<p>The package will immediately try to map the given name to a file
containing the code for a formatting engine generating that format. An
error will be thrown if this mapping fails. In that case a previously
configured format is left untouched.</p>
<p>The section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span> explains in detail how the
package and object will look for engine implementations.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">FORMAT MAPPING</a></h3>
<p>The package and object will perform the following algorithm when
trying to map a format name <i class="term">foo</i> to a file containing an
implementation of a formatting engine for <i class="term">foo</i>:</p>
<ol class="doctools_enumerated">
<li><p>If <i class="term">foo</i> is the name of an existing file then this file is
directly taken as the implementation.</p></li>
<li><p>If not, the list of per-object search paths is searched. For each
directory in the list the package checks if that directory contains a
file "<b class="file">idx.<i class="term">foo</i></b>". If yes, then that file is taken as the
implementation.</p>
<p>Note that this list of paths is initially empty and can be extended
through the object method <b class="method">search</b>.</p></li>
<li><p>If not, the list of package paths is searched.
For each directory in the list the package checks if that directory
contains a file "<b class="file">idx.<i class="term">foo</i></b>". If yes, then that file is taken
as the implementation.</p>
<p>This list of paths can be extended
through the command <b class="cmd">::doctools::idx::search</b>.
It contains initially one path, the subdirectory "<b class="file">mpformats</b>" of
the directory the package itself is located in. In other words, if the
package implementation "<b class="file">docidx.tcl</b>" is installed in the directory
"<b class="file">/usr/local/lib/tcllib/doctools</b>" then it will by default search
the directory "<b class="file">/usr/local/lib/tcllib/doctools/mpformats</b>" for
format implementations.</p></li>
<li><p>The mapping fails.</p></li>
</ol>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PREDEFINED ENGINES</a></h2>
<p>The package provides predefined formatting engines for the following
formats. Some of the formatting engines support engine
parameters. These will be explicitly highlighted.</p>
<dl class="doctools_definitions">
<dt>html</dt>
<dd><p>This engine generates HTML markup, for processing by web browsers and
the like. This engine supports three parameters:</p>
<dl class="doctools_definitions">
<dt>footer</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
before the <b class="const"></body></b> tag, closing the body of the generated
HTML.</p>
<p>This can be used to insert boilerplate footer markup into the
generated document.</p></dd>
<dt>header</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the <b class="const"><body></b> tag, starting the body of the generated HTML.</p>
<p>This can be used to insert boilerplate header markup into the
generated document.</p></dd>
<dt>meta</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the <b class="const"><head></b> tag, starting the header section of the
generated HTML.</p>
<p>This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.</p></dd>
</dl></dd>
<dt>latex</dt>
<dd><p>This engine generates output suitable for the <b class="syscmd"><a href="../../../../index.html#latex">latex</a></b> text
processor coming out of the TeX world.</p></dd>
<dt>list</dt>
<dd><p>This engine retrieves version, section and title of the manpage from
the document. As such it can be used to generate a directory listing
for a set of manpages.</p></dd>
<dt>nroff</dt>
<dd><p>This engine generates nroff output, for processing by <b class="syscmd"><a href="../../../../index.html#nroff">nroff</a></b>,
or <b class="syscmd">groff</b>. The result will be standard man pages as they are
known in the unix world.</p></dd>
<dt>null</dt>
<dd><p>This engine generates no outout at all. This can be used if one just
wants to validate some input.</p></dd>
<dt>tmml</dt>
<dd><p>This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.</p></dd>
<dt>wiki</dt>
<dd><p>This engine generates Wiki markup as understood by Jean Claude
Wippler's <b class="syscmd">wikit</b> application.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="docidx_lang_cmdref.html">docidx_lang_cmdref</a>, <a href="docidx_lang_intro.html">docidx_lang_intro</a>, <a href="docidx_lang_syntax.html">docidx_lang_syntax</a>, <a href="docidx_plugin_apiref.html">docidx_plugin_apiref</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#latex">latex</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2017 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
<div class='fossil-doc' data-title='docidx_intro - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docidx_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docidx_intro - docidx introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">RELATED FORMATS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#docidx">docidx</a></i> (short for <em>documentation tables of contents</em>)
stands for a set of related, yet different, entities which are working
together for the easy creation and transformation of keyword-based
indices for documentation. These are</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the semantic markup of a keyword index.
Markup is represented by Tcl commands.</p></li>
<li><p>A package providing the ability to read and transform texts written in
that markup language. It is important to note that the actual
transformation of the input text is delegated to plugins.</p></li>
<li><p>An API describing the interface between the package above and a
plugin.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the documentation process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of documentation has to understand the markup language
itself. A beginner to docidx should read the more informally written
<i class="term"><a href="docidx_lang_intro.html">docidx language introduction</a></i> first. Having digested this
the formal <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i> specification should
become understandable. A writer experienced with docidx may only
need the <i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i> from time to
time to refresh her memory.</p>
<p>While a document is written the <b class="syscmd">dtp</b> application can be used
to validate it, and after completion it also performs the conversion
into the chosen system of visual markup, be it *roff, HTML, plain
text, wiki, etc. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> application makes
internal use of docidx when handling directories of documentation,
automatically generating a proper keyword index for them.</p></li>
<li><p>A <i class="term">processor</i> of documentation written in the <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>
markup language has to know which tools are available for use.</p>
<p>The main tool is the aforementioned <b class="syscmd">dtp</b> application provided
by Tcllib. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does not expose docidx to the
user.
At the bottom level, common to both applications, however sits the
package <b class="package">doctoools::idx</b>, providing the basic facilities to
read and process files containing text in the docidx format.</p></li>
<li><p>At last, but not least, <i class="term">plugin writers</i> have to understand the
interaction between the <b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b> package and its
plugins, as described in the <i class="term"><a href="docidx_plugin_apiref.html">docidx plugin API reference</a></i>.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">RELATED FORMATS</a></h2>
<p>docidx does not stand alone, it has two companion formats. These are
called <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> and <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>, and they are for the markup
of <i class="term">tables of contents</i>, and general documentation,
respectively.
They are described in their own sets of documents, starting at the
<i class="term"><a href="doctoc_intro.html">doctoc introduction</a></i> and the <i class="term"><a href="doctools_intro.html">doctools introduction</a></i>,
respectively.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_lang_cmdref.html">docidx_lang_cmdref</a>, <a href="docidx_lang_faq.html">docidx_lang_faq</a>, <a href="docidx_lang_intro.html">docidx_lang_intro</a>, <a href="docidx_lang_syntax.html">docidx_lang_syntax</a>, <a href="docidx_plugin_apiref.html">docidx_plugin_apiref</a>, <a href="doctoc_intro.html">doctoc_intro</a>, <a href="../doctools2idx/idx_container.html">doctools::idx</a>, <a href="doctools_intro.html">doctools_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
<div class='fossil-doc' data-title='docidx_lang_cmdref - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docidx_lang_cmdref(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docidx_lang_cmdref - docidx language command reference</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#comment">comment</a></b> <i class="arg">plaintext</i></a></li>
<li><a href="#2"><b class="cmd">include</b> <i class="arg">filename</i></a></li>
<li><a href="#3"><b class="cmd">index_begin</b> <i class="arg">text</i> <i class="arg">title</i></a></li>
<li><a href="#4"><b class="cmd">index_end</b></a></li>
<li><a href="#5"><b class="cmd">key</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd">lb</b></a></li>
<li><a href="#7"><b class="cmd"><a href="../../../../index.html#manpage">manpage</a></b> <i class="arg">file</i> <i class="arg">text</i></a></li>
<li><a href="#8"><b class="cmd">rb</b></a></li>
<li><a href="#9"><b class="cmd"><a href="../../../../index.html#url">url</a></b> <i class="arg">url</i> <i class="arg">label</i></a></li>
<li><a href="#10"><b class="cmd">vset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#11"><b class="cmd">vset</b> <i class="arg">varname</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document specifies both names and syntax of all the commands
which together are the docidx markup language, version 1.
As this document is intended to be a reference the commands are listed
in alphabetical order, and the descriptions are relatively short.
A beginner should read the much more informally written
<i class="term"><a href="docidx_lang_intro.html">docidx language introduction</a></i> first.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#comment">comment</a></b> <i class="arg">plaintext</i></a></dt>
<dd><p>Index markup. The argument text is marked up as a comment standing
outside of the actual text of the document. Main use is in free-form
text.</p></dd>
<dt><a name="2"><b class="cmd">include</b> <i class="arg">filename</i></a></dt>
<dd><p>Templating. The contents of the named file are interpreted as text
written in the docidx markup and processed in the place of the
include command. The markup in the file has to be self-contained. It
is not possible for a markup command to cross the file boundaries.</p></dd>
<dt><a name="3"><b class="cmd">index_begin</b> <i class="arg">text</i> <i class="arg">title</i></a></dt>
<dd><p>Document structure. The command to start an index. The arguments are a
label for the whole group of documents the index refers to
(<i class="arg">text</i>) and the overall title text for the index (<i class="arg">title</i>),
without markup.</p>
<p>The label often is the name of the package (or extension) the
documents belong to.</p></dd>
<dt><a name="4"><b class="cmd">index_end</b></a></dt>
<dd><p>Document structure. Command to end an index. Anything in the document
coming after this command is in error.</p></dd>
<dt><a name="5"><b class="cmd">key</b> <i class="arg">text</i></a></dt>
<dd><p>Index structure. This command adds the keyword <i class="arg">text</i> to the
index.</p></dd>
<dt><a name="6"><b class="cmd">lb</b></a></dt>
<dd><p>Text. The command is replaced with a left bracket. Use in free-form
text. Required to avoid interpretation of a left bracket as the start
of a markup command. Its usage is restricted to the arguments of other
markup commands.</p></dd>
<dt><a name="7"><b class="cmd"><a href="../../../../index.html#manpage">manpage</a></b> <i class="arg">file</i> <i class="arg">text</i></a></dt>
<dd><p>Index structure. This command adds an element to the index which
refers to a document. The document is specified through the symbolic
name <i class="arg">file</i>. The <i class="arg">text</i> argument is used to label the
reference.</p>
<p>Symbolic names are used to preserve the convertibility of this format
to any output format. The actual name of the file will be inserted by
the chosen formatting engine when converting the input. This will be
based on a mapping from symbolic to actual names given to the engine.</p></dd>
<dt><a name="8"><b class="cmd">rb</b></a></dt>
<dd><p>Text. The command is replaced with a right bracket. Use in free-form
text. Required to avoid interpretation of a right bracket as the end
of a markup command. Its usage is restricted to the arguments of other
commands.</p></dd>
<dt><a name="9"><b class="cmd"><a href="../../../../index.html#url">url</a></b> <i class="arg">url</i> <i class="arg">label</i></a></dt>
<dd><p>Index structure. This is the second command to add an element to the
index. To refer to a document it is not using a symbolic name however,
but a (possibly format-specific) url describing the exact location of
the document indexed here.</p></dd>
<dt><a name="10"><b class="cmd">vset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Templating. In this form the command sets the named document variable
to the specified <i class="arg">value</i>. It does not generate output. I.e. the
command is replaced by the empty string.</p></dd>
<dt><a name="11"><b class="cmd">vset</b> <i class="arg">varname</i></a></dt>
<dd><p>Templating. In this form the command is replaced by the value of the
named document variable</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="docidx_lang_faq.html">docidx_lang_faq</a>, <a href="docidx_lang_intro.html">docidx_lang_intro</a>, <a href="docidx_lang_syntax.html">docidx_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#docidx_commands">docidx commands</a>, <a href="../../../../index.html#docidx_language">docidx language</a>, <a href="../../../../index.html#docidx_markup">docidx markup</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='docidx_lang_faq - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docidx_lang_faq(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docidx_lang_faq - docidx language faq</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">What is this document?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Where do I find docidx examples?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">What is this document?</a></h3>
<p>This document is currently mainly a placeholder, to be filled with
commonly asked questions about the docidx markup language
and companions, and their answers.</p>
<p>Please report any questions (and, if possible, answers) we should
consider for this document as explained in the section
<span class="sectref"><a href="#section4">Bugs, Ideas, Feedback</a></span> below.</p>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Where do I find docidx examples?</a></h3>
<p>We have no direct examples of documents written using docidx
markup. However the doctools processor <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does generate
a table of contents when processing a set of documents written in
doctools markup. The intermediate file for it uses docidx
markup and is not deleted when generation completes. Such files can
therefore serve as examples.</p>
<p><b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> is distributed as part of Tcllib, so to get it you
need one of</p>
<ol class="doctools_enumerated">
<li><p>A snapshot of Tcllib. How to retrieve such a snapshot and the
tools required for this are described at
<a href="/wiki?name=Development+Snapshots">Development Snapshots</a></p></li>
<li><p>A Tcllib release archive. They are available at the <a href="/home">home</a>
page.</p></li>
</ol>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_lang_cmdref.html">docidx_lang_cmdref</a>, <a href="docidx_lang_intro.html">docidx_lang_intro</a>, <a href="docidx_lang_syntax.html">docidx_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#docidx_commands">docidx commands</a>, <a href="../../../../index.html#docidx_language">docidx language</a>, <a href="../../../../index.html#docidx_markup">docidx markup</a>, <a href="../../../../index.html#docidx_syntax">docidx syntax</a>, <a href="../../../../index.html#examples">examples</a>, <a href="../../../../index.html#faq">faq</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<div class='fossil-doc' data-title='docidx_lang_intro - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docidx_lang_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docidx_lang_intro - docidx language introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Fundamentals</a></li>
<li class="doctools_subsection"><a href="#subsection2">Basic structure</a></li>
<li class="doctools_subsection"><a href="#subsection3">Advanced structure</a></li>
<li class="doctools_subsection"><a href="#subsection4">Escapes</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">FURTHER READING</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is an informal introduction to version 1 of the docidx
markup language based on a multitude of examples. After reading this a
writer should be ready to understand the two parts of the formal
specification, i.e. the <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i> specification
and the <i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Fundamentals</a></h3>
<p>While the <i class="term">docidx markup language</i> is quite similar to the
<i class="term">doctools markup language</i>, in the broadest terms possible,
there is one key difference. An index consists essentially only of
markup commands, with no plain text interspersed between them, except
for whitespace.</p>
<p>Each markup command is a Tcl command surrounded by a matching pair of
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
... [key {markup language}] ...
</pre>
<pre class="doctools_example">
... [manpage thefile \\
{file description}] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in docidx is</p>
<pre class="doctools_example">
[index_begin GROUPTITLE TITLE]
[index_end]
</pre>
<p>Not very useful, but valid. This also shows us that all docidx
documents consist of only one part where we will list all keys and
their references.</p>
<p>A more useful index will contain at least keywords, or short 'keys',
i.e. the phrases which were indexed. So:</p>
<pre class="doctools_example">
[index_begin GROUPTITLE TITLE]
[<b class="cmd">key markup</b>]
[<b class="cmd">key {semantic markup}]</b>]
[<b class="cmd">key {docidx markup}</b>]
[<b class="cmd">key {docidx language}</b>]
[<b class="cmd">key {docidx commands}</b>]
[index_end]
</pre>
<p>In the above example the command <b class="cmd">key</b> is used to declare the
keyword phrases we wish to be part of the index.</p>
<p>However a truly useful index does not only list the keyword phrases,
but will also contain references to documents associated with the
keywords. Here is a made-up index for all the manpages in the module
<i class="term"><a href="../../../../index.html#base64">base64</a></i>:</p>
<pre class="doctools_example">
[index_begin tcllib/base64 {De- & Encoding}]
[key base64]
[<b class="cmd">manpage base64</b>]
[key encoding]
[<b class="cmd">manpage base64</b>]
[<b class="cmd">manpage uuencode</b>]
[<b class="cmd">manpage yencode</b>]
[key uuencode]
[<b class="cmd">manpage uuencode</b>]
[key yEnc]
[<b class="cmd">manpage yencode</b>]
[key ydecode]
[<b class="cmd">manpage yencode</b>]
[key yencode]
[<b class="cmd">manpage yencode</b>]
[index_end]
</pre>
<p>In the above example the command <b class="cmd"><a href="../../../../index.html#manpage">manpage</a></b> is used to insert
references to documents, using symbolic file names, with each command
belonging to the last <b class="cmd">key</b> command coming before it.</p>
<p>The other command to insert references is <b class="cmd"><a href="../../../../index.html#url">url</a></b>. In contrast to
<b class="cmd"><a href="../../../../index.html#manpage">manpage</a></b> it uses explicit (possibly format-specific) urls to
describe the location of the referenced document. As such this command
is intended for the creation of references to external documents which
could not be handled in any other way.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Advanced structure</a></h3>
<p>In all previous examples we fudged a bit regarding the markup actually
allowed to be used before the <b class="cmd">index_begin</b> command opening the
document.</p>
<p>Instead of only whitespace the two templating commands <b class="cmd">include</b>
and <b class="cmd">vset</b> are also allowed, to enable the writer to either set
and/or import configuration settings relevant to the table of
contents. I.e. it is possible to write</p>
<pre class="doctools_example">
[<b class="cmd">include FILE</b>]
[<b class="cmd">vset VAR VALUE</b>]
[index_begin GROUPTITLE TITLE]
...
[index_end]
</pre>
<p>Even more important, these two commands are allowed anywhere where a
markup command is allowed, without regard for any other
structure.</p>
<pre class="doctools_example">
[index_begin GROUPTITLE TITLE]
[<b class="cmd">include FILE</b>]
[<b class="cmd">vset VAR VALUE</b>]
...
[index_end]
</pre>
<p>The only restriction <b class="cmd">include</b> has to obey is that the contents of
the included file must be valid at the place of the inclusion. I.e. a
file included before <b class="cmd">index_begin</b> may contain only the templating
commands <b class="cmd">vset</b> and <b class="cmd">include</b>, a file included after a key
may contain only manape or url references, and other keys, etc.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Escapes</a></h3>
<p>Beyond the 6 commands shown so far we have two more available.
However their function is not the marking up of index structure, but
the insertion of characters, namely <b class="const">[</b> and <b class="const">]</b>.
These commands, <b class="cmd">lb</b> and <b class="cmd">rb</b> respectively, are required
because our use of [ and ] to bracket markup commands makes it
impossible to directly use [ and ] within the text.</p>
<p>Our example of their use are the sources of the last sentence in the
previous paragraph, with some highlighting added.</p>
<pre class="doctools_example">
...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [<b class="cmd">lb</b>] and [<b class="cmd">rb</b>] to bracket markup commands makes it
impossible to directly use [<b class="cmd">lb</b>] and [<b class="cmd">rb</b>] within the text.
...
</pre>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">FURTHER READING</a></h2>
<p>Now that this document has been digested the reader, assumed to be a
<i class="term">writer</i> of documentation should be fortified enough to be able
to understand the formal <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i>
specification as well. From here on out the
<i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i> will also serve as the
detailed specification and cheat sheet for all available commands and
their syntax.</p>
<p>To be able to validate a document while writing it, it is also
recommended to familiarize oneself with Tclapps' ultra-configurable
<b class="syscmd">dtp</b>.</p>
<p>On the other hand, docidx is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> goes, creating an index for a set of
documents behind the scenes, without the writer having to do so on
their own.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="docidx_lang_cmdref.html">docidx_lang_cmdref</a>, <a href="docidx_lang_syntax.html">docidx_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#docidx_commands">docidx commands</a>, <a href="../../../../index.html#docidx_language">docidx language</a>, <a href="../../../../index.html#docidx_markup">docidx markup</a>, <a href="../../../../index.html#docidx_syntax">docidx syntax</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<div class='fossil-doc' data-title='docidx_lang_syntax - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docidx_lang_syntax(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docidx_lang_syntax - docidx language syntax</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Fundamentals</a></li>
<li class="doctools_section"><a href="#section3">Lexical definitions</a></li>
<li class="doctools_section"><a href="#section4">Syntax</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document contains the formal specification of the syntax of the
docidx markup language, version 1 in Backus-Naur-Form. This document
is intended to be a reference, complementing the
<i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i>.
A beginner should read the much more informally written
<i class="term"><a href="docidx_lang_intro.html">docidx language introduction</a></i> first before trying to
understand either this document or the command reference.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Fundamentals</a></h2>
<p>In the broadest terms possible the <i class="term">docidx markup language</i> is
like SGML and similar languages. A document written in this language
consists primarily of markup commands, with text embedded into it at
some places.</p>
<p>Each markup command is a just Tcl command surrounded by a matching
pair of <b class="const">[</b> and <b class="const">]</b>. Which commands are available,
and their arguments, i.e. syntax is specified in the
<i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i>.</p>
<p>In this document we specify first the lexeme, and then the syntax,
i.e. how we can mix text and markup commands with each other.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Lexical definitions</a></h2>
<p>In the syntax rules listed in the next section</p>
<ol class="doctools_enumerated">
<li><p><TEXT> stands for all text except markup commands.</p></li>
<li><p>Any XXX stands for the markup command [xxx] including its
arguments. Each markup command is a Tcl command surrounded by a
matching pair of <b class="const">[</b> and <b class="const">]</b>. Inside of these
delimiters the usual rules for a Tcl command apply with regard to word
quotation, nested commands, continuation lines, etc.</p></li>
<li><p><WHITE> stands for all text consisting only of spaces, newlines,
tabulators and the <b class="cmd"><a href="../../../../index.html#comment">comment</a></b> markup command.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Syntax</a></h2>
<p>The rules listed here specify only the syntax of docidx documents. The
lexical level of the language was covered in the previous section.</p>
<p>Regarding the syntax of the (E)BNF itself</p>
<ol class="doctools_enumerated">
<li><p>The construct { X } stands for zero or more occurrences of X.</p></li>
<li><p>The construct [ X ] stands for zero or one occurrence of X.</p></li>
</ol>
<p>The syntax:</p>
<pre class="doctools_example">
index = defs
INDEX_BEGIN
[ contents ]
INDEX_END
{ <WHITE> }
defs = { INCLUDE | VSET | <WHITE> }
contents = keyword { keyword }
keyword = defs KEY ref { ref }
ref = MANPAGE | URL | defs
</pre>
<p>At last a rule we were unable to capture in the EBNF syntax, as it is
about the arguments of the markup commands, something which is not
modeled here.</p>
<ol class="doctools_enumerated">
<li><p>The arguments of all markup commands have to be plain text, and/or text
markup commands, i.e. one of</p>
<ol class="doctools_enumerated">
<li><p><b class="cmd">lb</b>,</p></li>
<li><p><b class="cmd">rb</b>, or</p></li>
<li><p><b class="cmd">vset</b> (1-argument form).</p></li>
</ol>
</li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="docidx_lang_cmdref.html">docidx_lang_cmdref</a>, <a href="docidx_lang_faq.html">docidx_lang_faq</a>, <a href="docidx_lang_intro.html">docidx_lang_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#docidx_commands">docidx commands</a>, <a href="../../../../index.html#docidx_language">docidx language</a>, <a href="../../../../index.html#docidx_markup">docidx markup</a>, <a href="../../../../index.html#docidx_syntax">docidx syntax</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
|
<div class='fossil-doc' data-title='docidx_plugin_apiref - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">docidx_plugin_apiref(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>docidx_plugin_apiref - docidx plugin API reference</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a></li>
<li class="doctools_section"><a href="#section3">FRONTEND COMMANDS</a></li>
<li class="doctools_section"><a href="#section4">PLUGIN COMMANDS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Management commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Formatting commands</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">dt_fmap</b> <i class="arg">symfname</i></a></li>
<li><a href="#2"><b class="cmd">dt_format</b></a></li>
<li><a href="#3"><b class="cmd">dt_read</b> <i class="arg">file</i></a></li>
<li><a href="#4"><b class="cmd">dt_source</b> <i class="arg">file</i></a></li>
<li><a href="#5"><b class="cmd">ex_cappend</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd">ex_cget</b> <i class="arg">varname</i></a></li>
<li><a href="#7"><b class="cmd">ex_cis</b> <i class="arg">cname</i></a></li>
<li><a href="#8"><b class="cmd">ex_cname</b></a></li>
<li><a href="#9"><b class="cmd">ex_cpop</b> <i class="arg">cname</i></a></li>
<li><a href="#10"><b class="cmd">ex_cpush</b> <i class="arg">cname</i></a></li>
<li><a href="#11"><b class="cmd">ex_cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#12"><b class="cmd">ex_lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#13"><b class="cmd">ex_rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#14"><b class="cmd">idx_initialize</b></a></li>
<li><a href="#15"><b class="cmd">idx_listvariables</b></a></li>
<li><a href="#16"><b class="cmd">idx_numpasses</b></a></li>
<li><a href="#17"><b class="cmd">idx_postprocess</b> <i class="arg">text</i></a></li>
<li><a href="#18"><b class="cmd">idx_setup</b> <i class="arg">n</i></a></li>
<li><a href="#19"><b class="cmd">idx_shutdown</b></a></li>
<li><a href="#20"><b class="cmd">idx_varset</b> <i class="arg">varname</i> <i class="arg">text</i></a></li>
<li><a href="#21"><b class="cmd">fmt_plain_text</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is intended for <i class="term">plugin writers</i>, i.e. developers
wishing to write an index <i class="term"><a href="../../../../index.html#formatting_engine">formatting engine</a></i> for some output
format X.</p>
<p>It specifies the interaction between the <b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b>
package and its plugins, i.e. the interface any index formatting
engine has to comply with.</p>
<p>This document deals with version 1 of the interface.</p>
<p>A reader who is on the other hand more interested in the markup
language itself should start with the
<i class="term"><a href="docidx_lang_intro.html">docidx language introduction</a></i> and proceed from there to the
formal specifications, i.e. the <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i> and
the <i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<p>The API for an index formatting engine consists of two major sections.</p>
<p>On the one side we have a set of commands through which the plugin is
able to query the frontend. These commands are provided by the
frontend and linked into the plugin interpreter. Please see section
<span class="sectref"><a href="#section3">FRONTEND COMMANDS</a></span> for their detailed specification.</p>
<p>And on the other side the plugin has to provide its own set of
commands which will then be called by the frontend in a specific
sequence while processing input. They, again, fall into two
categories, management and formatting.
Please see section <span class="sectref"><a href="#section4">PLUGIN COMMANDS</a></span> and its subsections for
their detailed specification.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FRONTEND COMMANDS</a></h2>
<p>This section specifies the set of commands through which a plugin,
also known as an index formatting engine, is able to query the
frontend. These commands are provided by the frontend and linked into
the plugin interpreter.</p>
<p>I.e. an index formatting engine can assume that all of the following
commands are present when any of its own commands (as specified in
section <span class="sectref"><a href="#section4">PLUGIN COMMANDS</a></span>) are executed.</p>
<p>Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the
processor, nor can it damage the filesystem.
It is however able to either kill or hang the whole process, by
exiting, or running an infinite loop.</p>
<p>Coming back to the imported commands, all the commands with prefix
<em>dt_</em> provide limited access to specific parts of the frontend,
whereas the commands with prefix <em>ex_</em> provide access to the
state of the <b class="package"><a href="../textutil/expander.html">textutil::expander</a></b> object which does the main
parsing of the input within the frontend. These commands should not be
except under very special circumstances.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">dt_fmap</b> <i class="arg">symfname</i></a></dt>
<dd><p>Query command. It returns the actual pathname to use in the output in
place of the symbolic filename <i class="arg">symfname</i>. It will return the
unchanged input if no mapping was established for <i class="arg">symfname</i>.</p>
<p>The required mappings are established with the method <b class="method">map</b> of
a frontend, as explained in section <b class="sectref">OBJECT METHODS</b>
of the documentation for the package <b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b>.</p></dd>
<dt><a name="2"><b class="cmd">dt_format</b></a></dt>
<dd><p>Query command. It returns the name of the format associated with the
index formatting engine.</p></dd>
<dt><a name="3"><b class="cmd">dt_read</b> <i class="arg">file</i></a></dt>
<dd><p>Controlled filesystem access. Returns contents of <i class="arg">file</i> for
whatever use desired by the plugin.
Only files which are either in the same directory as the file
containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.</p></dd>
<dt><a name="4"><b class="cmd">dt_source</b> <i class="arg">file</i></a></dt>
<dd><p>Controlled filesystem access. This command allows the index formatting
engine to load additional Tcl code it may need.
Only files which are either in the same directory as the file
containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.</p></dd>
<dt><a name="5"><b class="cmd">ex_cappend</b> <i class="arg">text</i></a></dt>
<dd><p>Appends a string to the output in the current context. This command
should rarely be used by macros or application code.</p></dd>
<dt><a name="6"><b class="cmd">ex_cget</b> <i class="arg">varname</i></a></dt>
<dd><p>Retrieves the value of variable <i class="arg">varname</i>, defined in the current
context.</p></dd>
<dt><a name="7"><b class="cmd">ex_cis</b> <i class="arg">cname</i></a></dt>
<dd><p>Determines whether or not the name of the current context is
<i class="arg">cname</i>.</p></dd>
<dt><a name="8"><b class="cmd">ex_cname</b></a></dt>
<dd><p>Returns the name of the current context.</p></dd>
<dt><a name="9"><b class="cmd">ex_cpop</b> <i class="arg">cname</i></a></dt>
<dd><p>Pops a context from the context stack, returning all accumulated
output in that context. The context must be named <i class="arg">cname</i>, or an
error results.</p></dd>
<dt><a name="10"><b class="cmd">ex_cpush</b> <i class="arg">cname</i></a></dt>
<dd><p>Pushes a context named <i class="arg">cname</i> onto the context stack. The
context must be popped by <b class="method">cpop</b> before expansion ends or an
error results.</p></dd>
<dt><a name="11"><b class="cmd">ex_cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Sets variable <i class="arg">varname</i> to <i class="arg">value</i> in the current context.</p></dd>
<dt><a name="12"><b class="cmd">ex_lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the left macro expansion bracket; this is
for use as or within a macro, when the bracket needs to be included in
the output text. If <i class="arg">newbracket</i> is specified, it becomes the new
bracket, and is returned.</p></dd>
<dt><a name="13"><b class="cmd">ex_rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the right macro expansion bracket; this
is for use as or within a macro, when the bracket needs to be included
in the output text. If <i class="arg">newbracket</i> is specified, it becomes the
new bracket, and is returned.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PLUGIN COMMANDS</a></h2>
<p>The plugin has to provide its own set of commands which will then be
called by the frontend in a specific sequence while processing
input. They fall into two categories, management and formatting. Their
expected names, signatures, and responsibilities are specified in the
following two subsections.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Management commands</a></h3>
<p>The management commands a plugin has to provide are used by the
frontend to</p>
<ol class="doctools_enumerated">
<li><p>initialize and shutdown the plugin</p></li>
<li><p>determine the number of passes it has
to make over the input</p></li>
<li><p>initialize and shutdown each pass</p></li>
<li><p>query and initialize engine parameters</p></li>
</ol>
<p>After the plugin has been loaded and the frontend commands are
established the commands will be called in the following sequence:</p>
<pre class="doctools_example">
idx_numpasses -> n
idx_listvariables -> vars
idx_varset var1 value1
idx_varset var2 value2
...
idx_varset varK valueK
idx_initialize
idx_setup 1
...
idx_setup 2
...
...
idx_setup n
...
idx_postprocess
idx_shutdown
...
</pre>
<p>I.e. first the number of passes and the set of available engine
parameters is established, followed by calls setting the
parameters. That second part is optional.</p>
<p>After that the plugin is initialized, the specified number of passes
executed, the final result run through a global post processing step
and at last the plugin is shutdown again. This can be followed by more
conversions, restarting the sequence at <b class="cmd">idx_varset</b>.</p>
<p>In each of the passes, i.e. after the calls of <b class="cmd">idx_setup</b> the
frontend will process the input and call the formatting commands as
markup is encountered. This means that the sequence of formatting
commands is determined by the grammar of the docidx markup language,
as specified in the <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i> specification.</p>
<p>A different way of looking at the sequence is:</p>
<ul class="doctools_itemized">
<li><p>First some basic parameters are determined.</p></li>
<li><p>Then everything starting at the first <b class="cmd">idx_varset</b> to
<b class="cmd">idx_shutdown</b> forms a <i class="term">run</i>, the formatting of a
single input. Each run can be followed by more.</p></li>
<li><p>Embedded within each run we have one or more <i class="term">passes</i>,
each starting with <b class="cmd">idx_setup</b> and going until either the next
<b class="cmd">idx_setup</b> or <b class="cmd">idx_postprocess</b> is reached.</p>
<p>If more than one pass is required to perform the formatting only the
output of the last pass is relevant. The output of all the previous,
preparatory passes is ignored.</p></li>
</ul>
<p>The commands, their names, signatures, and responsibilities are, in
detail:</p>
<dl class="doctools_definitions">
<dt><a name="14"><b class="cmd">idx_initialize</b></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called at the beginning of every conversion run, as
the first command of that run. Note that a run is not a pass, but may
consist of multiple passes.
It has to initialize the general state of the plugin, beyond the
initialization done during the load. No return value is expected, and
any returned value is ignored.</p></dd>
<dt><a name="15"><b class="cmd">idx_listvariables</b></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Engine parameters</em>.
Second command is called after the plugin code has been loaded,
i.e. immediately after <b class="cmd">idx_numpasses</b>.
It has to return a list containing the names of the parameters the
frontend can set to configure the engine. This list can be empty.</p></dd>
<dt><a name="16"><b class="cmd">idx_numpasses</b></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Pass management</em>.
First command called after the plugin code has been loaded. No other
command of the engine will be called before it.
It has to return the number of passes this engine requires to fully
process the input document. This value has to be an integer number
greater or equal to one.</p></dd>
<dt><a name="17"><b class="cmd">idx_postprocess</b> <i class="arg">text</i></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called immediately after the last pass in a run. Its
argument is the result of the conversion generated by that pass. It is
provided to allow the engine to perform any global modifications of
the generated document. If no post-processing is required for a
specific format the command has to just return the argument.</p>
<p>Expected to return a value, the final result of formatting the input.</p></dd>
<dt><a name="18"><b class="cmd">idx_setup</b> <i class="arg">n</i></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Pass management</em>.
This command is called at the beginning of each pass over the input in
a run. Its argument is the number of the pass which has begun. Passes
are counted from <b class="const">1</b> upward.
The command has to set up the internal state of the plugin for this
particular pass. No return value is expected, and any returned value
is ignored.</p></dd>
<dt><a name="19"><b class="cmd">idx_shutdown</b></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called at the end of every conversion run. It is the
last command called in a run. It has to clean up of all the
run-specific state in the plugin.
After the call the engine has to be in a state which allows the
initiation of another run without fear that information from the last
run is leaked into this new run.
No return value is expected, and any returned value is ignored.</p></dd>
<dt><a name="20"><b class="cmd">idx_varset</b> <i class="arg">varname</i> <i class="arg">text</i></a></dt>
<dd><p><em>Engine parameters</em>.
This command is called by the frontend to set an engine parameter to a
particular value.
The parameter to change is specified by <i class="arg">varname</i>, the value to
set in <i class="arg">text</i>.</p>
<p>The command has to throw an error if an unknown <i class="arg">varname</i> is
used. Only the names returned by <b class="cmd">idx_listvariables</b> have to be
considered as known.</p>
<p>The values of all engine parameters have to persist between passes and
runs.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Formatting commands</a></h3>
<p>The formatting commands have to implement the formatting for the
output format, for all the markup commands of the docidx markup
language, except <b class="cmd">lb</b>, <b class="cmd">rb</b>, <b class="cmd">vset</b>, <b class="cmd">include</b>, and
<b class="cmd"><a href="../../../../index.html#comment">comment</a></b>. These exceptions are processed by the frontend and are
never seen by the plugin. In return a command for the formatting of
plain text has to be provided, something which has no markup in the
input at all.</p>
<p>This means, that each of the five markup commands specified in the
<i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i> and outside of the set of
exceptions listed above has an equivalent formatting command which
takes the same arguments as the markup command and whose name is the
name of markup command with the prefix <em>fmt_</em> added to it.</p>
<p>All commands are expected to format their input in some way per the
semantics specified in the command reference and to return whatever
part of this that they deem necessary as their result, which will be
added to the output.</p>
<p>To avoid essentially duplicating the command reference we do not list
any of the command here and simply refer the reader to the
<i class="term"><a href="docidx_lang_cmdref.html">docidx language command reference</a></i> for their signature and
description. The sole exception is the plain text formatter, which has
no equivalent markup command.</p>
<p>The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the docidx
markup language, as specified in the <i class="term"><a href="docidx_lang_syntax.html">docidx language syntax</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="21"><b class="cmd">fmt_plain_text</b> <i class="arg">text</i></a></dt>
<dd><p><em>No associated markup command</em>.</p>
<p>Called by the frontend for any plain text encountered in the
input. It has to perform any and all special processing required for
plain text.</p>
<p>The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.</p></dd>
</dl>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="docidx_lang_cmdref.html">docidx_lang_cmdref</a>, <a href="docidx_lang_faq.html">docidx_lang_faq</a>, <a href="docidx_lang_intro.html">docidx_lang_intro</a>, <a href="docidx_lang_syntax.html">docidx_lang_syntax</a>, <a href="../doctools2idx/idx_container.html">doctools::idx</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#formatting_engine">formatting engine</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#index_formatter">index formatter</a>, <a href="../../../../index.html#keywords">keywords</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
<div class='fossil-doc' data-title='doctools::toc - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc(n) 1.1.7 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc - doctoc - Processing tables of contents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">PACKAGE COMMANDS</a></li>
<li class="doctools_subsection"><a href="#subsection2">OBJECT COMMAND</a></li>
<li class="doctools_subsection"><a href="#subsection3">OBJECT METHODS</a></li>
<li class="doctools_subsection"><a href="#subsection4">OBJECT CONFIGURATION</a></li>
<li class="doctools_subsection"><a href="#subsection5">FORMAT MAPPING</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PREDEFINED ENGINES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools::toc <span class="opt">?1.1.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::toc::new</b> <i class="arg">objectName</i> <span class="opt">?<b class="option">-option</b> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::toc::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::toc::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">format</b> <i class="arg">text</i></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">map</b> <i class="arg">symbolic</i> <i class="arg">actual</i></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">parameters</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">search</b> <i class="arg">path</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">setparam</b> <i class="arg">name</i> <i class="arg">value</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">warnings</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the creation of objects able to
process and convert text written in the <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> markup language
into any output format X for which a <i class="term"><a href="../../../../index.html#formatting_engine">formatting engine</a></i> is
available.</p>
<p>A reader interested in the markup language itself should start with
the <i class="term"><a href="doctoc_lang_intro.html">doctoc language introduction</a></i> and proceed from there to
the formal specifications, i.e. the <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i>
and the <i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p>
<p>If on the other hand the reader wishes to write her own formatting
engine for some format, i.e. is a <i class="term">plugin writer</i> then reading
and understanding the <i class="term"><a href="doctoc_plugin_apiref.html">doctoc plugin API reference</a></i> is an
absolute necessity, as that document specifies the interaction between
this package and its plugins, i.e. the formatting engines, in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">PACKAGE COMMANDS</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::toc::new</b> <i class="arg">objectName</i> <span class="opt">?<b class="option">-option</b> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>This command creates a new doctoc object with an associated Tcl
command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command is
explained in full detail in the sections <span class="sectref"><a href="#subsection2">OBJECT COMMAND</a></span>
and <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p>
<p>The options and their values coming after the name of the object are
used to set the initial configuration of the object.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::toc::help</b></a></dt>
<dd><p>This is a convenience command for applications wishing to provide
their user with a short description of the available formatting
commands and their meanings. It returns a string containing a standard
help text.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::toc::search</b> <i class="arg">path</i></a></dt>
<dd><p>Whenever an object created by this the package has to map the name of
a format to the file containing the code for its formatting engine it
will search for the file in a number of directories stored in a
list. See section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span> for more explanations.</p>
<p>This list not only contains three default directories which are
declared by the package itself, but is also extensible user of the
package.
This command is the means to do so. When given a <i class="arg">path</i> to an
existing and readable directory it will prepend that directory to the
list of directories to search. This means that the <i class="arg">path</i> added
last is later searched through first.</p>
<p>An error will be thrown if the <i class="arg">path</i> either does not exist, is
not a directory, or is not readable.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">OBJECT COMMAND</a></h3>
<p>All commands created by <b class="cmd">::doctools::toc::new</b> have the following
general form and may be used to invoke various operations on their
doctoc converter object.</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the exact
behavior of the command. See section <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span> for
the detailed specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OBJECT METHODS</a></h3>
<dl class="doctools_definitions">
<dt><a name="5"><i class="arg">objectName</i> <b class="method">configure</b></a></dt>
<dd><p>The method returns a list of all known options and their current
values when called without any arguments.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>The method behaves like the method <b class="method">cget</b> when called with a
single argument and returns the value of the option specified by said
argument.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>The method reconfigures the specified <b class="option">option</b>s of the object,
setting them to the associated <i class="arg">value</i>s, when called with an even
number of arguments, at least two.</p>
<p>The legal options are described in the section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></dt>
<dd><p>This method expects a legal configuration option as argument and will
return the current value of that option for the object the method was
invoked for.</p>
<p>The legal configuration options are described in section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">format</b> <i class="arg">text</i></a></dt>
<dd><p>This method runs the <i class="arg">text</i> through the configured formatting
engine and returns the generated string as its result. An error will
be thrown if no <b class="option">-format</b> was configured for the object.</p>
<p>The method assumes that the <i class="arg">text</i> is in <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> format as
specified in the companion document <i class="term">doctoc_fmt</i>. Errors will be
thrown otherwise.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">map</b> <i class="arg">symbolic</i> <i class="arg">actual</i></a></dt>
<dd><p>This methods add one entry to the per-object mapping from
<i class="arg">symbolic</i> filenames to the <i class="arg">actual</i> uris.
The object just stores this mapping and makes it available to the
configured formatting engine through the command <b class="cmd">dt_fmap</b>.
This command is described in more detail in the
<i class="term"><a href="doctoc_plugin_apiref.html">doctoc plugin API reference</a></i> which specifies the interaction
between the objects created by this package and toc formatting
engines.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">parameters</b></a></dt>
<dd><p>This method returns a list containing the names of all engine
parameters provided by the configured formatting engine. It will
return an empty list if the object is not yet configured for a
specific format.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">search</b> <i class="arg">path</i></a></dt>
<dd><p>This method extends the per-object list of paths searched for toc
formatting engines. See also the command <b class="cmd">::doctools::toc::search</b>
on how to extend the per-package list of paths. Note that the path
entered last will be searched first.
For more details see section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span>.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">setparam</b> <i class="arg">name</i> <i class="arg">value</i></a></dt>
<dd><p>This method sets the <i class="arg">name</i>d engine parameter to the specified
<i class="arg">value</i>.
It will throw an error if the object is either not yet configured for
a specific format, or if the formatting engine for the configured
format does not provide a parameter with the given <i class="arg">name</i>.
The list of parameters provided by the configured formatting engine
can be retrieved through the method <b class="method">parameters</b>.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">warnings</b></a></dt>
<dd><p>This method returns a list containing all the warnings which were
generated by the configured formatting engine during the last
invocation of the method <b class="method">format</b>.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">OBJECT CONFIGURATION</a></h3>
<p>All doctoc objects understand the following configuration options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> <i class="arg">file</i></dt>
<dd><p>The argument of this option is stored in the object and made available
to the configured formatting engine through the command <b class="cmd">dt_file</b>.
This command is described in more detail in the companion document
<i class="term">doctoc_api</i> which specifies the API between the object and
formatting engines.</p>
<p>The default value of this option is the empty string.</p>
<p>The configured formatting engine should interpret the value as the
name of the file containing the document which is currently processed.</p></dd>
<dt><b class="option">-format</b> <i class="arg">text</i></dt>
<dd><p>The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the
method <b class="method">format</b>. Its default value is the empty string. The
method <b class="method">format</b> cannot be used if this option is not set to a
valid value at least once.</p>
<p>The package will immediately try to map the given name to a file
containing the code for a formatting engine generating that format. An
error will be thrown if this mapping fails. In that case a previously
configured format is left untouched.</p>
<p>The section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span> explains in detail how the
package and object will look for engine implementations.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">FORMAT MAPPING</a></h3>
<p>The package and object will perform the following algorithm when
trying to map a format name <i class="term">foo</i> to a file containing an
implementation of a formatting engine for <i class="term">foo</i>:</p>
<ol class="doctools_enumerated">
<li><p>If <i class="term">foo</i> is the name of an existing file then this file is
directly taken as the implementation.</p></li>
<li><p>If not, the list of per-object search paths is searched. For each
directory in the list the package checks if that directory contains a
file "<b class="file">toc.<i class="term">foo</i></b>". If yes, then that file is taken as the
implementation.</p>
<p>Note that this list of paths is initially empty and can be extended
through the object method <b class="method">search</b>.</p></li>
<li><p>If not, the list of package paths is searched.
For each directory in the list the package checks if that directory
contains a file "<b class="file">toc.<i class="term">foo</i></b>". If yes, then that file is taken
as the implementation.</p>
<p>This list of paths can be extended
through the command <b class="cmd">::doctools::toc::search</b>.
It contains initially one path, the subdirectory "<b class="file">mpformats</b>" of
the directory the package itself is located in. In other words, if the
package implementation "<b class="file">doctoc.tcl</b>" is installed in the directory
"<b class="file">/usr/local/lib/tcllib/doctools</b>" then it will by default search
the directory "<b class="file">/usr/local/lib/tcllib/doctools/mpformats</b>" for
format implementations.</p></li>
<li><p>The mapping fails.</p></li>
</ol>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PREDEFINED ENGINES</a></h2>
<p>The package provides predefined formatting engines for the following
formats. Some of the formatting engines support engine
parameters. These will be explicitly highlighted.</p>
<dl class="doctools_definitions">
<dt>html</dt>
<dd><p>This engine generates HTML markup, for processing by web browsers and
the like. This engine supports three parameters:</p>
<dl class="doctools_definitions">
<dt>footer</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
before the <b class="const"></body></b> tag, closing the body of the generated
HTML.</p>
<p>This can be used to insert boilerplate footer markup into the
generated document.</p></dd>
<dt>header</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the <b class="const"><body></b> tag, starting the body of the generated HTML.</p>
<p>This can be used to insert boilerplate header markup into the
generated document.</p></dd>
<dt>meta</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the <b class="const"><head></b> tag, starting the header section of the
generated HTML.</p>
<p>This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.</p></dd>
</dl></dd>
<dt>latex</dt>
<dd><p>This engine generates output suitable for the <b class="syscmd"><a href="../../../../index.html#latex">latex</a></b> text
processor coming out of the TeX world.</p></dd>
<dt>list</dt>
<dd><p>This engine retrieves version, section and title of the manpage from
the document. As such it can be used to generate a directory listing
for a set of manpages.</p></dd>
<dt>nroff</dt>
<dd><p>This engine generates nroff output, for processing by <b class="syscmd"><a href="../../../../index.html#nroff">nroff</a></b>,
or <b class="syscmd">groff</b>. The result will be standard man pages as they are
known in the unix world.</p></dd>
<dt>null</dt>
<dd><p>This engine generates no outout at all. This can be used if one just
wants to validate some input.</p></dd>
<dt>tmml</dt>
<dd><p>This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.</p></dd>
<dt>wiki</dt>
<dd><p>This engine generates Wiki markup as understood by Jean Claude
Wippler's <b class="syscmd">wikit</b> application.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctoc_intro.html">doctoc_intro</a>, <a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a>, <a href="doctoc_plugin_apiref.html">doctoc_plugin_apiref</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#latex">latex</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2017 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<div class='fossil-doc' data-title='doctoc_intro - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_intro - doctoc introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">RELATED FORMATS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> (short for <em>documentation tables of contents</em>)
stands for a set of related, yet different, entities which are working
together for the easy creation and transformation of tables of
contents for documentation. These are</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the semantic markup of a table of
contents. Markup is represented by Tcl commands.</p></li>
<li><p>A package providing the ability to read and transform texts written in
that markup language. It is important to note that the actual
transformation of the input text is delegated to plugins.</p></li>
<li><p>An API describing the interface between the package above and a
plugin.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the documentation process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of documentation has to understand the markup language
itself. A beginner to doctoc should read the more informally written
<i class="term"><a href="doctoc_lang_intro.html">doctoc language introduction</a></i> first. Having digested this
the formal <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i> specification should
become understandable. A writer experienced with doctoc may only
need the <i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i> from time to
time to refresh her memory.</p>
<p>While a document is written the <b class="syscmd">dtp</b> application can be used
to validate it, and after completion it also performs the conversion
into the chosen system of visual markup, be it *roff, HTML, plain
text, wiki, etc. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> application makes
internal use of doctoc when handling directories of documentation,
automatically generating a proper table of contents for them.</p></li>
<li><p>A <i class="term">processor</i> of documentation written in the <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>
markup language has to know which tools are available for use.</p>
<p>The main tool is the aforementioned <b class="syscmd">dtp</b> application provided
by Tcllib. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does not expose doctoc to the
user.
At the bottom level, common to both applications, however sits the
package <b class="package">doctoools::toc</b>, providing the basic facilities to
read and process files containing text in the doctoc format.</p></li>
<li><p>At last, but not least, <i class="term">plugin writers</i> have to understand the
interaction between the <b class="package"><a href="doctoc.html">doctools::toc</a></b> package and its
plugins, as described in the <i class="term"><a href="doctoc_plugin_apiref.html">doctoc plugin API reference</a></i>.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">RELATED FORMATS</a></h2>
<p>doctoc does not stand alone, it has two companion formats. These are
called <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> and <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>, and they are for the markup
of <i class="term">keyword indices</i>, and general documentation, respectively.
They are described in their own sets of documents, starting at the
<i class="term"><a href="docidx_intro.html">docidx introduction</a></i> and the <i class="term"><a href="doctools_intro.html">doctools introduction</a></i>,
respectively.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_faq.html">doctoc_lang_faq</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a>, <a href="doctoc_plugin_apiref.html">doctoc_plugin_apiref</a>, <a href="doctoc.html">doctools::toc</a>, <a href="doctools_intro.html">doctools_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
<div class='fossil-doc' data-title='doctoc_lang_cmdref - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_lang_cmdref(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_lang_cmdref - doctoc language command reference</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#comment">comment</a></b> <i class="arg">plaintext</i></a></li>
<li><a href="#2"><b class="cmd">division_end</b></a></li>
<li><a href="#3"><b class="cmd">division_start</b> <i class="arg">text</i> <span class="opt">?<i class="arg">symfile</i>?</span></a></li>
<li><a href="#4"><b class="cmd">include</b> <i class="arg">filename</i></a></li>
<li><a href="#5"><b class="cmd">item</b> <i class="arg">file</i> <i class="arg">text</i> <i class="arg">desc</i></a></li>
<li><a href="#6"><b class="cmd">lb</b></a></li>
<li><a href="#7"><b class="cmd">rb</b></a></li>
<li><a href="#8"><b class="cmd">toc_begin</b> <i class="arg">text</i> <i class="arg">title</i></a></li>
<li><a href="#9"><b class="cmd">toc_end</b></a></li>
<li><a href="#10"><b class="cmd">vset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#11"><b class="cmd">vset</b> <i class="arg">varname</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document specifies both names and syntax of all the commands
which together are the doctoc markup language, version 1.
As this document is intended to be a reference the commands are listed
in alphabetical order, and the descriptions are relatively short.
A beginner should read the much more informally written
<i class="term"><a href="doctoc_lang_intro.html">doctoc language introduction</a></i> first.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#comment">comment</a></b> <i class="arg">plaintext</i></a></dt>
<dd><p>Toc markup. The argument text is marked up as a comment standing
outside of the actual text of the document. Main use is in free-form
text.</p></dd>
<dt><a name="2"><b class="cmd">division_end</b></a></dt>
<dd><p>Toc structure. This command closes the division opened by the last
<b class="cmd">division_begin</b> command coming before it, and not yet closed.</p></dd>
<dt><a name="3"><b class="cmd">division_start</b> <i class="arg">text</i> <span class="opt">?<i class="arg">symfile</i>?</span></a></dt>
<dd><p>Toc structure. This command opens a division in the table of
contents. Its counterpart is <b class="cmd">division_end</b>. Together they allow a
user to give a table of contents additional structure.</p>
<p>The title of the new division is provided by the argument <i class="arg">text</i>.</p>
<p>If the symbolic filename <i class="arg">symfile</i> is present then the section
title should link to the referenced document, if links are supported
by the output format.</p></dd>
<dt><a name="4"><b class="cmd">include</b> <i class="arg">filename</i></a></dt>
<dd><p>Templating. The contents of the named file are interpreted as text
written in the doctoc markup and processed in the place of the
include command. The markup in the file has to be self-contained. It
is not possible for a markup command to cross the file boundaries.</p></dd>
<dt><a name="5"><b class="cmd">item</b> <i class="arg">file</i> <i class="arg">text</i> <i class="arg">desc</i></a></dt>
<dd><p>Toc structure. This command adds an individual element to the table of
contents. Each such element refers to a document. The document is
specified through the symbolic name <i class="arg">file</i>. The <i class="arg">text</i>
argument is used to label the reference, whereas the <i class="arg">desc</i>
provides a short descriptive text of that document.</p>
<p>The symbolic names are used to preserve the convertibility of this
format to any output format. The actual name of the file will be
inserted by the chosen formatting engine when converting the
input. This will be based on a mapping from symbolic to actual names
given to the engine.</p></dd>
<dt><a name="6"><b class="cmd">lb</b></a></dt>
<dd><p>Text. The command is replaced with a left bracket. Use in free-form
text. Required to avoid interpretation of a left bracket as the start
of a markup command. Its usage is restricted to the arguments of other
markup commands.</p></dd>
<dt><a name="7"><b class="cmd">rb</b></a></dt>
<dd><p>Text. The command is replaced with a right bracket. Use in free-form
text. Required to avoid interpretation of a right bracket as the end
of a markup command. Its usage is restricted to the arguments of other
commands.</p></dd>
<dt><a name="8"><b class="cmd">toc_begin</b> <i class="arg">text</i> <i class="arg">title</i></a></dt>
<dd><p>Document structure. The command to start a table of contents. The
arguments are a label for the whole group of documents the index
refers to (<i class="arg">text</i>) and the overall title text for the index
(<i class="arg">title</i>), without markup.</p>
<p>The label often is the name of the package (or extension) the
documents belong to.</p></dd>
<dt><a name="9"><b class="cmd">toc_end</b></a></dt>
<dd><p>Document structure. Command to end a table of contents. Anything in
the document coming after this command is in error.</p></dd>
<dt><a name="10"><b class="cmd">vset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Templating. In this form the command sets the named document variable
to the specified <i class="arg">value</i>. It does not generate output. I.e. the
command is replaced by the empty string.</p></dd>
<dt><a name="11"><b class="cmd">vset</b> <i class="arg">varname</i></a></dt>
<dd><p>Templating. In this form the command is replaced by the value of the
named document variable</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctoc_intro.html">doctoc_intro</a>, <a href="doctoc_lang_faq.html">doctoc_lang_faq</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctoc_commands">doctoc commands</a>, <a href="../../../../index.html#doctoc_language">doctoc language</a>, <a href="../../../../index.html#doctoc_markup">doctoc markup</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='doctoc_lang_faq - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_lang_faq(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_lang_faq - doctoc language faq</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">What is this document?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Where do I find doctoc examples?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">What is this document?</a></h3>
<p>This document is currently mainly a placeholder, to be filled with
commonly asked questions about the doctoc markup language
and companions, and their answers.</p>
<p>Please report any questions (and, if possible, answers) we should
consider for this document as explained in the section
<span class="sectref"><a href="#section4">Bugs, Ideas, Feedback</a></span> below.</p>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Where do I find doctoc examples?</a></h3>
<p>We have no direct examples of documents written using doctoc
markup. However the doctools processor <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does generate
a table of contents when processing a set of documents written in
doctools markup. The intermediate file for it uses doctoc
markup and is not deleted when generation completes. Such files can
therefore serve as examples.</p>
<p><b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> is distributed as part of Tcllib, so to get it you
need one of</p>
<ol class="doctools_enumerated">
<li><p>A snapshot of Tcllib. How to retrieve such a snapshot and the
tools required for this are described at
<a href="/wiki?name=Development+Snapshots">Development Snapshots</a></p></li>
<li><p>A Tcllib release archive. They are available at the <a href="/home">home</a>
page.</p></li>
</ol>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctoc_commands">doctoc commands</a>, <a href="../../../../index.html#doctoc_language">doctoc language</a>, <a href="../../../../index.html#doctoc_markup">doctoc markup</a>, <a href="../../../../index.html#doctoc_syntax">doctoc syntax</a>, <a href="../../../../index.html#examples">examples</a>, <a href="../../../../index.html#faq">faq</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
|
<div class='fossil-doc' data-title='doctoc_lang_intro - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_lang_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_lang_intro - doctoc language introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Fundamentals</a></li>
<li class="doctools_subsection"><a href="#subsection2">Basic structure</a></li>
<li class="doctools_subsection"><a href="#subsection3">Items</a></li>
<li class="doctools_subsection"><a href="#subsection4">Divisions</a></li>
<li class="doctools_subsection"><a href="#subsection5">Advanced structure</a></li>
<li class="doctools_subsection"><a href="#subsection6">Escapes</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">FURTHER READING</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is an informal introduction to version 1.1 of the doctoc
markup language based on a multitude of examples. After reading this a
writer should be ready to understand the two parts of the formal
specification, i.e. the <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i> specification
and the <i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Fundamentals</a></h3>
<p>While the <i class="term">doctoc markup language</i> is quite similar to the
<i class="term">doctools markup language</i>, in the broadest terms possible,
there is one key difference. A table of contents consists essentially
only of markup commands, with no plain text interspersed between them,
except for whitespace.</p>
<p>Each markup command is a Tcl command surrounded by a matching pair of
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
... [division_start {Appendix 1}] ...
</pre>
<pre class="doctools_example">
... [item thefile \\
label {file description}] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in doctoc is</p>
<pre class="doctools_example">
[toc_begin GROUPTITLE TITLE]
[toc_end]
</pre>
<p>This also shows us that all doctoc documents consist of only one
part where we will list <i class="term">items</i> and <i class="term">divisions</i>.</p>
<p>The user is free to mix these as she sees fit. This is a change from
version 1 of the language, which did not allow this mixing, but only
the use of either a series of items or a series of divisions.</p>
<p>We will discuss the commands for each of these two possibilities in
the next sections.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Items</a></h3>
<p>Use the command <b class="cmd">item</b> to put an <i class="term">item</i> into a table of
contents. This is essentially a reference to a section, subsection,
etc. in the document, or set of documents, the table of contents is
for. The command takes three arguments, a symbolic name for the file
the item is for and two text to label the item and describe the
referenced section.</p>
<p>Symbolic names are used to preserve the convertibility of this format
to any output format. The actual name of any file will be inserted by
the chosen formatting engine when converting the input, based on a
mapping from symbolic to actual names given to the engine.</p>
<p>Here a made up example for a table of contents of this document:</p>
<pre class="doctools_example">
[toc_begin Doctoc {Language Introduction}]
[<b class="cmd">item 1 DESCRIPTION</b>]
[<b class="cmd">item 1.1 {Basic structure}</b>]
[<b class="cmd">item 1.2 Items</b>]
[<b class="cmd">item 1.3 Divisions</b>]
[<b class="cmd">item 2 {FURTHER READING}</b>]
[toc_end]
</pre>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Divisions</a></h3>
<p>One thing of notice in the last example in the previous section is
that the referenced sections actually had a nested structure,
something which was expressed in the item labels, by using a common
prefix for all the sections nested under section 1.</p>
<p>This kind of structure can be made more explicit in the doctoc
language by using divisions. Instead of using a series of plain items
we use a series of divisions for the major references, and then place
the nested items inside of these.</p>
<p>Of course, instead of the nested items we can again use divisions and
thus nest arbitrarily deep.</p>
<p>A division is marked by two commands instead of one, one to start it,
the other to close the last opened division. They are:</p>
<dl class="doctools_commands">
<dt><b class="cmd">division_start</b></dt>
<dd><p>This command opens a new division. It takes one or two arguments, the
title of the division, and the symbolic name of the file it refers
to. The latter is optional.
If the symbolic filename is present then the section title should link
to the referenced document, if links are supported by the output
format.</p></dd>
<dt><b class="cmd">division_end</b></dt>
<dd><p>This command closes the last opened and not yet closed division.</p></dd>
</dl>
<p>Using this we can recast the last example like this</p>
<pre class="doctools_example">
[toc_begin Doctoc {Language Introduction}]
[<b class="cmd">division_start DESCRIPTION</b>]
[item 1 {Basic structure}]
[item 2 Items]
[item 3 Divisions]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_start {FURTHER READING}</b>]
[<b class="cmd">division_end</b>]
[toc_end]
</pre>
<p>Or, to demonstrate deeper nesting</p>
<pre class="doctools_example">
[toc_begin Doctoc {Language Introduction}]
[<b class="cmd">division_start DESCRIPTION</b>]
[<b class="cmd">division_start {Basic structure}</b>]
[item 1 Do]
[item 2 Re]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_start Items</b>]
[item a Fi]
[item b Fo]
[item c Fa]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_start Divisions</b>]
[item 1 Sub]
[item 1 Zero]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_start {FURTHER READING}</b>]
[<b class="cmd">division_end</b>]
[toc_end]
</pre>
<p>And do not forget, it is possible to freely mix items and divisions,
and to have empty divisions.</p>
<pre class="doctools_example">
[toc_begin Doctoc {Language Introduction}]
[item 1 Do]
[<b class="cmd">division_start DESCRIPTION</b>]
[<b class="cmd">division_start {Basic structure}</b>]
[item 2 Re]
[<b class="cmd">division_end</b>]
[item a Fi]
[<b class="cmd">division_start Items</b>]
[item b Fo]
[item c Fa]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_start Divisions</b>]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_end</b>]
[<b class="cmd">division_start {FURTHER READING}</b>]
[<b class="cmd">division_end</b>]
[toc_end]
</pre>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Advanced structure</a></h3>
<p>In all previous examples we fudged a bit regarding the markup actually
allowed to be used before the <b class="cmd">toc_begin</b> command opening the
document.</p>
<p>Instead of only whitespace the two templating commands <b class="cmd">include</b>
and <b class="cmd">vset</b> are also allowed, to enable the writer to either set
and/or import configuration settings relevant to the table of
contents. I.e. it is possible to write</p>
<pre class="doctools_example">
[<b class="cmd">include FILE</b>]
[<b class="cmd">vset VAR VALUE</b>]
[toc_begin GROUPTITLE TITLE]
...
[toc_end]
</pre>
<p>Even more important, these two commands are allowed anywhere where a
markup command is allowed, without regard for any other
structure.</p>
<pre class="doctools_example">
[toc_begin GROUPTITLE TITLE]
[<b class="cmd">include FILE</b>]
[<b class="cmd">vset VAR VALUE</b>]
...
[toc_end]
</pre>
<p>The only restriction <b class="cmd">include</b> has to obey is that the contents of
the included file must be valid at the place of the inclusion. I.e. a
file included before <b class="cmd">toc_begin</b> may contain only the templating
commands <b class="cmd">vset</b> and <b class="cmd">include</b>, a file included in a division
may contain only items or divisions commands, etc.</p>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Escapes</a></h3>
<p>Beyond the 6 commands shown so far we have two more available.
However their function is not the marking up of toc structure, but the
insertion of characters, namely <b class="const">[</b> and <b class="const">]</b>.
These commands, <b class="cmd">lb</b> and <b class="cmd">rb</b> respectively, are required
because our use of [ and ] to bracket markup commands makes it
impossible to directly use [ and ] within the text.</p>
<p>Our example of their use are the sources of the last sentence in the
previous paragraph, with some highlighting added.</p>
<pre class="doctools_example">
...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [<b class="cmd">lb</b>] and [<b class="cmd">rb</b>] to bracket markup commands makes it
impossible to directly use [<b class="cmd">lb</b>] and [<b class="cmd">rb</b>] within the text.
...
</pre>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">FURTHER READING</a></h2>
<p>Now that this document has been digested the reader, assumed to be a
<i class="term">writer</i> of documentation should be fortified enough to be able
to understand the formal <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i>
specification as well. From here on out the
<i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i> will also serve as the
detailed specification and cheat sheet for all available commands and
their syntax.</p>
<p>To be able to validate a document while writing it, it is also
recommended to familiarize oneself with Tclapps' ultra-configurable
<b class="syscmd">dtp</b>.</p>
<p>On the other hand, doctoc is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> goes, creating a table of contents
for a set of documents behind the scenes, without the writer having to
do so on their own.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctoc_intro.html">doctoc_intro</a>, <a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctoc_commands">doctoc commands</a>, <a href="../../../../index.html#doctoc_language">doctoc language</a>, <a href="../../../../index.html#doctoc_markup">doctoc markup</a>, <a href="../../../../index.html#doctoc_syntax">doctoc syntax</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<div class='fossil-doc' data-title='doctoc_lang_syntax - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_lang_syntax(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_lang_syntax - doctoc language syntax</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Fundamentals</a></li>
<li class="doctools_section"><a href="#section3">Lexical definitions</a></li>
<li class="doctools_section"><a href="#section4">Syntax</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document contains the formal specification of the syntax of the
doctoc markup language, version 1.1 in Backus-Naur-Form. This document
is intended to be a reference, complementing the
<i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i>.
A beginner should read the much more informally written
<i class="term"><a href="doctoc_lang_intro.html">doctoc language introduction</a></i> first before trying to
understand either this document or the command reference.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Fundamentals</a></h2>
<p>In the broadest terms possible the <i class="term">doctoc markup language</i> is
like SGML and similar languages. A document written in this language
consists primarily of markup commands, with text embedded into it at
some places.</p>
<p>Each markup command is a just Tcl command surrounded by a matching
pair of <b class="const">[</b> and <b class="const">]</b>. Which commands are available,
and their arguments, i.e. syntax is specified in the
<i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p>
<p>In this document we specify first the lexeme, and then the syntax,
i.e. how we can mix text and markup commands with each other.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Lexical definitions</a></h2>
<p>In the syntax rules listed in the next section</p>
<ol class="doctools_enumerated">
<li><p><TEXT> stands for all text except markup commands.</p></li>
<li><p>Any XXX stands for the markup command [xxx] including its
arguments. Each markup command is a Tcl command surrounded by a
matching pair of <b class="const">[</b> and <b class="const">]</b>. Inside of these
delimiters the usual rules for a Tcl command apply with regard to word
quotation, nested commands, continuation lines, etc.</p></li>
<li><p><WHITE> stands for all text consisting only of spaces, newlines,
tabulators and the <b class="cmd"><a href="../../../../index.html#comment">comment</a></b> markup command.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Syntax</a></h2>
<p>The rules listed here specify only the syntax of doctoc documents. The
lexical level of the language was covered in the previous section.</p>
<p>Regarding the syntax of the (E)BNF itself</p>
<ol class="doctools_enumerated">
<li><p>The construct { X } stands for zero or more occurrences of X.</p></li>
<li><p>The construct [ X ] stands for zero or one occurrence of X.</p></li>
</ol>
<p>The syntax:</p>
<pre class="doctools_example">
toc = defs
TOC_BEGIN
contents
TOC_END
{ <WHITE> }
defs = { INCLUDE | VSET | <WHITE> }
contents = { defs entry } [ defs ]
entry = ITEM | division
division = DIVISION_START
contents
DIVISION_END
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctoc_intro.html">doctoc_intro</a>, <a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_faq.html">doctoc_lang_faq</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctoc_commands">doctoc commands</a>, <a href="../../../../index.html#doctoc_language">doctoc language</a>, <a href="../../../../index.html#doctoc_markup">doctoc markup</a>, <a href="../../../../index.html#doctoc_syntax">doctoc syntax</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
|
<div class='fossil-doc' data-title='doctoc_plugin_apiref - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_plugin_apiref(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_plugin_apiref - doctoc plugin API reference</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a></li>
<li class="doctools_section"><a href="#section3">FRONTEND COMMANDS</a></li>
<li class="doctools_section"><a href="#section4">PLUGIN COMMANDS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Management commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Formatting commands</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">dt_fmap</b> <i class="arg">symfname</i></a></li>
<li><a href="#2"><b class="cmd">dt_format</b></a></li>
<li><a href="#3"><b class="cmd">dt_read</b> <i class="arg">file</i></a></li>
<li><a href="#4"><b class="cmd">dt_source</b> <i class="arg">file</i></a></li>
<li><a href="#5"><b class="cmd">ex_cappend</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd">ex_cget</b> <i class="arg">varname</i></a></li>
<li><a href="#7"><b class="cmd">ex_cis</b> <i class="arg">cname</i></a></li>
<li><a href="#8"><b class="cmd">ex_cname</b></a></li>
<li><a href="#9"><b class="cmd">ex_cpop</b> <i class="arg">cname</i></a></li>
<li><a href="#10"><b class="cmd">ex_cpush</b> <i class="arg">cname</i></a></li>
<li><a href="#11"><b class="cmd">ex_cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#12"><b class="cmd">ex_lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#13"><b class="cmd">ex_rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#14"><b class="cmd">toc_initialize</b></a></li>
<li><a href="#15"><b class="cmd">toc_listvariables</b></a></li>
<li><a href="#16"><b class="cmd">toc_numpasses</b></a></li>
<li><a href="#17"><b class="cmd">toc_postprocess</b> <i class="arg">text</i></a></li>
<li><a href="#18"><b class="cmd">toc_setup</b> <i class="arg">n</i></a></li>
<li><a href="#19"><b class="cmd">toc_shutdown</b></a></li>
<li><a href="#20"><b class="cmd">toc_varset</b> <i class="arg">varname</i> <i class="arg">text</i></a></li>
<li><a href="#21"><b class="cmd">fmt_plain_text</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is intended for <i class="term">plugin writers</i>, i.e. developers
wishing to write a toc <i class="term"><a href="../../../../index.html#formatting_engine">formatting engine</a></i> for some output
format X.</p>
<p>It specifies the interaction between the <b class="package"><a href="doctoc.html">doctools::toc</a></b>
package and its plugins, i.e. the interface any toc formatting engine
has to comply with.</p>
<p>This document deals with version 1 of the interface.</p>
<p>A reader who is on the other hand more interested in the markup
language itself should start with the
<i class="term"><a href="doctoc_lang_intro.html">doctoc language introduction</a></i> and proceed from there to the
formal specifications, i.e. the <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i> and
the <i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<p>The API for a toc formatting engine consists of two major sections.</p>
<p>On the one side we have a set of commands through which the plugin is
able to query the frontend. These commands are provided by the
frontend and linked into the plugin interpreter. Please see section
<span class="sectref"><a href="#section3">FRONTEND COMMANDS</a></span> for their detailed specification.</p>
<p>And on the other side the plugin has to provide its own set of
commands which will then be called by the frontend in a specific
sequence while processing input. They, again, fall into two
categories, management and formatting.
Please see section <span class="sectref"><a href="#section4">PLUGIN COMMANDS</a></span> and its subsections for
their detailed specification.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FRONTEND COMMANDS</a></h2>
<p>This section specifies the set of commands through which a plugin,
also known as a toc formatting engine, is able to query the
frontend. These commands are provided by the frontend and linked into
the plugin interpreter.</p>
<p>I.e. a toc formatting engine can assume that all of the following
commands are present when any of its own commands (as specified in
section <span class="sectref"><a href="#section4">PLUGIN COMMANDS</a></span>) are executed.</p>
<p>Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the
processor, nor can it damage the filesystem.
It is however able to either kill or hang the whole process, by
exiting, or running an infinite loop.</p>
<p>Coming back to the imported commands, all the commands with prefix
<em>dt_</em> provide limited access to specific parts of the frontend,
whereas the commands with prefix <em>ex_</em> provide access to the
state of the <b class="package"><a href="../textutil/expander.html">textutil::expander</a></b> object which does the main
parsing of the input within the frontend. These commands should not be
except under very special circumstances.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">dt_fmap</b> <i class="arg">symfname</i></a></dt>
<dd><p>Query command. It returns the actual pathname to use in the output in
place of the symbolic filename <i class="arg">symfname</i>. It will return the
unchanged input if no mapping was established for <i class="arg">symfname</i>.</p>
<p>The required mappings are established with the method <b class="method">map</b> of
a frontend, as explained in section <b class="sectref">OBJECT METHODS</b>
of the documentation for the package <b class="package"><a href="doctoc.html">doctools::toc</a></b>.</p></dd>
<dt><a name="2"><b class="cmd">dt_format</b></a></dt>
<dd><p>Query command. It returns the name of the format associated with the
toc formatting engine.</p></dd>
<dt><a name="3"><b class="cmd">dt_read</b> <i class="arg">file</i></a></dt>
<dd><p>Controlled filesystem access. Returns contents of <i class="arg">file</i> for
whatever use desired by the plugin.
Only files which are either in the same directory as the file
containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.</p></dd>
<dt><a name="4"><b class="cmd">dt_source</b> <i class="arg">file</i></a></dt>
<dd><p>Controlled filesystem access. This command allows the toc formatting
engine to load additional Tcl code it may need.
Only files which are either in the same directory as the file
containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.</p></dd>
<dt><a name="5"><b class="cmd">ex_cappend</b> <i class="arg">text</i></a></dt>
<dd><p>Appends a string to the output in the current context. This command
should rarely be used by macros or application code.</p></dd>
<dt><a name="6"><b class="cmd">ex_cget</b> <i class="arg">varname</i></a></dt>
<dd><p>Retrieves the value of variable <i class="arg">varname</i>, defined in the current
context.</p></dd>
<dt><a name="7"><b class="cmd">ex_cis</b> <i class="arg">cname</i></a></dt>
<dd><p>Determines whether or not the name of the current context is
<i class="arg">cname</i>.</p></dd>
<dt><a name="8"><b class="cmd">ex_cname</b></a></dt>
<dd><p>Returns the name of the current context.</p></dd>
<dt><a name="9"><b class="cmd">ex_cpop</b> <i class="arg">cname</i></a></dt>
<dd><p>Pops a context from the context stack, returning all accumulated
output in that context. The context must be named <i class="arg">cname</i>, or an
error results.</p></dd>
<dt><a name="10"><b class="cmd">ex_cpush</b> <i class="arg">cname</i></a></dt>
<dd><p>Pushes a context named <i class="arg">cname</i> onto the context stack. The
context must be popped by <b class="method">cpop</b> before expansion ends or an
error results.</p></dd>
<dt><a name="11"><b class="cmd">ex_cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Sets variable <i class="arg">varname</i> to <i class="arg">value</i> in the current context.</p></dd>
<dt><a name="12"><b class="cmd">ex_lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the left macro expansion bracket; this is
for use as or within a macro, when the bracket needs to be included in
the output text. If <i class="arg">newbracket</i> is specified, it becomes the new
bracket, and is returned.</p></dd>
<dt><a name="13"><b class="cmd">ex_rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the right macro expansion bracket; this
is for use as or within a macro, when the bracket needs to be included
in the output text. If <i class="arg">newbracket</i> is specified, it becomes the
new bracket, and is returned.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PLUGIN COMMANDS</a></h2>
<p>The plugin has to provide its own set of commands which will then be
called by the frontend in a specific sequence while processing
input. They fall into two categories, management and formatting. Their
expected names, signatures, and responsibilities are specified in the
following two subsections.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Management commands</a></h3>
<p>The management commands a plugin has to provide are used by the
frontend to</p>
<ol class="doctools_enumerated">
<li><p>initialize and shutdown the plugin</p></li>
<li><p>determine the number of passes it has
to make over the input</p></li>
<li><p>initialize and shutdown each pass</p></li>
<li><p>query and initialize engine parameters</p></li>
</ol>
<p>After the plugin has been loaded and the frontend commands are
established the commands will be called in the following sequence:</p>
<pre class="doctools_example">
toc_numpasses -> n
toc_listvariables -> vars
toc_varset var1 value1
toc_varset var2 value2
...
toc_varset varK valueK
toc_initialize
toc_setup 1
...
toc_setup 2
...
...
toc_setup n
...
toc_postprocess
toc_shutdown
...
</pre>
<p>I.e. first the number of passes and the set of available engine
parameters is established, followed by calls setting the
parameters. That second part is optional.</p>
<p>After that the plugin is initialized, the specified number of passes
executed, the final result run through a global post processing step
and at last the plugin is shutdown again. This can be followed by more
conversions, restarting the sequence at <b class="cmd">toc_varset</b>.</p>
<p>In each of the passes, i.e. after the calls of <b class="cmd">toc_setup</b> the
frontend will process the input and call the formatting commands as
markup is encountered. This means that the sequence of formatting
commands is determined by the grammar of the doctoc markup language,
as specified in the <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i> specification.</p>
<p>A different way of looking at the sequence is:</p>
<ul class="doctools_itemized">
<li><p>First some basic parameters are determined.</p></li>
<li><p>Then everything starting at the first <b class="cmd">toc_varset</b> to
<b class="cmd">toc_shutdown</b> forms a <i class="term">run</i>, the formatting of a
single input. Each run can be followed by more.</p></li>
<li><p>Embedded within each run we have one or more <i class="term">passes</i>,
each starting with <b class="cmd">toc_setup</b> and going until either the next
<b class="cmd">toc_setup</b> or <b class="cmd">toc_postprocess</b> is reached.</p>
<p>If more than one pass is required to perform the formatting only the
output of the last pass is relevant. The output of all the previous,
preparatory passes is ignored.</p></li>
</ul>
<p>The commands, their names, signatures, and responsibilities are, in
detail:</p>
<dl class="doctools_definitions">
<dt><a name="14"><b class="cmd">toc_initialize</b></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called at the beginning of every conversion run, as
the first command of that run. Note that a run is not a pass, but may
consist of multiple passes.
It has to initialize the general state of the plugin, beyond the
initialization done during the load. No return value is expected, and
any returned value is ignored.</p></dd>
<dt><a name="15"><b class="cmd">toc_listvariables</b></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Engine parameters</em>.
Second command is called after the plugin code has been loaded,
i.e. immediately after <b class="cmd">toc_numpasses</b>.
It has to return a list containing the names of the parameters the
frontend can set to configure the engine. This list can be empty.</p></dd>
<dt><a name="16"><b class="cmd">toc_numpasses</b></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Pass management</em>.
First command called after the plugin code has been loaded. No other
command of the engine will be called before it.
It has to return the number of passes this engine requires to fully
process the input document. This value has to be an integer number
greater or equal to one.</p></dd>
<dt><a name="17"><b class="cmd">toc_postprocess</b> <i class="arg">text</i></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called immediately after the last pass in a run. Its
argument is the result of the conversion generated by that pass. It is
provided to allow the engine to perform any global modifications of
the generated document. If no post-processing is required for a
specific format the command has to just return the argument.</p>
<p>Expected to return a value, the final result of formatting the input.</p></dd>
<dt><a name="18"><b class="cmd">toc_setup</b> <i class="arg">n</i></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Pass management</em>.
This command is called at the beginning of each pass over the input in
a run. Its argument is the number of the pass which has begun. Passes
are counted from <b class="const">1</b> upward.
The command has to set up the internal state of the plugin for this
particular pass. No return value is expected, and any returned value
is ignored.</p></dd>
<dt><a name="19"><b class="cmd">toc_shutdown</b></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called at the end of every conversion run. It is the
last command called in a run. It has to clean up of all the
run-specific state in the plugin.
After the call the engine has to be in a state which allows the
initiation of another run without fear that information from the last
run is leaked into this new run.
No return value is expected, and any returned value is ignored.</p></dd>
<dt><a name="20"><b class="cmd">toc_varset</b> <i class="arg">varname</i> <i class="arg">text</i></a></dt>
<dd><p><em>Engine parameters</em>.
This command is called by the frontend to set an engine parameter to a
particular value.
The parameter to change is specified by <i class="arg">varname</i>, the value to
set in <i class="arg">text</i>.</p>
<p>The command has to throw an error if an unknown <i class="arg">varname</i> is
used. Only the names returned by <b class="cmd">toc_listvariables</b> have to be
considered as known.</p>
<p>The values of all engine parameters have to persist between passes and
runs.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Formatting commands</a></h3>
<p>The formatting commands have to implement the formatting for the
output format, for all the markup commands of the doctoc markup
language, except <b class="cmd">lb</b>, <b class="cmd">rb</b>, <b class="cmd">vset</b>, <b class="cmd">include</b>, and
<b class="cmd"><a href="../../../../index.html#comment">comment</a></b>. These exceptions are processed by the frontend and are
never seen by the plugin. In return a command for the formatting of
plain text has to be provided, something which has no markup in the
input at all.</p>
<p>This means, that each of the five markup commands specified in the
<i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i> and outside of the set of
exceptions listed above has an equivalent formatting command which
takes the same arguments as the markup command and whose name is the
name of markup command with the prefix <em>fmt_</em> added to it.</p>
<p>All commands are expected to format their input in some way per the
semantics specified in the command reference and to return whatever
part of this that they deem necessary as their result, which will be
added to the output.</p>
<p>To avoid essentially duplicating the command reference we do not list
any of the command here and simply refer the reader to the
<i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i> for their signature and
description. The sole exception is the plain text formatter, which has
no equivalent markup command.</p>
<p>The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the doctoc
markup language, as specified in the <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="21"><b class="cmd">fmt_plain_text</b> <i class="arg">text</i></a></dt>
<dd><p><em>No associated markup command</em>.</p>
<p>Called by the frontend for any plain text encountered in the
input. It has to perform any and all special processing required for
plain text.</p>
<p>The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.</p></dd>
</dl>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctoc_intro.html">doctoc_intro</a>, <a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_faq.html">doctoc_lang_faq</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a>, <a href="doctoc.html">doctools::toc</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#formatting_engine">formatting engine</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a>, <a href="../../../../index.html#toc_formatter">toc formatter</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
|
<div class='fossil-doc' data-title='doctools - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools(n) 1.4.21 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools - doctools - Processing documents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">PACKAGE COMMANDS</a></li>
<li class="doctools_subsection"><a href="#subsection2">OBJECT COMMAND</a></li>
<li class="doctools_subsection"><a href="#subsection3">OBJECT METHODS</a></li>
<li class="doctools_subsection"><a href="#subsection4">OBJECT CONFIGURATION</a></li>
<li class="doctools_subsection"><a href="#subsection5">FORMAT MAPPING</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PREDEFINED ENGINES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">doctools <span class="opt">?1.4.21?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::help</b></a></li>
<li><a href="#3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></li>
<li><a href="#4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">format</b> <i class="arg">text</i></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">map</b> <i class="arg">symbolic</i> <i class="arg">actual</i></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">parameters</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">search</b> <i class="arg">path</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">setparam</b> <i class="arg">name</i> <i class="arg">value</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">warnings</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the creation of objects able to
process and convert text written in the <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> markup
language into any output format X for which a
<i class="term"><a href="../../../../index.html#formatting_engine">formatting engine</a></i> is available.</p>
<p>A reader interested in the markup language itself should start with
the <i class="term"><a href="doctools_lang_intro.html">doctools language introduction</a></i> and proceed from there to
the formal specifications, i.e. the <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i>
and the <i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i>.</p>
<p>If on the other hand the reader wishes to write her own formatting
engine for some format, i.e. is a <i class="term">plugin writer</i> then reading
and understanding the <i class="term"><a href="doctools_plugin_apiref.html">doctools plugin API reference</a></i> is an
absolute necessity, as that document specifies the interaction between
this package and its plugins, i.e. the formatting engines, in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">PACKAGE COMMANDS</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::new</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></dt>
<dd><p>This command creates a new doctools object with an associated Tcl
command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command is
explained in full detail in the sections <span class="sectref"><a href="#subsection2">OBJECT COMMAND</a></span>
and <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p>
<p>The options and their values coming after the name of the object are
used to set the initial configuration of the object.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::help</b></a></dt>
<dd><p>This is a convenience command for applications wishing to provide
their user with a short description of the available formatting
commands and their meanings. It returns a string containing a standard
help text.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::search</b> <i class="arg">path</i></a></dt>
<dd><p>Whenever an object created by this the package has to map the name of
a format to the file containing the code for its formatting engine it
will search for the file in a number of directories stored in a
list. See section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span> for more explanations.</p>
<p>This list not only contains three default directories which are
declared by the package itself, but is also extensible user of the
package.
This command is the means to do so. When given a <i class="arg">path</i> to an
existing and readable directory it will prepend that directory to the
list of directories to search. This means that the <i class="arg">path</i> added
last is later searched through first.</p>
<p>An error will be thrown if the <i class="arg">path</i> either does not exist, is
not a directory, or is not readable.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">OBJECT COMMAND</a></h3>
<p>All commands created by <b class="cmd">::doctools::new</b> have the following
general form and may be used to invoke various operations on their
doctools converter object.</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the exact
behavior of the command. See section <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span> for
the detailed specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OBJECT METHODS</a></h3>
<dl class="doctools_definitions">
<dt><a name="5"><i class="arg">objectName</i> <b class="method">configure</b></a></dt>
<dd><p>The method returns a list of all known options and their current
values when called without any arguments.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>The method behaves like the method <b class="method">cget</b> when called with a
single argument and returns the value of the option specified by said
argument.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>The method reconfigures the specified <b class="option">option</b>s of the object,
setting them to the associated <i class="arg">value</i>s, when called with an even
number of arguments, at least two.</p>
<p>The legal options are described in the section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></dt>
<dd><p>This method expects a legal configuration option as argument and will
return the current value of that option for the object the method was
invoked for.</p>
<p>The legal configuration options are described in section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">format</b> <i class="arg">text</i></a></dt>
<dd><p>This method runs the <i class="arg">text</i> through the configured formatting
engine and returns the generated string as its result. An error will
be thrown if no <b class="option">-format</b> was configured for the object.</p>
<p>The method assumes that the <i class="arg">text</i> is in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format as
specified in the companion document <i class="term">doctools_fmt</i>. Errors will
be thrown otherwise.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">map</b> <i class="arg">symbolic</i> <i class="arg">actual</i></a></dt>
<dd><p>This methods add one entry to the per-object mapping from
<i class="arg">symbolic</i> filenames to the <i class="arg">actual</i> uris.
The object just stores this mapping and makes it available to the
configured formatting engine through the command <b class="cmd">dt_fmap</b>.
This command is described in more detail in the
<i class="term"><a href="doctools_plugin_apiref.html">doctools plugin API reference</a></i> which specifies the interaction
between the objects created by this package and doctools formatting
engines.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">parameters</b></a></dt>
<dd><p>This method returns a list containing the names of all engine
parameters provided by the configured formatting engine. It will
return an empty list if the object is not yet configured for a
specific format.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">search</b> <i class="arg">path</i></a></dt>
<dd><p>This method extends the per-object list of paths searched for doctools
formatting engines. See also the command <b class="cmd">::doctools::search</b> on
how to extend the per-package list of paths. Note that the path
entered last will be searched first.
For more details see section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span>.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">setparam</b> <i class="arg">name</i> <i class="arg">value</i></a></dt>
<dd><p>This method sets the <i class="arg">name</i>d engine parameter to the specified
<i class="arg">value</i>.
It will throw an error if the object is either not yet configured for
a specific format, or if the formatting engine for the configured
format does not provide a parameter with the given <i class="arg">name</i>.
The list of parameters provided by the configured formatting engine
can be retrieved through the method <b class="method">parameters</b>.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">warnings</b></a></dt>
<dd><p>This method returns a list containing all the warnings which were
generated by the configured formatting engine during the last
invocation of the method <b class="method">format</b>.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">OBJECT CONFIGURATION</a></h3>
<p>All doctools objects understand the following configuration options:</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> <i class="arg">file</i></dt>
<dd><p>The argument of this option is stored in the object and made available
to the configured formatting engine through the commands <b class="cmd">dt_file</b>
and <b class="cmd">dt_mainfile</b>.
These commands are described in more detail in the companion document
<i class="term">doctools_api</i> which specifies the API between the object and
formatting engines.</p>
<p>The default value of this option is the empty string.</p>
<p>The configured formatting engine should interpret the value as the
name of the file containing the document which is currently processed.</p></dd>
<dt><b class="option">-ibase</b> <i class="arg">file</i></dt>
<dd><p>The argument of this option is stored in the object and used as the
base path for resolution of relative include paths. If this option is
not set (empty string) the value of <b class="option">-file</b> is used instead.</p>
<p>Note that <b class="option">-file</b> and <b class="option">-ibase</b>, while similar looking,
are actually very different. The value of <b class="option">-file</b> is used by
some engines for the generation of proper relative references between
output documents (HTML). As such this is a <i class="term">destination</i>
path. The <b class="option">-ibase</b> on the other hand is used to resolve
relative include paths, and as such deals with <i class="term"><a href="../../../../index.html#source">source</a></i> paths.</p>
<p>The default value of this option is the empty string.</p></dd>
<dt><b class="option">-module</b> <i class="arg">text</i></dt>
<dd><p>The argument of this option is stored in the object and made available
to the configured formatting engine through the command <b class="cmd">dt_module</b>.
This command is described in more detail in the companion document
<i class="term">doctools_api</i> which specifies the API between the object and
formatting engines.</p>
<p>The default value of this option is the empty string.</p>
<p>The configured formatting engine should interpret the value as the
name of the module the file containing the document which is currently
processed belongs to.</p></dd>
<dt><b class="option">-format</b> <i class="arg">text</i></dt>
<dd><p>The argument of this option specifies the format to generate and by
implication the formatting engine to use when converting text via the
method <b class="method">format</b>. Its default value is the empty string. The
method <b class="method">format</b> cannot be used if this option is not set to a
valid value at least once.</p>
<p>The package will immediately try to map the given name to a file
containing the code for a formatting engine generating that format. An
error will be thrown if this mapping fails. In that case a previously
configured format is left untouched.</p>
<p>The section <span class="sectref"><a href="#subsection5">FORMAT MAPPING</a></span> explains in detail how the
package and object will look for engine implementations.</p></dd>
<dt><b class="option">-deprecated</b> <i class="arg">boolean</i></dt>
<dd><p>This option is a boolean flag. The object will generate warnings if
this flag is set and the text given to method <b class="method">format</b> contains
the deprecated markup command <b class="cmd">strong</b>.
Its default value is <b class="const">FALSE</b>. In other words, no warnings will
be generated.</p></dd>
<dt><b class="option">-copyright</b> <i class="arg">text</i></dt>
<dd><p>The argument of this option is stored in the object and made available
to the configured formatting engine through the command <b class="cmd">dt_copyright</b>.
This command is described in more detail in the companion document
<i class="term">doctools_api</i> which specifies the API between the object and
formatting engines.</p>
<p>The default value of this option is the empty string.</p>
<p>The configured formatting engine should interpret the value as a
copyright assignment for the document which is currently processed, or
the package described by it.</p>
<p>This information must be used if and only if the engine is unable to
find any copyright assignments within the document itself. Such are
specified by the formatting command <b class="cmd">copyright</b>. This command is
described in more detail in the companion document <i class="term">doctools_fmt</i>
which specifies the <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format itself.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">FORMAT MAPPING</a></h3>
<p>The package and object will perform the following algorithm when
trying to map a format name <i class="term">foo</i> to a file containing an
implementation of a formatting engine for <i class="term">foo</i>:</p>
<ol class="doctools_enumerated">
<li><p>If <i class="term">foo</i> is the name of an existing file then this file is
directly taken as the implementation.</p></li>
<li><p>If not, the list of per-object search paths is searched. For each
directory in the list the package checks if that directory contains a
file "<b class="file">fmt.<i class="term">foo</i></b>". If yes, then that file is taken as the
implementation.</p>
<p>Note that this list of paths is initially empty and can be extended
through the object method <b class="method">search</b>.</p></li>
<li><p>If not, the list of package paths is searched.
For each directory in the list the package checks if that directory
contains a file "<b class="file">fmt.<i class="term">foo</i></b>". If yes, then that file is taken
as the implementation.</p>
<p>This list of paths can be extended
through the command <b class="cmd">::doctools::search</b>.
It contains initially one path, the subdirectory "<b class="file">mpformats</b>" of
the directory the package itself is located in.
In other words, if the package implementation "<b class="file">doctools.tcl</b>" is
installed in the directory "<b class="file">/usr/local/lib/tcllib/doctools</b>" then
it will by default search the
directory "<b class="file">/usr/local/lib/tcllib/doctools/mpformats</b>" for format
implementations.</p></li>
<li><p>The mapping fails.</p></li>
</ol>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PREDEFINED ENGINES</a></h2>
<p>The package provides predefined engines for the following
formats. Some of the engines support parameters. These will be
explained below as well.</p>
<dl class="doctools_definitions">
<dt>html</dt>
<dd><p>This engine generates HTML markup, for processing by web browsers and
the like. This engine supports four parameters:</p>
<dl class="doctools_definitions">
<dt>footer</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
before the <b class="const"></body></b> tag, closing the body of the generated
HTML.</p>
<p>This can be used to insert boilerplate footer markup into the
generated document.</p></dd>
<dt>header</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the body section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the <b class="const"><body></b> tag, starting the body of the generated HTML.</p>
<p>This can be used to insert boilerplate header markup into the
generated document.</p></dd>
<dt>meta</dt>
<dd><p>The value for this parameter has to be valid selfcontained HTML markup
for the header section of a HTML document. The default value is the
empty string. The value is inserted into the generated output just
after the <b class="const"><head></b> tag, starting the header section of the
generated HTML.</p>
<p>This can be used to insert boilerplate meta data markup into the
generated document, like references to a stylesheet, standard meta
keywords, etc.</p></dd>
<dt>xref</dt>
<dd><p>The value for this parameter has to be a list of triples specifying
cross-reference information. This information is used by the engine to
create more hyperlinks. Each triple is a list containing a pattern,
symbolic filename and fragment reference, in this order. If a pattern
is specified multiple times the last occurrence of the pattern will be
used.</p>
<p>The engine will consult the xref database when encountering specific
commands and will create a link if the relevant text matches one of
the patterns. No link will be created if no match was found. The link
will go to the uri <b class="const">file#fragment</b> listed in the relevant
triple, after conversion of the symbolic file name to the actual uri
via <b class="cmd">dt_fmap</b> (see the <i class="term"><a href="doctools_plugin_apiref.html">doctools plugin API reference</a></i>).
This file-to-uri mapping was build by calls to the method <b class="method">map</b>
of the doctools object (See section <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span>).</p>
<p>The following formatting commands will consult the xref database:</p>
<dl class="doctools_definitions">
<dt><b class="cmd">cmd</b> <i class="arg">word</i></dt>
<dd><p>The command will look for the patterns <b class="const">sa,</b><i class="arg">word</i>, and
<i class="arg">word</i>, in this order. If this fails if it will convert <i class="arg">word</i>
to all lowercase and try again.</p></dd>
<dt><b class="cmd">syscmd</b> <i class="arg">word</i></dt>
<dd><p>The command will look for the patterns <b class="const">sa,</b><i class="arg">word</i>, and
<i class="arg">word</i>, in this order. If this fails if it will convert <i class="arg">word</i>
to all lowercase and try again.</p></dd>
<dt><b class="cmd"><a href="../term/term.html">term</a></b> <i class="arg">word</i></dt>
<dd><p>The command will look for the patterns <b class="const">kw,</b><i class="arg">word</i>,
<b class="const">sa,</b><i class="arg">word</i>, and <i class="arg">word</i>, in this order. If this fails if
it will convert <i class="arg">word</i> to all lowercase and try again.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#package">package</a></b> <i class="arg">word</i></dt>
<dd><p>The command will look for the patterns <b class="const">sa,</b><i class="arg">word</i>,
<b class="const">kw,</b><i class="arg">word</i>, and <i class="arg">word</i>, in this order. If this fails if
it will convert <i class="arg">word</i> to all lowercase and try again.</p></dd>
<dt><b class="cmd">see_also</b> <i class="arg">word</i>...</dt>
<dd><p>The command will look for the patterns <b class="const">sa,</b><i class="arg">word</i>, and
<i class="arg">word</i>, in this order, for each <i class="arg">word</i> given to the
command. If this fails if it will convert <i class="arg">word</i> to all lowercase
and try again.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#keywords">keywords</a></b> <i class="arg">word</i>...</dt>
<dd><p>The command will look for the patterns <b class="const">kw,</b><i class="arg">word</i>, and
<i class="arg">word</i>, in this order, for each <i class="arg">word</i> given to the
command. If this fails if it will convert <i class="arg">word</i> to all lowercase
and try again.</p></dd>
</dl></dd>
</dl></dd>
<dt>latex</dt>
<dd><p>This engine generates output suitable for the <b class="syscmd"><a href="../../../../index.html#latex">latex</a></b> text
processor coming out of the TeX world.</p></dd>
<dt>list</dt>
<dd><p>This engine retrieves version, section and title of the manpage from
the document. As such it can be used to generate a directory listing
for a set of manpages.</p></dd>
<dt>nroff</dt>
<dd><p>This engine generates nroff output, for processing by <b class="syscmd"><a href="../../../../index.html#nroff">nroff</a></b>,
or <b class="syscmd">groff</b>. The result will be standard man pages as they are
known in the unix world.</p></dd>
<dt>null</dt>
<dd><p>This engine generates no outout at all. This can be used if one just
wants to validate some input.</p></dd>
<dt>tmml</dt>
<dd><p>This engine generates TMML markup as specified by Joe English. The Tcl
Manpage Markup Language is a derivate of XML.</p></dd>
<dt>wiki</dt>
<dd><p>This engine generates Wiki markup as understood by Jean Claude
Wippler's <b class="syscmd">wikit</b> application.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctools_intro.html">doctools_intro</a>, <a href="doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="doctools_lang_intro.html">doctools_lang_intro</a>, <a href="doctools_lang_syntax.html">doctools_lang_syntax</a>, <a href="doctools_plugin_apiref.html">doctools_plugin_apiref</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2017 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
<div class='fossil-doc' data-title='doctools_intro - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools_intro - doctools introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">RELATED FORMATS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#doctools">doctools</a></i> (short for <em>documentation tools</em>) stands for
a set of related, yet different, entities which are working together
for the easy creation and transformation of documentation. These are</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the semantic markup of text. Markup is
represented by Tcl commands interspersed with the actual text.</p></li>
<li><p>A package providing the ability to read and transform texts written in
that markup language. It is important to note that the actual
transformation of the input text is delegated to plugins.</p></li>
<li><p>An API describing the interface between the package above and a
plugin.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the documentation process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of documentation has to understand the markup language
itself. A beginner to doctools should read the more informally written
<i class="term"><a href="doctools_lang_intro.html">doctools language introduction</a></i> first. Having digested this
the formal <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i> specification should
become understandable. A writer experienced with doctools may only
need the <i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i> from time to
time to refresh her memory.</p>
<p>While a document is written the <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> application can be
used to validate it, and after completion it also performs the
conversion into the chosen system of visual markup, be it *roff, HTML,
plain text, wiki, etc.</p></li>
<li><p>A <i class="term">processor</i> of documentation written in the <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>
markup language has to know which tools are available for use.</p>
<p>The main tool is the aforementioned <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> application
provided by Tcllib. A more powerful one (in terms of options and
ability to configure it) is the <b class="syscmd">dtp</b> application, provided by
Tclapps.
At the bottom level, common to both applications, however sits the
package <b class="package"><a href="doctools.html">doctools</a></b>, providing the basic facilities to read and
process files containing text in the doctools format.</p></li>
<li><p>At last, but not least, <i class="term">plugin writers</i> have to understand the
interaction between the <b class="package"><a href="doctools.html">doctools</a></b> package and its plugins, as
described in the <i class="term"><a href="doctools_plugin_apiref.html">doctools plugin API reference</a></i>.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">RELATED FORMATS</a></h2>
<p>doctools does not stand alone, it has two companion formats. These are
called <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> and <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>, and they are for the markup of
<i class="term">keyword indices</i>, and <i class="term">tables of contents</i>,
respectively.
They are described in their own sets of documents, starting at the
<i class="term"><a href="docidx_intro.html">docidx introduction</a></i> and the <i class="term"><a href="doctoc_intro.html">doctoc introduction</a></i>,
respectively.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="doctoc_intro.html">doctoc_intro</a>, <a href="doctools.html">doctools</a>, <a href="doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="doctools_lang_faq.html">doctools_lang_faq</a>, <a href="doctools_lang_intro.html">doctools_lang_intro</a>, <a href="doctools_lang_syntax.html">doctools_lang_syntax</a>, <a href="doctools_plugin_apiref.html">doctools_plugin_apiref</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
|
<div class='fossil-doc' data-title='doctools_lang_cmdref - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools_lang_cmdref(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools_lang_cmdref - doctools language command reference</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">arg</b> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">arg_def</b> <i class="arg">type</i> <i class="arg">name</i> <span class="opt">?<i class="arg">mode</i>?</span></a></li>
<li><a href="#3"><b class="cmd">bullet</b></a></li>
<li><a href="#4"><b class="cmd">call</b> <i class="arg">args</i></a></li>
<li><a href="#5"><b class="cmd">category</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd"><a href="../../../../index.html#class">class</a></b> <i class="arg">text</i></a></li>
<li><a href="#7"><b class="cmd">cmd</b> <i class="arg">text</i></a></li>
<li><a href="#8"><b class="cmd">cmd_def</b> <i class="arg">command</i></a></li>
<li><a href="#9"><b class="cmd"><a href="../../../../index.html#comment">comment</a></b> <i class="arg">plaintext</i></a></li>
<li><a href="#10"><b class="cmd">const</b> <i class="arg">text</i></a></li>
<li><a href="#11"><b class="cmd">copyright</b> <i class="arg">text</i></a></li>
<li><a href="#12"><b class="cmd">def</b> <i class="arg">text</i></a></li>
<li><a href="#13"><b class="cmd">description</b></a></li>
<li><a href="#14"><b class="cmd">enum</b></a></li>
<li><a href="#15"><b class="cmd">emph</b> <i class="arg">text</i></a></li>
<li><a href="#16"><b class="cmd">example</b> <i class="arg">text</i></a></li>
<li><a href="#17"><b class="cmd">example_begin</b></a></li>
<li><a href="#18"><b class="cmd">example_end</b></a></li>
<li><a href="#19"><b class="cmd"><a href="../../../../index.html#file">file</a></b> <i class="arg">text</i></a></li>
<li><a href="#20"><b class="cmd">fun</b> <i class="arg">text</i></a></li>
<li><a href="#21"><b class="cmd"><a href="../../../../index.html#image">image</a></b> <i class="arg">name</i> <span class="opt">?<i class="arg">label</i>?</span></a></li>
<li><a href="#22"><b class="cmd">include</b> <i class="arg">filename</i></a></li>
<li><a href="#23"><b class="cmd">item</b></a></li>
<li><a href="#24"><b class="cmd"><a href="../../../../index.html#keywords">keywords</a></b> <i class="arg">args</i></a></li>
<li><a href="#25"><b class="cmd">lb</b></a></li>
<li><a href="#26"><b class="cmd">list_begin</b> <i class="arg">what</i></a></li>
<li><a href="#27"><b class="cmd">list_end</b></a></li>
<li><a href="#28"><b class="cmd">lst_item</b> <i class="arg">text</i></a></li>
<li><a href="#29"><b class="cmd">manpage_begin</b> <i class="arg">command</i> <i class="arg">section</i> <i class="arg">version</i></a></li>
<li><a href="#30"><b class="cmd">manpage_end</b></a></li>
<li><a href="#31"><b class="cmd"><a href="../../../../index.html#method">method</a></b> <i class="arg">text</i></a></li>
<li><a href="#32"><b class="cmd">moddesc</b> <i class="arg">text</i></a></li>
<li><a href="#33"><b class="cmd">namespace</b> <i class="arg">text</i></a></li>
<li><a href="#34"><b class="cmd">nl</b></a></li>
<li><a href="#35"><b class="cmd">opt</b> <i class="arg">text</i></a></li>
<li><a href="#36"><b class="cmd">opt_def</b> <i class="arg">name</i> <span class="opt">?<i class="arg">arg</i>?</span></a></li>
<li><a href="#37"><b class="cmd">option</b> <i class="arg">text</i></a></li>
<li><a href="#38"><b class="cmd"><a href="../../../../index.html#package">package</a></b> <i class="arg">text</i></a></li>
<li><a href="#39"><b class="cmd">para</b></a></li>
<li><a href="#40"><b class="cmd">rb</b></a></li>
<li><a href="#41"><b class="cmd">require</b> <i class="arg">package</i> <span class="opt">?<i class="arg">version</i>?</span></a></li>
<li><a href="#42"><b class="cmd">section</b> <i class="arg">name</i></a></li>
<li><a href="#43"><b class="cmd">sectref</b> <i class="arg">id</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#44"><b class="cmd">sectref-external</b> <i class="arg">text</i></a></li>
<li><a href="#45"><b class="cmd">see_also</b> <i class="arg">args</i></a></li>
<li><a href="#46"><b class="cmd">strong</b> <i class="arg">text</i></a></li>
<li><a href="#47"><b class="cmd">subsection</b> <i class="arg">name</i></a></li>
<li><a href="#48"><b class="cmd">syscmd</b> <i class="arg">text</i></a></li>
<li><a href="#49"><b class="cmd"><a href="../term/term.html">term</a></b> <i class="arg">text</i></a></li>
<li><a href="#50"><b class="cmd">titledesc</b> <i class="arg">desc</i></a></li>
<li><a href="#51"><b class="cmd">tkoption_def</b> <i class="arg">name</i> <i class="arg">dbname</i> <i class="arg">dbclass</i></a></li>
<li><a href="#52"><b class="cmd"><a href="../../../../index.html#type">type</a></b> <i class="arg">text</i></a></li>
<li><a href="#53"><b class="cmd"><a href="../uri/uri.html">uri</a></b> <i class="arg">text</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#54"><b class="cmd">usage</b> <i class="arg">args</i></a></li>
<li><a href="#55"><b class="cmd">var</b> <i class="arg">text</i></a></li>
<li><a href="#56"><b class="cmd">vset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#57"><b class="cmd">vset</b> <i class="arg">varname</i></a></li>
<li><a href="#58"><b class="cmd"><a href="../../../../index.html#widget">widget</a></b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document specifies both names and syntax of all the commands
which together are the doctools markup language, version 1.
As this document is intended to be a reference the commands are listed
in alphabetical order, and the descriptions are relatively short.
A beginner should read the much more informally written
<i class="term"><a href="doctools_lang_intro.html">doctools language introduction</a></i> first.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">arg</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as the <i class="term">argument</i> of
a command. Main uses are the highlighting of command arguments in
free-form text, and for the argument parameters of the markup commands
<b class="cmd">call</b> and <b class="cmd">usage</b>.</p></dd>
<dt><a name="2"><b class="cmd">arg_def</b> <i class="arg">type</i> <i class="arg">name</i> <span class="opt">?<i class="arg">mode</i>?</span></a></dt>
<dd><p>Text structure. List element. Argument list. Automatically closes the
previous list element. Specifies the data-<i class="arg">type</i> of the described
argument of a command, its <i class="arg">name</i> and its i/o-<i class="arg">mode</i>. The
latter is optional.</p></dd>
<dt><a name="3"><b class="cmd">bullet</b></a></dt>
<dd><p><em>Deprecated</em>. Text structure. List element. Itemized list. See
<b class="cmd">item</b> for the canonical command to open a list item in an
itemized list.</p></dd>
<dt><a name="4"><b class="cmd">call</b> <i class="arg">args</i></a></dt>
<dd><p>Text structure. List element. Definition list. Automatically closes
the previous list element. Defines the term as a command and its
arguments.
The first argument is the name of the command described by the
following free-form text, and all arguments coming after that are
descriptions of the command's arguments.
It is expected that the arguments are marked up with <b class="cmd">arg</b>,
<b class="cmd"><a href="../../../../index.html#method">method</a></b>, <b class="cmd">option</b> etc., as is appropriate, and that the
command itself is marked up with <b class="cmd">cmd</b>.
It is expected that the formatted term is not only printed in place,
but also in the table of contents of the document, or synopsis,
depending on the output format.</p></dd>
<dt><a name="5"><b class="cmd">category</b> <i class="arg">text</i></a></dt>
<dd><p>Document information. Anywhere. This command registers its plain text
arguments as the category this document belongs to. If this command is
used multiple times the last value specified is used.</p></dd>
<dt><a name="6"><b class="cmd"><a href="../../../../index.html#class">class</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as the name of a
<i class="term"><a href="../../../../index.html#class">class</a></i>. The text may have other markup already applied to
it. Main use is the highlighting of class names in free-form text.</p></dd>
<dt><a name="7"><b class="cmd">cmd</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as the name of a
<i class="term">Tcl command</i>. The text may have other markup already applied
to it. Main uses are the highlighting of commands in free-form text,
and for the command parameters of the markup commands <b class="cmd">call</b> and
<b class="cmd">usage</b>.</p></dd>
<dt><a name="8"><b class="cmd">cmd_def</b> <i class="arg">command</i></a></dt>
<dd><p>Text structure. List element. Command list. Automatically closes the
previous list element. The argument specifies the name of the
<i class="term">Tcl command</i> to be described by the list element. Expected to
be marked up in the output as if it had been formatted with <b class="cmd">cmd</b>.</p></dd>
<dt><a name="9"><b class="cmd"><a href="../../../../index.html#comment">comment</a></b> <i class="arg">plaintext</i></a></dt>
<dd><p>Text markup. The argument text is marked up as a comment standing
outside of the actual text of the document. Main use is in free-form
text.</p></dd>
<dt><a name="10"><b class="cmd">const</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as a <i class="term">constant</i> value. The
text may have other markup already applied to it. Main use is the
highlighting of constants in free-form text.</p></dd>
<dt><a name="11"><b class="cmd">copyright</b> <i class="arg">text</i></a></dt>
<dd><p>Document information. Anywhere. The command registers the plain text
argument as a copyright assignment for the manpage. When invoked more
than once the assignments are accumulated.</p></dd>
<dt><a name="12"><b class="cmd">def</b> <i class="arg">text</i></a></dt>
<dd><p>Text structure. List element. Definition list. Automatically closes
the previous list element. The argument text is the term defined by
the new list element. Text markup can be applied to it.</p></dd>
<dt><a name="13"><b class="cmd">description</b></a></dt>
<dd><p>Document structure. This command separates the header from the
document body. Implicitly starts a section named "DESCRIPTION" (See
command <b class="cmd">section</b>).</p></dd>
<dt><a name="14"><b class="cmd">enum</b></a></dt>
<dd><p>Text structure. List element. Enumerated list. Automatically closes
the previous list element.</p></dd>
<dt><a name="15"><b class="cmd">emph</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as emphasized. Main use is
for general highlighting of pieces of free-form text without attaching
special meaning to the pieces.</p></dd>
<dt><a name="16"><b class="cmd">example</b> <i class="arg">text</i></a></dt>
<dd><p>Text structure, Text markup. This command marks its argument up as an
<i class="term">example</i>. Main use is the simple embedding of examples in
free-form text. It should be used if the example does <em>not</em> need
special markup of its own. Otherwise use a sequence of
<b class="cmd">example_begin</b> ... <b class="cmd">example_end</b>.</p></dd>
<dt><a name="17"><b class="cmd">example_begin</b></a></dt>
<dd><p>Text structure. This commands starts an example. All text until the
next <b class="cmd">example_end</b> belongs to the example. Line breaks, spaces,
and tabs have to be preserved literally. Examples cannot be nested.</p></dd>
<dt><a name="18"><b class="cmd">example_end</b></a></dt>
<dd><p>Text structure. This command closes the example started by the last
<b class="cmd">example_begin</b>.</p></dd>
<dt><a name="19"><b class="cmd"><a href="../../../../index.html#file">file</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as a <i class="term"><a href="../../../../index.html#file">file</a></i> or
<i class="term">directory</i>, i.e. in general a <i class="term">path</i>. The text may have
other markup already applied to it. Main use is the highlighting of
paths in free-form text.</p></dd>
<dt><a name="20"><b class="cmd">fun</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as the name of a
<i class="term">function</i>. The text may have other markup already applied to
it. Main use is the highlighting of function names in free-form text.</p></dd>
<dt><a name="21"><b class="cmd"><a href="../../../../index.html#image">image</a></b> <i class="arg">name</i> <span class="opt">?<i class="arg">label</i>?</span></a></dt>
<dd><p>Text markup. The argument is the symbolic name of an <i class="term"><a href="../../../../index.html#image">image</a></i>
and replaced with the image itself, if a suitable variant is found
by the backend. The second argument, should it be present, will be
interpreted the human-readable description of the image, and put
into the output in a suitable position, if such is supported by the
format. The HTML format, for example, can place it into the <i class="term">alt</i>
attribute of image references.</p></dd>
<dt><a name="22"><b class="cmd">include</b> <i class="arg">filename</i></a></dt>
<dd><p>Templating. The contents of the named file are interpreted as text
written in the doctools markup and processed in the place of the
include command. The markup in the file has to be self-contained. It
is not possible for a markup command to cross the file boundaries.</p></dd>
<dt><a name="23"><b class="cmd">item</b></a></dt>
<dd><p>Text structure. List element. Itemized list. Automatically closes the
previous list element.</p></dd>
<dt><a name="24"><b class="cmd"><a href="../../../../index.html#keywords">keywords</a></b> <i class="arg">args</i></a></dt>
<dd><p>Document information. Anywhere. This command registers all its plain text
arguments as keywords applying to this document. Each argument is a single
keyword. If this command is used multiple times all the arguments accumulate.</p></dd>
<dt><a name="25"><b class="cmd">lb</b></a></dt>
<dd><p>Text. The command is replaced with a left bracket. Use in free-form text.
Required to avoid interpretation of a left bracket as the start of a markup
command.</p></dd>
<dt><a name="26"><b class="cmd">list_begin</b> <i class="arg">what</i></a></dt>
<dd><p>Text structure. This command starts a list. The exact nature of the
list is determined by the argument <i class="arg">what</i> of the command. This
further determines which commands are have to be used to start the
list elements. Lists can be nested, i.e. it is allowed to start a new
list within a list element.</p>
<p>The allowed types (and their associated item commands) are:</p>
<dl class="doctools_definitions">
<dt><b class="const">arguments</b></dt>
<dd><p><b class="cmd">arg_def</b>.</p></dd>
<dt><b class="const">commands</b></dt>
<dd><p><b class="cmd">cmd_def</b>.</p></dd>
<dt><b class="const">definitions</b></dt>
<dd><p><b class="cmd">def</b> and <b class="cmd">call</b>.</p></dd>
<dt><b class="const">enumerated</b></dt>
<dd><p><b class="cmd">enum</b></p></dd>
<dt><b class="const">itemized</b></dt>
<dd><p><b class="cmd">item</b></p></dd>
<dt><b class="const">options</b></dt>
<dd><p><b class="cmd">opt_def</b></p></dd>
<dt><b class="const">tkoptions</b></dt>
<dd><p><b class="cmd">tkoption_def</b></p></dd>
</dl>
<p>Additionally the following names are recognized as shortcuts for some
of the regular types:</p>
<dl class="doctools_definitions">
<dt><b class="const">args</b></dt>
<dd><p>Short for <b class="const">arguments</b>.</p></dd>
<dt><b class="const">cmds</b></dt>
<dd><p>Short for <b class="const">commands</b>.</p></dd>
<dt><b class="const">enum</b></dt>
<dd><p>Short for <b class="const">enumerated</b>.</p></dd>
<dt><b class="const">item</b></dt>
<dd><p>Short for <b class="const">itemized</b>.</p></dd>
<dt><b class="const">opts</b></dt>
<dd><p>Short for <b class="const">options</b>.</p></dd>
</dl>
<p>At last the following names are still recognized for backward
compatibility, but are otherwise considered to be <em>deprecated</em>.</p>
<dl class="doctools_definitions">
<dt><b class="const">arg</b></dt>
<dd><p><em>Deprecated</em>. See <b class="const">arguments</b>.</p></dd>
<dt><b class="const">bullet</b></dt>
<dd><p><em>Deprecated</em>. See <b class="const">itemized</b>.</p></dd>
<dt><b class="const">cmd</b></dt>
<dd><p><em>Deprecated</em>. See <b class="const">commands</b>.</p></dd>
<dt><b class="const">opt</b></dt>
<dd><p><em>Deprecated</em>. See <b class="const">options</b>.</p></dd>
<dt><b class="const">tkoption</b></dt>
<dd><p><em>Deprecated</em>. See <b class="const">tkoptions</b>.</p></dd>
</dl></dd>
<dt><a name="27"><b class="cmd">list_end</b></a></dt>
<dd><p>Text structure. This command closes the list opened by the last
<b class="cmd">list_begin</b> command coming before it.</p></dd>
<dt><a name="28"><b class="cmd">lst_item</b> <i class="arg">text</i></a></dt>
<dd><p><em>Deprecated</em>. Text structure. List element. Definition list. See
<b class="cmd">def</b> for the canonical command to open a general list item in a
definition list.</p></dd>
<dt><a name="29"><b class="cmd">manpage_begin</b> <i class="arg">command</i> <i class="arg">section</i> <i class="arg">version</i></a></dt>
<dd><p>Document structure. The command to start a manpage. The arguments are
the name of the <i class="arg">command</i> described by the manpage, the
<i class="arg">section</i> of the manpages this manpage resides in, and the
<i class="arg">version</i> of the module containing the command. All arguments have
to be plain text, without markup.</p></dd>
<dt><a name="30"><b class="cmd">manpage_end</b></a></dt>
<dd><p>Document structure. Command to end a manpage/document. Anything in the document
coming after this command is in error.</p></dd>
<dt><a name="31"><b class="cmd"><a href="../../../../index.html#method">method</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as the name of an
<i class="term"><a href="../../../../index.html#object">object</a></i> <i class="term"><a href="../../../../index.html#method">method</a></i>, i.e. subcommand of a Tcl command. The
text may have other markup already applied to it. Main uses are the
highlighting of method names in free-form text, and for the command
parameters of the markup commands <b class="cmd">call</b> and <b class="cmd">usage</b>.</p></dd>
<dt><a name="32"><b class="cmd">moddesc</b> <i class="arg">text</i></a></dt>
<dd><p>Document information. Header. Registers the plain text argument as a short
description of the module the manpage resides in.</p></dd>
<dt><a name="33"><b class="cmd">namespace</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as a namespace name. The
text may have other markup already applied to it. Main use is the
highlighting of namespace names in free-form text.</p></dd>
<dt><a name="34"><b class="cmd">nl</b></a></dt>
<dd><p><em>Deprecated</em>. Text structure. See <b class="cmd">para</b> for the canonical
command to insert paragraph breaks into the text.</p></dd>
<dt><a name="35"><b class="cmd">opt</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as <i class="term">optional</i>. The text may
have other markup already applied to it. Main use is the highlighting of
optional arguments, see the command arg <b class="cmd">arg</b>.</p></dd>
<dt><a name="36"><b class="cmd">opt_def</b> <i class="arg">name</i> <span class="opt">?<i class="arg">arg</i>?</span></a></dt>
<dd><p>Text structure. List element. Option list. Automatically closes the
previous list element. Specifies <i class="arg">name</i> and arguments of the
<i class="term">option</i> described by the list element. It is expected that the
name is marked up using <b class="cmd">option</b>.</p></dd>
<dt><a name="37"><b class="cmd">option</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as <i class="term">option</i>. The text may
have other markup already applied to it. Main use is the highlighting
of options, also known as command-switches, in either free-form text,
or the arguments of the <b class="cmd">call</b> and <b class="cmd">usage</b> commands.</p></dd>
<dt><a name="38"><b class="cmd"><a href="../../../../index.html#package">package</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as the name of a
<i class="term"><a href="../../../../index.html#package">package</a></i>. The text may have other markup already applied to
it. Main use is the highlighting of package names in free-form text.</p></dd>
<dt><a name="39"><b class="cmd">para</b></a></dt>
<dd><p>Text structure. This command breaks free-form text into
paragraphs. Each command closes the paragraph coming before it and
starts a new paragraph for the text coming after it. Higher-level
forms of structure are sections and subsections.</p></dd>
<dt><a name="40"><b class="cmd">rb</b></a></dt>
<dd><p>Text. The command is replaced with a right bracket. Use in free-form text.
Required to avoid interpretation of a right bracket as the end of a markup
command.</p></dd>
<dt><a name="41"><b class="cmd">require</b> <i class="arg">package</i> <span class="opt">?<i class="arg">version</i>?</span></a></dt>
<dd><p>Document information. Header. This command registers its argument
<i class="arg">package</i> as the name of a package or application required by the
described package or application. A minimum version can be provided as
well. This argument can be marked up. The usual markup is <b class="cmd">opt</b>.</p></dd>
<dt><a name="42"><b class="cmd">section</b> <i class="arg">name</i></a></dt>
<dd><p>Text structure. This command starts a new named document section. The
argument has to be plain text. Implicitly closes the last paragraph
coming before it and also implicitly opens the first paragraph of the
new section.</p></dd>
<dt><a name="43"><b class="cmd">sectref</b> <i class="arg">id</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>Text markup. Formats a reference to the section identified by <i class="arg">id</i>.
If no <i class="arg">text</i> is specified the title of the referenced section is
used in the output, otherwise <i class="arg">text</i> is used.</p></dd>
<dt><a name="44"><b class="cmd">sectref-external</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. Like <b class="cmd">sectref</b>, except that the section is assumed to
be in a different document and therefore doesn't need to be identified,
nor are any checks for existence made. Only the text to format is needed.</p></dd>
<dt><a name="45"><b class="cmd">see_also</b> <i class="arg">args</i></a></dt>
<dd><p>Document information. Anywhere. The command defines direct cross-references
to other documents. Each argument is a plain text label identifying the
referenced document. If this command is used multiple times all the arguments
accumulate.</p></dd>
<dt><a name="46"><b class="cmd">strong</b> <i class="arg">text</i></a></dt>
<dd><p><em>Deprecated</em>. Text markup. See <b class="cmd">emph</b> for the canonical
command to emphasize text.</p></dd>
<dt><a name="47"><b class="cmd">subsection</b> <i class="arg">name</i></a></dt>
<dd><p>Text structure. This command starts a new named subsection of a
section. The argument has to be plain text. Implicitly closes the last
paragraph coming before it and also implicitly opens the first
paragraph of the new subsection.</p></dd>
<dt><a name="48"><b class="cmd">syscmd</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument text is marked up as the name of an external
command. The text may have other markup already applied to it. Main
use is the highlighting of external commands in free-form text.</p></dd>
<dt><a name="49"><b class="cmd"><a href="../term/term.html">term</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as unspecific terminology. The
text may have other markup already applied to it. Main use is the
highlighting of important terms and concepts in free-form text.</p></dd>
<dt><a name="50"><b class="cmd">titledesc</b> <i class="arg">desc</i></a></dt>
<dd><p>Document information. Header. Optional. Registers the plain text
argument as the title of the manpage. Defaults to the value registered
by <b class="cmd">moddesc</b>.</p></dd>
<dt><a name="51"><b class="cmd">tkoption_def</b> <i class="arg">name</i> <i class="arg">dbname</i> <i class="arg">dbclass</i></a></dt>
<dd><p>Text structure. List element. Widget option list. Automatically closes
the previous list element. Specifies the <i class="arg">name</i> of the option as
used in scripts, the name used by the option database (<i class="arg">dbname</i>),
and its class (<i class="arg">dbclass</i>), i.e. its type. It is expected that the
name is marked up using <b class="cmd">option</b>.</p></dd>
<dt><a name="52"><b class="cmd"><a href="../../../../index.html#type">type</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as the name of a
<i class="term">data type</i>. The text may have other markup already applied to
it. Main use is the highlighting of data types in free-form text.</p></dd>
<dt><a name="53"><b class="cmd"><a href="../uri/uri.html">uri</a></b> <i class="arg">text</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>Text markup. The argument is marked up as an <i class="term"><a href="../../../../index.html#uri">uri</a></i> (i.e. a
<i class="term">uniform resource identifier</i>. The text may have other markup
already applied to it. Main use is the highlighting of uris in
free-form text. The second argument, should it be present, will be
interpreted the human-readable description of the uri. In other words,
as its label. Without an explicit label the uri will be its own label.</p></dd>
<dt><a name="54"><b class="cmd">usage</b> <i class="arg">args</i></a></dt>
<dd><p>Text markup. See <b class="cmd">call</b> for the full description, this command is
syntactically identical, as it is in its expectations for the markup
of its arguments.
In contrast to <b class="cmd">call</b> it is however not allowed to generate output
where this command occurs in the text. The command is <i class="term">silent</i>.
The formatted text may only appear in a different section of the
output, for example a table of contents, or synopsis, depending on the
output format.</p></dd>
<dt><a name="55"><b class="cmd">var</b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as the name of a
<i class="term">variable</i>. The text may have other markup already applied to
it. Main use is the highlighting of variables in free-form text.</p></dd>
<dt><a name="56"><b class="cmd">vset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Templating. In this form the command sets the named document variable
to the specified <i class="arg">value</i>. It does not generate output. I.e. the
command is replaced by the empty string.</p></dd>
<dt><a name="57"><b class="cmd">vset</b> <i class="arg">varname</i></a></dt>
<dd><p>Templating. In this form the command is replaced by the value of the
named document variable</p></dd>
<dt><a name="58"><b class="cmd"><a href="../../../../index.html#widget">widget</a></b> <i class="arg">text</i></a></dt>
<dd><p>Text markup. The argument is marked up as the name of a
<i class="term"><a href="../../../../index.html#widget">widget</a></i>. The text may have other markup already applied to
it. Main use is the highlighting of widget names in free-form text.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctools_intro.html">doctools_intro</a>, <a href="doctools_lang_faq.html">doctools_lang_faq</a>, <a href="doctools_lang_intro.html">doctools_lang_intro</a>, <a href="doctools_lang_syntax.html">doctools_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools_commands">doctools commands</a>, <a href="../../../../index.html#doctools_language">doctools language</a>, <a href="../../../../index.html#doctools_markup">doctools markup</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2010 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='doctools_lang_faq - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools_lang_faq(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools_lang_faq - doctools language faq</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">What is this document?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Where do I find doctools examples?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">What is this document?</a></h3>
<p>This document is currently mainly a placeholder, to be filled with
commonly asked questions about the doctools markup language
and companions, and their answers.</p>
<p>Please report any questions (and, if possible, answers) we should
consider for this document as explained in the section
<span class="sectref"><a href="#section4">Bugs, Ideas, Feedback</a></span> below.</p>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Where do I find doctools examples?</a></h3>
<p>We have no direct examples of documents written using doctools
markup. However the doctools processor <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does generate
a table of contents when processing a set of documents written in
doctools markup. The intermediate file for it uses doctools
markup and is not deleted when generation completes. Such files can
therefore serve as examples.</p>
<p><b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> is distributed as part of Tcllib, so to get it you
need one of</p>
<ol class="doctools_enumerated">
<li><p>A snapshot of Tcllib. How to retrieve such a snapshot and the
tools required for this are described at
<a href="/wiki?name=Development+Snapshots">Development Snapshots</a></p></li>
<li><p>A Tcllib release archive. They are available at the <a href="/home">home</a>
page.</p></li>
</ol>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="doctools_lang_intro.html">doctools_lang_intro</a>, <a href="doctools_lang_syntax.html">doctools_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools_commands">doctools commands</a>, <a href="../../../../index.html#doctools_language">doctools language</a>, <a href="../../../../index.html#doctools_markup">doctools markup</a>, <a href="../../../../index.html#doctools_syntax">doctools syntax</a>, <a href="../../../../index.html#examples">examples</a>, <a href="../../../../index.html#faq">faq</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
|
<div class='fossil-doc' data-title='doctools_lang_intro - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools_lang_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools_lang_intro - doctools language introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Fundamentals</a></li>
<li class="doctools_subsection"><a href="#subsection2">Basic structure</a></li>
<li class="doctools_subsection"><a href="#subsection3">Advanced structure</a></li>
<li class="doctools_subsection"><a href="#subsection4">Text structure</a></li>
<li class="doctools_subsection"><a href="#subsection5">Text markup</a></li>
<li class="doctools_subsection"><a href="#subsection6">Escapes</a></li>
<li class="doctools_subsection"><a href="#subsection7">Cross-references</a></li>
<li class="doctools_subsection"><a href="#subsection8">Examples</a></li>
<li class="doctools_subsection"><a href="#subsection9">Lists</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">FURTHER READING</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is an informal introduction to version 1 of the doctools
markup language based on a multitude of examples. After reading this a
writer should be ready to understand the two parts of the formal
specification, i.e. the <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i> specification
and the <i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Fundamentals</a></h3>
<p>In the broadest terms possible the <i class="term">doctools markup language</i>
is LaTeX-like, instead of like SGML and similar languages. A document
written in this language consists primarily of text, with markup
commands embedded into it.</p>
<p>Each markup command is a Tcl command surrounded by a matching pair of
<b class="const">[</b> and <b class="const">]</b>. Inside of these delimiters the usual
rules for a Tcl command apply with regard to word quotation, nested
commands, continuation lines, etc. I.e.</p>
<pre class="doctools_example">
... [list_begin enumerated] ...
</pre>
<pre class="doctools_example">
... [call [cmd foo] \\
[arg bar]] ...
</pre>
<pre class="doctools_example">
... [term {complex concept}] ...
</pre>
<pre class="doctools_example">
... [opt "[arg key] [arg value]"] ...
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Basic structure</a></h3>
<p>The most simple document which can be written in doctools is</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[see_also doctools_intro]
[see_also doctools_lang_cmdref]
[see_also doctools_lang_faq]
[see_also doctools_lang_syntax]
[keywords {doctools commands}]
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
[description]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
</pre>
<p>This also shows us that all doctools documents are split into two
parts, the <i class="term">header</i> and the <i class="term">body</i>. Everything coming before
[<b class="cmd">description</b>] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
two <b class="cmd">manpage_*</b> commands. Before and after these opening and
closing commands we have only <i class="term">whitespace</i>.</p>
<p>In the remainder of this section we will discuss only the contents of
the header, the structure of the body will be discussed in the section
<span class="sectref"><a href="#subsection4">Text structure</a></span>.</p>
<p>The header section can be empty, and otherwise may contain only an
arbitrary sequence of the four so-called <i class="term">header</i> commands, plus
<i class="term">whitespace</i>. These commands are</p>
<dl class="doctools_commands">
<dt><b class="cmd">titledesc</b></dt>
<dd></dd>
<dt><b class="cmd">moddesc</b></dt>
<dd></dd>
<dt><b class="cmd">require</b></dt>
<dd></dd>
<dt><b class="cmd">copyright</b></dt>
<dd></dd>
</dl>
<p>They provide, through their arguments, additional information about
the document, like its title, the title of the larger group the
document belongs to (if applicable), the requirements of the
documented packages (if applicable), and copyright assignments. All of
them can occur multiple times, including none, and they can be used in
any order.
However for <b class="cmd">titledesc</b> and <b class="cmd">moddesc</b> only the last occurrence
is taken. For the other two the specified information is accumulated,
in the given order. Regular text is not allowed within the header.</p>
<p>Given the above a less minimal example of a document is</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[<b class="cmd">copyright {YEAR AUTHOR}</b>]
[<b class="cmd">titledesc TITLE</b>]
[<b class="cmd">moddesc MODULE_TITLE</b>]
[<b class="cmd">require PACKAGE VERSION</b>]
[<b class="cmd">require PACKAGE</b>]
[description]
[manpage_end]
</pre>
<p>Remember that the whitespace is optional. The document</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
[require PACKAGE VERSION][require PACKAGE][description]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
</pre>
<p>has the same meaning as the example before.</p>
<p>On the other hand, if <i class="term">whitespace</i> is present it consists not
only of any sequence of characters containing the space character,
horizontal and vertical tabs, carriage return, and newline, but it may
contain comment markup as well, in the form of the <b class="cmd"><a href="../../../../index.html#comment">comment</a></b>
command.</p>
<pre class="doctools_example">
[<b class="cmd">comment { ... }</b>]
[manpage_begin NAME SECTION VERSION]
[copyright {YEAR AUTHOR}]
[titledesc TITLE]
[moddesc MODULE_TITLE][<b class="cmd">comment { ... }</b>]
[require PACKAGE VERSION]
[require PACKAGE]
[description]
[manpage_end]
[<b class="cmd">comment { ... }</b>]
</pre>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Advanced structure</a></h3>
<p>In the simple examples of the last section we fudged a bit regarding
the markup actually allowed to be used before the <b class="cmd">manpage_begin</b>
command opening the document.</p>
<p>Instead of only whitespace the two templating commands <b class="cmd">include</b>
and <b class="cmd">vset</b> are also allowed, to enable the writer to either set
and/or import configuration settings relevant to the document. I.e. it
is possible to write</p>
<pre class="doctools_example">
[<b class="cmd">include FILE</b>]
[<b class="cmd">vset VAR VALUE</b>]
[manpage_begin NAME SECTION VERSION]
[description]
[manpage_end]
</pre>
<p>Even more important, these two commands are allowed anywhere where a
markup command is allowed, without regard for any other
structure. I.e. for example in the header as well.</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[<b class="cmd">include FILE</b>]
[<b class="cmd">vset VAR VALUE</b>]
[description]
[manpage_end]
</pre>
<p>The only restriction <b class="cmd">include</b> has to obey is that the contents of
the included file must be valid at the place of the inclusion. I.e. a
file included before <b class="cmd">manpage_begin</b> may contain only the
templating commands <b class="cmd">vset</b> and <b class="cmd">include</b>, a file included in
the header may contain only header commands, etc.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Text structure</a></h3>
<p>The body of the document consists mainly of text, possibly split into
sections, subsections, and paragraphs, with parts marked up to
highlight various semantic categories of text, and additional
structure through the use of examples and (nested) lists.</p>
<p>This section explains the high-level structural commands, with
everything else deferred to the following sections.</p>
<p>The simplest way of structuring the body is through the introduction
of paragraphs. The command for doing so is <b class="cmd">para</b>. Each occurrence
of this command closes the previous paragraph and automatically opens
the next. The first paragraph is automatically opened at the beginning
of the body, by <b class="cmd">description</b>. In the same manner the last
paragraph automatically ends at <b class="cmd">manpage_end</b>.</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[description]
...
[<b class="cmd">para</b>]
...
[<b class="cmd">para</b>]
...
[manpage_end]
</pre>
<p>Empty paragraphs are ignored.</p>
<p>A structure coarser than paragraphs are sections, which allow the
writer to split a document into larger, and labeled, pieces. The
command for doing so is <b class="cmd">section</b>. Each occurrence of this command
closes the previous section and automatically opens the next,
including its first paragraph. The first section is automatically
opened at the beginning of the body, by <b class="cmd">description</b> (This
section is labeled "DESCRIPTION"). In the same manner the last section
automatically ends at <b class="cmd">manpage_end</b>.</p>
<p>Empty sections are <em>not</em> ignored. We are free to (not) use
paragraphs within sections.</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[description]
...
[<b class="cmd">section {Section A}</b>]
...
[para]
...
[<b class="cmd">section {Section B}</b>]
...
[manpage_end]
</pre>
<p>Between sections and paragraphs we have subsections, to split sections.
The command for doing so is <b class="cmd">subsection</b>. Each occurrence of this
command closes the previous subsection and automatically opens the
next, including its first paragraph. A subsection is automatically
opened at the beginning of the body, by <b class="cmd">description</b>, and at the
beginning of each section. In the same manner the last subsection
automatically ends at <b class="cmd">manpage_end</b>.</p>
<p>Empty subsections are <em>not</em> ignored. We are free to (not) use
paragraphs within subsections.</p>
<pre class="doctools_example">
[manpage_begin NAME SECTION VERSION]
[description]
...
[section {Section A}]
...
[<b class="cmd">subsection {Sub 1}</b>]
...
[para]
...
[<b class="cmd">subsection {Sub 2}</b>]
...
[section {Section B}]
...
[manpage_end]
</pre>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Text markup</a></h3>
<p>Having handled the overall structure a writer can impose on the
document we now take a closer at the text in a paragraph.</p>
<p>While most often this is just the unadorned content of the document we
do have situations where we wish to highlight parts of it as some type
of thing or other, like command arguments, command names, concepts,
uris, etc.</p>
<p>For this we have a series of markup commands which take the text to
highlight as their single argument. It should be noted that while
their predominant use is the highlighting of parts of a paragraph they
can also be used to mark up the arguments of list item commands, and
of other markup commands.</p>
<p>The commands available to us are</p>
<dl class="doctools_commands">
<dt><b class="cmd">arg</b></dt>
<dd><p>Its argument is a the name of a command argument.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#class">class</a></b></dt>
<dd><p>Its argument is a class name.</p></dd>
<dt><b class="cmd">cmd</b></dt>
<dd><p>Its argument is a command name (Tcl command).</p></dd>
<dt><b class="cmd">const</b></dt>
<dd><p>Its argument is a constant.</p></dd>
<dt><b class="cmd">emph</b></dt>
<dd><p>General, non-semantic emphasis.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#file">file</a></b></dt>
<dd><p>Its argument is a filename / path.</p></dd>
<dt><b class="cmd">fun</b></dt>
<dd><p>Its argument is a function name.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#method">method</a></b></dt>
<dd><p>Its argument is a method name</p></dd>
<dt><b class="cmd">namespace</b></dt>
<dd><p>Its argument is namespace name.</p></dd>
<dt><b class="cmd">opt</b></dt>
<dd><p>Its argument is some optional syntax element.</p></dd>
<dt><b class="cmd">option</b></dt>
<dd><p>Its argument is a command line switch / widget option.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#package">package</a></b></dt>
<dd><p>Its argument is a package name.</p></dd>
<dt><b class="cmd">sectref</b></dt>
<dd><p>Its argument is the title of a section or subsection,
i.e. a section reference.</p></dd>
<dt><b class="cmd">syscmd</b></dt>
<dd><p>Its argument is a command name (external, system command).</p></dd>
<dt><b class="cmd"><a href="../term/term.html">term</a></b></dt>
<dd><p>Its argument is a concept, or general terminology.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#type">type</a></b></dt>
<dd><p>Its argument is a type name.</p></dd>
<dt><b class="cmd"><a href="../uri/uri.html">uri</a></b></dt>
<dd><p>Its argument is a uniform resource identifier, i.e an
external reference. A second argument can be used
to specify an explicit label for the reference in
question.</p></dd>
<dt><b class="cmd">usage</b></dt>
<dd><p>The arguments describe the syntax of a Tcl command.</p></dd>
<dt><b class="cmd">var</b></dt>
<dd><p>Its argument is a variable.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#widget">widget</a></b></dt>
<dd><p>Its argument is a widget name.</p></dd>
</dl>
<p>The example demonstrating the use of text markup is an excerpt from
the <i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i>, with some
highlighting added.
It shows their use within a block of text, as the arguments of a list
item command (<b class="cmd">call</b>), and our ability to nest them.</p>
<pre class="doctools_example">
...
[call [<b class="cmd">cmd arg_def</b>] [<b class="cmd">arg type</b>] [<b class="cmd">arg name</b>] [<b class="cmd">opt</b> [<b class="cmd">arg mode</b>]]]
Text structure. List element. Argument list. Automatically closes the
previous list element. Specifies the data-[<b class="cmd">arg type</b>] of the described
argument of a command, its [<b class="cmd">arg name</b>] and its i/o-[<b class="cmd">arg mode</b>]. The
latter is optional.
...
</pre>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Escapes</a></h3>
<p>Beyond the 20 commands for simple markup shown in the previous section
we have two more available which are technically simple markup.
However their function is not the marking up of phrases as specific
types of things, but the insertion of characters, namely <b class="const">[</b>
and <b class="const">]</b>.
These commands, <b class="cmd">lb</b> and <b class="cmd">rb</b> respectively, are required
because our use of [ and ] to bracket markup commands makes it
impossible to directly use [ and ] within the text.</p>
<p>Our example of their use are the sources of the last sentence in the
previous paragraph, with some highlighting added.</p>
<pre class="doctools_example">
...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [<b class="cmd">lb</b>] and [<b class="cmd">rb</b>] to bracket markup commands makes it
impossible to directly use [<b class="cmd">lb</b>] and [<b class="cmd">rb</b>] within the text.
...
</pre>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Cross-references</a></h3>
<p>The last two commands we have to discuss are for the declaration of
cross-references between documents, explicit and implicit. They are
<b class="cmd"><a href="../../../../index.html#keywords">keywords</a></b> and <b class="cmd">see_also</b>. Both take an arbitrary number of
arguments, all of which have to be plain unmarked text. I.e. it is not
allowed to use markup on them. Both commands can be used multiple
times in a document. If that is done all arguments of all occurrences
of one of them are put together into a single set.</p>
<dl class="doctools_definitions">
<dt><b class="cmd"><a href="../../../../index.html#keywords">keywords</a></b></dt>
<dd><p>The arguments of this command are interpreted as keywords describing
the document. A processor can use this information to create an index
indirectly linking the containing document to all documents with the
same keywords.</p></dd>
<dt><b class="cmd">see_also</b></dt>
<dd><p>The arguments of this command are interpreted as references to other
documents. A processor can format them as direct links to these
documents.</p></dd>
</dl>
<p>All the cross-reference commands can occur anywhere in the document
between <b class="cmd">manpage_begin</b> and <b class="cmd">manpage_end</b>. As such the writer
can choose whether she wants to have them at the beginning of the
body, or at its end, maybe near the place a keyword is actually
defined by the main content, or considers them as meta data which
should be in the header, etc.</p>
<p>Our example shows the sources for the cross-references of this
document, with some highlighting added. Incidentally they are found
at the end of the body.</p>
<pre class="doctools_example">
...
[<b class="cmd">see_also doctools_intro</b>]
[<b class="cmd">see_also doctools_lang_syntax</b>]
[<b class="cmd">see_also doctools_lang_cmdref</b>]
[<b class="cmd">keywords markup {semantic markup}</b>]
[<b class="cmd">keywords {doctools markup} {doctools language}</b>]
[<b class="cmd">keywords {doctools syntax} {doctools commands}</b>]
[manpage_end]
</pre>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Examples</a></h3>
<p>Where ever we can write plain text we can write examples too. For
simple examples we have the command <b class="cmd">example</b> which takes a single
argument, the text of the argument. The example text must not contain
markup. If we wish to have markup within an example we have to use the
2-command combination <b class="cmd">example_begin</b> / <b class="cmd">example_end</b> instead.</p>
<p>The first opens an example block, the other closes it, and in between
we can write plain text and use all the regular text markup commands.
Note that text structure commands are not allowed. This also means
that it is not possible to embed examples and lists within an example.
On the other hand, we <em>can</em> use templating commands within
example blocks to read their contents from a file (Remember section
<span class="sectref"><a href="#subsection3">Advanced structure</a></span>).</p>
<p>The source for the very first example in this document (see section
<span class="sectref"><a href="#subsection1">Fundamentals</a></span>), with some highlighting added, is</p>
<pre class="doctools_example">
[<b class="cmd">example</b> {
... [list_begin enumerated] ...
}]
</pre>
<p>Using <b class="cmd">example_begin</b> / <b class="cmd">example_end</b> this would look like</p>
<pre class="doctools_example">
[<b class="cmd">example_begin</b>]
... [list_begin enumerated] ...
[<b class="cmd">example_end</b>]
</pre>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Lists</a></h3>
<p>Where ever we can write plain text we can write lists too. The main
commands are <b class="cmd">list_begin</b> to start a list, and <b class="cmd">list_end</b> to
close one. The opening command takes an argument specifying the type
of list started it, and this in turn determines which of the eight
existing list item commands are allowed within the list to start list
items.</p>
<p>After the opening command only whitespace is allowed, until the first
list item command opens the first item of the list. Each item is a
regular series of paragraphs and is closed by either the next list
item command, or the end of the list. If closed by a list item command
this command automatically opens the next list item. A consequence of
a list item being a series of paragraphs is that all regular text
markup can be used within a list item, including examples and other
lists.</p>
<p>The list types recognized by <b class="cmd">list_begin</b> and their associated
list item commands are:</p>
<dl class="doctools_definitions">
<dt><b class="const">arguments</b></dt>
<dd><p>(<b class="cmd">arg_def</b>) This opens an <i class="term">argument (declaration) list</i>. It
is a specialized form of a term definition list where the term is an
argument name, with its type and i/o-mode.</p></dd>
<dt><b class="const">commands</b></dt>
<dd><p>(<b class="cmd">cmd_def</b>) This opens a <i class="term">command (declaration) list</i>. It
is a specialized form of a term definition list where the term is a
command name.</p></dd>
<dt><b class="const">definitions</b></dt>
<dd><p>(<b class="cmd">def</b> and <b class="cmd">call</b>) This opens a general
<i class="term">term definition list</i>. The terms defined by the list items are
specified through the argument(s) of the list item commands, either
general terms, possibly with markup (<b class="cmd">def</b>), or Tcl commands with
their syntax (<b class="cmd">call</b>).</p></dd>
<dt><b class="const">enumerated</b></dt>
<dd><p>(<b class="cmd">enum</b>) This opens a general <i class="term">enumerated list</i>.</p></dd>
<dt><b class="const">itemized</b></dt>
<dd><p>(<b class="cmd">item</b>)
This opens a general <i class="term">itemized list</i>.</p></dd>
<dt><b class="const">options</b></dt>
<dd><p>(<b class="cmd">opt_def</b>) This opens an <i class="term">option (declaration) list</i>. It
is a specialized form of a term definition list where the term is an
option name, possibly with the option's arguments.</p></dd>
<dt><b class="const">tkoptions</b></dt>
<dd><p>(<b class="cmd">tkoption_def</b>) This opens a
<i class="term">widget option (declaration) list</i>. It is a specialized form of
a term definition list where the term is the name of a configuration
option for a widget, with its name and class in the option database.</p></dd>
</dl>
<p>Our example is the source of the definition list in the previous
paragraph, with most of the content in the middle removed.</p>
<pre class="doctools_example">
...
[<b class="cmd">list_begin</b> definitions]
[<b class="cmd">def</b> [const arg]]
([cmd arg_def]) This opens an argument (declaration) list. It is a
specialized form of a definition list where the term is an argument
name, with its type and i/o-mode.
[<b class="cmd">def</b> [const itemized]]
([cmd item])
This opens a general itemized list.
...
[<b class="cmd">def</b> [const tkoption]]
([cmd tkoption_def]) This opens a widget option (declaration) list. It
is a specialized form of a definition list where the term is the name
of a configuration option for a widget, with its name and class in the
option database.
[<b class="cmd">list_end</b>]
...
</pre>
<p>Note that a list cannot begin in one (sub)section and end in
another. Differently said, (sub)section breaks are not allowed within
lists and list items. An example of this <em>illegal</em> construct is</p>
<pre class="doctools_example">
...
[list_begin itemized]
[item]
...
[<b class="cmd">section {ILLEGAL WITHIN THE LIST}</b>]
...
[list_end]
...
</pre>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">FURTHER READING</a></h2>
<p>Now that this document has been digested the reader, assumed to be a
<i class="term">writer</i> of documentation should be fortified enough to be able
to understand the formal <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i>
specification as well. From here on out the
<i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i> will also serve as the
detailed specification and cheat sheet for all available commands and
their syntax.</p>
<p>To be able to validate a document while writing it, it is also
recommended to familiarize oneself with one of the applications for
the processing and conversion of doctools documents, i.e. either
Tcllib's easy and simple <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b>, or Tclapps'
ultra-configurable <b class="syscmd">dtp</b>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctools_intro.html">doctools_intro</a>, <a href="doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="doctools_lang_faq.html">doctools_lang_faq</a>, <a href="doctools_lang_syntax.html">doctools_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools_commands">doctools commands</a>, <a href="../../../../index.html#doctools_language">doctools language</a>, <a href="../../../../index.html#doctools_markup">doctools markup</a>, <a href="../../../../index.html#doctools_syntax">doctools syntax</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
<div class='fossil-doc' data-title='doctools_lang_syntax - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools_lang_syntax(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools_lang_syntax - doctools language syntax</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Fundamentals</a></li>
<li class="doctools_section"><a href="#section3">Lexical definitions</a></li>
<li class="doctools_section"><a href="#section4">Syntax</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document contains the formal specification of the syntax of the
doctools markup language, version 1 in Backus-Naur-Form. This document
is intended to be a reference, complementing the
<i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i>.
A beginner should read the much more informally written
<i class="term"><a href="doctools_lang_intro.html">doctools language introduction</a></i> first before trying to
understand either this document or the command reference.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Fundamentals</a></h2>
<p>In the broadest terms possible the <i class="term">doctools markup language</i>
is LaTeX-like, instead of like SGML and similar languages. A document
written in this language consists primarily of text, with markup
commands embedded into it.</p>
<p>Each markup command is a just Tcl command surrounded by a matching
pair of <b class="const">[</b> and <b class="const">]</b>. Which commands are available,
and their arguments, i.e. syntax is specified in the
<i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i>.</p>
<p>In this document we specify first the lexeme, and then the syntax,
i.e. how we can mix text and markup commands with each other.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Lexical definitions</a></h2>
<p>In the syntax rules listed in the next section</p>
<ol class="doctools_enumerated">
<li><p><TEXT> stands for all text except markup commands.</p></li>
<li><p>Any XXX stands for the markup command [xxx] including its
arguments. Each markup command is a Tcl command surrounded by a
matching pair of <b class="const">[</b> and <b class="const">]</b>. Inside of these
delimiters the usual rules for a Tcl command apply with regard to word
quotation, nested commands, continuation lines, etc.</p></li>
<li><p><WHITE> stands for all text consisting only of spaces, newlines,
tabulators and the <b class="cmd"><a href="../../../../index.html#comment">comment</a></b> markup command.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Syntax</a></h2>
<p>The rules listed here specify only the syntax of doctools
documents. The lexical level of the language was covered in the
previous section.</p>
<p>Regarding the syntax of the (E)BNF itself</p>
<ol class="doctools_enumerated">
<li><p>The construct { X } stands for zero or more occurrences of X.</p></li>
<li><p>The construct [ X ] stands for zero or one occurrence of X.</p></li>
<li><p>The construct LIST_BEGIN<X> stands for the markup command
<b class="cmd">list_begin</b> with <b class="const">X</b> as its type argument.</p></li>
</ol>
<p>The syntax:</p>
<pre class="doctools_example">
manpage = defs
MANPAGE_BEGIN
header
DESCRIPTION
body
MANPAGE_END
{ <WHITE> }
defs = { INCLUDE | VSET | <WHITE> }
header = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
xref = KEYWORDS | SEE_ALSO | CATEGORY
body = paras { SECTION sbody }
sbody = paras { SUBSECTION ssbody }
ssbody = paras
paras = tblock { (PARA | NL) tblock }
tblock = { <TEXT> | defs | markup | xref | an_example | a_list }
markup = ARG | CLASS | CMD | CONST | EMPH | FILE
| FUN | LB | METHOD | NAMESPACE | OPT | OPTION
| PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM
| TYPE | URI | USAGE | VAR | WIDGET
example = EXAMPLE
| EXAMPLE_BEGIN extext EXAMPLE_END
extext = { <TEXT> | defs | markup }
a_list = LIST_BEGIN<arguments> argd_list LIST_END
| LIST_BEGIN<commands> cmdd_list LIST_END
| LIST_BEGIN<definitions> def_list LIST_END
| LIST_BEGIN<enumerated> enum_list LIST_END
| LIST_BEGIN<itemized> item_list LIST_END
| LIST_BEGIN<options> optd_list LIST_END
| LIST_BEGIN<tkoptions> tkoptd_list LIST_END
argd_list = [ <WHITE> ] { ARG_DEF paras }
cmdd_list = [ <WHITE> ] { CMD_DEF paras }
def_list = [ <WHITE> ] { (DEF|CALL) paras }
enum_list = [ <WHITE> ] { ENUM paras }
item_list = [ <WHITE> ] { ITEM paras }
optd_list = [ <WHITE> ] { OPT_DEF paras }
tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctools_intro.html">doctools_intro</a>, <a href="doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="doctools_lang_faq.html">doctools_lang_faq</a>, <a href="doctools_lang_intro.html">doctools_lang_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools_commands">doctools commands</a>, <a href="../../../../index.html#doctools_language">doctools language</a>, <a href="../../../../index.html#doctools_markup">doctools markup</a>, <a href="../../../../index.html#doctools_syntax">doctools syntax</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
|
<div class='fossil-doc' data-title='doctools_plugin_apiref - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools_plugin_apiref(n) 1.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools_plugin_apiref - doctools plugin API reference</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a></li>
<li class="doctools_section"><a href="#section3">FRONTEND COMMANDS</a></li>
<li class="doctools_section"><a href="#section4">PLUGIN COMMANDS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Management commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Formatting commands</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">dt_copyright</b></a></li>
<li><a href="#2"><b class="cmd">dt_file</b></a></li>
<li><a href="#3"><b class="cmd">dt_mainfile</b></a></li>
<li><a href="#4"><b class="cmd">dt_fileid</b></a></li>
<li><a href="#5"><b class="cmd">dt_fmap</b> <i class="arg">symfname</i></a></li>
<li><a href="#6"><b class="cmd">dt_format</b></a></li>
<li><a href="#7"><b class="cmd">dt_imgdata</b> <i class="arg">key</i> <i class="arg">extensions</i></a></li>
<li><a href="#8"><b class="cmd">dt_imgdst</b> <i class="arg">key</i> <i class="arg">extensions</i></a></li>
<li><a href="#9"><b class="cmd">dt_imgsrc</b> <i class="arg">key</i> <i class="arg">extensions</i></a></li>
<li><a href="#10"><b class="cmd">dt_lnesting</b></a></li>
<li><a href="#11"><b class="cmd">dt_module</b></a></li>
<li><a href="#12"><b class="cmd">dt_read</b> <i class="arg">file</i></a></li>
<li><a href="#13"><b class="cmd">dt_source</b> <i class="arg">file</i></a></li>
<li><a href="#14"><b class="cmd">dt_user</b></a></li>
<li><a href="#15"><b class="cmd">ex_cappend</b> <i class="arg">text</i></a></li>
<li><a href="#16"><b class="cmd">ex_cget</b> <i class="arg">varname</i></a></li>
<li><a href="#17"><b class="cmd">ex_cis</b> <i class="arg">cname</i></a></li>
<li><a href="#18"><b class="cmd">ex_cname</b></a></li>
<li><a href="#19"><b class="cmd">ex_cpop</b> <i class="arg">cname</i></a></li>
<li><a href="#20"><b class="cmd">ex_cpush</b> <i class="arg">cname</i></a></li>
<li><a href="#21"><b class="cmd">ex_cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#22"><b class="cmd">ex_lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#23"><b class="cmd">ex_rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#24"><b class="cmd">fmt_initialize</b></a></li>
<li><a href="#25"><b class="cmd">fmt_listvariables</b></a></li>
<li><a href="#26"><b class="cmd">fmt_numpasses</b></a></li>
<li><a href="#27"><b class="cmd">fmt_postprocess</b> <i class="arg">text</i></a></li>
<li><a href="#28"><b class="cmd">fmt_setup</b> <i class="arg">n</i></a></li>
<li><a href="#29"><b class="cmd">fmt_shutdown</b></a></li>
<li><a href="#30"><b class="cmd">fmt_varset</b> <i class="arg">varname</i> <i class="arg">text</i></a></li>
<li><a href="#31"><b class="cmd">fmt_plain_text</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is intended for <i class="term">plugin writers</i>, i.e. developers
wishing to write a doctools <i class="term"><a href="../../../../index.html#formatting_engine">formatting engine</a></i> for some output
format X.</p>
<p>It specifies the interaction between the <b class="package"><a href="doctools.html">doctools</a></b> package
and its plugins, i.e. the interface any doctools formatting engine has
to comply with.</p>
<p>This document deals with version 1 of the interface.</p>
<p>A reader who is on the other hand more interested in the markup
language itself should start with the
<i class="term"><a href="doctools_lang_intro.html">doctools language introduction</a></i> and proceed from there to the
formal specifications, i.e. the <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i> and
the <i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<p>The API for a doctools formatting engine consists of two major
sections.</p>
<p>On the one side we have a set of commands through which the plugin is
able to query the frontend. These commands are provided by the
frontend and linked into the plugin interpreter. Please see section
<span class="sectref"><a href="#section3">FRONTEND COMMANDS</a></span> for their detailed specification.</p>
<p>And on the other side the plugin has to provide its own set of
commands which will then be called by the frontend in a specific
sequence while processing input. They, again, fall into two
categories, management and formatting.
Please see section <span class="sectref"><a href="#section4">PLUGIN COMMANDS</a></span> and its subsections for
their detailed specification.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FRONTEND COMMANDS</a></h2>
<p>This section specifies the set of commands through which a plugin,
also known as a doctools formatting engine, is able to query the
frontend. These commands are provided by the frontend and linked into
the plugin interpreter.</p>
<p>I.e. a doctools formatting engine can assume that all of the following
commands are present when any of its own commands (as specified in
section <span class="sectref"><a href="#section4">PLUGIN COMMANDS</a></span>) are executed.</p>
<p>Beyond that it can also assume that it has full access to its own safe
interpreter and thus is not able to damage the other parts of the
processor, nor can it damage the filesystem.
It is however able to either kill or hang the whole process, by
exiting, or running an infinite loop.</p>
<p>Coming back to the imported commands, all the commands with prefix
<em>dt_</em> provide limited access to specific parts of the frontend,
whereas the commands with prefix <em>ex_</em> provide access to the
state of the <b class="package"><a href="../textutil/expander.html">textutil::expander</a></b> object which does the main
parsing of the input within the frontend. These commands should not be
except under very special circumstances.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">dt_copyright</b></a></dt>
<dd><p>Query command. It returns a string containing the copyright
information the doctools processor was configured with. The relevant
option is <b class="option">-copyright</b>).</p></dd>
<dt><a name="2"><b class="cmd">dt_file</b></a></dt>
<dd><p>Query command. It returns the full path of the file containing the
input currently processed by the engine. This may be an included file.</p></dd>
<dt><a name="3"><b class="cmd">dt_mainfile</b></a></dt>
<dd><p>Query command. It returns the full path of the toplevel file containing
the input currently processed by the engine.</p></dd>
<dt><a name="4"><b class="cmd">dt_fileid</b></a></dt>
<dd><p>Query command. It returns the name of the file containing the input
currently processed by the engine, without path, nor extension.</p></dd>
<dt><a name="5"><b class="cmd">dt_fmap</b> <i class="arg">symfname</i></a></dt>
<dd><p>Query command. It returns the actual pathname to use in the output in
place of the symbolic filename <i class="arg">symfname</i>. It will return the
unchanged input if no mapping was established for <i class="arg">symfname</i>.</p>
<p>The required mappings are established with the method <b class="method">map</b> of
a frontend, as explained in section <b class="sectref">OBJECT METHODS</b>
of the documentation for the package <b class="package"><a href="doctools.html">doctools</a></b>.</p></dd>
<dt><a name="6"><b class="cmd">dt_format</b></a></dt>
<dd><p>Query command. It returns the name of the format associated with the
doctools formatting engine.</p></dd>
<dt><a name="7"><b class="cmd">dt_imgdata</b> <i class="arg">key</i> <i class="arg">extensions</i></a></dt>
<dd><p>Query command. Access to the image map. Looks for an image recorded
under the <i class="arg">key</i> and having on the specified <i class="arg">extension</i>. If a
matching image is found its data is returned as the result of the
command. Otherwise an empty string is returned.</p></dd>
<dt><a name="8"><b class="cmd">dt_imgdst</b> <i class="arg">key</i> <i class="arg">extensions</i></a></dt>
<dd><p>Query command. Access to the image map. Looks for an image recorded
under the <i class="arg">key</i> and having on the specified <i class="arg">extension</i>. If a
matching image is found its destination path in the output is returned
as the result of the command. Otherwise an empty string is returned.</p></dd>
<dt><a name="9"><b class="cmd">dt_imgsrc</b> <i class="arg">key</i> <i class="arg">extensions</i></a></dt>
<dd><p>Query command. Access to the image map. Looks for an image recorded
under the <i class="arg">key</i> and having on the specified <i class="arg">extension</i>. If a
matching image is found its origin path is returned as the result of
the command. Otherwise an empty string is returned.</p></dd>
<dt><a name="10"><b class="cmd">dt_lnesting</b></a></dt>
<dd><p>Query command. It returns the number of lists currently open.</p></dd>
<dt><a name="11"><b class="cmd">dt_module</b></a></dt>
<dd><p>Query command. It returns the name of the module the input currently
processed belongs to.</p></dd>
<dt><a name="12"><b class="cmd">dt_read</b> <i class="arg">file</i></a></dt>
<dd><p>Controlled filesystem access. Returns contents of <i class="arg">file</i> for
whatever use desired by the plugin.
Only files which are either in the same directory as the file
containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.</p></dd>
<dt><a name="13"><b class="cmd">dt_source</b> <i class="arg">file</i></a></dt>
<dd><p>Controlled filesystem access. This command allows the doctools
formatting engine to load additional Tcl code it may need.
Only files which are either in the same directory as the file
containing the engine, or below it, can be loaded. Trying to load a
file outside of this directory causes an error.</p></dd>
<dt><a name="14"><b class="cmd">dt_user</b></a></dt>
<dd><p>Query command. It returns the name of the current user as known to the
tcl interpreter the frontend controlling the formatting engine resides
in.</p></dd>
<dt><a name="15"><b class="cmd">ex_cappend</b> <i class="arg">text</i></a></dt>
<dd><p>Appends a string to the output in the current context. This command
should rarely be used by macros or application code.</p></dd>
<dt><a name="16"><b class="cmd">ex_cget</b> <i class="arg">varname</i></a></dt>
<dd><p>Retrieves the value of variable <i class="arg">varname</i>, defined in the current
context.</p></dd>
<dt><a name="17"><b class="cmd">ex_cis</b> <i class="arg">cname</i></a></dt>
<dd><p>Determines whether or not the name of the current context is
<i class="arg">cname</i>.</p></dd>
<dt><a name="18"><b class="cmd">ex_cname</b></a></dt>
<dd><p>Returns the name of the current context.</p></dd>
<dt><a name="19"><b class="cmd">ex_cpop</b> <i class="arg">cname</i></a></dt>
<dd><p>Pops a context from the context stack, returning all accumulated
output in that context. The context must be named <i class="arg">cname</i>, or an
error results.</p></dd>
<dt><a name="20"><b class="cmd">ex_cpush</b> <i class="arg">cname</i></a></dt>
<dd><p>Pushes a context named <i class="arg">cname</i> onto the context stack. The
context must be popped by <b class="method">cpop</b> before expansion ends or an
error results.</p></dd>
<dt><a name="21"><b class="cmd">ex_cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Sets variable <i class="arg">varname</i> to <i class="arg">value</i> in the current context.</p></dd>
<dt><a name="22"><b class="cmd">ex_lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the left macro expansion bracket; this is
for use as or within a macro, when the bracket needs to be included in
the output text. If <i class="arg">newbracket</i> is specified, it becomes the new
bracket, and is returned.</p></dd>
<dt><a name="23"><b class="cmd">ex_rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the right macro expansion bracket; this
is for use as or within a macro, when the bracket needs to be included
in the output text. If <i class="arg">newbracket</i> is specified, it becomes the
new bracket, and is returned.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PLUGIN COMMANDS</a></h2>
<p>The plugin has to provide its own set of commands which will then be
called by the frontend in a specific sequence while processing
input. They fall into two categories, management and formatting. Their
expected names, signatures, and responsibilities are specified in the
following two subsections.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Management commands</a></h3>
<p>The management commands a plugin has to provide are used by the
frontend to</p>
<ol class="doctools_enumerated">
<li><p>initialize and shutdown the plugin</p></li>
<li><p>determine the number of passes it has
to make over the input</p></li>
<li><p>initialize and shutdown each pass</p></li>
<li><p>query and initialize engine parameters</p></li>
</ol>
<p>After the plugin has been loaded and the frontend commands are
established the commands will be called in the following sequence:</p>
<pre class="doctools_example">
fmt_numpasses -> n
fmt_listvariables -> vars
fmt_varset var1 value1
fmt_varset var2 value2
...
fmt_varset varK valueK
fmt_initialize
fmt_setup 1
...
fmt_setup 2
...
...
fmt_setup n
...
fmt_postprocess
fmt_shutdown
...
</pre>
<p>I.e. first the number of passes and the set of available engine
parameters is established, followed by calls setting the
parameters. That second part is optional.</p>
<p>After that the plugin is initialized, the specified number of passes
executed, the final result run through a global post processing step
and at last the plugin is shutdown again. This can be followed by more
conversions, restarting the sequence at <b class="cmd">fmt_varset</b>.</p>
<p>In each of the passes, i.e. after the calls of <b class="cmd">fmt_setup</b> the
frontend will process the input and call the formatting commands as
markup is encountered. This means that the sequence of formatting
commands is determined by the grammar of the doctools markup language,
as specified in the <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i> specification.</p>
<p>A different way of looking at the sequence is:</p>
<ul class="doctools_itemized">
<li><p>First some basic parameters are determined.</p></li>
<li><p>Then everything starting at the first <b class="cmd">fmt_varset</b> to
<b class="cmd">fmt_shutdown</b> forms a <i class="term">run</i>, the formatting of a
single input. Each run can be followed by more.</p></li>
<li><p>Embedded within each run we have one or more <i class="term">passes</i>,
each starting with <b class="cmd">fmt_setup</b> and going until either the next
<b class="cmd">fmt_setup</b> or <b class="cmd">fmt_postprocess</b> is reached.</p>
<p>If more than one pass is required to perform the formatting only the
output of the last pass is relevant. The output of all the previous,
preparatory passes is ignored.</p></li>
</ul>
<p>The commands, their names, signatures, and responsibilities are, in
detail:</p>
<dl class="doctools_definitions">
<dt><a name="24"><b class="cmd">fmt_initialize</b></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called at the beginning of every conversion run, as
the first command of that run. Note that a run is not a pass, but may
consist of multiple passes.
It has to initialize the general state of the plugin, beyond the
initialization done during the load. No return value is expected, and
any returned value is ignored.</p></dd>
<dt><a name="25"><b class="cmd">fmt_listvariables</b></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Engine parameters</em>.
Second command is called after the plugin code has been loaded,
i.e. immediately after <b class="cmd">fmt_numpasses</b>.
It has to return a list containing the names of the parameters the
frontend can set to configure the engine. This list can be empty.</p></dd>
<dt><a name="26"><b class="cmd">fmt_numpasses</b></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Pass management</em>.
First command called after the plugin code has been loaded. No other
command of the engine will be called before it.
It has to return the number of passes this engine requires to fully
process the input document. This value has to be an integer number
greater or equal to one.</p></dd>
<dt><a name="27"><b class="cmd">fmt_postprocess</b> <i class="arg">text</i></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called immediately after the last pass in a run. Its
argument is the result of the conversion generated by that pass. It is
provided to allow the engine to perform any global modifications of
the generated document. If no post-processing is required for a
specific format the command has to just return the argument.</p>
<p>Expected to return a value, the final result of formatting the input.</p></dd>
<dt><a name="28"><b class="cmd">fmt_setup</b> <i class="arg">n</i></a></dt>
<dd><p><em>Initialization/Shutdown</em> and <em>Pass management</em>.
This command is called at the beginning of each pass over the input in
a run. Its argument is the number of the pass which has begun. Passes
are counted from <b class="const">1</b> upward.
The command has to set up the internal state of the plugin for this
particular pass. No return value is expected, and any returned value
is ignored.</p></dd>
<dt><a name="29"><b class="cmd">fmt_shutdown</b></a></dt>
<dd><p><em>Initialization/Shutdown</em>.
This command is called at the end of every conversion run. It is the
last command called in a run. It has to clean up of all the
run-specific state in the plugin.
After the call the engine has to be in a state which allows the
initiation of another run without fear that information from the last
run is leaked into this new run.
No return value is expected, and any returned value is ignored.</p></dd>
<dt><a name="30"><b class="cmd">fmt_varset</b> <i class="arg">varname</i> <i class="arg">text</i></a></dt>
<dd><p><em>Engine parameters</em>.
This command is called by the frontend to set an engine parameter to a
particular value.
The parameter to change is specified by <i class="arg">varname</i>, the value to
set in <i class="arg">text</i>.</p>
<p>The command has to throw an error if an unknown <i class="arg">varname</i> is
used. Only the names returned by <b class="cmd">fmt_listvariables</b> have to be
considered as known.</p>
<p>The values of all engine parameters have to persist between passes and
runs.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Formatting commands</a></h3>
<p>The formatting commands have to implement the formatting for the
output format, for all the markup commands of the doctools markup
language, except <b class="cmd">lb</b>, <b class="cmd">rb</b>, <b class="cmd">vset</b>, <b class="cmd">include</b>, and
<b class="cmd"><a href="../../../../index.html#comment">comment</a></b>. These exceptions are processed by the frontend and are
never seen by the plugin. In return a command for the formatting of
plain text has to be provided, something which has no markup in the
input at all.</p>
<p>This means, that each of the 49 markup commands specified in the
<i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i> and outside of the set of
exceptions listed above has an equivalent formatting command which
takes the same arguments as the markup command and whose name is the
name of markup command with the prefix <em>fmt_</em> added to it.</p>
<p>All commands are expected to format their input in some way per the
semantics specified in the command reference and to return whatever
part of this that they deem necessary as their result, which will be
added to the output.</p>
<p>To avoid essentially duplicating the command reference we do not list
any of the command here and simply refer the reader to the
<i class="term"><a href="doctools_lang_cmdref.html">doctools language command reference</a></i> for their signature and
description. The sole exception is the plain text formatter, which has
no equivalent markup command.</p>
<p>The calling sequence of formatting commands is not as rigid as for the
management commands, but determined by the grammar of the doctools
markup language, as specified in the <i class="term"><a href="doctools_lang_syntax.html">doctools language syntax</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="31"><b class="cmd">fmt_plain_text</b> <i class="arg">text</i></a></dt>
<dd><p><em>No associated markup command</em>.</p>
<p>Called by the frontend for any plain text encountered in the
input. It has to perform any and all special processing required for
plain text.</p>
<p>The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.</p></dd>
</dl>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="doctools.html">doctools</a>, <a href="doctools_intro.html">doctools_intro</a>, <a href="doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="doctools_lang_faq.html">doctools_lang_faq</a>, <a href="doctools_lang_intro.html">doctools_lang_intro</a>, <a href="doctools_lang_syntax.html">doctools_lang_syntax</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#document">document</a>, <a href="../../../../index.html#formatter">formatter</a>, <a href="../../../../index.html#formatting_engine">formatting engine</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2010 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools/mpexpand.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<div class='fossil-doc' data-title='mpexpand - Documentation toolbox'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">mpexpand(n) 1.0 tcllib "Documentation toolbox"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>mpexpand - Markup processor</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">NOTES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">mpexpand</b> <span class="opt">?-module <i class="arg">module</i>?</span> <i class="arg">format</i> <i class="arg">infile</i>|- <i class="arg">outfile</i>|-</a></li>
<li><a href="#2"><b class="cmd">mpexpand.all</b> <span class="opt">?<i class="arg">-verbose</i>?</span> <span class="opt">?<i class="arg">module</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This manpage describes a processor / converter for manpages in the
doctools format as specified in <b class="cmd">doctools_fmt</b>. The processor
is based upon the package <b class="package"><a href="doctools.html">doctools</a></b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">mpexpand</b> <span class="opt">?-module <i class="arg">module</i>?</span> <i class="arg">format</i> <i class="arg">infile</i>|- <i class="arg">outfile</i>|-</a></dt>
<dd><p>The processor takes three arguments, namely the code describing which
formatting to generate as the output, the file to read the markup
from, and the file to write the generated output into. If the
<i class="arg">infile</i> is "<b class="const">-</b>" the processor will read from
<b class="const">stdin</b>. If <i class="arg">outfile</i> is "<b class="const">-</b>" the processor will
write to <b class="const">stdout</b>.</p>
<p>If the option <i class="arg">-module</i> is present its value overrides the internal
definition of the module name.</p>
<p>The currently known output formats are</p>
<dl class="doctools_definitions">
<dt><b class="const">nroff</b></dt>
<dd><p>The processor generates *roff output, the standard format for unix
manpages.</p></dd>
<dt><b class="const">html</b></dt>
<dd><p>The processor generates HTML output, for usage in and display by web
browsers.</p></dd>
<dt><b class="const">tmml</b></dt>
<dd><p>The processor generates TMML output, the Tcl Manpage Markup Language,
a derivative of XML.</p></dd>
<dt><b class="const">latex</b></dt>
<dd><p>The processor generates LaTeX output.</p></dd>
<dt><b class="const">wiki</b></dt>
<dd><p>The processor generates Wiki markup as understood by <b class="syscmd">wikit</b>.</p></dd>
<dt><b class="const">list</b></dt>
<dd><p>The processor extracts the information provided by <b class="cmd">manpage_begin</b>.</p></dd>
<dt><b class="const">null</b></dt>
<dd><p>The processor does not generate any output.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">mpexpand.all</b> <span class="opt">?<i class="arg">-verbose</i>?</span> <span class="opt">?<i class="arg">module</i>?</span></a></dt>
<dd><p>This command uses <b class="syscmd">mpexpand</b> to generate all possible output
formats for all manpages in the current directory. The manpages are
recognized through the extension "<b class="file">.man</b>". If <i class="arg">-verbose</i> is
specified the command will list its actions before executing them.</p>
<p>The <i class="arg">module</i> information is passed to <b class="cmd">mpexpand</b>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">NOTES</a></h2>
<p>Possible future formats are plain text, pdf and postscript.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>expander(n), format(n), formatter(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002 Andreas Kupries <[email protected]><br>
Copyright © 2003 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
<div class='fossil-doc' data-title='doctools::html::cssdefaults - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::html::cssdefaults(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::html::cssdefaults - Default CSS style for HTML export plugins</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::html::cssdefaults <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::html::cssdefaults::contents</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single command providing access to the text of
the default CSS style to use for HTML markup generated by the various
HTML export plugins.</p>
<p>This is an internal package of doctools, for use by <i class="term"><a href="../../../../index.html#export">export</a></i> plugins,
i.e. the packages converting doctools related documented into other
formats, most notably <i class="term"><a href="../../../../index.html#html">HTML</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::html::cssdefaults::contents</b></a></dt>
<dd><p>This command returns the text of the default CSS style to use for HTML
markup generated by the various HTML export plugins.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#css">CSS</a>, <a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#style">style</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
<div class='fossil-doc' data-title='doctools::nroff::man_macros - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::nroff::man_macros(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::nroff::man_macros - Default CSS style for NROFF export plugins</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::nroff::man_macros <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::nroff::man_macros::contents</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single command providing access to the
definition of the nroff <em>man</em> macro set to use for NROFF markup
generated by the various NROFF export plugins.</p>
<p>This is an internal package of doctools, for use by <i class="term"><a href="../../../../index.html#export">export</a></i> plugins,
i.e. the packages converting doctools related documented into other
formats, most notably <i class="term"><a href="../../../../index.html#nroff">nroff</a></i>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::nroff::man_macros::contents</b></a></dt>
<dd><p>This command returns the text of the default CSS style to use for NROFF
generated by the various NROFF export plugins.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#macros">macros</a>, <a href="../../../../index.html#man_macros">man_macros</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#plugin">plugin</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<div class='fossil-doc' data-title='doctools::tcl::parse - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::tcl::parse(n) 1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::tcl::parse - Processing text in 'subst -novariables' format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error format</a></li>
<li class="doctools_section"><a href="#section4">Tree Structure</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::stack</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">treeql</b></li>
<li>package require <b class="pkgname">doctools::tcl::parse</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::tcl::parse</b> <b class="method">text</b> <i class="arg">tree</i> <i class="arg">text</i> <span class="opt">?<i class="arg">root</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::tcl::parse</b> <b class="method">file</b> <i class="arg">tree</i> <i class="arg">path</i> <span class="opt">?<i class="arg">root</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for parsing text with embedded Tcl
commands as accepted by the Tcl builtin command
<b class="cmd">subst -novariables</b>. The result of the parsing is an abstract
syntax tree.</p>
<p>This is an internal package of doctools, for use by the higher level
parsers processing the <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>, <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>, and <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>
markup languages.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::tcl::parse</b> <b class="method">text</b> <i class="arg">tree</i> <i class="arg">text</i> <span class="opt">?<i class="arg">root</i>?</span></a></dt>
<dd><p>The command takes the <i class="arg">text</i> and parses it under the assumption
that it contains a string acceptable to the Tcl builtin command
<b class="cmd">subst -novariables</b>. Errors are thrown otherwise during the
parsing. The format used for these errors in described in section
<span class="sectref"><a href="#section3">Error format</a></span>.</p>
<p>The command returns the empty string as it result. The actual result
of the parsing is entered into the tree structure <i class="arg">tree</i>, under
the node <i class="arg">root</i>.
If <i class="arg">root</i> is not specified the root of <i class="arg">tree</i> is used. The
<i class="arg">tree</i> has to exist and be the command of a tree object which
supports the same methods as trees created by the package
<b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>.</p>
<p>In case of errors <i class="arg">tree</i> will be left in an undefined state.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::tcl::parse</b> <b class="method">file</b> <i class="arg">tree</i> <i class="arg">path</i> <span class="opt">?<i class="arg">root</i>?</span></a></dt>
<dd><p>The same as <b class="method">text</b>, except that the text to parse is read from
the file specified by <i class="arg">path</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error format</a></h2>
<p>When the parser encounters a problem in the input
it will throw an error using the format described
here.</p>
<ol class="doctools_enumerated">
<li><p>The message will contain the reason for the problem (unexpected
character or end of input in input), the character in question, if
any, and the line and column the problem was found at, in a human
readable form. This part is not documented further as its format may
change as we see fit. It is intended for human consumption, not
machine.</p></li>
<li><p>The error code however will contain a machine-readable representation
of the problem, in the form of a 5-element list containing, in the
order listed below</p>
<ol class="doctools_enumerated">
<li><p>the constant string <b class="const">doctools::tcl::parse</b></p></li>
<li><p>the cause of the problem, one of</p>
<dl class="doctools_definitions">
<dt><b class="const">char</b></dt>
<dd><p>Unexpected character in input</p></dd>
<dt><b class="const">eof</b></dt>
<dd><p>Unexpected end of the input</p></dd>
</dl>
</li>
<li><p>The location of the problem as offset from the beginning of the input,
counted in characters. Note: Line markers count as one character.</p></li>
<li><p>The line the problem was found on (counted from 1 (one)),</p></li>
<li><p>The column the problem was found at (counted from 0 (zero))</p></li>
</ol>
</li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Tree Structure</a></h2>
<p>After successfully parsing a string the generated tree will have the
following structure:</p>
<ol class="doctools_enumerated">
<li><p>In the following items the word 'root' refers to the node which was
specified as the root of the tree when invoking either <b class="method">text</b>
or <b class="method">file</b>. This may be the actual root of the tree.</p></li>
<li><p>All the following items further ignore the possibility of pre-existing
attributes in the pre-existing nodes. If attributes exists with the
same names as the attributes used by the parser the pre-existing
values are written over. Attributes with names not clashing with the
parser's attributes are not touched.</p></li>
<li><p>The root node has no attributes.</p></li>
<li><p>All other nodes have the attributes</p>
<dl class="doctools_definitions">
<dt>type</dt>
<dd><p>The value is a string from the set { Command , Text , Word }</p></dd>
<dt>range</dt>
<dd><p>The value is either empty or a 2-element list containing integer
numbers. The numbers are the offsets of the first and last character
in the input text, of the token described by the node,.</p></dd>
<dt>line</dt>
<dd><p>The value is an integer, it describes the line in the input the token
described by the node ends on. Lines are counted from 1 (<b class="const">one</b>).</p></dd>
<dt>col</dt>
<dd><p>The value is an integer, it describes the column in the line in the
input the token described by the node ends on. Columns are counted
from 0 (<b class="const">zero</b>).</p></dd>
</dl>
</li>
<li><p>The children of the root, if any, are of type Command and Text, in
semi-alternation. This means: After a Text node a Command node has to
follow, and anything can follow a Command node, a Text or other
Command node.</p></li>
<li><p>The children of a Command node, if any, are of type Command, and Text,
and Word, they describe the arguments of the command.</p></li>
<li><p>The children of a Word node, if any, are of type Command, Text, in
semi-alternation. This means: After a Text node a Command node has to
follow, and anything can follow a Command node, a Text or other
Command node.</p></li>
<li><p>A Word node without children represents the empty string.</p></li>
<li><p>All Text nodes are leaves of the tree.</p></li>
<li><p>All leaves of the tree are either Text or Command nodes.
Word nodes cannot be leaves.</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tcl_syntax">Tcl syntax</a>, <a href="../../../../index.html#command">command</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#subst">subst</a>, <a href="../../../../index.html#word">word</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<div class='fossil-doc' data-title='doctools::msgcat - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat - Message catalog management for the various document parsers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::msgcat::init</b> <i class="arg">prefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat</b> is a support module handling
the selection of message catalogs for the various document processing
packages in the doctools system version 2. As such it is an internal
package a regular user (developer) should not be in direct contact
with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the various
parser packages, and is shared by them. Underneath it, but not
explicit dependencies, are the packages providing the message catalogs
for the various languages.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::msgcat::init</b> <i class="arg">prefix</i></a></dt>
<dd><p>The command locates and loads the message catalogs for all the
languages returned by <b class="cmd">msgcat::mcpreferences</b>, provided that they
could be found. It returns an integer number describing how many
packages were found and loaded.</p>
<p>The names of the packages the command will look for have the form
"doctools::msgcat::<i class="arg">prefix</i>::<b class="variable">langcode</b>", with <i class="arg">prefix</i>
the argument to the command, and the <b class="variable">langcode</b> supplied by the
result of <b class="cmd">msgcat::mcpreferences</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
<div class='fossil-doc' data-title='doctools::idx::export::docidx - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export::docidx(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export::docidx - docidx export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">[docidx] notation of keyword indices</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::export::docidx <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index export plugin for
the generation of docidx markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_export.html">doctools::idx::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_export.html">doctools::idx::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a keyword index, as
specified in section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates docidx markup encoding the index.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">[docidx] notation of keyword indices</a></h2>
<p>The docidx format for keyword indices, also called the
<i class="term">docidx markup language</i>, is too large to be covered in single
section.
The interested reader should start with the document</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/docidx_lang_intro.html">docidx language introduction</a></i></p></li>
</ol>
<p>and then proceed from there to the formal specifications, i.e. the
documents</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/docidx_lang_syntax.html">docidx language syntax</a></i> and</p></li>
<li><p><i class="term"><a href="../doctools/docidx_lang_cmdref.html">docidx language command reference</a></i>.</p></li>
</ol>
<p>to get a thorough understanding of the language.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>The docidx export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">user</i></dt>
<dd><p>This standard configuration variable contains the name of the user
running the process which invoked the export plugin.
The plugin puts this information into the provenance comment at the
beginning of the generated document.</p></dd>
<dt>string <i class="arg">file</i></dt>
<dd><p>This standard configuration variable contains the name of the file the
index came from. This variable may not be set or contain the empty
string.
The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the
generated document.</p></dd>
<dt>boolean <i class="arg">newlines</i></dt>
<dd><p>If this flag is set the plugin will break the generated docidx code
across lines, with each markup command on a separate line.</p>
<p>If this flag is not set (the default), the whole document will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will indent the markup commands
according to the structure of indices. To make this work this also
implies that <b class="variable">newlines</b> is set. This effect is independent of the
value for <b class="variable">aligned</b> however.</p>
<p>If this flag is not set (the default), the output is formatted as per
the values of <b class="variable">newlines</b> and <b class="variable">aligned</b>, and no indenting is
done.</p></dd>
<dt>boolean <i class="arg">aligned</i></dt>
<dd><p>If this flag is set the generator ensures that the arguments for the
<b class="cmd"><a href="../../../../index.html#manpage">manpage</a></b> and <b class="cmd"><a href="../../../../index.html#url">url</a></b> commands in a keyword section are aligned
vertically for a nice table effect. To make this work this also
implies that <b class="variable">newlines</b> is set. This effect is independent of the
value for <b class="variable">indented</b> however.</p>
<p>If this flag is not set (the default), the output is formatted as per
the values of <b class="variable">newlines</b> and <b class="variable">indented</b>, and no alignment is
done.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">format</b>, and <b class="variable">map</b>, and their values.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
|
<div class='fossil-doc' data-title='doctools::idx - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx(n) 2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx - Holding keyword indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::idx <span class="opt">?2?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">key add</b> <i class="arg">name</i></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">key remove</b> <i class="arg">name</i></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">key references</b> <i class="arg">name</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">keys</b></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">reference add</b> <i class="arg">type</i> <i class="arg">key</i> <i class="arg">name</i> <i class="arg">label</i></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">reference remove</b> <i class="arg">name</i></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">reference label</b> <i class="arg">name</i></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">reference keys</b> <i class="arg">name</i></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">reference type</b> <i class="arg">name</i></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">references</b></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">title</b></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">title</b> <i class="arg">text</i></a></li>
<li><a href="#16"><i class="arg">objectName</i> <b class="method">label</b></a></li>
<li><a href="#17"><i class="arg">objectName</i> <b class="method">label</b> <i class="arg">text</i></a></li>
<li><a href="#18"><i class="arg">objectName</i> <b class="method">importer</b></a></li>
<li><a href="#19"><i class="arg">objectName</i> <b class="method">importer</b> <i class="arg">object</i></a></li>
<li><a href="#20"><i class="arg">objectName</i> <b class="method">exporter</b></a></li>
<li><a href="#21"><i class="arg">objectName</i> <b class="method">exporter</b> <i class="arg">object</i></a></li>
<li><a href="#22"><i class="arg">objectName</i> <b class="method">deserialize =</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#23"><i class="arg">objectName</i> <b class="method">deserialize +=</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#24"><i class="arg">objectName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">format</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to contain and programmatically
manipulate keyword indices</p>
<p>This is one of the three public pillars the management of keyword
indices resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="idx_export.html">Exporting keyword indices</a></i>, and</p></li>
<li><p><i class="term"><a href="idx_import.html">Importing keyword indices</a></i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of keyword indices, and
their parts, see the same-named section.
For information about the data structure which is used to encode
keyword indices as values see the section
<span class="sectref"><a href="#section4">Keyword index serialization format</a></span>.
This is the only format directly known to this class. Conversions from
and to any other format are handled by export and import manager
objects. These may be attached to a container, but do not have to be,
it is merely a convenience.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#keyword_index">keyword index</a></i> consists of a (possibly empty) set of <i class="term"><a href="../../../../index.html#keywords">keywords</a></i>.</p></li>
<li><p>Each keyword in the set is identified by its name.</p></li>
<li><p>Each keyword has a (possibly empty) set of <i class="term">references</i>.</p></li>
<li><p>A reference can be associated with more than one keyword.</p></li>
<li><p>A reference not associated with at least one keyword is not possible
however.</p></li>
<li><p>Each reference is identified by its target, specified as either an url
or symbolic filename, depending on the type of reference (<b class="const">url</b>,
or <b class="const">manpage</b>).</p></li>
<li><p>The type of a reference (url, or manpage) depends only on the
reference itself, and not the keywords it is associated with.</p></li>
<li><p>In addition to a type each reference has a descriptive label as
well. This label depends only on the reference itself, and not the
keywords it is associated with.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>Manpage references are intended to be used for references to the
documents the index is made for. Their target is a symbolic file name
identifying the document, and export plugins may replace symbolic with
actual file names, if specified.</p></li>
<li><p>Url references are intended on the othre hand are inteded to be used
for links to anything else, like websites. Their target is an url.</p></li>
<li><p>While url and manpage references share a namespace for their
identifiers, this should be no problem, given that manpage identifiers
are symbolic filenames and as such they should never look like urls,
the identifiers for url references.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new container object with an associated Tcl
command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command is
explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::idx</b> command have the
following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">key add</b> <i class="arg">name</i></a></dt>
<dd><p>This method adds the keyword <i class="arg">name</i> to the index. If the keyword
is already known nothing is done. The result of the method is the
empty string.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">key remove</b> <i class="arg">name</i></a></dt>
<dd><p>This method removes the keyword <i class="arg">name</i> from the index. If the
keyword is already gone nothing is done. Any references for whom this
keyword was the last association are removed as well. The result of
the method is the empty string.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">key references</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns a list containing the names of all references
associated with the keyword <i class="arg">name</i>. An error is thrown in the
keyword is not known to the index. The order of the references in the
list is undefined.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">keys</b></a></dt>
<dd><p>This method returns a list containing the names of all keywords known
to the index. The order of the keywords in the list is undefined.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">reference add</b> <i class="arg">type</i> <i class="arg">key</i> <i class="arg">name</i> <i class="arg">label</i></a></dt>
<dd><p>This method adds the reference <i class="arg">name</i> to the index and associates
it with the keyword <i class="arg">key</i>.
The other two arguments hold the <i class="arg">type</i> and <i class="arg">label</i> of the
reference, respectively.
The type has to match the stored information, should the reference
exist already, i.e. this information is immutable after the reference
is known. The only way to change it is delete and recreate the
reference.
The label on the other hand is automatically updated to the value of
the argument, overwriting any previously stored information.
Should the reference exists already it is simply associated with the
<i class="arg">key</i>. If that is true already as well nothing is done, but the
<i class="arg">label</i> updated to the new value. The result of the method is the
empty string.</p>
<p>The <i class="arg">type</i> argument has be to one of <b class="const">manpage</b> or <b class="const">url</b>.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">reference remove</b> <i class="arg">name</i></a></dt>
<dd><p>The reference <i class="arg">name</i> is removed from the index. All associations
with keywords are released and the relevant reference labels removed.
The result of the method is the empty string.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">reference label</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns the label associated with the reference
<i class="arg">name</i>. An error is thrown if the reference is not known.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">reference keys</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns a list containing the names of all keywords
associated with the reference <i class="arg">name</i>. An error is thrown in the
reference is not known to the index. The order of the keywords in the
list is undefined.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">reference type</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns the type of the reference <i class="arg">name</i>. An error is
thrown in the reference is not known to the index.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">references</b></a></dt>
<dd><p>This method returns a list containing the names of all references
known to the index. The order of the references in the list is
undefined.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">title</b></a></dt>
<dd><p>Returns the currently defined title of the keyword index.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">title</b> <i class="arg">text</i></a></dt>
<dd><p>Sets the title of the keyword index to <i class="arg">text</i>, and returns it as
the result of the command.</p></dd>
<dt><a name="16"><i class="arg">objectName</i> <b class="method">label</b></a></dt>
<dd><p>Returns the currently defined label of the keyword index.</p></dd>
<dt><a name="17"><i class="arg">objectName</i> <b class="method">label</b> <i class="arg">text</i></a></dt>
<dd><p>Sets the label of the keyword index to <i class="arg">text</i>, and returns it as
the result of the command.</p></dd>
<dt><a name="18"><i class="arg">objectName</i> <b class="method">importer</b></a></dt>
<dd><p>Returns the import manager object currently attached to the container,
if any.</p></dd>
<dt><a name="19"><i class="arg">objectName</i> <b class="method">importer</b> <i class="arg">object</i></a></dt>
<dd><p>Attaches the <i class="arg">object</i> as import manager to the container, and
returns it as the result of the command.
Note that the <i class="arg">object</i> is <em>not</em> put into ownership of the
container. I.e., destruction of the container will <em>not</em> destroy
the <i class="arg">object</i>.</p>
<p>It is expected that <i class="arg">object</i> provides a method named
<b class="method">import text</b> which takes a text and a format name, and
returns the canonical serialization of the keyword index contained in
the text, assuming the given format.</p></dd>
<dt><a name="20"><i class="arg">objectName</i> <b class="method">exporter</b></a></dt>
<dd><p>Returns the export manager object currently attached to the container,
if any.</p></dd>
<dt><a name="21"><i class="arg">objectName</i> <b class="method">exporter</b> <i class="arg">object</i></a></dt>
<dd><p>Attaches the <i class="arg">object</i> as export manager to the container, and
returns it as the result of the command.
Note that the <i class="arg">object</i> is <em>not</em> put into ownership of the
container. I.e., destruction of the container will <em>not</em> destroy
the <i class="arg">object</i>.</p>
<p>It is expected that <i class="arg">object</i> provides a method named
<b class="method">export object</b> which takes the container and a format name,
and returns a text encoding keyword index stored in the container, in
the given format. It is further expected that the <i class="arg">object</i> will
use the container's method <b class="method">serialize</b> to obtain the
serialization of the keyword index from which to generate the text.</p></dd>
<dt><a name="22"><i class="arg">objectName</i> <b class="method">deserialize =</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method replaces the contents of the index object with the index
contained in the <i class="arg">data</i>. If no <i class="arg">format</i> was specified it is
assumed to be the regular serialization of a keyword index.</p>
<p>Otherwise the object will use the attached import manager to convert
the data from the specified format to a serialization it can handle.
In that case an error will be thrown if the container has no import
manager attached to it.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="23"><i class="arg">objectName</i> <b class="method">deserialize +=</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">deserialize =</b> in its essentials,
except that it merges the keyword index in the <i class="arg">data</i> to its
contents instead of replacing it.
The method will throw an error if merging is not possible, i.e. would
produce an invalid index. The existing content is left unchanged in
that case.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="24"><i class="arg">objectName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method returns the keyword index contained in the object. If no
<i class="arg">format</i> is not specified the returned result is the canonical
serialization of its contents.</p>
<p>Otherwise the object will use the attached export manager to convert
the data to the specified format.
In that case an error will be thrown if the container has no export
manager attached to it.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#docidx_markup">docidx markup</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#generation">generation</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#latex">latex</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#tcler_s_wiki">tcler's wiki</a>, <a href="../../../../index.html#text">text</a>, <a href="../../../../index.html#url">url</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_export.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
|
<div class='fossil-doc' data-title='doctools::idx::export - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export - Exporting keyword indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Export plugin API v2 reference</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::idx::export <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::config</b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx::export</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">export serial</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">export object</b> <i class="arg">object</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">config names</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">config get</b></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></li>
<li><a href="#10"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to manage the plugins for the export of
keyword indices to other formats, i.e. their conversion to, for
example <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>, <i class="term"><a href="../../../../index.html#html">HTML</a></i>, etc.</p>
<p>This is one of the three public pillars the management of keyword
indices resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="idx_import.html">Importing keyword indices</a></i>, and</p></li>
<li><p><i class="term"><a href="idx_container.html">Holding keyword indices</a></i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of keyword indices, and
their parts, see the same-named section.
For information about the data structure which is the major input to
the manager objects provided by this package see the section
<span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p>
<p>The plugin system of our class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">DOCTOOLS_IDX_EXPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_IDX_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/export/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/export/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\EXPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using Windows(tm) operating system.</p>
<p>The whole system is delivered with six predefined export plugins,
namely</p>
<dl class="doctools_definitions">
<dt>docidx</dt>
<dd><p>See <i class="term"><a href="export_docidx.html">docidx export plugin</a></i> for details.</p></dd>
<dt>html</dt>
<dd><p>See <i class="term">html export plugin</i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">json export plugin</i> for details.</p></dd>
<dt>nroff</dt>
<dd><p>See <i class="term"><a href="idx_export_nroff.html">nroff export plugin</a></i> for details.</p></dd>
<dt>text</dt>
<dd><p>See <i class="term">text export plugin</i> for details.</p></dd>
<dt>wiki</dt>
<dd><p>See <i class="term"><a href="idx_export_wiki.html">wiki export plugin</a></i> for details.</p></dd>
</dl>
<p>Readers wishing to write their own export plugin for some format, i.e.
<i class="term">plugin writer</i>s reading and understanding the section
containing the <span class="sectref"><a href="#section4">Export plugin API v2 reference</a></span> is an
absolute necessity, as it specifies the interaction between this
package and its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#keyword_index">keyword index</a></i> consists of a (possibly empty) set of <i class="term"><a href="../../../../index.html#keywords">keywords</a></i>.</p></li>
<li><p>Each keyword in the set is identified by its name.</p></li>
<li><p>Each keyword has a (possibly empty) set of <i class="term">references</i>.</p></li>
<li><p>A reference can be associated with more than one keyword.</p></li>
<li><p>A reference not associated with at least one keyword is not possible
however.</p></li>
<li><p>Each reference is identified by its target, specified as either an url
or symbolic filename, depending on the type of reference (<b class="const">url</b>,
or <b class="const">manpage</b>).</p></li>
<li><p>The type of a reference (url, or manpage) depends only on the
reference itself, and not the keywords it is associated with.</p></li>
<li><p>In addition to a type each reference has a descriptive label as
well. This label depends only on the reference itself, and not the
keywords it is associated with.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>Manpage references are intended to be used for references to the
documents the index is made for. Their target is a symbolic file name
identifying the document, and export plugins may replace symbolic with
actual file names, if specified.</p></li>
<li><p>Url references are intended on the othre hand are inteded to be used
for links to anything else, like websites. Their target is an url.</p></li>
<li><p>While url and manpage references share a namespace for their
identifiers, this should be no problem, given that manpage identifiers
are symbolic filenames and as such they should never look like urls,
the identifiers for url references.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx::export</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new export manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::idx::export</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">export serial</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the canonical serialization of a keyword index
stored in <i class="arg">serial</i> and converts it to the specified <i class="arg">format</i>,
using the export plugin for the format. An error is thrown if no
plugin could be found for the format.
The string generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">docidx</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p>
<p>The plugin has to conform to the interface specified in section
<span class="sectref"><a href="#section4">Export plugin API v2 reference</a></span>.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">export object</b> <i class="arg">object</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">export serial</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">serialize</b> method returning the canonical serialization of a
keyword index. It invokes that method, feeds the result into
<b class="method">export serial</b> and returns the resulting string as its own
result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">config names</b></a></dt>
<dd><p>This method returns a list containing the names of all configuration
variables currently known to the object.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">config get</b></a></dt>
<dd><p>This method returns a dictionary containing the names and values of
all configuration variables currently known to the object.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>This method sets the configuration variable <i class="arg">name</i> to the
specified <i class="arg">value</i> and returns the new value of the variable.</p>
<p>If no value is specified it simply returns the current value, without
changing it.</p>
<p>Note that while the user can set the predefined configuration
variables <b class="const">user</b> and <b class="const">format</b> doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></dt>
<dd><p>This method unsets all configuration variables matching the specified
glob <i class="arg">pattern</i>s. If no pattern is specified it will unset all
currently defined configuration variables.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Export plugin API v2 reference</a></h2>
<p>Plugins are what this package uses to manage the support for any
output format beyond the
<span class="sectref"><a href="#section5">Keyword index serialization format</a></span>. Here we specify the
API the objects created by this package use to interact with their
plugins.</p>
<p>A plugin for this package has to follow the rules listed below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
doctools::idx::export::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
generate output for. This name is also the argument to provide
to the various <b class="method">export</b> methods of export manager
objects to get a string encoding a keyword index in that
format.</p></li>
<li><p>The plugin can expect that the package
<b class="package">doctools::idx::export::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p></li>
<li><p>A plugin has to provide one command, with the signature shown
below.</p>
<dl class="doctools_definitions">
<dt><a name="10"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>Whenever an export manager of <b class="package"><a href="idx_container.html">doctools::idx</a></b> has to generate
output for an index it will invoke this command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">serial</i></dt>
<dd><p>This argument will contain the <i class="term">canonical</i> serialization of the
index for which to generate the output.
The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p></dd>
<dt>dictionary <i class="arg">configuration</i></dt>
<dd><p>This argument will contain the current configuration to apply to the
generation, as a dictionary mapping from variable names to values.</p>
<p>The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables recognized
by a plugin will be described in the manpage for that plugin.</p>
<dl class="doctools_definitions">
<dt>user</dt>
<dd><p>This variable is expected to contain the name of the user
owning the process invoking the plugin.</p></dd>
<dt>format</dt>
<dd><p>This variable is expected to contain the name of the
format whose plugin is invoked.</p></dd>
<dt>file</dt>
<dd><p>This variable, if defined by the user of the index object
is expected to contain the name of the input file for which
the plugin is generating its output for.</p></dd>
<dt>map</dt>
<dd><p>This variable, if defined by the user of the index object is
expected to contain a dictionary mapping from symbolic file
names used in the references of type <b class="const">manpage</b> to
actual paths (or urls). A plugin has to be able to handle
the possibility that a symbolic name is without entry in
this mapping.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of the invokations of
the command <b class="cmd"><a href="../../../../index.html#export">export</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#generation">generation</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#tcler_s_wiki">tcler's wiki</a>, <a href="../../../../index.html#text">text</a>, <a href="../../../../index.html#url">url</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2018 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
|
<div class='fossil-doc' data-title='doctools::idx::export::html - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export::html(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export::html - HTML export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::export::html <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
<li>package require <b class="pkgname">doctools::html</b></li>
<li>package require <b class="pkgname">doctools::html::cssdefaults</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index export plugin for
the generation of HTML markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_export.html">doctools::idx::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_export.html">doctools::idx::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a keyword index, as
specified in section <span class="sectref"><a href="#section4">Keyword index serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates HTML markup encoding the index.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The html export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">user</i></dt>
<dd><p>This standard configuration variable contains the name of the user
running the process which invoked the export plugin.
The plugin puts this information into the provenance comment at the
beginning of the generated document.</p></dd>
<dt>string <i class="arg">file</i></dt>
<dd><p>This standard configuration variable contains the name of the file the
index came from. This variable may not be set or contain the empty
string.
The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the
generated document.</p></dd>
<dt>dictionary <i class="arg">map</i></dt>
<dd><p>This standard configuration variable contains a dictionary mapping
from the symbolic files names in manpage references to the actual
filenames and/or urls to be used in the output.</p>
<p>Url references and symbolic file names without a mapping are used
unchanged.</p></dd>
<dt>boolean <i class="arg">newlines</i></dt>
<dd><p>If this flag is set the plugin will break the generated html code
across lines, with each markup command on a separate line.</p>
<p>If this flag is not set (the default), the whole document will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will indent the markup commands
according to the structure of indices. To make this work this also
implies that <b class="variable">newlines</b> is set.</p>
<p>If this flag is not set (the default), the output is formatted as per
the value of <b class="variable">newlines</b>, and no indenting is done.</p></dd>
<dt>string <i class="arg">meta</i></dt>
<dd><p>This variable is meant to hold a fragment of HTML (default: empty).
The fragment it contains will be inserted into the generated output in
the <head> section of the document, just after the <title> tag.</p></dd>
<dt>string <i class="arg">header</i></dt>
<dd><p>This variable is meant to hold a fragment of HTML (default: empty).
The fragment it contains will be inserted into the generated output
just after the <h1> title tag in the body of the document, in the
class.header <div>'ision.</p></dd>
<dt>string <i class="arg">footer</i></dt>
<dd><p>This variable is meant to hold a fragment of HTML (default:
empty). The fragment it contains will be inserted into the generated
output just before the </body> tag, in the class.footer <div>'ision.</p></dd>
<dt>dictionary <i class="arg">kwid</i></dt>
<dd><p>The value of this variable (default: empty) maps keywords to the
identifiers to use as their anchor names. Each keyword <b class="variable">FOO</b> not
found in the dictionary uses <b class="const">KW-</b><b class="variable">FOO</b> as anchor,
i.e. itself prefixed with the string <b class="const">KW-</b>.</p></dd>
<dt>string <i class="arg">sepline</i></dt>
<dd><p>The value of this variable is the string to use for the separator
comments inserted into the output when the outpout is broken across
lines and/or indented. The default string consists of 60 dashes.</p></dd>
<dt>integer <i class="arg">kwidth</i></dt>
<dd><p>This variable holds the size of the keyword column in the main table
generated by the plugin, in percent of the total width of the
table. This is an integer number in the range of 1 to 99. Choosing a
value outside of that range causes the generator to switch back to the
defauly setting, 35 percent.</p></dd>
<dt>string <i class="arg">dot</i></dt>
<dd><p>This variable contains a HTML fragment inserted between the entries of
the navigation bar, and the references associated with each keyword.
The default is the HTML entity &#183; i.e. the bullet character, also
known as the "Greek middle dot", i.e. the unicode character 00B7.</p></dd>
<dt>string <i class="arg">class.main</i></dt>
<dd><p>This variable contains the class name for the main <div>'ivision of
the generated document. The default is <b class="const">doctools</b>.</p></dd>
<dt>string <i class="arg">class.header</i></dt>
<dd><p>This variable contains the class name for the header <div>'ision of
the generated document. The default is <b class="const">idx-header</b>. This
division contains the document title, the user specified <b class="variable">header</b>,
if any, a visible separator line, and the navigation bar for quick
access to each keyword section.</p></dd>
<dt>string <i class="arg">class.title</i></dt>
<dd><p>This variable contains the class name for the <h1> tag enclosing the
document title. The default is <b class="const">idx-title</b>.</p></dd>
<dt>string <i class="arg">class.navsep</i></dt>
<dd><p>This variable contains the class name for the <hr> separators in the
header and footer sections of the generated document. The default is
<b class="const">idx-navsep</b>.</p></dd>
<dt>string <i class="arg">class.navbar</i></dt>
<dd><p>This variable contains the class name for the navigation <div>'ision
enclosing the navigation bar of the generated document. The default is
<b class="const">idx-kwnav</b>.</p></dd>
<dt>string <i class="arg">class.contents</i></dt>
<dd><p>This variable contains the class name for the <table> holding the
keywords and their references in the generated document. The default
is <b class="const">idx-contents</b>.</p></dd>
<dt>string <i class="arg">class.leader</i></dt>
<dd><p>This variable contains the class name for the anchor names the plugin
inserts into the keyword table when switching from one section to the
next (Each section holds all keywords with a particular first
character). The default is <b class="const">idx-leader</b>.</p></dd>
<dt>string <i class="arg">class.row0</i></dt>
<dd><p>This variable contains the class name used to label the even rows
(<tr>) of the keyword table. The default is <b class="const">idx-even</b>.</p></dd>
<dt>string <i class="arg">class.row1</i></dt>
<dd><p>This variable contains the class name used to label the odd rows
(<tr>) of the keyword table. The default is <b class="const">idx-odd</b>.</p></dd>
<dt>string <i class="arg">class.keyword</i></dt>
<dd><p>This variable contains the class name used to label the keyword
cells/column (<td>) in the keyword table of the document. The default
is <b class="const">idx-keyword</b>.</p></dd>
<dt>string <i class="arg">class.refs</i></dt>
<dd><p>This variable contains the class name used to label the reference
cells/column (<td>) in the keyword table of the document. The default
is <b class="const">idx-refs</b>.</p></dd>
<dt>string <i class="arg">class.footer</i></dt>
<dd><p>This variable contains the class name for the footer <div>'ision of
the generated document. The default is <b class="const">idx-footer</b>. This
division contains a browser-visible separator line and the user
specified <b class="variable">footer</b>, if any.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variable <b class="variable">format</b>, and its value.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
|
<div class='fossil-doc' data-title='doctools::idx::export::json - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export::json(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export::json - JSON export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">JSON notation of keyword indices</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::export::json <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">textutil::adjust</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index export plugin for
the generation of JSON markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_export.html">doctools::idx::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_export.html">doctools::idx::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a keyword index, as
specified in section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates JSON markup encoding the index.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">JSON notation of keyword indices</a></h2>
<p>The JSON format used for keyword indices is a direct translation of
the <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>, mapping Tcl
dictionaries as JSON objects and Tcl lists as JSON arrays.
For example, the Tcl serialization</p>
<pre class="doctools_example">
doctools::idx {
label {Keyword Index}
keywords {
changelog {changelog.man cvs.man}
conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
cvs cvs.man
}
references {
apps/dtplite.man {manpage dtplite}
changelog.man {manpage doctools::changelog}
cvs.man {manpage doctools::cvs}
docidx.man {manpage doctools::idx}
doctoc.man {manpage doctools::toc}
doctools.man {manpage doctools}
mpexpand.man {manpage mpexpand}
}
title {}
}
</pre>
<p>is equivalent to the JSON string</p>
<pre class="doctools_example">
{
"doctools::idx" : {
"label" : "Keyword Index",
"keywords" : {
"changelog" : ["changelog.man","cvs.man"],
"conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
"cvs" : ["cvs.man"],
},
"references" : {
"apps\/dtplite.man" : ["manpage","dtplite"],
"changelog.man" : ["manpage","doctools::changelog"],
"cvs.man" : ["manpage","doctools::cvs"],
"docidx.man" : ["manpage","doctools::idx"],
"doctoc.man" : ["manpage","doctools::toc"],
"doctools.man" : ["manpage","doctools"],
"mpexpand.man" : ["manpage","mpexpand"]
},
"title" : ""
}
}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>The JSON export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will break the generated JSON code
across lines and indent it according to its inner structure, with each
key of a dictionary on a separate line.</p>
<p>If this flag is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">aligned</i></dt>
<dd><p>If this flag is set the generator ensures that the values for the keys
in a dictionary are vertically aligned with each other, for a nice
table effect. To make this work this also implies that <b class="variable">indented</b>
is set.</p>
<p>If this flag is not set (the default), the output is formatted as per
the value of <b class="variable">indented</b>, without trying to align the values for
dictionary keys.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">format</b>, <b class="variable">file</b>, and <b class="variable">map</b> and
their values.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<div class='fossil-doc' data-title='doctools::idx::export::nroff - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export::nroff(n) 0.3 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export::nroff - nroff export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::export::nroff <span class="opt">?0.3?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
<li>package require <b class="pkgname">doctools::nroff::man_macros</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index export plugin for
the generation of nroff markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_export.html">doctools::idx::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_export.html">doctools::idx::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a keyword index, as
specified in section <span class="sectref"><a href="#section4">Keyword index serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates nroff markup encoding the index.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The nroff export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">user</i></dt>
<dd><p>This standard configuration variable contains the name of the user
running the process which invoked the export plugin.
The plugin puts this information into the provenance comment at the
beginning of the generated document.</p></dd>
<dt>string <i class="arg">file</i></dt>
<dd><p>This standard configuration variable contains the name of the file the
index came from. This variable may not be set or contain the empty
string.
The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the
generated document.</p></dd>
<dt>boolean <i class="arg">inline</i></dt>
<dd><p>If this flag is set (default) the plugin will place the definitions of
the man macro set directly into the output.</p>
<p>If this flag is not set, the plugin will place a reference to the
definitions of the man macro set into the output, but not the macro
definitions themselves.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">format</b>, and <b class="variable">map</b>, and their values.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<div class='fossil-doc' data-title='doctools::idx::export::text - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export::text(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export::text - plain text export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::export::text <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index export plugin for
the generation of plain text markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_export.html">doctools::idx::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_export.html">doctools::idx::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a keyword index, as
specified in section <span class="sectref"><a href="#section4">Keyword index serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates plain text markup encoding the index.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The text export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>dictionary <i class="arg">map</i></dt>
<dd><p>This standard configuration variable contains a dictionary mapping
from the symbolic files names in manpage references to the actual
filenames and/or urls to be used in the output.</p>
<p>Url references and symbolic file names without a mapping are used
unchanged.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">file</b>, and <b class="variable">format</b>, and their values.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#plain_text">plain text</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<div class='fossil-doc' data-title='doctools::idx::export::wiki - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::export::wiki(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::export::wiki - wiki export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Wiki markup</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::export::wiki <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index export plugin for
the generation of wiki markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_export.html">doctools::idx::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_export.html">doctools::idx::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a keyword index, as
specified in section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates wiki markup encoding the index.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Wiki markup</a></h2>
<p>The basic syntax of the wiki markup generated by this plugin are
described at <a href="http://wiki.tcl.tk/14">http://wiki.tcl.tk/14</a>.</p>
<p>The plugin goes beyond the classic markup to generate proper headers
and either a table or indented list of the keywords and their
references.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>The wiki export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>dictionary <i class="arg">map</i></dt>
<dd><p>This standard configuration variable contains a dictionary mapping
from the symbolic files names in manpage references to the actual
filenames and/or urls to be used in the output.</p>
<p>Url references and symbolic file names without a mapping are used
unchanged.</p></dd>
<dt>enum <i class="arg">style</i></dt>
<dd><p>This variable recognizes two values as legal, <b class="const">list</b> (default),
and <b class="const">table</b>.
Depending on the value the plugin generates either a list- or
table-based wiki page for the index.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">file</b> and <b class="variable">format</b>, and their values.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_import.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
|
<div class='fossil-doc' data-title='doctools::idx::import - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::import(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::import - Importing keyword indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Import plugin API v2 reference</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::idx::import <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::config</b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx::import</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">config names</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">config get</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">includes</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">include clear</b></a></li>
<li><a href="#16"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></li>
<li><a href="#17"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to manage the plugins for the import of
keyword indices from other formats, i.e. their conversion from, for
example <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>, <i class="term"><a href="../../../../index.html#json">json</a></i>, etc.</p>
<p>This is one of the three public pillars the management of keyword
indices resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="idx_export.html">Exporting keyword indices</a></i>, and</p></li>
<li><p><i class="term"><a href="idx_container.html">Holding keyword indices</a></i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of keyword indices, and
their parts, see the same-named section.
For information about the data structure which is the major output of
the manager objects provided by this package see the section
<span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p>
<p>The plugin system of our class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">DOCTOOLS_IDX_IMPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_IDX_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/import/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/import/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/idx/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\IMPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using Windows(tm) operating system.</p>
<p>The whole system is delivered with two predefined import plugins,
namely</p>
<dl class="doctools_definitions">
<dt>docidx</dt>
<dd><p>See <i class="term"><a href="import_docidx.html">docidx import plugin</a></i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">json import plugin</i> for details.</p></dd>
</dl>
<p>Readers wishing to write their own import plugin for some format, i.e.
<i class="term">plugin writer</i>s reading and understanding the section
containing the <span class="sectref"><a href="#section4">Import plugin API v2 reference</a></span> is an
absolute necessity, as it specifies the interaction between this
package and its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#keyword_index">keyword index</a></i> consists of a (possibly empty) set of <i class="term"><a href="../../../../index.html#keywords">keywords</a></i>.</p></li>
<li><p>Each keyword in the set is identified by its name.</p></li>
<li><p>Each keyword has a (possibly empty) set of <i class="term">references</i>.</p></li>
<li><p>A reference can be associated with more than one keyword.</p></li>
<li><p>A reference not associated with at least one keyword is not possible
however.</p></li>
<li><p>Each reference is identified by its target, specified as either an url
or symbolic filename, depending on the type of reference (<b class="const">url</b>,
or <b class="const">manpage</b>).</p></li>
<li><p>The type of a reference (url, or manpage) depends only on the
reference itself, and not the keywords it is associated with.</p></li>
<li><p>In addition to a type each reference has a descriptive label as
well. This label depends only on the reference itself, and not the
keywords it is associated with.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>Manpage references are intended to be used for references to the
documents the index is made for. Their target is a symbolic file name
identifying the document, and export plugins may replace symbolic with
actual file names, if specified.</p></li>
<li><p>Url references are intended on the othre hand are inteded to be used
for links to anything else, like websites. Their target is an url.</p></li>
<li><p>While url and manpage references share a namespace for their
identifiers, this should be no problem, given that manpage identifiers
are symbolic filenames and as such they should never look like urls,
the identifiers for url references.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx::import</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new import manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::idx::import</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the <i class="arg">text</i> and converts it from the specified
<i class="arg">format</i> to the canonical serialization of a keyword index using
the import plugin for the format. An error is thrown if no plugin
could be found for the format.
The serialization generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">docidx</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>.</p>
<p>The plugin has to conform to the interface specified in section
<span class="sectref"><a href="#section4">Import plugin API v2 reference</a></span>.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It reads the contents of the specified file into memory, feeds the
result into <b class="method">import text</b> and returns the resulting
serialization as its own result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">deserialize</b> method expecting the canonical serialization of a
keyword index.
It imports the text using <b class="method">import text</b> and then feeds the
resulting serialization into the <i class="arg">object</i> via <b class="method">deserialize</b>.
This method returns the empty string as it result.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">import object text</b>, except that it
reads the text to convert from the specified file instead of being
given it as argument.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">config names</b></a></dt>
<dd><p>This method returns a list containing the names of all configuration
variables currently known to the object.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">config get</b></a></dt>
<dd><p>This method returns a dictionary containing the names and values of
all configuration variables currently known to the object.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>This method sets the configuration variable <i class="arg">name</i> to the
specified <i class="arg">value</i> and returns the new value of the variable.</p>
<p>If no value is specified it simply returns the current value, without
changing it.</p>
<p>Note that while the user can set the predefined configuration
variables <b class="const">user</b> and <b class="const">format</b> doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></dt>
<dd><p>This method unsets all configuration variables matching the specified
glob <i class="arg">pattern</i>s. If no pattern is specified it will unset all
currently defined configuration variables.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">includes</b></a></dt>
<dd><p>This method returns a list containing the currently specified paths to
use to search for include files when processing input.
The order of paths in the list corresponds to the order in which they
are used, from first to last, and also corresponds to the order in
which they were added to the object.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></dt>
<dd><p>This methods adds the specified <i class="arg">path</i> to the list of paths to use
to search for include files when processing input. The path is added
to the end of the list, causing it to be searched after all previously
added paths. The result of the command is the empty string.</p>
<p>The method does nothing if the path is already known.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></dt>
<dd><p>This methods removes the specified <i class="arg">path</i> from the list of paths
to use to search for include files when processing input. The result
of the command is the empty string.</p>
<p>The method does nothing if the path is not known.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">include clear</b></a></dt>
<dd><p>This method clears the list of paths to use to search for include
files when processing input. The result of the command is the empty
string.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Import plugin API v2 reference</a></h2>
<p>Plugins are what this package uses to manage the support for any input
format beyond the <span class="sectref"><a href="#section5">Keyword index serialization format</a></span>. Here
we specify the API the objects created by this package use to interact
with their plugins.</p>
<p>A plugin for this package has to follow the rules listed below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
doctools::idx::import::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
generate output for. This name is also the argument to provide
to the various <b class="method">import</b> methods of import manager
objects to get a string encoding a keyword index in that
format.</p></li>
<li><p>The plugin can expect that the package
<b class="package">doctools::idx::export::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p></li>
<li><p>The plugin can expect that a command named <b class="cmd">IncludeFile</b> is
present, with the signature</p>
<dl class="doctools_definitions">
<dt><a name="16"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></dt>
<dd><p>This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such. An example of
such a format would be <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>.</p>
<p>The plugin has to supply the following arguments</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">currentfile</i></dt>
<dd><p>The path of the file it is currently processing. This may be the empty
string if no such is known.</p></dd>
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of the include file as specified in the include directive
being processed.</p></dd>
</dl>
<p>The result of the command will be a 5-element list containing</p>
<ol class="doctools_enumerated">
<li><p>A boolean flag indicating the success (<b class="const">True</b>) or failure
(<b class="const">False</b>) of the operation.</p></li>
<li><p>In case of success the contents of the included file, and the
empty string otherwise.</p></li>
<li><p>The resolved, i.e. absolute path of the included file, if
possible, or the unchanged <i class="arg">path</i> argument. This is for
display in an error message, or as the <i class="arg">currentfile</i>
argument of another call to <b class="cmd">IncludeFile</b> should this file
contain more files.</p></li>
<li><p>In case of success an empty string, and for failure a code
indicating the reason for it, one of</p>
<dl class="doctools_definitions">
<dt>notfound</dt>
<dd><p>The specified file could not be found.</p></dd>
<dt>notread</dt>
<dd><p>The specified file was found, but not be read into memory.</p></dd>
</dl>
</li>
<li><p>An empty string in case of success of a <b class="const">notfound</b>
failure, and an additional error message describing the reason
for a <b class="const">notread</b> error in more detail.</p></li>
</ol></dd>
</dl>
</li>
<li><p>A plugin has to provide one command, with the signature shown
below.</p>
<dl class="doctools_definitions">
<dt><a name="17"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i> <i class="arg">configuration</i></a></dt>
<dd><p>Whenever an import manager of <b class="package"><a href="idx_container.html">doctools::idx</a></b> has to parse
input for an index it will invoke this command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">text</i></dt>
<dd><p>This argument will contain the text encoding the index per the format
the plugin is for.</p></dd>
<dt>dictionary <i class="arg">configuration</i></dt>
<dd><p>This argument will contain the current configuration to apply to the
parsing, as a dictionary mapping from variable names to values.</p>
<p>The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables recognized
by a plugin will be described in the manpage for that plugin.</p>
<dl class="doctools_definitions">
<dt>user</dt>
<dd><p>This variable is expected to contain the name of the user
owning the process invoking the plugin.</p></dd>
<dt>format</dt>
<dd><p>This variable is expected to contain the name of the
format whose plugin is invoked.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of the invokations of
the command <b class="cmd"><a href="../../../../index.html#import">import</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#url">url</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2018 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
|
<div class='fossil-doc' data-title='doctools::idx::import::json - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::import::json(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::import::json - JSON import plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">JSON notation of keyword indices</a></li>
<li class="doctools_section"><a href="#section4">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::import::json <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">json</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index import plugin for
the parsing of JSON markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_import.html">doctools::idx::import</a></b>, the import manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_import.html">doctools::idx::import</a></b> and the import manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx import plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the <i class="arg">string</i> and parses it as JSON
markup encoding a keyword index, in the context of the specified
<i class="arg">configuration</i> (a dictionary). The result of the command is the
canonical serialization of that keyword index, in the form specified
in section <span class="sectref"><a href="#section4">Keyword index serialization format</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">JSON notation of keyword indices</a></h2>
<p>The JSON format used for keyword indices is a direct translation of
the <span class="sectref"><a href="#section4">Keyword index serialization format</a></span>, mapping Tcl
dictionaries as JSON objects and Tcl lists as JSON arrays.
For example, the Tcl serialization</p>
<pre class="doctools_example">
doctools::idx {
label {Keyword Index}
keywords {
changelog {changelog.man cvs.man}
conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
cvs cvs.man
}
references {
apps/dtplite.man {manpage dtplite}
changelog.man {manpage doctools::changelog}
cvs.man {manpage doctools::cvs}
docidx.man {manpage doctools::idx}
doctoc.man {manpage doctools::toc}
doctools.man {manpage doctools}
mpexpand.man {manpage mpexpand}
}
title {}
}
</pre>
<p>is equivalent to the JSON string</p>
<pre class="doctools_example">
{
"doctools::idx" : {
"label" : "Keyword Index",
"keywords" : {
"changelog" : ["changelog.man","cvs.man"],
"conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
"cvs" : ["cvs.man"],
},
"references" : {
"apps\/dtplite.man" : ["manpage","dtplite"],
"changelog.man" : ["manpage","doctools::changelog"],
"cvs.man" : ["manpage","doctools::cvs"],
"docidx.man" : ["manpage","doctools::idx"],
"doctoc.man" : ["manpage","doctools::toc"],
"doctools.man" : ["manpage","doctools"],
"mpexpand.man" : ["manpage","mpexpand"]
},
"title" : ""
}
}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#deserialization">deserialization</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#index">index</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<div class='fossil-doc' data-title='doctools2idx_introduction - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools2idx_introduction(n) 2.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools2idx_introduction - DocTools - Keyword indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Related formats</a></li>
<li class="doctools_section"><a href="#section3">Package Overview</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#docidx">docidx</a></i> (short for <em>documentation indices</em>) stands for a
set of related, yet different, entities which are working together for
the easy creation and transformation of keyword indices for
documentation.</p>
<p>These are</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the semantic markup of a keyword index.
Markup is represented by Tcl commands.
Beginners should start with the
<i class="term"><a href="../doctools/docidx_lang_intro.html">docidx language introduction</a></i>.
The formal specification is split over two documents, one dealing with
the <i class="term"><a href="../doctools/docidx_lang_syntax.html">docidx language syntax</a></i>, the other a
<i class="term"><a href="../doctools/docidx_lang_cmdref.html">docidx language command reference</a></i>.</p></li>
<li><p>A set of packages for the programmatic manipulation of keyword indices
in memory, and their conversion between various formats, reading and
writing. The aforementioned markup language is one of the formats
which can be both read from and written to.</p></li>
<li><p>The system for the conversion of indices is based on a plugin
mechanism, for this we have two APIs describing the interface between
the packages above and the import/export plugins.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the documentation process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of documentation has to understand the markup language
itself. A beginner to docidx should read the more informally written
<i class="term"><a href="../doctools/docidx_lang_intro.html">docidx language introduction</a></i> first. Having digested this
the formal <i class="term"><a href="../doctools/docidx_lang_syntax.html">docidx language syntax</a></i> specification should
become understandable. A writer experienced with docidx may only
need the <i class="term"><a href="../doctools/docidx_lang_cmdref.html">docidx language command reference</a></i> from time to
time to refresh her memory.</p>
<p>While a document is written the <b class="syscmd">dtp</b> application can be used
to validate it, and after completion it also performs the conversion
into the chosen system of visual markup, be it *roff, HTML, plain
text, wiki, etc. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> application makes
internal use of docidx when handling directories of documentation,
automatically generating a proper keyword index for them.</p></li>
<li><p>A <i class="term">processor</i> of documentation written in the <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>
markup language has to know which tools are available for use.</p>
<p>The main tool is the aforementioned <b class="syscmd">dtp</b> application provided
by Tcllib. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does not expose docidx to the
user. At the bottom level, common to both applications, however we
find the three packages providing the basic facilities to handle
keyword indices, i.e. import from textual formats, programmatic
manipulation in memory, and export to textual formats. These are</p>
<dl class="doctools_definitions">
<dt><b class="package"><a href="idx_container.html">doctools::idx</a></b></dt>
<dd><p>Programmatic manipulation of keyword indices in memory.</p></dd>
<dt><b class="package"><a href="idx_import.html">doctools::idx::import</a></b></dt>
<dd><p>Import of keyword indices from various textual formats. The set of
supported formats is extensible through plugin packages.</p></dd>
<dt><b class="package"><a href="idx_export.html">doctools::idx::export</a></b></dt>
<dd><p>Export of keyword indices to various textual formats. The set of
supported formats is extensible through plugin packages.</p></dd>
</dl>
<p>See also section <span class="sectref"><a href="#section3">Package Overview</a></span> for an overview of the
dependencies between these and other, supporting packages.</p></li>
<li><p>At last, but not least, <i class="term">plugin writers</i> have to understand the
interaction between the import and export packages and their plugins.
These APIs are described in the documentation for the two relevant
packages, i.e.</p>
<ul class="doctools_itemized">
<li><p><b class="package"><a href="idx_import.html">doctools::idx::import</a></b></p></li>
<li><p><b class="package"><a href="idx_export.html">doctools::idx::export</a></b></p></li>
</ul>
</li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Related formats</a></h2>
<p>The docidx format does not stand alone, it has two companion formats.
These are called <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> and <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>, and they are
intended for the markup of <i class="term">tables of contents</i>, and of general
documentation, respectively.
They are described in their own sets of documents, starting at
the <i class="term">DocTools - Tables Of Contents</i> and
the <i class="term">DocTools - General</i>, respectively.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Package Overview</a></h2>
<pre class="doctools_example">
~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
~~ | ~~
doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
| | |
+---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+
| | | | | | | | |
doctools::config = | | | = doctools::include doctools::config doctools::paths
| | | | |
doctools::idx::export::<*> | | | doctools::idx::import::<*>
docidx | | | docidx, json
json | | | | \\
html | | | doctools::idx::parse \\
nroff | | | | \\
wiki | | | +---------------+ json
text | | | | |
doctools::idx::structure |
|
+-------+---------------+
| |
doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat
| |
doctools::text doctools::nroff::man_macros =
|
doctools::msgcat::idx::<*>
c, en, de, fr
(fr == en for now)
~~ Interoperable objects, without actual package dependencies
-- Package dependency, higher requires lower package
= Dynamic dependency through plugin system
<*> Multiple packages following the given form of naming.
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../doctools/docidx_intro.html">docidx_intro</a>, <a href="../doctools/doctoc_intro.html">doctoc_intro</a>, <a href="../doctools/doctools.html">doctools</a>, doctools2doc_introduction, <a href="../doctools2toc/toc_introduction.html">doctools2toc_introduction</a>, <a href="../doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="../doctools/doctools_lang_faq.html">doctools_lang_faq</a>, <a href="../doctools/doctools_lang_intro.html">doctools_lang_intro</a>, <a href="../doctools/doctools_lang_syntax.html">doctools_lang_syntax</a>, <a href="../doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#index">index</a>, <a href="../../../../index.html#keyword_index">keyword index</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::idx::c - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::idx::c(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::idx::c - Message catalog for the docidx parser (C)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::idx::c <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::idx::c</b> is a
support module providing the C language message catalog
for the docidx parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#c">C</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::idx::de - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::idx::de(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::idx::de - Message catalog for the docidx parser (DE)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::idx::de <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::idx::de</b> is a
support module providing the DE (german) language message catalog
for the docidx parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#de">DE</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::idx::en - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::idx::en(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::idx::en - Message catalog for the docidx parser (EN)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::idx::en <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::idx::en</b> is a
support module providing the EN (english) language message catalog
for the docidx parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#en">EN</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::idx::fr - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::idx::fr(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::idx::fr - Message catalog for the docidx parser (FR)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::idx::fr <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::idx::fr</b> is a
support module providing the FR (french) language message catalog
for the docidx parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fr">FR</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
|
<div class='fossil-doc' data-title='doctools::idx::parse - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::parse(n) 1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::parse - Parsing text in docidx format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Parse errors</a></li>
<li class="doctools_section"><a href="#section4">[docidx] notation of keyword indices</a></li>
<li class="doctools_section"><a href="#section5">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::idx::parse <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">doctools::msgcat</b></li>
<li>package require <b class="pkgname">doctools::tcl::parse</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::stack</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx::parse</b> <b class="method">text</b> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">::doctools::idx::parse</b> <b class="method">file</b> <i class="arg">path</i></a></li>
<li><a href="#3"><b class="cmd">::doctools::idx::parse</b> <b class="method">includes</b></a></li>
<li><a href="#4"><b class="cmd">::doctools::idx::parse</b> <b class="method">include add</b> <i class="arg">path</i></a></li>
<li><a href="#5"><b class="cmd">::doctools::idx::parse</b> <b class="method">include remove</b> <i class="arg">path</i></a></li>
<li><a href="#6"><b class="cmd">::doctools::idx::parse</b> <b class="method">include clear</b></a></li>
<li><a href="#7"><b class="cmd">::doctools::idx::parse</b> <b class="method">vars</b></a></li>
<li><a href="#8"><b class="cmd">::doctools::idx::parse</b> <b class="method">var set</b> <i class="arg">name</i> <i class="arg">value</i></a></li>
<li><a href="#9"><b class="cmd">::doctools::idx::parse</b> <b class="method">var unset</b> <i class="arg">name</i></a></li>
<li><a href="#10"><b class="cmd">::doctools::idx::parse</b> <b class="method">var clear</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to parse text written in the
<i class="term"><a href="../../../../index.html#docidx">docidx</a></i> markup language and convert it into the canonical
serialization of the keyword index encoded in the text.
See the section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span> for
specification of their format.</p>
<p>This is an internal package of doctools, for use by the higher level
packages handling <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> documents.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx::parse</b> <b class="method">text</b> <i class="arg">text</i></a></dt>
<dd><p>The command takes the string contained in <i class="arg">text</i> and parses it
under the assumption that it contains a document written using the
<i class="term"><a href="../../../../index.html#docidx">docidx</a></i> markup language. An error is thrown if this assumption
is found to be false. The format of these errors is described in
section <span class="sectref"><a href="#section3">Parse errors</a></span>.</p>
<p>When successful the command returns the canonical serialization of the
keyword index which was encoded in the text.
See the section <span class="sectref"><a href="#section5">Keyword index serialization format</a></span> for
specification of that format.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::idx::parse</b> <b class="method">file</b> <i class="arg">path</i></a></dt>
<dd><p>The same as <b class="method">text</b>, except that the text to parse is read from
the file specified by <i class="arg">path</i>.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::idx::parse</b> <b class="method">includes</b></a></dt>
<dd><p>This method returns the current list of search paths used when looking
for include files.</p></dd>
<dt><a name="4"><b class="cmd">::doctools::idx::parse</b> <b class="method">include add</b> <i class="arg">path</i></a></dt>
<dd><p>This method adds the <i class="arg">path</i> to the list of paths searched when
looking for an include file. The call is ignored if the path is
already in the list of paths. The method returns the empty string as
its result.</p></dd>
<dt><a name="5"><b class="cmd">::doctools::idx::parse</b> <b class="method">include remove</b> <i class="arg">path</i></a></dt>
<dd><p>This method removes the <i class="arg">path</i> from the list of paths searched
when looking for an include file. The call is ignored if the path is
not contained in the list of paths. The method returns the empty
string as its result.</p></dd>
<dt><a name="6"><b class="cmd">::doctools::idx::parse</b> <b class="method">include clear</b></a></dt>
<dd><p>This method clears the list of search paths for include files.</p></dd>
<dt><a name="7"><b class="cmd">::doctools::idx::parse</b> <b class="method">vars</b></a></dt>
<dd><p>This method returns a dictionary containing the current set of
predefined variables known to the <b class="cmd">vset</b> markup command during
processing.</p></dd>
<dt><a name="8"><b class="cmd">::doctools::idx::parse</b> <b class="method">var set</b> <i class="arg">name</i> <i class="arg">value</i></a></dt>
<dd><p>This method adds the variable <i class="arg">name</i> to the set of predefined
variables known to the <b class="cmd">vset</b> markup command during processing,
and gives it the specified <i class="arg">value</i>. The method returns the empty
string as its result.</p></dd>
<dt><a name="9"><b class="cmd">::doctools::idx::parse</b> <b class="method">var unset</b> <i class="arg">name</i></a></dt>
<dd><p>This method removes the variable <i class="arg">name</i> from the set of predefined
variables known to the <b class="cmd">vset</b> markup command during
processing. The method returns the empty string as its result.</p></dd>
<dt><a name="10"><b class="cmd">::doctools::idx::parse</b> <b class="method">var clear</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>This method removes all variables matching the <i class="arg">pattern</i> from the
set of predefined variables known to the <b class="cmd">vset</b> markup command
during processing. The method returns the empty string as its result.</p>
<p>The pattern matching is done with <b class="cmd">string match</b>, and the
default pattern used when none is specified, is <b class="const">*</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Parse errors</a></h2>
<p>The format of the parse error messages thrown when encountering
violations of the <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> markup syntax is human readable and
not intended for processing by machines. As such it is not documented.</p>
<p><em>However</em>, the errorCode attached to the message is
machine-readable and has the following format:</p>
<ol class="doctools_enumerated">
<li><p>The error code will be a list, each element describing a single error
found in the input. The list has at least one element, possibly more.</p></li>
<li><p>Each error element will be a list containing six strings describing an
error in detail. The strings will be</p>
<ol class="doctools_enumerated">
<li><p>The path of the file the error occurred in. This may be empty.</p></li>
<li><p>The range of the token the error was found at. This range is a
two-element list containing the offset of the first and last character
in the range, counted from the beginning of the input (file). Offsets
are counted from zero.</p></li>
<li><p>The line the first character after the error is on.
Lines are counted from one.</p></li>
<li><p>The column the first character after the error is at.
Columns are counted from zero.</p></li>
<li><p>The message code of the error. This value can be used as argument to
<b class="cmd">msgcat::mc</b> to obtain a localized error message, assuming that
the application had a suitable call of <b class="cmd">doctools::msgcat::init</b> to
initialize the necessary message catalogs (See package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b>).</p></li>
<li><p>A list of details for the error, like the markup command involved. In
the case of message code <b class="const">docidx/include/syntax</b> this value is
the set of errors found in the included file, using the format
described here.</p></li>
</ol>
</li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">[docidx] notation of keyword indices</a></h2>
<p>The docidx format for keyword indices, also called the
<i class="term">docidx markup language</i>, is too large to be covered in single
section.
The interested reader should start with the document</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/docidx_lang_intro.html">docidx language introduction</a></i></p></li>
</ol>
<p>and then proceed from there to the formal specifications, i.e. the
documents</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/docidx_lang_syntax.html">docidx language syntax</a></i> and</p></li>
<li><p><i class="term"><a href="../doctools/docidx_lang_cmdref.html">docidx language command reference</a></i>.</p></li>
</ol>
<p>to get a thorough understanding of the language.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#lexer">lexer</a>, <a href="../../../../index.html#parser">parser</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
<div class='fossil-doc' data-title='doctools::idx::structure - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::structure(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::structure - Docidx serialization utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::idx::structure <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::idx::structure</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::idx::structure</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></li>
<li><a href="#3"><b class="cmd">::doctools::idx::structure</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></li>
<li><a href="#4"><b class="cmd">::doctools::idx::structure</b> <b class="method">print</b> <i class="arg">serial</i></a></li>
<li><a href="#5"><b class="cmd">::doctools::idx::structure</b> <b class="method">merge</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to work with the serializations of
keyword indices as managed by the doctools system v2, and specified in
section <span class="sectref"><a href="#section3">Keyword index serialization format</a></span>.</p>
<p>This is an internal package of doctools, for use by the higher level
packages handling keyword indices and their conversion into and out of
various other formats, like documents written using <i class="term"><a href="../../../../index.html#docidx">docidx</a></i>
markup.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::idx::structure</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of a keyword index and will throw an
error if that is not the case. The result of the command is the empty
string.</p>
<p>If the argument <i class="arg">canonvar</i> is specified it is interpreted as the
name of a variable in the calling context. This variable will be
written to if and only if <i class="arg">serial</i> is a valid regular
serialization. Its value will be a boolean, with <b class="const">True</b>
indicating that the serialization is not only valid, but also
<i class="term">canonical</i>. <b class="const">False</b> will be written for a valid, but
non-canonical serialization.</p>
<p>For the specification of regular and canonical keyword index
serializations see the section
<span class="sectref"><a href="#section3">Keyword index serialization format</a></span>.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::idx::structure</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">canonical</i> serialization of a keyword index and will throw an
error if that is not the case. The result of the command is the empty
string.</p>
<p>For the specification of canonical keyword index serializations see
the section <span class="sectref"><a href="#section3">Keyword index serialization format</a></span>.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::idx::structure</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of a keyword index and will throw an
error if that is not the case.</p>
<p>It will then convert the input into the <i class="term">canonical</i> serialization
of the contained keyword index and return it as its result. If the
input is already canonical it will be returned unchanged.</p>
<p>For the specification of regular and canonical keyword index
serializations see the section
<span class="sectref"><a href="#section3">Keyword index serialization format</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::doctools::idx::structure</b> <b class="method">print</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the argument <i class="arg">serial</i> contains a valid
regular serialization of a keyword index and returns a string
containing that index in a human readable form.</p>
<p>The exact format of this form is not specified and cannot be relied on
for parsing or other machine-based activities.</p>
<p>For the specification of regular keyword index serializations see the
section <span class="sectref"><a href="#section3">Keyword index serialization format</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::doctools::idx::structure</b> <b class="method">merge</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></dt>
<dd><p>This command accepts the regular serializations of two keyword indices
and uses them to create their union. The result of the command is the
canonical serialization of this unified keyword index.</p>
<p>Title and label of the resulting index are taken from the index
contained in <i class="arg">serialb</i>. The set of keys, references and their
connections is the union of the set of keys and references of the two
inputs.</p>
<p>For the specification of regular and canonical keyword index
serializations see the section
<span class="sectref"><a href="#section3">Keyword index serialization format</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#deserialization">deserialization</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<div class='fossil-doc' data-title='doctools::idx::import::docidx - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::idx::import::docidx(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::idx::import::docidx - docidx import plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">[docidx] notation of keyword indices</a></li>
<li class="doctools_section"><a href="#section4">Keyword index serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::idx::import::docidx <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::idx::parse</b></li>
<li>package require <b class="pkgname">doctools::idx::structure</b></li>
<li>package require <b class="pkgname">doctools::msgcat</b></li>
<li>package require <b class="pkgname">doctools::tcl::parse</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">struct::stack</b></li>
<li>package require <b class="pkgname">struct::tree</b></li>
<li>package require <b class="pkgname">treeql</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools keyword index import plugin for
the parsing of docidx markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling keyword indices, especially <b class="package"><a href="idx_import.html">doctools::idx::import</a></b>, the import manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="idx_import.html">doctools::idx::import</a></b> and the import manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
docidx import plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the <i class="arg">string</i> and parses it as docidx
markup encoding a keyword index, in the context of the specified
<i class="arg">configuration</i> (a dictionary). The result of the command is the
canonical serialization of that keyword index, in the form specified
in section <span class="sectref"><a href="#section4">Keyword index serialization format</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">[docidx] notation of keyword indices</a></h2>
<p>The docidx format for keyword indices, also called the
<i class="term">docidx markup language</i>, is too large to be covered in single
section.
The interested reader should start with the document</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/docidx_lang_intro.html">docidx language introduction</a></i></p></li>
</ol>
<p>and then proceed from there to the formal specifications, i.e. the
documents</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/docidx_lang_syntax.html">docidx language syntax</a></i> and</p></li>
<li><p><i class="term"><a href="../doctools/docidx_lang_cmdref.html">docidx language command reference</a></i>.</p></li>
</ol>
<p>to get a thorough understanding of the language.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Keyword index serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize keyword indices as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations. While a keyword index may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>An index serialization is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::idx</b>, and its
value. This value holds the contents of the index.</p></li>
<li><p>The contents of the index are a Tcl dictionary holding the title of
the index, a label, and the keywords and references. The relevant keys
and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the index.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the index.</p></dd>
<dt><b class="const">keywords</b></dt>
<dd><p>The value is a Tcl dictionary, using the keywords known to the index
as keys. The associated values are lists containing the identifiers of
the references associated with that particular keyword.</p>
<p>Any reference identifier used in these lists has to exist as a key in
the <b class="const">references</b> dictionary, see the next item for its
definition.</p></dd>
<dt><b class="const">references</b></dt>
<dd><p>The value is a Tcl dictionary, using the identifiers for the
references known to the index as keys. The associated values are
2-element lists containing the type and label of the reference, in
this order.</p>
<p>Any key here has to be associated with at least one keyword,
i.e. occur in at least one of the reference lists which are the values
in the <b class="const">keywords</b> dictionary, see previous item for its
definition.</p></dd>
</dl>
</li>
<li><p>The <i class="term"><a href="../../../../index.html#type">type</a></i> of a reference can be one of two values,</p>
<dl class="doctools_definitions">
<dt><b class="const">manpage</b></dt>
<dd><p>The identifier of the reference is interpreted as symbolic file name,
referring to one of the documents the index was made for.</p></dd>
<dt><b class="const">url</b></dt>
<dd><p>The identifier of the reference is interpreted as an url, referring to
some external location, like a website, etc.</p></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a keyword index has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of the keyword index.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The references listed for each keyword of the index, if any, are
listed in ascending dictionary order of their <em>labels</em>, as
generated by Tcl's builtin command <b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#deserialization">deserialization</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#index">index</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
|
<div class='fossil-doc' data-title='doctools::toc::export::doctoc - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export::doctoc(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export::doctoc - doctoc export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">[doctoc] notation of tables of contents</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::export::doctoc <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents export plugin
for the generation of doctoc markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_export.html">doctools::toc::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_export.html">doctools::toc::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a table of contents,
as specified in section <span class="sectref"><a href="#section5">ToC serialization format</a></span>, and
contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary, and
generates doctoc markup encoding the table.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">[doctoc] notation of tables of contents</a></h2>
<p>The doctoc format for tables of contents, also called the
<i class="term">doctoc markup language</i>, is too large to be covered in single
section.
The interested reader should start with the document</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/doctoc_lang_intro.html">doctoc language introduction</a></i></p></li>
</ol>
<p>and then proceed from there to the formal specifications, i.e. the
documents</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/doctoc_lang_syntax.html">doctoc language syntax</a></i> and</p></li>
<li><p><i class="term"><a href="../doctools/doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p></li>
</ol>
<p>to get a thorough understanding of the language.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>The doctoc export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">user</i></dt>
<dd><p>This standard configuration variable contains the name of the user
running the process which invoked the export plugin.
The plugin puts this information into the provenance comment at the
beginning of the generated document.</p></dd>
<dt>string <i class="arg">file</i></dt>
<dd><p>This standard configuration variable contains the name of the file the
table of contents came from. This variable may not be set or contain
the empty string.
The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the
generated document.</p></dd>
<dt>boolean <i class="arg">newlines</i></dt>
<dd><p>If this flag is set the plugin will break the generated doctoc code
across lines, with each markup command on a separate line.</p>
<p>If this flag is not set (the default), the whole document will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will indent the markup commands
according to the structure of tables of contents. To make this work
this also implies that <b class="variable">newlines</b> is set. This effect is
independent of the value for <b class="variable">aligned</b> however.</p>
<p>If this flag is not set (the default), the output is formatted as per
the value of <b class="variable">newlines</b>, and no indenting is done.</p></dd>
<dt>boolean <i class="arg">aligned</i></dt>
<dd><p>If this flag is set the generator ensures that the arguments for the
<b class="cmd">item</b> commands in a division are aligned vertically for a nice
table effect. To make this work this also implies that <b class="variable">newlines</b>
is set. This effect is independent of the value for <b class="variable">indented</b>
however.</p>
<p>If this flag is not set (the default), the output is formatted as per
the values of <b class="variable">newlines</b> and <b class="variable">indented</b>, and no alignment is
done.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">format</b>, and <b class="variable">map</b>, and their values.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<div class='fossil-doc' data-title='doctools::toc::import::doctoc - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::import::doctoc(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::import::doctoc - doctoc import plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">[doctoc] notation of tables of contents</a></li>
<li class="doctools_section"><a href="#section4">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::import::doctoc <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::toc::parse</b></li>
<li>package require <b class="pkgname">doctools::toc::structure</b></li>
<li>package require <b class="pkgname">doctools::msgcat</b></li>
<li>package require <b class="pkgname">doctools::tcl::parse</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">struct::stack</b></li>
<li>package require <b class="pkgname">struct::tree</b></li>
<li>package require <b class="pkgname">treeql</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents import plugin
for the parsing of doctoc markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_import.html">doctools::toc::import</a></b>, the import manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_import.html">doctools::toc::import</a></b> and the import manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc import plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the <i class="arg">string</i> and parses it as doctoc
markup encoding a table of contents, in the context of the specified
<i class="arg">configuration</i> (a dictionary). The result of the command is the
canonical serialization of that table of contents, in the form
specified in section <span class="sectref"><a href="#section4">ToC serialization format</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">[doctoc] notation of tables of contents</a></h2>
<p>The doctoc format for tables of contents, also called the
<i class="term">doctoc markup language</i>, is too large to be covered in single
section.
The interested reader should start with the document</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/doctoc_lang_intro.html">doctoc language introduction</a></i></p></li>
</ol>
<p>and then proceed from there to the formal specifications, i.e. the
documents</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/doctoc_lang_syntax.html">doctoc language syntax</a></i> and</p></li>
<li><p><i class="term"><a href="../doctools/doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p></li>
</ol>
<p>to get a thorough understanding of the language.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#deserialization">deserialization</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
|
<div class='fossil-doc' data-title='doctools::toc - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc(n) 2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc - Holding tables of contents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::toc <span class="opt">?2?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::structure</b></li>
<li>package require <b class="pkgname">struct::tree</b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::toc</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">+ reference</b> <i class="arg">id</i> <i class="arg">label</i> <i class="arg">docid</i> <i class="arg">desc</i></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">+ division</b> <i class="arg">id</i> <i class="arg">label</i> <span class="opt">?<i class="arg">docid</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">remove</b> <i class="arg">id</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">up</b> <i class="arg">id</i></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">next</b> <i class="arg">id</i></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">prev</b> <i class="arg">id</i></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">child</b> <i class="arg">id</i> <i class="arg">label</i> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">element</b> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">children</b> <i class="arg">id</i></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">type</b> <i class="arg">id</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">full-label</b> <i class="arg">id</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">elabel</b> <i class="arg">id</i> <span class="opt">?<i class="arg">newlabel</i>?</span></a></li>
<li><a href="#16"><i class="arg">objectName</i> <b class="method">description</b> <i class="arg">id</i> <span class="opt">?<i class="arg">newdesc</i>?</span></a></li>
<li><a href="#17"><i class="arg">objectName</i> <b class="method">document</b> <i class="arg">id</i> <span class="opt">?<i class="arg">newdocid</i>?</span></a></li>
<li><a href="#18"><i class="arg">objectName</i> <b class="method">title</b></a></li>
<li><a href="#19"><i class="arg">objectName</i> <b class="method">title</b> <i class="arg">text</i></a></li>
<li><a href="#20"><i class="arg">objectName</i> <b class="method">label</b></a></li>
<li><a href="#21"><i class="arg">objectName</i> <b class="method">label</b> <i class="arg">text</i></a></li>
<li><a href="#22"><i class="arg">objectName</i> <b class="method">importer</b></a></li>
<li><a href="#23"><i class="arg">objectName</i> <b class="method">importer</b> <i class="arg">object</i></a></li>
<li><a href="#24"><i class="arg">objectName</i> <b class="method">exporter</b></a></li>
<li><a href="#25"><i class="arg">objectName</i> <b class="method">exporter</b> <i class="arg">object</i></a></li>
<li><a href="#26"><i class="arg">objectName</i> <b class="method">deserialize =</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#27"><i class="arg">objectName</i> <b class="method">deserialize +=</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#28"><i class="arg">objectName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">format</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to contain and programmatically
manipulate tables of contents.</p>
<p>This is one of the three public pillars the management of tables of
contents resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="toc_export.html">Exporting tables of contents</a></i>, and</p></li>
<li><p><i class="term">Importing tables of contents</i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of tables of contents, and
their parts, see the same-named section.
For information about the data structure which is used to encode
tables of contents as values see the section
<span class="sectref"><a href="#section4">ToC serialization format</a></span>.
This is the only format directly known to this class. Conversions from
and to any other format are handled by export and import manager
objects. These may be attached to a container, but do not have to be,
it is merely a convenience.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#table_of_contents">table of contents</a></i> consists of a (possibly empty) list of
<i class="term">elements</i>.</p></li>
<li><p>Each element in the list is identified by its label.</p></li>
<li><p>Each element is either a <i class="term"><a href="../../../../index.html#reference">reference</a></i>, or a <i class="term">division</i>.</p></li>
<li><p>Each reference has an associated document, identified by a symbolic
id, and a textual description.</p></li>
<li><p>Each division may have an associated document, identified by a
symbolic id.</p></li>
<li><p>Each division consists consists of a (possibly empty) list of
<i class="term">elements</i>, with each element following the rules as specified in
item 2 and above.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>The above rules span up a tree of elements, with references as the
leaf nodes, and divisions as the inner nodes, and each element
representing an entry in the whole table of contents.</p></li>
<li><p>The identifying labels of any element E are unique within their
division (or toc), and the full label of any element E is the list of
labels for all nodes on the unique path from the root of the tree to
E, including E.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::toc</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new container object with an associated Tcl
command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command is
explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::toc</b> command have the
following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">+ reference</b> <i class="arg">id</i> <i class="arg">label</i> <i class="arg">docid</i> <i class="arg">desc</i></a></dt>
<dd><p>This method adds a new reference element to the table of contents,
under the element specified via its handle <i class="arg">id</i>. This parent
element has to be a division element, or the root. An error is thrown
otherwise.
The new element will be externally identified by its <i class="arg">label</i>,
which has to be be unique within the parent element. An error is
thrown otherwise.</p>
<p>As a reference element it will refer to a document identified by the
symbolic <i class="arg">docid</i>. This reference must not be the empty string, an
error is thrown otherwise.
Beyond the label the element also has a longer descriptive string,
supplied via <i class="arg">desc</i>.</p>
<p>The result of the method is the handle (id) of the new element.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">+ division</b> <i class="arg">id</i> <i class="arg">label</i> <span class="opt">?<i class="arg">docid</i>?</span></a></dt>
<dd><p>This method adds a new division element to the table of contents,
under the element specified via its handle <i class="arg">id</i>. This parent
element has to be a division element, or the root. An error is thrown
otherwise.
The new element will be externally identified by its <i class="arg">label</i>,
which has to be be unique within the parent element. An error is
thrown otherwise.</p>
<p>As a division element it is can refer to a document, identified by the
symbolic <i class="arg">docid</i>, but may choose not to.</p>
<p>The result of the method is the handle (id) of the new element.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">remove</b> <i class="arg">id</i></a></dt>
<dd><p>This method removes the element identified by the handle <i class="arg">id</i> from
the table of contents.
If the element is a division all of its children, if any, are removed
as well. The root element/division of the table of contents cannot be
removed however, only its children.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">up</b> <i class="arg">id</i></a></dt>
<dd><p>This method returns the handle of the parent for the element
identified by its handle <i class="arg">id</i>, or the empty string if <i class="arg">id</i>
referred to the root element.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">next</b> <i class="arg">id</i></a></dt>
<dd><p>This method returns the handle of the right sibling for the element
identified by its handle <i class="arg">id</i>, or the handle of the parent if the
element has no right sibling, or the empty string if <i class="arg">id</i> referred
to the root element.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">prev</b> <i class="arg">id</i></a></dt>
<dd><p>This method returns the handle of the left sibling for the element
identified by its handle <i class="arg">id</i>, or the handle of the parent if the
element has no left sibling, or the empty string if <i class="arg">id</i> referred
to the root element.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">child</b> <i class="arg">id</i> <i class="arg">label</i> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>This method returns the handle of a child of the element identified by
its handle <i class="arg">id</i>. The child itself is identified by a series of
labels.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">element</b> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>This method returns the handle of the element identified by a series
of labels, starting from the root of the table of contents. The series
of labels is allowed to be empty, in which case the handle of the root
element is returned.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">children</b> <i class="arg">id</i></a></dt>
<dd><p>This method returns a list containing the handles of all children of
the element identified by the handle <i class="arg">id</i>, from first to last, in
that order.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">type</b> <i class="arg">id</i></a></dt>
<dd><p>This method returns the type of the element, either <b class="const">reference</b>,
or <b class="const">division</b>.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">full-label</b> <i class="arg">id</i></a></dt>
<dd><p>This method is the complement of the method <b class="method">element</b>,
converting the handle <i class="arg">id</i> of an element into a list of labels
full identifying the element within the whole table of contents.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">elabel</b> <i class="arg">id</i> <span class="opt">?<i class="arg">newlabel</i>?</span></a></dt>
<dd><p>This method queries and/or changes the label of the element identified
by the handle <i class="arg">id</i>. If the argument <i class="arg">newlabel</i> is present then
the label is changed to that value. Regardless of this, the result of
the method is the current value of the label.</p>
<p>If the label is changed the new label has to be unique within the
containing division, or an error is thrown.</p>
<p>Further, of the <i class="arg">id</i> refers to the root element of the table of
contents, then using this method is equivalent to using the method
<i class="arg">label</i>, i.e. it is accessing the global label for the whole
table.</p></dd>
<dt><a name="16"><i class="arg">objectName</i> <b class="method">description</b> <i class="arg">id</i> <span class="opt">?<i class="arg">newdesc</i>?</span></a></dt>
<dd><p>This method queries and/or changes the description of the element
identified by the handle <i class="arg">id</i>. If the argument <i class="arg">newdesc</i> is
present then the description is changed to that value. Regardless of
this, the result of the method is the current value of the description.</p>
<p>The element this method operates on has to be a reference element, or
an error will be thrown.</p></dd>
<dt><a name="17"><i class="arg">objectName</i> <b class="method">document</b> <i class="arg">id</i> <span class="opt">?<i class="arg">newdocid</i>?</span></a></dt>
<dd><p>This method queries and/or changes the document reference of the
element identified by the handle <i class="arg">id</i>.
If the argument <i class="arg">newdocid</i> is present then the description is
changed to that value. Regardless of this, the result of the method is
the current value of the document reference.</p>
<p>Setting the reference to the empty string means unsetting it, and is
allowed only for division elements. Conversely, if the result is the
empty string then the element has no document reference, and this can
happen only for division elements.</p></dd>
<dt><a name="18"><i class="arg">objectName</i> <b class="method">title</b></a></dt>
<dd><p>Returns the currently defined title of the table of contents.</p></dd>
<dt><a name="19"><i class="arg">objectName</i> <b class="method">title</b> <i class="arg">text</i></a></dt>
<dd><p>Sets the title of the table of contents to <i class="arg">text</i>, and returns it as
the result of the command.</p></dd>
<dt><a name="20"><i class="arg">objectName</i> <b class="method">label</b></a></dt>
<dd><p>Returns the currently defined label of the table of contents.</p></dd>
<dt><a name="21"><i class="arg">objectName</i> <b class="method">label</b> <i class="arg">text</i></a></dt>
<dd><p>Sets the label of the table of contents to <i class="arg">text</i>, and returns it as
the result of the command.</p></dd>
<dt><a name="22"><i class="arg">objectName</i> <b class="method">importer</b></a></dt>
<dd><p>Returns the import manager object currently attached to the container,
if any.</p></dd>
<dt><a name="23"><i class="arg">objectName</i> <b class="method">importer</b> <i class="arg">object</i></a></dt>
<dd><p>Attaches the <i class="arg">object</i> as import manager to the container, and
returns it as the result of the command.
Note that the <i class="arg">object</i> is <em>not</em> put into ownership of the
container. I.e., destruction of the container will <em>not</em> destroy
the <i class="arg">object</i>.</p>
<p>It is expected that <i class="arg">object</i> provides a method named
<b class="method">import text</b> which takes a text and a format name, and
returns the canonical serialization of the table of contents contained in
the text, assuming the given format.</p></dd>
<dt><a name="24"><i class="arg">objectName</i> <b class="method">exporter</b></a></dt>
<dd><p>Returns the export manager object currently attached to the container,
if any.</p></dd>
<dt><a name="25"><i class="arg">objectName</i> <b class="method">exporter</b> <i class="arg">object</i></a></dt>
<dd><p>Attaches the <i class="arg">object</i> as export manager to the container, and
returns it as the result of the command.
Note that the <i class="arg">object</i> is <em>not</em> put into ownership of the
container. I.e., destruction of the container will <em>not</em> destroy
the <i class="arg">object</i>.</p>
<p>It is expected that <i class="arg">object</i> provides a method named
<b class="method">export object</b> which takes the container and a format name,
and returns a text encoding table of contents stored in the container, in
the given format. It is further expected that the <i class="arg">object</i> will
use the container's method <b class="method">serialize</b> to obtain the
serialization of the table of contents from which to generate the text.</p></dd>
<dt><a name="26"><i class="arg">objectName</i> <b class="method">deserialize =</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method replaces the contents of the table object with the table
contained in the <i class="arg">data</i>. If no <i class="arg">format</i> was specified it is
assumed to be the regular serialization of a table of contents.</p>
<p>Otherwise the object will use the attached import manager to convert
the data from the specified format to a serialization it can handle.
In that case an error will be thrown if the container has no import
manager attached to it.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="27"><i class="arg">objectName</i> <b class="method">deserialize +=</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">deserialize =</b> in its essentials,
except that it merges the table of contents in the <i class="arg">data</i> to its
contents instead of replacing it.
The method will throw an error if merging is not possible, i.e. would
produce an invalid table. The existing content is left unchanged in
that case.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="28"><i class="arg">objectName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method returns the table of contents contained in the object. If no
<i class="arg">format</i> is not specified the returned result is the canonical
serialization of its contents.</p>
<p>Otherwise the object will use the attached export manager to convert
the data to the specified format.
In that case an error will be thrown if the container has no export
manager attached to it.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#doctoc_markup">doctoc markup</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#generation">generation</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#latex">latex</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#table">table</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#tcler_s_wiki">tcler's wiki</a>, <a href="../../../../index.html#text">text</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_export.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
|
<div class='fossil-doc' data-title='doctools::toc::export - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export - Exporting tables of contents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Export plugin API v2 reference</a></li>
<li class="doctools_section"><a href="#section5">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::toc::export <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::config</b></li>
<li>package require <b class="pkgname">doctools::toc::structure</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::toc::export</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">export serial</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">export object</b> <i class="arg">object</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">config names</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">config get</b></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></li>
<li><a href="#10"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to manage the plugins for the export of
tables of contents to other formats, i.e. their conversion to, for
example <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>, <i class="term"><a href="../../../../index.html#html">HTML</a></i>, etc.</p>
<p>This is one of the three public pillars the management of tables of
contents resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term">Importing tables of contents</i>, and</p></li>
<li><p><i class="term"><a href="toc_container.html">Holding tables of contents</a></i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of tables of contents,
and their parts, see the same-named section.
For information about the data structure which is the major input to
the manager objects provided by this package see the section
<span class="sectref"><a href="#section5">ToC serialization format</a></span>.</p>
<p>The plugin system of our class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">DOCTOOLS_TOC_EXPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_TOC_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/export/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/export/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\EXPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using Windows(tm) operating system.</p>
<p>The whole system is delivered with six predefined export plugins,
namely</p>
<dl class="doctools_definitions">
<dt>doctoc</dt>
<dd><p>See <i class="term"><a href="export_doctoc.html">doctoc export plugin</a></i> for details.</p></dd>
<dt>html</dt>
<dd><p>See <i class="term">html export plugin</i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">json export plugin</i> for details.</p></dd>
<dt>nroff</dt>
<dd><p>See <i class="term"><a href="../doctools2idx/idx_export_nroff.html">nroff export plugin</a></i> for details.</p></dd>
<dt>text</dt>
<dd><p>See <i class="term">text export plugin</i> for details.</p></dd>
<dt>wiki</dt>
<dd><p>See <i class="term"><a href="../doctools2idx/idx_export_wiki.html">wiki export plugin</a></i> for details.</p></dd>
</dl>
<p>Readers wishing to write their own export plugin for some format, i.e.
<i class="term">plugin writer</i>s reading and understanding the section
containing the <span class="sectref"><a href="#section4">Export plugin API v2 reference</a></span> is an
absolute necessity, as it specifies the interaction between this
package and its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#table_of_contents">table of contents</a></i> consists of a (possibly empty) list of
<i class="term">elements</i>.</p></li>
<li><p>Each element in the list is identified by its label.</p></li>
<li><p>Each element is either a <i class="term"><a href="../../../../index.html#reference">reference</a></i>, or a <i class="term">division</i>.</p></li>
<li><p>Each reference has an associated document, identified by a symbolic
id, and a textual description.</p></li>
<li><p>Each division may have an associated document, identified by a
symbolic id.</p></li>
<li><p>Each division consists consists of a (possibly empty) list of
<i class="term">elements</i>, with each element following the rules as specified in
item 2 and above.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>The above rules span up a tree of elements, with references as the
leaf nodes, and divisions as the inner nodes, and each element
representing an entry in the whole table of contents.</p></li>
<li><p>The identifying labels of any element E are unique within their
division (or toc), and the full label of any element E is the list of
labels for all nodes on the unique path from the root of the tree to
E, including E.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::toc::export</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new export manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::toc::export</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">export serial</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the canonical serialization of a table of contents
stored in <i class="arg">serial</i> and converts it to the specified <i class="arg">format</i>,
using the export plugin for the format. An error is thrown if no
plugin could be found for the format.
The string generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">doctoc</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">ToC serialization format</a></span>.</p>
<p>The plugin has to conform to the interface specified in section
<span class="sectref"><a href="#section4">Export plugin API v2 reference</a></span>.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">export object</b> <i class="arg">object</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">export serial</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">serialize</b> method returning the canonical serialization of a
table of contents. It invokes that method, feeds the result into
<b class="method">export serial</b> and returns the resulting string as its own
result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">config names</b></a></dt>
<dd><p>This method returns a list containing the names of all configuration
variables currently known to the object.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">config get</b></a></dt>
<dd><p>This method returns a dictionary containing the names and values of
all configuration variables currently known to the object.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>This method sets the configuration variable <i class="arg">name</i> to the
specified <i class="arg">value</i> and returns the new value of the variable.</p>
<p>If no value is specified it simply returns the current value, without
changing it.</p>
<p>Note that while the user can set the predefined configuration
variables <b class="const">user</b> and <b class="const">format</b> doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></dt>
<dd><p>This method unsets all configuration variables matching the specified
glob <i class="arg">pattern</i>s. If no pattern is specified it will unset all
currently defined configuration variables.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Export plugin API v2 reference</a></h2>
<p>Plugins are what this package uses to manage the support for any
output format beyond the <span class="sectref"><a href="#section5">ToC serialization format</a></span>. Here we
specify the API the objects created by this package use to interact
with their plugins.</p>
<p>A plugin for this package has to follow the rules listed below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
doctools::toc::export::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
generate output for. This name is also the argument to provide
to the various <b class="method">export</b> methods of export manager
objects to get a string encoding a table of contents in that
format.</p></li>
<li><p>The plugin can expect that the package
<b class="package">doctools::toc::export::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p></li>
<li><p>A plugin has to provide one command, with the signature shown
below.</p>
<dl class="doctools_definitions">
<dt><a name="10"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>Whenever an export manager of <b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b> has to generate
output for a table of contents it will invoke this command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">serial</i></dt>
<dd><p>This argument will contain the <i class="term">canonical</i> serialization of the
table of contents for which to generate the output.
The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">ToC serialization format</a></span>.</p></dd>
<dt>dictionary <i class="arg">configuration</i></dt>
<dd><p>This argument will contain the current configuration to apply to the
generation, as a dictionary mapping from variable names to values.</p>
<p>The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables recognized
by a plugin will be described in the manpage for that plugin.</p>
<dl class="doctools_definitions">
<dt>user</dt>
<dd><p>This variable is expected to contain the name of the user
owning the process invoking the plugin.</p></dd>
<dt>format</dt>
<dd><p>This variable is expected to contain the name of the
format whose plugin is invoked.</p></dd>
<dt>file</dt>
<dd><p>This variable, if defined by the user of the table object
is expected to contain the name of the input file for which
the plugin is generating its output for.</p></dd>
<dt>map</dt>
<dd><p>This variable, if defined by the user of the table object is
expected to contain a dictionary mapping from symbolic
document ids used in the table entries to actual paths (or
urls). A plugin has to be able to handle the possibility
that a document id is without entry in this mapping.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of the invokations of
the command <b class="cmd"><a href="../../../../index.html#export">export</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#generation">generation</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#table">table</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#tcler_s_wiki">tcler's wiki</a>, <a href="../../../../index.html#text">text</a>, <a href="../../../../index.html#url">url</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2018 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
|
<div class='fossil-doc' data-title='doctools::toc::export::html - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export::html(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export::html - HTML export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::export::html <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
<li>package require <b class="pkgname">doctools::html</b></li>
<li>package require <b class="pkgname">doctools::html::cssdefaults</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents export plugin
for the generation of HTML markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_export.html">doctools::toc::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_export.html">doctools::toc::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a table of contents,
as specified in section <span class="sectref"><a href="#section4">ToC serialization format</a></span>, and
contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary, and
generates HTML markup encoding the table.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The html export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">user</i></dt>
<dd><p>This standard configuration variable contains the name of the user
running the process which invoked the export plugin.
The plugin puts this information into the provenance comment at the
beginning of the generated document.</p></dd>
<dt>string <i class="arg">file</i></dt>
<dd><p>This standard configuration variable contains the name of the file the
table of contents came from. This variable may not be set or contain
the empty string.
The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the
generated document.</p></dd>
<dt>dictionary <i class="arg">map</i></dt>
<dd><p>This standard configuration variable contains a dictionary mapping
from the (symbolic) document ids in reference entries to the actual
filenames and/or urls to be used in the output.</p>
<p>Document ids without a mapping are used unchanged.</p></dd>
<dt>boolean <i class="arg">newlines</i></dt>
<dd><p>If this flag is set the plugin will break the generated html code
across lines, with each markup command on a separate line.</p>
<p>If this flag is not set (the default), the whole document will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will indent the markup commands
according to the structure of indices. To make this work this also
implies that <b class="variable">newlines</b> is set.</p>
<p>If this flag is not set (the default), the output is formatted as per
the value of <b class="variable">newlines</b>, and no indenting is done.</p></dd>
<dt>string <i class="arg">meta</i></dt>
<dd><p>This variable is meant to hold a fragment of HTML (default: empty).
The fragment it contains will be inserted into the generated output in
the <head> section of the document, just after the <title> tag.</p></dd>
<dt>string <i class="arg">header</i></dt>
<dd><p>This variable is meant to hold a fragment of HTML (default: empty).
The fragment it contains will be inserted into the generated output
just after the <h1> title tag in the body of the document, in the
class.header <div>'ision.</p></dd>
<dt>string <i class="arg">footer</i></dt>
<dd><p>This variable is meant to hold a fragment of HTML (default:
empty). The fragment it contains will be inserted into the generated
output just before the </body> tag, in the class.footer <div>'ision.</p></dd>
<dt>dictionary <i class="arg">rid</i></dt>
<dd><p>The value of this variable (default: empty) maps references to the
identifiers to use as their anchor names. Each reference <b class="variable">FOO</b> not
found in the dictionary uses <b class="const">REF-</b><b class="variable">FOO</b> as anchor,
i.e. itself prefixed with the string <b class="const">REF-</b>.</p></dd>
<dt>string <i class="arg">sepline</i></dt>
<dd><p>The value of this variable is the string to use for the separator
comments inserted into the output when the outpout is broken across
lines and/or indented. The default string consists of 60 dashes.</p></dd>
<dt>string <i class="arg">class.main</i></dt>
<dd><p>This variable contains the class name for the main <div>'ivision of
the generated document. The default is <b class="const">doctools</b>.</p></dd>
<dt>string <i class="arg">class.header</i></dt>
<dd><p>This variable contains the class name for the header <div>'ision of
the generated document. The default is <b class="const">toc-header</b>. This
division contains the document title, the user specified <b class="variable">header</b>,
if any, and a visible separator line.</p></dd>
<dt>string <i class="arg">class.title</i></dt>
<dd><p>This variable contains the class name for the <h1> tag enclosing the
document title. The default is <b class="const">toc-title</b>.</p></dd>
<dt>string <i class="arg">class.navsep</i></dt>
<dd><p>This variable contains the class name for the <hr> separators in the
header and footer sections of the generated document. The default is
<b class="const">toc-navsep</b>.</p></dd>
<dt>string <i class="arg">class.contents</i></dt>
<dd><p>This variable contains the class name for the XXXXX holding the
keywords and their references in the generated document. The default
is <b class="const">toc-contents</b>.</p></dd>
<dt>string <i class="arg">class.ref</i></dt>
<dd><p>This variable contains the class name for the table elements which are
references to other documents. The default is <b class="const">toc-ref</b>.</p></dd>
<dt>string <i class="arg">class.div</i></dt>
<dd><p>This variable contains the class name for the table elements which are
divisions. The default is <b class="const">toc-div</b>.</p></dd>
<dt>string <i class="arg">class.footer</i></dt>
<dd><p>This variable contains the class name for the footer <div>'ision of
the generated document. The default is <b class="const">toc-footer</b>. This
division contains a browser-visible separator line and the user
specified <b class="variable">footer</b>, if any.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variable <b class="variable">format</b>, and its value.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
<div class='fossil-doc' data-title='doctools::toc::export::json - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export::json(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export::json - JSON export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">JSON notation of tables of contents</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::export::json <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">textutil::adjust</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents export plugin
for the generation of JSON markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_export.html">doctools::toc::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_export.html">doctools::toc::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a table of contents,
as specified in section <span class="sectref"><a href="#section5">ToC serialization format</a></span>, and
contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary, and
generates JSON markup encoding the table.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">JSON notation of tables of contents</a></h2>
<p>The JSON format used for tables of contents is a direct translation of
the <span class="sectref"><a href="#section5">ToC serialization format</a></span>, mapping Tcl dictionaries as
JSON objects and Tcl lists as JSON arrays.
For example, the Tcl serialization</p>
<pre class="doctools_example">
doctools::toc {
items {
{reference {
desc {DocTools - Tables of Contents}
id introduction.man
label doctools::toc::introduction
}}
{division {
id processing.man
items {
{reference {
desc {doctoc serialization utilities}
id structure.man
label doctools::toc::structure
}}
{reference {
desc {Parsing text in doctoc format}
id parse.man
label doctools::toc::parse
}}
}
label Processing
}}
}
label {Table of Contents}
title TOC
}
</pre>
<p>is equivalent to the JSON string</p>
<pre class="doctools_example">
{
"doctools::toc" : {
"items" : [{
"reference" : {
"desc" : "DocTools - Tables of Contents",
"id" : "introduction.man",
"label" : "doctools::toc::introduction"
}
},{
"division" : {
"id" : "processing.man",
"items" : [{
"reference" : {
"desc" : "doctoc serialization utilities",
"id" : "structure.man",
"label" : "doctools::toc::structure"
}
},{
"reference" : {
"desc" : "Parsing text in doctoc format",
"id" : "parse.man",
"label" : "doctools::toc::parse"
}
}],
"label" : "Processing"
}
}],
"label" : "Table of Contents",
"title" : "TOC"
}
}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>The JSON export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will break the generated JSON code
across lines and indent it according to its inner structure, with each
key of a dictionary on a separate line.</p>
<p>If this flag is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">aligned</i></dt>
<dd><p>If this flag is set the generator ensures that the values for the keys
in a dictionary are vertically aligned with each other, for a nice
table effect. To make this work this also implies that <b class="variable">indented</b>
is set.</p>
<p>If this flag is not set (the default), the output is formatted as per
the value of <b class="variable">indented</b>, without trying to align the values for
dictionary keys.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">format</b>, <b class="variable">file</b>, and <b class="variable">map</b> and
their values.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<div class='fossil-doc' data-title='doctools::toc::export::nroff - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export::nroff(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export::nroff - nroff export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::export::nroff <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
<li>package require <b class="pkgname">doctools::nroff::man_macros</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents export plugin
for the generation of nroff markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_export.html">doctools::toc::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_export.html">doctools::toc::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a table of contents,
as specified in section <span class="sectref"><a href="#section4">ToC serialization format</a></span>, and
contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary, and
generates nroff markup encoding the table.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The nroff export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">user</i></dt>
<dd><p>This standard configuration variable contains the name of the user
running the process which invoked the export plugin.
The plugin puts this information into the provenance comment at the
beginning of the generated document.</p></dd>
<dt>string <i class="arg">file</i></dt>
<dd><p>This standard configuration variable contains the name of the file the
table of contents came from. This variable may not be set or contain
the empty string.
The plugin puts this information, if defined, i.e. set and not the
empty string, into the provenance comment at the beginning of the
generated document.</p></dd>
<dt>boolean <i class="arg">inline</i></dt>
<dd><p>If this flag is set (default) the plugin will place the definitions of
the man macro set directly into the output.</p>
<p>If this flag is not set, the plugin will place a reference to the
definitions of the man macro set into the output, but not the macro
definitions themselves.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">format</b>, and <b class="variable">map</b>, and their values.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#nroff">nroff</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
<div class='fossil-doc' data-title='doctools::toc::export::text - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export::text(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export::text - plain text export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::export::text <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents export plugin
for the generation of plain text markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_export.html">doctools::toc::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_export.html">doctools::toc::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a table of contents,
as specified in section <span class="sectref"><a href="#section4">ToC serialization format</a></span>, and
contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary, and
generates plain text markup encoding the table.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The text export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>dictionary <i class="arg">map</i></dt>
<dd><p>This standard configuration variable contains a dictionary mapping
from the (symbolic) document ids in reference entries to the actual
filenames and/or urls to be used in the output.</p>
<p>Document ids without a mapping are used unchanged.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">file</b>, and <b class="variable">format</b>, and their values.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#plain_text">plain text</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
|
<div class='fossil-doc' data-title='doctools::toc::export::wiki - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::export::wiki(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::export::wiki - wiki export plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Wiki markup</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::export::wiki <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::text</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents export plugin
for the generation of wiki markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_export.html">doctools::toc::export</a></b>, the export manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_export.html">doctools::toc::export</a></b> and the export manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc export plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a table of contents,
as specified in section <span class="sectref"><a href="#section5">ToC serialization format</a></span>, and
contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary, and
generates wiki markup encoding the table.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Wiki markup</a></h2>
<p>The basic syntax of the wiki markup generated by this plugin are
described at <a href="http://wiki.tcl.tk/14">http://wiki.tcl.tk/14</a>.</p>
<p>The plugin goes beyond the classic markup to generate proper headers
and indenting.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>The wiki export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>dictionary <i class="arg">map</i></dt>
<dd><p>This standard configuration variable contains a dictionary mapping
from the (symbolic) document ids in reference entries to the actual
filenames and/or urls to be used in the output.</p>
<p>Document ids without a mapping are used unchanged.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">file</b> and <b class="variable">format</b>, and their values.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a>, <a href="../../../../index.html#wiki">wiki</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_import.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
|
<div class='fossil-doc' data-title='doctools::toc::import - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::import(n) 0.2 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::import - Importing keyword indices</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a></li>
<li class="doctools_section"><a href="#section3">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Import plugin API v2 reference</a></li>
<li class="doctools_section"><a href="#section5">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::toc::import <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::config</b></li>
<li>package require <b class="pkgname">doctools::toc::structure</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::toc::import</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">config names</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">config get</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">includes</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">include clear</b></a></li>
<li><a href="#16"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></li>
<li><a href="#17"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class to manage the plugins for the import of
tables of contents from other formats, i.e. their conversion from, for
example <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>, <i class="term"><a href="../../../../index.html#json">json</a></i>, etc.</p>
<p>This is one of the three public pillars the management of tables of
contents resides on. The other two pillars are</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="toc_export.html">Exporting tables of contents</a></i>, and</p></li>
<li><p><i class="term"><a href="toc_container.html">Holding tables of contents</a></i></p></li>
</ol>
<p>For information about the <span class="sectref"><a href="#section2">Concepts</a></span> of tables of contents,
and their parts, see the same-named section.
For information about the data structure which is the major output of
the manager objects provided by this package see the section
<span class="sectref"><a href="#section5">ToC serialization format</a></span>.</p>
<p>The plugin system of our class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">DOCTOOLS_TOC_IMPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_TOC_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">DOCTOOLS_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/import/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/import/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/toc/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.doctools/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\IMPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using Windows(tm) operating system.</p>
<p>The whole system is delivered with two predefined import plugins,
namely</p>
<dl class="doctools_definitions">
<dt>doctoc</dt>
<dd><p>See <i class="term"><a href="import_doctoc.html">doctoc import plugin</a></i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">json import plugin</i> for details.</p></dd>
</dl>
<p>Readers wishing to write their own import plugin for some format, i.e.
<i class="term">plugin writer</i>s reading and understanding the section
containing the <span class="sectref"><a href="#section4">Import plugin API v2 reference</a></span> is an
absolute necessity, as it specifies the interaction between this
package and its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#table_of_contents">table of contents</a></i> consists of a (possibly empty) list of
<i class="term">elements</i>.</p></li>
<li><p>Each element in the list is identified by its label.</p></li>
<li><p>Each element is either a <i class="term"><a href="../../../../index.html#reference">reference</a></i>, or a <i class="term">division</i>.</p></li>
<li><p>Each reference has an associated document, identified by a symbolic
id, and a textual description.</p></li>
<li><p>Each division may have an associated document, identified by a
symbolic id.</p></li>
<li><p>Each division consists consists of a (possibly empty) list of
<i class="term">elements</i>, with each element following the rules as specified in
item 2 and above.</p></li>
</ol>
<p>A few notes</p>
<ol class="doctools_enumerated">
<li><p>The above rules span up a tree of elements, with references as the
leaf nodes, and divisions as the inner nodes, and each element
representing an entry in the whole table of contents.</p></li>
<li><p>The identifying labels of any element E are unique within their
division (or toc), and the full label of any element E is the list of
labels for all nodes on the unique path from the root of the tree to
E, including E.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::toc::import</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new import manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::doctools::toc::import</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the <i class="arg">text</i> and converts it from the specified
<i class="arg">format</i> to the canonical serialization of a table of contents using
the import plugin for the format. An error is thrown if no plugin
could be found for the format.
The serialization generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">doctoc</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">ToC serialization format</a></span>.</p>
<p>The plugin has to conform to the interface specified in section
<span class="sectref"><a href="#section4">Import plugin API v2 reference</a></span>.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It reads the contents of the specified file into memory, feeds the
result into <b class="method">import text</b> and returns the resulting
serialization as its own result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">deserialize</b> method expecting the canonical serialization of a
table of contents.
It imports the text using <b class="method">import text</b> and then feeds the
resulting serialization into the <i class="arg">object</i> via <b class="method">deserialize</b>.
This method returns the empty string as it result.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">import object text</b>, except that it
reads the text to convert from the specified file instead of being
given it as argument.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">config names</b></a></dt>
<dd><p>This method returns a list containing the names of all configuration
variables currently known to the object.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">config get</b></a></dt>
<dd><p>This method returns a dictionary containing the names and values of
all configuration variables currently known to the object.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">config set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>This method sets the configuration variable <i class="arg">name</i> to the
specified <i class="arg">value</i> and returns the new value of the variable.</p>
<p>If no value is specified it simply returns the current value, without
changing it.</p>
<p>Note that while the user can set the predefined configuration
variables <b class="const">user</b> and <b class="const">format</b> doing so will have no
effect, these values will be internally overridden when invoking an
import plugin.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">config unset</b> <i class="arg">pattern</i>...</a></dt>
<dd><p>This method unsets all configuration variables matching the specified
glob <i class="arg">pattern</i>s. If no pattern is specified it will unset all
currently defined configuration variables.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">includes</b></a></dt>
<dd><p>This method returns a list containing the currently specified paths to
use to search for include files when processing input.
The order of paths in the list corresponds to the order in which they
are used, from first to last, and also corresponds to the order in
which they were added to the object.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></dt>
<dd><p>This methods adds the specified <i class="arg">path</i> to the list of paths to use
to search for include files when processing input. The path is added
to the end of the list, causing it to be searched after all previously
added paths. The result of the command is the empty string.</p>
<p>The method does nothing if the path is already known.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></dt>
<dd><p>This methods removes the specified <i class="arg">path</i> from the list of paths
to use to search for include files when processing input. The result
of the command is the empty string.</p>
<p>The method does nothing if the path is not known.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">include clear</b></a></dt>
<dd><p>This method clears the list of paths to use to search for include
files when processing input. The result of the command is the empty
string.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Import plugin API v2 reference</a></h2>
<p>Plugins are what this package uses to manage the support for any input
format beyond the <span class="sectref"><a href="#section5">ToC serialization format</a></span>. Here we
specify the API the objects created by this package use to interact
with their plugins.</p>
<p>A plugin for this package has to follow the rules listed below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
doctools::toc::import::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
generate output for. This name is also the argument to provide
to the various <b class="method">import</b> methods of import manager
objects to get a string encoding a table of contents in that
format.</p></li>
<li><p>The plugin can expect that the package
<b class="package">doctools::toc::export::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p></li>
<li><p>The plugin can expect that a command named <b class="cmd">IncludeFile</b> is
present, with the signature</p>
<dl class="doctools_definitions">
<dt><a name="16"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></dt>
<dd><p>This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such. An example of
such a format would be <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>.</p>
<p>The plugin has to supply the following arguments</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">currentfile</i></dt>
<dd><p>The path of the file it is currently processing. This may be the empty
string if no such is known.</p></dd>
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of the include file as specified in the include directive
being processed.</p></dd>
</dl>
<p>The result of the command will be a 5-element list containing</p>
<ol class="doctools_enumerated">
<li><p>A boolean flag indicating the success (<b class="const">True</b>) or failure
(<b class="const">False</b>) of the operation.</p></li>
<li><p>In case of success the contents of the included file, and the
empty string otherwise.</p></li>
<li><p>The resolved, i.e. absolute path of the included file, if
possible, or the unchanged <i class="arg">path</i> argument. This is for
display in an error message, or as the <i class="arg">currentfile</i>
argument of another call to <b class="cmd">IncludeFile</b> should this file
contain more files.</p></li>
<li><p>In case of success an empty string, and for failure a code
indicating the reason for it, one of</p>
<dl class="doctools_definitions">
<dt>notfound</dt>
<dd><p>The specified file could not be found.</p></dd>
<dt>notread</dt>
<dd><p>The specified file was found, but not be read into memory.</p></dd>
</dl>
</li>
<li><p>An empty string in case of success of a <b class="const">notfound</b>
failure, and an additional error message describing the reason
for a <b class="const">notread</b> error in more detail.</p></li>
</ol></dd>
</dl>
</li>
<li><p>A plugin has to provide one command, with the signature shown
below.</p>
<dl class="doctools_definitions">
<dt><a name="17"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i> <i class="arg">configuration</i></a></dt>
<dd><p>Whenever an import manager of <b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b> has to parse
input for a table of contents it will invoke this command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">text</i></dt>
<dd><p>This argument will contain the text encoding the table of contents per
the format the plugin is for.</p></dd>
<dt>dictionary <i class="arg">configuration</i></dt>
<dd><p>This argument will contain the current configuration to apply to the
parsing, as a dictionary mapping from variable names to values.</p>
<p>The following configuration variables have a predefined meaning all
plugins have to obey, although they can ignore this information at
their discretion. Any other other configuration variables recognized
by a plugin will be described in the manpage for that plugin.</p>
<dl class="doctools_definitions">
<dt>user</dt>
<dd><p>This variable is expected to contain the name of the user
owning the process invoking the plugin.</p></dd>
<dt>format</dt>
<dd><p>This variable is expected to contain the name of the
format whose plugin is invoked.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of the invokations of
the command <b class="cmd"><a href="../../../../index.html#import">import</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#reference">reference</a>, <a href="../../../../index.html#table">table</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#url">url</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2018 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<div class='fossil-doc' data-title='doctools::toc::import::json - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::import::json(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::import::json - JSON import plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">JSON notation of tables of contents</a></li>
<li class="doctools_section"><a href="#section4">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::import::json <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">doctools::toc::structure</b></li>
<li>package require <b class="pkgname">json</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements the doctools table of contents import plugin
for the parsing of JSON markup.</p>
<p>This is an internal package of doctools, for use by the higher level
management packages handling tables of contents, especially <b class="package"><a href="toc_import.html">doctools::toc::import</a></b>, the import manager.</p>
<p>Using it from a regular interpreter is possible, however only with
contortions, and is not recommended.
The proper way to use this functionality is through the package
<b class="package"><a href="toc_import.html">doctools::toc::import</a></b> and the import manager objects it
provides.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
doctoc import plugin API version 2.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">string</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the <i class="arg">string</i> and parses it as JSON
markup encoding a table of contents, in the context of the specified
<i class="arg">configuration</i> (a dictionary). The result of the command is the
canonical serialization of that table of contents, in the form
specified in section <span class="sectref"><a href="#section4">ToC serialization format</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">JSON notation of tables of contents</a></h2>
<p>The JSON format used for tables of contents is a direct translation of
the <span class="sectref"><a href="#section4">ToC serialization format</a></span>, mapping Tcl dictionaries as
JSON objects and Tcl lists as JSON arrays.
For example, the Tcl serialization</p>
<pre class="doctools_example">
doctools::toc {
items {
{reference {
desc {DocTools - Tables of Contents}
id introduction.man
label doctools::toc::introduction
}}
{division {
id processing.man
items {
{reference {
desc {doctoc serialization utilities}
id structure.man
label doctools::toc::structure
}}
{reference {
desc {Parsing text in doctoc format}
id parse.man
label doctools::toc::parse
}}
}
label Processing
}}
}
label {Table of Contents}
title TOC
}
</pre>
<p>is equivalent to the JSON string</p>
<pre class="doctools_example">
{
"doctools::toc" : {
"items" : [{
"reference" : {
"desc" : "DocTools - Tables of Contents",
"id" : "introduction.man",
"label" : "doctools::toc::introduction"
}
},{
"division" : {
"id" : "processing.man",
"items" : [{
"reference" : {
"desc" : "doctoc serialization utilities",
"id" : "structure.man",
"label" : "doctools::toc::structure"
}
},{
"reference" : {
"desc" : "Parsing text in doctoc format",
"id" : "parse.man",
"label" : "doctools::toc::parse"
}
}],
"label" : "Processing"
}
}],
"label" : "Table of Contents",
"title" : "TOC"
}
}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#deserialization">deserialization</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text formatter plugin</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<div class='fossil-doc' data-title='doctools2toc_introduction - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools2toc_introduction(n) 2.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools2toc_introduction - DocTools - Tables of Contents</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Related formats</a></li>
<li class="doctools_section"><a href="#section3">Package Overview</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> (short for <em>documentation tables of contents</em>)
stands for a set of related, yet different, entities which are working
together for the easy creation and transformation of tables and
contents for documentation.</p>
<p>These are</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the semantic markup of a table of contents.
Markup is represented by Tcl commands.
Beginners should start with the
<i class="term"><a href="../doctools/doctoc_lang_intro.html">doctoc language introduction</a></i>.
The formal specification is split over two documents, one dealing with
the <i class="term"><a href="../doctools/doctoc_lang_syntax.html">doctoc language syntax</a></i>, the other a
<i class="term"><a href="../doctools/doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p></li>
<li><p>A set of packages for the programmatic manipulation of tables of
contents in memory, and their conversion between various formats,
reading and writing. The aforementioned markup language is one of the
formats which can be both read from and written to.</p></li>
<li><p>The system for the conversion of tables of contents is based on a
plugin mechanism, for this we have two APIs describing the interface
between the packages above and the import/export plugins.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the documentation process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of documentation has to understand the markup language
itself. A beginner to doctoc should read the more informally written
<i class="term"><a href="../doctools/doctoc_lang_intro.html">doctoc language introduction</a></i> first. Having digested this
the formal <i class="term"><a href="../doctools/doctoc_lang_syntax.html">doctoc language syntax</a></i> specification should
become understandable. A writer experienced with doctoc may only
need the <i class="term"><a href="../doctools/doctoc_lang_cmdref.html">doctoc language command reference</a></i> from time to
time to refresh her memory.</p>
<p>While a document is written the <b class="syscmd">dtp</b> application can be used
to validate it, and after completion it also performs the conversion
into the chosen system of visual markup, be it *roff, HTML, plain
text, wiki, etc. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> application makes
internal use of doctoc when handling directories of documentation,
automatically generating a proper table of contents for them.</p></li>
<li><p>A <i class="term">processor</i> of documentation written in the <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>
markup language has to know which tools are available for use.</p>
<p>The main tool is the aforementioned <b class="syscmd">dtp</b> application provided
by Tcllib. The simpler <b class="syscmd"><a href="../dtplite/pkg_dtplite.html">dtplite</a></b> does not expose doctoc to the
user. At the bottom level, common to both applications, however we
find the three packages providing the basic facilities to handle
tables of contents, i.e. import from textual formats, programmatic
manipulation in memory, and export to textual formats. These are</p>
<dl class="doctools_definitions">
<dt><b class="package">doctoools::toc</b></dt>
<dd><p>Programmatic manipulation of tables of contents in memory.</p></dd>
<dt><b class="package">doctoools::toc::import</b></dt>
<dd><p>Import of tables of contents from various textual formats. The set of
supported formats is extensible through plugin packages.</p></dd>
<dt><b class="package">doctoools::toc::export</b></dt>
<dd><p>Export of tables of contents to various textual formats. The set of
supported formats is extensible through plugin packages.</p></dd>
</dl>
<p>See also section <span class="sectref"><a href="#section3">Package Overview</a></span> for an overview of the
dependencies between these and other, supporting packages.</p></li>
<li><p>At last, but not least, <i class="term">plugin writers</i> have to understand the
interaction between the import and export packages and their plugins.
These APIs are described in the documentation for the two relevant
packages, i.e.</p>
<ul class="doctools_itemized">
<li><p><b class="package">doctoools::toc::import</b></p></li>
<li><p><b class="package">doctoools::toc::export</b></p></li>
</ul>
</li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Related formats</a></h2>
<p>The doctoc format does not stand alone, it has two companion formats.
These are called <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> and <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>, and they are
intended for the markup of <i class="term">keyword indices</i>, and of general
documentation, respectively.
They are described in their own sets of documents, starting at
the <i class="term">DocTools - Keyword Indices</i> and
the <i class="term">DocTools - General</i>, respectively.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Package Overview</a></h2>
<pre class="doctools_example">
~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
~~ | ~~
doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
| | |
+---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+
| | | | | | | | |
doctools::config = | | | = doctools::include doctools::config doctools::paths
| | | | |
doctools::toc::export::<*> | | | doctools::toc::import::<*>
doctoc | | | doctoc, json
json | | | | \\
html | | | doctools::toc::parse \\
nroff | | | | \\
wiki | | | +---------------+ json
text | | | | |
doctools::toc::structure |
|
+-------+---------------+
| |
doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat
| |
doctools::text doctools::nroff::man_macros =
|
doctools::msgcat::toc::<*>
c, en, de, fr
(fr == en for now)
~~ Interoperable objects, without actual package dependencies
-- Package dependency, higher requires lower package
= Dynamic dependency through plugin system
<*> Multiple packages following the given form of naming.
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../doctools/doctoc_intro.html">doctoc_intro</a>, <a href="../doctools/doctools.html">doctools</a>, doctools2doc_introduction, <a href="../doctools2idx/idx_introduction.html">doctools2idx_introduction</a>, <a href="../doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a>, <a href="../doctools/doctools_lang_faq.html">doctools_lang_faq</a>, <a href="../doctools/doctools_lang_intro.html">doctools_lang_intro</a>, <a href="../doctools/doctools_lang_syntax.html">doctools_lang_syntax</a>, <a href="../doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#contents">contents</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a>, <a href="../../../../index.html#table_of_contents">table of contents</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::toc::c - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::toc::c(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::toc::c - Message catalog for the doctoc parser (C)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::toc::c <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::toc::c</b> is a
support module providing the C language message catalog
for the doctoc parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#c">C</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::toc::de - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::toc::de(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::toc::de - Message catalog for the doctoc parser (DE)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::toc::de <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::toc::de</b> is a
support module providing the DE (german) language message catalog
for the doctoc parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#de">DE</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::toc::en - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::toc::en(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::toc::en - Message catalog for the doctoc parser (EN)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::toc::en <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::toc::en</b> is a
support module providing the EN (english) language message catalog
for the doctoc parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#en">EN</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='doctools::msgcat::toc::fr - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::msgcat::toc::fr(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::msgcat::toc::fr - Message catalog for the doctoc parser (FR)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">msgcat</b></li>
<li>package require <b class="pkgname">doctools::msgcat::toc::fr <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">doctools::msgcat::toc::fr</b> is a
support module providing the FR (french) language message catalog
for the doctoc parser in the doctools system version 2. As such it is
an internal package a regular user (developer) should not be in direct
contact with.</p>
<p>If you are such please go the documentation of either</p>
<ol class="doctools_enumerated">
<li><p><b class="package">doctools::doc</b>,</p></li>
<li><p><b class="package"><a href="../doctools/doctoc.html">doctools::toc</a></b>, or</p></li>
<li><p><b class="package"><a href="../doctools2idx/idx_container.html">doctools::idx</a></b></p></li>
</ol>
<p>Within the system architecture this package resides under the package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b> providing the general message catalog
management within the system. <em>Note</em> that there is <em>no</em>
explicit dependency between the manager and catalog packages. The
catalog is a plugin which is selected and loaded dynamically.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>This package has no exported API.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fr">FR</a>, <a href="../../../../index.html#catalog_package">catalog package</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#i18n">i18n</a>, <a href="../../../../index.html#internationalization">internationalization</a>, <a href="../../../../index.html#l10n">l10n</a>, <a href="../../../../index.html#localization">localization</a>, <a href="../../../../index.html#message_catalog">message catalog</a>, <a href="../../../../index.html#message_package">message package</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
|
<div class='fossil-doc' data-title='doctools::toc::parse - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::parse(n) 1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::parse - Parsing text in doctoc format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Parse errors</a></li>
<li class="doctools_section"><a href="#section4">[doctoc] notation of tables of contents</a></li>
<li class="doctools_section"><a href="#section5">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::toc::parse <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">doctools::toc::structure</b></li>
<li>package require <b class="pkgname">doctools::msgcat</b></li>
<li>package require <b class="pkgname">doctools::tcl::parse</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::stack</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::toc::parse</b> <b class="method">text</b> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">::doctools::toc::parse</b> <b class="method">file</b> <i class="arg">path</i></a></li>
<li><a href="#3"><b class="cmd">::doctools::toc::parse</b> <b class="method">includes</b></a></li>
<li><a href="#4"><b class="cmd">::doctools::toc::parse</b> <b class="method">include add</b> <i class="arg">path</i></a></li>
<li><a href="#5"><b class="cmd">::doctools::toc::parse</b> <b class="method">include remove</b> <i class="arg">path</i></a></li>
<li><a href="#6"><b class="cmd">::doctools::toc::parse</b> <b class="method">include clear</b></a></li>
<li><a href="#7"><b class="cmd">::doctools::toc::parse</b> <b class="method">vars</b></a></li>
<li><a href="#8"><b class="cmd">::doctools::toc::parse</b> <b class="method">var set</b> <i class="arg">name</i> <i class="arg">value</i></a></li>
<li><a href="#9"><b class="cmd">::doctools::toc::parse</b> <b class="method">var unset</b> <i class="arg">name</i></a></li>
<li><a href="#10"><b class="cmd">::doctools::toc::parse</b> <b class="method">var clear</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to parse text written in the
<i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> markup language and convert it into the canonical
serialization of the table of contents encoded in the text.
See the section <span class="sectref"><a href="#section5">ToC serialization format</a></span> for specification
of their format.</p>
<p>This is an internal package of doctools, for use by the higher level
packages handling <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> documents.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::toc::parse</b> <b class="method">text</b> <i class="arg">text</i></a></dt>
<dd><p>The command takes the string contained in <i class="arg">text</i> and parses it
under the assumption that it contains a document written using the
<i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> markup language. An error is thrown if this assumption
is found to be false. The format of these errors is described in
section <span class="sectref"><a href="#section3">Parse errors</a></span>.</p>
<p>When successful the command returns the canonical serialization of the
table of contents which was encoded in the text.
See the section <span class="sectref"><a href="#section5">ToC serialization format</a></span> for specification
of that format.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::toc::parse</b> <b class="method">file</b> <i class="arg">path</i></a></dt>
<dd><p>The same as <b class="method">text</b>, except that the text to parse is read from
the file specified by <i class="arg">path</i>.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::toc::parse</b> <b class="method">includes</b></a></dt>
<dd><p>This method returns the current list of search paths used when looking
for include files.</p></dd>
<dt><a name="4"><b class="cmd">::doctools::toc::parse</b> <b class="method">include add</b> <i class="arg">path</i></a></dt>
<dd><p>This method adds the <i class="arg">path</i> to the list of paths searched when
looking for an include file. The call is ignored if the path is
already in the list of paths. The method returns the empty string as
its result.</p></dd>
<dt><a name="5"><b class="cmd">::doctools::toc::parse</b> <b class="method">include remove</b> <i class="arg">path</i></a></dt>
<dd><p>This method removes the <i class="arg">path</i> from the list of paths searched
when looking for an include file. The call is ignored if the path is
not contained in the list of paths. The method returns the empty
string as its result.</p></dd>
<dt><a name="6"><b class="cmd">::doctools::toc::parse</b> <b class="method">include clear</b></a></dt>
<dd><p>This method clears the list of search paths for include files.</p></dd>
<dt><a name="7"><b class="cmd">::doctools::toc::parse</b> <b class="method">vars</b></a></dt>
<dd><p>This method returns a dictionary containing the current set of
predefined variables known to the <b class="cmd">vset</b> markup command during
processing.</p></dd>
<dt><a name="8"><b class="cmd">::doctools::toc::parse</b> <b class="method">var set</b> <i class="arg">name</i> <i class="arg">value</i></a></dt>
<dd><p>This method adds the variable <i class="arg">name</i> to the set of predefined
variables known to the <b class="cmd">vset</b> markup command during processing,
and gives it the specified <i class="arg">value</i>. The method returns the empty
string as its result.</p></dd>
<dt><a name="9"><b class="cmd">::doctools::toc::parse</b> <b class="method">var unset</b> <i class="arg">name</i></a></dt>
<dd><p>This method removes the variable <i class="arg">name</i> from the set of predefined
variables known to the <b class="cmd">vset</b> markup command during
processing. The method returns the empty string as its result.</p></dd>
<dt><a name="10"><b class="cmd">::doctools::toc::parse</b> <b class="method">var clear</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>This method removes all variables matching the <i class="arg">pattern</i> from the
set of predefined variables known to the <b class="cmd">vset</b> markup command
during processing. The method returns the empty string as its result.</p>
<p>The pattern matching is done with <b class="cmd">string match</b>, and the
default pattern used when none is specified, is <b class="const">*</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Parse errors</a></h2>
<p>The format of the parse error messages thrown when encountering
violations of the <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> markup syntax is human readable and
not intended for processing by machines. As such it is not documented.</p>
<p><em>However</em>, the errorCode attached to the message is
machine-readable and has the following format:</p>
<ol class="doctools_enumerated">
<li><p>The error code will be a list, each element describing a single error
found in the input. The list has at least one element, possibly more.</p></li>
<li><p>Each error element will be a list containing six strings describing an
error in detail. The strings will be</p>
<ol class="doctools_enumerated">
<li><p>The path of the file the error occurred in. This may be empty.</p></li>
<li><p>The range of the token the error was found at. This range is a
two-element list containing the offset of the first and last character
in the range, counted from the beginning of the input (file). Offsets
are counted from zero.</p></li>
<li><p>The line the first character after the error is on.
Lines are counted from one.</p></li>
<li><p>The column the first character after the error is at.
Columns are counted from zero.</p></li>
<li><p>The message code of the error. This value can be used as argument to
<b class="cmd">msgcat::mc</b> to obtain a localized error message, assuming that
the application had a suitable call of <b class="cmd">doctools::msgcat::init</b> to
initialize the necessary message catalogs (See package
<b class="package"><a href="../doctools2base/tcllib_msgcat.html">doctools::msgcat</a></b>).</p></li>
<li><p>A list of details for the error, like the markup command involved. In
the case of message code <b class="const">doctoc/include/syntax</b> this value is
the set of errors found in the included file, using the format
described here.</p></li>
</ol>
</li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">[doctoc] notation of tables of contents</a></h2>
<p>The doctoc format for tables of contents, also called the
<i class="term">doctoc markup language</i>, is too large to be covered in single
section.
The interested reader should start with the document</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/doctoc_lang_intro.html">doctoc language introduction</a></i></p></li>
</ol>
<p>and then proceed from there to the formal specifications, i.e. the
documents</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="../doctools/doctoc_lang_syntax.html">doctoc language syntax</a></i> and</p></li>
<li><p><i class="term"><a href="../doctools/doctoc_lang_cmdref.html">doctoc language command reference</a></i>.</p></li>
</ol>
<p>to get a thorough understanding of the language.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#lexer">lexer</a>, <a href="../../../../index.html#parser">parser</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
|
<div class='fossil-doc' data-title='doctools::toc::structure - Documentation tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctools::toc::structure(n) 0.1 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctools::toc::structure - Doctoc serialization utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">ToC serialization format</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">doctools::toc::structure <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::doctools::toc::structure</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::doctools::toc::structure</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></li>
<li><a href="#3"><b class="cmd">::doctools::toc::structure</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></li>
<li><a href="#4"><b class="cmd">::doctools::toc::structure</b> <b class="method">print</b> <i class="arg">serial</i></a></li>
<li><a href="#5"><b class="cmd">::doctools::toc::structure</b> <b class="method">merge</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to work with the serializations of
tables of contents as managed by the doctools system v2, and specified
in section <span class="sectref"><a href="#section3">ToC serialization format</a></span>.</p>
<p>This is an internal package of doctools, for use by the higher level
packages handling tables of contents and their conversion into and out
of various other formats, like documents written using <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>
markup.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::doctools::toc::structure</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of a table of contents and will throw an
error if that is not the case. The result of the command is the empty
string.</p>
<p>If the argument <i class="arg">canonvar</i> is specified it is interpreted as the
name of a variable in the calling context. This variable will be
written to if and only if <i class="arg">serial</i> is a valid regular
serialization. Its value will be a boolean, with <b class="const">True</b>
indicating that the serialization is not only valid, but also
<i class="term">canonical</i>. <b class="const">False</b> will be written for a valid, but
non-canonical serialization.</p>
<p>For the specification of regular and canonical serializations see the
section <span class="sectref"><a href="#section3">ToC serialization format</a></span>.</p></dd>
<dt><a name="2"><b class="cmd">::doctools::toc::structure</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">canonical</i> serialization of a table of contents and will throw
an error if that is not the case. The result of the command is the
empty string.</p>
<p>For the specification of canonical serializations see the section
<span class="sectref"><a href="#section3">ToC serialization format</a></span>.</p></dd>
<dt><a name="3"><b class="cmd">::doctools::toc::structure</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of a table of contents and will throw an
error if that is not the case.</p>
<p>It will then convert the input into the <i class="term">canonical</i> serialization
of the contained table of contents and return it as its result. If the
input is already canonical it will be returned unchanged.</p>
<p>For the specification of regular and canonical serializations see the
section <span class="sectref"><a href="#section3">ToC serialization format</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::doctools::toc::structure</b> <b class="method">print</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the argument <i class="arg">serial</i> contains a valid
regular serialization of a table of contents and returns a string
containing that table in a human readable form.</p>
<p>The exact format of this form is not specified and cannot be relied on
for parsing or other machine-based activities.</p>
<p>For the specification of regular serializations see the section
<span class="sectref"><a href="#section3">ToC serialization format</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::doctools::toc::structure</b> <b class="method">merge</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></dt>
<dd><p>This command accepts the regular serializations of two tables of
contents and uses them to create their union. The result of the
command is the canonical serialization of this unified table of
contents.</p>
<p>Title and label of the resulting table are taken from the table
contained in <i class="arg">serialb</i>.</p>
<p>The whole table and its divisions are merged recursively in the same
manner:</p>
<ol class="doctools_enumerated">
<li><p>All reference elements which occur in both divisions (identified by
their label) are unified with document id's and descriptions taken
from the second table.</p></li>
<li><p>All division elements which occur in both divisions (identified by
their label) are unified with the optional document id taken from the
second table, if any, or from the first if none is in the second. The
elements in the division are merged recursively using the same
algorithm as described in this list.</p></li>
<li><p>Type conflicts between elements, i.e. finding two elements with the
same label but different types result in a merge error.</p></li>
<li><p>All elements found in the second division but not in the first are
added to the end of the list of elements in the merge result.</p></li>
</ol>
<p>For the specification of regular and canonical serializations see the
section <span class="sectref"><a href="#section3">ToC serialization format</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">ToC serialization format</a></h2>
<p>Here we specify the format used by the doctools v2 packages to
serialize tables of contents as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a table of contents may have more than one regular serialization
only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any table of contents is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">doctools::toc</b>, and its
value. This value holds the contents of the table of contents.</p></li>
<li><p>The contents of the table of contents are a Tcl dictionary holding the
title of the table of contents, a label, and its elements. The
relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">title</b></dt>
<dd><p>The value is a string containing the title of the table of contents.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the table of contents.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the table, in the
order they are to be shown.</p>
<p>Each element is a Tcl list holding the type of the item, and its
description, in this order. An alternative description would be that
it is a Tcl dictionary holding a single key, the item type, mapped to
the item description.</p>
<p>The two legal item types and their descriptions are</p>
<dl class="doctools_definitions">
<dt><b class="const">reference</b></dt>
<dd><p>This item describes a single entry in the table of contents,
referencing a single document.
To this end its value is a Tcl dictionary containing an id for the
referenced document, a label, and a longer textual description which
can be associated with the entry.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the entry.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for this entry. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">desc</b></dt>
<dd><p>The value is a string containing a longer description for this entry.</p></dd>
</dl></dd>
<dt><b class="const">division</b></dt>
<dd><p>This item describes a group of entries in the table of contents,
inducing a hierarchy of entries.
To this end its value is a Tcl dictionary containing a label for the
group, an optional id to a document for the whole group, and the list
of entries in the group.
The relevant keys and their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">id</b></dt>
<dd><p>The value is a string containing the id of the document associated
with the whole group. This key is optional.</p></dd>
<dt><b class="const">label</b></dt>
<dd><p>The value is a string containing a label for the group. This string
also identifies the entry, and no two entries (references and
divisions) in the containing list are allowed to have the same label.</p></dd>
<dt><b class="const">items</b></dt>
<dd><p>The value is a Tcl list holding the elements of the group, in the
order they are to be shown.
This list has the same structure as the value for the keyword
<b class="const">items</b> used to describe the whole table of contents, see
above. This closes the recusrive definition of the structure, with
divisions holding the same type of elements as the whole table of
contents, including other divisions.</p></dd>
</dl></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a table of contents has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this table of contents.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
</ol></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#deserialization">deserialization</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#serialization">serialization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
|
<div class='fossil-doc' data-title='dtplite - Documentation toolbox'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">dtplite(n) 1.3.1 tcllib "Documentation toolbox"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>dtplite - Lightweight DocTools Markup Processor</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">USE CASES</a></li>
<li class="doctools_subsection"><a href="#subsection2">COMMAND LINE</a></li>
<li class="doctools_subsection"><a href="#subsection3">OPTIONS</a></li>
<li class="doctools_subsection"><a href="#subsection4">FORMATS</a></li>
<li class="doctools_subsection"><a href="#subsection5">DIRECTORY STRUCTURES</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">dtplite <span class="opt">?1.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">dtplite</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputfile</i></a></li>
<li><a href="#2"><b class="cmd">dtplite</b> <b class="const">validate</b> <i class="arg">inputfile</i></a></li>
<li><a href="#3"><b class="cmd">dtplite</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></li>
<li><a href="#4"><b class="cmd">dtplite</b> <b class="option">-merge</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The application described by this document, <b class="syscmd">dtplite</b>, is the
successor to the extremely simple <b class="syscmd"><a href="../doctools/mpexpand.html">mpexpand</a></b>. Influenced in its
functionality by the <b class="syscmd">dtp</b> doctools processor it is much more
powerful than <b class="syscmd"><a href="../doctools/mpexpand.html">mpexpand</a></b>, yet still as easy to use; definitely
easier than <b class="syscmd">dtp</b> with its myriad of subcommands and options.</p>
<p><b class="syscmd">dtplite</b> is based upon the package <b class="package"><a href="../doctools/doctools.html">doctools</a></b>, like
the other two processors.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">USE CASES</a></h3>
<p><b class="syscmd">dtplite</b> was written with the following three use cases in
mind.</p>
<ol class="doctools_enumerated">
<li><p>Validation of a single document, i.e. checking that it was written in
valid doctools format. This mode can also be used to get a preliminary
version of the formatted output for a single document, for display in
a browser, nroff, etc., allowing proofreading of the formatting.</p></li>
<li><p>Generation of the formatted documentation for a single package,
i.e. all the manpages, plus a table of contents and an index of
keywords.</p></li>
<li><p>An extension of the previous mode of operation, a method for the easy
generation of one documentation tree for several packages, and
especially of a unified table of contents and keyword index.</p></li>
</ol>
<p>Beyond the above we also want to make use of the customization
features provided by the HTML formatter. It is not the only format the
application should be able to generate, but we anticipiate it to be
the most commonly used, and it is one of the few which do provide
customization hooks.</p>
<p>We allow the caller to specify a header string, footer string, a
stylesheet, and data for a bar of navigation links at the top of the
generated document.
While all can be set as long as the formatting engine provides an
appropriate engine parameter (See section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>) the last
two have internal processing which make them specific to HTML.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">COMMAND LINE</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">dtplite</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputfile</i></a></dt>
<dd><p>This is the form for use case [1]. The <i class="arg">options</i> will be
explained later, in section <span class="sectref"><a href="#subsection3">OPTIONS</a></span>.</p>
<dl class="doctools_arguments">
<dt>path <i class="arg">output</i> (in)</dt>
<dd><p>This argument specifies where to write the generated document. It can
be the path to a file or directory, or <b class="const">-</b>.
The last value causes the application to write the generated
documented to <b class="const">stdout</b>.</p>
<p>If the <i class="arg">output</i> does not exist then [file dirname $output]
has to exist and must be a writable directory.
The generated document will be written to a file in that directory,
and the name of that file will be derived from the <i class="arg">inputfile</i>,
the <i class="arg">format</i>, and the value given to option <b class="option">-ext</b> (if
present).</p></dd>
<dt>(path|handle) <i class="arg">format</i> (in)</dt>
<dd><p>This argument specifies the formatting engine to use when processing
the input, and thus the format of the generated document. See section
<span class="sectref"><a href="#subsection4">FORMATS</a></span> for the possibilities recognized by the application.</p></dd>
<dt>path <i class="arg">inputfile</i> (in)</dt>
<dd><p>This argument specifies the path to the file to process. It has to
exist, must be readable, and written in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">dtplite</b> <b class="const">validate</b> <i class="arg">inputfile</i></a></dt>
<dd><p>This is a simpler form for use case [1]. The "validate" format
generates no output at all, only syntax checks are performed. As such
the specification of an output file or other options is not necessary
and left out.</p></dd>
<dt><a name="3"><b class="cmd">dtplite</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></dt>
<dd><p>This is the form for use case [2]. It differs from the form for
use case [1] by having the input documents specified through a
directory instead of a file. The other arguments are identical, except
for <i class="arg">output</i>, which now has to be the path to an existing and
writable directory.</p>
<p>The input documents are all files in <i class="arg">inputdirectory</i> or any of
its subdirectories which were recognized by <b class="cmd">fileutil::fileType</b>
as containing text in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="4"><b class="cmd">dtplite</b> <b class="option">-merge</b> <b class="option">-o</b> <i class="arg">output</i> <span class="opt">?options?</span> <i class="arg">format</i> <i class="arg">inputdirectory</i></a></dt>
<dd><p>This is the form for use case [3]. The only difference to the
form for use case [2] is the additional option <b class="option">-merge</b>.</p>
<p>Each such call will merge the generated documents coming from
processing the input documents under <i class="arg">inputdirectory</i> or any of
its subdirectories to the files under <i class="arg">output</i>. In this manner it
is possible to incrementally build the unified documentation for any
number of packages. Note that it is necessary to run through all the
packages twice to get fully correct cross-references (for formats
supporting them).</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OPTIONS</a></h3>
<p>This section describes all the options available to the user of the
application, with
the exception of the options <b class="option">-o</b> and <b class="option">-merge</b>. These
two were described already, in section <span class="sectref"><a href="#subsection2">COMMAND LINE</a></span>.</p>
<dl class="doctools_options">
<dt><b class="option">-exclude</b> string</dt>
<dd><p>This option specifies an exclude (glob) pattern. Any files identified
as manpages to process which match the exclude pattern are
ignored. The option can be provided multiple times, each usage adding
an additional pattern to the list of exclusions.</p></dd>
<dt><b class="option">-ext</b> string</dt>
<dd><p>If the name of an output file has to be derived from the name of an
input file it will use the name of the <i class="arg">format</i> as the extension
by default. This option here will override this however, forcing it to
use <i class="arg">string</i> as the file extension. This option is ignored if the
name of the output file is fully specified through option <b class="option">-o</b>.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-header</b> file</dt>
<dd><p>This option can be used if and only if the selected <i class="arg">format</i>
provides an engine parameter named "header". It takes the contents of
the specified file and assign them to that parameter, for whatever use
by the engine. The HTML engine will insert the text just after the tag
<b class="const"><body></b>.
If navigation buttons are present (see option <b class="option">-nav</b> below),
then the HTML generated for them is appended to the header data
originating here before the final assignment to the parameter.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-footer</b> file</dt>
<dd><p>Like <b class="option">-header</b>, except that: Any navigation buttons are ignored,
the corresponding required engine parameter is named "footer", and the
data is inserted just before the tag <b class="const"></body></b>.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-style</b> file</dt>
<dd><p>This option can be used if and only if the selected <i class="arg">format</i>
provides an engine parameter named "meta". When specified it will
generate a piece of HTML code declaring the <i class="arg">file</i> as the
stylesheet for the generated document and assign that to the
parameter. The HTML engine will insert this inot the document, just
after the tag <b class="const"><head></b>.</p>
<p>When processing an input directory the stylesheet file is copied into
the output directory and the generated HTML will refer to the copy, to
make the result more self-contained. When processing an input file we
have no location to copy the stylesheet to and so just reference it as
specified.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-toc</b> path|text</dt>
<dd><p>This option specifies a doctoc file (or text) to use for the table of contents
instead of generating our own.</p>
<p>When used multiple times only the last definition is relevant.</p></dd>
<dt><b class="option">-pre+toc</b> label path|text</dt>
<dd></dd>
<dt><b class="option">-post+toc</b> label path|text</dt>
<dd><p>This option specifies additional doctoc files (or texts) to use in
the navigation bar.</p>
<p>Positioning and handling of multiple uses is like for options
<b class="option">-prenav</b> and <b class="option">-postnav</b>, see below.</p></dd>
<dt><b class="option">-nav</b> label url</dt>
<dd></dd>
<dt><b class="option">-prenav</b> label url</dt>
<dd><p>Use this option to specify a navigation button with <i class="arg">label</i> to
display and the <i class="arg">url</i> to link to. This option can be used if and
only if the selected <i class="arg">format</i> provides an engine parameter named
"header". The HTML generated for this is appended to whatever data we
got from option <b class="option">-header</b> before it is inserted into the
generated documents.</p>
<p>When used multiple times all definitions are collected and a
navigation bar is created, with the first definition shown at the left
edge and the last definition to the right.</p>
<p>The url can be relative. In that case it is assumed to be relative
to the main files (TOC and Keyword index), and will be transformed for
all others to still link properly.</p></dd>
<dt><b class="option">-postnav</b> label url</dt>
<dd><p>Use this option to specify a navigation button with <i class="arg">label</i> to
display and the <i class="arg">url</i> to link to. This option can be used if and
only if the selected <i class="arg">format</i> provides an engine parameter named
"header". The HTML generated for this is appended to whatever data we
got from option <b class="option">-header</b> before it is inserted into the
generated documents.</p>
<p>When used multiple times all definitions are collected and a
navigation bar is created, with the last definition shown at the right
edge and the first definition to the left.</p>
<p>The url can be relative. In that case it is assumed to be relative
to the main files (TOC and Keyword index), and will be transformed for
all others to still link properly.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">FORMATS</a></h3>
<p>At first the <i class="arg">format</i> argument will be treated as a path to a tcl
file containing the code for the requested formatting engine. The
argument will be treated as the name of one of the predefined formats
listed below if and only if the path does not exist.</p>
<p><em>Note a limitation</em>: If treating the format as path to the tcl
script implementing the engine was sucessful, then this script has to
implement not only the engine API for doctools, i.e.
<i class="term">doctools_api</i>, but for <i class="term">doctoc_api</i> and <i class="term">docidx_api</i>
as well. Otherwise the generation of a table of contents and of a
keyword index will fail.</p>
<p>List of predefined formats, i.e. as provided by the
package <b class="package"><a href="../doctools/doctools.html">doctools</a></b>:</p>
<dl class="doctools_definitions">
<dt><b class="const">nroff</b></dt>
<dd><p>The processor generates *roff output, the standard format for unix
manpages.</p></dd>
<dt><b class="const">html</b></dt>
<dd><p>The processor generates HTML output, for usage in and display by web
browsers. This engine is currently the only one providing the various
engine parameters required for the additional customaization of the
output.</p></dd>
<dt><b class="const">tmml</b></dt>
<dd><p>The processor generates TMML output, the Tcl Manpage Markup Language,
a derivative of XML.</p></dd>
<dt><b class="const">latex</b></dt>
<dd><p>The processor generates LaTeX output.</p></dd>
<dt><b class="const">wiki</b></dt>
<dd><p>The processor generates Wiki markup as understood by <b class="syscmd">wikit</b>.</p></dd>
<dt><b class="const">list</b></dt>
<dd><p>The processor extracts the information provided by <b class="cmd">manpage_begin</b>.
This format is used internally to extract the meta data from which
both table of contents and keyword index are derived from.</p></dd>
<dt><b class="const">null</b></dt>
<dd><p>The processor does not generate any output. This is equivalent to
<b class="const">validate</b>.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">DIRECTORY STRUCTURES</a></h3>
<p>In this section we describe the directory structures generated by the
application under <i class="arg">output</i> when processing all documents in an
<i class="arg">inputdirectory</i>. In other words, this is only relevant to the use
cases [2] and [3].</p>
<dl class="doctools_definitions">
<dt>[2]</dt>
<dd><p>The following directory structure is created when processing a single
set of input documents. The file extension used is for output in
HTML, but that is not relevant to the structure and was just used to
have proper file names.</p>
<pre class="doctools_example">
output/
toc.html
index.html
files/
path/to/FOO.html
</pre>
<p>The last line in the example shows the document
generated for a file FOO located at</p>
<pre class="doctools_example">
inputdirectory/path/to/FOO
</pre>
</dd>
<dt>[3]</dt>
<dd><p>When merging many packages into a unified set of documents the
generated directory structure is a bit deeper:</p>
<pre class="doctools_example">
output
.toc
.idx
.tocdoc
.idxdoc
.xrf
toc.html
index.html
FOO1/
...
FOO2/
toc.html
files/
path/to/BAR.html
</pre>
<p>Each of the directories FOO1, ... contains the documents generated for
the package FOO1, ... and follows the structure shown for use case
[2]. The only exception is that there is no per-package index.</p>
<p>The files "<b class="file">.toc</b>", "<b class="file">.idx</b>", and "<b class="file">.xrf</b>" contain the
internal status of the whole output and will be read and updated by
the next invokation. Their contents will not be documented. Remove
these files when all packages wanted for the output have been
processed, i.e. when the output is complete.</p>
<p>The files "<b class="file">.tocdoc</b>", and "<b class="file">.idxdoc</b>", are intermediate files
in doctoc and docidx markup, respectively, containing the main table
of contents and keyword index for the set of documents before their
conversion to the chosen output format.
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../doctools/docidx_intro.html">docidx introduction</a>, <a href="../doctools/doctoc_intro.html">doctoc introduction</a>, <a href="../doctools/doctools_intro.html">doctools introduction</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">HTML</a>, <a href="../../../../index.html#tmml">TMML</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#docidx">docidx</a>, <a href="../../../../index.html#doctoc">doctoc</a>, <a href="../../../../index.html#doctools">doctools</a>, <a href="../../../../index.html#manpage">manpage</a>, <a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#nroff">nroff</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2013 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fileutil/fileutil.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
|
<div class='fossil-doc' data-title='fileutil - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil(n) 1.16 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil - Procedures implementing some file utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Warnings and Incompatibilities</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">fileutil <span class="opt">?1.16?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::lexnormalize</b> <i class="arg">path</i></a></li>
<li><a href="#2"><b class="cmd">::fileutil::fullnormalize</b> <i class="arg">path</i></a></li>
<li><a href="#3"><b class="cmd">::fileutil::test</b> <i class="arg">path</i> <i class="arg">codes</i> <span class="opt">?<i class="arg">msgvar</i>?</span> <span class="opt">?<i class="arg">label</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::fileutil::cat</b> (<span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i>)...</a></li>
<li><a href="#5"><b class="cmd">::fileutil::writeFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">data</i></a></li>
<li><a href="#6"><b class="cmd">::fileutil::appendToFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">data</i></a></li>
<li><a href="#7"><b class="cmd">::fileutil::insertIntoFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">at</i> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::fileutil::removeFromFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">at</i> <i class="arg">n</i></a></li>
<li><a href="#9"><b class="cmd">::fileutil::replaceInFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">at</i> <i class="arg">n</i> <i class="arg">data</i></a></li>
<li><a href="#10"><b class="cmd">::fileutil::updateInPlace</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">cmd</i></a></li>
<li><a href="#11"><b class="cmd">::fileutil::fileType</b> <i class="arg">filename</i></a></li>
<li><a href="#12"><b class="cmd">::fileutil::find</b> <span class="opt">?<i class="arg">basedir</i> <span class="opt">?<i class="arg">filtercmd</i>?</span>?</span></a></li>
<li><a href="#13"><b class="cmd">::fileutil::findByPattern</b> <i class="arg">basedir</i> <span class="opt">?<b class="option">-regexp</b>|<b class="option">-glob</b>?</span> <span class="opt">?<b class="option">--</b>?</span> <i class="arg">patterns</i></a></li>
<li><a href="#14"><b class="cmd">::fileutil::foreachLine</b> <i class="arg">var filename cmd</i></a></li>
<li><a href="#15"><b class="cmd">::fileutil::grep</b> <i class="arg">pattern</i> <span class="opt">?<i class="arg">files</i>?</span></a></li>
<li><a href="#16"><b class="cmd">::fileutil::install</b> <span class="opt">?<b class="option">-m</b> <i class="arg">mode</i>?</span> <i class="arg">source</i> <i class="arg">destination</i></a></li>
<li><a href="#17"><b class="cmd">::fileutil::stripN</b> <i class="arg">path</i> <i class="arg">n</i></a></li>
<li><a href="#18"><b class="cmd">::fileutil::stripPwd</b> <i class="arg">path</i></a></li>
<li><a href="#19"><b class="cmd">::fileutil::stripPath</b> <i class="arg">prefix</i> <i class="arg">path</i></a></li>
<li><a href="#20"><b class="cmd">::fileutil::jail</b> <i class="arg">jail</i> <i class="arg">path</i></a></li>
<li><a href="#21"><b class="cmd">::fileutil::touch</b> <span class="opt">?<b class="option">-a</b>?</span> <span class="opt">?<b class="option">-c</b>?</span> <span class="opt">?<b class="option">-m</b>?</span> <span class="opt">?<b class="option">-r</b> <i class="arg">ref_file</i>?</span> <span class="opt">?<b class="option">-t</b> <i class="arg">time</i>?</span> <i class="arg">filename</i> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#22"><b class="cmd">::fileutil::tempdir</b></a></li>
<li><a href="#23"><b class="cmd">::fileutil::tempdir</b> <i class="arg">path</i></a></li>
<li><a href="#24"><b class="cmd">::fileutil::tempdirReset</b></a></li>
<li><a href="#25"><b class="cmd">::fileutil::tempfile</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#26"><b class="cmd">::fileutil::maketempdir</b> <span class="opt">?<b class="option">-prefix</b> <i class="arg">str</i>?</span> <span class="opt">?<b class="option">-suffix</b> <i class="arg">str</i>?</span> <span class="opt">?<b class="option">-dir</b> <i class="arg">str</i>?</span></a></li>
<li><a href="#27"><b class="cmd">::fileutil::relative</b> <i class="arg">base</i> <i class="arg">dst</i></a></li>
<li><a href="#28"><b class="cmd">::fileutil::relativeUrl</b> <i class="arg">base</i> <i class="arg">dst</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides implementations of standard unix utilities.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::lexnormalize</b> <i class="arg">path</i></a></dt>
<dd><p>This command performs purely lexical normalization on the <i class="arg">path</i> and returns
the changed path as its result. Symbolic links in the path are <em>not</em> resolved.</p>
<p>Examples:</p>
<pre class="doctools_example">
fileutil::lexnormalize /foo/./bar
=> /foo/bar
fileutil::lexnormalize /foo/../bar
=> /bar
</pre>
</dd>
<dt><a name="2"><b class="cmd">::fileutil::fullnormalize</b> <i class="arg">path</i></a></dt>
<dd><p>This command resolves all symbolic links in the <i class="arg">path</i> and returns
the changed path as its result.
In contrast to the builtin <b class="cmd">file normalize</b> this command
resolves a symbolic link in the last element of the path as well.</p></dd>
<dt><a name="3"><b class="cmd">::fileutil::test</b> <i class="arg">path</i> <i class="arg">codes</i> <span class="opt">?<i class="arg">msgvar</i>?</span> <span class="opt">?<i class="arg">label</i>?</span></a></dt>
<dd><p>A command for the testing of several properties of a <i class="arg">path</i>. The
properties to test for are specified in <i class="arg">codes</i>, either as a list
of keywords describing the properties, or as a string where each
letter is a shorthand for a property to test. The recognized keywords,
shorthands, and associated properties are shown in the list below. The
tests are executed in the order given to the command.</p>
<p>The result of the command is a boolean value. It will be true if and
only if the <i class="arg">path</i> passes all the specified tests.
In the case of the <i class="arg">path</i> not passing one or more test the first
failing test will leave a message in the variable referenced by
<i class="arg">msgvar</i>, if such is specified. The message will be prefixed with
<i class="arg">label</i>, if it is specified.
<em>Note</em> that the variabled referenced by <i class="arg">msgvar</i> is not touched at
all if all the tests pass.</p>
<dl class="doctools_definitions">
<dt><em>r</em>ead</dt>
<dd><p><b class="cmd">file readable</b></p></dd>
<dt><em>w</em>rite</dt>
<dd><p><b class="cmd">file writable</b></p></dd>
<dt><em>e</em>xists</dt>
<dd><p><b class="cmd">file exists</b></p></dd>
<dt>e<em>x</em>ec</dt>
<dd><p><b class="cmd">file executable</b></p></dd>
<dt><em>f</em>ile</dt>
<dd><p><b class="cmd">file isfile</b></p></dd>
<dt><em>d</em>ir</dt>
<dd><p><b class="cmd">file isdirectory</b></p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::fileutil::cat</b> (<span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i>)...</a></dt>
<dd><p>A tcl implementation of the UNIX <b class="syscmd"><a href="../../../../index.html#cat">cat</a></b> command. Returns the
contents of the specified file(s). The arguments are files to read,
with interspersed options configuring the process. If there are
problems reading any of the files, an error will occur, and no data
will be returned.</p>
<p>The options accepted are <b class="option">-encoding</b>, <b class="option">-translation</b>,
<b class="option">-eofchar</b>, and <b class="option">--</b>. With the exception of the last all
options take a single value as argument, as specified by the tcl
builtin command <b class="cmd">fconfigure</b>. The <b class="option">--</b> has to be used to
terminate option processing before a file if that file's name begins
with a dash.</p>
<p>Each file can have its own set of options coming before it, and for
anything not specified directly the defaults are inherited from the
options of the previous file. The first file inherits the system
default for unspecified options.</p></dd>
<dt><a name="5"><b class="cmd">::fileutil::writeFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">data</i></a></dt>
<dd><p>The command replaces the current contents of the specified <i class="arg">file</i>
with <i class="arg">data</i>, with the process configured by the options. The
command accepts the same options as <b class="cmd">::fileutil::cat</b>. The
specification of a non-existent file is legal and causes the command
to create the file (and all required but missing directories).</p></dd>
<dt><a name="6"><b class="cmd">::fileutil::appendToFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">data</i></a></dt>
<dd><p>This command is like <b class="cmd">::fileutil::writeFile</b>, except that the
previous contents of <i class="arg">file</i> are not replaced, but appended to. The
command accepts the same options as <b class="cmd">::fileutil::cat</b></p></dd>
<dt><a name="7"><b class="cmd">::fileutil::insertIntoFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">at</i> <i class="arg">data</i></a></dt>
<dd><p>This comment is similar to <b class="cmd">::fileutil::appendToFile</b>, except that
the new data is not appended at the end, but inserted at a specified
location within the file. In further contrast this command has to be
given the path to an existing file. It will not create a missing file,
but throw an error instead.</p>
<p>The specified location <i class="arg">at</i> has to be an integer number in the
range <b class="const">0</b> ... [file size <i class="arg">file</i>]. <b class="const">0</b> will cause
insertion of the new data before the first character of the existing
content, whereas [file size <i class="arg">file</i>] causes insertion after
the last character of the existing content, i.e. appending.</p>
<p>The command accepts the same options as <b class="cmd">::fileutil::cat</b>.</p></dd>
<dt><a name="8"><b class="cmd">::fileutil::removeFromFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">at</i> <i class="arg">n</i></a></dt>
<dd><p>This command is the complement to <b class="cmd">::fileutil::insertIntoFile</b>, removing <i class="arg">n</i> characters from the <i class="arg">file</i>, starting at location <i class="arg">at</i>.
The specified location <i class="arg">at</i> has to be an integer number in the
range <b class="const">0</b> ... [file size <i class="arg">file</i>] - <i class="arg">n</i>. <b class="const">0</b>
will cause the removal of the new data to start with the first
character of the existing content,
whereas [file size <i class="arg">file</i>] - <i class="arg">n</i> causes the removal of
the tail of the existing content, i.e. the truncation of the file.</p>
<p>The command accepts the same options as <b class="cmd">::fileutil::cat</b>.</p></dd>
<dt><a name="9"><b class="cmd">::fileutil::replaceInFile</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">at</i> <i class="arg">n</i> <i class="arg">data</i></a></dt>
<dd><p>This command is a combination of <b class="cmd">::fileutil::removeFromFile</b> and
<b class="cmd">::fileutil::insertIntoFile</b>. It first removes the part of the
contents specified by the arguments <i class="arg">at</i> and <i class="arg">n</i>, and then
inserts <i class="arg">data</i> at the given location, effectively replacing the
removed by content with <i class="arg">data</i>.
All constraints imposed on <i class="arg">at</i> and <i class="arg">n</i> by
<b class="cmd">::fileutil::removeFromFile</b> and <b class="cmd">::fileutil::insertIntoFile</b>
are obeyed.</p>
<p>The command accepts the same options as <b class="cmd">::fileutil::cat</b>.</p></dd>
<dt><a name="10"><b class="cmd">::fileutil::updateInPlace</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">file</i> <i class="arg">cmd</i></a></dt>
<dd><p>This command can be seen as the generic core functionality of
<b class="cmd">::fileutil::replaceInFile</b>.
It first reads the contents of the specified <i class="arg">file</i>, then runs the
command prefix <i class="arg">cmd</i> with that data appended to it, and at last
writes the result of that invokation back as the new contents of the
file.</p>
<p>If the executed command throws an error the <i class="arg">file</i> is not changed.</p>
<p>The command accepts the same options as <b class="cmd">::fileutil::cat</b>.</p></dd>
<dt><a name="11"><b class="cmd">::fileutil::fileType</b> <i class="arg">filename</i></a></dt>
<dd><p>An implementation of the UNIX <b class="syscmd"><a href="../../../../index.html#file">file</a></b> command, which uses
various heuristics to guess the type of a file. Returns a list
specifying as much type information as can be determined about the
file, from most general (eg, "binary" or "text") to most specific (eg,
"gif"). For example, the return value for a GIF file would be "binary
graphic gif". The command will detect the following types of files:
directory, empty, binary, text, script (with interpreter), executable
elf, executable dos, executable ne, executable pe, graphic gif, graphic
jpeg, graphic png, graphic tiff, graphic bitmap, html, xml (with doctype
if available), message pgp, binary pdf, text ps, text eps, binary
gravity_wave_data_frame, compressed bzip, compressed gzip, compressed
zip, compressed tar, audio wave, audio mpeg, and link. It further
detects doctools, doctoc, and docidx documentation files, and
tklib diagrams.</p></dd>
<dt><a name="12"><b class="cmd">::fileutil::find</b> <span class="opt">?<i class="arg">basedir</i> <span class="opt">?<i class="arg">filtercmd</i>?</span>?</span></a></dt>
<dd><p>An implementation of the unix command <b class="syscmd"><a href="../../../../index.html#find">find</a></b>. Adapted from the
Tcler's Wiki. Takes at most two arguments, the path to the directory
to start searching from and a command to use to evaluate interest in
each file. The path defaults to "<b class="file">.</b>", i.e. the current
directory. The command defaults to the empty string, which means that
all files are of interest. The command takes care <em>not</em> to
lose itself in infinite loops upon encountering circular link
structures. The result of the command is a list containing the paths
to the interesting files.</p>
<p>The <i class="arg">filtercmd</i>, if specified, is interpreted as a command prefix
and one argument is added to it, the name of the file or directory
find is currently looking at. Note that this name is <em>not</em> fully
qualified. It has to be joined it with the result of <b class="cmd">pwd</b> to get
an absolute filename.</p>
<p>The result of <i class="arg">filtercmd</i> is a boolean value that indicates if the
current file should be included in the list of interesting files.</p>
<p>Example:</p>
<pre class="doctools_example">
# find .tcl files
package require fileutil
proc is_tcl {name} {return [string match *.tcl $name]}
set tcl_files [fileutil::find . is_tcl]
</pre>
</dd>
<dt><a name="13"><b class="cmd">::fileutil::findByPattern</b> <i class="arg">basedir</i> <span class="opt">?<b class="option">-regexp</b>|<b class="option">-glob</b>?</span> <span class="opt">?<b class="option">--</b>?</span> <i class="arg">patterns</i></a></dt>
<dd><p>This command is based upon the <b class="package">TclX</b> command
<b class="cmd">recursive_glob</b>, except that it doesn't allow recursion over more
than one directory at a time. It uses <b class="cmd">::fileutil::find</b>
internally and is thus able to and does follow symbolic links,
something the <b class="package">TclX</b> command does not do. First argument is
the directory to start the search in, second argument is a list of
<i class="arg">patterns</i>. The command returns a list of all files reachable
through <i class="arg">basedir</i> whose names match at least one of the
patterns. The options before the pattern-list determine the style of
matching, either regexp or glob. glob-style matching is the default if
no options are given. Usage of the option <b class="option">--</b> stops option
processing. This allows the use of a leading '-' in the patterns.</p></dd>
<dt><a name="14"><b class="cmd">::fileutil::foreachLine</b> <i class="arg">var filename cmd</i></a></dt>
<dd><p>The command reads the file <i class="arg">filename</i> and executes the script
<i class="arg">cmd</i> for every line in the file. During the execution of the
script the variable <i class="arg">var</i> is set to the contents of the current
line. The return value of this command is the result of the last
invocation of the script <i class="arg">cmd</i> or the empty string if the file was
empty.</p></dd>
<dt><a name="15"><b class="cmd">::fileutil::grep</b> <i class="arg">pattern</i> <span class="opt">?<i class="arg">files</i>?</span></a></dt>
<dd><p>Implementation of <b class="syscmd"><a href="../../../../index.html#grep">grep</a></b>. Adapted from the Tcler's Wiki. The
first argument defines the <i class="arg">pattern</i> to search for. This is
followed by a list of <i class="arg">files</i> to search through. The list is
optional and <b class="const">stdin</b> will be used if it is missing. The result
of the procedures is a list containing the matches. Each match is a
single element of the list and contains filename, number and contents
of the matching line, separated by a colons.</p></dd>
<dt><a name="16"><b class="cmd">::fileutil::install</b> <span class="opt">?<b class="option">-m</b> <i class="arg">mode</i>?</span> <i class="arg">source</i> <i class="arg">destination</i></a></dt>
<dd><p>The <b class="cmd">install</b> command is similar in functionality to the <b class="syscmd">install</b>
command found on many unix systems, or the shell script
distributed with many source distributions (unix/install-sh in the Tcl
sources, for example). It copies <i class="arg">source</i>, which can be either a
file or directory to <i class="arg">destination</i>, which should be a directory,
unless <i class="arg">source</i> is also a single file. The <span class="opt">?-m?</span> option lets
the user specify a unix-style mode (either octal or symbolic - see
<b class="cmd">file attributes</b>.</p></dd>
<dt><a name="17"><b class="cmd">::fileutil::stripN</b> <i class="arg">path</i> <i class="arg">n</i></a></dt>
<dd><p>Removes the first <i class="arg">n</i> elements from the specified <i class="arg">path</i> and
returns the modified path. If <i class="arg">n</i> is greater than the number of
components in <i class="arg">path</i> an empty string is returned. The number of
components in a given path may be determined by performing
<b class="cmd">llength</b> on the list returned by <b class="cmd">file split</b>.</p></dd>
<dt><a name="18"><b class="cmd">::fileutil::stripPwd</b> <i class="arg">path</i></a></dt>
<dd><p>If, and only if the <i class="arg">path</i> is inside of the directory returned by
[<b class="cmd">pwd</b>] (or the current working directory itself) it is made
relative to that directory. In other words, the current working
directory is stripped from the <i class="arg">path</i>. The possibly modified path
is returned as the result of the command. If the current working
directory itself was specified for <i class="arg">path</i> the result is the string
"<b class="const">.</b>".</p></dd>
<dt><a name="19"><b class="cmd">::fileutil::stripPath</b> <i class="arg">prefix</i> <i class="arg">path</i></a></dt>
<dd><p>If, and only of the <i class="arg">path</i> is inside of the directory
"<b class="file">prefix</b>" (or the prefix directory itself) it is made relative to
that directory. In other words, the prefix directory is stripped from
the <i class="arg">path</i>. The possibly modified path is returned as the result
of the command.
If the prefix directory itself was specified for <i class="arg">path</i> the result
is the string "<b class="const">.</b>".</p></dd>
<dt><a name="20"><b class="cmd">::fileutil::jail</b> <i class="arg">jail</i> <i class="arg">path</i></a></dt>
<dd><p>This command ensures that the <i class="arg">path</i> is not escaping the directory
<i class="arg">jail</i>. It always returns an absolute path derived from <i class="arg">path</i>
which is within <i class="arg">jail</i>.</p>
<p>If <i class="arg">path</i> is an absolute path and already within <i class="arg">jail</i> it is
returned unmodified.</p>
<p>An absolute path outside of <i class="arg">jail</i> is stripped of its root element
and then put into the <i class="arg">jail</i> by prefixing it with it. The same
happens if <i class="arg">path</i> is relative, except that nothing is stripped of
it. Before adding the <i class="arg">jail</i> prefix the <i class="arg">path</i> is lexically
normalized to prevent the caller from using <b class="const">..</b> segments in
<i class="arg">path</i> to escape the jail.</p></dd>
<dt><a name="21"><b class="cmd">::fileutil::touch</b> <span class="opt">?<b class="option">-a</b>?</span> <span class="opt">?<b class="option">-c</b>?</span> <span class="opt">?<b class="option">-m</b>?</span> <span class="opt">?<b class="option">-r</b> <i class="arg">ref_file</i>?</span> <span class="opt">?<b class="option">-t</b> <i class="arg">time</i>?</span> <i class="arg">filename</i> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>Implementation of <b class="syscmd"><a href="../../../../index.html#touch">touch</a></b>. Alter the atime and mtime of the
specified files. If <b class="option">-c</b>, do not create files if they do not
already exist. If <b class="option">-r</b>, use the atime and mtime from
<i class="arg">ref_file</i>. If <b class="option">-t</b>, use the integer clock value
<i class="arg">time</i>. It is illegal to specify both <b class="option">-r</b> and
<b class="option">-t</b>. If <b class="option">-a</b>, only change the atime. If <b class="option">-m</b>,
only change the mtime.</p>
<p><em>This command is not available for Tcl versions less than 8.3.</em></p></dd>
<dt><a name="22"><b class="cmd">::fileutil::tempdir</b></a></dt>
<dd><p>The command returns the path of a directory where the caller can
place temporary files, such as "<b class="file">/tmp</b>" on Unix systems. The
algorithm we use to find the correct directory is as follows:</p>
<ol class="doctools_enumerated">
<li><p>The directory set by an invokation of <b class="cmd">::fileutil::tempdir</b> with
an argument. If this is present it is tried exclusively and none of
the following item are tried.</p></li>
<li><p>The directory named in the TMPDIR environment variable.</p></li>
<li><p>The directory named in the TEMP environment variable.</p></li>
<li><p>The directory named in the TMP environment variable.</p></li>
<li><p>A platform specific location:</p>
<dl class="doctools_definitions">
<dt>Windows</dt>
<dd><p>"<b class="file">C:\TEMP</b>", "<b class="file">C:\TMP</b>", "<b class="file">\TEMP</b>",
and "<b class="file">\TMP</b>" are tried in that order.</p></dd>
<dt>(classic) Macintosh</dt>
<dd><p>The TRASH_FOLDER environment variable is used. This is most likely
not correct.</p></dd>
<dt>Unix</dt>
<dd><p>The directories "<b class="file">/tmp</b>", "<b class="file">/var/tmp</b>", and "<b class="file">/usr/tmp</b>" are
tried in that order.</p></dd>
</dl>
</li>
</ol>
<p>The algorithm utilized is mainly that used in the Python standard
library. The exception is the first item, the ability to have the
search overridden by a user-specified directory.</p></dd>
<dt><a name="23"><b class="cmd">::fileutil::tempdir</b> <i class="arg">path</i></a></dt>
<dd><p>In this mode the command sets the <i class="arg">path</i> as the first and only
directory to try as a temp. directory. See the previous item for the
use of the set directory. The command returns the empty string.</p></dd>
<dt><a name="24"><b class="cmd">::fileutil::tempdirReset</b></a></dt>
<dd><p>Invoking this command clears the information set by the
last call of [<b class="cmd">::fileutil::tempdir</b> <i class="arg">path</i>].
See the last item too.</p></dd>
<dt><a name="25"><b class="cmd">::fileutil::tempfile</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></dt>
<dd><p>The command generates a temporary file name suitable for writing to,
and the associated file. The file name will be unique, and the file
will be writable and contained in the appropriate system specific temp
directory. The name of the file will be returned as the result of the
command.</p>
<p>The code was taken from <a href="http://wiki.tcl.tk/772">http://wiki.tcl.tk/772</a>, attributed to
Igor Volobouev and anon.</p></dd>
<dt><a name="26"><b class="cmd">::fileutil::maketempdir</b> <span class="opt">?<b class="option">-prefix</b> <i class="arg">str</i>?</span> <span class="opt">?<b class="option">-suffix</b> <i class="arg">str</i>?</span> <span class="opt">?<b class="option">-dir</b> <i class="arg">str</i>?</span></a></dt>
<dd><p>The command generates a temporary directory suitable for writing to.
The directory name will be unique, and the directory will be writable
and contained in the appropriate system specific temp directory. The
name of the directory will be returned as the result of the command.</p>
<p>The three options can used to tweak the behaviour of the command:</p>
<dl class="doctools_options">
<dt><b class="option">-prefix</b> str</dt>
<dd><p>The initial, fixed part of the directory name. Defaults to <b class="const">tmp</b> if not specified.</p></dd>
<dt><b class="option">-suffix</b> str</dt>
<dd><p>The fixed tail of the directory. Defaults to the empty string if not specified.</p></dd>
<dt><b class="option">-dir</b> str</dt>
<dd><p>The directory to place the new directory into. Defaults to the result of <b class="cmd">fileutil::tempdir</b> if not specified.</p></dd>
</dl>
<p>The initial code for this was supplied by <a href="mailto:[email protected]">Miguel Martinez Lopez</a>.</p></dd>
<dt><a name="27"><b class="cmd">::fileutil::relative</b> <i class="arg">base</i> <i class="arg">dst</i></a></dt>
<dd><p>This command takes two directory paths, both either absolute or relative
and computes the path of <i class="arg">dst</i> relative to <i class="arg">base</i>. This relative
path is returned as the result of the command. As implied in the previous
sentence, the command is not able to compute this relationship between the
arguments if one of the paths is absolute and the other relative.</p>
<p><em>Note:</em> The processing done by this command is purely lexical.
Symbolic links are <em>not</em> taken into account.</p></dd>
<dt><a name="28"><b class="cmd">::fileutil::relativeUrl</b> <i class="arg">base</i> <i class="arg">dst</i></a></dt>
<dd><p>This command takes two file paths, both either absolute or relative
and computes the path of <i class="arg">dst</i> relative to <i class="arg">base</i>, as seen
from inside of the <i class="arg">base</i>. This is the algorithm how a browser
resolves a relative link found in the currently shown file.</p>
<p>The computed relative path is returned as the result of the command.
As implied in the previous sentence, the command is not able to compute
this relationship between the arguments if one of the paths is absolute
and the other relative.</p>
<p><em>Note:</em> The processing done by this command is purely lexical.
Symbolic links are <em>not</em> taken into account.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Warnings and Incompatibilities</a></h2>
<dl class="doctools_definitions">
<dt><b class="const">1.14.9</b></dt>
<dd><p>In this version <b class="cmd">fileutil::find</b>'s broken system for handling
symlinks was replaced with one working correctly and properly
enumerating all the legal non-cyclic paths under a base directory.</p>
<p>While correct this means that certain pathological directory
hierarchies with cross-linked sym-links will now take about O(n**2)
time to enumerate whereas the original broken code managed O(n) due to
its brokenness.</p>
<p>A concrete example and extreme case is the "<b class="file">/sys</b>"
hierarchy under Linux where some hundred devices exist under both
"<b class="file">/sys/devices</b>" and "<b class="file">/sys/class</b>" with the two sub-hierarchies
linking to the other, generating millions of legal paths to enumerate.
The structure, reduced to three devices, roughly looks like</p>
<pre class="doctools_example">
/sys/class/tty/tty0 --> ../../dev/tty0
/sys/class/tty/tty1 --> ../../dev/tty1
/sys/class/tty/tty2 --> ../../dev/tty1
/sys/dev/tty0/bus
/sys/dev/tty0/subsystem --> ../../class/tty
/sys/dev/tty1/bus
/sys/dev/tty1/subsystem --> ../../class/tty
/sys/dev/tty2/bus
/sys/dev/tty2/subsystem --> ../../class/tty
</pre>
<p>The command <b class="cmd">fileutil::find</b> currently has no way to escape
this. When having to handle such a pathological hierarchy It is
recommended to switch to package <b class="package">fileutil::traverse</b> and the
same-named command it provides, and then use the <b class="option">-prefilter</b>
option to prevent the traverser from following symbolic links, like so:</p>
<pre class="doctools_example">
package require fileutil::traverse
proc NoLinks {fileName} {
if {[string equal [file type $fileName] link]} {
return 0
}
return 1
}
fileutil::traverse T /sys/devices -prefilter NoLinks
T foreach p {
puts $p
}
T destroy
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cat">cat</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#grep">grep</a>, <a href="../../../../index.html#temp_file">temp file</a>, <a href="../../../../index.html#test">test</a>, <a href="../../../../index.html#touch">touch</a>, <a href="../../../../index.html#type">type</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fileutil/multi.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<div class='fossil-doc' data-title='fileutil::multi - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil::multi(n) 0.1 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil::multi - Multi-file operation, scatter/gather, standard object</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">fileutil::multi <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">fileutil::multi::op <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">wip <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::multi</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single command to perform actions on multiple
files selected by glob patterns. It is a thin layer over the package
<b class="package"><a href="multiop.html">fileutil::multi::op</a></b> which provides objects for the
same. This package simply creates a single such object and directs all
file commands to it.</p>
<p>At the core is a domain specific language allowing the easy
specification of multi-file copy and/or move and/or deletion
operations. Alternate names would be scatter/gather processor, or
maybe even assembler.
For the detailed specification of this language, and examples, please
see the documention for the package <b class="package"><a href="multiop.html">fileutil::multi::op</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<p>The main command of the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::multi</b> <span class="opt">?<i class="arg">word</i>...?</span></a></dt>
<dd><p>This command interprets the specified words as file commands to
execute. See the section <b class="sectref">FILE API</b> of the
documentation for the package <b class="package"><a href="multiop.html">fileutil::multi::op</a></b> for
the set of acceptable commands, their syntax, and semantics.</p>
<p>The result of the command is the result generated by the last file
command it executed.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#move">move</a>, <a href="../../../../index.html#multi_file">multi-file</a>, <a href="../../../../index.html#remove">remove</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fileutil/multiop.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
|
<div class='fossil-doc' data-title='fileutil::multi::op - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil::multi::op(n) 0.5.3 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil::multi::op - Multi-file operation, scatter/gather</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">CLASS API</a></li>
<li class="doctools_section"><a href="#section3">OBJECT API</a></li>
<li class="doctools_section"><a href="#section4">FILE API</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">fileutil::multi::op <span class="opt">?0.5.3?</span></b></li>
<li>package require <b class="pkgname">wip <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::multi::op</b> <span class="opt">?<i class="arg">opName</i>?</span> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">opName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">$opName</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#4"><b class="cmd">into</b> <i class="arg">directory</i></a></li>
<li><a href="#5"><b class="cmd">in</b> <i class="arg">directory</i></a></li>
<li><a href="#6"><b class="cmd">to</b> <i class="arg">directory</i></a></li>
<li><a href="#7"><b class="cmd">from</b> <i class="arg">directory</i></a></li>
<li><a href="#8"><b class="cmd">not</b> <i class="arg">pattern</i></a></li>
<li><a href="#9"><b class="cmd">for</b> <i class="arg">pattern</i></a></li>
<li><a href="#10"><b class="cmd">exclude</b> <i class="arg">pattern</i></a></li>
<li><a href="#11"><b class="cmd">but</b></a></li>
<li><a href="#12"><b class="cmd">except</b></a></li>
<li><a href="#13"><b class="cmd">as</b> <i class="arg">name</i></a></li>
<li><a href="#14"><b class="cmd">recursive</b></a></li>
<li><a href="#15"><b class="cmd">recursively</b></a></li>
<li><a href="#16"><b class="cmd"><a href="../../../../index.html#copy">copy</a></b></a></li>
<li><a href="#17"><b class="cmd"><a href="../../../../index.html#move">move</a></b></a></li>
<li><a href="#18"><b class="cmd"><a href="../../../../index.html#remove">remove</a></b></a></li>
<li><a href="#19"><b class="cmd">expand</b></a></li>
<li><a href="#20"><b class="cmd">invoke</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#21"><b class="cmd">reset</b></a></li>
<li><a href="#22"><b class="cmd">(</b></a></li>
<li><a href="#23"><b class="cmd">)</b></a></li>
<li><a href="#24"><b class="cmd">cd</b> <i class="arg">directory</i></a></li>
<li><a href="#25"><b class="cmd">up</b></a></li>
<li><a href="#26"><b class="cmd">for-windows</b></a></li>
<li><a href="#27"><b class="cmd">for-win</b></a></li>
<li><a href="#28"><b class="cmd">for-unix</b></a></li>
<li><a href="#29"><b class="cmd">the</b> <i class="arg">pattern</i></a></li>
<li><a href="#30"><b class="cmd">the-set</b> <i class="arg">varname</i></a></li>
<li><a href="#31"><b class="cmd">-></b> <i class="arg">varname</i></a></li>
<li><a href="#32"><b class="cmd">strict</b></a></li>
<li><a href="#33"><b class="cmd">!strict</b></a></li>
<li><a href="#34"><b class="cmd">files</b></a></li>
<li><a href="#35"><b class="cmd">links</b></a></li>
<li><a href="#36"><b class="cmd">directories</b></a></li>
<li><a href="#37"><b class="cmd">dirs</b></a></li>
<li><a href="#38"><b class="cmd">all</b></a></li>
<li><a href="#39"><b class="cmd">state?</b></a></li>
<li><a href="#40"><b class="cmd">as?</b></a></li>
<li><a href="#41"><b class="cmd">excluded?</b></a></li>
<li><a href="#42"><b class="cmd">from?</b></a></li>
<li><a href="#43"><b class="cmd">into?</b></a></li>
<li><a href="#44"><b class="cmd">operation?</b></a></li>
<li><a href="#45"><b class="cmd">recursive?</b></a></li>
<li><a href="#46"><b class="cmd">strict?</b></a></li>
<li><a href="#47"><b class="cmd">type?</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects which are able to perform actions on
multiple files selected by glob patterns.</p>
<p>At the core is a domain specific language allowing the easy
specification of multi-file copy and/or move and/or deletion
operations. Alternate names would be scatter/gather processor, or
maybe even assembler.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">CLASS API</a></h2>
<p>The main command of the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::multi::op</b> <span class="opt">?<i class="arg">opName</i>?</span> <span class="opt">?<i class="arg">word</i>...?</span></a></dt>
<dd><p>The command creates a new multi-file operation object with an
associated global Tcl command whose name is <i class="arg">opName</i>. This
command can be used to invoke the various possible file operations.
It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">opName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>If the string <b class="const">%AUTO%</b> is used as the <i class="arg">opName</i> then the
package will generate a unique name on its own.</p>
<p>If one or more <i class="arg">word</i>s are specified they are interpreted as an
initial set of file commands to execute. I.e. the method <b class="method">do</b>
of the newly constructed object is implicitly invoked using the words
as its arguments.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OBJECT API</a></h2>
<p>The following methods are possible for multi-file operation objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">$opName</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></dt>
<dd><p>This method interprets the specified words as file commands to
execute. See the section <span class="sectref"><a href="#section4">FILE API</a></span> for the set of
acceptable commands, their syntax, and semantics.</p>
<p>The result of the method is the result generated by the last file
command it executed.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">FILE API</a></h2>
<p>Both object constructor and method <b class="method">do</b> take a list of words
and interpret them as file commands to execute. The names were chosen
to allow the construction of operations as sentences in near-natural
language. Most of the commands influence just the state of the object,
i.e. are simply providing the configuration used by the command
triggering the actual action.</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">into</b> <i class="arg">directory</i></a></dt>
<dd><p>Specifies the destination directory for operations.</p></dd>
<dt><a name="5"><b class="cmd">in</b> <i class="arg">directory</i></a></dt>
<dd><p>Alias for <b class="cmd">into</b>.</p></dd>
<dt><a name="6"><b class="cmd">to</b> <i class="arg">directory</i></a></dt>
<dd><p>Alias for <b class="cmd">into</b>.</p></dd>
<dt><a name="7"><b class="cmd">from</b> <i class="arg">directory</i></a></dt>
<dd><p>Specifies the source directory for operations.</p></dd>
<dt><a name="8"><b class="cmd">not</b> <i class="arg">pattern</i></a></dt>
<dd><p>Specifies a glob pattern for paths to be excluded from the operation.</p></dd>
<dt><a name="9"><b class="cmd">for</b> <i class="arg">pattern</i></a></dt>
<dd><p>Alias for <b class="cmd">not</b>.</p></dd>
<dt><a name="10"><b class="cmd">exclude</b> <i class="arg">pattern</i></a></dt>
<dd><p>Alias for <b class="cmd">not</b>.</p></dd>
<dt><a name="11"><b class="cmd">but</b></a></dt>
<dd><p>Has no arguments of its own, but looks ahead in the list of words and
executes all <b class="cmd">not</b> commands immediately following it. This allows the
construction of "but not" and "but exclude" clauses for a more natural
sounding specification of excluded paths.</p></dd>
<dt><a name="12"><b class="cmd">except</b></a></dt>
<dd><p>A semi-alias for <b class="cmd">but</b>. Has no arguments of its own, but looks
ahead in the list of words and executes all <b class="cmd">for</b> commands
immediately following it. This allows the construction of "except for"
clauses for a more natural sounding specification of excluded paths.</p></dd>
<dt><a name="13"><b class="cmd">as</b> <i class="arg">name</i></a></dt>
<dd><p>Specifies a new name for the first file handled by the current
operation. I.e. for the renaming of a single file during the
operation.</p></dd>
<dt><a name="14"><b class="cmd">recursive</b></a></dt>
<dd><p>Signals that file expansion should happen in the whole directory
hierarchy and not just the directory itself.</p></dd>
<dt><a name="15"><b class="cmd">recursively</b></a></dt>
<dd><p>An alias for <b class="cmd">recursive</b>.</p></dd>
<dt><a name="16"><b class="cmd"><a href="../../../../index.html#copy">copy</a></b></a></dt>
<dd><p>Signals that the operation is the copying of files from source to
destination directory per the specified inclusion and exclusion
patterns.</p></dd>
<dt><a name="17"><b class="cmd"><a href="../../../../index.html#move">move</a></b></a></dt>
<dd><p>Signals that the operation is the moving of files from source to
destination directory per the specified inclusion and exclusion
patterns.</p></dd>
<dt><a name="18"><b class="cmd"><a href="../../../../index.html#remove">remove</a></b></a></dt>
<dd><p>Signals that the operation is the removal of files in the destination
directory per the specified inclusion and exclusion patterns.</p></dd>
<dt><a name="19"><b class="cmd">expand</b></a></dt>
<dd><p>Signals that there is no operation but the calculation of the set of
files from the include and exclude patterns. This operation is not
available if <b class="cmd">the-set</b> is used.</p></dd>
<dt><a name="20"><b class="cmd">invoke</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Signals that the user-specified command prefix <i class="arg">cmdprefix</i> is the
operation to perform. The command prefix is executed at the global
level and given the source directory, destination directory, and set
of files (as dictionary mapping from source to destination files), in
this order.</p></dd>
<dt><a name="21"><b class="cmd">reset</b></a></dt>
<dd><p>Forces the object into the ground state where all parts of the
configuration have default values.</p></dd>
<dt><a name="22"><b class="cmd">(</b></a></dt>
<dd><p>Saves a copy of the current object state on a stack.</p></dd>
<dt><a name="23"><b class="cmd">)</b></a></dt>
<dd><p>Takes the state at the top of the state stack and restores it,
i.e. makes it the new current object state.</p></dd>
<dt><a name="24"><b class="cmd">cd</b> <i class="arg">directory</i></a></dt>
<dd><p>Changes the destination directory to the sub-directory <i class="arg">directory</i>
of the current destination.</p></dd>
<dt><a name="25"><b class="cmd">up</b></a></dt>
<dd><p>Changes the destination directory to the parent directory of the
current destination.</p></dd>
<dt><a name="26"><b class="cmd">for-windows</b></a></dt>
<dd><p>Checks that Windows is the current platform. Aborts processing if not.</p></dd>
<dt><a name="27"><b class="cmd">for-win</b></a></dt>
<dd><p>An alias for <b class="cmd">for-windows</b>.</p></dd>
<dt><a name="28"><b class="cmd">for-unix</b></a></dt>
<dd><p>Checks that Unix is the current platform. Aborts processing if not.</p></dd>
<dt><a name="29"><b class="cmd">the</b> <i class="arg">pattern</i></a></dt>
<dd><p>This command specifies the files to operate on per a glob pattern, and
is also the active element, i.e. the command which actually performs
the specified operation. All the other commands only modified the
object state to set the operation up, but di nothing else.</p>
<p>To allow for a more natural sounding syntax this command also looks
ahead in the list of words looks and executes several commands
immediately following it before performing its own actions.
These commands are <b class="cmd">as</b>, <b class="cmd">but</b>, <b class="cmd">exclude</b>, <b class="cmd">except</b>,
<b class="cmd">from</b>, and <b class="cmd">into</b> (and aliases). That way these commands act
like qualifiers, and still take effect as if they had been written
before this command.</p>
<p>After the operation has been performed the object state the exclude
patterns and the alias name, if specified, are reset to their default
values (i.e. empty), but nothing else.</p></dd>
<dt><a name="30"><b class="cmd">the-set</b> <i class="arg">varname</i></a></dt>
<dd><p>Like <b class="cmd">the</b>, however the set of files to use is not specified
implicitly per a glob pattern, but contained and loaded from the
specified variable. The operation <b class="cmd">expand</b> is not available
if this command is used.</p></dd>
<dt><a name="31"><b class="cmd">-></b> <i class="arg">varname</i></a></dt>
<dd><p>Saves the set of files from the last expansion into the specified
variable.</p></dd>
<dt><a name="32"><b class="cmd">strict</b></a></dt>
<dd><p>Make file expansion and definition of destination directory (<b class="cmd">in</b>
and aliases) strict, i.e. report errors for missing directories, and
empty expansion.</p></dd>
<dt><a name="33"><b class="cmd">!strict</b></a></dt>
<dd><p>Complement of <b class="cmd">strict</b>. A missing destination directory or empty
expansion are not reported as errors.</p></dd>
<dt><a name="34"><b class="cmd">files</b></a></dt>
<dd><p>Limit the search to files. Default is to accept every type of path.</p></dd>
<dt><a name="35"><b class="cmd">links</b></a></dt>
<dd><p>Limit the search to symbolic links. Default is to accept every type of path.</p></dd>
<dt><a name="36"><b class="cmd">directories</b></a></dt>
<dd><p>Limit the search to directories. Default is to accept every type of path.</p></dd>
<dt><a name="37"><b class="cmd">dirs</b></a></dt>
<dd><p>An alias for <b class="cmd">directories</b>.</p></dd>
<dt><a name="38"><b class="cmd">all</b></a></dt>
<dd><p>Accept all types of paths (default).</p></dd>
<dt><a name="39"><b class="cmd">state?</b></a></dt>
<dd><p>Returns the current state of the object as dictionary. The dictionary keys and their meanings are:</p>
<dl class="doctools_definitions">
<dt><b class="const">as</b></dt>
<dd><p>Last setting made by <b class="cmd">as</b>.</p></dd>
<dt><b class="const">excluded</b></dt>
<dd><p>List of currently known exclusion patterns.</p></dd>
<dt><b class="const">from</b></dt>
<dd><p>Current source directory, set by <b class="cmd">from</b>.</p></dd>
<dt><b class="const">into</b></dt>
<dd><p>Current destination directory, set by <b class="cmd">into</b> (and aliases).</p></dd>
<dt><b class="const">operation</b></dt>
<dd><p>Current operation to perform, set by <b class="cmd"><a href="../../../../index.html#copy">copy</a></b>, <b class="cmd"><a href="../../../../index.html#move">move</a></b>, <b class="cmd"><a href="../../../../index.html#remove">remove</a></b>, <b class="cmd">expand</b>, or <b class="cmd">invoke</b>.</p></dd>
<dt><b class="const">recursive</b></dt>
<dd><p>Current recursion status. Set/unset by <b class="cmd">recursive</b> and <b class="cmd">!recursive</b>.</p></dd>
<dt><b class="const">strict</b></dt>
<dd><p>Current strictness. Set/unset by <b class="cmd">strict</b> and <b class="cmd">!strict</b>.</p></dd>
<dt><b class="const">type</b></dt>
<dd><p>Current path type limiter. Set by either <b class="cmd">files</b>, <b class="cmd">directories</b>, <b class="cmd">links</b>, or <b class="cmd">all</b>.</p></dd>
</dl></dd>
<dt><a name="40"><b class="cmd">as?</b></a></dt>
<dd><p>Returns the current alias name.</p></dd>
<dt><a name="41"><b class="cmd">excluded?</b></a></dt>
<dd><p>Returns the current set of exclusion patterns.</p></dd>
<dt><a name="42"><b class="cmd">from?</b></a></dt>
<dd><p>Returns the current source directory.</p></dd>
<dt><a name="43"><b class="cmd">into?</b></a></dt>
<dd><p>Returns the current destination directory.</p></dd>
<dt><a name="44"><b class="cmd">operation?</b></a></dt>
<dd><p>Returns the current operation to perform.</p></dd>
<dt><a name="45"><b class="cmd">recursive?</b></a></dt>
<dd><p>Returns the current recursion status.</p></dd>
<dt><a name="46"><b class="cmd">strict?</b></a></dt>
<dd><p>Returns the current strictness.</p></dd>
<dt><a name="47"><b class="cmd">type?</b></a></dt>
<dd><p>Returns the current path type limiter.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>The following examples assume that the variable <b class="variable">F</b> contains a
reference to a multi-file operation object.</p>
<pre class="doctools_example">
$F do copy \\
the *.dll \\
from c:/TDK/PrivateOpenSSL/bin \\
to [installdir_of tls]
</pre>
<pre class="doctools_example">
$F do move \\
the * \\
from /sources \\
into /scratch \\
but not *.html
# Alternatively use 'except for *.html'.
</pre>
<pre class="doctools_example">
$F do \\
move \\
the index \\
from /sources \\
into /scratch \\
as pkgIndex.tcl
</pre>
<pre class="doctools_example">
$F do \\
remove \\
the *.txt \\
in /scratch
</pre>
<p>Note that the fact that most commands just modify the object state
allows us to use more off forms as specifications instead of just
nearly-natural language sentences.
For example the second example in this section can re-arranged into:</p>
<pre class="doctools_example">
$F do \\
from /sources \\
into /scratch \\
but not *.html \\
move \\
the *
</pre>
<p>and the result is not only still a valid specification, but even stays
relatively readable.</p>
<p>Further note that the information collected by the commands <b class="cmd">but</b>,
<b class="cmd">except</b>, and <b class="cmd">as</b> is automatically reset after the associated
<b class="cmd">the</b> was executed. However no other state is reset in that
manner, allowing the user to avoid repetitions of unchanging
information. For example the second and third examples of this section
can be merged and rewritten into the equivalent:</p>
<pre class="doctools_example">
$F do \\
move \\
the * \\
from /sources \\
into /scratch \\
but not *.html not index \\
the index \\
as pkgIndex.tcl
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#move">move</a>, <a href="../../../../index.html#multi_file">multi-file</a>, <a href="../../../../index.html#remove">remove</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fileutil/traverse.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
|
<div class='fossil-doc' data-title='fileutil_traverse - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil_traverse(n) 0.6 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil_traverse - Iterative directory traversal</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OPTIONS</a></li>
<li class="doctools_section"><a href="#section3">Warnings and Incompatibilities</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">fileutil::traverse <span class="opt">?0.6?</span></b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">control</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::traverse</b> <span class="opt">?<i class="arg">objectName</i>?</span> <i class="arg">path</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">$traverser</b> <b class="method">command</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">$traverser</b> <b class="method">files</b></a></li>
<li><a href="#4"><b class="cmd">$traverser</b> <b class="method">foreach</b> <i class="arg">filevar</i> <i class="arg">script</i></a></li>
<li><a href="#5"><b class="cmd">$traverser</b> <b class="method">next</b> <i class="arg">filevar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects for the programmable traversal of
directory hierarchies.
The main command exported by the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::traverse</b> <span class="opt">?<i class="arg">objectName</i>?</span> <i class="arg">path</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p>The command creates a new traversal object with an associated global
Tcl command whose name is <i class="arg">objectName</i>. This command may be used
to invoke various operations on the traverser.
If the string <b class="const">%AUTO%</b> is used as the <i class="arg">objectName</i> then a
unique name will be generated by the package itself.</p>
<p>Regarding the recognized options see section <span class="sectref"><a href="#section2">OPTIONS</a></span>. Note
that all these options can be set only during the creation of the
traversal object. Changing them later is not possible and causes
errors to be thrown if attempted.</p>
<p>The object command has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">$traverser</b> <b class="method">command</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Command</i> and its <i class="arg">arg</i>uments determine the exact behavior of
the object.</p></dd>
</dl></dd>
</dl>
<p>The following commands are possible for traversal objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">$traverser</b> <b class="method">files</b></a></dt>
<dd><p>This method is the most highlevel one provided by traversal
objects. When invoked it returns a list containing the names of all
files and directories matching the current configuration of the
traverser.</p></dd>
<dt><a name="4"><b class="cmd">$traverser</b> <b class="method">foreach</b> <i class="arg">filevar</i> <i class="arg">script</i></a></dt>
<dd><p>The highlevel <b class="method">files</b> method (see above) is based on this
mid-level method. When invoked it finds all files and directories
matching per the current configuration and executes the <i class="arg">script</i>
for each path. The current path under consideration is stored in the
variable named by <i class="arg">filevar</i>. Both variable and script live / are
executed in the context of the caller of the method. In the method
<b class="method">files</b> the script simply saves the found paths into the list
to return.</p></dd>
<dt><a name="5"><b class="cmd">$traverser</b> <b class="method">next</b> <i class="arg">filevar</i></a></dt>
<dd><p>This is the lowest possible interface to the traverser, the core all
higher methods are built on. When invoked it returns a boolean value
indicating whether it found a path matching the current configuration
(<b class="const">True</b>), or not (<b class="const">False</b>). If a path was found it is
stored into the variable named by <i class="arg">filevar</i>, in the context of the
caller.</p>
<p>The <b class="method">foreach</b> method simply calls this method in a loop
until it returned <b class="const">False</b>. This method is exposed so that we are
also able to incrementally traverse a directory hierarchy in an
event-based manner.</p>
<p>Note that the traverser does follow symbolic links, except when
doing so would cause it to enter a link-cycle. In other words, the
command takes care to <em>not</em> lose itself in infinite loops upon
encountering circular link structures. Note that even links which are
not followed will still appear in the result.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OPTIONS</a></h2>
<dl class="doctools_options">
<dt><b class="option">-prefilter</b> command_prefix</dt>
<dd><p>This callback is executed for directories. Its result determines if
the traverser recurses into the directory or not. The default is to
always recurse into all directories. The callback is invoked with a
single argument, the <em>absolute</em> path of the directory, and has to
return a boolean value, <b class="const">True</b> when the directory passes the
filter, and <b class="const">False</b> if not.</p></dd>
<dt><b class="option">-filter</b> command_prefix</dt>
<dd><p>This callback is executed for all paths. Its result determines if the
current path is a valid result, and returned by <b class="method">next</b>. The
default is to accept all paths as valid. The callback is invoked with
a single argument, the <em>absolute</em> path to check, and has to
return a boolean value, <b class="const">True</b> when the path passes the filter,
and <b class="const">False</b> if not.</p></dd>
<dt><b class="option">-errorcmd</b> command_prefix</dt>
<dd><p>This callback is executed for all paths the traverser has trouble
with. Like being unable to change into them, get their status,
etc. The default is to ignore any such problems. The callback is
invoked with a two arguments, the <em>absolute</em> path for which the
error occured, and the error message. Errors thrown by the filter
callbacks are handled through this callback too. Errors thrown by the
error callback itself are not caught and ignored, but allowed to pass
to the caller, i.e. however invoked the <b class="method">next</b>. Any other
results from the callback are ignored.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Warnings and Incompatibilities</a></h2>
<dl class="doctools_definitions">
<dt><b class="const">0.4.4</b></dt>
<dd><p>In this version the traverser's broken system for handling symlinks
was replaced with one working correctly and properly enumerating all
the legal non-cyclic paths under a base directory.</p>
<p>While correct this means that certain pathological directory
hierarchies with cross-linked sym-links will now take about O(n**2)
time to enumerate whereas the original broken code managed O(n) due to
its brokenness.</p>
<p>A concrete example and extreme case is the "<b class="file">/sys</b>"
hierarchy under Linux where some hundred devices exist under both
"<b class="file">/sys/devices</b>" and "<b class="file">/sys/class</b>" with the two sub-hierarchies
linking to the other, generating millions of legal paths to enumerate.
The structure, reduced to three devices, roughly looks like</p>
<pre class="doctools_example">
/sys/class/tty/tty0 --> ../../dev/tty0
/sys/class/tty/tty1 --> ../../dev/tty1
/sys/class/tty/tty2 --> ../../dev/tty1
/sys/dev/tty0/bus
/sys/dev/tty0/subsystem --> ../../class/tty
/sys/dev/tty1/bus
/sys/dev/tty1/subsystem --> ../../class/tty
/sys/dev/tty2/bus
/sys/dev/tty2/subsystem --> ../../class/tty
</pre>
<p>When having to handle such a pathological hierarchy it is
recommended to use the <b class="option">-prefilter</b> option to prevent the
traverser from following symbolic links, like so:</p>
<pre class="doctools_example">
package require fileutil::traverse
proc NoLinks {fileName} {
if {[string equal [file type $fileName] link]} {
return 0
}
return 1
}
fileutil::traverse T /sys/devices -prefilter NoLinks
T foreach p {
puts $p
}
T destroy
</pre>
</dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#directory_traversal">directory traversal</a>, <a href="../../../../index.html#traversal">traversal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ftp/ftp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
|
<div class='fossil-doc' data-title='ftp - ftp client'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ftp(n) 2.4.13 tcllib "ftp client"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ftp - Client-side tcl implementation of the ftp protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">BUGS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">ftp <span class="opt">?2.4.13?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ftp::Open</b> <i class="arg">server</i> <i class="arg">user</i> <i class="arg">passwd</i> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::ftp::Close</b> <i class="arg">handle</i></a></li>
<li><a href="#3"><b class="cmd">::ftp::Cd</b> <i class="arg">handle</i> <i class="arg">directory</i></a></li>
<li><a href="#4"><b class="cmd">::ftp::Pwd</b> <i class="arg">handle</i></a></li>
<li><a href="#5"><b class="cmd">::ftp::Type</b> <i class="arg">handle</i> <span class="opt">?<b class="const">ascii|binary|tenex</b>?</span></a></li>
<li><a href="#6"><b class="cmd">::ftp::List</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::ftp::NList</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">directory</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::ftp::FileSize</b> <i class="arg">handle</i> <i class="arg">file</i></a></li>
<li><a href="#9"><b class="cmd">::ftp::ModTime</b> <i class="arg">handle</i> <i class="arg">file</i></a></li>
<li><a href="#10"><b class="cmd">::ftp::Delete</b> <i class="arg">handle</i> <i class="arg">file</i></a></li>
<li><a href="#11"><b class="cmd">::ftp::Rename</b> <i class="arg">handle</i> <i class="arg">from</i> <i class="arg">to</i></a></li>
<li><a href="#12"><b class="cmd">::ftp::Put</b> <i class="arg">handle</i> (<i class="arg">local</i> | -data <i class="arg">data</i> | -channel <i class="arg">chan</i>) <span class="opt">?<i class="arg">remote</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::ftp::Append</b> <i class="arg">handle</i> (<i class="arg">local</i> | -data <i class="arg">data</i> | -channel <i class="arg">chan</i>) <span class="opt">?<i class="arg">remote</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::ftp::Get</b> <i class="arg">handle</i> <i class="arg">remote</i> <span class="opt">?(<i class="arg">local</i> | -variable <i class="arg">varname</i> | -channel <i class="arg">chan</i>)?</span></a></li>
<li><a href="#15"><b class="cmd">::ftp::Reget</b> <i class="arg">handle</i> <i class="arg">remote</i> <span class="opt">?<i class="arg">local</i>?</span> <span class="opt">?<i class="arg">from</i>?</span> <span class="opt">?<i class="arg">to</i>?</span></a></li>
<li><a href="#16"><b class="cmd">::ftp::Newer</b> <i class="arg">handle</i> <i class="arg">remote</i> <span class="opt">?<i class="arg">local</i>?</span></a></li>
<li><a href="#17"><b class="cmd">::ftp::MkDir</b> <i class="arg">handle</i> <i class="arg">directory</i></a></li>
<li><a href="#18"><b class="cmd">::ftp::RmDir</b> <i class="arg">handle</i> <i class="arg">directory</i></a></li>
<li><a href="#19"><b class="cmd">::ftp::Quote</b> <i class="arg">handle</i> <i class="arg">arg1</i> <i class="arg">arg2</i> <i class="arg">...</i></a></li>
<li><a href="#20"><b class="cmd">::ftp::DisplayMsg</b> <i class="arg">handle</i> <i class="arg">msg</i> <span class="opt">?<i class="arg">state</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The ftp package provides the client side of the ftp protocol as
specified in RFC 959 (<a href="http://www.rfc-editor.org/rfc/rfc959.txt">http://www.rfc-editor.org/rfc/rfc959.txt</a>).
The package implements both active (default) and passive ftp sessions.</p>
<p>A new ftp session is started with the <b class="cmd">::ftp::Open</b> command. To
shutdown an existing ftp session use <b class="cmd">::ftp::Close</b>. All other
commands are restricted to usage in an an open ftp session. They will
generate errors if they are used out of context. The ftp package
includes file and directory manipulating commands for remote sites. To
perform the same operations on the local site use commands built into
the core, like <b class="cmd">cd</b> or <b class="cmd"><a href="../../../../index.html#file">file</a></b>.</p>
<p>The output of the package is controlled by two state variables,
<b class="variable">::ftp::VERBOSE</b> and <b class="variable">::ftp::DEBUG</b>. Setting
<b class="variable">::ftp::VERBOSE</b> to "1" forces the package to show all responses
from a remote server. The default value is "0". Setting
<b class="variable">::ftp::DEBUG</b> to "1" enables debugging and forces the package to
show all return codes, states, state changes and "real" ftp
commands. The default value is "0".</p>
<p>The command <b class="cmd">::ftp::DisplayMsg</b> is used to show the different
messages from the ftp session. The setting of <b class="variable">::ftp::VERBOSE</b>
determines if this command is called or not. The current
implementation of the command uses the <b class="package"><a href="../log/log.html">log</a></b> package of tcllib
to write the messages to their final destination. This means that the
behaviour of <b class="cmd">::ftp::DisplayMsg</b> can be customized without
changing its implementation. For more radical changes overwriting its
implementation by the application is of course still possible. Note
that the default implementation honors the option <b class="option">-output</b> to
<b class="cmd">::ftp::Open</b> for a session specific log command.</p>
<p><em>Caution</em>: The default implementation logs error messages like
all other messages. If this behaviour is changed to throwing an error
instead all commands in the API will change their behaviour too. In
such a case they will not return a failure code as described below but
pass the thrown error to their caller.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ftp::Open</b> <i class="arg">server</i> <i class="arg">user</i> <i class="arg">passwd</i> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>This command is used to start a FTP session by establishing a control
connection to the FTP server. The defaults are used for any option not
specified by the caller.</p>
<p>The command takes a host name <i class="arg">server</i>, a user name <i class="arg">user</i> and
a password <i class="arg">password</i> as its parameters and returns a session
handle that is an integer number greater than or equal to "0", if the
connection is successfully established. Otherwise it returns "-1".
The <i class="arg">server</i> parameter must be the name or internet address (in
dotted decimal notation) of the ftp server to connect to. The
<i class="arg">user</i> and <i class="arg">passwd</i> parameters must contain a valid user name
and password to complete the login process.</p>
<p>The options overwrite some default values or set special abilities:</p>
<dl class="doctools_definitions">
<dt><b class="option">-blocksize</b> <i class="arg">size</i></dt>
<dd><p>The blocksize is used during data transfer. At most <i class="arg">size</i> bytes
are transfered at once. The default value for this option is 4096.
The package will evaluate the <b class="cmd">-progress callback</b> for the
session after the transfer of each block.</p></dd>
<dt><b class="option">-timeout</b> <i class="arg">seconds</i></dt>
<dd><p>If <i class="arg">seconds</i> is non-zero, then <b class="cmd">::ftp::Open</b> sets up a timeout
which will occur after the specified number of seconds. The default
value is 600.</p></dd>
<dt><b class="option">-port</b> <i class="arg">number</i></dt>
<dd><p>The port <i class="arg">number</i> specifies an alternative remote port on the ftp
server on which the ftp service resides. Most ftp services listen for
connection requests on the default port 21. Sometimes, usually for
security reasons, port numbers other than 21 are used for ftp
connections.</p></dd>
<dt><b class="option">-mode</b> <i class="arg">mode</i></dt>
<dd><p>The transfer <i class="arg">mode</i> option determines if a file transfer occurs in
<b class="const">active</b> or <b class="const">passive</b> mode. In passive mode the client
will ask the ftp server to listen on a data port and wait for the
connection rather than to initiate the process by itself when a data
transfer request comes in. Passive mode is normally a requirement when
accessing sites via a firewall. The default mode is <b class="const">active</b>.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">callback</i></dt>
<dd><p>This <i class="arg">callback</i> is evaluated whenever a block of data was
transfered. See the option <b class="option">-blocksize</b> for how to specify the
size of the transfered blocks.</p>
<p>When evaluating the <i class="arg">callback</i> one argument is appended to the
callback script, the current accumulated number of bytes transferred
so far.</p></dd>
<dt><b class="option">-command</b> <i class="arg">callback</i></dt>
<dd><p>Specifying this option places the connection into asynchronous
mode. The <i class="arg">callback</i> is evaluated after the completion of any
operation. When an operation is running no further operations must be
started until a callback has been received for the currently executing
operation.</p>
<p>When evaluating the <i class="arg">callback</i> several arguments are appended to
the callback script, namely the keyword of the operation that has
completed and any additional arguments specific to the operation. If
an error occurred during the execution of the operation the callback is
given the keyword <b class="const">error</b>.</p></dd>
<dt><b class="option">-output</b> <i class="arg">callback</i></dt>
<dd><p>This option has no default. If it is set the default implementation of
<b class="cmd">::ftp::DisplayMsg</b> will use its value as command prefix to log
all internal messages. The callback will have three arguments appended
to it before evaluation, the id of the session, the message itself,
and the connection state, in this order.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::ftp::Close</b> <i class="arg">handle</i></a></dt>
<dd><p>This command terminates the specified ftp session. If no file transfer
is in progress, the server will close the control connection
immediately. If a file transfer is in progress however, the control
connection will remain open until the transfers completes. When that
happens the server will write the result response for the transfer to
it and close the connection afterward.</p></dd>
<dt><a name="3"><b class="cmd">::ftp::Cd</b> <i class="arg">handle</i> <i class="arg">directory</i></a></dt>
<dd><p>This command changes the current working directory on the ftp server
to a specified target <i class="arg">directory</i>. The command returns 1 if the
current working directory was successfully changed to the specified
directory or 0 if it fails. The target directory can be</p>
<ul class="doctools_itemized">
<li><p>a subdirectory of the current directory,</p></li>
<li><p>Two dots, <b class="const">..</b> (as an indicator for the parent directory of
the current directory)</p></li>
<li><p>or a fully qualified path to a new working directory.</p></li>
</ul></dd>
<dt><a name="4"><b class="cmd">::ftp::Pwd</b> <i class="arg">handle</i></a></dt>
<dd><p>This command returns the complete path of the current working
directory on the ftp server, or an empty string in case of an error.</p></dd>
<dt><a name="5"><b class="cmd">::ftp::Type</b> <i class="arg">handle</i> <span class="opt">?<b class="const">ascii|binary|tenex</b>?</span></a></dt>
<dd><p>This command sets the ftp file transfer type to either <b class="const">ascii</b>,
<b class="const">binary</b>, or <b class="const">tenex</b>. The command always returns the
currently set type. If called without type no change is made.</p>
<p>Currently only <b class="const">ascii</b> and <b class="const">binary</b> types are
supported. There is some early (alpha) support for Tenex mode. The
type <b class="const">ascii</b> is normally used to convert text files into a
format suitable for text editors on the platform of the destination
machine. This mainly affects end-of-line markers. The type
<b class="const">binary</b> on the other hand allows the undisturbed transfer of
non-text files, such as compressed files, images and executables.</p></dd>
<dt><a name="6"><b class="cmd">::ftp::List</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>This command returns a human-readable list of files. Wildcard
expressions such as "<b class="file">*.tcl</b>" are allowed. If <i class="arg">pattern</i>
refers to a specific directory, then the contents of that directory
are returned. If the <i class="arg">pattern</i> is not a fully-qualified path
name, the command lists entries relative to the current remote
directory. If no <i class="arg">pattern</i> is specified, the contents of the
current remote directory is returned.</p>
<p>The listing includes any system-dependent information that the server
chooses to include. For example most UNIX systems produce output from
the command <b class="syscmd">ls -l</b>. The command returns the retrieved
information as a tcl list with one item per entry. Empty lines and
UNIX's "total" lines are ignored and not included in the result as
reported by this command.</p>
<p>If the command fails an empty list is returned.</p></dd>
<dt><a name="7"><b class="cmd">::ftp::NList</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">directory</i>?</span></a></dt>
<dd><p>This command has the same behavior as the <b class="cmd">::ftp::List</b> command,
except that it only retrieves an abbreviated listing. This means only
file names are returned in a sorted list.</p></dd>
<dt><a name="8"><b class="cmd">::ftp::FileSize</b> <i class="arg">handle</i> <i class="arg">file</i></a></dt>
<dd><p>This command returns the size of the specified <i class="arg">file</i> on the ftp
server. If the command fails an empty string is returned.</p>
<p><em>ATTENTION!</em> It will not work properly when in ascii mode and
is not supported by all ftp server implementations.</p></dd>
<dt><a name="9"><b class="cmd">::ftp::ModTime</b> <i class="arg">handle</i> <i class="arg">file</i></a></dt>
<dd><p>This command retrieves the time of the last modification of the
<i class="arg">file</i> on the ftp server as a system dependent integer value in
seconds or an empty string if an error occurred. Use the built-in
command <b class="cmd">clock</b> to convert the retrieves value into other formats.</p></dd>
<dt><a name="10"><b class="cmd">::ftp::Delete</b> <i class="arg">handle</i> <i class="arg">file</i></a></dt>
<dd><p>This command deletes the specified <i class="arg">file</i> on the ftp server. The
command returns 1 if the specified file was successfully deleted or 0
if it failed.</p></dd>
<dt><a name="11"><b class="cmd">::ftp::Rename</b> <i class="arg">handle</i> <i class="arg">from</i> <i class="arg">to</i></a></dt>
<dd><p>This command renames the file <i class="arg">from</i> in the current directory of
the ftp server to the specified new file name <i class="arg">to</i>. This new file
name must not be the same as any existing subdirectory or file name.
The command returns 1 if the specified file was successfully renamed
or 0 if it failed.</p></dd>
<dt><a name="12"><b class="cmd">::ftp::Put</b> <i class="arg">handle</i> (<i class="arg">local</i> | -data <i class="arg">data</i> | -channel <i class="arg">chan</i>) <span class="opt">?<i class="arg">remote</i>?</span></a></dt>
<dd><p>This command transfers a local file <i class="arg">local</i> to a remote file
<i class="arg">remote</i> on the ftp server. If the file parameters passed to the
command do not fully qualified path names the command will use the
current directory on local and remote host. If the remote file name is
unspecified, the server will use the name of the local file as the
name of the remote file. The command returns 1 to indicate a successful
transfer and 0 in the case of a failure.</p>
<p>If <b class="option">-data</b> <i class="arg">data</i> is specified instead of a local file, the
system will not transfer a file, but the <i class="arg">data</i> passed into it. In
this case the name of the remote file has to be specified.</p>
<p>If <b class="option">-channel</b> <i class="arg">chan</i> is specified instead of a local file,
the system will not transfer a file, but read the contents of the
channel <i class="arg">chan</i> and write this to the remote file. In this case the
name of the remote file has to be specified. After the transfer
<i class="arg">chan</i> will be closed.</p></dd>
<dt><a name="13"><b class="cmd">::ftp::Append</b> <i class="arg">handle</i> (<i class="arg">local</i> | -data <i class="arg">data</i> | -channel <i class="arg">chan</i>) <span class="opt">?<i class="arg">remote</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::ftp::Puts</b>, but appends the
transfered information to the remote file. If the file did not exist
on the server it will be created.</p></dd>
<dt><a name="14"><b class="cmd">::ftp::Get</b> <i class="arg">handle</i> <i class="arg">remote</i> <span class="opt">?(<i class="arg">local</i> | -variable <i class="arg">varname</i> | -channel <i class="arg">chan</i>)?</span></a></dt>
<dd><p>This command retrieves a remote file <i class="arg">remote</i> on the ftp server
and stores its contents into the local file <i class="arg">local</i>. If the file
parameters passed to the command are not fully qualified path names
the command will use the current directory on local and remote
host. If the local file name is unspecified, the server will use the
name of the remote file as the name of the local file. The command
returns 1 to indicate a successful transfer and 0 in the case of a
failure. The command will throw an error if the directory the file
<i class="arg">local</i> is to be placed in does not exist.</p>
<p>If <b class="option">-variable</b> <i class="arg">varname</i> is specified, the system will
store the retrieved data into the variable <i class="arg">varname</i> instead of a
file.</p>
<p>If <b class="option">-channel</b> <i class="arg">chan</i> is specified, the system will write
the retrieved data into the channel <i class="arg">chan</i> instead of a file. The
system will <em>not</em> close <i class="arg">chan</i> after the transfer, this is
the responsibility of the caller to <b class="cmd">::ftp::Get</b>.</p></dd>
<dt><a name="15"><b class="cmd">::ftp::Reget</b> <i class="arg">handle</i> <i class="arg">remote</i> <span class="opt">?<i class="arg">local</i>?</span> <span class="opt">?<i class="arg">from</i>?</span> <span class="opt">?<i class="arg">to</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::ftp::Get</b>, except that if local file
<i class="arg">local</i> exists and is smaller than remote file <i class="arg">remote</i>, the
local file is presumed to be a partially transferred copy of the
remote file and the transfer is continued from the apparent point of
failure. The command will throw an error if the directory the file
<i class="arg">local</i> is to be placed in does not exist. This command is useful
when transferring very large files over networks that tend to drop
connections.</p>
<p>Specifying the additional byte offsets <i class="arg">from</i> and <i class="arg">to</i> will
cause the command to change its behaviour and to download exactly the
specified slice of the remote file. This mode is possible only if a
local destination is explicitly provided. Omission of <i class="arg">to</i> leads
to downloading till the end of the file.</p></dd>
<dt><a name="16"><b class="cmd">::ftp::Newer</b> <i class="arg">handle</i> <i class="arg">remote</i> <span class="opt">?<i class="arg">local</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::ftp::Get</b>, except that it retrieves
the remote file only if the modification time of the remote file is
more recent than the file on the local system. If the file does not
exist on the local system, the remote file is considered newer. The
command will throw an error if the directory the file <i class="arg">local</i> is
to be placed in does not exist.</p></dd>
<dt><a name="17"><b class="cmd">::ftp::MkDir</b> <i class="arg">handle</i> <i class="arg">directory</i></a></dt>
<dd><p>This command creates the specified <i class="arg">directory</i> on the ftp
server. If the specified path is relative the new directory will be
created as a subdirectory of the current working directory. Else the
created directory will have the specified path name. The command
returns 1 to indicate a successful creation of the directory and 0 in
the case of a failure.</p></dd>
<dt><a name="18"><b class="cmd">::ftp::RmDir</b> <i class="arg">handle</i> <i class="arg">directory</i></a></dt>
<dd><p>This command removes the specified directory on the ftp server. The
remote directory has to be empty or the command will fail. The command
returns 1 to indicate a successful removal of the directory and 0 in
the case of a failure.</p></dd>
<dt><a name="19"><b class="cmd">::ftp::Quote</b> <i class="arg">handle</i> <i class="arg">arg1</i> <i class="arg">arg2</i> <i class="arg">...</i></a></dt>
<dd><p>This command is used to send an arbitrary ftp command to the
server. It cannot be used to obtain a directory listing or for
transferring files. It is included to allow an application to execute
commands on the ftp server which are not provided by this package.
The arguments are sent verbatim, i.e. as is, with no changes.</p>
<p>In contrast to the other commands in this package this command will
not parse the response it got from the ftp server but return it
verbatim to the caller.</p></dd>
<dt><a name="20"><b class="cmd">::ftp::DisplayMsg</b> <i class="arg">handle</i> <i class="arg">msg</i> <span class="opt">?<i class="arg">state</i>?</span></a></dt>
<dd><p>This command is used by the package itself to show the different
messages from the ftp sessions. The package itself declares this
command very simple, writing the messages to <b class="const">stdout</b> (if
<b class="variable">::ftp::VERBOSE</b> was set, see below) and throwing tcl errors for
error messages. It is the responsibility of the application to
overwrite it as needed. A state variable for different states assigned
to different colors is recommended by the author. The package
<b class="package"><a href="../log/log.html">log</a></b> is useful for this.</p></dd>
<dt><b class="variable">::ftp::VERBOSE</b></dt>
<dd><p>A state variable controlling the output of the package. Setting
<b class="variable">::ftp::VERBOSE</b> to "1" forces the package to show all responses
from a remote server. The default value is "0".</p></dd>
<dt><b class="variable">::ftp::DEBUG</b></dt>
<dd><p>A state variable controlling the output of ftp. Setting
<b class="variable">::ftp::DEBUG</b> to "1" enables debugging and forces the package to
show all return codes, states, state changes and "real" ftp
commands. The default value is "0".</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">BUGS</a></h2>
<p>The correct execution of many commands depends upon the proper
behavior by the remote server, network and router configuration.</p>
<p>An update command placed in the procedure <b class="cmd">::ftp::DisplayMsg</b> may
run into persistent errors or infinite loops. The solution to this
problem is to use <b class="cmd">update idletasks</b> instead of <b class="cmd"><a href="../../../../index.html#update">update</a></b>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ftp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../ftpd/ftpd.html">ftpd</a>, <a href="../mime/mime.html">mime</a>, <a href="../pop3/pop3.html">pop3</a>, <a href="../mime/smtp.html">smtp</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ftp">ftp</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#net">net</a>, <a href="../../../../index.html#rfc_959">rfc 959</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ftp/ftp_geturl.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<div class='fossil-doc' data-title='ftp::geturl - ftp client'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ftp::geturl(n) 0.2.2 tcllib "ftp client"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ftp::geturl - Uri handler for ftp urls</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">ftp::geturl <span class="opt">?0.2.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ftp::geturl</b> <i class="arg">url</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a command which wraps around the client side of
the <i class="term"><a href="../../../../index.html#ftp">ftp</a></i> protocol provided by package <b class="package"><a href="ftp.html">ftp</a></b> to allow the
retrieval of urls using the <i class="term"><a href="../../../../index.html#ftp">ftp</a></i> schema.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ftp::geturl</b> <i class="arg">url</i></a></dt>
<dd><p>This command can be used by the generic command <b class="cmd">::uri::geturl</b>
(See package <b class="package"><a href="../uri/uri.html">uri</a></b>) to retrieve the contents of ftp
urls. Internally it uses the commands of the package <b class="package"><a href="ftp.html">ftp</a></b> to
fulfill the request.</p>
<p>The contents of a <i class="term"><a href="../../../../index.html#ftp">ftp</a></i> url are defined as follows:</p>
<dl class="doctools_definitions">
<dt><i class="term"><a href="../../../../index.html#file">file</a></i></dt>
<dd><p>The contents of the specified file itself.</p></dd>
<dt><i class="term">directory</i></dt>
<dd><p>A listing of the contents of the directory in key value notation where
the file name is the key and its attributes the associated value.</p></dd>
<dt><i class="term">link</i></dt>
<dd><p>The attributes of the link, including the path it refers to.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ftp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../ftpd/ftpd.html">ftpd</a>, <a href="../mime/mime.html">mime</a>, <a href="../pop3/pop3.html">pop3</a>, <a href="../mime/smtp.html">smtp</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ftp">ftp</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#net">net</a>, <a href="../../../../index.html#rfc_959">rfc 959</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ftpd/ftpd.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
<div class='fossil-doc' data-title='ftpd - Tcl FTP Server Package'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ftpd(n) 1.3 tcllib "Tcl FTP Server Package"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ftpd - Tcl FTP server implementation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">CALLBACKS</a></li>
<li class="doctools_section"><a href="#section4">VARIABLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">ftpd <span class="opt">?1.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ftpd::server</b> <span class="opt">?<i class="arg">myaddr</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::ftpd::config</b> <span class="opt">?<i class="arg">option value</i>?</span> <span class="opt">?<i class="arg">option value ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">fsCmd</i> <b class="method">append</b> <i class="arg">path</i></a></li>
<li><a href="#4"><i class="arg">fsCmd</i> <b class="method">delete</b> <i class="arg">path</i> <i class="arg">channel</i></a></li>
<li><a href="#5"><i class="arg">fsCmd</i> <b class="method">dlist</b> <i class="arg">path</i> <i class="arg">style</i> <i class="arg">channel</i></a></li>
<li><a href="#6"><i class="arg">fsCmd</i> <b class="method">exists</b> <i class="arg">path</i></a></li>
<li><a href="#7"><i class="arg">fsCmd</i> <b class="method">mkdir</b> <i class="arg">path</i> <i class="arg">channel</i></a></li>
<li><a href="#8"><i class="arg">fsCmd</i> <b class="method">mtime</b> <i class="arg">path</i> <i class="arg">channel</i></a></li>
<li><a href="#9"><i class="arg">fsCmd</i> <b class="method">permissions</b> <i class="arg">path</i></a></li>
<li><a href="#10"><i class="arg">fsCmd</i> <b class="method">rename</b> <i class="arg">path</i> <i class="arg">newpath</i> <i class="arg">channel</i></a></li>
<li><a href="#11"><i class="arg">fsCmd</i> <b class="method">retr</b> <i class="arg">path</i></a></li>
<li><a href="#12"><i class="arg">fsCmd</i> <b class="method">rmdir</b> <i class="arg">path</i> <i class="arg">channel</i></a></li>
<li><a href="#13"><i class="arg">fsCmd</i> <b class="method">size</b> <i class="arg">path</i> <i class="arg">channel</i></a></li>
<li><a href="#14"><i class="arg">fsCmd</i> <b class="method">store</b> <i class="arg">path</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">ftpd</b> package provides a simple Tcl-only server library
for the FTP protocol as specified in
RFC 959 (<a href="http://www.rfc-editor.org/rfc/rfc959.txt">http://www.rfc-editor.org/rfc/rfc959.txt</a>).
It works by listening on the standard FTP socket. Most server errors
are returned as error messages with the appropriate code attached to
them. Since the server code for the ftp daemon is executed in the
event loop, it is possible that a
<b class="cmd">bgerror</b> will be thrown on the server if there are problems with
the code in the module.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ftpd::server</b> <span class="opt">?<i class="arg">myaddr</i>?</span></a></dt>
<dd><p>Open a listening socket to listen to and accept ftp connections.
myaddr is an optional argument. <i class="arg">myaddr</i> is the domain-style name
or numerical IP address of the client-side network interface to use
for the connection.</p></dd>
<dt><a name="2"><b class="cmd">::ftpd::config</b> <span class="opt">?<i class="arg">option value</i>?</span> <span class="opt">?<i class="arg">option value ...</i>?</span></a></dt>
<dd><p>The value is always the name of the command to call as the
callback. The option specifies which callback should be configured.
See section <span class="sectref"><a href="#section3">CALLBACKS</a></span> for descriptions of the arguments and
return values for each of the callbacks.</p>
<dl class="doctools_definitions">
<dt>-authIpCmd <i class="arg">proc</i></dt>
<dd><p>Callback to authenticate new connections based on the ip-address of
the peer.</p></dd>
<dt>-authUsrCmd <i class="arg">proc</i></dt>
<dd><p>Callback to authenticate new connections based on the user logging in
(and the users password).</p></dd>
<dt>-authFileCmd <i class="arg">proc</i></dt>
<dd><p>Callback to accept or deny a users access to read and write to a
specific path or file.</p></dd>
<dt>-logCmd <i class="arg">proc</i></dt>
<dd><p>Callback for log information generated by the FTP engine.</p></dd>
<dt>-fsCmd <i class="arg">proc</i></dt>
<dd><p>Callback to connect the engine to the filesystem it operates on.</p></dd>
<dt>-closeCmd <i class="arg">proc</i></dt>
<dd><p>Callback to be called when a connection is closed. This allows the
embedding application to perform its own cleanup operations.</p></dd>
<dt>-xferDoneCmd <i class="arg">proc</i></dt>
<dd><p>Callback for transfer completion notification. In other words, it is
called whenever a transfer of data to or from the client has
completed.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CALLBACKS</a></h2>
<dl class="doctools_definitions">
<dt><b class="cmd">authIpCmd</b> callback</dt>
<dd><p>The authIpCmd receives the ip-address of the peer attempting to
connect to the ftp server as its argument. It returns a 1 to allow
users from the specified IP to attempt to login and a 0 to reject the
login attempt from the specified IP.</p></dd>
<dt><b class="cmd">authUsrCmd</b> callback</dt>
<dd><p>The authUsrCmd receives the username and password as its two
arguments. It returns a 1 to accept the attempted login to the ftpd
and a 0 to reject the attempted login.</p></dd>
<dt><b class="cmd">authFileCmd</b> callback</dt>
<dd><p>The authFileCmd receives the user (that is currently logged in), the
path or filename that is about to be read or written, and
<b class="const">read</b> or <b class="const">write</b> as its three arguments. It returns a
1 to allow the path or filename to be read or written, and a 0 to
reject the attempted read or write with a permissions error code.</p></dd>
<dt><b class="cmd">logCmd</b> callback</dt>
<dd><p>The logCmd receives a severity and a message as its two arguments.
The severities used within the ftpd package are <b class="const">note</b>,
<b class="const">debug</b>, and <b class="const">error</b>. The logCmd doesn't return
anything.</p></dd>
<dt><b class="cmd">fsCmd</b> callback</dt>
<dd><p>The fsCmd receives a subcommand, a filename or path, and optional
additional arguments (depending on the subcommand).</p>
<p>The subcommands supported by the fsCmd are:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">fsCmd</i> <b class="method">append</b> <i class="arg">path</i></a></dt>
<dd><p>The append subcommand receives the filename to append to as its
argument. It returns a writable tcl channel as its return value.</p></dd>
<dt><a name="4"><i class="arg">fsCmd</i> <b class="method">delete</b> <i class="arg">path</i> <i class="arg">channel</i></a></dt>
<dd><p>The delete subcommand receives the filename to delete, and a channel
to write to as its two arguments. The file specified is deleted and
the appropriate ftp message is written to the channel that is passed
as the second argument. The delete subcommand returns nothing.</p></dd>
<dt><a name="5"><i class="arg">fsCmd</i> <b class="method">dlist</b> <i class="arg">path</i> <i class="arg">style</i> <i class="arg">channel</i></a></dt>
<dd><p>The dlist subcommand receives the path that it should list the files
that are in, the style in which the files should be listed which is
either <b class="const">nlst</b> or <b class="const">list</b>, and a channel to write to as
its three arguments. The files in the specified path are printed to
the specified channel one per line. If the style is <b class="const">nlst</b>
only the name of the file is printed to the channel. If the style is
<b class="const">list</b> then the file permissions, number of links to the file,
the name of the user that owns the file, the name of the group that
owns the file, the size (in bytes) of the file, the modify time of the
file, and the filename are printed out to the channel in a formatted
space separated format. The <b class="method">dlist</b> subcommand returns
nothing.</p></dd>
<dt><a name="6"><i class="arg">fsCmd</i> <b class="method">exists</b> <i class="arg">path</i></a></dt>
<dd><p>The exists subcommand receives the name of a file to check the
existence of as its only argument. The exists subcommand returns a 1
if the path specified exists and the path is not a directory.</p></dd>
<dt><a name="7"><i class="arg">fsCmd</i> <b class="method">mkdir</b> <i class="arg">path</i> <i class="arg">channel</i></a></dt>
<dd><p>The mkdir subcommand receives the path of a directory to create and a
channel to write to as its two arguments. The mkdir subcommand
creates the specified directory if necessary and possible. The mkdir
subcommand then prints the appropriate success or failure message to
the channel. The mkdir subcommand returns nothing.</p></dd>
<dt><a name="8"><i class="arg">fsCmd</i> <b class="method">mtime</b> <i class="arg">path</i> <i class="arg">channel</i></a></dt>
<dd><p>The mtime subcommand receives the path of a file to check the modify
time on and a channel as its two arguments. If the file exists the
mtime is printed to the channel in the proper FTP format, otherwise an
appropriate error message and code are printed to the channel. The
mtime subcommand returns nothing.</p></dd>
<dt><a name="9"><i class="arg">fsCmd</i> <b class="method">permissions</b> <i class="arg">path</i></a></dt>
<dd><p>The permissions subcommand receives the path of a file to retrieve the
permissions of. The permissions subcommand returns the octal file
permissions of the specified file. The file is expected to exist.</p></dd>
<dt><a name="10"><i class="arg">fsCmd</i> <b class="method">rename</b> <i class="arg">path</i> <i class="arg">newpath</i> <i class="arg">channel</i></a></dt>
<dd><p>The rename subcommand receives the path of the current file, the new
file path, and a channel to write to as its three arguments. The
rename subcommand renames the current file to the new file path if the
path to the new file exists, and then prints out the appropriate
message to the channel. If the new file path doesn't exist the
appropriate error message is printed to the channel. The rename
subcommand returns nothing.</p></dd>
<dt><a name="11"><i class="arg">fsCmd</i> <b class="method">retr</b> <i class="arg">path</i></a></dt>
<dd><p>The retr subcommand receives the path of a file to read as its only
argument. The retr subcommand returns a readable channel that the
specified file can be read from.</p></dd>
<dt><a name="12"><i class="arg">fsCmd</i> <b class="method">rmdir</b> <i class="arg">path</i> <i class="arg">channel</i></a></dt>
<dd><p>The rmdir subcommand receives the path of a directory to remove and a
channel to write to as its two arguments. The rmdir subcommand
removes the specified directory (if possible) and prints the
appropriate message to the channel (which may be an error if the
specified directory does not exist or is not empty). The rmdir
subcommand returns nothing.</p></dd>
<dt><a name="13"><i class="arg">fsCmd</i> <b class="method">size</b> <i class="arg">path</i> <i class="arg">channel</i></a></dt>
<dd><p>The size subcommand receives the path of a file to get the size (in
bytes) of and a channel to write to as its two arguments. The size
subcommand prints the appropriate code and the size of the file if the
specified path is a file, otherwise an appropriate error code and
message are printed to the channel. The size subcommand returns
nothing.</p></dd>
<dt><a name="14"><i class="arg">fsCmd</i> <b class="method">store</b> <i class="arg">path</i></a></dt>
<dd><p>The store subcommand receives the path of a file to write as its only
argument. The store subcommand returns a writable channel.</p></dd>
</dl></dd>
<dt><b class="cmd">closeCmd</b></dt>
<dd><p>The <b class="cmd">closeCmd</b> receives no arguments when it is invoked, and any
return value it may generate is discarded.</p></dd>
<dt><b class="cmd">xferDoneCmd</b> sock sock2 file bytes filename err</dt>
<dd><p>The <b class="cmd">xferDoneCmd</b> receives six arguments when invoked. These are,
in this order, the channel handle of the control socket for the
connection, the channel handle of the data socket used for the
transfer (already closed), the handle of the channel containing the
transfered file, the number of bytes transfered, the path of the file
which was transfered, and a (possibly empty) error message.
Any return value it may generate is discarded.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">VARIABLES</a></h2>
<dl class="doctools_definitions">
<dt><b class="variable">::ftpd::cwd</b></dt>
<dd><p>The current working directory for a session when someone first
connects to the FTPD or when the <b class="cmd">REIN</b> ftp command is received.</p></dd>
<dt><b class="variable">::ftpd::contact</b></dt>
<dd><p>The e-mail address of the person that is the contact for the ftp
server. This address is printed out as part of the response to the
<b class="cmd">FTP HELP</b> command.</p></dd>
<dt><b class="variable">::ftpd::port</b></dt>
<dd><p>The port that the ftp server should listen on.
If port is specified as zero, the operating system will allocate an
unused port for use as a server socket; afterwards, the variable will
contain the port number that was allocated.</p></dd>
<dt><b class="variable">::ftpd::welcome</b></dt>
<dd><p>The message that is printed out when the user first connects to the
ftp server.</p></dd>
<dt><b class="variable">::ftpd::CurrentSocket</b></dt>
<dd><p>Accessible to all callbacks and all filesystem commands (which are a
special form of callback) and contains the handle of the socket
channel which was active when the callback was invoked.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ftpd</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ftp">ftp</a>, <a href="../../../../index.html#ftpd">ftpd</a>, <a href="../../../../index.html#ftpserver">ftpserver</a>, <a href="../../../../index.html#rfc_959">rfc 959</a>, <a href="../../../../index.html#services">services</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fumagic/cfront.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
<div class='fossil-doc' data-title='fileutil::magic::cfront - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil::magic::cfront(n) 1.2.0 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil::magic::cfront - Generator core for compiler of magic(5) files</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">fileutil::magic::cfront <span class="opt">?1.2.0?</span></b></li>
<li>package require <b class="pkgname">fileutil::magic::cgen <span class="opt">?1.2.0?</span></b></li>
<li>package require <b class="pkgname">fileutil::magic::rt <span class="opt">?1.2.0?</span></b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::magic::cfront::compile</b> <i class="arg">path</i>...</a></li>
<li><a href="#2"><b class="cmd">::fileutil::magic::cfront::procdef</b> <i class="arg">procname</i> <i class="arg">path</i>...</a></li>
<li><a href="#3"><b class="cmd">::fileutil::magic::cfront::install</b> <i class="arg">path</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the frontend of a compiler of magic(5) files
into recognizers based on the <b class="package"><a href="rtcore.html">fileutil::magic::rt</a></b> recognizer
runtime package. For the generator backed used by this compiler see
the package <b class="package"><a href="cgen.html">fileutil::magic::cgen</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::magic::cfront::compile</b> <i class="arg">path</i>...</a></dt>
<dd><p>This command takes the paths of one or more files and directories and
compiles all the files, and the files in all the directories into a
single recognizer for all the file types specified in these files.</p>
<p>All the files have to be in the format specified by magic(5).</p>
<p>The result of the command is a Tcl script containing the generated
recognizer.</p></dd>
<dt><a name="2"><b class="cmd">::fileutil::magic::cfront::procdef</b> <i class="arg">procname</i> <i class="arg">path</i>...</a></dt>
<dd><p>This command behaves like <b class="cmd">::fileutil::magic::cfront::compile</b>
with regard to the specified path arguments, then wraps the resulting
recognizer script into a procedure named <i class="arg">procname</i>, puts code
setting up the namespace of <i class="arg">procname</i> in front, and returns the
resulting script.</p></dd>
<dt><a name="3"><b class="cmd">::fileutil::magic::cfront::install</b> <i class="arg">path</i>...</a></dt>
<dd><p>This command uses <b class="cmd">::fileutil::magic::cfront::procdef</b> to compile
each of the paths into a recognizer procedure and installs the result
in the current interpreter.</p>
<p>The name of each new procedure is derived from the name of the
file/directory used in its creation, with file/directory "<b class="file">FOO</b>"
causing the creation of procedure <b class="const">::fileutil::magic::/FOO::run</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil :: magic</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>file(1), <a href="../fileutil/fileutil.html">fileutil</a>, magic(5)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#file_recognition">file recognition</a>, <a href="../../../../index.html#file_type">file type</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#mime">mime</a>, <a href="../../../../index.html#type">type</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fumagic/cgen.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='fileutil::magic::cgen - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil::magic::cgen(n) 1.2.0 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil::magic::cgen - Generator core for compiler of magic(5) files</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">fileutil::magic::cgen <span class="opt">?1.2.0?</span></b></li>
<li>package require <b class="pkgname">fileutil::magic::rt <span class="opt">?1.2.0?</span></b></li>
<li>package require <b class="pkgname">struct::tree</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::magic::cgen::2tree</b> <i class="arg">script</i></a></li>
<li><a href="#2"><b class="cmd">::fileutil::magic::cgen::treedump</b> <i class="arg">tree</i></a></li>
<li><a href="#3"><b class="cmd">::fileutil::magic::cgen::treegen</b> <i class="arg">tree</i> <i class="arg">node</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the generator backend for a compiler of magic(5)
files into recognizers based on the <b class="package"><a href="rtcore.html">fileutil::magic::rt</a></b>
recognizer runtime package. For the compiler frontend using this
generator see the package <b class="package"><a href="cfront.html">fileutil::magic::cfront</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::magic::cgen::2tree</b> <i class="arg">script</i></a></dt>
<dd><p>This command converts the recognizer specified by the <i class="arg">script</i>
into a tree and returns the object command of that tree as its
result. It uses the package <b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b> for the tree.</p>
<p>The <i class="arg">script</i> is in the format specified by magic(5).</p></dd>
<dt><a name="2"><b class="cmd">::fileutil::magic::cgen::treedump</b> <i class="arg">tree</i></a></dt>
<dd><p>This command takes a <i class="arg">tree</i> as generated by
<b class="cmd">::fileutil::magic::cgen::2tree</b> and returns a string encoding the
tree for human consumption, to aid in debugging.</p></dd>
<dt><a name="3"><b class="cmd">::fileutil::magic::cgen::treegen</b> <i class="arg">tree</i> <i class="arg">node</i></a></dt>
<dd><p>This command takes a <i class="arg">tree</i> as generated by
<b class="cmd">::fileutil::magic::cgen::2tree</b> and returns a Tcl script, the
recognizer for the file types represented by the sub-tree rooted at
the <i class="arg">node</i>.
The generated script makes extensive use of the commands provided by
the recognizer runtime package <b class="package"><a href="rtcore.html">fileutil::magic::rt</a></b> to
perform its duties.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil :: magic</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>file(1), <a href="../fileutil/fileutil.html">fileutil</a>, magic(5)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#file_recognition">file recognition</a>, <a href="../../../../index.html#file_type">file type</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#mime">mime</a>, <a href="../../../../index.html#type">type</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fumagic/filetypes.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<div class='fossil-doc' data-title='fileutil::magic::filetype - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil::magic::filetype(n) 2.0 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil::magic::filetype - Procedures implementing file-type recognition</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">REFERENCES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">fileutil::magic::filetype <span class="opt">?2.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::magic::filetype</b> <i class="arg">filename</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a command for the recognition of file types in
pure Tcl.</p>
<p>The core part of the recognizer was generated from a "magic(5)" file
containing the checks to perform to recognize files, and associated
file-types.</p>
<p><em>Beware!</em> This recognizer is large, about 752 Kilobyte of
generated Tcl code.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::magic::filetype</b> <i class="arg">filename</i></a></dt>
<dd><p>This command is similar to the command <b class="cmd">fileutil::fileType</b>.</p>
<p>Returns a list containing a list of descriptions, a list of mimetype
components, and a list file extensions. Returns an empty string if the file
content is not recognized.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="ftp://ftp.astron.com/pub/file/">File(1) sources</a>
This site contains the current sources for the file command, including
the magic definitions used by it. The latter were used by us to
generate this recognizer.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil :: magic</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>file(1), <a href="../fileutil/fileutil.html">fileutil</a>, magic(5)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#file_recognition">file recognition</a>, <a href="../../../../index.html#file_type">file type</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#type">type</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/fumagic/rtcore.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
<div class='fossil-doc' data-title='fileutil::magic::rt - file utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">fileutil::magic::rt(n) 2.0 tcllib "file utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>fileutil::magic::rt - Runtime core for file type recognition engines written in pure Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">NUMERIC TYPES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">fileutil::magic::rt <span class="opt">?2.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::fileutil::magic::rt::></b></a></li>
<li><a href="#2"><b class="cmd">::fileutil::magic::rt::<</b></a></li>
<li><a href="#3"><b class="cmd">::fileutil::magic::rt::open</b> <i class="arg">filename</i></a></li>
<li><a href="#4"><b class="cmd">::fileutil::magic::rt::close</b></a></li>
<li><a href="#5"><b class="cmd">::fileutil::magic::rt::file_start</b> <i class="arg">name</i></a></li>
<li><a href="#6"><b class="cmd">::fileutil::magic::rt::result</b> <span class="opt">?<i class="arg">msg</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::fileutil::magic::rt::resultv</b> <span class="opt">?<i class="arg">msg</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::fileutil::magic::rt::emit</b> <i class="arg">msg</i></a></li>
<li><a href="#9"><b class="cmd">::fileutil::magic::rt::offset</b> <i class="arg">where</i></a></li>
<li><a href="#10"><b class="cmd">::fileutil::magic::rt::Nv</b> <i class="arg">type</i> <i class="arg">offset</i> <span class="opt">?<i class="arg">qual</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::fileutil::magic::rt::N</b> <i class="arg">type</i> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::fileutil::magic::rt::Nvx</b> <i class="arg">type</i> <i class="arg">offset</i> <span class="opt">?<i class="arg">qual</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::fileutil::magic::rt::Nx</b> <i class="arg">type</i> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::fileutil::magic::rt::S</b> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></li>
<li><a href="#15"><b class="cmd">::fileutil::magic::rt::Sx</b> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></li>
<li><a href="#16"><b class="cmd">::fileutil::magic::rt::L</b> <i class="arg">newlevel</i></a></li>
<li><a href="#17"><b class="cmd">::fileutil::magic::rt::I</b> <i class="arg">base</i> <i class="arg">type</i> <i class="arg">delta</i></a></li>
<li><a href="#18"><b class="cmd">::fileutil::magic::rt::R</b> <i class="arg">offset</i></a></li>
<li><a href="#19"><b class="cmd">::fileutil::magic::rt::U</b> <i class="arg">fileindex</i> <i class="arg">name</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the runtime core for file type recognition
engines written in pure Tcl and is thus used by all other packages in
this module, i.e. the two frontend packages
<b class="package">fileutil::magic::mimetypes</b> and
<b class="package">fileutil::magic::filetypes</b>, and the two engine compiler
packages <b class="package"><a href="cgen.html">fileutil::magic::cgen</a></b> and
<b class="package"><a href="cfront.html">fileutil::magic::cfront</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::fileutil::magic::rt::></b></a></dt>
<dd><p>Shorthand for <b class="cmd">incr level</b>.</p></dd>
<dt><a name="2"><b class="cmd">::fileutil::magic::rt::<</b></a></dt>
<dd><p>Shorthand for <b class="cmd">incr level -1</b>.</p></dd>
<dt><a name="3"><b class="cmd">::fileutil::magic::rt::open</b> <i class="arg">filename</i></a></dt>
<dd><p>This command initializes the runtime and prepares the file
<i class="arg">filename</i> for use by the system.
This command has to be invoked first, before any other command of this
package.</p>
<p>The command returns the channel handle of the opened file as its
result.</p></dd>
<dt><a name="4"><b class="cmd">::fileutil::magic::rt::close</b></a></dt>
<dd><p>This command closes the last file opened via
<b class="cmd">::fileutil::magic::rt::open</b> and shuts the runtime down.
This command has to be invoked last, after the file has been dealt
with completely.
Afterward another invokation of <b class="cmd">::fileutil::magic::rt::open</b> is
required to process another file.</p>
<p>This command returns the empty string as its result.</p></dd>
<dt><a name="5"><b class="cmd">::fileutil::magic::rt::file_start</b> <i class="arg">name</i></a></dt>
<dd><p>This command marks the start of a magic file when debugging. It
returns the empty string as its result.</p></dd>
<dt><a name="6"><b class="cmd">::fileutil::magic::rt::result</b> <span class="opt">?<i class="arg">msg</i>?</span></a></dt>
<dd><p>This command returns the current result and stops processing.</p>
<p>If <i class="arg">msg</i> is specified its text is added to the result before it is
returned. See <b class="cmd">::fileutil::magic::rt::emit</b> for the allowed
special character sequences.</p></dd>
<dt><a name="7"><b class="cmd">::fileutil::magic::rt::resultv</b> <span class="opt">?<i class="arg">msg</i>?</span></a></dt>
<dd><p>This command returns the current result.
In contrast to <b class="cmd">::fileutil::magic::rt::result</b> processing
continues.</p>
<p>If <i class="arg">msg</i> is specified its text is added to the result before it is
returned. See <b class="cmd">::fileutil::magic::rt::emit</b> for the allowed
special character sequences.</p></dd>
<dt><a name="8"><b class="cmd">::fileutil::magic::rt::emit</b> <i class="arg">msg</i></a></dt>
<dd><p>This command adds the text <i class="arg">msg</i> to the result buffer. The
message may contain the following special character sequences. They
will be replaced with buffered values before the message is added to
the result. The command returns the empty string as its result.</p>
<dl class="doctools_definitions">
<dt><b class="const">\b</b></dt>
<dd><p>This sequence is removed</p></dd>
<dt><b class="const">%s</b></dt>
<dd><p>Replaced with the last buffered string value.</p></dd>
<dt><b class="const">%ld</b></dt>
<dd><p>Replaced with the last buffered numeric value.</p></dd>
<dt><b class="const">%d</b></dt>
<dd><p>See above.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::fileutil::magic::rt::Nv</b> <i class="arg">type</i> <i class="arg">offset</i> <span class="opt">?<i class="arg">qual</i>?</span></a></dt>
<dd><p>This command fetches the numeric value with <i class="arg">type</i> from the
absolute location <i class="arg">offset</i> and returns it as its result. The
fetched value is further stored in the numeric buffer.</p>
<p>If <i class="arg">qual</i> is specified it is considered to be a mask and applied
to the fetched value before it is stored and returned. It has to have
the form of a partial Tcl bit-wise expression, i.e.</p>
<pre class="doctools_example">
& number
</pre>
<p>For example:</p>
<pre class="doctools_example">
Nv lelong 0 &0x8080ffff
</pre>
<p>For the possible types see section <span class="sectref"><a href="#section3">NUMERIC TYPES</a></span>.</p></dd>
<dt><a name="11"><b class="cmd">::fileutil::magic::rt::N</b> <i class="arg">type</i> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></dt>
<dd><p>This command behaves mostly like <b class="cmd">::fileutil::magic::rt::Nv</b>,
except that it compares the fetched and masked value against <i class="arg">val</i>
as specified with <i class="arg">comp</i> and returns the result of that
comparison.</p>
<p>The argument <i class="arg">comp</i> has to contain one of Tcl's comparison
operators, and the comparison made will be</p>
<pre class="doctools_example">
<val> <comp> <fetched-and-masked-value>
</pre>
<p>The special comparison operator <b class="const">x</b> signals that no comparison
should be done, or, in other words, that the fetched value will always
match <i class="arg">val</i>.</p></dd>
<dt><a name="12"><b class="cmd">::fileutil::magic::rt::Nvx</b> <i class="arg">type</i> <i class="arg">offset</i> <span class="opt">?<i class="arg">qual</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::fileutil::magic::rt::Nv</b>, except that
it additionally remembers the location in the file after the fetch in
the calling context, for the current level, for later use by
<b class="cmd">::fileutil::magic::rt::R</b>.</p></dd>
<dt><a name="13"><b class="cmd">::fileutil::magic::rt::Nx</b> <i class="arg">type</i> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::fileutil::magic::rt::N</b>, except that
it additionally remembers the location in the file after the fetch in
the calling context, for the current, for later use by
<b class="cmd">::fileutil::magic::rt::R</b>.</p></dd>
<dt><a name="14"><b class="cmd">::fileutil::magic::rt::S</b> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::fileutil::magic::rt::N</b>, except that
it fetches and compares strings, not numeric data. The fetched value
is also stored in the internal string buffer instead of the numeric
buffer.</p></dd>
<dt><a name="15"><b class="cmd">::fileutil::magic::rt::Sx</b> <i class="arg">offset</i> <i class="arg">comp</i> <i class="arg">val</i> <span class="opt">?<i class="arg">qual</i>?</span></a></dt>
<dd><p>This command behaves like <b class="cmd">::fileutil::magic::rt::S</b>, except that
it additionally remembers the location in the file after the fetch in
the calling context, for the current level, for later use by
<b class="cmd">::fileutil::magic::rt::R</b>.</p></dd>
<dt><a name="16"><b class="cmd">::fileutil::magic::rt::L</b> <i class="arg">newlevel</i></a></dt>
<dd><p>This command sets the current level in the calling context to
<i class="arg">newlevel</i>. The command returns the empty string as its result.</p></dd>
<dt><a name="17"><b class="cmd">::fileutil::magic::rt::I</b> <i class="arg">base</i> <i class="arg">type</i> <i class="arg">delta</i></a></dt>
<dd><p>This command handles base locations specified indirectly through the
contents of the inspected file. It returns the sum of <i class="arg">delta</i> and
the value of numeric <i class="arg">type</i> fetched from the absolute location
<i class="arg">base</i>.</p>
<p>For the possible types see section <span class="sectref"><a href="#section3">NUMERIC TYPES</a></span>.</p></dd>
<dt><a name="18"><b class="cmd">::fileutil::magic::rt::R</b> <i class="arg">offset</i></a></dt>
<dd><p>This command handles base locations specified relative to the end of
the last field one level above.</p>
<p>In other words, the command computes an absolute location in the file
based on the relative <i class="arg">offset</i> and returns it as its result. The
base the offset is added to is the last location remembered for the
level in the calling context.</p></dd>
<dt><a name="19"><b class="cmd">::fileutil::magic::rt::U</b> <i class="arg">fileindex</i> <i class="arg">name</i></a></dt>
<dd><p>Use a named test script at the current level.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">NUMERIC TYPES</a></h2>
<dl class="doctools_definitions">
<dt><b class="const">byte</b></dt>
<dd><p>8-bit integer</p></dd>
<dt><b class="const">short</b></dt>
<dd><p>16-bit integer, stored in native endianess</p></dd>
<dt><b class="const">beshort</b></dt>
<dd><p>see above, stored in big endian</p></dd>
<dt><b class="const">leshort</b></dt>
<dd><p>see above, stored in small/little endian</p></dd>
<dt><b class="const">long</b></dt>
<dd><p>32-bit integer, stored in native endianess</p></dd>
<dt><b class="const">belong</b></dt>
<dd><p>see above, stored in big endian</p></dd>
<dt><b class="const">lelong</b></dt>
<dd><p>see above, stored in small/little endian</p></dd>
</dl>
<p>All of the types above exit in an unsigned form as well. The type
names are the same, with the character "u" added as prefix.</p>
<dl class="doctools_definitions">
<dt><b class="const">date</b></dt>
<dd><p>32-bit integer timestamp, stored in native endianess</p></dd>
<dt><b class="const">bedate</b></dt>
<dd><p>see above, stored in big endian</p></dd>
<dt><b class="const">ledate</b></dt>
<dd><p>see above, stored in small/little endian</p></dd>
<dt><b class="const">ldate</b></dt>
<dd><p>32-bit integer timestamp, stored in native endianess</p></dd>
<dt><b class="const">beldate</b></dt>
<dd><p>see above, stored in big endian</p></dd>
<dt><b class="const">leldate</b></dt>
<dd><p>see above, stored in small/little endian</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>fileutil :: magic</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>file(1), <a href="../fileutil/fileutil.html">fileutil</a>, magic(5)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#file_recognition">file recognition</a>, <a href="../../../../index.html#file_type">file type</a>, <a href="../../../../index.html#file_utilities">file utilities</a>, <a href="../../../../index.html#mime">mime</a>, <a href="../../../../index.html#type">type</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/generator/generator.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
|
<div class='fossil-doc' data-title='generator - Tcl Generator Commands'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">generator(n) 0.1 tcllib "Tcl Generator Commands"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>generator - Procedures for creating and using generators.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PRELUDE</a></li>
<li class="doctools_section"><a href="#section4">BUGS, IDEAS, FEEDBACK</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">generator <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">generator</b> <b class="method">define</b> <i class="arg">name</i> <i class="arg">params</i> <i class="arg">body</i></a></li>
<li><a href="#2"><b class="cmd">generator</b> <b class="method">yield</b> <i class="arg">arg</i> <span class="opt">?<i class="arg">args..</i>?</span></a></li>
<li><a href="#3"><b class="cmd">generator</b> <b class="method">foreach</b> <i class="arg">varList</i> <i class="arg">generator</i> <i class="arg">varList</i> <i class="arg">generator</i> <span class="opt">?...?</span> <i class="arg">body</i></a></li>
<li><a href="#4"><b class="cmd">generator</b> <b class="method">next</b> <i class="arg">generator</i> <span class="opt">?<i class="arg">varName..</i>?</span></a></li>
<li><a href="#5"><b class="cmd">generator</b> <b class="method">exists</b> <i class="arg">generator</i></a></li>
<li><a href="#6"><b class="cmd">generator</b> <b class="method">names</b></a></li>
<li><a href="#7"><b class="cmd">generator</b> <b class="method">destroy</b> <span class="opt">?<i class="arg">generator..</i>?</span></a></li>
<li><a href="#8"><b class="cmd">generator</b> <b class="method">finally</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">arg..</i>?</span></a></li>
<li><a href="#9"><b class="cmd">generator</b> <b class="method">from</b> <i class="arg">format</i> <i class="arg">value</i></a></li>
<li><a href="#10"><b class="cmd">generator</b> <b class="method">to</b> <i class="arg">format</i> <i class="arg">generator</i></a></li>
<li><a href="#11"><b class="cmd">generator</b> <b class="method">map</b> <i class="arg">function</i> <i class="arg">generator</i></a></li>
<li><a href="#12"><b class="cmd">generator</b> <b class="method">filter</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></li>
<li><a href="#13"><b class="cmd">generator</b> <b class="method">reduce</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></li>
<li><a href="#14"><b class="cmd">generator</b> <b class="method">foldl</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></li>
<li><a href="#15"><b class="cmd">generator</b> <b class="method">foldr</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></li>
<li><a href="#16"><b class="cmd">generator</b> <b class="method">all</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></li>
<li><a href="#17"><b class="cmd">generator</b> <b class="method">and</b> <i class="arg">generator</i></a></li>
<li><a href="#18"><b class="cmd">generator</b> <b class="method">any</b> <i class="arg">generator</i></a></li>
<li><a href="#19"><b class="cmd">generator</b> <b class="method">concat</b> <i class="arg">generator</i> <span class="opt">?<i class="arg">generator..</i>?</span></a></li>
<li><a href="#20"><b class="cmd">generator</b> <b class="method">concatMap</b> <i class="arg">function</i> <i class="arg">generator</i></a></li>
<li><a href="#21"><b class="cmd">generator</b> <b class="method">drop</b> <i class="arg">n</i> <i class="arg">generator</i></a></li>
<li><a href="#22"><b class="cmd">generator</b> <b class="method">dropWhile</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></li>
<li><a href="#23"><b class="cmd">generator</b> <b class="method">contains</b> <i class="arg">element</i> <i class="arg">generator</i></a></li>
<li><a href="#24"><b class="cmd">generator</b> <b class="method">foldl1</b> <i class="arg">function</i> <i class="arg">generator</i></a></li>
<li><a href="#25"><b class="cmd">generator</b> <b class="method">foldli</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></li>
<li><a href="#26"><b class="cmd">generator</b> <b class="method">foldri</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></li>
<li><a href="#27"><b class="cmd">generator</b> <b class="method">head</b> <i class="arg">generator</i></a></li>
<li><a href="#28"><b class="cmd">generator</b> <b class="method">tail</b> <i class="arg">generator</i></a></li>
<li><a href="#29"><b class="cmd">generator</b> <b class="method">init</b> <i class="arg">generator</i></a></li>
<li><a href="#30"><b class="cmd">generator</b> <b class="method">takeList</b> <i class="arg">n</i> <i class="arg">generator</i></a></li>
<li><a href="#31"><b class="cmd">generator</b> <b class="method">take</b> <i class="arg">n</i> <i class="arg">generator</i></a></li>
<li><a href="#32"><b class="cmd">generator</b> <b class="method">iterate</b> <i class="arg">function</i> <i class="arg">init</i></a></li>
<li><a href="#33"><b class="cmd">generator</b> <b class="method">last</b> <i class="arg">generator</i></a></li>
<li><a href="#34"><b class="cmd">generator</b> <b class="method">length</b> <i class="arg">generator</i></a></li>
<li><a href="#35"><b class="cmd">generator</b> <b class="method">or</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></li>
<li><a href="#36"><b class="cmd">generator</b> <b class="method">product</b> <i class="arg">generator</i></a></li>
<li><a href="#37"><b class="cmd">generator</b> <b class="method">repeat</b> <i class="arg">n</i> <i class="arg">value..</i></a></li>
<li><a href="#38"><b class="cmd">generator</b> <b class="method">sum</b> <i class="arg">generator</i></a></li>
<li><a href="#39"><b class="cmd">generator</b> <b class="method">takeWhile</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></li>
<li><a href="#40"><b class="cmd">generator</b> <b class="method">splitWhen</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></li>
<li><a href="#41"><b class="cmd">generator</b> <b class="method">scanl</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">generator</b> package provides commands to define and iterate over
generator expressions. A <em>generator</em> is a command that returns a sequence
of values. However, unlike an ordinary command that returns a list, a
generator <em>yields</em> each value and then suspends, allowing subsequent
values to be fetched on-demand. As such, generators can be used to efficiently
iterate over a set of values, without having to generate all answers in-memory.
Generators can be used to iterate over elements of a data structure, or rows
in the result set of a database query, or to decouple producer/consumer software
designs such as parsers and tokenizers, or to implement sophisticated custom
control strategies such as backtracking search. Generators reduce the need to
implement custom control structures, as many such structures can be recast as
generators, leading to both a simpler implementation and a more standardised
interface. The generator mechanism is built on top of the Tcl 8.6 coroutine
mechanism.</p>
<p>The package exports a single ensemble command, <b class="cmd">generator</b>. All
functionality is provided as subcommands of this command. The core subcommands
of the package are <b class="method">define</b>, <b class="method">yield</b>, and <b class="method">foreach</b>. The
<b class="method">define</b> command works like Tcl's <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> command, but creates a
generator procedure; that is, a procedure that returns a generator when called.
The generator itself is a command that can be called multiple times: each time
it returns the next value in the generated series. When the
series has been exhausted, the generator command returns an empty list and then
destroys itself. Rather than manually call a generator, however, the package
also provides a flexible <b class="method">foreach</b> command that loops through the values of
one or more generators. This loop construct mimicks the functionality of the
built-in Tcl <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b> command, including handling multiple return values
and looping over multiple generators at once. Writing a generator is also a
simple task, much like writing a normal procedure: simply use the <b class="method">define</b>
command to define the generator, and then call <b class="method">yield</b> instead of <b class="cmd"><a href="../../../../index.html#return">return</a></b>.
For example, we can define a generator for looping through the integers
in a particular range:</p>
<pre class="doctools_example">
generator define range {n m} {
for {set i $n} {$i <= $m} {incr i} { generator yield $i }
}
generator foreach x [range 1 10] {
puts "x = $x"
}
</pre>
<p>The above example will print the numbers from 1 to 10 in sequence, as you would
expect. The difference from a normal loop over a list is that the numbers are
only generated as they are needed. If we insert a break into the loop then any
remaining numbers in the sequence would never be generated. To illustrate, we
can define a generator that produces the sequence of natural numbers: an
infinite series. A normal procedure would never return trying to produce this
series as a list. By using a generator we only have to generate those values
which are actually used:</p>
<pre class="doctools_example">
generator define nats {} {
while 1 { generator yield [incr nat] }
}
generator foreach n [nats] {
if {$n > 100} { break }
}
</pre>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">generator</b> <b class="method">define</b> <i class="arg">name</i> <i class="arg">params</i> <i class="arg">body</i></a></dt>
<dd><p>Creates a new generator procedure. The arguments to the command are identical to
those for <b class="cmd"><a href="../../../../index.html#proc">proc</a></b>: a <i class="arg">name</i>, a list of parameters, and a body. The
parameter list format is identical to a procedure. In particular, default values
and the <span class="opt">?args?</span> syntax can be used as usual. Each time the resulting
generator procedure is called it creates a new generator command (coroutine)
that will yield a list of values on each call. Each result from a generator is
guaranteed to be a non-empty list of values. When a generator is exhausted it
returns an empty list and then destroys itself to free up resources. It is an
error to attempt to call an exhausted generator as the command no longer exists.</p></dd>
<dt><a name="2"><b class="cmd">generator</b> <b class="method">yield</b> <i class="arg">arg</i> <span class="opt">?<i class="arg">args..</i>?</span></a></dt>
<dd><p>Used in the definition of a generator, this command returns the next set of
values to the consumer. Once the <b class="method">yield</b> command has been called the
generator will suspend to allow the consumer to process that value. When the
next value is requested, the generator will resume as if the yield command had
just returned, and can continue processing to yield the next result. The
<b class="method">yield</b> command must be called with at least one argument, but can be called with
multiple arguments, in which case this is equivalent to calling <b class="method">yield</b>
once for each argument.</p></dd>
<dt><a name="3"><b class="cmd">generator</b> <b class="method">foreach</b> <i class="arg">varList</i> <i class="arg">generator</i> <i class="arg">varList</i> <i class="arg">generator</i> <span class="opt">?...?</span> <i class="arg">body</i></a></dt>
<dd><p>Loops through one or more generators, assigning the next values to variables and
then executing the loop body. Works much like the built-in <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b>
command, but working with generators rather than lists. Multiple generators can
be iterated over in parallel, and multiple results can be retrieved from a
single generator at once. Like the built-in <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b>, the loop will
continue until all of the generators have been exhausted: variables for
generators that are exhausted early will be set to the empty string.</p>
<p>The <b class="method">foreach</b> command will automatically clean-up all of the generators
at the end of the loop, regardless of whether the loop terminated early or not.
This behaviour is provided as a convenience to avoid having to explicitly
clean up a generator in the usual cases. Generators can however be destroyed
before the end of the loop, in which case the loop will continue as normal until
all the other generators have been destroyed or exhausted.</p>
<p>The <b class="method">foreach</b> command does not take a snapshot of the generator. Any
changes in the state of the generator made inside the loop or by other code will
affect the state of the loop. In particular, if the code in the loop invokes the
generator to manually retrieve the next element, this element will then be
excluded from the loop, and the next iteration will continue from the element
after that one. Care should be taken to avoid concurrent updates to generators
unless this behaviour is required (e.g., in argument processing).</p></dd>
<dt><a name="4"><b class="cmd">generator</b> <b class="method">next</b> <i class="arg">generator</i> <span class="opt">?<i class="arg">varName..</i>?</span></a></dt>
<dd><p>Manually retrieves the next values from a generator. One value is retrieved for
each variable supplied and assigned to the corresponding variable. If the
generator becomes exhausted at any time then any remaining variables are set to
the empty string.</p></dd>
<dt><a name="5"><b class="cmd">generator</b> <b class="method">exists</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns 1 if the generator (still) exists, or 0 otherwise.</p></dd>
<dt><a name="6"><b class="cmd">generator</b> <b class="method">names</b></a></dt>
<dd><p>Returns a list of all currently existing generator commands.</p></dd>
<dt><a name="7"><b class="cmd">generator</b> <b class="method">destroy</b> <span class="opt">?<i class="arg">generator..</i>?</span></a></dt>
<dd><p>Destroys one or more generators, freeing any associated resources.</p></dd>
<dt><a name="8"><b class="cmd">generator</b> <b class="method">finally</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">arg..</i>?</span></a></dt>
<dd><p>Used in the definition of a generator procedure, this command arranges for a
resource to be cleaned up whenever the generator is destroyed, either explicitly
or implicitly when the generator is exhausted. This command can be used like a
<b class="method">finally</b> block in the <b class="cmd"><a href="../try/tcllib_try.html">try</a></b> command, except that it is tied to the
life-cycle of the generator rather than to a particular scope. For example, if
we create a generator to iterate over the lines in a text file, we can use
<b class="method">finally</b> to ensure that the file is closed whenever the generator is
destroyed:</p>
<pre class="doctools_example">
generator define lines file {
set in [open $file]
# Ensure file is always closed
generator finally close $in
while {[gets $in line] >= 0} {
generator yield $line
}
}
generator foreach line [lines /etc/passwd] {
puts "[incr count]: $line"
if {$count > 10} { break }
}
# File will be closed even on early exit
</pre>
<p>If you create a generator that consumes another generator (such as the standard
<b class="method">map</b> and <b class="method">filter</b> generators defined later), then you should use
a <b class="method">finally</b> command to ensure that this generator is destroyed when its
parent is. For example, the <b class="method">map</b> generator is defined as follows:</p>
<pre class="doctools_example">
generator define map {f xs} {
generator finally generator destroy $xs
generator foreach x $xs { generator yield [{*}$f $x] }
}
</pre>
</dd>
<dt><a name="9"><b class="cmd">generator</b> <b class="method">from</b> <i class="arg">format</i> <i class="arg">value</i></a></dt>
<dd><p>Creates a generator from a data structure. Currently, supported formats are
<b class="option">list</b>, <b class="option">dict</b>, or <b class="option">string</b>. The list format yields each
element in turn. For dictionaries, each key and value are yielded separately.
Finally, strings are yielded a character at a time.</p></dd>
<dt><a name="10"><b class="cmd">generator</b> <b class="method">to</b> <i class="arg">format</i> <i class="arg">generator</i></a></dt>
<dd><p>Converts a generator into a data structure. This is the reverse operation of the
<b class="method">from</b> command, and supports the same data structures. The two operations
obey the following identity laws (where <b class="method">=</b> is interpreted
appropriately):</p>
<pre class="doctools_example">
[generator to $fmt [generator from $fmt $value]] = $value
[generator from $fmt [generator to $fmt $gen]] = $gen
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PRELUDE</a></h2>
<p>The following commands are provided as a standard library of generator
combinators and functions that perform convenience operations on generators. The
functions in this section are loosely modelled on the equivalent functions from
the Haskell Prelude. <em>Warning:</em> most of the functions in this prelude
destroy any generator arguments they are passed as a side-effect. If you want to
have persistent generators, see the streams library.</p>
<dl class="doctools_definitions">
<dt><a name="11"><b class="cmd">generator</b> <b class="method">map</b> <i class="arg">function</i> <i class="arg">generator</i></a></dt>
<dd><p>Apply a function to every element of a generator, returning a new generator of
the results. This is the classic map function from functional programming,
applied to generators. For example, we can generate all the square numbers using
the following code (where <b class="cmd">nats</b> is defined as earlier):</p>
<pre class="doctools_example">
proc square x { expr {$x * $x} }
generator foreach n [generator map square [nats]] {
puts "n = $n"
if {$n > 1000} { break }
}
</pre>
</dd>
<dt><a name="12"><b class="cmd">generator</b> <b class="method">filter</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></dt>
<dd><p>Another classic functional programming gem. This command returns a generator
that yields only those items from the argument generator that satisfy the
predicate (boolean function). For example, if we had a generator <b class="variable">employees</b>
that returned a stream of dictionaries representing people, we could filter all
those whose salaries are above 100,000 dollars (or whichever currency you prefer)
using a simple filter:</p>
<pre class="doctools_example">
proc salary> {amount person} { expr {[dict get $person salary] > $amount} }
set fat-cats [generator filter {salary> 100000} $employees]
</pre>
</dd>
<dt><a name="13"><b class="cmd">generator</b> <b class="method">reduce</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></dt>
<dd><p>This is the classic left-fold operation. This command takes a function, an
initial value, and a generator of values. For each element in the generator it
applies the function to the current accumulator value (the <i class="arg">zero</i> argument
initially) and that element, and then uses the result as the new accumulator
value. This process is repeated through the entire generator (eagerly) and the
final accumulator value is then returned. If we consider the function to be a
binary operator, and the zero argument to be the left identity element of that
operation, then we can consider the <b class="method">reduce</b> command as <em>folding</em>
the operator between each successive pair of values in the generator in a
left-associative fashion. For example, the sum of a sequence of numbers can be
calculated by folding a <b class="cmd">+</b> operator between them, with 0 as the identity:</p>
<pre class="doctools_example">
# sum xs = reduce + 0 xs
# sum [range 1 5] = reduce + 0 [range 1 5]
# = reduce + [+ 0 1] [range 2 5]
# = reduce + [+ 1 2] [range 3 5]
# = ...
# = reduce + [+ 10 5] <empty>
# = ((((0+1)+2)+3)+4)+5
# = 15
proc + {a b} { expr {$a + $b} }
proc sum gen { generator reduce + 0 $gen }
puts [sum [range 1 10]]
</pre>
<p>The <b class="method">reduce</b> operation is an extremely useful one, and a great variety of
different operations can be defined using it. For example, we can define a
factorial function as the product of a range using generators. This definition
is both very clear and also quite efficient (in both memory and running time):</p>
<pre class="doctools_example">
proc * {x y} { expr {$x * $y} }
proc prod gen { generator reduce * 0 $gen }
proc fac n { prod [range 1 $n] }
</pre>
<p>However, while the <b class="method">reduce</b> operation is efficient for finite generators,
care should be taken not to apply it to an infinite generator, as this will
result in an infinite loop:</p>
<pre class="doctools_example">
sum [nats]; # Never returns
</pre>
</dd>
<dt><a name="14"><b class="cmd">generator</b> <b class="method">foldl</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></dt>
<dd><p>This is an alias for the <b class="method">reduce</b> command.</p></dd>
<dt><a name="15"><b class="cmd">generator</b> <b class="method">foldr</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></dt>
<dd><p>This is the right-associative version of <b class="method">reduce</b>. This operation is
generally inefficient, as the entire generator needs to be evaluated into memory
(as a list) before the reduction can commence. In an eagerly evaluated language
like Tcl, this operation has limited use, and should be avoided if possible.</p></dd>
<dt><a name="16"><b class="cmd">generator</b> <b class="method">all</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></dt>
<dd><p>Returns true if all elements of the generator satisfy the given predicate.</p></dd>
<dt><a name="17"><b class="cmd">generator</b> <b class="method">and</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns true if all elements of the generator are true (i.e., takes the logical
conjunction of the elements).</p></dd>
<dt><a name="18"><b class="cmd">generator</b> <b class="method">any</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns true if any of the elements of the generator are true (i.e., logical
disjunction).</p></dd>
<dt><a name="19"><b class="cmd">generator</b> <b class="method">concat</b> <i class="arg">generator</i> <span class="opt">?<i class="arg">generator..</i>?</span></a></dt>
<dd><p>Returns a generator which is the concatenation of each of the argument
generators.</p></dd>
<dt><a name="20"><b class="cmd">generator</b> <b class="method">concatMap</b> <i class="arg">function</i> <i class="arg">generator</i></a></dt>
<dd><p>Given a function which maps a value to a series of values, and a generator of
values of that type, returns a generator of all of the results in one flat
series. Equivalent to <b class="method">concat</b> applied to the result of <b class="method">map</b>.</p></dd>
<dt><a name="21"><b class="cmd">generator</b> <b class="method">drop</b> <i class="arg">n</i> <i class="arg">generator</i></a></dt>
<dd><p>Removes the given number of elements from the front of the generator and returns
the resulting generator with those elements removed.</p></dd>
<dt><a name="22"><b class="cmd">generator</b> <b class="method">dropWhile</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></dt>
<dd><p>Removes all elements from the front of the generator that satisfy the predicate.</p></dd>
<dt><a name="23"><b class="cmd">generator</b> <b class="method">contains</b> <i class="arg">element</i> <i class="arg">generator</i></a></dt>
<dd><p>Returns true if the generator contains the given element. Note that this will
destroy the generator!</p></dd>
<dt><a name="24"><b class="cmd">generator</b> <b class="method">foldl1</b> <i class="arg">function</i> <i class="arg">generator</i></a></dt>
<dd><p>A version of <b class="method">foldl</b> that takes the <i class="arg">zero</i> argument from the first
element of the generator. Therefore this function is only valid on non-empty
generators.</p></dd>
<dt><a name="25"><b class="cmd">generator</b> <b class="method">foldli</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></dt>
<dd><p>A version of <b class="method">foldl</b> that supplies the integer index of each element as
the first argument to the function. The first element in the generator at this
point is given index 0.</p></dd>
<dt><a name="26"><b class="cmd">generator</b> <b class="method">foldri</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></dt>
<dd><p>Right-associative version of <b class="method">foldli</b>.</p></dd>
<dt><a name="27"><b class="cmd">generator</b> <b class="method">head</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns the first element of the generator.</p></dd>
<dt><a name="28"><b class="cmd">generator</b> <b class="method">tail</b> <i class="arg">generator</i></a></dt>
<dd><p>Removes the first element of the generator, returning the rest.</p></dd>
<dt><a name="29"><b class="cmd">generator</b> <b class="method">init</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns a new generator consisting of all elements except the last of the
argument generator.</p></dd>
<dt><a name="30"><b class="cmd">generator</b> <b class="method">takeList</b> <i class="arg">n</i> <i class="arg">generator</i></a></dt>
<dd><p>Returns the next <i class="arg">n</i> elements of the generator as a list. If not enough
elements are left in the generator, then just the remaining elements are
returned.</p></dd>
<dt><a name="31"><b class="cmd">generator</b> <b class="method">take</b> <i class="arg">n</i> <i class="arg">generator</i></a></dt>
<dd><p>Returns the next <i class="arg">n</i> elements of the generator as a new generator. The old
generator is destroyed.</p></dd>
<dt><a name="32"><b class="cmd">generator</b> <b class="method">iterate</b> <i class="arg">function</i> <i class="arg">init</i></a></dt>
<dd><p>Returns an infinite generator formed by repeatedly applying the function to the
initial argument. For example, the Fibonacci numbers can be defined as follows:</p>
<pre class="doctools_example">
proc fst pair { lindex $pair 0 }
proc snd pair { lindex $pair 1 }
proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] }
proc fibs {} { generator map fst [generator iterate nextFib {0 1}] }
</pre>
</dd>
<dt><a name="33"><b class="cmd">generator</b> <b class="method">last</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns the last element of the generator (if it exists).</p></dd>
<dt><a name="34"><b class="cmd">generator</b> <b class="method">length</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns the length of the generator, destroying it in the process.</p></dd>
<dt><a name="35"><b class="cmd">generator</b> <b class="method">or</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></dt>
<dd><p>Returns 1 if any of the elements of the generator satisfy the predicate.</p></dd>
<dt><a name="36"><b class="cmd">generator</b> <b class="method">product</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns the product of the numbers in a generator.</p></dd>
<dt><a name="37"><b class="cmd">generator</b> <b class="method">repeat</b> <i class="arg">n</i> <i class="arg">value..</i></a></dt>
<dd><p>Returns a generator that consists of <i class="arg">n</i> copies of the given elements. The
special value <em>Inf</em> can be used to generate an infinite sequence.</p></dd>
<dt><a name="38"><b class="cmd">generator</b> <b class="method">sum</b> <i class="arg">generator</i></a></dt>
<dd><p>Returns the sum of the values in the generator.</p></dd>
<dt><a name="39"><b class="cmd">generator</b> <b class="method">takeWhile</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></dt>
<dd><p>Returns a generator of the first elements in the argument generator that satisfy
the predicate.</p></dd>
<dt><a name="40"><b class="cmd">generator</b> <b class="method">splitWhen</b> <i class="arg">predicate</i> <i class="arg">generator</i></a></dt>
<dd><p>Splits the generator into lists of elements using the predicate to identify
delimiters. The resulting lists are returned as a generator. Elements matching
the delimiter predicate are discarded. For example, to split up a generator
using the string "|" as a delimiter:</p>
<pre class="doctools_example">
set xs [generator from list {a | b | c}]
generator split {string equal "|"} $xs ;# returns a then b then c
</pre>
</dd>
<dt><a name="41"><b class="cmd">generator</b> <b class="method">scanl</b> <i class="arg">function</i> <i class="arg">zero</i> <i class="arg">generator</i></a></dt>
<dd><p>Similar to <b class="method">foldl</b>, but returns a generator of all of the intermediate
values for the accumulator argument. The final element of this generator is
equivalent to <b class="method">foldl</b> called on the same arguments.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">BUGS, IDEAS, FEEDBACK</a></h2>
<p>Please report any errors in this document, or in the package it describes, to
<a href="mailto:[email protected]">Neil Madden</a>.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#control_structure">control structure</a>, <a href="../../../../index.html#coroutine">coroutine</a>, <a href="../../../../index.html#filter">filter</a>, <a href="../../../../index.html#foldl">foldl</a>, <a href="../../../../index.html#foldr">foldr</a>, <a href="../../../../index.html#foreach">foreach</a>, <a href="../../../../index.html#generator">generator</a>, <a href="../../../../index.html#iterator">iterator</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#reduce">reduce</a>, <a href="../../../../index.html#scanl">scanl</a></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/gpx/gpx.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
<div class='fossil-doc' data-title='gpx - GPS eXchange Format (GPX)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">gpx(n) 0.9 tcllib "GPS eXchange Format (GPX)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>gpx - Extracts waypoints, tracks and routes from GPX files</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">DATA STRUCTURES</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">AUTHOR</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">gpx <span class="opt">?0.9?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::gpx::Create</b> <i class="arg">gpxFilename</i> <span class="opt">?<i class="arg">rawXML</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::gpx::Cleanup</b> <i class="arg">token</i></a></li>
<li><a href="#3"><b class="cmd">::gpx::GetGPXMetadata</b> <i class="arg">token</i></a></li>
<li><a href="#4"><b class="cmd">::gpx::GetWaypointCount</b> <i class="arg">token</i></a></li>
<li><a href="#5"><b class="cmd">::gpx::GetAllWaypoints</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::gpx::GetTrackCount</b> <i class="arg">token</i></a></li>
<li><a href="#7"><b class="cmd">::gpx::GetTrackMetadata</b> <i class="arg">token</i> <i class="arg">whichTrack</i></a></li>
<li><a href="#8"><b class="cmd">::gpx::GetTrackPoints</b> <i class="arg">token</i> <i class="arg">whichTrack</i></a></li>
<li><a href="#9"><b class="cmd">::gpx::GetRouteCount</b> <i class="arg">token</i></a></li>
<li><a href="#10"><b class="cmd">::gpx::GetRouteMetadata</b> <i class="arg">token</i> <i class="arg">whichRoute</i></a></li>
<li><a href="#11"><b class="cmd">::gpx::GetRoutePoints</b> <i class="arg">token</i> <i class="arg">whichRoute</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This module parses and extracts waypoints, tracks, routes and
metadata from a GPX (GPS eXchange) file. Both GPX version 1.0
and 1.1 are supported.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::gpx::Create</b> <i class="arg">gpxFilename</i> <span class="opt">?<i class="arg">rawXML</i>?</span></a></dt>
<dd><p>The <b class="cmd">::gpx::Create</b> is the first command called to process GPX
data. It takes the GPX data from either the <i class="arg">rawXML</i>
parameter if present or from the contents of <i class="arg">gpxFilename</i>,
and parses it using <em>tdom</em>. It returns a token value that is used
by all the other commands.</p></dd>
<dt><a name="2"><b class="cmd">::gpx::Cleanup</b> <i class="arg">token</i></a></dt>
<dd><p>This procedure cleans up resources associated with <i class="arg">token</i>.
It is <em>strongly</em> recommended that you call this
function after you are done with a given GPX file.
Not doing so will result in memory not being freed, and
if your app calls <b class="cmd">::gpx::Create</b> enough times, the
memory leak could cause a performance hit...or worse.</p></dd>
<dt><a name="3"><b class="cmd">::gpx::GetGPXMetadata</b> <i class="arg">token</i></a></dt>
<dd><p>This procedure returns a dictionary of the metadata
associated with the GPX data identified by <i class="arg">token</i>.
The format of the metadata dictionary is described
below, but keys <em>version</em> and <em>creator</em>
will always be present.</p></dd>
<dt><a name="4"><b class="cmd">::gpx::GetWaypointCount</b> <i class="arg">token</i></a></dt>
<dd><p>This procedure returns the number of waypoints defined in the GPX
data identified by <i class="arg">token</i>.</p></dd>
<dt><a name="5"><b class="cmd">::gpx::GetAllWaypoints</b> <i class="arg">token</i></a></dt>
<dd><p>This procedure returns the a list of waypoints defined in the GPX
data identified by <i class="arg">token</i>. The format of each waypoint item
is described below.</p></dd>
<dt><a name="6"><b class="cmd">::gpx::GetTrackCount</b> <i class="arg">token</i></a></dt>
<dd><p>This procedure returns the number of tracks defined in the GPX
data identified by <i class="arg">token</i>.</p></dd>
<dt><a name="7"><b class="cmd">::gpx::GetTrackMetadata</b> <i class="arg">token</i> <i class="arg">whichTrack</i></a></dt>
<dd><p>This procedure returns a dictionary of the metadata
associated track number <i class="arg">whichTrack</i> (1 based) in
the GPX data identified by <i class="arg">token</i>.
The format of the metadata dictionary is described below.</p></dd>
<dt><a name="8"><b class="cmd">::gpx::GetTrackPoints</b> <i class="arg">token</i> <i class="arg">whichTrack</i></a></dt>
<dd><p>The procedure returns a list of track points comprising track
number <i class="arg">whichTrack</i> (1 based) in the GPX data identified by
<i class="arg">token</i>. The format of the metadata dictionary is described below.</p></dd>
<dt><a name="9"><b class="cmd">::gpx::GetRouteCount</b> <i class="arg">token</i></a></dt>
<dd><p>This procedure returns the number of routes defined in the GPX
data identified by <i class="arg">token</i>.</p></dd>
<dt><a name="10"><b class="cmd">::gpx::GetRouteMetadata</b> <i class="arg">token</i> <i class="arg">whichRoute</i></a></dt>
<dd><p>This procedure returns a dictionary of the metadata
associated route number <i class="arg">whichRoute</i> (1 based) in
the GPX data identified by <i class="arg">token</i>.
The format of the metadata dictionary is described below.</p></dd>
<dt><a name="11"><b class="cmd">::gpx::GetRoutePoints</b> <i class="arg">token</i> <i class="arg">whichRoute</i></a></dt>
<dd><p>The procedure returns a list of route points comprising route
number <i class="arg">whichRoute</i> (1 based) in the GPX data identified by
<i class="arg">token</i>. The format of the metadata dictionary is described below.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">DATA STRUCTURES</a></h2>
<dl class="doctools_definitions">
<dt>metadata dictionary</dt>
<dd><p>The metadata associated with either the GPX document, a
track, a route, a waypoint, a track point or route
point is returned in a dictionary. The keys of that
dictionary will be whatever optional GPX elements are
present. The value for each key depends on the GPX schema
for that element. For example, the value for a version
key will be a string, while for a link key will be
a sub-dictionary with keys <em>href</em> and optionally
<em>text</em> and <em>type</em>.</p></dd>
<dt>point item</dt>
<dd><p>Each item in a track or route list of points consists of
a list of three elements: <em>latitude</em>, <em>longitude</em> and
<em>metadata dictionary</em>. <em>Latitude</em> and <em>longitude</em>
are decimal numbers. The <em>metadata dictionary</em> format is
described above. For points in a track, typically there will
always be ele (elevation) and time metadata keys.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLE</a></h2>
<pre class="doctools_example">
% set token [::gpx::Create myGpxFile.gpx]
% set version [dict get [::gpx::GetGPXMetadata $token] version]
% set trackCnt [::gpx::GetTrackCount $token]
% set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
% lassign $firstPoint lat lon ptMetadata
% puts "first point in the first track is at $lat, $lon"
% if {[dict exists $ptMetadata ele]} {
puts "at elevation [dict get $ptMetadata ele] meters"
}
% ::gpx::Cleanup $token
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>GPX: the GPS Exchange Format
(<a href="http://www.topografix.com/gpx.asp">http://www.topografix.com/gpx.asp</a>)</p></li>
<li><p>GPX 1.1 Schema Documentation (<a href="http://www.topografix.com/GPX/1/1/">http://www.topografix.com/GPX/1/1/</a>)</p></li>
<li><p>GPX 1.0 Developer's Manual (<a href="http://www.topografix.com/gpx_manual.asp">http://www.topografix.com/gpx_manual.asp</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">AUTHOR</a></h2>
<p>Keith Vetter</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>gpx</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#gps">gps</a>, <a href="../../../../index.html#gpx">gpx</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File formats</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010, Keith Vetter <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_aycock/aycock.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
<div class='fossil-doc' data-title='grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::aycock(n) 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">OBJECT COMMAND</a></li>
<li class="doctools_section"><a href="#section4">DESCRIPTION</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section6">KEYWORDS</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">grammar::aycock <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::aycock::parser</b> <i class="arg">grammar</i> <span class="opt">?<b class="option">-verbose</b>?</span></a></li>
<li><a href="#2"><i class="arg">parserName</i> <b class="method">parse</b> <i class="arg">symList</i> <i class="arg">valList</i> <span class="opt">?<i class="arg">clientData</i>?</span></a></li>
<li><a href="#3"><i class="arg">parserName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">parserName</i> <b class="method">terminals</b></a></li>
<li><a href="#5"><i class="arg">parserName</i> <b class="method">nonterminals</b></a></li>
<li><a href="#6"><i class="arg">parserName</i> <b class="method">save</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">grammar::aycock</b> package
implements a parser generator for the class of parsers described
in John Aycock and R. Nigel Horspool. Practical Earley Parsing.
<em>The Computer Journal,</em> <em>45</em>(6):620-630, 2002.
<a href="http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254">http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254</a></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The <b class="package">grammar::aycock</b> package exports the single procedure:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::aycock::parser</b> <i class="arg">grammar</i> <span class="opt">?<b class="option">-verbose</b>?</span></a></dt>
<dd><p>Generates a parser for the given <i class="arg">grammar</i>, and returns its
name. If the optional <b class="option">-verbose</b> flag is given, dumps verbose
information relating to the generated parser to the standard output.
The returned parser is an object that accepts commands as shown in
<span class="sectref"><a href="#section3">OBJECT COMMAND</a></span> below.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OBJECT COMMAND</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">parserName</i> <b class="method">parse</b> <i class="arg">symList</i> <i class="arg">valList</i> <span class="opt">?<i class="arg">clientData</i>?</span></a></dt>
<dd><p>Invokes a parser returned from <b class="cmd">::aycock::parser</b>. <i class="arg">symList</i> is
a list of grammar symbols representing the terminals in an input
string, and <i class="arg">valList</i> is a list of their semantic values. The
result is the semantic value of the entire string when parsed.</p></dd>
<dt><a name="3"><i class="arg">parserName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys a parser constructed by <b class="cmd">::aycock::parser</b>.</p></dd>
<dt><a name="4"><i class="arg">parserName</i> <b class="method">terminals</b></a></dt>
<dd><p>Returns a list of terminal symbols that may be presented in the
<i class="arg">symList</i> argument to the <b class="method">parse</b> object command.</p></dd>
<dt><a name="5"><i class="arg">parserName</i> <b class="method">nonterminals</b></a></dt>
<dd><p>Returns a list of nonterminal symbols that were defined in the
parser's grammar.</p></dd>
<dt><a name="6"><i class="arg">parserName</i> <b class="method">save</b></a></dt>
<dd><p>Returns a Tcl script that will reconstruct the parser without
needing all the mechanism of the parser generator at run time.
The reconstructed parser depends on a set of commands in the
package <b class="package">grammar::aycock::runtime</b>,
which is also automatically loaded
when the <b class="package">grammar::aycock</b> package is loaded.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">DESCRIPTION</a></h2>
<p>The <b class="cmd">grammar::aycock::parser</b> command accepts a grammar expressed as
a Tcl list. The list must be structured as the concatenation of a set
of <i class="term">rule</i>s. Each <i class="term">rule</i> comprises a variable number of
elements in the list:</p>
<ul class="doctools_itemized">
<li><p>The name of the nonterminal symbol that the rule reduces.</p></li>
<li><p>The literal string, <b class="const">::=</b></p></li>
<li><p>Zero or more names of terminal or nonterminal symbols that
comprise the right-hand-side of the rule.</p></li>
<li><p>Finally, a Tcl script to execute when the rule is reduced.
Within the given script, a variable called <b class="variable">_</b> contains a list of
the semantic values of the symbols on the right-hand side. The value
returned by the script is expected to be the semantic value of the
left-hand side. If the <i class="arg">clientData</i> parameter was passed to the
<b class="method">parse</b> method, it is available in a variable called
<b class="variable">clientData</b>. It is permissible for the script to be the empty
string. In this case, the semantic value of the rule will be the same
as the semantic value of the first symbol on the right-hand side. If
the right-hand side is also empty, the semantic value will be the
empty string.</p></li>
</ul>
<p>Parsing is done with an Earley parser, which is not terribly efficient
in speed or memory consumption, but which deals effectively with
ambiguous grammars. For this reason, the <b class="package">grammar::aycock</b> package is
perhaps best adapted to natural-language processing or the parsing of
extraordinarily complex languages in which ambiguity can be tolerated.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLE</a></h2>
<p>The following code demonstrates a trivial desk calculator, admitting
only <b class="const">+</b>, <b class="const">*</b> and parentheses as its operators. It also
shows the format in which the lexical analyzer is expected to present
terminal symbols to the parser.</p>
<pre class="doctools_example">
set p [aycock::parser {
start ::= E {}
E ::= E + T {expr {[lindex $_ 0] + [lindex $_ 2]}}
E ::= T {}
T ::= T * F {expr {[lindex $_ 0] * [lindex $_ 2]}}
T ::= F {}
F ::= NUMBER {}
F ::= ( E ) {lindex $_ 1}
}]
puts [$p parse {( NUMBER + NUMBER ) * ( NUMBER + NUMBER ) } {{} 2 {} 3 {} {} {} 7 {} 1 {}}]
$p destroy
</pre>
<p>The example, when run, prints <b class="const">40</b>.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">KEYWORDS</a></h2>
<p>Aycock, Earley, Horspool, parser, compiler</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ambiguous">ambiguous</a>, <a href="../../../../index.html#aycock">aycock</a>, <a href="../../../../index.html#earley">earley</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#horspool">horspool</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 by Kevin B. Kenny <[email protected]><br>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
<div class='fossil-doc' data-title='grammar::fa::dacceptor - Finite automaton operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::fa::dacceptor(n) 0.1.1 tcllib "Finite automaton operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::fa::dacceptor - Create and use deterministic acceptors</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">ACCEPTOR METHODS</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">grammar::fa::dacceptor <span class="opt">?0.1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::fa::dacceptor</b> <i class="arg">daName</i> <i class="arg">fa</i> <span class="opt">?<b class="option">-any</b> <i class="arg">any</i>?</span></a></li>
<li><a href="#2"><b class="cmd">daName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">daName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">daName</i> <b class="method">accept?</b> <i class="arg">symbols</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for acceptors constructed from
deterministic <i class="term">finite automatons</i> (DFA). Acceptors are objects
which can be given a string of symbols and tell if the DFA they are
constructed from would <i class="term">accept</i> that string.
For the actual creation of the DFAs the acceptors are based on we have
the packages <b class="package"><a href="fa.html">grammar::fa</a></b> and <b class="package"><a href="faop.html">grammar::fa::op</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::fa::dacceptor</b> <i class="arg">daName</i> <i class="arg">fa</i> <span class="opt">?<b class="option">-any</b> <i class="arg">any</i>?</span></a></dt>
<dd><p>Creates a new deterministic acceptor with an associated global Tcl command
whose name is <i class="arg">daName</i>. This command may be used to invoke various
operations on the acceptor. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">daName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. See section <span class="sectref"><a href="#section3">ACCEPTOR METHODS</a></span> for more explanations.</p>
<p>The acceptor will be based on the deterministic finite automaton
stored in the object <i class="arg">fa</i>. It will keep a copy of the relevant
data of the FA in its own storage, in a form easy to use for its
purposes. This also means that changes made to the <i class="arg">fa</i> after the
construction of the acceptor <em>will not</em> influence the acceptor.</p>
<p>If <i class="arg">any</i> has been specified, then the acceptor will convert all
symbols in the input which are unknown to the base FA to that symbol
before proceeding with the processing.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">ACCEPTOR METHODS</a></h2>
<p>All acceptors provide the following methods for their manipulation:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">daName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the automaton, including its storage space and associated
command.</p></dd>
<dt><a name="4"><i class="arg">daName</i> <b class="method">accept?</b> <i class="arg">symbols</i></a></dt>
<dd><p>Takes the list of <i class="arg">symbols</i> and checks if the FA the acceptor is
based on would accept it. The result is a boolean value. <b class="const">True</b>
is returned if the symbols are accepted, and <b class="const">False</b>
otherwise. Note that bogus symbols in the input are either translated
to the <i class="arg">any</i> symbol (if specified), or cause the acceptance test
to simply fail. No errors will be thrown. The method will process only
just that prefix of the input which is enough to fully determine
(non-)acceptance.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_fa</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#acceptance">acceptance</a>, <a href="../../../../index.html#acceptor">acceptor</a>, <a href="../../../../index.html#automaton">automaton</a>, <a href="../../../../index.html#finite_automaton">finite automaton</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#regular_grammar">regular grammar</a>, <a href="../../../../index.html#regular_languages">regular languages</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_fa/dexec.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
<div class='fossil-doc' data-title='grammar::fa::dexec - Finite automaton operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::fa::dexec(n) 0.2 tcllib "Finite automaton operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::fa::dexec - Execute deterministic finite automatons</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">EXECUTOR METHODS</a></li>
<li class="doctools_section"><a href="#section4">EXECUTOR CALLBACK</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">grammar::fa::dexec <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::fa::dexec</b> <i class="arg">daName</i> <i class="arg">fa</i> <span class="opt">?<b class="option">-any</b> <i class="arg">any</i>?</span> <span class="opt">?<b class="option">-command</b> <i class="arg">cmdprefix</i>?</span></a></li>
<li><a href="#2"><b class="cmd">daName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">daName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">daName</i> <b class="method">put</b> <i class="arg">symbol</i></a></li>
<li><a href="#5"><i class="arg">daName</i> <b class="method">reset</b></a></li>
<li><a href="#6"><i class="arg">daName</i> <b class="method">state</b></a></li>
<li><a href="#7"><i class="arg">cmdprefix</i> <b class="method">error</b> <i class="arg">code</i> <i class="arg">message</i></a></li>
<li><a href="#8"><i class="arg">cmdprefix</i> <b class="method">final</b> <i class="arg">stateid</i></a></li>
<li><a href="#9"><i class="arg">cmdprefix</i> <b class="method">reset</b></a></li>
<li><a href="#10"><i class="arg">cmdprefix</i> <b class="method">state</b> <i class="arg">stateid</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for executors constructed from
deterministic <i class="term">finite automatons</i> (DFA). Executors are objects
which are given a string of symbols in a piecemal fashion, perform
state transitions and report back when they enter a final state, or
find an error in the input.
For the actual creation of the DFAs the executors are based on we have
the packages <b class="package"><a href="fa.html">grammar::fa</a></b> and <b class="package"><a href="faop.html">grammar::fa::op</a></b>.</p>
<p>The objects follow a push model. Symbols are pushed into the executor,
and when something important happens, i.e. error occurs, a state transition,
or a final state is entered this will be reported via the callback
specified via the option <b class="option">-command</b>. Note that conversion of
this into a pull model where the environment retrieves messages from
the object and the object uses a callback to ask for more symbols is
a trivial thing.</p>
<p><em>Side note</em>:
The acceptor objects provided by <b class="package"><a href="dacceptor.html">grammar::fa::dacceptor</a></b>
could have been implemented on top of the executors provided here, but
were not, to get a bit more performance (we avoid a number of method
calls and the time required for their dispatch).</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::fa::dexec</b> <i class="arg">daName</i> <i class="arg">fa</i> <span class="opt">?<b class="option">-any</b> <i class="arg">any</i>?</span> <span class="opt">?<b class="option">-command</b> <i class="arg">cmdprefix</i>?</span></a></dt>
<dd><p>Creates a new deterministic executor with an associated global Tcl
command whose name is <i class="arg">daName</i>. This command may be used to invoke
various operations on the executor. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">daName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. See section <span class="sectref"><a href="#section3">EXECUTOR METHODS</a></span> for more
explanations.</p>
<p>The executor will be based on the deterministic finite automaton
stored in the object <i class="arg">fa</i>. It will keep a copy of the relevant
data of the FA in its own storage, in a form easy to use for its
purposes. This also means that changes made to the <i class="arg">fa</i> after the
construction of the executor <em>will not</em> influence the executor.</p>
<p>If <i class="arg">any</i> has been specified, then the executor will convert all
symbols in the input which are unknown to the base FA to that symbol
before proceeding with the processing.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXECUTOR METHODS</a></h2>
<p>All executors provide the following methods for their manipulation:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">daName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the automaton, including its storage space and associated
command.</p></dd>
<dt><a name="4"><i class="arg">daName</i> <b class="method">put</b> <i class="arg">symbol</i></a></dt>
<dd><p>Takes the current state of the executor and the <i class="arg">symbol</i> and
performs the appropriate state transition. Reports any errors
encountered via the command callback, as well as entering a final
state of the underlying FA.</p>
<p>When an error is reported all further invokations of <b class="method">put</b> will
do nothing, until the error condition has been cleared via an
invokation of method <b class="method">reset</b>.</p></dd>
<dt><a name="5"><i class="arg">daName</i> <b class="method">reset</b></a></dt>
<dd><p>Unconditionally sets the executor into the start state of the
underlying FA. This also clears any error condition <b class="method">put</b> may
have encountered.</p></dd>
<dt><a name="6"><i class="arg">daName</i> <b class="method">state</b></a></dt>
<dd><p>Returns the current state of the underlying FA. This allow for
introspection without the need to pass data from the callback command.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXECUTOR CALLBACK</a></h2>
<p>The callback command <i class="arg">cmdprefix</i> given to an executor via the
option <b class="option">-command</b> will be executed by the object at the global
level, using the syntax described below. Note that <i class="arg">cmdprefix</i> is
not simply the name of a command, but a full command prefix. In other
words it may contain additional fixed argument words beyond the
command word.</p>
<dl class="doctools_definitions">
<dt><a name="7"><i class="arg">cmdprefix</i> <b class="method">error</b> <i class="arg">code</i> <i class="arg">message</i></a></dt>
<dd><p>The executor has encountered an error, and <i class="arg">message</i> contains a
human-readable text explaining the nature of the problem.
The <i class="arg">code</i> on the other hand is a fixed machine-readable text.
The following error codes can be generated by executor objects.</p>
<dl class="doctools_definitions">
<dt><b class="const">BADSYM</b></dt>
<dd><p>An unknown symbol was found in the input. This can happen if and only
if no <b class="option">-any</b> symbol was specified.</p></dd>
<dt><b class="const">BADTRANS</b></dt>
<dd><p>The underlying FA has no transition for the current combination of
input symbol and state. In other words, the executor was not able to
compute a new state for this combination.</p></dd>
</dl></dd>
<dt><a name="8"><i class="arg">cmdprefix</i> <b class="method">final</b> <i class="arg">stateid</i></a></dt>
<dd><p>The executor has entered the final state <i class="arg">stateid</i>.</p></dd>
<dt><a name="9"><i class="arg">cmdprefix</i> <b class="method">reset</b></a></dt>
<dd><p>The executor was reset.</p></dd>
<dt><a name="10"><i class="arg">cmdprefix</i> <b class="method">state</b> <i class="arg">stateid</i></a></dt>
<dd><p>The FA changed state due to a transition. <i class="arg">stateid</i> is the new state.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_fa</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#automaton">automaton</a>, <a href="../../../../index.html#execution">execution</a>, <a href="../../../../index.html#finite_automaton">finite automaton</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#regular_grammar">regular grammar</a>, <a href="../../../../index.html#regular_languages">regular languages</a>, <a href="../../../../index.html#running">running</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Andreas Kupries <[email protected]><br>
Copyright © 2007 Bogdan <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_fa/fa.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
|
<div class='fossil-doc' data-title='grammar::fa - Finite automaton operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::fa(n) 0.4 tcllib "Finite automaton operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::fa - Create and manipulate finite automatons</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">FA METHODS</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">FINITE AUTOMATONS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit 1.3</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">grammar::fa::op <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">grammar::fa <span class="opt">?0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::fa</b> <i class="arg">faName</i> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const"><--</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">src</i>|<b class="const">fromRegex</b> <i class="arg">re</i> <span class="opt">?<i class="arg">over</i>?</span>?</span></a></li>
<li><a href="#2"><b class="cmd">faName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">faName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">faName</i> <b class="method">clear</b></a></li>
<li><a href="#5"><i class="arg">faName</i> <b class="method">=</b> <i class="arg">srcFA</i></a></li>
<li><a href="#6"><i class="arg">faName</i> <b class="method">--></b> <i class="arg">dstFA</i></a></li>
<li><a href="#7"><i class="arg">faName</i> <b class="method">serialize</b></a></li>
<li><a href="#8"><i class="arg">faName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></li>
<li><a href="#9"><i class="arg">faName</i> <b class="method">states</b></a></li>
<li><a href="#10"><i class="arg">faName</i> <b class="method">state</b> <b class="method">add</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></li>
<li><a href="#11"><i class="arg">faName</i> <b class="method">state</b> <b class="method">delete</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></li>
<li><a href="#12"><i class="arg">faName</i> <b class="method">state</b> <b class="method">exists</b> <i class="arg">s</i></a></li>
<li><a href="#13"><i class="arg">faName</i> <b class="method">state</b> <b class="method">rename</b> <i class="arg">s</i> <i class="arg">snew</i></a></li>
<li><a href="#14"><i class="arg">faName</i> <b class="method">startstates</b></a></li>
<li><a href="#15"><i class="arg">faName</i> <b class="method">start</b> <b class="method">add</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></li>
<li><a href="#16"><i class="arg">faName</i> <b class="method">start</b> <b class="method">remove</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></li>
<li><a href="#17"><i class="arg">faName</i> <b class="method">start?</b> <i class="arg">s</i></a></li>
<li><a href="#18"><i class="arg">faName</i> <b class="method">start?set</b> <i class="arg">stateset</i></a></li>
<li><a href="#19"><i class="arg">faName</i> <b class="method">finalstates</b></a></li>
<li><a href="#20"><i class="arg">faName</i> <b class="method">final</b> <b class="method">add</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></li>
<li><a href="#21"><i class="arg">faName</i> <b class="method">final</b> <b class="method">remove</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></li>
<li><a href="#22"><i class="arg">faName</i> <b class="method">final?</b> <i class="arg">s</i></a></li>
<li><a href="#23"><i class="arg">faName</i> <b class="method">final?set</b> <i class="arg">stateset</i></a></li>
<li><a href="#24"><i class="arg">faName</i> <b class="method">symbols</b></a></li>
<li><a href="#25"><i class="arg">faName</i> <b class="method">symbols@</b> <i class="arg">s</i> <span class="opt">?<i class="arg">d</i>?</span></a></li>
<li><a href="#26"><i class="arg">faName</i> <b class="method">symbols@set</b> <i class="arg">stateset</i></a></li>
<li><a href="#27"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">add</b> <i class="arg">sym1</i> <span class="opt">?<i class="arg">sym2</i> ...?</span></a></li>
<li><a href="#28"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">delete</b> <i class="arg">sym1</i> <span class="opt">?<i class="arg">sym2</i> ...?</span></a></li>
<li><a href="#29"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">rename</b> <i class="arg">sym</i> <i class="arg">newsym</i></a></li>
<li><a href="#30"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">exists</b> <i class="arg">sym</i></a></li>
<li><a href="#31"><i class="arg">faName</i> <b class="method">next</b> <i class="arg">s</i> <i class="arg">sym</i> <span class="opt">?<b class="const">--></b> <i class="arg">next</i>?</span></a></li>
<li><a href="#32"><i class="arg">faName</i> <b class="method">!next</b> <i class="arg">s</i> <i class="arg">sym</i> <span class="opt">?<b class="const">--></b> <i class="arg">next</i>?</span></a></li>
<li><a href="#33"><i class="arg">faName</i> <b class="method">nextset</b> <i class="arg">stateset</i> <i class="arg">sym</i></a></li>
<li><a href="#34"><i class="arg">faName</i> <b class="method">is</b> <b class="method">deterministic</b></a></li>
<li><a href="#35"><i class="arg">faName</i> <b class="method">is</b> <b class="method">complete</b></a></li>
<li><a href="#36"><i class="arg">faName</i> <b class="method">is</b> <b class="method">useful</b></a></li>
<li><a href="#37"><i class="arg">faName</i> <b class="method">is</b> <b class="method">epsilon-free</b></a></li>
<li><a href="#38"><i class="arg">faName</i> <b class="method">reachable_states</b></a></li>
<li><a href="#39"><i class="arg">faName</i> <b class="method">unreachable_states</b></a></li>
<li><a href="#40"><i class="arg">faName</i> <b class="method">reachable</b> <i class="arg">s</i></a></li>
<li><a href="#41"><i class="arg">faName</i> <b class="method">useful_states</b></a></li>
<li><a href="#42"><i class="arg">faName</i> <b class="method">unuseful_states</b></a></li>
<li><a href="#43"><i class="arg">faName</i> <b class="method">useful</b> <i class="arg">s</i></a></li>
<li><a href="#44"><i class="arg">faName</i> <b class="method">epsilon_closure</b> <i class="arg">s</i></a></li>
<li><a href="#45"><i class="arg">faName</i> <b class="method">reverse</b></a></li>
<li><a href="#46"><i class="arg">faName</i> <b class="method">complete</b></a></li>
<li><a href="#47"><i class="arg">faName</i> <b class="method">remove_eps</b></a></li>
<li><a href="#48"><i class="arg">faName</i> <b class="method">trim</b> <span class="opt">?<i class="arg">what</i>?</span></a></li>
<li><a href="#49"><i class="arg">faName</i> <b class="method">determinize</b> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#50"><i class="arg">faName</i> <b class="method">minimize</b> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#51"><i class="arg">faName</i> <b class="method">complement</b></a></li>
<li><a href="#52"><i class="arg">faName</i> <b class="method">kleene</b></a></li>
<li><a href="#53"><i class="arg">faName</i> <b class="method">optional</b></a></li>
<li><a href="#54"><i class="arg">faName</i> <b class="method">union</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#55"><i class="arg">faName</i> <b class="method">intersect</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#56"><i class="arg">faName</i> <b class="method">difference</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#57"><i class="arg">faName</i> <b class="method">concatenate</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#58"><i class="arg">faName</i> <b class="method">fromRegex</b> <i class="arg">regex</i> <span class="opt">?<i class="arg">over</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a container class for
<i class="term">finite automatons</i> (Short: FA).
It allows the incremental definition of the automaton, its
manipulation and querying of the definition.
While the package provides complex operations on the automaton
(via package <b class="package"><a href="faop.html">grammar::fa::op</a></b>), it does not have the
ability to execute a definition for a stream of symbols.
Use the packages
<b class="package"><a href="dacceptor.html">grammar::fa::dacceptor</a></b> and
<b class="package"><a href="dexec.html">grammar::fa::dexec</a></b> for that.
Another package related to this is <b class="package">grammar::fa::compiler</b>. It
turns a FA into an executor class which has the definition of the FA
hardwired into it. The output of this package is configurable to suit
a large number of different implementation languages and paradigms.</p>
<p>For more information about what a finite automaton is see section
<span class="sectref"><a href="#section5">FINITE AUTOMATONS</a></span>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::fa</b> <i class="arg">faName</i> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const"><--</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">src</i>|<b class="const">fromRegex</b> <i class="arg">re</i> <span class="opt">?<i class="arg">over</i>?</span>?</span></a></dt>
<dd><p>Creates a new finite automaton with an associated global Tcl command
whose name is <i class="arg">faName</i>. This command may be used to invoke various
operations on the automaton. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">faName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. See section <span class="sectref"><a href="#section3">FA METHODS</a></span> for more explanations. The
new automaton will be empty if no <i class="arg">src</i> is specified. Otherwise
it will contain a copy of the definition contained in the <i class="arg">src</i>.
The <i class="arg">src</i> has to be a FA object reference for all operators except
<b class="const">deserialize</b> and <b class="const">fromRegex</b>. The <b class="const">deserialize</b>
operator requires <i class="arg">src</i> to be the serialization of a FA instead,
and <b class="const">fromRegex</b> takes a regular expression in the form a of a
syntax tree. See <b class="cmd">::grammar::fa::op::fromRegex</b> for more detail on
that.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FA METHODS</a></h2>
<p>All automatons provide the following methods for their manipulation:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">faName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the automaton, including its storage space and associated
command.</p></dd>
<dt><a name="4"><i class="arg">faName</i> <b class="method">clear</b></a></dt>
<dd><p>Clears out the definition of the automaton contained in <i class="arg">faName</i>,
but does <em>not</em> destroy the object.</p></dd>
<dt><a name="5"><i class="arg">faName</i> <b class="method">=</b> <i class="arg">srcFA</i></a></dt>
<dd><p>Assigns the contents of the automaton contained
in <i class="arg">srcFA</i> to <i class="arg">faName</i>, overwriting any
existing definition.
This is the assignment operator for automatons. It copies the
automaton contained in the FA object <i class="arg">srcFA</i> over the automaton
definition in <i class="arg">faName</i>. The old contents of <i class="arg">faName</i> are
deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">faName</i> <b class="method">deserialize</b> [<i class="arg">srcFA</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="6"><i class="arg">faName</i> <b class="method">--></b> <i class="arg">dstFA</i></a></dt>
<dd><p>This is the reverse assignment operator for automatons. It copies the
automation contained in the object <i class="arg">faName</i> over the automaton
definition in the object <i class="arg">dstFA</i>.
The old contents of <i class="arg">dstFA</i> are deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">dstFA</i> <b class="method">deserialize</b> [<i class="arg">faName</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="7"><i class="arg">faName</i> <b class="method">serialize</b></a></dt>
<dd><p>This method serializes the automaton stored in <i class="arg">faName</i>. In other
words it returns a tcl <em>value</em> completely describing that
automaton.
This allows, for example, the transfer of automatons over arbitrary
channels, persistence, etc.
This method is also the basis for both the copy constructor and the
assignment operator.</p>
<p>The result of this method has to be semantically identical over all
implementations of the <b class="package">grammar::fa</b> interface. This is what
will enable us to copy automatons between different implementations of
the same interface.</p>
<p>The result is a list of three elements with the following structure:</p>
<ol class="doctools_enumerated">
<li><p>The constant string <b class="const">grammar::fa</b>.</p></li>
<li><p>A list containing the names of all known input symbols. The order of
elements in this list is not relevant.</p></li>
<li><p>The last item in the list is a dictionary, however the order of the
keys is important as well. The keys are the states of the serialized
FA, and their order is the order in which to create the states when
deserializing. This is relevant to preserve the order relationship
between states.</p>
<p>The value of each dictionary entry is a list of three elements
describing the state in more detail.</p>
<ol class="doctools_enumerated">
<li><p>A boolean flag. If its value is <b class="const">true</b> then the state is a
start state, otherwise it is not.</p></li>
<li><p>A boolean flag. If its value is <b class="const">true</b> then the state is a
final state, otherwise it is not.</p></li>
<li><p>The last element is a dictionary describing the transitions for the
state. The keys are symbols (or the empty string), and the values are
sets of successor states.</p></li>
</ol>
</li>
</ol>
<p>Assuming the following FA (which describes the life of a truck driver
in a very simple way :)</p>
<pre class="doctools_example">
Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
(...) is the start state.
</pre>
<p>a possible serialization is</p>
<pre class="doctools_example">
grammar::fa \\
{yellow red green red/yellow} \\
{Drive {0 0 {yellow Brake}} \\
Brake {0 0 {red Stop}} \\
Stop {1 0 {red/yellow Attention}} \\
Attention {0 0 {green Drive}}}
</pre>
<p>A possible one, because I did not care about creation order here</p></dd>
<dt><a name="8"><i class="arg">faName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the
automaton definition in <i class="arg">faName</i> with the automaton described by
the <i class="arg">serialization</i> value. The old contents of <i class="arg">faName</i> are
deleted by this operation.</p></dd>
<dt><a name="9"><i class="arg">faName</i> <b class="method">states</b></a></dt>
<dd><p>Returns the set of all states known to <i class="arg">faName</i>.</p></dd>
<dt><a name="10"><i class="arg">faName</i> <b class="method">state</b> <b class="method">add</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></dt>
<dd><p>Adds the states <i class="arg">s1</i>, <i class="arg">s2</i>, et cetera to the FA definition in
<i class="arg">faName</i>. The operation will fail any of the new states is already
declared.</p></dd>
<dt><a name="11"><i class="arg">faName</i> <b class="method">state</b> <b class="method">delete</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></dt>
<dd><p>Deletes the state <i class="arg">s1</i>, <i class="arg">s2</i>, et cetera, and all associated
information from the FA definition in <i class="arg">faName</i>. The latter means
that the information about in- or outbound transitions is deleted as
well. If the deleted state was a start or final state then this
information is invalidated as well. The operation will fail if the
state <i class="arg">s</i> is not known to the FA.</p></dd>
<dt><a name="12"><i class="arg">faName</i> <b class="method">state</b> <b class="method">exists</b> <i class="arg">s</i></a></dt>
<dd><p>A predicate. It tests whether the state <i class="arg">s</i> is known to the FA in
<i class="arg">faName</i>.
The result is a boolean value. It will be set to <b class="const">true</b> if the
state <i class="arg">s</i> is known, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="13"><i class="arg">faName</i> <b class="method">state</b> <b class="method">rename</b> <i class="arg">s</i> <i class="arg">snew</i></a></dt>
<dd><p>Renames the state <i class="arg">s</i> to <i class="arg">snew</i>. Fails if <i class="arg">s</i> is not a
known state. Also fails if <i class="arg">snew</i> is already known as a state.</p></dd>
<dt><a name="14"><i class="arg">faName</i> <b class="method">startstates</b></a></dt>
<dd><p>Returns the set of states which are marked as <i class="term">start</i> states,
also known as <i class="term">initial</i> states.
See <span class="sectref"><a href="#section5">FINITE AUTOMATONS</a></span> for explanations what this means.</p></dd>
<dt><a name="15"><i class="arg">faName</i> <b class="method">start</b> <b class="method">add</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></dt>
<dd><p>Mark the states <i class="arg">s1</i>, <i class="arg">s2</i>, et cetera in the FA <i class="arg">faName</i>
as <i class="term">start</i> (aka <i class="term">initial</i>).</p></dd>
<dt><a name="16"><i class="arg">faName</i> <b class="method">start</b> <b class="method">remove</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></dt>
<dd><p>Mark the states <i class="arg">s1</i>, <i class="arg">s2</i>, et cetera in the FA <i class="arg">faName</i>
as <i class="term">not start</i> (aka <i class="term">not accepting</i>).</p></dd>
<dt><a name="17"><i class="arg">faName</i> <b class="method">start?</b> <i class="arg">s</i></a></dt>
<dd><p>A predicate. It tests if the state <i class="arg">s</i> in the FA <i class="arg">faName</i> is
<i class="term">start</i> or not.
The result is a boolean value. It will be set to <b class="const">true</b> if the
state <i class="arg">s</i> is <i class="term">start</i>, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="18"><i class="arg">faName</i> <b class="method">start?set</b> <i class="arg">stateset</i></a></dt>
<dd><p>A predicate. It tests if the set of states <i class="arg">stateset</i> contains at
least one start state. They operation will fail if the set contains an
element which is not a known state.
The result is a boolean value. It will be set to <b class="const">true</b> if a
start state is present in <i class="arg">stateset</i>, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="19"><i class="arg">faName</i> <b class="method">finalstates</b></a></dt>
<dd><p>Returns the set of states which are marked as <i class="term"><a href="../../../../index.html#final">final</a></i> states,
also known as <i class="term">accepting</i> states.
See <span class="sectref"><a href="#section5">FINITE AUTOMATONS</a></span> for explanations what this means.</p></dd>
<dt><a name="20"><i class="arg">faName</i> <b class="method">final</b> <b class="method">add</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></dt>
<dd><p>Mark the states <i class="arg">s1</i>, <i class="arg">s2</i>, et cetera in the FA <i class="arg">faName</i>
as <i class="term"><a href="../../../../index.html#final">final</a></i> (aka <i class="term">accepting</i>).</p></dd>
<dt><a name="21"><i class="arg">faName</i> <b class="method">final</b> <b class="method">remove</b> <i class="arg">s1</i> <span class="opt">?<i class="arg">s2</i> ...?</span></a></dt>
<dd><p>Mark the states <i class="arg">s1</i>, <i class="arg">s2</i>, et cetera in the FA <i class="arg">faName</i>
as <i class="term">not final</i> (aka <i class="term">not accepting</i>).</p></dd>
<dt><a name="22"><i class="arg">faName</i> <b class="method">final?</b> <i class="arg">s</i></a></dt>
<dd><p>A predicate. It tests if the state <i class="arg">s</i> in the FA <i class="arg">faName</i> is
<i class="term"><a href="../../../../index.html#final">final</a></i> or not.
The result is a boolean value. It will be set to <b class="const">true</b> if the
state <i class="arg">s</i> is <i class="term"><a href="../../../../index.html#final">final</a></i>, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="23"><i class="arg">faName</i> <b class="method">final?set</b> <i class="arg">stateset</i></a></dt>
<dd><p>A predicate. It tests if the set of states <i class="arg">stateset</i> contains at
least one final state. They operation will fail if the set contains an
element which is not a known state.
The result is a boolean value. It will be set to <b class="const">true</b> if a
final state is present in <i class="arg">stateset</i>, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="24"><i class="arg">faName</i> <b class="method">symbols</b></a></dt>
<dd><p>Returns the set of all symbols known to the FA <i class="arg">faName</i>.</p></dd>
<dt><a name="25"><i class="arg">faName</i> <b class="method">symbols@</b> <i class="arg">s</i> <span class="opt">?<i class="arg">d</i>?</span></a></dt>
<dd><p>Returns the set of all symbols for which the state <i class="arg">s</i> has transitions.
If the empty symbol is present then <i class="arg">s</i> has epsilon transitions. If two
states are specified the result is the set of symbols which have transitions
from <i class="arg">s</i> to <i class="arg">t</i>. This set may be empty if there are no transitions
between the two specified states.</p></dd>
<dt><a name="26"><i class="arg">faName</i> <b class="method">symbols@set</b> <i class="arg">stateset</i></a></dt>
<dd><p>Returns the set of all symbols for which at least one state in the set
of states <i class="arg">stateset</i> has transitions.
In other words, the union of [<i class="arg">faName</i> <b class="method">symbols@</b> <b class="variable">s</b>]
for all states <b class="variable">s</b> in <i class="arg">stateset</i>.
If the empty symbol is present then at least one state contained in
<i class="arg">stateset</i> has epsilon transitions.</p></dd>
<dt><a name="27"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">add</b> <i class="arg">sym1</i> <span class="opt">?<i class="arg">sym2</i> ...?</span></a></dt>
<dd><p>Adds the symbols <i class="arg">sym1</i>, <i class="arg">sym2</i>, et cetera to the FA
definition in <i class="arg">faName</i>. The operation will fail any of the symbols
is already declared. The empty string is not allowed as a value for the symbols.</p></dd>
<dt><a name="28"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">delete</b> <i class="arg">sym1</i> <span class="opt">?<i class="arg">sym2</i> ...?</span></a></dt>
<dd><p>Deletes the symbols <i class="arg">sym1</i>, <i class="arg">sym2</i> et cetera, and all
associated information from the FA definition in <i class="arg">faName</i>. The
latter means that all transitions using the symbols are deleted as
well. The operation will fail if any of the symbols is not known to
the FA.</p></dd>
<dt><a name="29"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">rename</b> <i class="arg">sym</i> <i class="arg">newsym</i></a></dt>
<dd><p>Renames the symbol <i class="arg">sym</i> to <i class="arg">newsym</i>. Fails if <i class="arg">sym</i> is
not a known symbol. Also fails if <i class="arg">newsym</i> is already known as a
symbol.</p></dd>
<dt><a name="30"><i class="arg">faName</i> <b class="method">symbol</b> <b class="method">exists</b> <i class="arg">sym</i></a></dt>
<dd><p>A predicate. It tests whether the symbol <i class="arg">sym</i> is known to the FA
in <i class="arg">faName</i>.
The result is a boolean value. It will be set to <b class="const">true</b> if the
symbol <i class="arg">sym</i> is known, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="31"><i class="arg">faName</i> <b class="method">next</b> <i class="arg">s</i> <i class="arg">sym</i> <span class="opt">?<b class="const">--></b> <i class="arg">next</i>?</span></a></dt>
<dd><p>Define or query transition information.</p>
<p>If <i class="arg">next</i> is specified, then the method will add a transition from
the state <i class="arg">s</i> to the <i class="term">successor</i> state <i class="arg">next</i> labeled with
the symbol <i class="arg">sym</i> to the FA contained in <i class="arg">faName</i>. The
operation will fail if <i class="arg">s</i>, or <i class="arg">next</i> are not known states, or
if <i class="arg">sym</i> is not a known symbol. An exception to the latter is that
<i class="arg">sym</i> is allowed to be the empty string. In that case the new
transition is an <i class="term">epsilon transition</i> which will not consume
input when traversed. The operation will also fail if the combination
of (<i class="arg">s</i>, <i class="arg">sym</i>, and <i class="arg">next</i>) is already present in the FA.</p>
<p>If <i class="arg">next</i> was not specified, then the method will return
the set of states which can be reached from <i class="arg">s</i> through
a single transition labeled with symbol <i class="arg">sym</i>.</p></dd>
<dt><a name="32"><i class="arg">faName</i> <b class="method">!next</b> <i class="arg">s</i> <i class="arg">sym</i> <span class="opt">?<b class="const">--></b> <i class="arg">next</i>?</span></a></dt>
<dd><p>Remove one or more transitions from the Fa in <i class="arg">faName</i>.</p>
<p>If <i class="arg">next</i> was specified then the single transition from the state
<i class="arg">s</i> to the state <i class="arg">next</i> labeled with the symbol <i class="arg">sym</i> is
removed from the FA. Otherwise <em>all</em> transitions originating in
state <i class="arg">s</i> and labeled with the symbol <i class="arg">sym</i> will be removed.</p>
<p>The operation will fail if <i class="arg">s</i> and/or <i class="arg">next</i> are not known as
states. It will also fail if a non-empty <i class="arg">sym</i> is not known as
symbol. The empty string is acceptable, and allows the removal of
epsilon transitions.</p></dd>
<dt><a name="33"><i class="arg">faName</i> <b class="method">nextset</b> <i class="arg">stateset</i> <i class="arg">sym</i></a></dt>
<dd><p>Returns the set of states which can be reached by a single transition
originating in a state in the set <i class="arg">stateset</i> and labeled with the
symbol <i class="arg">sym</i>.</p>
<p>In other words, this is the union of
[<i class="arg">faName</i> next <b class="variable">s</b> <i class="arg">symbol</i>]
for all states <b class="variable">s</b> in <i class="arg">stateset</i>.</p></dd>
<dt><a name="34"><i class="arg">faName</i> <b class="method">is</b> <b class="method">deterministic</b></a></dt>
<dd><p>A predicate. It tests whether the FA in <i class="arg">faName</i> is a
deterministic FA or not.
The result is a boolean value. It will be set to <b class="const">true</b> if the
FA is deterministic, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="35"><i class="arg">faName</i> <b class="method">is</b> <b class="method">complete</b></a></dt>
<dd><p>A predicate. It tests whether the FA in <i class="arg">faName</i> is a complete FA
or not. A FA is complete if it has at least one transition per state
and symbol. This also means that a FA without symbols, or states is
also complete.
The result is a boolean value. It will be set to <b class="const">true</b> if the
FA is deterministic, and <b class="const">false</b> otherwise.</p>
<p>Note: When a FA has epsilon-transitions transitions over a symbol for
a state S can be indirect, i.e. not attached directly to S, but to a
state in the epsilon-closure of S. The symbols for such indirect
transitions count when computing completeness.</p></dd>
<dt><a name="36"><i class="arg">faName</i> <b class="method">is</b> <b class="method">useful</b></a></dt>
<dd><p>A predicate. It tests whether the FA in <i class="arg">faName</i> is an useful FA
or not. A FA is useful if all states are <i class="term">reachable</i>
and <i class="term">useful</i>.
The result is a boolean value. It will be set to <b class="const">true</b> if the
FA is deterministic, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="37"><i class="arg">faName</i> <b class="method">is</b> <b class="method">epsilon-free</b></a></dt>
<dd><p>A predicate. It tests whether the FA in <i class="arg">faName</i> is an
epsilon-free FA or not. A FA is epsilon-free if it has no epsilon
transitions. This definition means that all deterministic FAs are
epsilon-free as well, and epsilon-freeness is a necessary
pre-condition for deterministic'ness.
The result is a boolean value. It will be set to <b class="const">true</b> if the
FA is deterministic, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="38"><i class="arg">faName</i> <b class="method">reachable_states</b></a></dt>
<dd><p>Returns the set of states which are reachable from a start state by
one or more transitions.</p></dd>
<dt><a name="39"><i class="arg">faName</i> <b class="method">unreachable_states</b></a></dt>
<dd><p>Returns the set of states which are not reachable from any start state
by any number of transitions. This is</p>
<pre class="doctools_example">
[faName states] - [faName reachable_states]
</pre>
</dd>
<dt><a name="40"><i class="arg">faName</i> <b class="method">reachable</b> <i class="arg">s</i></a></dt>
<dd><p>A predicate. It tests whether the state <i class="arg">s</i> in the FA <i class="arg">faName</i>
can be reached from a start state by one or more transitions.
The result is a boolean value. It will be set to <b class="const">true</b> if the
state can be reached, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="41"><i class="arg">faName</i> <b class="method">useful_states</b></a></dt>
<dd><p>Returns the set of states which are able to reach a final state by
one or more transitions.</p></dd>
<dt><a name="42"><i class="arg">faName</i> <b class="method">unuseful_states</b></a></dt>
<dd><p>Returns the set of states which are not able to reach a final state by
any number of transitions. This is</p>
<pre class="doctools_example">
[faName states] - [faName useful_states]
</pre>
</dd>
<dt><a name="43"><i class="arg">faName</i> <b class="method">useful</b> <i class="arg">s</i></a></dt>
<dd><p>A predicate. It tests whether the state <i class="arg">s</i> in the FA <i class="arg">faName</i>
is able to reach a final state by one or more transitions.
The result is a boolean value. It will be set to <b class="const">true</b> if the
state is useful, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="44"><i class="arg">faName</i> <b class="method">epsilon_closure</b> <i class="arg">s</i></a></dt>
<dd><p>Returns the set of states which are reachable from the state <i class="arg">s</i>
in the FA <i class="arg">faName</i> by one or more epsilon transitions, i.e
transitions over the empty symbol, transitions which do not consume
input. This is called the <i class="term">epsilon closure</i> of <i class="arg">s</i>.</p></dd>
<dt><a name="45"><i class="arg">faName</i> <b class="method">reverse</b></a></dt>
<dd></dd>
<dt><a name="46"><i class="arg">faName</i> <b class="method">complete</b></a></dt>
<dd></dd>
<dt><a name="47"><i class="arg">faName</i> <b class="method">remove_eps</b></a></dt>
<dd></dd>
<dt><a name="48"><i class="arg">faName</i> <b class="method">trim</b> <span class="opt">?<i class="arg">what</i>?</span></a></dt>
<dd></dd>
<dt><a name="49"><i class="arg">faName</i> <b class="method">determinize</b> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd></dd>
<dt><a name="50"><i class="arg">faName</i> <b class="method">minimize</b> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd></dd>
<dt><a name="51"><i class="arg">faName</i> <b class="method">complement</b></a></dt>
<dd></dd>
<dt><a name="52"><i class="arg">faName</i> <b class="method">kleene</b></a></dt>
<dd></dd>
<dt><a name="53"><i class="arg">faName</i> <b class="method">optional</b></a></dt>
<dd></dd>
<dt><a name="54"><i class="arg">faName</i> <b class="method">union</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd></dd>
<dt><a name="55"><i class="arg">faName</i> <b class="method">intersect</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd></dd>
<dt><a name="56"><i class="arg">faName</i> <b class="method">difference</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd></dd>
<dt><a name="57"><i class="arg">faName</i> <b class="method">concatenate</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd></dd>
<dt><a name="58"><i class="arg">faName</i> <b class="method">fromRegex</b> <i class="arg">regex</i> <span class="opt">?<i class="arg">over</i>?</span></a></dt>
<dd><p>These methods provide more complex operations on the FA. Please see
the same-named commands in the package <b class="package"><a href="faop.html">grammar::fa::op</a></b> for
descriptions of what they do.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">FINITE AUTOMATONS</a></h2>
<p>For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where</p>
<ul class="doctools_itemized">
<li><p>S is a set of <i class="term">states</i>,</p></li>
<li><p>Sy a set of <i class="term">input symbols</i>,</p></li>
<li><p>St is a subset of S, the set of <i class="term">start</i> states, also known as
<i class="term">initial</i> states.</p></li>
<li><p>Fi is a subset of S, the set of <i class="term"><a href="../../../../index.html#final">final</a></i> states, also known as
<i class="term">accepting</i>.</p></li>
<li><p>T is a function from S x (Sy + epsilon) to {S}, the <i class="term">transition function</i>.
Here <b class="const">epsilon</b> denotes the empty input symbol and is distinct
from all symbols in Sy; and {S} is the set of subsets of S. In other
words, T maps a combination of State and Input (which can be empty) to
a set of <i class="term">successor states</i>.</p></li>
</ul>
<p>In computer theory a FA is most often shown as a graph where the nodes
represent the states, and the edges between the nodes encode the
transition function: For all n in S' = T (s, sy) we have one edge
between the nodes representing s and n resp., labeled with sy. The
start and accepting states are encoded through distinct visual
markers, i.e. they are attributes of the nodes.</p>
<p>FA's are used to process streams of symbols over Sy.</p>
<p>A specific FA is said to <i class="term">accept</i> a finite stream sy_1 sy_2
... sy_n if there is a path in the graph of the FA beginning at a
state in St and ending at a state in Fi whose edges have the labels
sy_1, sy_2, etc. to sy_n.
The set of all strings accepted by the FA is the <i class="term">language</i> of
the FA. One important equivalence is that the set of languages which
can be accepted by an FA is the set of <i class="term"><a href="../../../../index.html#regular_languages">regular languages</a></i>.</p>
<p>Another important concept is that of deterministic FAs. A FA is said
to be <i class="term">deterministic</i> if for each string of input symbols there
is exactly one path in the graph of the FA beginning at the start
state and whose edges are labeled with the symbols in the string.
While it might seem that non-deterministic FAs to have more power of
recognition, this is not so. For each non-deterministic FA we can
construct a deterministic FA which accepts the same language (-->
Thompson's subset construction).</p>
<p>While one of the premier applications of FAs is in <i class="term"><a href="../../../../index.html#parsing">parsing</a></i>,
especially in the <i class="term"><a href="../../../../index.html#lexer">lexer</a></i> stage (where symbols == characters),
this is not the only possibility by far.</p>
<p>Quite a lot of processes can be modeled as a FA, albeit with a
possibly large set of states. For these the notion of accepting states
is often less or not relevant at all. What is needed instead is the
ability to act to state changes in the FA, i.e. to generate some
output in response to the input.
This transforms a FA into a <i class="term">finite transducer</i>, which has an
additional set OSy of <i class="term">output symbols</i> and also an additional
<i class="term">output function</i> O which maps from "S x (Sy + epsilon)" to
"(Osy + epsilon)", i.e a combination of state and input, possibly
empty to an output symbol, or nothing.</p>
<p>For the graph representation this means that edges are additional
labeled with the output symbol to write when this edge is traversed
while matching input. Note that for an application "writing an output
symbol" can also be "executing some code".</p>
<p>Transducers are not handled by this package. They will get their own
package in the future.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_fa</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#automaton">automaton</a>, <a href="../../../../index.html#finite_automaton">finite automaton</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#regular_grammar">regular grammar</a>, <a href="../../../../index.html#regular_languages">regular languages</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_fa/faop.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
|
<div class='fossil-doc' data-title='grammar::fa::op - Finite automaton operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::fa::op(n) 0.4 tcllib "Finite automaton operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::fa::op - Operations on finite automatons</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">grammar::fa::op <span class="opt">?0.4.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::fa::op::constructor</b> <i class="arg">cmd</i></a></li>
<li><a href="#2"><b class="cmd">::grammar::fa::op::reverse</b> <i class="arg">fa</i></a></li>
<li><a href="#3"><b class="cmd">::grammar::fa::op::complete</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">sink</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::grammar::fa::op::remove_eps</b> <i class="arg">fa</i></a></li>
<li><a href="#5"><b class="cmd">::grammar::fa::op::trim</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">what</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::grammar::fa::op::determinize</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::grammar::fa::op::minimize</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::grammar::fa::op::complement</b> <i class="arg">fa</i></a></li>
<li><a href="#9"><b class="cmd">::grammar::fa::op::kleene</b> <i class="arg">fa</i></a></li>
<li><a href="#10"><b class="cmd">::grammar::fa::op::optional</b> <i class="arg">fa</i></a></li>
<li><a href="#11"><b class="cmd">::grammar::fa::op::union</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::grammar::fa::op::intersect</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::grammar::fa::op::difference</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::grammar::fa::op::concatenate</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></li>
<li><a href="#15"><b class="cmd">::grammar::fa::op::fromRegex</b> <i class="arg">fa</i> <i class="arg">regex</i> <span class="opt">?<i class="arg">over</i>?</span></a></li>
<li><a href="#16"><b class="cmd">::grammar::fa::op::toRegexp</b> <i class="arg">fa</i></a></li>
<li><a href="#17"><b class="cmd">::grammar::fa::op::toRegexp2</b> <i class="arg">fa</i></a></li>
<li><a href="#18"><b class="cmd">::grammar::fa::op::toTclRegexp</b> <i class="arg">regexp</i> <i class="arg">symdict</i></a></li>
<li><a href="#19"><b class="cmd">::grammar::fa::op::simplifyRegexp</b> <i class="arg">regexp</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a number of complex operations on finite
automatons (Short: FA),
as provided by the package <b class="package"><a href="fa.html">grammar::fa</a></b>.
The package does not provide the ability to create and/or manipulate
such FAs, nor the ability to execute a FA for a stream of symbols.
Use the packages <b class="package"><a href="fa.html">grammar::fa</a></b>
and <b class="package">grammar::fa::interpreter</b> for that.
Another package related to this is <b class="package">grammar::fa::compiler</b>
which turns a FA into an executor class which has the definition of
the FA hardwired into it.</p>
<p>For more information about what a finite automaton is see section
<em>FINITE AUTOMATONS</em> in package <b class="package"><a href="fa.html">grammar::fa</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports the API described here. All commands modify their
first argument. I.e. whatever FA they compute is stored back into
it. Some of the operations will construct an automaton whose states
are all new, but related to the states in the source
automaton(s). These operations take variable names as optional
arguments where they will store mappings which describe the
relationship(s).
The operations can be loosely partitioned into structural and language
operations. The latter are defined in terms of the language the
automaton(s) accept, whereas the former are defined in terms of the
structural properties of the involved automaton(s). Some operations
are both.
<em>Structure operations</em></p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::fa::op::constructor</b> <i class="arg">cmd</i></a></dt>
<dd><p>This command has to be called by the user of the package before any other
operations is performed, to establish a command which can be used to
construct a FA container object. If this is not done several operations
will fail as they are unable to construct internal and transient containers
to hold state and/or partial results.</p>
<p>Any container class using this package for complex operations should set
its own class command as the constructor. See package <b class="package"><a href="fa.html">grammar::fa</a></b>
for an example.</p></dd>
<dt><a name="2"><b class="cmd">::grammar::fa::op::reverse</b> <i class="arg">fa</i></a></dt>
<dd><p>Reverses the <i class="arg">fa</i>. This is done by reversing the direction of all
transitions and swapping the sets of <i class="term">start</i> and <i class="term"><a href="../../../../index.html#final">final</a></i>
states. The language of <i class="arg">fa</i> changes unpredictably.</p></dd>
<dt><a name="3"><b class="cmd">::grammar::fa::op::complete</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">sink</i>?</span></a></dt>
<dd><p>Completes the <i class="arg">fa</i> <i class="term">complete</i>, but nothing is done if the
<i class="arg">fa</i> is already <i class="term">complete</i>. This implies that only the first
in a series of multiple consecutive complete operations on <i class="arg">fa</i>
will perform anything. The remainder will be null operations.</p>
<p>The language of <i class="arg">fa</i> is unchanged by this operation.</p>
<p>This is done by adding a single new state, the <i class="term">sink</i>, and
transitions from all other states to that sink for all symbols they
have no transitions for. The sink itself is made complete by adding
loop transitions for all symbols.</p>
<p>Note: When a FA has epsilon-transitions transitions over a symbol for
a state S can be indirect, i.e. not attached directly to S, but to a
state in the epsilon-closure of S. The symbols for such indirect
transitions count when computing completeness of a state. In other
words, these indirectly reached symbols are <em>not</em> missing.</p>
<p>The argument <i class="arg">sink</i> provides the name for the new state and most
not be present in the <i class="arg">fa</i> if specified. If the name is not
specified the command will name the state "sink<b class="variable">n</b>", where <b class="variable">n</b>
is set so that there are no collisions with existing states.</p>
<p>Note that the sink state is <i class="term">not useful</i> by definition. In
other words, while the FA becomes complete, it is also
<i class="term">not useful</i> in the strict sense as it has a state from which
no final state can be reached.</p></dd>
<dt><a name="4"><b class="cmd">::grammar::fa::op::remove_eps</b> <i class="arg">fa</i></a></dt>
<dd><p>Removes all epsilon-transitions from the <i class="arg">fa</i> in such a manner the
the language of <i class="arg">fa</i> is unchanged. However nothing is done if the
<i class="arg">fa</i> is already <i class="term">epsilon-free</i>.
This implies that only the first in a series of multiple consecutive
complete operations on <i class="arg">fa</i> will perform anything. The remainder
will be null operations.</p>
<p><em>Note:</em> This operation may cause states to become unreachable or
not useful. These states are not removed by this operation.
Use <b class="cmd">::grammar::fa::op::trim</b> for that instead.</p></dd>
<dt><a name="5"><b class="cmd">::grammar::fa::op::trim</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">what</i>?</span></a></dt>
<dd><p>Removes unwanted baggage from <i class="arg">fa</i>.
The legal values for <i class="arg">what</i> are listed below. The command defaults
to <b class="const">!reachable|!useful</b> if no specific argument was given.</p>
<dl class="doctools_definitions">
<dt><b class="const">!reachable</b></dt>
<dd><p>Removes all states which are not reachable from a start state.</p></dd>
<dt><b class="const">!useful</b></dt>
<dd><p>Removes all states which are unable to reach a final state.</p></dd>
<dt><b class="const">!reachable&!useful</b></dt>
<dd></dd>
<dt><b class="const">!(reachable|useful)</b></dt>
<dd><p>Removes all states which are not reachable from a start state and are
unable to reach a final state.</p></dd>
<dt><b class="const">!reachable|!useful</b></dt>
<dd></dd>
<dt><b class="const">!(reachable&useful)</b></dt>
<dd><p>Removes all states which are not reachable from a start state or are
unable to reach a final state.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::grammar::fa::op::determinize</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd><p>Makes the <i class="arg">fa</i> deterministic without changing the language
accepted by the <i class="arg">fa</i>. However nothing is done if the <i class="arg">fa</i> is
already <i class="term">deterministic</i>. This implies that only the first in a
series of multiple consecutive complete operations on <i class="arg">fa</i> will
perform anything. The remainder will be null operations.</p>
<p>The command will store a dictionary describing the relationship
between the new states of the resulting dfa and the states of the
input nfa in <i class="arg">mapvar</i>, if it has been specified. Keys of the
dictionary are the handles for the states of the resulting dfa, values
are sets of states from the input nfa.</p>
<p><em>Note</em>: An empty dictionary signals that the command was able to
make the <i class="arg">fa</i> deterministic without performing a full subset
construction, just by removing states and shuffling transitions around
(As part of making the FA epsilon-free).</p>
<p><em>Note</em>: The algorithm fails to make the FA deterministic in the
technical sense if the FA has no start state(s), because determinism
requires the FA to have exactly one start states.
In that situation we make a best effort; and the missing start state
will be the only condition preventing the generated result from being
<i class="term">deterministic</i>.
It should also be noted that in this case the possibilities for
trimming states from the FA are also severely reduced as we cannot
declare states unreachable.</p></dd>
<dt><a name="7"><b class="cmd">::grammar::fa::op::minimize</b> <i class="arg">fa</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd><p>Creates a FA which accepts the same language as <i class="arg">fa</i>, but has a
minimal number of states. Uses Brzozowski's method to accomplish this.</p>
<p>The command will store a dictionary describing the relationship
between the new states of the resulting minimal fa and the states of
the input fa in <i class="arg">mapvar</i>, if it has been specified. Keys of the
dictionary are the handles for the states of the resulting minimal fa,
values are sets of states from the input fa.</p>
<p><em>Note</em>: An empty dictionary signals that the command was able to
minimize the <i class="arg">fa</i> without having to compute new states. This
should happen if and only if the input FA was already minimal.</p>
<p><em>Note</em>: If the algorithm has no start or final states to work
with then the result might be technically minimal, but have a very
unexpected structure.
It should also be noted that in this case the possibilities for
trimming states from the FA are also severely reduced as we cannot
declare states unreachable.</p></dd>
</dl>
<p><em>Language operations</em>
All operations in this section require that all input FAs have at
least one start and at least one final state. Otherwise the language of
the FAs will not be defined, making the operation senseless (as it
operates on the languages of the FAs in a defined manner).</p>
<dl class="doctools_definitions">
<dt><a name="8"><b class="cmd">::grammar::fa::op::complement</b> <i class="arg">fa</i></a></dt>
<dd><p>Complements <i class="arg">fa</i>. This is possible if and only if <i class="arg">fa</i> is
<i class="term">complete</i> and <i class="term">deterministic</i>. The resulting FA accepts the
complementary language of <i class="arg">fa</i>. In other words, all inputs not
accepted by the input are accepted by the result, and vice versa.</p>
<p>The result will have all states and transitions of the input, and
different final states.</p></dd>
<dt><a name="9"><b class="cmd">::grammar::fa::op::kleene</b> <i class="arg">fa</i></a></dt>
<dd><p>Applies Kleene's closure to <i class="arg">fa</i>.
The resulting FA accepts all strings <b class="variable">S</b> for which we can find a
natural number <b class="variable">n</b> (0 inclusive) and strings <b class="variable">A1</b> ... <b class="variable">An</b>
in the language of <i class="arg">fa</i> such that <b class="variable">S</b> is the concatenation of
<b class="variable">A1</b> ... <b class="variable">An</b>.
In other words, the language of the result is the infinite union over
finite length concatenations over the language of <i class="arg">fa</i>.</p>
<p>The result will have all states and transitions of the input, and new
start and final states.</p></dd>
<dt><a name="10"><b class="cmd">::grammar::fa::op::optional</b> <i class="arg">fa</i></a></dt>
<dd><p>Makes the <i class="arg">fa</i> optional. In other words it computes the FA which
accepts the language of <i class="arg">fa</i> and the empty the word (epsilon) as
well.</p>
<p>The result will have all states and transitions of the input, and new
start and final states.</p></dd>
<dt><a name="11"><b class="cmd">::grammar::fa::op::union</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd><p>Combines the FAs <i class="arg">fa</i> and <i class="arg">fb</i> such that the resulting FA
accepts the union of the languages of the two FAs.</p>
<p>The result will have all states and transitions of the two input FAs,
and new start and final states. All states of <i class="arg">fb</i> which exist in
<i class="arg">fa</i> as well will be renamed, and the <i class="arg">mapvar</i> will contain a
mapping from the old states of <i class="arg">fb</i> to the new ones, if present.</p>
<p>It should be noted that the result will be non-deterministic, even if
the inputs are deterministic.</p></dd>
<dt><a name="12"><b class="cmd">::grammar::fa::op::intersect</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd><p>Combines the FAs <i class="arg">fa</i> and <i class="arg">fb</i> such that the resulting FA
accepts the intersection of the languages of the two FAs. In other
words, the result will accept a word if and only if the word is
accepted by both <i class="arg">fa</i> and <i class="arg">fb</i>. The result will be useful, but
not necessarily deterministic or minimal.</p>
<p>The command will store a dictionary describing the relationship
between the new states of the resulting fa and the pairs of states of
the input FAs in <i class="arg">mapvar</i>, if it has been specified. Keys of the
dictionary are the handles for the states of the resulting fa, values
are pairs of states from the input FAs. Pairs are represented by
lists. The first element in each pair will be a state in <i class="arg">fa</i>, the
second element will be drawn from <i class="arg">fb</i>.</p></dd>
<dt><a name="13"><b class="cmd">::grammar::fa::op::difference</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd><p>Combines the FAs <i class="arg">fa</i> and <i class="arg">fb</i> such that the resulting FA
accepts the difference of the languages of the two FAs. In other
words, the result will accept a word if and only if the word is
accepted by <i class="arg">fa</i>, but not by <i class="arg">fb</i>. This can also be expressed
as the intersection of <i class="arg">fa</i> with the complement of <i class="arg">fb</i>. The
result will be useful, but not necessarily deterministic or minimal.</p>
<p>The command will store a dictionary describing the relationship
between the new states of the resulting fa and the pairs of states of
the input FAs in <i class="arg">mapvar</i>, if it has been specified. Keys of the
dictionary are the handles for the states of the resulting fa, values
are pairs of states from the input FAs. Pairs are represented by
lists. The first element in each pair will be a state in <i class="arg">fa</i>, the
second element will be drawn from <i class="arg">fb</i>.</p></dd>
<dt><a name="14"><b class="cmd">::grammar::fa::op::concatenate</b> <i class="arg">fa</i> <i class="arg">fb</i> <span class="opt">?<i class="arg">mapvar</i>?</span></a></dt>
<dd><p>Combines the FAs <i class="arg">fa</i> and <i class="arg">fb</i> such that the resulting FA
accepts the cross-product of the languages of the two FAs. I.e. a word
W will be accepted by the result if there are two words A and B
accepted by <i class="arg">fa</i>, and <i class="arg">fb</i> resp. and W is the concatenation of
A and B.</p>
<p>The result FA will be non-deterministic.</p></dd>
<dt><a name="15"><b class="cmd">::grammar::fa::op::fromRegex</b> <i class="arg">fa</i> <i class="arg">regex</i> <span class="opt">?<i class="arg">over</i>?</span></a></dt>
<dd><p>Generates a non-deterministic FA which accepts the same language as
the regular expression <i class="arg">regex</i>. If the <i class="arg">over</i> is specified it
is treated as the set of symbols the regular expression and the
automaton are defined over. The command will compute the set from the
"S" constructors in <i class="arg">regex</i> when <i class="arg">over</i> was not
specified. This set is important if and only if the complement
operator "!" is used in <i class="arg">regex</i> as the complementary language of
an FA is quite different for different sets of symbols.</p>
<p>The regular expression is represented by a nested list, which forms
a syntax tree. The following structures are legal:</p>
<dl class="doctools_definitions">
<dt>{S x}</dt>
<dd><p>Atomic regular expression. Everything else is constructed from
these. Accepts the <b class="const">S</b>ymbol "x".</p></dd>
<dt>{. A1 A2 ...}</dt>
<dd><p>Concatenation operator. Accepts the concatenation of the regular
expressions <b class="variable">A1</b>, <b class="variable">A2</b>, etc.</p>
<p><em>Note</em> that this operator accepts zero or more arguments. With zero
arguments the represented language is <i class="term">epsilon</i>, the empty word.</p></dd>
<dt>{| A1 A2 ...}</dt>
<dd><p>Choice operator, also called "Alternative". Accepts all input accepted
by at least one of the regular expressions <b class="variable">A1</b>, <b class="variable">A2</b>, etc. In
other words, the union of <b class="variable">A1</b>, <b class="variable">A2</b>.</p>
<p><em>Note</em> that this operator accepts zero or more arguments. With zero
arguments the represented language is the <i class="term">empty</i> language,
the language without words.</p></dd>
<dt>{& A1 A2 ...}</dt>
<dd><p>Intersection operator, logical and. Accepts all input accepted which
is accepted by all of the regular expressions <b class="variable">A1</b>, <b class="variable">A2</b>,
etc. In other words, the intersection of <b class="variable">A1</b>, <b class="variable">A2</b>.</p></dd>
<dt>{? A}</dt>
<dd><p>Optionality operator. Accepts the empty word and anything from the
regular expression <b class="variable">A</b>.</p></dd>
<dt>{* A}</dt>
<dd><p>Kleene closure. Accepts the empty word and any finite concatenation of
words accepted by the regular expression <b class="variable">A</b>.</p></dd>
<dt>{+ A}</dt>
<dd><p>Positive Kleene closure. Accepts any finite concatenation of words
accepted by the regular expression <b class="variable">A</b>, but not the empty word.</p></dd>
<dt>{! A}</dt>
<dd><p>Complement operator. Accepts any word not accepted by the regular
expression <b class="variable">A</b>. Note that the complement depends on the set of
symbol the result should run over. See the discussion of the argument
<i class="arg">over</i> before.</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::grammar::fa::op::toRegexp</b> <i class="arg">fa</i></a></dt>
<dd><p>This command generates and returns a regular expression which accepts
the same language as the finite automaton <i class="arg">fa</i>. The regular
expression is in the format as described above, for
<b class="cmd">::grammar::fa::op::fromRegex</b>.</p></dd>
<dt><a name="17"><b class="cmd">::grammar::fa::op::toRegexp2</b> <i class="arg">fa</i></a></dt>
<dd><p>This command has the same functionality as <b class="cmd">::grammar::fa::op::toRegexp</b>,
but uses a different algorithm to simplify the generated regular expressions.</p></dd>
<dt><a name="18"><b class="cmd">::grammar::fa::op::toTclRegexp</b> <i class="arg">regexp</i> <i class="arg">symdict</i></a></dt>
<dd><p>This command generates and returns a regular expression in Tcl syntax for the
regular expression <i class="arg">regexp</i>, if that is possible. <i class="arg">regexp</i> is in the
same format as expected by <b class="cmd">::grammar::fa::op::fromRegex</b>.</p>
<p>The command will fail and throw an error if <i class="arg">regexp</i> contains
complementation and intersection operations.</p>
<p>The argument <i class="arg">symdict</i> is a dictionary mapping symbol names to
pairs of <i class="term">syntactic type</i> and Tcl-regexp. If a symbol
occurring in the <i class="arg">regexp</i> is not listed in this dictionary then
single-character symbols are considered to designate themselves
whereas multiple-character symbols are considered to be a character
class name.</p></dd>
<dt><a name="19"><b class="cmd">::grammar::fa::op::simplifyRegexp</b> <i class="arg">regexp</i></a></dt>
<dd><p>This command simplifies a regular expression by applying the following
algorithm first to the main expression and then recursively to all
sub-expressions:</p>
<ol class="doctools_enumerated">
<li><p>Convert the expression into a finite automaton.</p></li>
<li><p>Minimize the automaton.</p></li>
<li><p>Convert the automaton back to a regular expression.</p></li>
<li><p>Choose the shorter of original expression and expression from
the previous step.</p></li>
</ol></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_fa</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#automaton">automaton</a>, <a href="../../../../index.html#finite_automaton">finite automaton</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#regular_grammar">regular grammar</a>, <a href="../../../../index.html#regular_languages">regular languages</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/gasm.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
|
<div class='fossil-doc' data-title='grammar::me::cpu::gasm - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me::cpu::gasm(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me::cpu::gasm - ME assembler</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">DEFINITIONS</a></li>
<li class="doctools_section"><a href="#section3">API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">grammar::me::cpu::gasm <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::me::cpu::gasm::begin</b> <i class="arg">g</i> <i class="arg">n</i> <span class="opt">?<i class="arg">mode</i>?</span> <span class="opt">?<i class="arg">note</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::grammar::me::cpu::gasm::done</b> <b class="const">--></b> <i class="arg">t</i></a></li>
<li><a href="#3"><b class="cmd">::grammar::me::cpu::gasm::state</b></a></li>
<li><a href="#4"><b class="cmd">::grammar::me::cpu::gasm::state!</b> <i class="arg">s</i></a></li>
<li><a href="#5"><b class="cmd">::grammar::me::cpu::gasm::lift</b> <i class="arg">t</i> <i class="arg">dst</i> <b class="const">=</b> <i class="arg">src</i></a></li>
<li><a href="#6"><b class="cmd">::grammar::me::cpu::gasm::Inline</b> <i class="arg">t</i> <i class="arg">node</i> <i class="arg">label</i></a></li>
<li><a href="#7"><b class="cmd">::grammar::me::cpu::gasm::Cmd</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#8"><b class="cmd">::grammar::me::cpu::gasm::Bra</b></a></li>
<li><a href="#9"><b class="cmd">::grammar::me::cpu::gasm::Nop</b> <i class="arg">text</i></a></li>
<li><a href="#10"><b class="cmd">::grammar::me::cpu::gasm::Note</b> <i class="arg">text</i></a></li>
<li><a href="#11"><b class="cmd">::grammar::me::cpu::gasm::Jmp</b> <i class="arg">label</i></a></li>
<li><a href="#12"><b class="cmd">::grammar::me::cpu::gasm::Exit</b></a></li>
<li><a href="#13"><b class="cmd">::grammar::me::cpu::gasm::Who</b> <i class="arg">label</i></a></li>
<li><a href="#14"><b class="cmd">::grammar::me::cpu::gasm::/Label</b> <i class="arg">name</i></a></li>
<li><a href="#15"><b class="cmd">::grammar::me::cpu::gasm::/Clear</b></a></li>
<li><a href="#16"><b class="cmd">::grammar::me::cpu::gasm::/Ok</b></a></li>
<li><a href="#17"><b class="cmd">::grammar::me::cpu::gasm::/Fail</b></a></li>
<li><a href="#18"><b class="cmd">::grammar::me::cpu::gasm::/At</b> <i class="arg">name</i></a></li>
<li><a href="#19"><b class="cmd">::grammar::me::cpu::gasm::/CloseLoop</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a simple in-memory assembler. Its origin is that
of a support package for use by packages converting PEG and other
grammars into a corresponding matcher based on the ME virtual machine,
like <b class="package">page::compiler::peg::mecpu</b>. Despite that it is actually
mostly agnostic regarding the instructions, users can choose any
instruction set they like.</p>
<p>The program under construction is held in a graph structure (See
package <b class="package"><a href="../struct/graph.html">struct::graph</a></b>) during assembly and subsequent
manipulation, with instructions represented by nodes, and the flow of
execution between instructions explicitly encoded in the arcs between
them.</p>
<p>In this model jumps are not encoded explicitly, they are implicit in
the arcs. The generation of explicit jumps is left to any code
converting the graph structure into a more conventional
representation. The same goes for branches. They are implicitly
encoded by all instructions which have two outgoing arcs, whereas all
other instructions have only one outgoing arc. Their conditonality is
handled by tagging their outgoing arcs with information about the
conditions under which they are taken.</p>
<p>While the graph the assembler operates on is supplied from the
outside, i.e. external, it does manage some internal state, namely:</p>
<ol class="doctools_enumerated">
<li><p>The handle of the graph node most assembler operations will
work on, the <i class="term">anchor</i>.</p></li>
<li><p>A mapping from arbitrary strings to instructions. I.e. it is
possible to <i class="term">label</i> an instruction during assembly, and later
recall that instruction by its label.</p></li>
<li><p>The condition code to use when creating arcs between
instructions, which is one of <b class="const">always</b>, <b class="const">ok</b>, and
<b class="const">fail</b>.</p></li>
<li><p>The current operation mode, one of <b class="const">halt</b>,
<b class="const">okfail</b>, and <b class="const">!okfail</b>.</p></li>
<li><p>The name of a node in a tree. This, and the operation mode
above are the parts most heavily influenced by the needs of a grammar
compiler, as they assume some basic program structures (selected
through the operation mode), and intertwine the graph with a tree,
like the AST for the grammar to be compiled.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">DEFINITIONS</a></h2>
<p>As the graph the assembler is operating on, and the tree it is
intertwined with, are supplied to the assembler from the outside it is
necessary to specify the API expected from them, and to describe the
structures expected and/or generated by the assembler in either.</p>
<ol class="doctools_enumerated">
<li><p>Any graph object command used by the assembler has to provide
the API as specified in the documentation for the package
<b class="package"><a href="../struct/graph.html">struct::graph</a></b>.</p></li>
<li><p>Any tree object command used by the assembler has to provide
the API as specified in the documentation for the package
<b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>.</p></li>
<li><p>Any instruction (node) generated by the assembler in a graph
will have at least two, and at most three attributes:</p>
<dl class="doctools_definitions">
<dt><b class="const">instruction</b></dt>
<dd><p>The value of this attribute is the name of
the instruction. The only names currently defined by the assembler are
the three pseudo-instructions</p>
<dl class="doctools_definitions">
<dt><b class="const">NOP</b></dt>
<dd><p>This instruction does nothing. Useful for fixed
framework nodes, unchanging jump destinations, and the like. No
arguments.</p></dd>
<dt><b class="const">C</b></dt>
<dd><p>A .NOP to allow the insertion of arbitrary comments
into the instruction stream, i.e. a comment node. One argument, the
text of the comment.</p></dd>
<dt><b class="const">BRA</b></dt>
<dd><p>A .NOP serving as explicitly coded conditional
branch. No arguments.</p></dd>
</dl>
<p>However we reserve the space of all instructions whose names begin
with a "." (dot) for future use by the assembler.</p></dd>
<dt><b class="const">arguments</b></dt>
<dd><p>The value of this attribute is a list of
strings, the arguments of the instruction. The contents are dependent
on the actual instruction and the assembler doesn't know or care about
them. This means for example that it has no builtin knowledge about
what instruction need which arguments and thus doesn't perform any
type of checking.</p></dd>
<dt><b class="const">expr</b></dt>
<dd><p>This attribute is optional. When it is present its
value is the name of a node in the tree intertwined with the graph.</p></dd>
</dl>
</li>
<li><p>Any arc between two instructions will have one attribute:</p>
<dl class="doctools_definitions">
<dt><b class="const">condition</b></dt>
<dd><p>The value of this attribute determines under which
condition execution will take this arc. It is one of <b class="const">always</b>,
<b class="const">ok</b>, and <b class="const">fail</b>. The first condition is used for all arcs
which are the single outgoing arc of an instruction. The other two are
used for the two outgoing arcs of an instruction which implicitly
encode a branch.</p></dd>
</dl>
</li>
<li><p>A tree node given to the assembler for cross-referencing will
be written to and given the following attributes, some fixed, some
dependent on the operation mode. All values will be references to
nodes in the instruction graph. Some of the instruction will expect
some or specific sets of these attributes.</p>
<dl class="doctools_definitions">
<dt><b class="const">gas::entry</b></dt>
<dd><p>Always written.</p></dd>
<dt><b class="const">gas::exit</b></dt>
<dd><p>Written for all modes but <b class="const">okfail</b>.</p></dd>
<dt><b class="const">gas::exit::ok</b></dt>
<dd><p>Written for mode <b class="const">okfail</b>.</p></dd>
<dt><b class="const">gas::exit::fail</b></dt>
<dd><p>Written for mode <b class="const">okfail</b>.</p></dd>
</dl>
</li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::me::cpu::gasm::begin</b> <i class="arg">g</i> <i class="arg">n</i> <span class="opt">?<i class="arg">mode</i>?</span> <span class="opt">?<i class="arg">note</i>?</span></a></dt>
<dd><p>This command starts the assembly of an instruction sequence, and
(re)initializes the state of the assembler. After completion of the
instruction sequence use <b class="cmd">::grammar::me::cpu::gasm::done</b> to
finalize the assembler.</p>
<p>It will operate on the graph <i class="arg">g</i> in the specified <i class="arg">mode</i>
(Default is <b class="const">okfail</b>). As part of the initialization it will
always create a standard .NOP instruction and label it "entry". The
creation of the remaining standard instructions is
<i class="arg">mode</i>-dependent:</p>
<dl class="doctools_definitions">
<dt><b class="const">halt</b></dt>
<dd><p>An "icf_halt" instruction labeled "exit/return".</p></dd>
<dt><b class="const">!okfail</b></dt>
<dd><p>An "icf_ntreturn" instruction labeled "exit/return".</p></dd>
<dt><b class="const">okfail</b></dt>
<dd><p>Two .NOP instructions labeled "exit/ok" and
"exit/fail" respectively.</p></dd>
</dl>
<p>The <i class="arg">note</i>, if specified (default is not), is given to the "entry" .NOP instruction.</p>
<p>The node reference <i class="arg">n</i> is simply stored for use by
<b class="cmd">::grammar::me::cpu::gasm::done</b>. It has to refer to a node in the
tree <i class="arg">t</i> argument of that command.</p>
<p>After the initialization is done the "entry" instruction will be the
<i class="term">anchor</i>, and the condition code will be set to <b class="const">always</b>.</p>
<p>The command returns the empy string as its result.</p></dd>
<dt><a name="2"><b class="cmd">::grammar::me::cpu::gasm::done</b> <b class="const">--></b> <i class="arg">t</i></a></dt>
<dd><p>This command finalizes the creation of an instruction sequence and
then clears the state of the assembler.
<em>NOTE</em> that this <em>does not</em> delete any of the created
instructions. They can be made available to future begin/done cycles.
Further assembly will be possible only after reinitialization of the
system via <b class="cmd">::grammar::me::cpu::gasm::begin</b>.</p>
<p>Before the state is cleared selected references to selected
instructions will be written to attributes of the node <i class="arg">n</i> in the
tree <i class="arg">t</i>.
Which instructions are saved is <i class="arg">mode</i>-dependent. Both <i class="arg">mode</i>
and the destination node <i class="arg">n</i> were specified during invokation of
<b class="cmd">::grammar::me::cpu::gasm::begin</b>.</p>
<p>Independent of the mode a reference to the instruction labeled "entry"
will be saved to the attribute <b class="const">gas::entry</b> of <i class="arg">n</i>. The
reference to the node <i class="arg">n</i> will further be saved into the attribute
"expr" of the "entry" instruction. Beyond that</p>
<dl class="doctools_definitions">
<dt><b class="const">halt</b></dt>
<dd><p>A reference to the instruction labeled
"exit/return" will be saved to the attribute <b class="const">gas::exit</b> of
<i class="arg">n</i>.</p></dd>
<dt><b class="const">okfail</b></dt>
<dd><p>See <b class="const">halt</b>.</p></dd>
<dt><b class="const">!okfail</b></dt>
<dd><p>Reference to the two instructions labeled
"exit/ok" and "exit/fail" will be saved to the attributes
<b class="const">gas::exit::ok</b> and <b class="const">gas::exit::fail</b> of <i class="arg">n</i>
respectively.</p></dd>
</dl>
<p>The command returns the empy string as its result.</p></dd>
<dt><a name="3"><b class="cmd">::grammar::me::cpu::gasm::state</b></a></dt>
<dd><p>This command returns the current state of the assembler. Its format is
not documented and considered to be internal to the package.</p></dd>
<dt><a name="4"><b class="cmd">::grammar::me::cpu::gasm::state!</b> <i class="arg">s</i></a></dt>
<dd><p>This command takes a serialized assembler state <i class="arg">s</i> as returned by
<b class="cmd">::grammar::me::cpu::gasm::state</b> and makes it the current state
of the assembler.</p>
<p><em>Note</em> that this may overwrite label definitions, however all
non-conflicting label definitions in the state before are not touched
and merged with <i class="arg">s</i>.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="5"><b class="cmd">::grammar::me::cpu::gasm::lift</b> <i class="arg">t</i> <i class="arg">dst</i> <b class="const">=</b> <i class="arg">src</i></a></dt>
<dd><p>This command operates on the tree <i class="arg">t</i>. It copies the contents of
the attributes <b class="const">gas::entry</b>, <b class="const">gas::exit::ok</b> and
<b class="const">gas::exit::fail</b> from the node <i class="arg">src</i> to the node <i class="arg">dst</i>.
It returns the empty string as its result.</p></dd>
<dt><a name="6"><b class="cmd">::grammar::me::cpu::gasm::Inline</b> <i class="arg">t</i> <i class="arg">node</i> <i class="arg">label</i></a></dt>
<dd><p>This command links an instruction sequence created by an earlier
begin/done pair into the current instruction sequence.</p>
<p>To this end it</p>
<ol class="doctools_enumerated">
<li><p>reads the instruction references from the attributes
<b class="const">gas::entry</b>, <b class="const">gas::exit::ok</b>, and <b class="const">gas::exit::fail</b>
from the node <i class="arg">n</i> of the tree <i class="arg">t</i> and makes them available to
assembler und the labels <i class="arg">label</i>/entry, <i class="arg">label</i>/exit::ok, and
<i class="arg">label</i>/exit::fail respectively.</p></li>
<li><p>Creates an arc from the <i class="term">anchor</i> to the node labeled
<i class="arg">label</i>/entry, and tags it with the current condition code.</p></li>
<li><p>Makes the node labeled <i class="arg">label</i>/exit/ok the new <i class="term">anchor</i>.</p></li>
</ol>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="7"><b class="cmd">::grammar::me::cpu::gasm::Cmd</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This is the basic command to add instructions to the graph.
It creates a new instruction of type <i class="arg">cmd</i> with the given
arguments <i class="arg">arg</i>...
If the <i class="term">anchor</i> was defined it will also create an arc from the
<i class="term">anchor</i> to the new instruction using the current condition code.
After the call the new instruction will be the <i class="term">anchor</i> and the
current condition code will be set to <b class="const">always</b>.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="8"><b class="cmd">::grammar::me::cpu::gasm::Bra</b></a></dt>
<dd><p>This is a convenience command to create a .BRA pseudo-instruction. It
uses <b class="cmd">::grammar::me::cpu::gasm::Cmd</b> to actually create the
instruction and inherits its behaviour.</p></dd>
<dt><a name="9"><b class="cmd">::grammar::me::cpu::gasm::Nop</b> <i class="arg">text</i></a></dt>
<dd><p>This is a convenience command to create a .NOP pseudo-instruction. It
uses <b class="cmd">::grammar::me::cpu::gasm::Cmd</b> to actually create the
instruction and inherits its behaviour.
The <i class="arg">text</i> will be saved as the first and only argument of the new
instruction.</p></dd>
<dt><a name="10"><b class="cmd">::grammar::me::cpu::gasm::Note</b> <i class="arg">text</i></a></dt>
<dd><p>This is a convenience command to create a .C pseudo-instruction,
i.e. a comment. It uses <b class="cmd">::grammar::me::cpu::gasm::Cmd</b> to
actually create the instruction and inherits its behaviour.
The <i class="arg">text</i> will be saved as the first and only argument of the new
instruction.</p></dd>
<dt><a name="11"><b class="cmd">::grammar::me::cpu::gasm::Jmp</b> <i class="arg">label</i></a></dt>
<dd><p>This command creates an arc from the <i class="term">anchor</i> to the instruction
labeled with <i class="arg">label</i>, and tags with the the current condition
code.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="12"><b class="cmd">::grammar::me::cpu::gasm::Exit</b></a></dt>
<dd><p>This command creates an arc from the <i class="term">anchor</i> to one of the exit
instructions, based on the operation mode (see
<b class="cmd">::grammar::me::cpu::gasm::begin</b>), and tags it with current
condition code.</p>
<p>For mode <b class="const">okfail</b> it links to the instruction labeled either
"exit/ok" or "exit/fail", depending on the current condition code, and
tagging it with the current condition code
For the other two modes it links to the instruction labeled
"exit/return", tagging it condition code <b class="const">always</b>, independent
the current condition code.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="13"><b class="cmd">::grammar::me::cpu::gasm::Who</b> <i class="arg">label</i></a></dt>
<dd><p>This command returns a reference to the instruction labeled with
<i class="arg">label</i>.</p></dd>
<dt><a name="14"><b class="cmd">::grammar::me::cpu::gasm::/Label</b> <i class="arg">name</i></a></dt>
<dd><p>This command labels the <i class="term">anchor</i> with <i class="arg">name</i>.
<em>Note</em> that an instruction can have more than one label.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="15"><b class="cmd">::grammar::me::cpu::gasm::/Clear</b></a></dt>
<dd><p>This command clears the <i class="term">anchor</i>, leaving it undefined, and
further resets the current condition code to <b class="const">always</b>.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="16"><b class="cmd">::grammar::me::cpu::gasm::/Ok</b></a></dt>
<dd><p>This command sets the current condition code to <b class="const">ok</b>.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="17"><b class="cmd">::grammar::me::cpu::gasm::/Fail</b></a></dt>
<dd><p>This command sets the current condition code to <b class="const">fail</b>.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="18"><b class="cmd">::grammar::me::cpu::gasm::/At</b> <i class="arg">name</i></a></dt>
<dd><p>This command sets the <i class="term">anchor</i> to the instruction labeled with
<i class="arg">name</i>, and further resets the current condition code to
<b class="const">always</b>.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="19"><b class="cmd">::grammar::me::cpu::gasm::/CloseLoop</b></a></dt>
<dd><p>This command marks the <i class="term">anchor</i> as the last instruction in a loop
body, by creating the attribute <b class="const">LOOP</b>.</p>
<p>The command returns the empty string as its result.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#assembler">assembler</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#graph">graph</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#tree">tree</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_ast.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
<div class='fossil-doc' data-title='grammar::me_ast - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me_ast(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me_ast - Various representations of ASTs</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">AST VALUES</a></li>
<li class="doctools_section"><a href="#section3">AST OBJECTS</a></li>
<li class="doctools_section"><a href="#section4">EXTENDED AST OBJECTS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document specifies various representations for the
<i class="term"><a href="../../../../index.html#abstract_syntax_tree">abstract syntax tree</a></i>s (short <i class="term"><a href="../../../../index.html#ast">AST</a></i>) generated by
instances of ME virtual machines, independent of variant.
Please go and read the document <b class="syscmd"><a href="me_intro.html">grammar::me_intro</a></b> first if
you do not know what a ME virtual machine is.</p>
<p>ASTs and all the representations we specify distinguish between two
types of nodes, namely:</p>
<dl class="doctools_definitions">
<dt>Terminal</dt>
<dd><p>Terminal nodes refer to the terminal symbols found in the token
stream. They are always leaf nodes. I.e. terminal nodes never have
children.</p></dd>
<dt>Nonterminal</dt>
<dd><p>Nonterminal nodes represent a nonterminal symbol of the grammar used
during parsing. They can occur as leaf and inner nodes of the
tree.</p></dd>
</dl>
<p>Both types of nodes carry basic range information telling a user which
parts of the input are covered by the node by providing the location
of the first and last tokens found within the range. Locations are
provided as non-negative integer offsets from the beginning of the
token stream, with the first token found in the stream located at
offset 0 (zero).</p>
<p>The root of an AS tree can be either a terminal or nonterminal node.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">AST VALUES</a></h2>
<p>This representation of ASTs is a Tcl list. The main list represents
the root node of the tree, with the representations of the children
nested within.</p>
<p>Each node is represented by a single Tcl list containing three or more
elements. The first element is either the empty string or the name of
a nonterminal symbol (which is never the empty string). The second and
third elements are then the locations of the first and last tokens.
Any additional elements after the third are then the representations
of the children, with the leftmost child first, i.e. as the fourth
element of the list representing the node.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AST OBJECTS</a></h2>
<p>In this representation an AST is represented by a Tcl object command
whose API is compatible to the tree objects provided by the package
<b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>. I.e it has to support at least all of the
methods described by that package, and may support more.</p>
<p>Because of this the remainder of the specifications is written using
the terms of <b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>.</p>
<p>Each node of the AST directly maps to a node in the tree object. All
data beyond the child nodes, i.e. node type and input locations, are
stored in attributes of the node in the tree object. They are:</p>
<dl class="doctools_definitions">
<dt>type</dt>
<dd><p>The type of the AST node. The recognized values are <b class="const">terminal</b>
and <b class="const">nonterminal</b>.</p></dd>
<dt>range</dt>
<dd><p>The locations of the first and last token of the terminal data in the
input covered by the node. This is a list containing two locations.</p></dd>
<dt>detail</dt>
<dd><p>This attribute is present only for nonterminal nodes. It contains the
name of the nonterminal symbol stored in the node.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXTENDED AST OBJECTS</a></h2>
<p>Extended AST objects are like AST objects, with additional
information.</p>
<dl class="doctools_definitions">
<dt>detail</dt>
<dd><p>This attribute is now present at all nodes. Its contents are unchanged
for nonterminal nodes. For terminal nodes it contains a list
describing all tokens from the input which are covered by the node.</p>
<p>Each element of the list contains the token name, the associated
lexeme attribute, line number, and column index, in this order.</p></dd>
<dt>range_lc</dt>
<dd><p>This new attribute is defined for all nodes, and contains the
locations from attribute <i class="term">range</i> translated into line number and
column index. Lines are counted from 1, columns are counted from 0.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ast">AST</a>, <a href="../../../../index.html#abstract_syntax_tree">abstract syntax tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_cpu.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
|
<div class='fossil-doc' data-title='grammar::me::cpu - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me::cpu(n) 0.2 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me::cpu - Virtual machine implementation II for parsing token streams</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">CLASS API</a></li>
<li class="doctools_subsection"><a href="#subsection2">OBJECT API</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">grammar::me::cpu <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::me::cpu</b> <i class="arg">meName</i> <i class="arg">matchcode</i></a></li>
<li><a href="#2"><b class="cmd">meName</b> <b class="method">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">meName</i> <b class="method">lc</b> <i class="arg">location</i></a></li>
<li><a href="#4"><i class="arg">meName</i> <b class="method">tok</b> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#5"><i class="arg">meName</i> <b class="method">pc</b> <i class="arg">state</i></a></li>
<li><a href="#6"><i class="arg">meName</i> <b class="method">iseof</b> <i class="arg">state</i></a></li>
<li><a href="#7"><i class="arg">meName</i> <b class="method">at</b> <i class="arg">state</i></a></li>
<li><a href="#8"><i class="arg">meName</i> <b class="method">cc</b> <i class="arg">state</i></a></li>
<li><a href="#9"><i class="arg">meName</i> <b class="method">sv</b></a></li>
<li><a href="#10"><i class="arg">meName</i> <b class="method">ok</b></a></li>
<li><a href="#11"><i class="arg">meName</i> <b class="method">error</b></a></li>
<li><a href="#12"><i class="arg">meName</i> <b class="method">lstk</b> <i class="arg">state</i></a></li>
<li><a href="#13"><i class="arg">meName</i> <b class="method">astk</b> <i class="arg">state</i></a></li>
<li><a href="#14"><i class="arg">meName</i> <b class="method">mstk</b> <i class="arg">state</i></a></li>
<li><a href="#15"><i class="arg">meName</i> <b class="method">estk</b> <i class="arg">state</i></a></li>
<li><a href="#16"><i class="arg">meName</i> <b class="method">rstk</b> <i class="arg">state</i></a></li>
<li><a href="#17"><i class="arg">meName</i> <b class="method">nc</b> <i class="arg">state</i></a></li>
<li><a href="#18"><i class="arg">meName</i> <b class="method">ast</b></a></li>
<li><a href="#19"><i class="arg">meName</i> <b class="method">halted</b></a></li>
<li><a href="#20"><i class="arg">meName</i> <b class="method">code</b></a></li>
<li><a href="#21"><i class="arg">meName</i> <b class="method">eof</b></a></li>
<li><a href="#22"><i class="arg">meName</i> <b class="method">put</b> <i class="arg">tok</i> <i class="arg">lex</i> <i class="arg">line</i> <i class="arg">col</i></a></li>
<li><a href="#23"><i class="arg">meName</i> <b class="method">putstring</b> <i class="arg">string</i> <i class="arg">lvar</i> <i class="arg">cvar</i></a></li>
<li><a href="#24"><i class="arg">meName</i> <b class="method">run</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#25"><i class="arg">meName</i> <b class="method">pull</b> <i class="arg">nextcmd</i></a></li>
<li><a href="#26"><i class="arg">meName</i> <b class="method">reset</b></a></li>
<li><a href="#27"><i class="arg">meName</i> <b class="method">destroy</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an implementation of the ME virtual machine.
Please go and read the document <b class="syscmd"><a href="me_intro.html">grammar::me_intro</a></b> first if
you do not know what a ME virtual machine is.</p>
<p>This implementation provides an object-based API and the machines are
not truly tied to Tcl. A C implementation of the same API is quite
possible.</p>
<p>Internally the package actually uses the value-based machine
manipulation commands as provided by the package
<b class="package"><a href="me_cpucore.html">grammar::me::cpu::core</a></b> to perform its duties.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">CLASS API</a></h3>
<p>The package directly provides only a single command for the
construction of ME virtual machines.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::me::cpu</b> <i class="arg">meName</i> <i class="arg">matchcode</i></a></dt>
<dd><p>The command creates a new ME machine object with an associated global
Tcl command whose name is <i class="arg">meName</i>. This command may be used to
invoke various operations on the machine.
It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">meName</b> <b class="method">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>The argument <i class="arg">matchcode</i> contains the match instructions the
machine has to execute while parsing the input stream. Please read
section <b class="sectref">MATCH CODE REPRESENTATION</b> of the
documentation for the package <b class="package"><a href="me_cpucore.html">grammar::me::cpu::core</a></b> for
the specification of the structure of this value.</p>
<p>The <i class="arg">tokmap</i> argument taken by the implementation provided by the
package <b class="package"><a href="me_tcl.html">grammar::me::tcl</a></b> is here hidden inside of the match
instructions and therefore not needed.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">OBJECT API</a></h3>
<p>All ME virtual machine objects created by the class command specified
in section <span class="sectref"><a href="#subsection1">CLASS API</a></span> support the methods listed below.</p>
<p>The machines provided by this package provide methods for operation in
both push- and pull-styles. Push-style means that tokens are pushed
into the machine state when they arrive, triggering further execution
until they are consumed. In other words, this allows the machine to be
suspended and resumed at will and an arbitrary number of times, the
quasi-parallel operation of several machines, and the operation as
part of the event loop.</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">meName</i> <b class="method">lc</b> <i class="arg">location</i></a></dt>
<dd><p>This method converts the location of a token given as offset in the
input stream into the associated line number and column index. The
result of the command is a 2-element list containing the two values,
in the order mentioned in the previous sentence.
This allows higher levels to convert the location information found in
the error status and the generated AST into more human readable data.</p>
<p><em>Note</em> that the command is not able to convert locations which
have not been reached by the machine yet. In other words, if the
machine has read 7 tokens the command is able to convert the offsets
<b class="const">0</b> to <b class="const">6</b>, but nothing beyond that. This also shows that
it is not possible to convert offsets which refer to locations before
the beginning of the stream.</p></dd>
<dt><a name="4"><i class="arg">meName</i> <b class="method">tok</b> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>This method returns a Tcl list containing the part of the input stream
between the locations <i class="arg">from</i> and <i class="arg">to</i> (both inclusive). If
<i class="arg">to</i> is not specified it will default to the value of <i class="arg">from</i>.
If <i class="arg">from</i> is not specified either the whole input stream is returned.</p>
<p>Each element of the returned list is a list of four elements, the
token, its associated lexeme, line number, and column index, in this
order.
This command places the same restrictions on its location arguments as
the method <b class="method">lc</b>.</p></dd>
<dt><a name="5"><i class="arg">meName</i> <b class="method">pc</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current value of the stored program counter.</p></dd>
<dt><a name="6"><i class="arg">meName</i> <b class="method">iseof</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current value of the stored eof flag.</p></dd>
<dt><a name="7"><i class="arg">meName</i> <b class="method">at</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current location in the input stream.</p></dd>
<dt><a name="8"><i class="arg">meName</i> <b class="method">cc</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current token.</p></dd>
<dt><a name="9"><i class="arg">meName</i> <b class="method">sv</b></a></dt>
<dd><p>This command returns the current semantic value <i class="term">SV</i> stored in
the machine. This is an abstract syntax tree as specified in the
document <b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section <b class="sectref">AST VALUES</b>.</p></dd>
<dt><a name="10"><i class="arg">meName</i> <b class="method">ok</b></a></dt>
<dd><p>This method returns the current match status <i class="term">OK</i>.</p></dd>
<dt><a name="11"><i class="arg">meName</i> <b class="method">error</b></a></dt>
<dd><p>This method returns the current error status <i class="term">ER</i>.</p></dd>
<dt><a name="12"><i class="arg">meName</i> <b class="method">lstk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the location stack.</p></dd>
<dt><a name="13"><i class="arg">meName</i> <b class="method">astk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the AST stack.</p></dd>
<dt><a name="14"><i class="arg">meName</i> <b class="method">mstk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the AST marker stack.</p></dd>
<dt><a name="15"><i class="arg">meName</i> <b class="method">estk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the error stack.</p></dd>
<dt><a name="16"><i class="arg">meName</i> <b class="method">rstk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the subroutine return stack.</p></dd>
<dt><a name="17"><i class="arg">meName</i> <b class="method">nc</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the nonterminal match cache as a dictionary.</p></dd>
<dt><a name="18"><i class="arg">meName</i> <b class="method">ast</b></a></dt>
<dd><p>This method returns the current top entry of the AST stack <i class="term">AS</i>.
This is an abstract syntax tree as specified in the document
<b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section <b class="sectref">AST VALUES</b>.</p></dd>
<dt><a name="19"><i class="arg">meName</i> <b class="method">halted</b></a></dt>
<dd><p>This method returns a boolean value telling the caller whether the
engine has halted execution or not. Halt means that no further
matching is possible, and the information retrieved via the other
method is final. Attempts to <b class="method">run</b> the engine will be ignored,
until a <b class="method">reset</b> is made.</p></dd>
<dt><a name="20"><i class="arg">meName</i> <b class="method">code</b></a></dt>
<dd><p>This method returns the <i class="arg">code</i> information used to construct the
object. In other words, the match program executed by the machine.</p></dd>
<dt><a name="21"><i class="arg">meName</i> <b class="method">eof</b></a></dt>
<dd><p>This method adds an end of file marker to the end of the input stream.
This signals the machine that the current contents of the input queue
are the final parts of the input and nothing will come after. Attempts
to put more characters into the queue will fail.</p></dd>
<dt><a name="22"><i class="arg">meName</i> <b class="method">put</b> <i class="arg">tok</i> <i class="arg">lex</i> <i class="arg">line</i> <i class="arg">col</i></a></dt>
<dd><p>This method adds the token <i class="arg">tok</i> to the end of the input stream,
with associated lexeme data <i class="arg">lex</i> and <i class="arg">line</i>/<i class="arg">col</i>umn
information.</p></dd>
<dt><a name="23"><i class="arg">meName</i> <b class="method">putstring</b> <i class="arg">string</i> <i class="arg">lvar</i> <i class="arg">cvar</i></a></dt>
<dd><p>This method adds each individual character in the <i class="arg">string</i> as a
token to the end of the input stream, from first to last. The lexemes
will be empty and the line/col information is computed based on the
characters encountered and the data in the variables <i class="arg">lvar</i> and
<i class="arg">cvar</i>.</p></dd>
<dt><a name="24"><i class="arg">meName</i> <b class="method">run</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>This methods causes the engine to execute match instructions until
either</p>
<ul class="doctools_itemized">
<li><p><i class="arg">n</i> instructions have been executed, or</p></li>
<li><p>a halt instruction was executed, or</p></li>
<li><p>the input queue is empty and the code is asking for more tokens to
process.</p></li>
</ul>
<p>If no limit <i class="arg">n</i> was set only the last two conditions are checked
for.</p></dd>
<dt><a name="25"><i class="arg">meName</i> <b class="method">pull</b> <i class="arg">nextcmd</i></a></dt>
<dd><p>This method implements pull-style operation of the machine. It causes
it to execute match instructions until either a halt instruction is
reached, or the command prefix
<i class="arg">nextcmd</i> ceases to deliver more tokens.</p>
<p>The command prefix <i class="arg">nextcmd</i> represents the input stream of
characters and is invoked by the machine whenever the a new character
from the stream is required. The instruction for handling this is
<i class="term">ict_advance</i>.
The callback has to return either the empty list, or a list of 4
elements containing the token, its lexeme attribute, and its location
as line number and column index, in this order.
The empty list is the signal that the end of the input stream has been
reached. The lexeme attribute is stored in the terminal cache, but
otherwise not used by the machine.</p>
<p>The end of the input stream for this method does not imply that method
<b class="method">eof</b> is called for the machine as a whole. By avoiding this
and still asking for an explicit call of the method it is possible to
mix push- and pull-style operation during the lifetime of the machine.</p></dd>
<dt><a name="26"><i class="arg">meName</i> <b class="method">reset</b></a></dt>
<dd><p>This method resets the machine to its initial state, discarding any
state it may have.</p></dd>
<dt><a name="27"><i class="arg">meName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method deletes the object and releases all resurces it claimed.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005-2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
<div class='fossil-doc' data-title='grammar::me::cpu::core - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me::cpu::core(n) 0.2 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me::cpu::core - ME virtual machine state manipulation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">MATCH PROGRAM REPRESENTATION</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">CPU STATE</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">grammar::me::cpu::core <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">disasm</b> <i class="arg">asm</i></a></li>
<li><a href="#2"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">asm</b> <i class="arg">asm</i></a></li>
<li><a href="#3"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">new</b> <i class="arg">asm</i></a></li>
<li><a href="#4"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">lc</b> <i class="arg">state</i> <i class="arg">location</i></a></li>
<li><a href="#5"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">tok</b> <i class="arg">state</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#6"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">pc</b> <i class="arg">state</i></a></li>
<li><a href="#7"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">iseof</b> <i class="arg">state</i></a></li>
<li><a href="#8"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">at</b> <i class="arg">state</i></a></li>
<li><a href="#9"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">cc</b> <i class="arg">state</i></a></li>
<li><a href="#10"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">sv</b> <i class="arg">state</i></a></li>
<li><a href="#11"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">ok</b> <i class="arg">state</i></a></li>
<li><a href="#12"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">error</b> <i class="arg">state</i></a></li>
<li><a href="#13"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">lstk</b> <i class="arg">state</i></a></li>
<li><a href="#14"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">astk</b> <i class="arg">state</i></a></li>
<li><a href="#15"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">mstk</b> <i class="arg">state</i></a></li>
<li><a href="#16"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">estk</b> <i class="arg">state</i></a></li>
<li><a href="#17"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">rstk</b> <i class="arg">state</i></a></li>
<li><a href="#18"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">nc</b> <i class="arg">state</i></a></li>
<li><a href="#19"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">ast</b> <i class="arg">state</i></a></li>
<li><a href="#20"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">halted</b> <i class="arg">state</i></a></li>
<li><a href="#21"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">code</b> <i class="arg">state</i></a></li>
<li><a href="#22"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">eof</b> <i class="arg">statevar</i></a></li>
<li><a href="#23"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">put</b> <i class="arg">statevar</i> <i class="arg">tok</i> <i class="arg">lex</i> <i class="arg">line</i> <i class="arg">col</i></a></li>
<li><a href="#24"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">run</b> <i class="arg">statevar</i> <span class="opt">?<i class="arg">n</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an implementation of the ME virtual machine.
Please go and read the document <b class="syscmd"><a href="me_intro.html">grammar::me_intro</a></b> first if
you do not know what a ME virtual machine is.</p>
<p>This implementation represents each ME virtual machine as a Tcl value
and provides commands to manipulate and query such values to show the
effects of executing instructions, adding tokens, retrieving state,
etc.</p>
<p>The values fully follow the paradigm of Tcl that every value is a
string and while also allowing C implementations for a proper
Tcl_ObjType to keep all the important data in native data structures.
Because of the latter it is recommended to access the state values
<em>only</em> through the commands of this package to ensure that
internal representation is not shimmered away.</p>
<p>The actual structure used by all state values is described in section
<span class="sectref"><a href="#section3">CPU STATE</a></span>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package directly provides only a single command, and all the
functionality is made available through its methods.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">disasm</b> <i class="arg">asm</i></a></dt>
<dd><p>This method returns a list containing a disassembly of the match
instructions in <i class="arg">asm</i>. The format of <i class="arg">asm</i> is specified in the
section <span class="sectref"><a href="#subsection1">MATCH PROGRAM REPRESENTATION</a></span>.</p>
<p>Each element of the result contains instruction label, instruction
name, and the instruction arguments, in this order. The label can be
the empty string. Jump destinations are shown as labels, strings and
tokens unencoded. Token names are prefixed with their numeric id, if,
and only if a tokmap is defined. The two components are separated by a
colon.</p></dd>
<dt><a name="2"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">asm</b> <i class="arg">asm</i></a></dt>
<dd><p>This method returns code in the format as specified in section
<span class="sectref"><a href="#subsection1">MATCH PROGRAM REPRESENTATION</a></span> generated from ME assembly
code <i class="arg">asm</i>, which is in the format as returned by the method
<b class="method">disasm</b>.</p></dd>
<dt><a name="3"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">new</b> <i class="arg">asm</i></a></dt>
<dd><p>This method creates state value for a ME virtual machine in its
initial state and returns it as its result.</p>
<p>The argument <i class="arg">matchcode</i> contains a Tcl representation of the
match instructions the machine has to execute while parsing the input
stream. Its format is specified in the section
<span class="sectref"><a href="#subsection1">MATCH PROGRAM REPRESENTATION</a></span>.</p>
<p>The <i class="arg">tokmap</i> argument taken by the implementation provided by the
package <b class="package"><a href="me_tcl.html">grammar::me::tcl</a></b> is here hidden inside of the match
instructions and therefore not needed.</p></dd>
<dt><a name="4"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">lc</b> <i class="arg">state</i> <i class="arg">location</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and uses it
to convert a location in the input stream (as offset) into a line
number and column index. The result of the method is a 2-element list
containing the two pieces in the order mentioned in the previous
sentence.</p>
<p><em>Note</em> that the method cannot convert locations which the machine
has not yet read from the input stream. In other words, if the machine
has read 7 characters so far it is possible to convert the offsets
<b class="const">0</b> to <b class="const">6</b>, but nothing beyond that. This also shows that
it is not possible to convert offsets which refer to locations before
the beginning of the stream.</p>
<p>This utility allows higher levels to convert the location offsets
found in the error status and the AST into more human readable data.</p></dd>
<dt><a name="5"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">tok</b> <i class="arg">state</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
a Tcl list containing the part of the input stream between the
locations <i class="arg">from</i> and <i class="arg">to</i> (both inclusive). If <i class="arg">to</i> is not
specified it will default to the value of <i class="arg">from</i>. If <i class="arg">from</i> is
not specified either the whole input stream is returned.</p>
<p>This method places the same restrictions on its location arguments as
the method <b class="method">lc</b>.</p></dd>
<dt><a name="6"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">pc</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current value of the stored program counter.</p></dd>
<dt><a name="7"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">iseof</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current value of the stored eof flag.</p></dd>
<dt><a name="8"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">at</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current location in the input stream.</p></dd>
<dt><a name="9"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">cc</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current token.</p></dd>
<dt><a name="10"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">sv</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current semantic value stored in it.
This is an abstract syntax tree as specified in the document
<b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section <b class="sectref">AST VALUES</b>.</p></dd>
<dt><a name="11"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">ok</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the match status stored in it.</p></dd>
<dt><a name="12"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">error</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current error status stored in it.</p></dd>
<dt><a name="13"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">lstk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the location stack.</p></dd>
<dt><a name="14"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">astk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the AST stack.</p></dd>
<dt><a name="15"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">mstk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the AST marker stack.</p></dd>
<dt><a name="16"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">estk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the error stack.</p></dd>
<dt><a name="17"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">rstk</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the subroutine return stack.</p></dd>
<dt><a name="18"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">nc</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the nonterminal match cache as a dictionary.</p></dd>
<dt><a name="19"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">ast</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the abstract syntax tree currently at the top of the AST stack stored
in it.
This is an abstract syntax tree as specified in the document
<b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section <b class="sectref">AST VALUES</b>.</p></dd>
<dt><a name="20"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">halted</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the current halt status stored in it, i.e. if the machine has stopped
or not.</p></dd>
<dt><a name="21"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">code</b> <i class="arg">state</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine and returns
the code stored in it, i.e. the instructions executed by the machine.</p></dd>
<dt><a name="22"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">eof</b> <i class="arg">statevar</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine as stored in
the variable named by <i class="arg">statevar</i> and modifies it so that the eof
flag inside is set. This signals to the machine that whatever token
are in the input queue are the last to be processed. There will be no
more.</p></dd>
<dt><a name="23"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">put</b> <i class="arg">statevar</i> <i class="arg">tok</i> <i class="arg">lex</i> <i class="arg">line</i> <i class="arg">col</i></a></dt>
<dd><p>This method takes the state value of a ME virtual machine as stored in
the variable named by <i class="arg">statevar</i> and modifies it so that the token
<i class="arg">tok</i> is added to the end of the input queue, with associated
lexeme data <i class="arg">lex</i> and <i class="arg">line</i>/<i class="arg">col</i>umn information.</p>
<p>The operation will fail with an error if the eof flag of the machine
has been set through the method <b class="method">eof</b>.</p></dd>
<dt><a name="24"><b class="cmd">::grammar::me::cpu::core</b> <b class="method">run</b> <i class="arg">statevar</i> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>This method takes the state value of a ME virtual machine as stored in
the variable named by <i class="arg">statevar</i>, executes a number of
instructions and stores the state resulting from their modifications
back into the variable.</p>
<p>The execution loop will run until either</p>
<ul class="doctools_itemized">
<li><p><i class="arg">n</i> instructions have been executed, or</p></li>
<li><p>a halt instruction was executed, or</p></li>
<li><p>the input queue is empty and the code is asking for more tokens to
process.</p></li>
</ul>
<p>If no limit <i class="arg">n</i> was set only the last two conditions are checked
for.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">MATCH PROGRAM REPRESENTATION</a></h3>
<p>A match program is represented by nested Tcl list. The first element,
<i class="term">asm</i>, is a list of integer numbers, the instructions to execute,
and their arguments. The second element, <i class="term"><a href="../../../../index.html#pool">pool</a></i>, is a list of
strings, referenced by the instructions, for error messages, token
names, etc. The third element, <i class="term">tokmap</i>, provides ordering
information for the tokens, mapping their names to their numerical
rank. This element can be empty, forcing lexicographic comparison when
matching ranges.</p>
<p>All ME instructions are encoded as integer numbers, with the mapping
given below. A number of the instructions, those which handle error
messages, have been given an additional argument to supply that
message explicitly instead of having it constructed from token names,
etc. This allows the machine state to store only the message ids
instead of the full strings.</p>
<p>Jump destination arguments are absolute indices into the <i class="term">asm</i>
element, refering to the instruction to jump to. Any string arguments
are absolute indices into the <i class="term"><a href="../../../../index.html#pool">pool</a></i> element. Tokens, characters,
messages, and token (actually character) classes to match are coded as
references into the <i class="term"><a href="../../../../index.html#pool">pool</a></i> as well.</p>
<ol class="doctools_enumerated">
<li><p>"<b class="cmd">ict_advance</b> <i class="arg">message</i>"</p></li>
<li><p>"<b class="cmd">ict_match_token</b> <i class="arg">tok</i> <i class="arg">message</i>"</p></li>
<li><p>"<b class="cmd">ict_match_tokrange</b> <i class="arg">tokbegin</i> <i class="arg">tokend</i> <i class="arg">message</i>"</p></li>
<li><p>"<b class="cmd">ict_match_tokclass</b> <i class="arg">code</i> <i class="arg">message</i>"</p></li>
<li><p>"<b class="cmd">inc_restore</b> <i class="arg">branchlabel</i> <i class="arg">nt</i>"</p></li>
<li><p>"<b class="cmd">inc_save</b> <i class="arg">nt</i>"</p></li>
<li><p>"<b class="cmd">icf_ntcall</b> <i class="arg">branchlabel</i>"</p></li>
<li><p>"<b class="cmd">icf_ntreturn</b>"</p></li>
<li><p>"<b class="cmd">iok_ok</b>"</p></li>
<li><p>"<b class="cmd">iok_fail</b>"</p></li>
<li><p>"<b class="cmd">iok_negate</b>"</p></li>
<li><p>"<b class="cmd">icf_jalways</b> <i class="arg">branchlabel</i>"</p></li>
<li><p>"<b class="cmd">icf_jok</b> <i class="arg">branchlabel</i>"</p></li>
<li><p>"<b class="cmd">icf_jfail</b> <i class="arg">branchlabel</i>"</p></li>
<li><p>"<b class="cmd">icf_halt</b>"</p></li>
<li><p>"<b class="cmd">icl_push</b>"</p></li>
<li><p>"<b class="cmd">icl_rewind</b>"</p></li>
<li><p>"<b class="cmd">icl_pop</b>"</p></li>
<li><p>"<b class="cmd">ier_push</b>"</p></li>
<li><p>"<b class="cmd">ier_clear</b>"</p></li>
<li><p>"<b class="cmd">ier_nonterminal</b> <i class="arg">message</i>"</p></li>
<li><p>"<b class="cmd">ier_merge</b>"</p></li>
<li><p>"<b class="cmd">isv_clear</b>"</p></li>
<li><p>"<b class="cmd">isv_terminal</b>"</p></li>
<li><p>"<b class="cmd">isv_nonterminal_leaf</b> <i class="arg">nt</i>"</p></li>
<li><p>"<b class="cmd">isv_nonterminal_range</b> <i class="arg">nt</i>"</p></li>
<li><p>"<b class="cmd">isv_nonterminal_reduce</b> <i class="arg">nt</i>"</p></li>
<li><p>"<b class="cmd">ias_push</b>"</p></li>
<li><p>"<b class="cmd">ias_mark</b>"</p></li>
<li><p>"<b class="cmd">ias_mrewind</b>"</p></li>
<li><p>"<b class="cmd">ias_mpop</b>"</p></li>
</ol>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CPU STATE</a></h2>
<p>A state value is a list containing the following elements, in the order listed below:</p>
<ol class="doctools_enumerated">
<li><p><i class="term">code</i>: Match instructions, see <span class="sectref"><a href="#subsection1">MATCH PROGRAM REPRESENTATION</a></span>.</p></li>
<li><p><i class="term">pc</i>: Program counter, <i class="term">int</i>.</p></li>
<li><p><i class="term">halt</i>: Halt flag, <i class="term">boolean</i>.</p></li>
<li><p><i class="term">eof</i>: Eof flag, <i class="term">boolean</i></p></li>
<li><p><i class="term">tc</i>: Terminal cache, and input queue. Structure see below.</p></li>
<li><p><i class="term">cl</i>: Current location, <i class="term">int</i>.</p></li>
<li><p><i class="term">ct</i>: Current token, <i class="term"><a href="../../../../index.html#string">string</a></i>.</p></li>
<li><p><i class="term">ok</i>: Match status, <i class="term">boolean</i>.</p></li>
<li><p><i class="term">sv</i>: Semantic value, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">er</i>: Error status, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">ls</i>: Location stack, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">as</i>: AST stack, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">ms</i>: AST marker stack, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">es</i>: Error stack, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">rs</i>: Return stack, <i class="term"><a href="../../../../index.html#list">list</a></i>.</p></li>
<li><p><i class="term">nc</i>: Nonterminal cache, <i class="term">dictionary</i>.</p></li>
</ol>
<p><i class="term">tc</i>, the input queue of tokens waiting for processing and the
terminal cache containing the tokens already processing are one
unified data structure simply holding all tokens and their
information, with the current location separating that which has been
processed from that which is waiting.
Each element of the queue/cache is a list containing the token, its
lexeme information, line number, and column index, in this order.</p>
<p>All stacks have their top element aat the end, i.e. pushing an item is
equivalent to appending to the list representing the stack, and
popping it removes the last element.</p>
<p><i class="term">er</i>, the error status is either empty or a list of two elements,
a location in the input, and a list of messages, encoded as references
into the <i class="term"><a href="../../../../index.html#pool">pool</a></i> element of the <i class="term">code</i>.</p>
<p><i class="term">nc</i>, the nonterminal cache is keyed by nonterminal name and
location, each value a four-element list containing current location,
match status, semantic value, and error status, in this order.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005-2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<div class='fossil-doc' data-title='grammar::me_intro - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me_intro(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me_intro - Introduction to virtual machines for parsing token streams</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is an introduction to and overview of the basic
facilities for the parsing and/or matching of <i class="term">token</i>
streams. One possibility often used for the token domain are
characters.</p>
<p>The packages themselves all provide variants of one
<i class="term"><a href="../../../../index.html#virtual_machine">virtual machine</a></i>, called a <i class="term">match engine</i> (short
<i class="term">ME</i>), which has all the facilities needed for the matching and
parsing of a stream, and which are either controlled directly, or are
customized with a match program. The virtual machine is basically a
pushdown automaton, with additional elements for backtracking and/or
handling of semantic data and construction of abstract syntax trees
(<i class="term"><a href="../../../../index.html#ast">AST</a></i>).</p>
<p>Because of the high degree of similarity in the actual implementations
of the aforementioned virtual machine and the data structures they
receive and generate these common parts are specified in a separate
document which will be referenced by the documentation for packages
actually implementing it.</p>
<p>The relevant documents are:</p>
<dl class="doctools_definitions">
<dt><b class="package"><a href="me_vm.html">grammar::me_vm</a></b></dt>
<dd><p>Virtual machine specification.</p></dd>
<dt><b class="package"><a href="me_ast.html">grammar::me_ast</a></b></dt>
<dd><p>Specification of various representations used for abstract syntax
trees.</p></dd>
<dt><b class="package"><a href="me_util.html">grammar::me::util</a></b></dt>
<dd><p>Utility commands.</p></dd>
<dt><b class="package"><a href="me_tcl.html">grammar::me::tcl</a></b></dt>
<dd><p>Singleton ME virtual machine implementation tied to Tcl for control
flow and stacks. Hardwired for pull operation. Uninteruptible during
processing.</p></dd>
<dt><b class="package"><a href="me_cpu.html">grammar::me::cpu</a></b></dt>
<dd><p>Object-based ME virtual machine implementation with explicit control
flow, and stacks, using bytecodes. Suspend/Resumable. Push/pull
operation.</p></dd>
<dt><b class="package"><a href="me_cpucore.html">grammar::me::cpu::core</a></b></dt>
<dd><p>Core functionality for state manipulation and stepping used in the
bytecode based implementation of ME virtual machines.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cfg">CFG</a>, <a href="../../../../index.html#cfl">CFL</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tpdl">TPDL</a>, <a href="../../../../index.html#context_free_grammar">context-free grammar</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_tcl.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
|
<div class='fossil-doc' data-title='grammar::me::tcl - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me::tcl(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me::tcl - Virtual machine implementation I for parsing token streams</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">MACHINE STATE</a></li>
<li class="doctools_section"><a href="#section4">MACHINE INSTRUCTIONS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">grammar::me::tcl <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::me::tcl</b> <b class="method">cmd</b> <i class="arg">...</i></a></li>
<li><a href="#2"><b class="cmd">::grammar::me::tcl</b> <b class="method">init</b> <i class="arg">nextcmd</i> <span class="opt">?<i class="arg">tokmap</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::grammar::me::tcl</b> <b class="method">lc</b> <i class="arg">location</i></a></li>
<li><a href="#4"><b class="cmd">::grammar::me::tcl</b> <b class="method">tok</b> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::grammar::me::tcl</b> <b class="method">tokens</b></a></li>
<li><a href="#6"><b class="cmd">::grammar::me::tcl</b> <b class="method">sv</b></a></li>
<li><a href="#7"><b class="cmd">::grammar::me::tcl</b> <b class="method">ast</b></a></li>
<li><a href="#8"><b class="cmd">::grammar::me::tcl</b> <b class="method">astall</b></a></li>
<li><a href="#9"><b class="cmd">::grammar::me::tcl</b> <b class="method">ctok</b></a></li>
<li><a href="#10"><b class="cmd">::grammar::me::tcl</b> <b class="method">nc</b></a></li>
<li><a href="#11"><b class="cmd">::grammar::me::tcl</b> <b class="method">next</b></a></li>
<li><a href="#12"><b class="cmd">::grammar::me::tcl</b> <b class="method">ord</b></a></li>
<li><a href="#13"><b class="cmd">::grammar::me::tcl::ict_advance</b> <i class="arg">message</i></a></li>
<li><a href="#14"><b class="cmd">::grammar::me::tcl::ict_match_token</b> <i class="arg">tok</i> <i class="arg">message</i></a></li>
<li><a href="#15"><b class="cmd">::grammar::me::tcl::ict_match_tokrange</b> <i class="arg">tokbegin</i> <i class="arg">tokend</i> <i class="arg">message</i></a></li>
<li><a href="#16"><b class="cmd">::grammar::me::tcl::ict_match_tokclass</b> <i class="arg">code</i> <i class="arg">message</i></a></li>
<li><a href="#17"><b class="cmd">::grammar::me::tcl::inc_restore</b> <i class="arg">nt</i></a></li>
<li><a href="#18"><b class="cmd">::grammar::me::tcl::inc_save</b> <i class="arg">nt</i> <i class="arg">startlocation</i></a></li>
<li><a href="#19"><b class="cmd">::grammar::me::tcl::iok_ok</b></a></li>
<li><a href="#20"><b class="cmd">::grammar::me::tcl::iok_fail</b></a></li>
<li><a href="#21"><b class="cmd">::grammar::me::tcl::iok_negate</b></a></li>
<li><a href="#22"><b class="cmd">::grammar::me::tcl::icl_get</b></a></li>
<li><a href="#23"><b class="cmd">::grammar::me::tcl::icl_rewind</b> <i class="arg">oldlocation</i></a></li>
<li><a href="#24"><b class="cmd">::grammar::me::tcl::ier_get</b></a></li>
<li><a href="#25"><b class="cmd">::grammar::me::tcl::ier_clear</b></a></li>
<li><a href="#26"><b class="cmd">::grammar::me::tcl::ier_nonterminal</b> <i class="arg">message</i> <i class="arg">location</i></a></li>
<li><a href="#27"><b class="cmd">::grammar::me::tcl::ier_merge</b> <i class="arg">olderror</i></a></li>
<li><a href="#28"><b class="cmd">::grammar::me::tcl::isv_clear</b></a></li>
<li><a href="#29"><b class="cmd">::grammar::me::tcl::isv_terminal</b></a></li>
<li><a href="#30"><b class="cmd">::grammar::me::tcl::isv_nonterminal_leaf</b> <i class="arg">nt</i> <i class="arg">startlocation</i></a></li>
<li><a href="#31"><b class="cmd">::grammar::me::tcl::isv_nonterminal_range</b> <i class="arg">nt</i> <i class="arg">startlocation</i></a></li>
<li><a href="#32"><b class="cmd">::grammar::me::tcl::isv_nonterminal_reduce</b> <i class="arg">nt</i> <i class="arg">startlocation</i> <span class="opt">?<i class="arg">marker</i>?</span></a></li>
<li><a href="#33"><b class="cmd">::grammar::me::tcl::ias_push</b></a></li>
<li><a href="#34"><b class="cmd">::grammar::me::tcl::ias_mark</b></a></li>
<li><a href="#35"><b class="cmd">::grammar::me::tcl::ias_pop2mark</b> <i class="arg">marker</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an implementation of the ME virtual machine.
Please go and read the document <b class="syscmd"><a href="me_intro.html">grammar::me_intro</a></b> first if
you do not know what a ME virtual machine is.</p>
<p>This implementation is tied very strongly to Tcl. All the stacks in
the machine state are handled through the Tcl stack, all control flow
is handled by Tcl commands, and the remaining machine instructions are
directly mapped to Tcl commands. Especially the matching of
nonterminal symbols is handled by Tcl procedures as well, essentially
extending the machine implementation with custom instructions.</p>
<p>Further on the implementation handles only a single machine which is
uninteruptible during execution and hardwired for pull operation. I.e.
it explicitly requests each new token through a callback, pulling them
into its state.</p>
<p>A related package is <b class="package"><a href="../grammar_peg/peg_interp.html">grammar::peg::interp</a></b> which provides a
generic interpreter / parser for parsing expression grammars (PEGs),
implemented on top of this implementation of the ME virtual machine.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The commands documented in this section do not implement any of the
instructions of the ME virtual machine. They provide the facilities
for the initialization of the machine and the retrieval of important
information.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::me::tcl</b> <b class="method">cmd</b> <i class="arg">...</i></a></dt>
<dd><p>This is an ensemble command providing access to the commands listed in
this section. See the methods themselves for detailed specifications.</p></dd>
<dt><a name="2"><b class="cmd">::grammar::me::tcl</b> <b class="method">init</b> <i class="arg">nextcmd</i> <span class="opt">?<i class="arg">tokmap</i>?</span></a></dt>
<dd><p>This command (re)initializes the machine. It returns the empty
string. This command has to be invoked before any other command of
this package.</p>
<p>The command prefix <i class="arg">nextcmd</i> represents the input stream of
characters and is invoked by the machine whenever the a new character
from the stream is required. The instruction for handling this is
<i class="term">ict_advance</i>.
The callback has to return either the empty list, or a list of 4
elements containing the token, its lexeme attribute, and its location
as line number and column index, in this order.
The empty list is the signal that the end of the input stream has been
reached. The lexeme attribute is stored in the terminal cache, but
otherwise not used by the machine.</p>
<p>The optional dictionary <i class="arg">tokmap</i> maps from tokens to integer
numbers. If present the numbers impose an order on the tokens, which
is subsequently used by <i class="term">ict_match_tokrange</i> to determine if a
token is in the specified range or not. If no token map is specified
the lexicographic order of th token names will be used instead. This
choice is especially asensible when using characters as tokens.</p></dd>
<dt><a name="3"><b class="cmd">::grammar::me::tcl</b> <b class="method">lc</b> <i class="arg">location</i></a></dt>
<dd><p>This command converts the location of a token given as offset in the
input stream into the associated line number and column index. The
result of the command is a 2-element list containing the two values,
in the order mentioned in the previous sentence.
This allows higher levels to convert the location information found in
the error status and the generated AST into more human readable data.</p>
<p><em>Note</em> that the command is not able to convert locations which
have not been reached by the machine yet. In other words, if the
machine has read 7 tokens the command is able to convert the offsets
<b class="const">0</b> to <b class="const">6</b>, but nothing beyond that. This also shows that
it is not possible to convert offsets which refer to locations before
the beginning of the stream.</p>
<p>After a call of <b class="method">init</b> the state used for the conversion is
cleared, making further conversions impossible until the machine has
read tokens again.</p></dd>
<dt><a name="4"><b class="cmd">::grammar::me::tcl</b> <b class="method">tok</b> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span></a></dt>
<dd><p>This command returns a Tcl list containing the part of the input
stream between the locations <i class="arg">from</i> and <i class="arg">to</i> (both
inclusive). If <i class="arg">to</i> is not specified it will default to the value
of <i class="arg">from</i>.</p>
<p>Each element of the returned list is a list of four elements, the
token, its associated lexeme, line number, and column index, in this
order.
In other words, each element has the same structure as the result of
the <i class="arg">nextcmd</i> callback given to <b class="cmd">::grammar::me::tcl::init</b></p>
<p>This command places the same restrictions on its location arguments as
<b class="cmd">::grammar::me::tcl::lc</b>.</p></dd>
<dt><a name="5"><b class="cmd">::grammar::me::tcl</b> <b class="method">tokens</b></a></dt>
<dd><p>This command returns the number of tokens currently known to the ME
virtual machine.</p></dd>
<dt><a name="6"><b class="cmd">::grammar::me::tcl</b> <b class="method">sv</b></a></dt>
<dd><p>This command returns the current semantic value <i class="term">SV</i> stored in
the machine. This is an abstract syntax tree as specified in the
document <b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section <b class="sectref">AST VALUES</b>.</p></dd>
<dt><a name="7"><b class="cmd">::grammar::me::tcl</b> <b class="method">ast</b></a></dt>
<dd><p>This method returns the abstract syntax tree currently at the top of
the AST stack of the ME virtual machine. This is an abstract syntax
tree as specified in the document <b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section
<b class="sectref">AST VALUES</b>.</p></dd>
<dt><a name="8"><b class="cmd">::grammar::me::tcl</b> <b class="method">astall</b></a></dt>
<dd><p>This method returns the whole stack of abstract syntax trees currently
known to the ME virtual machine. Each element of the returned list is
an abstract syntax tree as specified in the document
<b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>, section <b class="sectref">AST VALUES</b>.
The top of the stack resides at the end of the list.</p></dd>
<dt><a name="9"><b class="cmd">::grammar::me::tcl</b> <b class="method">ctok</b></a></dt>
<dd><p>This method returns the current token considered by the ME virtual
machine.</p></dd>
<dt><a name="10"><b class="cmd">::grammar::me::tcl</b> <b class="method">nc</b></a></dt>
<dd><p>This method returns the contents of the nonterminal cache as a
dictionary mapping from "<b class="variable">symbol</b>,<b class="variable">location</b>" to match
information.</p></dd>
<dt><a name="11"><b class="cmd">::grammar::me::tcl</b> <b class="method">next</b></a></dt>
<dd><p>This method returns the next token callback as specified during
initialization of the ME virtual machine.</p></dd>
<dt><a name="12"><b class="cmd">::grammar::me::tcl</b> <b class="method">ord</b></a></dt>
<dd><p>This method returns a dictionary containing the <i class="arg">tokmap</i> specified
during initialization of the ME virtual machine.
<b class="variable"><b class="cmd">::grammar::me::tcl::ok</b></b>
This variable contains the current match status <i class="term">OK</i>. It is
provided as variable instead of a command because that makes access to
this information faster, and the speed of access is considered very
important here as this information is used constantly to determine the
control flow.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">MACHINE STATE</a></h2>
<p>Please go and read the document <b class="syscmd"><a href="me_vm.html">grammar::me_vm</a></b> first for a
specification of the basic ME virtual machine and its state.</p>
<p>This implementation manages the state described in that document,
except for the stacks minus the AST stack. In other words, location
stack, error stack, return stack, and ast marker stack are implicitly
managed through standard Tcl scoping, i.e. Tcl variables in
procedures, outside of this implementation.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">MACHINE INSTRUCTIONS</a></h2>
<p>Please go and read the document <b class="syscmd"><a href="me_vm.html">grammar::me_vm</a></b> first for a
specification of the basic ME virtual machine and its instruction set.</p>
<p>This implementation maps all instructions to Tcl commands in the
namespace "::grammar::me::tcl", except for the stack related commands,
nonterminal symbols and control flow.
Here we simply list the commands and explain the differences to the
specified instructions, if there are any. For their semantics see the
aforementioned specification. The machine commands are <em>not</em>
reachable through the ensemble command <b class="cmd">::grammar::me::tcl</b>.</p>
<dl class="doctools_definitions">
<dt><a name="13"><b class="cmd">::grammar::me::tcl::ict_advance</b> <i class="arg">message</i></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="14"><b class="cmd">::grammar::me::tcl::ict_match_token</b> <i class="arg">tok</i> <i class="arg">message</i></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="15"><b class="cmd">::grammar::me::tcl::ict_match_tokrange</b> <i class="arg">tokbegin</i> <i class="arg">tokend</i> <i class="arg">message</i></a></dt>
<dd><p>If, and only if a token map was specified during initialization then
the arguments are the numeric representations of the smallest and
largest tokens in the range. Otherwise they are the relevant tokens
themselves and lexicographic comparison is used.</p></dd>
<dt><a name="16"><b class="cmd">::grammar::me::tcl::ict_match_tokclass</b> <i class="arg">code</i> <i class="arg">message</i></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="17"><b class="cmd">::grammar::me::tcl::inc_restore</b> <i class="arg">nt</i></a></dt>
<dd><p>Instead of taking a branchlabel the command returns a boolean value.
The result will be <b class="const">true</b> if and only if cached information was
found. The caller has to perform the appropriate branching.</p></dd>
<dt><a name="18"><b class="cmd">::grammar::me::tcl::inc_save</b> <i class="arg">nt</i> <i class="arg">startlocation</i></a></dt>
<dd><p>The command takes the start location as additional argument, as it is
managed on the Tcl stack, and not in the machine state.</p></dd>
<dt><b class="cmd">icf_ntcall</b> <i class="arg">branchlabel</i></dt>
<dd></dd>
<dt><b class="cmd">icf_ntreturn</b></dt>
<dd><p>These two instructions are not mapped to commands. They are control
flow instructions and handled in Tcl.</p></dd>
<dt><a name="19"><b class="cmd">::grammar::me::tcl::iok_ok</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="20"><b class="cmd">::grammar::me::tcl::iok_fail</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="21"><b class="cmd">::grammar::me::tcl::iok_negate</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><b class="cmd">icf_jalways</b> <i class="arg">branchlabel</i></dt>
<dd></dd>
<dt><b class="cmd">icf_jok</b> <i class="arg">branchlabel</i></dt>
<dd></dd>
<dt><b class="cmd">icf_jfail</b> <i class="arg">branchlabel</i></dt>
<dd></dd>
<dt><b class="cmd">icf_halt</b></dt>
<dd><p>These four instructions are not mapped to commands. They are control
flow instructions and handled in Tcl.</p></dd>
<dt><a name="22"><b class="cmd">::grammar::me::tcl::icl_get</b></a></dt>
<dd><p>This command returns the current location <i class="term">CL</i> in the input.
It replaces <i class="term">icl_push</i>.</p></dd>
<dt><a name="23"><b class="cmd">::grammar::me::tcl::icl_rewind</b> <i class="arg">oldlocation</i></a></dt>
<dd><p>The command takes the location as argument as it comes from the
Tcl stack, not the machine state.</p></dd>
<dt><b class="cmd">icl_pop</b></dt>
<dd><p>Not mapped, the stacks are not managed by the package.</p></dd>
<dt><a name="24"><b class="cmd">::grammar::me::tcl::ier_get</b></a></dt>
<dd><p>This command returns the current error state <i class="term">ER</i>.
It replaces <i class="term">ier_push</i>.</p></dd>
<dt><a name="25"><b class="cmd">::grammar::me::tcl::ier_clear</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="26"><b class="cmd">::grammar::me::tcl::ier_nonterminal</b> <i class="arg">message</i> <i class="arg">location</i></a></dt>
<dd><p>The command takes the location as argument as it comes from the
Tcl stack, not the machine state.</p></dd>
<dt><a name="27"><b class="cmd">::grammar::me::tcl::ier_merge</b> <i class="arg">olderror</i></a></dt>
<dd><p>The command takes the second error state to merge as argument as it
comes from the Tcl stack, not the machine state.</p></dd>
<dt><a name="28"><b class="cmd">::grammar::me::tcl::isv_clear</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="29"><b class="cmd">::grammar::me::tcl::isv_terminal</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="30"><b class="cmd">::grammar::me::tcl::isv_nonterminal_leaf</b> <i class="arg">nt</i> <i class="arg">startlocation</i></a></dt>
<dd><p>The command takes the start location as argument as it comes from the
Tcl stack, not the machine state.</p></dd>
<dt><a name="31"><b class="cmd">::grammar::me::tcl::isv_nonterminal_range</b> <i class="arg">nt</i> <i class="arg">startlocation</i></a></dt>
<dd><p>The command takes the start location as argument as it comes from the
Tcl stack, not the machine state.</p></dd>
<dt><a name="32"><b class="cmd">::grammar::me::tcl::isv_nonterminal_reduce</b> <i class="arg">nt</i> <i class="arg">startlocation</i> <span class="opt">?<i class="arg">marker</i>?</span></a></dt>
<dd><p>The command takes start location and marker as argument as it comes
from the Tcl stack, not the machine state.</p></dd>
<dt><a name="33"><b class="cmd">::grammar::me::tcl::ias_push</b></a></dt>
<dd><p>No changes.</p></dd>
<dt><a name="34"><b class="cmd">::grammar::me::tcl::ias_mark</b></a></dt>
<dd><p>This command returns a marker for the current state of the AST stack
<i class="term">AS</i>. The marker stack is not managed by the machine.</p></dd>
<dt><a name="35"><b class="cmd">::grammar::me::tcl::ias_pop2mark</b> <i class="arg">marker</i></a></dt>
<dd><p>The command takes the marker as argument as it comes from the
Tcl stack, not the machine state. It replaces <i class="term">ias_mpop</i>.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_util.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<div class='fossil-doc' data-title='grammar::me::util - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me::util(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me::util - AST utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">grammar::me::util <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::me::util::ast2tree</b> <i class="arg">ast</i> <i class="arg">tree</i> <span class="opt">?<i class="arg">root</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::grammar::me::util::ast2etree</b> <i class="arg">ast</i> <i class="arg">mcmd</i> <i class="arg">tree</i> <span class="opt">?<i class="arg">root</i>?</span></a></li>
<li><a href="#3"><b class="cmd">mcmd</b> <b class="method">lc</b> <i class="arg">location</i></a></li>
<li><a href="#4"><b class="cmd">mcmd</b> <b class="method">tok</b> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::grammar::me::util::tree2ast</b> <i class="arg">tree</i> <span class="opt">?<i class="arg">root</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a number of utility command for the conversion
between the various representations of abstract syntax trees as
specified in the document <b class="syscmd"><a href="me_ast.html">grammar::me_ast</a></b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::me::util::ast2tree</b> <i class="arg">ast</i> <i class="arg">tree</i> <span class="opt">?<i class="arg">root</i>?</span></a></dt>
<dd><p>This command converts an <i class="arg">ast</i> from value to object
representation. All nodes in the <i class="arg">ast</i> will be converted into
nodes of this <i class="arg">tree</i>, with the root of the AST a child of the node
<i class="arg">root</i>. If this node is not explicitly specified the root of the
tree is used. Existing content of tree is not touched, i.e. neither
removed nor changed, with the exception of the specified root node,
which will gain a new child.</p></dd>
<dt><a name="2"><b class="cmd">::grammar::me::util::ast2etree</b> <i class="arg">ast</i> <i class="arg">mcmd</i> <i class="arg">tree</i> <span class="opt">?<i class="arg">root</i>?</span></a></dt>
<dd><p>This command is like <b class="cmd">::grammar::me::util::ast2tree</b>, except that
the result is in the extended object representation of the input AST.
The source of the extended information is the command prefix
<i class="arg">mcmd</i>.
It has to understand two methods, <b class="method">lc</b>, and <b class="method">tok</b>, with
the semantics specified below.</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">mcmd</b> <b class="method">lc</b> <i class="arg">location</i></a></dt>
<dd><p>Takes the location of a token given as offset in the input stream and
return a 2-element list containing the associated line number and
column index, in this order.</p></dd>
<dt><a name="4"><b class="cmd">mcmd</b> <b class="method">tok</b> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span></a></dt>
<dd><p>Takes one or two locations <i class="arg">from</i> and <i class="arg">to</i> as offset in the
input stream and returns a Tcl list containing the specified part of
the input stream. Both location are inclusive. If <i class="arg">to</i> is not
specified it will default to the value of <i class="arg">from</i>.</p>
<p>Each element of the returned list is a list containing the token, its
associated lexeme, the line number, and column index, in this order.</p></dd>
</dl>
<p>Both the ensemble command <b class="cmd">::grammar::me::tcl</b> provided by the
package <b class="package"><a href="me_tcl.html">grammar::me::tcl</a></b> and the objects command created by
the package <b class="package">::grammar::me::cpu</b> fit the above specification.</p></dd>
<dt><a name="5"><b class="cmd">::grammar::me::util::tree2ast</b> <i class="arg">tree</i> <span class="opt">?<i class="arg">root</i>?</span></a></dt>
<dd><p>This command converts an <i class="arg">ast</i> in (extended) object representation
into a value and returns it.
If a <i class="arg">root</i> node is specified the AST is generated from that node
downward. Otherwise the root of the tree object is used as the
starting point.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#abstract_syntax_tree">abstract syntax tree</a>, <a href="../../../../index.html#syntax_tree">syntax tree</a>, <a href="../../../../index.html#tree">tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_me/me_vm.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
|
<div class='fossil-doc' data-title='grammar::me_vm - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::me_vm(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::me_vm - Virtual machine for parsing token streams</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">MACHINE STATE</a></li>
<li class="doctools_section"><a href="#section3">MACHINE INSTRUCTIONS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">TERMINAL MATCHING</a></li>
<li class="doctools_subsection"><a href="#subsection2">NONTERMINAL MATCHING</a></li>
<li class="doctools_subsection"><a href="#subsection3">UNCONDITIONAL MATCHING</a></li>
<li class="doctools_subsection"><a href="#subsection4">CONTROL FLOW</a></li>
<li class="doctools_subsection"><a href="#subsection5">INPUT LOCATION HANDLING</a></li>
<li class="doctools_subsection"><a href="#subsection6">ERROR HANDLING</a></li>
<li class="doctools_subsection"><a href="#subsection7">SEMANTIC VALUES</a></li>
<li class="doctools_subsection"><a href="#subsection8">AST STACK HANDLING</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please go and read the document <b class="syscmd"><a href="me_intro.html">grammar::me_intro</a></b> first for
an overview of the various documents and their relations.</p>
<p>This document specifies a virtual machine for the controlled matching
and parsing of token streams, creating an
<i class="term"><a href="../../../../index.html#abstract_syntax_tree">abstract syntax tree</a></i> (short <i class="term"><a href="../../../../index.html#ast">AST</a></i>) reflecting the
structure of the input. Special machine features are the caching and
reuse of partial results, caching of the encountered input, and the
ability to backtrack in both input and AST creation.</p>
<p>These features make the specified virtual machine especially useful to
packrat parsers based on parsing expression grammars. It is however
not restricted to this type of parser. Normal LL and LR parsers can be
implemented with it as well.</p>
<p>The following sections will discuss first the abstract state kept by
ME virtual machines, and then their instruction set.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">MACHINE STATE</a></h2>
<p>A ME virtual machine manages the following state:</p>
<dl class="doctools_definitions">
<dt><i class="term">Current token</i> CT</dt>
<dd><p>The token from the input under consideration by the machine.</p>
<p>This information is used and modified by the instructions defined in
the section
<span class="sectref"><a href="#subsection1">TERMINAL MATCHING</a></span>.</p></dd>
<dt><i class="term">Current location</i> CL</dt>
<dd><p>The location of the <i class="term">current token</i> in the input stream, as
offset relative to the beginning of the stream. The first token is
considered to be at offset <b class="const">0</b>.</p>
<p>This information is implicitly used and modified by the instructions
defined in the sections
<span class="sectref"><a href="#subsection1">TERMINAL MATCHING</a></span> and
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>,
and can be directly queried and modified by the instructions defined
in section
<span class="sectref"><a href="#subsection5">INPUT LOCATION HANDLING</a></span>.</p></dd>
<dt><i class="term">Location stack</i> LS</dt>
<dd><p>In addition to the above a stack of locations, for backtracking.
Locations can put on the stack, removed from it, and removed with
setting the current location.</p>
<p>This information is implicitly used and modified by the instructions
defined in the sections
<span class="sectref"><a href="#subsection1">TERMINAL MATCHING</a></span> and
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>,
and can be directly queried and modified by the instructions defined
in section
<span class="sectref"><a href="#subsection5">INPUT LOCATION HANDLING</a></span>.</p></dd>
<dt><i class="term">Match status</i> OK</dt>
<dd><p>A boolean value, the result of the last attempt at matching input.
It is set to <b class="const">true</b> if that attempt was successful, and
<b class="const">false</b> otherwise.</p>
<p>This information is influenced by the instructions defined in the
sections
<span class="sectref"><a href="#subsection1">TERMINAL MATCHING</a></span>,
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>, and
<span class="sectref"><a href="#subsection3">UNCONDITIONAL MATCHING</a></span>.
It is queried by the instructions defined in the section
<span class="sectref"><a href="#subsection4">CONTROL FLOW</a></span>.</p></dd>
<dt><i class="term">Semantic value</i> SV</dt>
<dd><p>The semantic value associated with (generated by) the last attempt at
matching input. Contains either the empty string or a node for the
abstract syntax tree constructed from the input.</p>
<p>This information is influenced by the instructions defined in the
sections
<span class="sectref"><a href="#subsection7">SEMANTIC VALUES</a></span>, and
<span class="sectref"><a href="#subsection8">AST STACK HANDLING</a></span>.</p></dd>
<dt><i class="term">AST stack</i> AS</dt>
<dd><p>A stack of partial abstract syntax trees constructed by the machine
during matching.</p>
<p>This information is influenced by the instructions defined in the
sections
<span class="sectref"><a href="#subsection7">SEMANTIC VALUES</a></span>, and
<span class="sectref"><a href="#subsection8">AST STACK HANDLING</a></span>.</p></dd>
<dt><i class="term">AST Marker stack</i> MS</dt>
<dd><p>In addition to the above a stack of stacks, for backtracking. This is
actually a stack of markers into the AST stack, thus implicitly
snapshooting the state of the AST stack at some point in time. Markers
can be put on the stack, dropped from it, and used to roll back the
AST stack to an earlier state.</p>
<p>This information is influenced by the instructions defined in the
sections
<span class="sectref"><a href="#subsection7">SEMANTIC VALUES</a></span>, and
<span class="sectref"><a href="#subsection8">AST STACK HANDLING</a></span>.</p></dd>
<dt><i class="term">Error status</i> ER</dt>
<dd><p>Error information associated with the last attempt at matching
input. Contains either the empty string or a list of 2 elements, a
location in the input and a list of error messages associated with
it, in this order.</p>
<p><em>Note</em> that error information can be set even if the last attempt
at matching input was successful. For example the *-operator (matching
a sub-expression zero or more times) in a parsing expression grammar
is always successful, even if it encounters a problem further in the
input and has to backtrack. Such problems must not be forgotten when
continuing to match.</p>
<p>This information is queried and influenced by the instructions defined
in the sections
<span class="sectref"><a href="#subsection1">TERMINAL MATCHING</a></span>,
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>, and
<span class="sectref"><a href="#subsection6">ERROR HANDLING</a></span>.</p></dd>
<dt><i class="term">Error stack</i> ES</dt>
<dd><p>In addition to the above a stack of error information, to allow the
merging of current and older error information when performing
backtracking in choices after an unsucessful match.</p>
<p>This information is queried and influenced by the instructions defined
in the sections
<span class="sectref"><a href="#subsection1">TERMINAL MATCHING</a></span>,
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>, and
<span class="sectref"><a href="#subsection6">ERROR HANDLING</a></span>.</p></dd>
<dt><i class="term">Return stack</i> RS</dt>
<dd><p>A stack of program counter values, i.e. locations in the code
controlling the virtual machine, for the management of subroutine
calls, i.e. the matching of nonterminal symbols.</p>
<p>This information is queried and influenced by the instructions defined
in the section
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>.</p></dd>
<dt><i class="term">Nonterminal cache</i> NC</dt>
<dd><p>A cache of machine states (A 4-tuple containing a location in the
input, match status <i class="term">OK</i>, semantic value <i class="term">SV</i>, and error
status <i class="term">ER</i>) keyed by name of nonterminal symbol and location in
the input stream.</p>
<p>The key location is where machine started the attempt to match the
named nonterminal symbol, and the location in the value is where
machine ended up after the attempt completed, independent of the
success of the attempt.</p>
<p>This status is queried and influenced by the instructions defined in
the section
<span class="sectref"><a href="#subsection2">NONTERMINAL MATCHING</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">MACHINE INSTRUCTIONS</a></h2>
<p>With the machine state specified it is now possible to explain the
instruction set of ME virtual machines. They are grouped roughly by
the machine state they influence and/or query.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">TERMINAL MATCHING</a></h3>
<p>First the instructions to match tokens from the input stream, and
by extension all terminal symbols.</p>
<p>These instructions are the only ones which may retrieve a new token
from the input stream. This is a <em>may</em> and not a <em>will</em>
because the instructions will a retrieve new token if, and only if the
current location <i class="term">CL</i> is at the head of the stream.
If the machine has backtracked (see <b class="cmd">icl_rewind</b>) the instructions
will retrieve the token to compare against from the internal cache.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">ict_advance</b> <i class="arg">message</i></dt>
<dd><p>This instruction tries to advance to the next token in the input
stream, i.e. the one after the current location <i class="term">CL</i>. The
instruction will fail if, and only if the end of the input stream is
reached, i.e. if there is no next token.</p>
<p>The sucess/failure of the instruction is remembered in the match
status <i class="term">OK</i>. In the case of failure the error status <i class="term">ER</i> is
set to the current location and the message <i class="arg">message</i>.
In the case of success the error status <i class="term">ER</i> is cleared, the new
token is made the current token <i class="term">CT</i>, and the new location is
made the current location <i class="term">CL</i>.</p>
<p>The argument <i class="arg">message</i> is a reference to the string to put into
the error status <i class="term">ER</i>, if such is needed.</p></dd>
<dt><b class="cmd">ict_match_token</b> <i class="arg">tok</i> <i class="arg">message</i></dt>
<dd><p>This instruction tests the current token <i class="term">CT</i> for equality
with the argument <i class="arg">tok</i> and records the result in the match
status <i class="term">OK</i>. The instruction fails if the current token is
not equal to <i class="arg">tok</i>.</p>
<p>In case of failure the error status <i class="term">ER</i> is set to the current
location <i class="term">CL</i> and the message <i class="arg">message</i>, and the
current location <i class="term">CL</i> is moved one token backwards.
Otherwise, i.e. upon success, the error status <i class="term">ER</i> is cleared
and the current location <i class="term">CL</i> is not touched.</p></dd>
<dt><b class="cmd">ict_match_tokrange</b> <i class="arg">tokbegin</i> <i class="arg">tokend</i> <i class="arg">message</i></dt>
<dd><p>This instruction tests the current token <i class="term">CT</i> for being in
the range of tokens from <i class="arg">tokbegin</i> to <i class="arg">tokend</i>
(inclusive) and records the result in the match status <i class="term">OK</i>. The
instruction fails if the current token is not inside the range.</p>
<p>In case of failure the error status <i class="term">ER</i> is set to the current
location <i class="term">CL</i> and the message <i class="arg">message</i>, and the current location
<i class="term">CL</i> is moved one token backwards.
Otherwise, i.e. upon success, the error status <i class="term">ER</i> is cleared
and the current location <i class="term">CL</i> is not touched.</p></dd>
<dt><b class="cmd">ict_match_tokclass</b> <i class="arg">code</i> <i class="arg">message</i></dt>
<dd><p>This instruction tests the current token <i class="term">CT</i> for being a member
of the token class <i class="arg">code</i> and records the result in the match
status <i class="term">OK</i>. The instruction fails if the current token is not a
member of the specified class.</p>
<p>In case of failure the error status <i class="term">ER</i> is set to the current
location <i class="term">CL</i> and the message <i class="arg">message</i>, and the
current location <i class="term">CL</i> is moved one token backwards.
Otherwise, i.e. upon success, the error status <i class="term">ER</i> is cleared
and the current location <i class="term">CL</i> is not touched.</p>
<p>Currently the following classes are legal:</p>
<dl class="doctools_definitions">
<dt>alnum</dt>
<dd><p>A token is accepted if it is a unicode alphabetical character, or a digit.</p></dd>
<dt>alpha</dt>
<dd><p>A token is accepted if it is a unicode alphabetical character.</p></dd>
<dt>digit</dt>
<dd><p>A token is accepted if it is a unicode digit character.</p></dd>
<dt>xdigit</dt>
<dd><p>A token is accepted if it is a hexadecimal digit character.</p></dd>
<dt>punct</dt>
<dd><p>A token is accepted if it is a unicode punctuation character.</p></dd>
<dt>space</dt>
<dd><p>A token is accepted if it is a unicode space character.</p></dd>
</dl></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">NONTERMINAL MATCHING</a></h3>
<p>The instructions in this section handle the matching of nonterminal
symbols. They query the nonterminal cache <i class="term">NC</i> for saved
information, and put such information into the cache.</p>
<p>The usage of the cache is a performance aid for backtracking parsers,
allowing them to avoid an expensive rematch of complex nonterminal
symbols if they have been encountered before.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">inc_restore</b> <i class="arg">branchlabel</i> <i class="arg">nt</i></dt>
<dd><p>This instruction checks if the nonterminal cache <i class="term">NC</i> contains
information about the nonterminal symbol <i class="arg">nt</i>, at the current
location <i class="term">CL</i>. If that is the case the instruction will update
the machine state (current location <i class="term">CL</i>, match status <i class="term">OK</i>,
semantic value <i class="term">SV</i>, and error status <i class="term">ER</i>) with the found
information and continue execution at the instruction refered to by
the <i class="arg">branchlabel</i>. The new current location <i class="term">CL</i> will be the
last token matched by the nonterminal symbol, i.e. belonging to it.</p>
<p>If no information was found the instruction will continue execution at
the next instruction.</p>
<p>Together with <b class="cmd">icf_ntcall</b> it is possible to generate code for
memoized and non-memoized matching of nonterminal symbols, either as
subroutine calls, or inlined in the caller.</p></dd>
<dt><b class="cmd">inc_save</b> <i class="arg">nt</i></dt>
<dd><p>This instruction saves the current state of the machine (current
location <i class="term">CL</i>, match status <i class="term">OK</i>, semantic value <i class="term">SV</i>,
and error status <i class="term">ER</i>), to the nonterminal cache <i class="term">NC</i>. It
will also pop an entry from the location stack <i class="term">LS</i> and save it
as the start location of the match.</p>
<p>It is expected to be called at the end of matching a nonterminal
symbol, with <i class="arg">nt</i> the name of the nonterminal symbol the code was
working on. This allows the instruction <b class="cmd">inc_restore</b> to check for
and retrieve the data, should we have to match this nonterminal symbol
at the same location again, during backtracking.</p></dd>
<dt><b class="cmd">icf_ntcall</b> <i class="arg">branchlabel</i></dt>
<dd><p>This instruction invokes the code for matching the nonterminal symbol
<i class="arg">nt</i> as a subroutine. To this end it stores the current program
counter <i class="term">PC</i> on the return stack <i class="term">RS</i>, the current location
<i class="term">CL</i> on the location stack <i class="term">LS</i>, and then continues
execution at the address <i class="arg">branchlabel</i>.</p>
<p>The next matching <b class="cmd">icf_ntreturn</b> will cause the execution to
continue at the instruction coming after the call.</p></dd>
<dt><b class="cmd">icf_ntreturn</b></dt>
<dd><p>This instruction will pop an entry from the return stack <i class="term">RS</i>,
assign it to the program counter <i class="term">PC</i>, and then continue
execution at the new address.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">UNCONDITIONAL MATCHING</a></h3>
<p>The instructions in this section are the remaining match
operators. They change the match status <i class="term">OK</i> directly and
unconditionally.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">iok_ok</b></dt>
<dd><p>This instruction sets the match status <i class="term">OK</i> to <b class="const">true</b>,
indicating a successful match.</p></dd>
<dt><b class="cmd">iok_fail</b></dt>
<dd><p>This instruction sets the match status <i class="term">OK</i> to <b class="const">false</b>,
indicating a failed match.</p></dd>
<dt><b class="cmd">iok_negate</b></dt>
<dd><p>This instruction negates the match status <i class="term">OK</i>, turning a failure
into a success and vice versa.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">CONTROL FLOW</a></h3>
<p>The instructions in this section implement both conditional and
unconditional control flow. The conditional jumps query the match
status <i class="term">OK</i>.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">icf_jalways</b> <i class="arg">branchlabel</i></dt>
<dd><p>This instruction sets the program counter <i class="term">PC</i> to the address
specified by <i class="arg">branchlabel</i> and then continues execution from
there. This is an unconditional jump.</p></dd>
<dt><b class="cmd">icf_jok</b> <i class="arg">branchlabel</i></dt>
<dd><p>This instruction sets the program counter <i class="term">PC</i> to the address
specified by <i class="arg">branchlabel</i>. This happens if, and only if the match
status <i class="term">OK</i> indicates a success. Otherwise it simply continues
execution at the next instruction. This is a conditional jump.</p></dd>
<dt><b class="cmd">icf_jfail</b> <i class="arg">branchlabel</i></dt>
<dd><p>This instruction sets the program counter <i class="term">PC</i> to the address
specified by <i class="arg">branchlabel</i>. This happens if, and only if the match
status <i class="term">OK</i> indicates a failure. Otherwise it simply continues
execution at the next instruction. This is a conditional jump.</p></dd>
<dt><b class="cmd">icf_halt</b></dt>
<dd><p>This instruction halts the machine and blocks any further execution.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">INPUT LOCATION HANDLING</a></h3>
<p>The instructions in this section are for backtracking, they manipulate
the current location <i class="term">CL</i> of the machine state.
They allow a user of the machine to query and save locations in the
input, and to rewind the current location <i class="term">CL</i> to saved
locations, making them one of the components enabling the
implementation of backtracking parsers.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">icl_push</b></dt>
<dd><p>This instruction pushes a copy of the current location <i class="term">CL</i> on
the location stack <i class="term">LS</i>.</p></dd>
<dt><b class="cmd">icl_rewind</b></dt>
<dd><p>This instruction pops an entry from the location stack <i class="term">LS</i> and
then moves the current location <i class="term">CL</i> back to this point in the
input.</p></dd>
<dt><b class="cmd">icl_pop</b></dt>
<dd><p>This instruction pops an entry from the location stack <i class="term">LS</i> and
discards it.</p></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">ERROR HANDLING</a></h3>
<p>The instructions in this section provide read and write access to the
error status <i class="term">ER</i> of the machine.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">ier_push</b></dt>
<dd><p>This instruction pushes a copy of the current error status <i class="term">ER</i>
on the error stack <i class="term">ES</i>.</p></dd>
<dt><b class="cmd">ier_clear</b></dt>
<dd><p>This instruction clears the error status <i class="term">ER</i>.</p></dd>
<dt><b class="cmd">ier_nonterminal</b> <i class="arg">message</i></dt>
<dd><p>This instruction checks if the error status <i class="term">ER</i> contains an
error whose location is just past the location found in the top entry
of the location stack <i class="term">LS</i>.
Nothing happens if no such error is found.
Otherwise the found error is replaced by an error at the location
found on the stack, having the message <i class="arg">message</i>.</p></dd>
<dt><b class="cmd">ier_merge</b></dt>
<dd><p>This instruction pops an entry from the error stack <i class="term">ES</i>, merges
it with the current error status <i class="term">ER</i> and stores the result of
the merge as the new error status <i class="term">ER</i>.</p>
<p>The merge is performed as described below:</p>
<p>If one of the two error states is empty the other is chosen. If
neither error state is empty, and refering to different locations,
then the error state with the location further in the input is
chosen. If both error states refer to the same location their messages
are merged (with removing duplicates).</p></dd>
</dl>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">SEMANTIC VALUES</a></h3>
<p>The instructions in this section manipulate the semantic value
<i class="term">SV</i>.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">isv_clear</b></dt>
<dd><p>This instruction clears the semantic value <i class="term">SV</i>.</p></dd>
<dt><b class="cmd">isv_terminal</b></dt>
<dd><p>This instruction creates a terminal AST node for the current token
<i class="term">CT</i>, makes it the semantic value <i class="term">SV</i>, and also pushes the
node on the AST stack <i class="term">AS</i>.</p></dd>
<dt><b class="cmd">isv_nonterminal_leaf</b> <i class="arg">nt</i></dt>
<dd><p>This instruction creates a nonterminal AST node without any children
for the nonterminal <i class="arg">nt</i>, and makes it the semantic value
<i class="term">SV</i>.</p>
<p>This instruction should be executed if, and only if the match status
<i class="term">OK</i> indicates a success.
In the case of a failure <b class="cmd">isv_clear</b> should be called.</p></dd>
<dt><b class="cmd">isv_nonterminal_range</b> <i class="arg">nt</i></dt>
<dd><p>This instruction creates a nonterminal AST node for the nonterminal
<i class="arg">nt</i>, with a single terminal node as its child, and makes this AST
the semantic value <i class="term">SV</i>. The terminal node refers to the input
string from the location found on top of the location stack <i class="term">LS</i>
to the current location <i class="term">CL</i> (both inclusive).</p>
<p>This instruction should be executed if, and only if the match status
<i class="term">OK</i> indicates a success.
In the case of a failure <b class="cmd">isv_clear</b> should be called.</p></dd>
<dt><b class="cmd">isv_nonterminal_reduce</b> <i class="arg">nt</i></dt>
<dd><p>This instruction creates a nonterminal AST node for the nonterminal
<i class="arg">nt</i> and makes it the semantic value <i class="term">SV</i>.</p>
<p>All entries on the AST stack <i class="term">AS</i> above the marker found in the
top entry of the AST Marker stack <i class="term">MS</i> become children of the new
node, with the entry at the stack top becoming the rightmost child. If
the AST Marker stack <i class="term">MS</i> is empty the whole stack is used. The
AST marker stack <i class="term">MS</i> is left unchanged.</p>
<p>This instruction should be executed if, and only if the match status
<i class="term">OK</i> indicates a success.
In the case of a failure <b class="cmd">isv_clear</b> should be called.</p></dd>
</dl>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">AST STACK HANDLING</a></h3>
<p>The instructions in this section manipulate the AST stack <i class="term">AS</i>,
and the AST Marker stack <i class="term">MS</i>.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">ias_push</b></dt>
<dd><p>This instruction pushes the semantic value <i class="term">SV</i> on the AST stack
<i class="term">AS</i>.</p></dd>
<dt><b class="cmd">ias_mark</b></dt>
<dd><p>This instruction pushes a marker for the current state of the AST
stack <i class="term">AS</i> on the AST Marker stack <i class="term">MS</i>.</p></dd>
<dt><b class="cmd">ias_mrewind</b></dt>
<dd><p>This instruction pops an entry from the AST Marker stack <i class="term">MS</i> and
then proceeds to pop entries from the AST stack <i class="term">AS</i> until the
state represented by the popped marker has been reached again.
Nothing is done if the AST stack <i class="term">AS</i> is already smaller than
indicated by the popped marker.</p></dd>
<dt><b class="cmd">ias_mpop</b></dt>
<dd><p>This instruction pops an entry from the AST Marker stack <i class="term">MS</i> and
discards it.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_me</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_peg/peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
|
<div class='fossil-doc' data-title='grammar::peg - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::peg(n) 0.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::peg - Create and manipulate parsing expression grammars</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">TERMS & CONCEPTS</a></li>
<li class="doctools_subsection"><a href="#subsection2">CONTAINER CLASS API</a></li>
<li class="doctools_subsection"><a href="#subsection3">CONTAINER OBJECT API</a></li>
<li class="doctools_subsection"><a href="#subsection4">PARSING EXPRESSIONS</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">PARSING EXPRESSION GRAMMARS</a></li>
<li class="doctools_section"><a href="#section3">REFERENCES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">grammar::peg <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::peg</b> <i class="arg">pegName</i> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const"><--</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">src</i>?</span></a></li>
<li><a href="#2"><i class="arg">pegName</i> <b class="method">destroy</b></a></li>
<li><a href="#3"><i class="arg">pegName</i> <b class="method">clear</b></a></li>
<li><a href="#4"><i class="arg">pegName</i> <b class="method">=</b> <i class="arg">srcPEG</i></a></li>
<li><a href="#5"><i class="arg">pegName</i> <b class="method">--></b> <i class="arg">dstPEG</i></a></li>
<li><a href="#6"><i class="arg">pegName</i> <b class="method">serialize</b></a></li>
<li><a href="#7"><i class="arg">pegName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></li>
<li><a href="#8"><i class="arg">pegName</i> <b class="method">is valid</b></a></li>
<li><a href="#9"><i class="arg">pegName</i> <b class="method">start</b> <span class="opt">?<i class="arg">pe</i>?</span></a></li>
<li><a href="#10"><i class="arg">pegName</i> <b class="method">nonterminals</b></a></li>
<li><a href="#11"><i class="arg">pegName</i> <b class="method">nonterminal add</b> <i class="arg">nt</i> <i class="arg">pe</i></a></li>
<li><a href="#12"><i class="arg">pegName</i> <b class="method">nonterminal delete</b> <i class="arg">nt1</i> <span class="opt">?<i class="arg">nt2</i> ...?</span></a></li>
<li><a href="#13"><i class="arg">pegName</i> <b class="method">nonterminal exists</b> <i class="arg">nt</i></a></li>
<li><a href="#14"><i class="arg">pegName</i> <b class="method">nonterminal rename</b> <i class="arg">nt</i> <i class="arg">ntnew</i></a></li>
<li><a href="#15"><i class="arg">pegName</i> <b class="method">nonterminal mode</b> <i class="arg">nt</i> <span class="opt">?<i class="arg">mode</i>?</span></a></li>
<li><a href="#16"><i class="arg">pegName</i> <b class="method">nonterminal rule</b> <i class="arg">nt</i></a></li>
<li><a href="#17"><i class="arg">pegName</i> <b class="method">unknown nonterminals</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a container class for
<i class="term">parsing expression grammars</i> (Short: PEG).
It allows the incremental definition of the grammar, its manipulation
and querying of the definition.
The package neither provides complex operations on the grammar, nor has
it the ability to execute a grammar definition for a stream of symbols.
Two packages related to this one are <b class="package">grammar::mengine</b> and
<b class="package">grammar::peg::interpreter</b>. The first of them defines a
general virtual machine for the matching of a character stream, and
the second implements an interpreter for parsing expression grammars
on top of that virtual machine.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">TERMS & CONCEPTS</a></h3>
<p>PEGs are similar to context-free grammars, but not equivalent; in some
cases PEGs are strictly more powerful than context-free grammars (there
exist PEGs for some non-context-free languages).
The formal mathematical definition of parsing expressions and parsing
expression grammars can be found in section
<span class="sectref"><a href="#section2">PARSING EXPRESSION GRAMMARS</a></span>.</p>
<p>In short, we have <i class="term">terminal symbols</i>, which are the most basic
building blocks for <i class="term">sentences</i>, and <i class="term">nonterminal symbols</i>
with associated <i class="term">parsing expressions</i>, defining the grammatical
structure of the sentences. The two sets of symbols are distinctive,
and do not overlap. When speaking about symbols the word "symbol" is
often left out. The union of the sets of terminal and nonterminal
symbols is called the set of <i class="term">symbols</i>.</p>
<p>Here the set of <i class="term">terminal symbols</i> is not explicitly managed,
but implicitly defined as the set of all characters. Note that this
means that we inherit from Tcl the ability to handle all of Unicode.</p>
<p>A pair of <i class="term">nonterminal</i> and <i class="term"><a href="../../../../index.html#parsing_expression">parsing expression</a></i> is also
called a <i class="term">grammatical rule</i>, or <i class="term">rule</i> for short. In the
context of a rule the nonterminal is often called the left-hand-side
(LHS), and the parsing expression the right-hand-side (RHS).</p>
<p>The <i class="term">start expression</i> of a grammar is a parsing expression
from which all the sentences contained in the language specified by
the grammar are <i class="term">derived</i>.
To make the understanding of this term easier let us assume for a
moment that the RHS of each rule, and the start expression, is either
a sequence of symbols, or a series of alternate parsing expressions.
In the latter case the rule can be seen as a set of rules, each
providing one alternative for the nonterminal.
A parsing expression A' is now a derivation of a parsing expression A
if we pick one of the nonterminals N in the expression, and one of the
alternative rules R for N, and then replace the nonterminal in A with
the RHS of the chosen rule. Here we can see why the terminal symbols
are called such. They cannot be expanded any further, thus terminate
the process of deriving new expressions.
An example</p>
<pre class="doctools_example">
Rules
(1) A <- a B c
(2a) B <- d B
(2b) B <- e
Some derivations, using starting expression A.
A -/1/-> a B c -/2a/-> a d B c -/2b/-> a d e c
</pre>
<p>A derived expression containing only terminal symbols is a
<i class="term">sentence</i>. The set of all sentences which can be derived from
the start expression is the <i class="term">language</i> of the grammar.</p>
<p>Some definitions for nonterminals and expressions:</p>
<ol class="doctools_enumerated">
<li><p>A nonterminal A is called <i class="term">reachable</i> if it is possible to derive
a parsing expression from the start expression which contains A.</p></li>
<li><p>A nonterminal A is called <i class="term">useful</i> if it is possible to derive a
sentence from it.</p></li>
<li><p>A nonterminal A is called <i class="term">recursive</i> if it is possible to derive
a parsing expression from it which contains A, again.</p></li>
<li><p>The <i class="term">FIRST set</i> of a nonterminal A contains all the symbols which
can occur of as the leftmost symbol in a parsing expression derived from
A. If the FIRST set contains A itself then that nonterminal is called
<i class="term">left-recursive</i>.</p></li>
<li><p>The <i class="term">LAST set</i> of a nonterminal A contains all the symbols which
can occur of as the rightmost symbol in a parsing expression derived from
A. If the LAST set contains A itself then that nonterminal is called
<i class="term">right-recursive</i>.</p></li>
<li><p>The <i class="term">FOLLOW set</i> of a nonterminal A contains all the symbols which
can occur after A in a parsing expression derived from the start
expression.</p></li>
<li><p>A nonterminal (or parsing expression) is called <i class="term">nullable</i> if the
empty sentence can be derived from it.</p></li>
</ol>
<p>And based on the above definitions for grammars:</p>
<ol class="doctools_enumerated">
<li><p>A grammar G is <i class="term">recursive</i> if and only if it contains a nonterminal
A which is recursive. The terms <i class="term">left-</i> and <i class="term">right-recursive</i>,
and <i class="term">useful</i> are analogously defined.</p></li>
<li><p>A grammar is <i class="term">minimal</i> if it contains only <i class="term">reachable</i> and
<i class="term">useful</i> nonterminals.</p></li>
<li><p>A grammar is <i class="term">wellformed</i> if it is not left-recursive. Such
grammars are also <i class="term">complete</i>, which means that they always succeed
or fail on all input sentences. For an incomplete grammar on the
other hand input sentences exist for which an attempt to match them
against the grammar will not terminate.</p></li>
<li><p>As we wish to allow ourselves to build a grammar incrementally in a
container object we will encounter stages where the RHS of one or more
rules reference symbols which are not yet known to the container. Such
a grammar we call <i class="term">invalid</i>.
We cannot use the term <i class="term">incomplete</i> as this term is already
taken, see the last item.</p></li>
</ol>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">CONTAINER CLASS API</a></h3>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::peg</b> <i class="arg">pegName</i> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const"><--</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">src</i>?</span></a></dt>
<dd><p>The command creates a new container object for a parsing expression
grammar and returns the fully qualified name of the object command as
its result. The API the returned command is following is described in
the section <span class="sectref"><a href="#subsection3">CONTAINER OBJECT API</a></span>. It may be used to invoke
various operations on the container and the grammar within.</p>
<p>The new container, i.e. grammar will be empty if no <i class="arg">src</i> is
specified. Otherwise it will contain a copy of the grammar contained
in the <i class="arg">src</i>.
The <i class="arg">src</i> has to be a container object reference for all operators
except <b class="const">deserialize</b>.
The <b class="const">deserialize</b> operator requires <i class="arg">src</i> to be the
serialization of a parsing expression grammar instead.</p>
<p>An empty grammar has no nonterminal symbols, and the start expression
is the empty expression, i.e. epsilon. It is <i class="term">valid</i>, but not
<i class="term">useful</i>.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">CONTAINER OBJECT API</a></h3>
<p>All grammar container objects provide the following methods for the
manipulation of their contents:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">pegName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the grammar, including its storage space and associated
command.</p></dd>
<dt><a name="3"><i class="arg">pegName</i> <b class="method">clear</b></a></dt>
<dd><p>Clears out the definition of the grammar contained in <i class="arg">pegName</i>,
but does <em>not</em> destroy the object.</p></dd>
<dt><a name="4"><i class="arg">pegName</i> <b class="method">=</b> <i class="arg">srcPEG</i></a></dt>
<dd><p>Assigns the contents of the grammar contained in <i class="arg">srcPEG</i> to
<i class="arg">pegName</i>, overwriting any existing definition.
This is the assignment operator for grammars. It copies the grammar
contained in the grammar object <i class="arg">srcPEG</i> over the grammar
definition in <i class="arg">pegName</i>. The old contents of <i class="arg">pegName</i> are
deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">pegName</i> <b class="method">deserialize</b> [<i class="arg">srcPEG</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="5"><i class="arg">pegName</i> <b class="method">--></b> <i class="arg">dstPEG</i></a></dt>
<dd><p>This is the reverse assignment operator for grammars. It copies the
automation contained in the object <i class="arg">pegName</i> over the grammar
definition in the object <i class="arg">dstPEG</i>.
The old contents of <i class="arg">dstPEG</i> are deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">dstPEG</i> <b class="method">deserialize</b> [<i class="arg">pegName</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="6"><i class="arg">pegName</i> <b class="method">serialize</b></a></dt>
<dd><p>This method serializes the grammar stored in <i class="arg">pegName</i>. In other
words it returns a tcl <em>value</em> completely describing that
grammar.
This allows, for example, the transfer of grammars over arbitrary
channels, persistence, etc.
This method is also the basis for both the copy constructor and the
assignment operator.</p>
<p>The result of this method has to be semantically identical over all
implementations of the <b class="package">grammar::peg</b> interface. This is what
will enable us to copy grammars between different implementations of
the same interface.</p>
<p>The result is a list of four elements with the following structure:</p>
<ol class="doctools_enumerated">
<li><p>The constant string <b class="const">grammar::peg</b>.</p></li>
<li><p>A dictionary. Its keys are the names of all known nonterminal symbols,
and their associated values are the parsing expressions describing
their sentennial structure.</p></li>
<li><p>A dictionary. Its keys are the names of all known nonterminal symbols,
and their associated values hints to a matcher regarding the semantic
values produced by the symbol.</p></li>
<li><p>The last item is a parsing expression, the <i class="term">start expression</i>
of the grammar.</p></li>
</ol>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
Sign <- '+' / '-'
Number <- Sign? Digit+
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)
MulOp <- '*' / '/'
Factor <- Term (AddOp Term)*
AddOp <- '+'/'-'
Term <- Number
</pre>
<p>a possible serialization is</p>
<pre class="doctools_example">
grammar::peg \\
{Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
Factor {x Term {* {x AddOp Term}}} \\
Term Number \\
MulOp {/ * /} \\
AddOp {/ + -} \\
Number {x {? Sign} {+ Digit}} \\
Sign {/ + -} \\
Digit {/ 0 1 2 3 4 5 6 7 8 9} \\
} \\
{Expression value Factor value \\
Term value MulOp value \\
AddOp value Number value \\
Sign value Digit value \\
}
Expression
</pre>
<p>A possible one, because the order of the nonterminals in the
dictionary is not relevant.</p></dd>
<dt><a name="7"><i class="arg">pegName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the grammar
definition in <i class="arg">pegName</i> with the grammar described by the
<i class="arg">serialization</i> value. The old contents of <i class="arg">pegName</i> are
deleted by this operation.</p></dd>
<dt><a name="8"><i class="arg">pegName</i> <b class="method">is valid</b></a></dt>
<dd><p>A predicate. It tests whether the PEG in <i class="arg">pegName</i> is <i class="term">valid</i>.
See section <span class="sectref"><a href="#subsection1">TERMS & CONCEPTS</a></span> for the definition of this
grammar property.
The result is a boolean value. It will be set to <b class="const">true</b> if
the PEG has the tested property, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="9"><i class="arg">pegName</i> <b class="method">start</b> <span class="opt">?<i class="arg">pe</i>?</span></a></dt>
<dd><p>This method defines the <i class="term">start expression</i> of the grammar. It
replaces the previously defined start expression with the parsing
expression <i class="arg">pe</i>.
The method fails and throws an error if <i class="arg">pe</i> does not contain a
valid parsing expression as specified in the section
<span class="sectref"><a href="#subsection4">PARSING EXPRESSIONS</a></span>. In that case the existing start
expression is not changed.
The method returns the empty string as its result.</p>
<p>If the method is called without an argument it will return the currently
defined start expression.</p></dd>
<dt><a name="10"><i class="arg">pegName</i> <b class="method">nonterminals</b></a></dt>
<dd><p>Returns the set of all nonterminal symbols known to the grammar.</p></dd>
<dt><a name="11"><i class="arg">pegName</i> <b class="method">nonterminal add</b> <i class="arg">nt</i> <i class="arg">pe</i></a></dt>
<dd><p>This method adds the nonterminal <i class="arg">nt</i> and its associated parsing
expression <i class="arg">pe</i> to the set of nonterminal symbols and rules of the
PEG contained in the object <i class="arg">pegName</i>.
The method fails and throws an error if either the string <i class="arg">nt</i> is
already known as a symbol of the grammar, or if <i class="arg">pe</i> does not
contain a valid parsing expression as specified in the section
<span class="sectref"><a href="#subsection4">PARSING EXPRESSIONS</a></span>. In that case the current set of
nonterminal symbols and rules is not changed.
The method returns the empty string as its result.</p></dd>
<dt><a name="12"><i class="arg">pegName</i> <b class="method">nonterminal delete</b> <i class="arg">nt1</i> <span class="opt">?<i class="arg">nt2</i> ...?</span></a></dt>
<dd><p>This method removes the named symbols <i class="arg">nt1</i>, <i class="arg">nt2</i> from the
set of nonterminal symbols of the PEG contained in the object
<i class="arg">pegName</i>.
The method fails and throws an error if any of the strings is not
known as a nonterminal symbol. In that case the current set of
nonterminal symbols is not changed.
The method returns the empty string as its result.</p>
<p>The stored grammar becomes invalid if the deleted nonterminals are
referenced by the RHS of still-known rules.</p></dd>
<dt><a name="13"><i class="arg">pegName</i> <b class="method">nonterminal exists</b> <i class="arg">nt</i></a></dt>
<dd><p>A predicate. It tests whether the nonterminal symbol <i class="arg">nt</i> is known
to the PEG in <i class="arg">pegName</i>.
The result is a boolean value. It will be set to <b class="const">true</b> if the
symbol <i class="arg">nt</i> is known, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="14"><i class="arg">pegName</i> <b class="method">nonterminal rename</b> <i class="arg">nt</i> <i class="arg">ntnew</i></a></dt>
<dd><p>This method renames the nonterminal symbol <i class="arg">nt</i> to <i class="arg">ntnew</i>.
The method fails and throws an error if either <i class="arg">nt</i> is not known
as a nonterminal, or if <i class="arg">ntnew</i> is a known symbol.
The method returns the empty string as its result.</p></dd>
<dt><a name="15"><i class="arg">pegName</i> <b class="method">nonterminal mode</b> <i class="arg">nt</i> <span class="opt">?<i class="arg">mode</i>?</span></a></dt>
<dd><p>This mode returns or sets the semantic mode associated with the
nonterminal symbol <i class="arg">nt</i>. If no <i class="arg">mode</i> is specified the
current mode of the nonterminal is returned. Otherwise the current
mode is set to <i class="arg">mode</i>.
The method fails and throws an error if <i class="arg">nt</i> is not known as a
nonterminal.
The grammar interpreter implemented by the package
<b class="package">grammar::peg::interpreter</b> recognizes the
following modes:</p>
<dl class="doctools_definitions">
<dt>value</dt>
<dd><p>The semantic value of the nonterminal is the abstract syntax tree
created from the AST's of the RHS and a node for the nonterminal
itself.</p></dd>
<dt>match</dt>
<dd><p>The semantic value of the nonterminal is an the abstract syntax tree
consisting of single a node for the string matched by the RHS. The ASTs
generated by the RHS are discarded.</p></dd>
<dt>leaf</dt>
<dd><p>The semantic value of the nonterminal is an the abstract syntax tree
consisting of single a node for the nonterminal itself. The ASTs
generated by the RHS are discarded.</p></dd>
<dt>discard</dt>
<dd><p>The nonterminal has no semantic value. The ASTs generated by the RHS
are discarded (as well).</p></dd>
</dl></dd>
<dt><a name="16"><i class="arg">pegName</i> <b class="method">nonterminal rule</b> <i class="arg">nt</i></a></dt>
<dd><p>This method returns the parsing expression associated with the
nonterminal <i class="arg">nt</i>.
The method fails and throws an error if <i class="arg">nt</i> is not known as a
nonterminal.</p></dd>
<dt><a name="17"><i class="arg">pegName</i> <b class="method">unknown nonterminals</b></a></dt>
<dd><p>This method returns a list containing the names of all nonterminal
symbols which are referenced on the RHS of a grammatical rule, but
have no rule definining their structure. In other words, a list of
the nonterminal symbols which make the grammar invalid. The grammar
is valid if this list is empty.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">PARSING EXPRESSIONS</a></h3>
<p>Various methods of PEG container objects expect a parsing expression
as their argument, or will return such. This section specifies the
format such parsing expressions are in.</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any alphanumeric character.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any alphabetical character.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol>
<p>Examples of parsing expressions where already shown, in the
description of the method <b class="method">serialize</b>.</p>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PARSING EXPRESSION GRAMMARS</a></h2>
<p>For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where</p>
<ul class="doctools_itemized">
<li><p>VN is a set of <i class="term">nonterminal symbols</i>,</p></li>
<li><p>VT is a set of <i class="term">terminal symbols</i>,</p></li>
<li><p>R is a finite set of rules, where each rule is a pair (A,e), A in VN,
and <i class="term"><a href="../../../../index.html#e">e</a></i> a <i class="term"><a href="../../../../index.html#parsing_expression">parsing expression</a></i>.</p></li>
<li><p>eS is a parsing expression, the <i class="term">start expression</i>.</p></li>
</ul>
<p>Further constraints are</p>
<ul class="doctools_itemized">
<li><p>The intersection of VN and VT is empty.</p></li>
<li><p>For all A in VT exists exactly one pair (A,e) in R. In other words, R
is a function from nonterminal symbols to parsing expressions.</p></li>
</ul>
<p>Parsing expression are inductively defined via</p>
<ul class="doctools_itemized">
<li><p>The empty string (epsilon) is a parsing expression.</p></li>
<li><p>A terminal symbol <i class="term">a</i> is a parsing expression.</p></li>
<li><p>A nonterminal symbol <i class="term">A</i> is a parsing expression.</p></li>
<li><p><i class="term">e1</i><i class="term">e2</i> is a parsing expression for parsing expressions
<i class="term">e1</i> and <i class="term">2</i>. This is called <i class="term">sequence</i>.</p></li>
<li><p><i class="term">e1</i>/<i class="term">e2</i> is a parsing expression for parsing expressions
<i class="term">e1</i> and <i class="term">2</i>. This is called <i class="term">ordered choice</i>.</p></li>
<li><p><i class="term"><a href="../../../../index.html#e">e</a></i>* is a parsing expression for parsing expression
<i class="term"><a href="../../../../index.html#e">e</a></i>. This is called <i class="term">zero-or-more repetitions</i>, also known
as <i class="term">kleene closure</i>.</p></li>
<li><p><i class="term"><a href="../../../../index.html#e">e</a></i>+ is a parsing expression for parsing expression
<i class="term"><a href="../../../../index.html#e">e</a></i>. This is called <i class="term">one-or-more repetitions</i>, also known
as <i class="term">positive kleene closure</i>.</p></li>
<li><p>!<i class="term"><a href="../../../../index.html#e">e</a></i> is a parsing expression for parsing expression
<i class="term">e1</i>. This is called a <i class="term">not lookahead predicate</i>.</p></li>
<li><p>&<i class="term"><a href="../../../../index.html#e">e</a></i> is a parsing expression for parsing expression
<i class="term">e1</i>. This is called an <i class="term">and lookahead predicate</i>.</p></li>
</ul>
<p>PEGs are used to define a grammatical structure for streams of symbols
over VT. They are a modern phrasing of older formalisms invented by
Alexander Birham. These formalisms were called TS (TMG recognition
scheme), and gTS (generalized TS). Later they were renamed to TPDL
(Top-Down Parsing Languages) and gTPDL (generalized TPDL).</p>
<p>They can be easily implemented by recursive descent parsers with
backtracking. This makes them relatives of LL(k) Context-Free
Grammars.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://www.pdos.lcs.mit.edu/~baford/packrat/">The Packrat Parsing and Parsing Expression Grammars Page</a>,
by Bryan Ford, Massachusetts Institute of Technology. This is the main
entry page to PEGs, and their realization through Packrat Parsers.</p></li>
<li><p><a href="http://www.cs.vu.nl/~dick/PTAPG.html">Parsing Techniques - A Practical Guide </a>, an online book
offering a clear, accessible, and thorough discussion of many
different parsing techniques with their interrelations and
applicabilities, including error recovery techniques.</p></li>
<li><p><a href="http://scifac.ru.ac.za/compilers/">Compilers and Compiler Generators</a>, an online book using
CoCo/R, a generator for recursive descent parsers.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_peg</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
<div class='fossil-doc' data-title='grammar::peg::interp - Grammar operations and usage'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">grammar::peg::interp(n) 0.1.1 tcllib "Grammar operations and usage"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>grammar::peg::interp - Interpreter for parsing expression grammars</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">THE INTERPRETER API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">grammar::mengine <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">grammar::peg::interp <span class="opt">?0.1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::grammar::peg::interp::setup</b> <i class="arg">peg</i></a></li>
<li><a href="#2"><b class="cmd">::grammar::peg::interp::parse</b> <i class="arg">nextcmd</i> <i class="arg">errorvar</i> <i class="arg">astvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for the controlled matching of a
character stream via a parsing expression grammar and the creation
of an abstract syntax tree for the stream and partials.</p>
<p>It is built on top of the virtual machine provided by the package
<b class="package"><a href="../grammar_me/me_tcl.html">grammar::me::tcl</a></b> and directly interprets the parsing
expression grammar given to it.
In other words, the grammar is <em>not</em> pre-compiled but used as is.</p>
<p>The grammar to be interpreted is taken from a container object
following the interface specified by the package
<b class="package">grammar::peg::container</b>. Only the relevant parts
are copied into the state of this package.</p>
<p>It should be noted that the package provides exactly one instance
of the interpreter, and interpreting a second grammar requires
the user to either abort or complete a running interpretation, or
to put them into different Tcl interpreters.</p>
<p>Also of note is that the implementation assumes a pull-type
handling of the input. In other words, the interpreter pulls
characters from the input stream as it needs them. For usage
in a push environment, i.e. where the environment pushes new
characters as they come we have to put the engine into its
own thread.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">THE INTERPRETER API</a></h2>
<p>The package exports the following API</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::grammar::peg::interp::setup</b> <i class="arg">peg</i></a></dt>
<dd><p>This command (re)initializes the interpreter. It returns the
empty string. This command has to be invoked first, before any
matching run.</p>
<p>Its argument <i class="arg">peg</i> is the handle of an object containing the
parsing expression grammar to interpret. This grammar has to be
valid, or an error will be thrown.</p></dd>
<dt><a name="2"><b class="cmd">::grammar::peg::interp::parse</b> <i class="arg">nextcmd</i> <i class="arg">errorvar</i> <i class="arg">astvar</i></a></dt>
<dd><p>This command interprets the loaded grammar and tries to match it
against the stream of characters represented by the command prefix
<i class="arg">nextcmd</i>.</p>
<p>The command prefix <i class="arg">nextcmd</i> represents the input stream of
characters and is invoked by the interpreter whenever the a new
character from the stream is required.
The callback has to return either the empty list, or a list of 4
elements containing the token, its lexeme attribute, and its location
as line number and column index, in this order.
The empty list is the signal that the end of the input stream has been
reached. The lexeme attribute is stored in the terminal cache, but
otherwise not used by the machine.</p>
<p>The result of the command is a boolean value indicating whether the
matching process was successful (<b class="const">true</b>), or not
(<b class="const">false</b>). In the case of a match failure error information will
be stored into the variable referenced by <i class="arg">errorvar</i>. The variable
referenced by <i class="arg">astvar</i> will always contain the generated abstract
syntax tree, however in the case of an error it will be only partial
and possibly malformed.</p>
<p>The abstract syntax tree is represented by a nested list, as
described in section <b class="sectref">AST VALUES</b> of
document <i class="term"><a href="../grammar_me/me_ast.html">grammar::me_ast</a></i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>grammar_peg</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Grammars and finite automata</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005-2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/hook/hook.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
|
<div class='fossil-doc' data-title='hook - Hooks'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">hook(n) 0.1 tcllib "Hooks"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>hook - Hooks</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Concepts</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Introduction</a></li>
<li class="doctools_subsection"><a href="#subsection2">Bindings</a></li>
<li class="doctools_subsection"><a href="#subsection3">Subjects and observers</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Reference</a></li>
<li class="doctools_section"><a href="#section4">Example</a></li>
<li class="doctools_section"><a href="#section5">Credits</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">hook <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">hook</b> <b class="method">bind</b> <span class="opt">?<i class="arg">subject</i>?</span> <span class="opt">?<i class="arg">hook</i>?</span> <span class="opt">?<i class="arg">observer</i>?</span> <span class="opt">?<i class="arg">cmdPrefix</i>?</span></a></li>
<li><a href="#2"><b class="cmd">hook</b> <b class="method">call</b> <i class="arg">subject</i> <i class="arg">hook</i> <span class="opt">?<i class="arg">args</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">hook</b> <b class="method">forget</b> <i class="arg">object</i></a></li>
<li><a href="#4"><b class="cmd">hook</b> <b class="method">cget</b> <i class="arg">option</i></a></li>
<li><a href="#5"><b class="cmd">hook</b> <b class="method">configure</b> <b class="option">option</b> <i class="arg">value</i> ...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the <b class="cmd">hook</b> ensemble command, which
implements the Subject/Observer pattern. It allows <i class="term">subjects</i>,
which may be <i class="term">modules</i>, <i class="term">objects</i>, <i class="term">widgets</i>, and so
forth, to synchronously call <i class="term">hooks</i> which may be bound to an
arbitrary number of subscribers, called <i class="term">observers</i>. A subject
may call any number of distinct hooks, and any number of observers can
bind callbacks to a particular hook called by a particular
subject. Hook bindings can be queried and deleted.</p>
<p>This man page is intended to be a reference only.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Concepts</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Introduction</a></h3>
<p>Tcl modules usually send notifications to other modules in two ways:
via Tk events, and via callback options like the text widget's
<b class="option">-yscrollcommand</b> option. Tk events are available only in Tk,
and callback options require tight coupling between the modules
sending and receiving the notification.</p>
<p>Loose coupling between sender and receiver is often desirable,
however. In Model/View/Controller terms, a View can send a command
(stemming from user input) to the Controller, which updates the
Model. The Model can then call a hook <em>to which all relevant
Views subscribe.</em> The Model is decoupled from the Views, and indeed
need not know whether any Views actually exist.
At present, Tcl/Tk has no standard mechanism for implementing loose
coupling of this kind. This package defines a new command, <b class="cmd">hook</b>,
which implements just such a mechanism.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Bindings</a></h3>
<p>The <b class="cmd">hook</b> command manages a collection of hook bindings. A hook
binding has four elements:</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term"><a href="../../../../index.html#subject">subject</a></i>: the name of the entity that will be calling the
hook.</p></li>
<li><p>The <i class="term"><a href="../../../../index.html#hook">hook</a></i> itself. A hook usually reflects some occurrence in the
life of the <i class="term"><a href="../../../../index.html#subject">subject</a></i> that other entities might care to know
about. A <i class="term"><a href="../../../../index.html#hook">hook</a></i> has a name, and may also have arguments. Hook
names are arbitrary strings. Each <i class="term"><a href="../../../../index.html#subject">subject</a></i> must document the
names and arguments of the hooks it can call.</p></li>
<li><p>The name of the <i class="term"><a href="../../../../index.html#observer">observer</a></i> that wishes to receive the <i class="term"><a href="../../../../index.html#hook">hook</a></i>
from the <i class="term"><a href="../../../../index.html#subject">subject</a></i>.</p></li>
<li><p>A command prefix to which the <i class="term"><a href="../../../../index.html#hook">hook</a></i> arguments will be appended
when the binding is executed.</p></li>
</ol>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Subjects and observers</a></h3>
<p>For convenience, this document collectively refers to subjects and
observers as <i class="term">objects</i>, while placing no requirements on how
these <i class="term">objects</i> are actually implemented. An object can be a
<b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> or <b class="package"><a href="../../../../index.html#snit">Snit</a></b> or <b class="package">XOTcl</b> object, a Tcl
command, a namespace, a module, a pseudo-object managed by some other
object (as tags are managed by the Tk text widget) or simply a
well-known name.</p>
<p>Subject and observer names are arbitrary strings; however, as
<b class="cmd">hook</b> might be used at the package level, it's necessary to have
conventions that avoid name collisions between packages written by
different people.</p>
<p>Therefore, any subject or observer name used in core or package level
code should look like a Tcl command name, and should be defined in a
namespace owned by the package. Consider, for example, an ensemble
command <b class="cmd">::foo</b> that creates a set of pseudo-objects and uses
<b class="package">hook</b> to send notifications. The pseudo-objects have names
that are not commands and exist in their own namespace, rather like
file handles do. To avoid name collisions with subjects defined by
other packages, users of <b class="package">hook</b>, these <b class="cmd">::foo</b> handles
should have names like <b class="const">::foo::1</b>, <b class="const">::foo::2</b>, and so on.</p>
<p>Because object names are arbitrary strings, application code can use
whatever additional conventions are dictated by the needs of the
application.</p>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Reference</a></h2>
<p>Hook provides the following commands:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">hook</b> <b class="method">bind</b> <span class="opt">?<i class="arg">subject</i>?</span> <span class="opt">?<i class="arg">hook</i>?</span> <span class="opt">?<i class="arg">observer</i>?</span> <span class="opt">?<i class="arg">cmdPrefix</i>?</span></a></dt>
<dd><p>This subcommand is used to create, update, delete, and query hook
bindings.</p>
<p>Called with no arguments it returns a list of the subjects with
hooks to which observers are currently bound.</p>
<p>Called with one argument, a <i class="arg">subject</i>, it returns a list of
the subject's hooks to which observers are currently bound.</p>
<p>Called with two arguments, a <i class="arg">subject</i> and a <i class="arg">hook</i>, it
returns a list of the observers which are currently bound to this
<i class="arg">subject</i> and <i class="arg">hook</i>.</p>
<p>Called with three arguments, a <i class="arg">subject</i>, a <i class="arg">hook</i>, and
an <i class="arg">observer</i>, it returns the binding proper, the command prefix
to be called when the hook is called, or the empty string if there is
no such binding.</p>
<p>Called with four arguments, it creates, updates, or deletes a
binding. If <i class="arg">cmdPrefix</i> is the empty string, it deletes any
existing binding for the <i class="arg">subject</i>, <i class="arg">hook</i>, and
<i class="arg">observer</i>; nothing is returned. Otherwise, <i class="arg">cmdPrefix</i> must
be a command prefix taking as many additional arguments as are
documented for the <i class="arg">subject</i> and <i class="arg">hook</i>. The binding is added
or updated, and the observer is returned.</p>
<p>If the <i class="arg">observer</i> is the empty string, "", it will create a
new binding using an automatically generated observer name of the form
<b class="const">::hook::ob</b><<b class="variable">number</b>>. The automatically generated name
will be returned, and can be used to query, update, and delete the
binding as usual. If automated observer names are always used, the
observer name effectively becomes a unique binding ID.</p>
<p>It is possible to call <b class="cmd">hook bind</b> to create or delete a
binding to a <i class="arg">subject</i> and <i class="arg">hook</i> while in an observer binding
for that same <i class="arg">subject</i> and <i class="arg">hook</i>. The following rules
determine what happens when</p>
<pre class="doctools_example">
hook bind $s $h $o $binding
</pre>
<p>is called during the execution of</p>
<pre class="doctools_example">
hook call $s $h
</pre>
<ol class="doctools_enumerated">
<li><p>No binding is ever called after it is deleted.</p></li>
<li><p>When a binding is called, the most recently given command prefix is
always used.</p></li>
<li><p>The set of observers whose bindings are to be called is determined
when this method begins to execute, and does not change thereafter,
except that deleted bindings are not called.</p></li>
</ol>
<p>In particular:</p>
<ol class="doctools_enumerated">
<li><p>If <b class="variable">$o</b>s binding to <b class="variable">$s</b> and <b class="variable">$h</b> is deleted, and
<b class="variable">$o</b>s binding has not yet been called during this execution of</p>
<pre class="doctools_example">
hook call $s $h
</pre>
<p>it will not be called. (Note that it might already have been called;
and in all likelihood, it is probably deleting itself.)</p></li>
<li><p>If <b class="variable">$o</b> changes the command prefix that's bound to <b class="variable">$s</b> and
<b class="variable">$h</b>, and if <b class="variable">$o</b>s binding has not yet been called during
this execution of</p>
<pre class="doctools_example">
hook call $s $h
</pre>
<p>the new binding will be called when the time comes. (But again, it is
probably <b class="variable">$o</b>s binding that is is making the change.)</p></li>
<li><p>If a new observer is bound to <b class="variable">$s</b> and <b class="variable">$h</b>, its binding will
not be called until the next invocation of</p>
<pre class="doctools_example">
hook call $s $h
</pre>
</li>
</ol></dd>
<dt><a name="2"><b class="cmd">hook</b> <b class="method">call</b> <i class="arg">subject</i> <i class="arg">hook</i> <span class="opt">?<i class="arg">args</i>...?</span></a></dt>
<dd><p>This command is called when the named <i class="arg">subject</i> wishes to call the
named <i class="arg">hook</i>. All relevant bindings are called with the specified
arguments in the global namespace. Note that the bindings are called
synchronously, before the command returns; this allows the <i class="arg">args</i>
to include references to entities that will be cleaned up as soon as
the hook has been called.</p>
<p>The order in which the bindings are called is not guaranteed. If
sequence among observers must be preserved, define one observer and
have its bindings call the other callbacks directly in the proper
sequence.</p>
<p>Because the <b class="cmd">hook</b> mechanism is intended to support loose
coupling, it is presumed that the <i class="arg">subject</i> has no knowledge of
the observers, nor any expectation regarding return values. This has a
number of implications:</p>
<ol class="doctools_enumerated">
<li><p><b class="cmd">hook call</b> returns the empty string.</p></li>
<li><p>Normal return values from observer bindings are ignored.</p></li>
<li><p>Errors and other exceptional returns propagate normally by
default. This will rarely be what is wanted, because the subjects
usually have no knowledge of the observers and will therefore have no
particular competence at handling their errors. That makes it an
application issue, and so applications will usually want to define an
<b class="option">-errorcommand</b>.</p></li>
</ol>
<p>If the <b class="option">-errorcommand</b> configuration option has a non-empty
value, its value will be invoked for all errors and other exceptional
returns in observer bindings. See <b class="cmd">hook configure</b>, below, for
more information on configuration options.</p></dd>
<dt><a name="3"><b class="cmd">hook</b> <b class="method">forget</b> <i class="arg">object</i></a></dt>
<dd><p>This command deletes any existing bindings in which the named
<i class="arg">object</i> appears as either the <i class="term"><a href="../../../../index.html#subject">subject</a></i> or the
<i class="term"><a href="../../../../index.html#observer">observer</a></i>.
Bindings deleted by this method will never be called again. In
particular,</p>
<ol class="doctools_enumerated">
<li><p>If an observer is forgotten during a call to <b class="cmd">hook call</b>, any
uncalled binding it might have had to the relevant subject and hook
will <em>not</em> be called subsequently.</p></li>
<li><p>If a subject <b class="variable">$s</b> is forgotten during a call to</p>
<pre class="doctools_example">hook call $s $h</pre>
<p>then <b class="cmd">hook call</b> will return as soon as the current binding
returns. No further bindings will be called.</p></li>
</ol></dd>
<dt><a name="4"><b class="cmd">hook</b> <b class="method">cget</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the value of one of the <b class="cmd">hook</b> command's
configuration options.</p></dd>
<dt><a name="5"><b class="cmd">hook</b> <b class="method">configure</b> <b class="option">option</b> <i class="arg">value</i> ...</a></dt>
<dd><p>This command sets the value of one or more of the <b class="cmd">hook</b> command's
configuration options:</p>
<dl class="doctools_options">
<dt><b class="option">-errorcommand</b> <i class="arg">cmdPrefix</i></dt>
<dd><p>If the value of this option is the empty string, "", then errors
and other exception returns in binding scripts are propagated
normally. Otherwise, it must be a command prefix taking three
additional arguments:</p>
<ol class="doctools_enumerated">
<li><p>a 4-element list {subject hook arglist observer},</p></li>
<li><p>the result string, and</p></li>
<li><p>the return options dictionary.</p></li>
</ol>
<p>Given this information, the <b class="option">-errorcommand</b> can choose to log
the error, call <b class="cmd">interp bgerror</b>, delete the errant binding
(thus preventing the error from arising a second time) and so forth.</p></dd>
<dt><b class="option">-tracecommand</b> <i class="arg">cmdPrefix</i></dt>
<dd><p>The option's value should be a command prefix taking four
arguments:</p>
<ol class="doctools_enumerated">
<li><p>a <i class="term"><a href="../../../../index.html#subject">subject</a></i>,</p></li>
<li><p>a <i class="term"><a href="../../../../index.html#hook">hook</a></i>,</p></li>
<li><p>a list of the hook's argument values, and</p></li>
<li><p>a list of <i class="term">objects</i> the hook was called for.</p></li>
</ol>
<p>The command will be called for each hook that is called. This allows
the application to trace hook execution for debugging purposes.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Example</a></h2>
<p>The <b class="cmd">::model</b> module calls the <Update> hook in response to
commands that change the model's data:</p>
<pre class="doctools_example">
hook call ::model <Update>
</pre>
<p>The <b class="widget">.view</b> megawidget displays the model state, and needs to
know about model updates. Consequently, it subscribes to the ::model's
<Update> hook.</p>
<pre class="doctools_example">
hook bind ::model <Update> .view [list .view ModelUpdate]
</pre>
<p>When the <b class="cmd">::model</b> calls the hook, the <b class="widget">.view</b>s
ModelUpdate subcommand will be called.</p>
<p>Later the <b class="widget">.view</b> megawidget is destroyed. In its destructor,
it tells the <i class="term"><a href="../../../../index.html#hook">hook</a></i> that it no longer exists:</p>
<pre class="doctools_example">
hook forget .view
</pre>
<p>All bindings involving <b class="widget">.view</b> are deleted.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Credits</a></h2>
<p>Hook has been designed and implemented by William H. Duquette.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>hook</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../uev/uevent.html">uevent(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#callback">callback</a>, <a href="../../../../index.html#event">event</a>, <a href="../../../../index.html#hook">hook</a>, <a href="../../../../index.html#observer">observer</a>, <a href="../../../../index.html#producer">producer</a>, <a href="../../../../index.html#publisher">publisher</a>, <a href="../../../../index.html#subject">subject</a>, <a href="../../../../index.html#subscriber">subscriber</a>, <a href="../../../../index.html#uevent">uevent</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010, by William H. Duquette</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/html/html.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
|
<div class='fossil-doc' data-title='html - HTML Generation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">html(n) 1.4.4 tcllib "HTML Generation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>html - Procedures to generate HTML structures</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">html <span class="opt">?1.4.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::html::author</b> <i class="arg">author</i></a></li>
<li><a href="#2"><b class="cmd">::html::bodyTag</b> <i class="arg">args</i></a></li>
<li><a href="#3"><b class="cmd">::html::cell</b> <i class="arg">param value</i> <span class="opt">?<i class="arg">tag</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::html::checkbox</b> <i class="arg">name value</i></a></li>
<li><a href="#5"><b class="cmd">::html::checkSet</b> <i class="arg">key sep list</i></a></li>
<li><a href="#6"><b class="cmd">::html::checkValue</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::html::closeTag</b></a></li>
<li><a href="#8"><b class="cmd">::html::default</b> <i class="arg">key</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::html::description</b> <i class="arg">description</i></a></li>
<li><a href="#10"><b class="cmd">::html::end</b></a></li>
<li><a href="#11"><b class="cmd">::html::eval</b> <i class="arg">arg</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::html::extractParam</b> <i class="arg">param key</i> <span class="opt">?<i class="arg">varName</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::html::font</b> <i class="arg">args</i></a></li>
<li><a href="#14"><b class="cmd">::html::for</b> <i class="arg">start test next body</i></a></li>
<li><a href="#15"><b class="cmd">::html::foreach</b> <i class="arg">varlist1 list1</i> <span class="opt">?<i class="arg">varlist2 list2 ...</i>?</span> <i class="arg">body</i></a></li>
<li><a href="#16"><b class="cmd">::html::formValue</b> <i class="arg">name</i> <span class="opt">?<i class="arg">defvalue</i>?</span></a></li>
<li><a href="#17"><b class="cmd">::html::getFormInfo</b> <i class="arg">args</i></a></li>
<li><a href="#18"><b class="cmd">::html::getTitle</b></a></li>
<li><a href="#19"><b class="cmd">::html::h</b> <i class="arg">level string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#20"><b class="cmd">::html::h1</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#21"><b class="cmd">::html::h2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#22"><b class="cmd">::html::h3</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#23"><b class="cmd">::html::h4</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#24"><b class="cmd">::html::h5</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#25"><b class="cmd">::html::h6</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#26"><b class="cmd">::html::hdrRow</b> <i class="arg">args</i></a></li>
<li><a href="#27"><b class="cmd">::html::head</b> <i class="arg">title</i></a></li>
<li><a href="#28"><b class="cmd">::html::headTag</b> <i class="arg">string</i></a></li>
<li><a href="#29"><b class="cmd">::html::html_entities</b> <i class="arg">string</i></a></li>
<li><a href="#30"><b class="cmd">::html::if</b> <i class="arg">expr1 body1</i> <span class="opt">?<b class="const">elseif</b> <i class="arg">expr2 body2 ...</i>?</span> <span class="opt">?<b class="const">else</b> <i class="arg">bodyN</i>?</span></a></li>
<li><a href="#31"><b class="cmd">::html::init</b> <span class="opt">?<i class="arg">list</i>?</span></a></li>
<li><a href="#32"><b class="cmd">::html::keywords</b> <i class="arg">args</i></a></li>
<li><a href="#33"><b class="cmd">::html::mailto</b> <i class="arg">email</i> <span class="opt">?<i class="arg">subject</i>?</span></a></li>
<li><a href="#34"><b class="cmd">::html::meta</b> <i class="arg">args</i></a></li>
<li><a href="#35"><b class="cmd">::html::css</b> <i class="arg">href</i></a></li>
<li><a href="#36"><b class="cmd">::html::css-clear</b></a></li>
<li><a href="#37"><b class="cmd">::html::js</b> <i class="arg">href</i></a></li>
<li><a href="#38"><b class="cmd">::html::js-clear</b></a></li>
<li><a href="#39"><b class="cmd">::html::minorList</b> <i class="arg">list</i> <span class="opt">?<i class="arg">ordered</i>?</span></a></li>
<li><a href="#40"><b class="cmd">::html::minorMenu</b> <i class="arg">list</i> <span class="opt">?<i class="arg">sep</i>?</span></a></li>
<li><a href="#41"><b class="cmd">::html::nl2br</b> <i class="arg">string</i></a></li>
<li><a href="#42"><b class="cmd">::html::openTag</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#43"><b class="cmd">::html::paramRow</b> <i class="arg">list</i> <span class="opt">?<i class="arg">rparam</i>?</span> <span class="opt">?<i class="arg">cparam</i>?</span></a></li>
<li><a href="#44"><b class="cmd">::html::passwordInput</b> <span class="opt">?<i class="arg">name</i>?</span></a></li>
<li><a href="#45"><b class="cmd">::html::passwordInputRow</b> <i class="arg">label</i> <span class="opt">?<i class="arg">name</i>?</span></a></li>
<li><a href="#46"><b class="cmd">::html::quoteFormValue</b> <i class="arg">value</i></a></li>
<li><a href="#47"><b class="cmd">::html::radioSet</b> <i class="arg">key sep list</i></a></li>
<li><a href="#48"><b class="cmd">::html::radioValue</b> <i class="arg">name value</i></a></li>
<li><a href="#49"><b class="cmd">::html::refresh</b> <i class="arg">seconds url</i></a></li>
<li><a href="#50"><b class="cmd">::html::row</b> <i class="arg">args</i></a></li>
<li><a href="#51"><b class="cmd">::html::select</b> <i class="arg">name param choices</i> <span class="opt">?<i class="arg">current</i>?</span></a></li>
<li><a href="#52"><b class="cmd">::html::selectPlain</b> <i class="arg">name param choices</i> <span class="opt">?<i class="arg">current</i>?</span></a></li>
<li><a href="#53"><b class="cmd">::html::set</b> <i class="arg">var val</i></a></li>
<li><a href="#54"><b class="cmd">::html::submit</b> <i class="arg">label</i> <span class="opt">?<i class="arg">name</i>?</span></a></li>
<li><a href="#55"><b class="cmd">::html::tableFromArray</b> <i class="arg">arrname</i> <span class="opt">?<i class="arg">param</i>?</span> <span class="opt">?<i class="arg">pat</i>?</span></a></li>
<li><a href="#56"><b class="cmd">::html::tableFromList</b> <i class="arg">querylist</i> <span class="opt">?<i class="arg">param</i>?</span></a></li>
<li><a href="#57"><b class="cmd">::html::textarea</b> <i class="arg">name</i> <span class="opt">?<i class="arg">param</i>?</span> <span class="opt">?<i class="arg">current</i>?</span></a></li>
<li><a href="#58"><b class="cmd">::html::textInput</b> <i class="arg">name value args</i></a></li>
<li><a href="#59"><b class="cmd">::html::textInputRow</b> <i class="arg">label name value args</i></a></li>
<li><a href="#60"><b class="cmd">::html::varEmpty</b> <i class="arg">name</i></a></li>
<li><a href="#61"><b class="cmd">::html::while</b> <i class="arg">test body</i></a></li>
<li><a href="#62"><b class="cmd">::html::doctype</b> <i class="arg">id</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">html</b> provides commands that generate HTML.
These commands typically return an HTML string as their result. In
particular, they do not output their result to <b class="const">stdout</b>.</p>
<p>The command <b class="cmd">::html::init</b> should be called early to initialize
the module. You can also use this procedure to define default values
for HTML tag parameters.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::html::author</b> <i class="arg">author</i></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
define an author for the page. The author is noted in a comment in
the HEAD section.</p></dd>
<dt><a name="2"><b class="cmd">::html::bodyTag</b> <i class="arg">args</i></a></dt>
<dd><p>Generate a <i class="term">body</i> tag. The tag parameters are taken from <i class="arg">args</i> or
from the body.* attributes define with <b class="cmd">::html::init</b>.</p></dd>
<dt><a name="3"><b class="cmd">::html::cell</b> <i class="arg">param value</i> <span class="opt">?<i class="arg">tag</i>?</span></a></dt>
<dd><p>Generate a <i class="term">td</i> (or <i class="term">th</i>) tag, a value, and a closing
<i class="term">td</i> (or <i class="term">th</i>) tag. The
tag parameters come from <i class="arg">param</i> or TD.* attributes defined with
<b class="cmd">::html::init</b>. This uses <b class="cmd">::html::font</b> to insert a standard
<i class="term">font</i> tag into the table cell. The <i class="arg">tag</i> argument defaults to "td".</p></dd>
<dt><a name="4"><b class="cmd">::html::checkbox</b> <i class="arg">name value</i></a></dt>
<dd><p>Generate a <i class="term"><a href="../../../../index.html#checkbox">checkbox</a></i> form element with the specified name and value.
This uses <b class="cmd">::html::checkValue</b>.</p></dd>
<dt><a name="5"><b class="cmd">::html::checkSet</b> <i class="arg">key sep list</i></a></dt>
<dd><p>Generate a set of <i class="term"><a href="../../../../index.html#checkbox">checkbox</a></i> form elements and associated labels. The
<i class="arg">list</i> should contain an alternating list of labels and values.
This uses <b class="cmd">::html::checkbox</b>. All the <i class="term"><a href="../../../../index.html#checkbox">checkbox</a></i> buttons share the
same <i class="arg">key</i> for their name. The <i class="arg">sep</i> is text used to separate
the elements.</p></dd>
<dt><a name="6"><b class="cmd">::html::checkValue</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Generate the "name=<i class="arg">name</i> value=<i class="arg">value</i>" for a <i class="term"><a href="../../../../index.html#checkbox">checkbox</a></i> form
element. If the CGI variable <i class="arg">name</i> has the value <i class="arg">value</i>,
then SELECTED is added to the return value. <i class="arg">value</i> defaults to
"1".</p></dd>
<dt><a name="7"><b class="cmd">::html::closeTag</b></a></dt>
<dd><p>Pop a tag off the stack created by <b class="cmd">::html::openTag</b> and generate
the corresponding close tag (e.g., </body>).</p></dd>
<dt><a name="8"><b class="cmd">::html::default</b> <i class="arg">key</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>This procedure is used by <b class="cmd">::html::tagParam</b> to generate the name,
value list of parameters for a tag. The <b class="cmd">::html::default</b>
procedure is used to generate default values for those items not
already in <i class="arg">param</i>. If the value identified by <i class="arg">key</i> matches
a value in <i class="arg">param</i> then this procedure returns the empty string.
Otherwise, it returns a "parameter=value" string for a form element
identified by <i class="arg">key</i>. The <i class="arg">key</i> has the form "tag.parameter"
(e.g., body.bgcolor). Use <b class="cmd">::html::init</b> to register default
values. <i class="arg">param</i> defaults to the empty string.</p></dd>
<dt><a name="9"><b class="cmd">::html::description</b> <i class="arg">description</i></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
define a description <i class="term">meta</i> tag for the page. This tag is generated
later in the call to <b class="cmd">::html::head</b>.</p></dd>
<dt><a name="10"><b class="cmd">::html::end</b></a></dt>
<dd><p>Pop all open tags from the stack and generate the corresponding close
HTML tags, (e.g., </body></html>).</p></dd>
<dt><a name="11"><b class="cmd">::html::eval</b> <i class="arg">arg</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>This procedure is similar to the built-in Tcl <b class="cmd">eval</b> command. The
only difference is that it returns "" so it can be called from an HTML
template file without appending unwanted results.</p></dd>
<dt><a name="12"><b class="cmd">::html::extractParam</b> <i class="arg">param key</i> <span class="opt">?<i class="arg">varName</i>?</span></a></dt>
<dd><p>This is a parsing procedure that extracts the value of <i class="arg">key</i> from
<i class="arg">param</i>, which is a HTML-style "name=quotedvalue" list.
<i class="arg">varName</i> is used as the name of a Tcl variable that is changed to
have the value found in the parameters. The function returns 1 if the
parameter was found in <i class="arg">param</i>, otherwise it returns 0. If the
<i class="arg">varName</i> is not specified, then <i class="arg">key</i> is used as the variable
name.</p></dd>
<dt><a name="13"><b class="cmd">::html::font</b> <i class="arg">args</i></a></dt>
<dd><p>Generate a standard <i class="term">font</i> tag. The parameters to the tag are taken
from <i class="arg">args</i> and the HTML defaults defined with <b class="cmd">::html::init</b>.</p></dd>
<dt><a name="14"><b class="cmd">::html::for</b> <i class="arg">start test next body</i></a></dt>
<dd><p>This procedure is similar to the built-in Tcl <b class="cmd">for</b> control
structure. Rather than evaluating the body, it returns the subst'ed
<i class="arg">body</i>. Each iteration of the loop causes another string to be
concatenated to the result value.</p></dd>
<dt><a name="15"><b class="cmd">::html::foreach</b> <i class="arg">varlist1 list1</i> <span class="opt">?<i class="arg">varlist2 list2 ...</i>?</span> <i class="arg">body</i></a></dt>
<dd><p>This procedure is similar to the built-in Tcl <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b> control
structure. Rather than evaluating the body, it returns the subst'ed
<i class="arg">body</i>. Each iteration of the loop causes another string to be
concatenated to the result value.</p></dd>
<dt><a name="16"><b class="cmd">::html::formValue</b> <i class="arg">name</i> <span class="opt">?<i class="arg">defvalue</i>?</span></a></dt>
<dd><p>Return a name and value pair, where the value is initialized from
existing CGI data, if any. The result has this form:</p>
<pre class="doctools_example">
name="fred" value="freds value"
</pre>
</dd>
<dt><a name="17"><b class="cmd">::html::getFormInfo</b> <i class="arg">args</i></a></dt>
<dd><p>Generate hidden fields to capture form values. If <i class="arg">args</i> is
empty, then hidden fields are generated for all CGI values. Otherwise
args is a list of string match patterns for form element names.</p></dd>
<dt><a name="18"><b class="cmd">::html::getTitle</b></a></dt>
<dd><p>Return the title string, with out the surrounding <i class="term">title</i> tag,
set with a previous call to <b class="cmd">::html::title</b>.</p></dd>
<dt><a name="19"><b class="cmd">::html::h</b> <i class="arg">level string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate a heading (e.g., <i class="term">h<b class="variable">level</b></i>) tag. The <i class="arg">string</i> is nested in the
heading, and <i class="arg">param</i> is used for the tag parameters.</p></dd>
<dt><a name="20"><b class="cmd">::html::h1</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate an <i class="term">h1</i> tag. See <b class="cmd">::html::h</b>.</p></dd>
<dt><a name="21"><b class="cmd">::html::h2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate an <i class="term">h2</i> tag. See <b class="cmd">::html::h</b>.</p></dd>
<dt><a name="22"><b class="cmd">::html::h3</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate an <i class="term">h3</i> tag. See <b class="cmd">::html::h</b>.</p></dd>
<dt><a name="23"><b class="cmd">::html::h4</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate an <i class="term">h4</i> tag. See <b class="cmd">::html::h</b>.</p></dd>
<dt><a name="24"><b class="cmd">::html::h5</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate an <i class="term">h5</i> tag. See <b class="cmd">::html::h</b>.</p></dd>
<dt><a name="25"><b class="cmd">::html::h6</b> <i class="arg">string</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate an <i class="term">h6</i> tag. See <b class="cmd">::html::h</b>.</p></dd>
<dt><a name="26"><b class="cmd">::html::hdrRow</b> <i class="arg">args</i></a></dt>
<dd><p>Generate a table row, including <i class="term">tr</i> and <i class="term">th</i> tags.
Each value in <i class="arg">args</i> is place into its own table cell.
This uses <b class="cmd">::html::cell</b>.</p></dd>
<dt><a name="27"><b class="cmd">::html::head</b> <i class="arg">title</i></a></dt>
<dd><p>Generate the <i class="term">head</i> section that includes the page <i class="term">title</i>.
If previous calls have been made to
<b class="cmd">::html::author</b>,
<b class="cmd">::html::keywords</b>,
<b class="cmd">::html::description</b>,
or
<b class="cmd">::html::meta</b>
then additional tags are inserted into the <i class="term">head</i> section.
This leaves an open <i class="term"><a href="../../../../index.html#html">html</a></i> tag pushed on the stack with
<b class="cmd">::html::openTag</b>.</p></dd>
<dt><a name="28"><b class="cmd">::html::headTag</b> <i class="arg">string</i></a></dt>
<dd><p>Save a tag for inclusion in the <i class="term">head</i> section generated by
<b class="cmd">::html::head</b>. The <i class="arg">string</i> is everything in the tag except
the enclosing angle brackets, < >.</p></dd>
<dt><a name="29"><b class="cmd">::html::html_entities</b> <i class="arg">string</i></a></dt>
<dd><p>This command replaces all special characters in the <i class="arg">string</i> with
their HTML entities and returns the modified text.</p></dd>
<dt><a name="30"><b class="cmd">::html::if</b> <i class="arg">expr1 body1</i> <span class="opt">?<b class="const">elseif</b> <i class="arg">expr2 body2 ...</i>?</span> <span class="opt">?<b class="const">else</b> <i class="arg">bodyN</i>?</span></a></dt>
<dd><p>This procedure is similar to the built-in Tcl <b class="cmd">if</b> control
structure. Rather than evaluating the body of the branch that is
taken, it returns the subst'ed <i class="arg">body</i>. Note that the syntax is
slightly more restrictive than that of the built-in Tcl <b class="cmd">if</b>
control structure.</p></dd>
<dt><a name="31"><b class="cmd">::html::init</b> <span class="opt">?<i class="arg">list</i>?</span></a></dt>
<dd><p><b class="cmd">::html::init</b> accepts a Tcl-style name-value list that defines
values for items with a name of the form "tag.parameter". For
example, a default with key "body.bgcolor" defines the background
color for the <i class="term">body</i> tag.</p></dd>
<dt><a name="32"><b class="cmd">::html::keywords</b> <i class="arg">args</i></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
define a keyword <i class="term">meta</i> tag for the page. The <i class="term">meta</i> tag
is included in the result of <b class="cmd">::html::head</b>.</p></dd>
<dt><a name="33"><b class="cmd">::html::mailto</b> <i class="arg">email</i> <span class="opt">?<i class="arg">subject</i>?</span></a></dt>
<dd><p>Generate a hypertext link to a mailto: URL.</p></dd>
<dt><a name="34"><b class="cmd">::html::meta</b> <i class="arg">args</i></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
define a <i class="term">meta</i> tag for the page. The <i class="arg">args</i> is a Tcl-style name,
value list that is used for the name= and value= parameters for the
<i class="term">meta</i> tag. The <i class="term">meta</i> tag is included in the result of
<b class="cmd">::html::head</b>.</p></dd>
<dt><a name="35"><b class="cmd">::html::css</b> <i class="arg">href</i></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
define a <i class="term">link</i> tag for a linked CSS document. The <i class="arg">href</i>
value is a HTTP URL to a CSS document. The <i class="term">link</i> tag is included
in the result of <b class="cmd">::html::head</b>.</p>
<p>Multiple calls of this command are allowed, enabling the use of
multiple CSS document references. In other words, the arguments
of multiple calls are accumulated, and do not overwrite each other.</p></dd>
<dt><a name="36"><b class="cmd">::html::css-clear</b></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
clear all links to CSS documents.</p>
<p>Multiple calls of this command are allowed, doing nothing after the
first of a sequence with no intervening <b class="cmd">::html::css</b>.</p></dd>
<dt><a name="37"><b class="cmd">::html::js</b> <i class="arg">href</i></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
define a <i class="term">script</i> tag for a linked JavaScript document. The
<i class="arg">href</i> is a HTTP URL to a JavaScript document. The <i class="term">script</i>
tag is included in the result of <b class="cmd">::html::head</b>.</p>
<p>Multiple calls of this command are allowed, enabling the use of
multiple JavaScript document references. In other words, the arguments
of multiple calls are accumulated, and do not overwrite each other.</p></dd>
<dt><a name="38"><b class="cmd">::html::js-clear</b></a></dt>
<dd><p><em>Side effect only</em>. Call this before <b class="cmd">::html::head</b> to
clear all links to JavaScript documents.</p>
<p>Multiple calls of this command are allowed, doing nothing after the
first of a sequence with no intervening <b class="cmd">::html::js</b>.</p></dd>
<dt><a name="39"><b class="cmd">::html::minorList</b> <i class="arg">list</i> <span class="opt">?<i class="arg">ordered</i>?</span></a></dt>
<dd><p>Generate an ordered or unordered list of links. The <i class="arg">list</i> is a
Tcl-style name, value list of labels and urls for the links.
<i class="arg">ordered</i> is a boolean used to choose between an ordered or
unordered list. It defaults to <b class="const">false</b>.</p></dd>
<dt><a name="40"><b class="cmd">::html::minorMenu</b> <i class="arg">list</i> <span class="opt">?<i class="arg">sep</i>?</span></a></dt>
<dd><p>Generate a series of hypertext links. The <i class="arg">list</i> is a Tcl-style
name, value list of labels and urls for the links. The <i class="arg">sep</i> is
the text to put between each link. It defaults to " | ".</p></dd>
<dt><a name="41"><b class="cmd">::html::nl2br</b> <i class="arg">string</i></a></dt>
<dd><p>This command replaces all line-endings in the <i class="arg">string</i> with a
<i class="term">br</i> tag and returns the modified text.</p></dd>
<dt><a name="42"><b class="cmd">::html::openTag</b> <i class="arg">tag</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Push <i class="arg">tag</i> onto a stack and generate the opening tag for
<i class="arg">tag</i>. Use <b class="cmd">::html::closeTag</b> to pop the tag from the
stack. The second argument provides any tag arguments, as a
list whose elements are formatted to be in the form
"<b class="variable">key</b>=<b class="const">value</b>".</p></dd>
<dt><a name="43"><b class="cmd">::html::paramRow</b> <i class="arg">list</i> <span class="opt">?<i class="arg">rparam</i>?</span> <span class="opt">?<i class="arg">cparam</i>?</span></a></dt>
<dd><p>Generate a table row, including <i class="term">tr</i> and <i class="term">td</i> tags. Each value in
<i class="arg">list</i> is placed into its own table cell. This uses
<b class="cmd">::html::cell</b>. The value of <i class="arg">rparam</i> is used as parameter for
the <i class="term">tr</i> tag. The value of <i class="arg">cparam</i> is passed to <b class="cmd">::html::cell</b>
as parameter for the <i class="term">td</i> tags.</p></dd>
<dt><a name="44"><b class="cmd">::html::passwordInput</b> <span class="opt">?<i class="arg">name</i>?</span></a></dt>
<dd><p>Generate an <i class="term">input</i> tag of type <i class="term"><a href="../../../../index.html#password">password</a></i>. The <i class="arg">name</i> defaults to
"password".</p></dd>
<dt><a name="45"><b class="cmd">::html::passwordInputRow</b> <i class="arg">label</i> <span class="opt">?<i class="arg">name</i>?</span></a></dt>
<dd><p>Format a table row containing a label and an <i class="term">input</i> tag of type
<i class="term"><a href="../../../../index.html#password">password</a></i>. The <i class="arg">name</i> defaults to "password".</p></dd>
<dt><a name="46"><b class="cmd">::html::quoteFormValue</b> <i class="arg">value</i></a></dt>
<dd><p>Quote special characters in <i class="arg">value</i> by replacing them with HTML
entities for quotes, ampersand, and angle brackets.</p></dd>
<dt><a name="47"><b class="cmd">::html::radioSet</b> <i class="arg">key sep list</i></a></dt>
<dd><p>Generate a set of <i class="term">input</i> tags of type <i class="term">radio</i> and an associated text
label. All the radio buttons share the same <i class="arg">key</i> for their name.
The <i class="arg">sep</i> is text used to separate the elements. The <i class="arg">list</i>
is a Tcl-style label, value list.</p></dd>
<dt><a name="48"><b class="cmd">::html::radioValue</b> <i class="arg">name value</i></a></dt>
<dd><p>Generate the "name=<i class="arg">name</i> value=<i class="arg">value</i>" for a <i class="term">radio</i> form
element. If the CGI variable <i class="arg">name</i> has the value <i class="arg">value</i>,
then SELECTED is added to the return value.</p></dd>
<dt><a name="49"><b class="cmd">::html::refresh</b> <i class="arg">seconds url</i></a></dt>
<dd><p>Set up a refresh <i class="term">meta</i> tag. Call this before <b class="cmd">::html::head</b> and the
HEAD section will contain a <i class="term">meta</i> tag that causes the document to
refresh in <i class="arg">seconds</i> seconds. The <i class="arg">url</i> is optional. If
specified, it specifies a new page to load after the refresh interval.</p></dd>
<dt><a name="50"><b class="cmd">::html::row</b> <i class="arg">args</i></a></dt>
<dd><p>Generate a table row, including <i class="term">tr</i> and <i class="term">td</i> tags. Each value in
<i class="arg">args</i> is place into its own table cell. This uses
<b class="cmd">::html::cell</b>. Ignores any default information set up via
<b class="cmd">::html::init</b>.</p></dd>
<dt><a name="51"><b class="cmd">::html::select</b> <i class="arg">name param choices</i> <span class="opt">?<i class="arg">current</i>?</span></a></dt>
<dd><p>Generate a <i class="term">select</i> form element and nested <i class="term">option</i> tags. The <i class="arg">name</i>
and <i class="arg">param</i> are used to generate the <i class="term">select</i> tag. The <i class="arg">choices</i>
list is a Tcl-style name, value list.</p></dd>
<dt><a name="52"><b class="cmd">::html::selectPlain</b> <i class="arg">name param choices</i> <span class="opt">?<i class="arg">current</i>?</span></a></dt>
<dd><p>Like <b class="cmd">::html::select</b> except that <i class="arg">choices</i> is a Tcl list of
values used for the <i class="term">option</i> tags. The label and the value for each
<i class="term">option</i> are the same.</p></dd>
<dt><a name="53"><b class="cmd">::html::set</b> <i class="arg">var val</i></a></dt>
<dd><p>This procedure is similar to the built-in Tcl <b class="cmd"><a href="../../../../index.html#set">set</a></b> command. The
main difference is that it returns "" so it can be called from an HTML
template file without appending unwanted results. The other
difference is that it must take two arguments.</p></dd>
<dt><a name="54"><b class="cmd">::html::submit</b> <i class="arg">label</i> <span class="opt">?<i class="arg">name</i>?</span></a></dt>
<dd><p>Generate an <i class="term">input</i> tag of type <i class="term">submit</i>. <i class="arg">name</i> defaults to "submit".</p></dd>
<dt><a name="55"><b class="cmd">::html::tableFromArray</b> <i class="arg">arrname</i> <span class="opt">?<i class="arg">param</i>?</span> <span class="opt">?<i class="arg">pat</i>?</span></a></dt>
<dd><p>Generate a two-column <i class="term"><a href="../../../../index.html#table">table</a></i> and nested rows to display a Tcl array. The
table gets a heading that matches the array name, and each generated row
contains a name, value pair. The array names are sorted (<b class="cmd">lsort</b> without
special options). The argument <i class="arg">param</i> is for the <i class="term"><a href="../../../../index.html#table">table</a></i> tag and has
to contain a pre-formatted string. The <i class="arg">pat</i> is a <b class="cmd">string match</b>
pattern used to select the array elements to show in the table. It defaults to
<b class="const">*</b>, i.e. the whole array is shown.</p></dd>
<dt><a name="56"><b class="cmd">::html::tableFromList</b> <i class="arg">querylist</i> <span class="opt">?<i class="arg">param</i>?</span></a></dt>
<dd><p>Generate a two-column <i class="term"><a href="../../../../index.html#table">table</a></i> and nested rows to display <i class="arg">querylist</i>,
which is a Tcl dictionary. Each generated row contains a name, value pair. The
information is shown in the same order as specified in the dictionary. The
argument <i class="arg">param</i> is for the <i class="term"><a href="../../../../index.html#table">table</a></i> tag and has to contain a
pre-formatted string.</p></dd>
<dt><a name="57"><b class="cmd">::html::textarea</b> <i class="arg">name</i> <span class="opt">?<i class="arg">param</i>?</span> <span class="opt">?<i class="arg">current</i>?</span></a></dt>
<dd><p>Generate a <i class="term">textarea</i> tag wrapped around its current values.</p></dd>
<dt><a name="58"><b class="cmd">::html::textInput</b> <i class="arg">name value args</i></a></dt>
<dd><p>Generate an <i class="term">input</i> form tag with type <i class="term"><a href="../../../../index.html#text">text</a></i>. This uses
<b class="cmd">::html::formValue</b>. The args is any additional tag attributes
you want to put into the <i class="term">input</i> tag.</p></dd>
<dt><a name="59"><b class="cmd">::html::textInputRow</b> <i class="arg">label name value args</i></a></dt>
<dd><p>Generate an <i class="term">input</i> form tag with type <i class="term"><a href="../../../../index.html#text">text</a></i> formatted into a table row
with an associated label. The args is any additional tag attributes
you want to put into the <i class="term">input</i> tag.</p></dd>
<dt><a name="60"><b class="cmd">::html::varEmpty</b> <i class="arg">name</i></a></dt>
<dd><p>This returns 1 if the named variable either does not exist or has the
empty string for its value.</p></dd>
<dt><a name="61"><b class="cmd">::html::while</b> <i class="arg">test body</i></a></dt>
<dd><p>This procedure is similar to the built-in Tcl <b class="cmd">while</b> control
structure. Rather than evaluating the body, it returns the subst'ed
<i class="arg">body</i>. Each iteration of the loop causes another string to be
concatenated to the result value.</p></dd>
<dt><a name="62"><b class="cmd">::html::doctype</b> <i class="arg">id</i></a></dt>
<dd><p>This procedure can be used to build the standard DOCTYPE
declaration string. It will return the standard declaration
string for the id, or throw an error if the id is not known.
The following id's are defined:</p>
<ol class="doctools_enumerated">
<li><p>HTML32</p></li>
<li><p>HTML40</p></li>
<li><p>HTML40T</p></li>
<li><p>HTML40F</p></li>
<li><p>HTML401</p></li>
<li><p>HTML401T</p></li>
<li><p>HTML401F</p></li>
<li><p>XHTML10S</p></li>
<li><p>XHTML10T</p></li>
<li><p>XHTML10F</p></li>
<li><p>XHTML11</p></li>
<li><p>XHTMLB</p></li>
</ol></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>html</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../htmlparse/htmlparse.html">htmlparse</a>, <a href="../ncgi/ncgi.html">ncgi</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checkbox">checkbox</a>, <a href="../../../../index.html#checkbutton">checkbutton</a>, <a href="../../../../index.html#form">form</a>, <a href="../../../../index.html#html">html</a>, <a href="../../../../index.html#radiobutton">radiobutton</a>, <a href="../../../../index.html#table">table</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>CGI programming</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/htmlparse/htmlparse.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
|
<div class='fossil-doc' data-title='htmlparse - HTML Parser'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">htmlparse(n) 1.2.2 tcllib "HTML Parser"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>htmlparse - Procedures to parse HTML strings</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::stack 1.3</b></li>
<li>package require <b class="pkgname">cmdline 1.1</b></li>
<li>package require <b class="pkgname">htmlparse <span class="opt">?1.2.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::htmlparse::parse</b> <span class="opt">?-cmd <i class="arg">cmd</i>?</span> <span class="opt">?-vroot <i class="arg">tag</i>?</span> <span class="opt">?-split <i class="arg">n</i>?</span> <span class="opt">?-incvar <i class="arg">var</i>?</span> <span class="opt">?-queue <i class="arg">q</i>?</span> <i class="arg">html</i></a></li>
<li><a href="#2"><b class="cmd">::htmlparse::debugCallback</b> <span class="opt">?<i class="arg">clientdata</i>?</span> <i class="arg">tag slash param textBehindTheTag</i></a></li>
<li><a href="#3"><b class="cmd">::htmlparse::mapEscapes</b> <i class="arg">html</i></a></li>
<li><a href="#4"><b class="cmd">::htmlparse::2tree</b> <i class="arg">html tree</i></a></li>
<li><a href="#5"><b class="cmd">::htmlparse::removeVisualFluff</b> <i class="arg">tree</i></a></li>
<li><a href="#6"><b class="cmd">::htmlparse::removeFormDefs</b> <i class="arg">tree</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">htmlparse</b> package provides commands that allow libraries
and applications to parse HTML in a string into a representation of
their choice.</p>
<p>The following commands are available:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::htmlparse::parse</b> <span class="opt">?-cmd <i class="arg">cmd</i>?</span> <span class="opt">?-vroot <i class="arg">tag</i>?</span> <span class="opt">?-split <i class="arg">n</i>?</span> <span class="opt">?-incvar <i class="arg">var</i>?</span> <span class="opt">?-queue <i class="arg">q</i>?</span> <i class="arg">html</i></a></dt>
<dd><p>This command is the basic parser for HTML. It takes an HTML string,
parses it and invokes a command prefix for every tag encountered. It
is not necessary for the HTML to be valid for this parser to
function. It is the responsibility of the command invoked for every
tag to check this. Another responsibility of the invoked command is
the handling of tag attributes and character entities (escaped
characters). The parser provides the un-interpreted tag attributes to
the invoked command to aid in the former, and the package at large
provides a helper command, <b class="cmd">::htmlparse::mapEscapes</b>, to aid in
the handling of the latter. The parser <em>does</em> ignore leading
DOCTYPE declarations and all valid HTML comments it encounters.</p>
<p>All information beyond the HTML string itself is specified via
options, these are explained below.</p>
<p>To help understand the options, some more background information about
the parser.</p>
<p>It is capable of detecting incomplete tags in the HTML string given to
it. Under normal circumstances this will cause the parser to throw an
error, but if the option <i class="arg">-incvar</i> is used to specify a global (or
namespace) variable, the parser will store the incomplete part of the
input into this variable instead. This will aid greatly in the
handling of incrementally arriving HTML, as the parser will handle
whatever it can and defer the handling of the incomplete part until
more data has arrived.</p>
<p>Another feature of the parser are its two possible modes of
operation. The normal mode is activated if the option <i class="arg">-queue</i> is
not present on the command line invoking the parser. If it is present,
the parser will go into the incremental mode instead.</p>
<p>The main difference is that a parser in normal mode will immediately
invoke the command prefix for each tag it encounters. In incremental
mode however the parser will generate a number of scripts which invoke
the command prefix for groups of tags in the HTML string and then
store these scripts in the specified queue. It is then the
responsibility of the caller of the parser to ensure the execution of
the scripts in the queue.</p>
<p><em>Note</em>: The queue object given to the parser has to provide the
same interface as the queue defined in tcllib -> struct. This means,
for example, that all queues created via that tcllib module can be
immediately used here. Still, the queue doesn't have to come from
tcllib -> struct as long as the same interface is provided.</p>
<p>In both modes the parser will return an empty string to the caller.</p>
<p>The <i class="arg">-split</i> option may be given to a parser in incremental mode to
specify the size of the groups it creates. In other words, -split 5
means that each of the generated scripts will invoke the command
prefix for 5 consecutive tags in the HTML string. A parser in normal
mode will ignore this option and its value.</p>
<p>The option <i class="arg">-vroot</i> specifies a virtual root tag. A parser in
normal mode will invoke the command prefix for it immediately before
and after it processes the tags in the HTML, thus simulating that the
HTML string is enclosed in a <vroot> </vroot> combination. In
incremental mode however the parser is unable to provide the closing
virtual root as it never knows when the input is complete. In this
case the first script generated by each invocation of the parser will
contain an invocation of the command prefix for the virtual root as
its first command.
The following options are available:</p>
<dl class="doctools_definitions">
<dt><b class="option">-cmd</b> <i class="arg">cmd</i></dt>
<dd><p>The command prefix to invoke for every tag in the HTML
string. Defaults to <i class="arg">::htmlparse::debugCallback</i>.</p></dd>
<dt><b class="option">-vroot</b> <i class="arg">tag</i></dt>
<dd><p>The virtual root tag to add around the HTML in normal mode. In
incremental mode it is the first tag in each chunk processed by the
parser, but there will be no closing tags. Defaults to
<i class="arg">hmstart</i>.</p></dd>
<dt><b class="option">-split</b> <i class="arg">n</i></dt>
<dd><p>The size of the groups produced by an incremental mode parser. Ignored
when in normal mode. Defaults to 10. Values <= 0 are not allowed.</p></dd>
<dt><b class="option">-incvar</b> <i class="arg">var</i></dt>
<dd><p>The name of the variable where to store any incomplete HTML into. This
makes most sense for the incremental mode. The parser will throw an
error if it sees incomplete HTML and has no place to store it to. This
makes sense for the normal mode. Only incomplete tags are detected,
not missing tags. Optional, defaults to 'no variable'.</p></dd>
</dl>
<dl class="doctools_definitions">
<dt><em>Interface to the command prefix</em></dt>
<dd><p>In normal mode the parser will invoke the command prefix with four
arguments appended. See <b class="cmd">::htmlparse::debugCallback</b> for a
description.</p>
<p>In incremental mode, however, the generated scripts will invoke the
command prefix with five arguments appended. The last four of these
are the same which were mentioned above. The first is a placeholder
string (<b class="const">@win@</b>) for a clientdata value to be supplied later
during the actual execution of the generated scripts. This could be a
tk window path, for example. This allows the user of this package to
preprocess HTML strings without committing them to a specific window,
object, whatever during parsing. This connection can be made
later. This also means that it is possible to cache preprocessed
HTML. Of course, nothing prevents the user of the parser from
replacing the placeholder with an empty string.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::htmlparse::debugCallback</b> <span class="opt">?<i class="arg">clientdata</i>?</span> <i class="arg">tag slash param textBehindTheTag</i></a></dt>
<dd><p>This command is the standard callback used by the parser in
<b class="cmd">::htmlparse::parse</b> if none was specified by the user. It simply
dumps its arguments to stdout. This callback can be used for both
normal and incremental mode of the calling parser. In other words, it
accepts four or five arguments. The last four arguments are described
below. The optional fifth argument contains the clientdata value
passed to the callback by a parser in incremental mode. All callbacks
have to follow the signature of this command in the last four
arguments, and callbacks used in incremental parsing have to follow
this signature in the last five arguments.</p>
<p>The first argument, <i class="arg">clientdata</i>, is optional and present only if
this command is invoked by a parser in incremental mode. It contains
whatever the user of this package wishes.</p>
<p>The second argument, <i class="arg">tag</i>, contains the name of the tag which is
currently processed by the parser.</p>
<p>The third argument, <i class="arg">slash</i>, is either empty or contains a slash
character. It allows the callback to distinguish between opening
(slash is empty) and closing tags (slash contains a slash character).</p>
<p>The fourth argument, <i class="arg">param</i>, contains the un-interpreted list of
parameters to the tag.</p>
<p>The fifth and last argument, <i class="arg">textBehindTheTag</i>, contains the text
found by the parser behind the tag named in <i class="arg">tag</i>.</p></dd>
<dt><a name="3"><b class="cmd">::htmlparse::mapEscapes</b> <i class="arg">html</i></a></dt>
<dd><p>This command takes a HTML string, substitutes all escape sequences
with their actual characters and then returns the resulting string.
HTML strings which do not contain escape sequences are returned
unchanged.</p></dd>
<dt><a name="4"><b class="cmd">::htmlparse::2tree</b> <i class="arg">html tree</i></a></dt>
<dd><p>This command is a wrapper around <b class="cmd">::htmlparse::parse</b> which takes
an HTML string (in <i class="arg">html</i>) and converts it into a tree containing
the logical structure of the parsed document. The name of the tree is
given to the command as its second argument (<i class="arg">tree</i>). The command
does <b class="cmd">not</b> generate the tree by itself but expects that the caller
provided it with an existing and empty tree. It also expects that the
specified tree object follows the same interface as the tree object in
tcllib -> struct. It doesn't have to be from tcllib -> struct, but it
must provide the same interface.</p>
<p>The internal callback does some basic checking of HTML validity and
tries to recover from the most basic errors. The command returns the
contents of its second argument. Side effects are the creation and
manipulation of a tree object.</p>
<p>Each node in the generated tree represent one tag in the input. The
name of the tag is stored in the attribute <em>type</em> of the
node. Any html attributes coming with the tag are stored unmodified in
the attribute <em>data</em> of the tag. In other words, the command does
<em>not</em> parse html attributes into their names and values.</p>
<p>If a tag contains text its node will have children of type
<em>PCDATA</em> containing this text. The text will be stored in the
attribute <em>data</em> of these children.</p></dd>
<dt><a name="5"><b class="cmd">::htmlparse::removeVisualFluff</b> <i class="arg">tree</i></a></dt>
<dd><p>This command walks a tree as generated by <b class="cmd">::htmlparse::2tree</b> and
removes all the nodes which represent visual tags and not structural
ones. The purpose of the command is to make the tree easier to
navigate without getting bogged down in visual information not
relevant to the search. Its only argument is the name of the tree to
cut down.</p></dd>
<dt><a name="6"><b class="cmd">::htmlparse::removeFormDefs</b> <i class="arg">tree</i></a></dt>
<dd><p>Like <b class="cmd">::htmlparse::removeVisualFluff</b> this command is here to cut
down on the size of the tree as generated by
<b class="cmd">::htmlparse::2tree</b>. It removes all nodes representing forms and
form elements. Its only argument is the name of the tree to cut down.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>htmlparse</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../struct/struct_tree.html">struct::tree</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#html">html</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#queue">queue</a>, <a href="../../../../index.html#tree">tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/http/autoproxy.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
<div class='fossil-doc' data-title='autoproxy - HTTP protocol helper modules'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">autoproxy(n) 1.7 tcllib "HTTP protocol helper modules"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>autoproxy - Automatic HTTP proxy usage and authentication</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section3">COMMANDS</a></li>
<li class="doctools_section"><a href="#section4">OPTIONS</a></li>
<li class="doctools_section"><a href="#section5">Basic Authentication</a></li>
<li class="doctools_section"><a href="#section6">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section7">REFERENCES</a></li>
<li class="doctools_section"><a href="#section8">BUGS</a></li>
<li class="doctools_section"><a href="#section9">AUTHORS</a></li>
<li class="doctools_section"><a href="#section10">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">http <span class="opt">?2.0?</span></b></li>
<li>package require <b class="pkgname">autoproxy <span class="opt">?1.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::autoproxy::init</b></a></li>
<li><a href="#2"><b class="cmd">::autoproxy::cget</b> <i class="arg">-option</i></a></li>
<li><a href="#3"><b class="cmd">::autoproxy::configure</b> <span class="opt">?-option <i class="arg">value</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::autoproxy::tls_connect</b> <i class="arg">args</i></a></li>
<li><a href="#5"><b class="cmd">::autoproxy::tunnel_connect</b> <i class="arg">args</i></a></li>
<li><a href="#6"><b class="cmd">::autoproxy::tls_socket</b> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package attempts to automate the use of HTTP proxy servers in Tcl
HTTP client code. It tries to initialize the web access settings from
system standard locations and can be configured to negotiate
authentication with the proxy if required.</p>
<p>On Unix the standard for identifying the local HTTP proxy server
seems to be to use the environment variable http_proxy or ftp_proxy and
no_proxy to list those domains to be excluded from proxying.
On Windows we can retrieve the Internet Settings values from the registry
to obtain pretty much the same information.
With this information we can setup a suitable filter procedure for the
Tcl http package and arrange for automatic use of the proxy.</p>
<p>There seem to be a number of ways that the http_proxy environment
variable may be set up. Either a plain host:port or more commonly a
URL and sometimes the URL may contain authentication parameters or
these may be requested from the user or provided via http_proxy_user
and http_proxy_pass. This package attempts to deal with all these
schemes. It will do it's best to get the required parameters from the
environment or registry and if it fails can be reconfigured.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TLS Security Considerations</a></h2>
<p><em>Note</em> This section only applies if TLS support is provided
by the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package.
It does not apply when <b class="package">autoproxy</b> was configured to use some
other package which can provide the same (i.e <b class="package">twapi</b>), via
the <b class="option">-tls_package</b> configuration option.</p>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::autoproxy::init</b></a></dt>
<dd><p>Initialize the autoproxy package from system resources. Under unix
this means we look for environment variables. Under windows we look
for the same environment variables but also look at the registry
settings used by Internet Explorer.</p></dd>
<dt><a name="2"><b class="cmd">::autoproxy::cget</b> <i class="arg">-option</i></a></dt>
<dd><p>Retrieve individual package configuration options. See <span class="sectref"><a href="#section4">OPTIONS</a></span>.</p></dd>
<dt><a name="3"><b class="cmd">::autoproxy::configure</b> <span class="opt">?-option <i class="arg">value</i>?</span></a></dt>
<dd><p>Configure the autoproxy package. Calling <b class="cmd">configure</b> with no
options will return a list of all option names and values.
See <span class="sectref"><a href="#section4">OPTIONS</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::autoproxy::tls_connect</b> <i class="arg">args</i></a></dt>
<dd><p>Connect to a secure socket through a proxy. HTTP proxy servers permit
the use of the CONNECT HTTP command to open a link through the proxy
to the target machine. This function hides the details. For use with
the http package see <b class="cmd">tls_socket</b>.</p>
<p>The <i class="arg">args</i> list may contain any of the options
supported by the specific TLS package that is in use but
must end with the host and port as the last two items.</p></dd>
<dt><a name="5"><b class="cmd">::autoproxy::tunnel_connect</b> <i class="arg">args</i></a></dt>
<dd><p>Connect to a target host throught a proxy. This uses the same CONNECT
HTTP command as the <b class="cmd">tls_connect</b> but does not promote the link
security once the connection is established.</p>
<p>The <i class="arg">args</i> list may contain any of the options
supported by the specific TLS package that is in use but
must end with the host and port as the last two items.</p>
<p>Note that many proxy servers will permit CONNECT calls to a limited
set of ports - typically only port 443 (the secure HTTP port).</p></dd>
<dt><a name="6"><b class="cmd">::autoproxy::tls_socket</b> <i class="arg">args</i></a></dt>
<dd><p>This function is to be used to register a proxy-aware secure socket
handler for the https protocol. It may only be used with the Tcl http
package and should be registered using the http::register command (see
the examples below). The job of actually creating the tunnelled
connection is done by the tls_connect command and this may be used
when not registering with the http package.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">OPTIONS</a></h2>
<dl class="doctools_options">
<dt><b class="option">-host</b> hostname</dt>
<dd></dd>
<dt><b class="option">-proxy_host</b> hostname</dt>
<dd><p>Set the proxy hostname. This is normally set up by <b class="cmd">init</b> but may
be configured here as well.</p></dd>
<dt><b class="option">-port</b> number</dt>
<dd></dd>
<dt><b class="option">-proxy_port</b> number</dt>
<dd><p>Set the proxy port number. This is normally set up by <b class="cmd">init</b>.
e.g. <b class="cmd">configure</b> <b class="option">-port</b> <i class="arg">3128</i></p></dd>
<dt><b class="option">-no_proxy</b> list</dt>
<dd><p>You may manipulate the <b class="option">no_proxy</b> list that was setup by
<b class="cmd">init</b>. The value of this option is a tcl list of
strings that are matched against the http request host using the tcl
<b class="cmd">string match</b> command. Therefore glob patterns are permitted.
For instance, <b class="cmd">configure</b> <b class="option">-no_proxy</b> <i class="arg">*.localdomain</i></p></dd>
<dt><b class="option">-authProc</b> procedure</dt>
<dd><p>This option may be used to set an application defined procedure to be
called when <b class="cmd">configure</b> <b class="option">-basic</b> is called with either no or
insufficient authentication details. This can be used to present a
dialog to the user to request the additional information.</p></dd>
<dt><b class="option">-basic</b></dt>
<dd><p>Following options are for configuring the Basic authentication
scheme parameters. See <span class="sectref"><a href="#section5">Basic Authentication</a></span>.
To unset the proxy authentication information retained from a previous
call of this function either "--" or no additional parameters can be
supplied. This will remove the existing authentication information.</p></dd>
<dt><b class="option">-tls_package</b> packagename</dt>
<dd><p>This option may be used to configure the Tcl package to use for
TLS support. Valid package names are <b class="const">tls</b> (default)
and <b class="const">twapi</b>.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Basic Authentication</a></h2>
<p>Basic is the simplest and most commonly use HTTP proxy authentication
scheme. It is described in (1 section 11) and also in (2). It offers
no privacy whatsoever and its use should be discouraged in favour of
more secure alternatives like Digest. To perform Basic authentication
the client base64 encodes the username and plaintext password
separated by a colon. This encoded text is prefixed with the word
"Basic" and a space.</p>
<p>The following options exists for this scheme:</p>
<dl class="doctools_options">
<dt><b class="option">-username</b> name</dt>
<dd><p>The username required to authenticate with the configured proxy.</p></dd>
<dt><b class="option">-password</b> password</dt>
<dd><p>The password required for the username specified.</p></dd>
<dt><b class="option">-realm</b> realm</dt>
<dd><p>This option is not used by this package but may be used in requesting
authentication details from the user.</p></dd>
<dt><b class="option">--</b></dt>
<dd><p>The end-of-options indicator may be used alone to unset any
authentication details currently enabled.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">EXAMPLES</a></h2>
<pre class="doctools_example">
package require autoproxy
autoproxy::init
autoproxy::configure -basic -username ME -password SEKRET
set tok [http::geturl http://wiki.tcl.tk/]
http::data $tok
</pre>
<pre class="doctools_example">
package require http
package require tls
package require autoproxy
autoproxy::init
http::register https 443 autoproxy::tls_socket
set tok [http::geturl https://www.example.com/]
</pre>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Berners-Lee, T., Fielding R. and Frystyk, H.
"Hypertext Transfer Protocol -- HTTP/1.0",
RFC 1945, May 1996,
(<a href="http://www.rfc-editor.org/rfc/rfc1945.txt">http://www.rfc-editor.org/rfc/rfc1945.txt</a>)</p></li>
<li><p>Franks, J. et al.
"HTTP Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999
(<a href="http://www.rfc-editor.org/rfc/rfc2617.txt">http://www.rfc-editor.org/rfc/rfc2617.txt</a>)</p></li>
</ol>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">BUGS</a></h2>
<p>At this time only Basic authentication (1) (2) is supported. It is
planned to add support for Digest (2) and NTLM in the future.</p>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section10" class="doctools_section"><h2><a name="section10">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>http :: autoproxy</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>http(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#authentication">authentication</a>, <a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#proxy">proxy</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/httpd/httpd.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
|
<div class='fossil-doc' data-title='tool - Tcl Web Server'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tool(n) 4.1.1 tcllib "Tcl Web Server"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tool - A TclOO and coroutine based web server</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Minimal Example</a></li>
<li class="doctools_section"><a href="#section3">Class ::httpd::server</a></li>
<li class="doctools_section"><a href="#section4">Class ::httpd::reply</a></li>
<li class="doctools_section"><a href="#section5">Reply Method Ensembles</a></li>
<li class="doctools_section"><a href="#section6">Reply Method Ensemble: http_info</a></li>
<li class="doctools_section"><a href="#section7">Reply Method Ensemble: request</a></li>
<li class="doctools_section"><a href="#section8">Reply Method Ensemble: reply</a></li>
<li class="doctools_section"><a href="#section9">Reply Methods</a></li>
<li class="doctools_section"><a href="#section10">Class ::httpd::content</a></li>
<li class="doctools_section"><a href="#section11">Class ::httpd::content.cgi</a></li>
<li class="doctools_section"><a href="#section12">Class ::httpd::content.file</a></li>
<li class="doctools_section"><a href="#section13">Class ::httpd::content.proxy</a></li>
<li class="doctools_section"><a href="#section14">Class ::httpd::content.scgi</a></li>
<li class="doctools_section"><a href="#section15">Class ::httpd::content.websocket</a></li>
<li class="doctools_section"><a href="#section16">SCGI Server Functions</a></li>
<li class="doctools_section"><a href="#section17">Class ::httpd::reply.scgi</a></li>
<li class="doctools_section"><a href="#section18">Class ::httpd::server.scgi</a></li>
<li class="doctools_section"><a href="#section19">AUTHORS</a></li>
<li class="doctools_section"><a href="#section20">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">httpd <span class="opt">?4.1.1?</span></b></li>
<li>package require <b class="pkgname">sha1</b></li>
<li>package require <b class="pkgname">dicttool</b></li>
<li>package require <b class="pkgname">oo::meta</b></li>
<li>package require <b class="pkgname">oo::dialect</b></li>
<li>package require <b class="pkgname">tool</b></li>
<li>package require <b class="pkgname">coroutine</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">fileutil::magic::filetype</b></li>
<li>package require <b class="pkgname">websocket</b></li>
<li>package require <b class="pkgname">mime</b></li>
<li>package require <b class="pkgname">cron</b></li>
<li>package require <b class="pkgname">uri</b></li>
<li>package require <b class="pkgname">Markdown</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1">constructor ?port <span class="opt">?port?</span>? ?myaddr <span class="opt">?ipaddr?</span>|all? ?server_string <span class="opt">?string?</span>? ?server_name <span class="opt">?string?</span>?</a></li>
<li><a href="#2">method <b class="cmd">add_uri</b> <i class="arg">pattern</i> <i class="arg">dict</i></a></li>
<li><a href="#3">method <b class="cmd">connect</b> <i class="arg">sock</i> <i class="arg">ip</i> <i class="arg">port</i></a></li>
<li><a href="#4">method <b class="cmd">Connect</b> <i class="arg">uuid</i> <i class="arg">sock</i> <i class="arg">ip</i></a></li>
<li><a href="#5">method <b class="cmd"><a href="../counter/counter.html">counter</a></b> <i class="arg">which</i></a></li>
<li><a href="#6">method <b class="cmd">CheckTimeout</b></a></li>
<li><a href="#7">method <b class="cmd">dispatch</b> <i class="arg">header_dict</i></a></li>
<li><a href="#8">method <b class="cmd"><a href="../log/log.html">log</a></b> <i class="arg">args</i></a></li>
<li><a href="#9">method <b class="cmd">port_listening</b></a></li>
<li><a href="#10">method <b class="cmd">PrefixNormalize</b> <i class="arg">prefix</i></a></li>
<li><a href="#11">method <b class="cmd">start</b></a></li>
<li><a href="#12">method <b class="cmd">stop</b></a></li>
<li><a href="#13">method <b class="cmd">template</b> <i class="arg">page</i></a></li>
<li><a href="#14">method <b class="cmd">TemplateSearch</b> <i class="arg">page</i></a></li>
<li><a href="#15">method <b class="cmd">Validate_Connection</b> <i class="arg">sock</i> <i class="arg">ip</i></a></li>
<li><a href="#16">method <b class="cmd">ENSEMBLE::add</b> <i class="arg">field</i> <i class="arg">element</i></a></li>
<li><a href="#17">method <b class="cmd">ENSEMBLE::dump</b></a></li>
<li><a href="#18">method <b class="cmd">ENSEMBLE::get</b> <i class="arg">field</i></a></li>
<li><a href="#19">method <b class="cmd">ENSEMBLE::reset</b></a></li>
<li><a href="#20">method <b class="cmd">ENSEMBLE::remove</b> <i class="arg">field</i> <i class="arg">element</i></a></li>
<li><a href="#21">method <b class="cmd">ENSEMBLE::replace</b> <i class="arg">keyvaluelist</i></a></li>
<li><a href="#22">method <b class="cmd">ENSEMBLE::reset</b></a></li>
<li><a href="#23">method <b class="cmd">ENSEMBLE::set</b> <i class="arg">field</i> <i class="arg">value</i></a></li>
<li><a href="#24">method <b class="cmd">http_info::netstring</b></a></li>
<li><a href="#25">method <b class="cmd">request::parse</b> <i class="arg">string</i></a></li>
<li><a href="#26">method <b class="cmd">reply::output</b></a></li>
<li><a href="#27">method <b class="cmd">close</b></a></li>
<li><a href="#28">method <b class="cmd">HttpHeaders</b> <i class="arg">sock</i> <i class="arg">?debug?</i></a></li>
<li><a href="#29">method <b class="cmd">dispatch</b> <i class="arg">newsock</i> <i class="arg">datastate</i></a></li>
<li><a href="#30">method <b class="cmd"><a href="../../../../index.html#error">error</a></b> <i class="arg">code</i> <i class="arg">?message?</i> <i class="arg">?errorInfo?</i></a></li>
<li><a href="#31">method <b class="cmd">content</b></a></li>
<li><a href="#32">method <b class="cmd">EncodeStatus</b> <i class="arg">status</i></a></li>
<li><a href="#33">method FormData</a></li>
<li><a href="#34">method MimeParse <i class="arg">mimetext</i></a></li>
<li><a href="#35">method <b class="cmd">DoOutput</b></a></li>
<li><a href="#36">method PostData <i class="arg">length</i></a></li>
<li><a href="#37">method <b class="cmd">puts</b> <i class="arg">string</i></a></li>
<li><a href="#38">method <b class="cmd">reset</b></a></li>
<li><a href="#39">method <b class="cmd">timeOutCheck</b></a></li>
<li><a href="#40">method <b class="cmd"><a href="../../../../index.html#timestamp">timestamp</a></b></a></li>
<li><a href="#41">method <b class="cmd">TransferComplete</b> <i class="arg">args</i></a></li>
<li><a href="#42">method <b class="cmd">Url_Decode</b> <i class="arg">string</i></a></li>
<li><a href="#43">method cgi_info</a></li>
<li><a href="#44">option <b class="cmd">path</b></a></li>
<li><a href="#45">option <b class="cmd"><a href="../../../../index.html#prefix">prefix</a></b></a></li>
<li><a href="#46">method proxy_info</a></li>
<li><a href="#47">method scgi_info</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This module implements a web server, suitable for embedding in an
application. The server is object oriented, and contains all of the
fundamentals needed for a full service website.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Minimal Example</a></h2>
<p>Starting a web service requires starting a class of type
<b class="cmd">httpd::server</b>, and providing that server with one or more URIs
to service, and <b class="cmd">httpd::reply</b> derived classes to generate them.</p>
<pre class="doctools_example">
tool::define ::reply.hello {
method content {} {
my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
my puts "<h1>Hello World!</h1>"
my puts </BODY></HTML>
}
}
::docserver::server create HTTPD port 8015 myaddr 127.0.0.1
HTTPD add_uri /* [list mixin reply.hello]
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Class ::httpd::server</a></h2>
<p>This class is the root object of the webserver. It is responsible
for opening the socket and providing the initial connection negotiation.</p>
<dl class="doctools_definitions">
<dt><a name="1">constructor ?port <span class="opt">?port?</span>? ?myaddr <span class="opt">?ipaddr?</span>|all? ?server_string <span class="opt">?string?</span>? ?server_name <span class="opt">?string?</span>?</a></dt>
<dd><p>Build a new server object. <span class="opt">?port?</span> is the port to listen on</p></dd>
<dt><a name="2">method <b class="cmd">add_uri</b> <i class="arg">pattern</i> <i class="arg">dict</i></a></dt>
<dd><p>Set the hander for a URI pattern. Information given in the <i class="arg">dict</i> is stored
in the data structure the <b class="cmd">dispatch</b> method uses. If a field called
<i class="arg">mixin</i> is given, that class will be mixed into the reply object immediately
after construction.</p></dd>
<dt><a name="3">method <b class="cmd">connect</b> <i class="arg">sock</i> <i class="arg">ip</i> <i class="arg">port</i></a></dt>
<dd><p>Reply to an open socket. This method builds a coroutine to manage the remainder
of the connection. The coroutine's operations are driven by the <b class="cmd">Connect</b> method.</p></dd>
<dt><a name="4">method <b class="cmd">Connect</b> <i class="arg">uuid</i> <i class="arg">sock</i> <i class="arg">ip</i></a></dt>
<dd><p>This method reads HTTP headers, and then consults the <b class="cmd">dispatch</b> method to
determine if the request is valid, and/or what kind of reply to generate. Under
normal cases, an object of class <b class="cmd">::http::reply</b> is created.
Fields the server are looking for in particular are:
class: A class to use instead of the server's own <i class="arg">reply_class</i>
mixin: A class to be mixed into the new object after construction.
All other fields are passed along to the <b class="cmd">http_info</b> structure of the
reply object.
After the class is created and the mixin is mixed in, the server invokes the
reply objects <b class="cmd">dispatch</b> method. This action passes control of the socket to
the reply object. The reply object manages the rest of the transaction, including
closing the socket.</p></dd>
<dt><a name="5">method <b class="cmd"><a href="../counter/counter.html">counter</a></b> <i class="arg">which</i></a></dt>
<dd><p>Increment an internal counter.</p></dd>
<dt><a name="6">method <b class="cmd">CheckTimeout</b></a></dt>
<dd><p>Check open connections for a time out event.</p></dd>
<dt><a name="7">method <b class="cmd">dispatch</b> <i class="arg">header_dict</i></a></dt>
<dd><p>Given a key/value list of information, return a data structure describing how
the server should reply.</p></dd>
<dt><a name="8">method <b class="cmd"><a href="../log/log.html">log</a></b> <i class="arg">args</i></a></dt>
<dd><p>Log an event. The input for args is free form. This method is intended
to be replaced by the user, and is a noop for a stock http::server object.</p></dd>
<dt><a name="9">method <b class="cmd">port_listening</b></a></dt>
<dd><p>Return the actual port that httpd is listening on.</p></dd>
<dt><a name="10">method <b class="cmd">PrefixNormalize</b> <i class="arg">prefix</i></a></dt>
<dd><p>For the stock version, trim trailing /'s and *'s from a prefix. This
method can be replaced by the end user to perform any other transformations
needed for the application.</p></dd>
<dt><a name="11">method <b class="cmd">start</b></a></dt>
<dd><p>Open the socket listener.</p></dd>
<dt><a name="12">method <b class="cmd">stop</b></a></dt>
<dd><p>Shut off the socket listener, and destroy any pending replies.</p></dd>
<dt><a name="13">method <b class="cmd">template</b> <i class="arg">page</i></a></dt>
<dd><p>Return a template for the string <i class="arg">page</i></p></dd>
<dt><a name="14">method <b class="cmd">TemplateSearch</b> <i class="arg">page</i></a></dt>
<dd><p>Perform a search for the template that best matches <i class="arg">page</i>. This
can include local file searches, in-memory structures, or even
database lookups. The stock implementation simply looks for files
with a .tml or .html extension in the <span class="opt">?doc_root?</span> directory.</p></dd>
<dt><a name="15">method <b class="cmd">Validate_Connection</b> <i class="arg">sock</i> <i class="arg">ip</i></a></dt>
<dd><p>Given a socket and an ip address, return true if this connection should
be terminated, or false if it should be allowed to continue. The stock
implementation always returns 0. This is intended for applications to
be able to implement black lists and/or provide security based on IP
address.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Class ::httpd::reply</a></h2>
<p>A class which shephards a request through the process of generating a
reply.
The socket associated with the reply is available at all times as the <i class="arg">chan</i>
variable.
The process of generating a reply begins with an <b class="cmd">httpd::server</b> generating a
<b class="cmd">http::class</b> object, mixing in a set of behaviors and then invoking the reply
object's <b class="cmd">dispatch</b> method.
In normal operations the <b class="cmd">dispatch</b> method:</p>
<ol class="doctools_enumerated">
<li><p>Invokes the <b class="cmd">reset</b> method for the object to populate default headers.</p></li>
<li><p>Invokes the <b class="cmd">HttpHeaders</b> method to stream the MIME headers out of the socket</p></li>
<li><p>Invokes the <b class="cmd">request parse</b> method to convert the stream of MIME headers into a
dict that can be read via the <b class="cmd">request</b> method.</p></li>
<li><p>Stores the raw stream of MIME headers in the <i class="arg">rawrequest</i> variable of the object.</p></li>
<li><p>Invokes the <b class="cmd">content</b> method for the object, generating an call to the <b class="cmd"><a href="../../../../index.html#error">error</a></b>
method if an exception is raised.</p></li>
<li><p>Invokes the <b class="cmd">output</b> method for the object</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Reply Method Ensembles</a></h2>
<p>The <b class="cmd">http::reply</b> class and its derivatives maintain several variables as dictionaries
internally. Access to these dictionaries is managed through a dedicated ensemble. The
ensemble implements most of the same behaviors as the <b class="cmd"><a href="../../../../index.html#dict">dict</a></b> command.
Each ensemble implements the following methods above, beyond, or modifying standard dicts:</p>
<dl class="doctools_definitions">
<dt><a name="16">method <b class="cmd">ENSEMBLE::add</b> <i class="arg">field</i> <i class="arg">element</i></a></dt>
<dd><p>Add <i class="arg">element</i> to a list stored in <i class="arg">field</i>, but only if it is not already present om the list.</p></dd>
<dt><a name="17">method <b class="cmd">ENSEMBLE::dump</b></a></dt>
<dd><p>Return the current contents of the data structure as a key/value list.</p></dd>
<dt><a name="18">method <b class="cmd">ENSEMBLE::get</b> <i class="arg">field</i></a></dt>
<dd><p>Return the value of the field <i class="arg">field</i>, or an empty string if it does not exist.</p></dd>
<dt><a name="19">method <b class="cmd">ENSEMBLE::reset</b></a></dt>
<dd><p>Return a key/value list of the default contents for this data structure.</p></dd>
<dt><a name="20">method <b class="cmd">ENSEMBLE::remove</b> <i class="arg">field</i> <i class="arg">element</i></a></dt>
<dd><p>Remove all instances of <i class="arg">element</i> from the list stored in <i class="arg">field</i>.</p></dd>
<dt><a name="21">method <b class="cmd">ENSEMBLE::replace</b> <i class="arg">keyvaluelist</i></a></dt>
<dd><p>Replace the internal dict with the contents of <i class="arg">keyvaluelist</i></p></dd>
<dt><a name="22">method <b class="cmd">ENSEMBLE::reset</b></a></dt>
<dd><p>Replace the internal dict with the default state.</p></dd>
<dt><a name="23">method <b class="cmd">ENSEMBLE::set</b> <i class="arg">field</i> <i class="arg">value</i></a></dt>
<dd><p>Set the value of <i class="arg">field</i> to <i class="arg">value</i>.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Reply Method Ensemble: http_info</a></h2>
<p>Manages HTTP headers passed in by the server.
Ensemble Methods:</p>
<dl class="doctools_definitions">
<dt><a name="24">method <b class="cmd">http_info::netstring</b></a></dt>
<dd><p>Return the contents of this data structure as a netstring encoded block.</p></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Reply Method Ensemble: request</a></h2>
<p>Managed data from MIME headers of the request.</p>
<dl class="doctools_definitions">
<dt><a name="25">method <b class="cmd">request::parse</b> <i class="arg">string</i></a></dt>
<dd><p>Replace the contents of the data structure with information encoded in a MIME
formatted block of text (<i class="arg">string</i>).</p></dd>
</dl>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Reply Method Ensemble: reply</a></h2>
<p>Manage the headers sent in the reply.</p>
<dl class="doctools_definitions">
<dt><a name="26">method <b class="cmd">reply::output</b></a></dt>
<dd><p>Return the contents of this data structure as a MIME encoded block appropriate
for an HTTP response.</p></dd>
</dl>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">Reply Methods</a></h2>
<dl class="doctools_definitions">
<dt><a name="27">method <b class="cmd">close</b></a></dt>
<dd><p>Terminate the transaction, and close the socket.</p></dd>
<dt><a name="28">method <b class="cmd">HttpHeaders</b> <i class="arg">sock</i> <i class="arg">?debug?</i></a></dt>
<dd><p>Stream MIME headers from the socket <i class="arg">sock</i>, stopping at an empty line. Returns
the stream as a block of text.</p></dd>
<dt><a name="29">method <b class="cmd">dispatch</b> <i class="arg">newsock</i> <i class="arg">datastate</i></a></dt>
<dd><p>Take over control of the socket <i class="arg">newsock</i>, and store that as the <i class="arg">chan</i> variable
for the object. This method runs through all of the steps of reading HTTP headers, generating
content, and closing the connection. (See class writetup).</p></dd>
<dt><a name="30">method <b class="cmd"><a href="../../../../index.html#error">error</a></b> <i class="arg">code</i> <i class="arg">?message?</i> <i class="arg">?errorInfo?</i></a></dt>
<dd><p>Generate an error message of the specified <i class="arg">code</i>, and display the <i class="arg">message</i> as the
reason for the exception. <i class="arg">errorInfo</i> is passed in from calls, but how or if it should be
displayed is a prerogative of the developer.</p></dd>
<dt><a name="31">method <b class="cmd">content</b></a></dt>
<dd><p>Generate the content for the reply. This method is intended to be replaced by the mixin.
Developers have the option of streaming output to a buffer via the <b class="cmd">puts</b> method of the
reply, or simply populating the <i class="arg">reply_body</i> variable of the object.
The information returned by the <b class="cmd">content</b> method is not interpreted in any way.
If an exception is thrown (via the <b class="cmd"><a href="../../../../index.html#error">error</a></b> command in Tcl, for example) the caller will
auto-generate a 500 {Internal Error} message.
A typical implementation of <b class="cmd">content</b> look like:</p>
<pre class="doctools_example">
tool::define ::test::content.file {
superclass ::httpd::content.file
# Return a file
# Note: this is using the content.file mixin which looks for the reply_file variable
# and will auto-compute the Content-Type
method content {} {
my reset
set doc_root [my http_info get doc_root]
my variable reply_file
set reply_file [file join $doc_root index.html]
}
}
tool::define ::test::content.time {
# return the current system time
method content {} {
my variable reply_body
my reply set Content-Type text/plain
set reply_body [clock seconds]
}
}
tool::define ::test::content.echo {
method content {} {
my variable reply_body
my reply set Content-Type [my request get CONTENT_TYPE]
set reply_body [my PostData [my request get CONTENT_LENGTH]]
}
}
tool::define ::test::content.form_handler {
method content {} {
set form [my FormData]
my reply set Content-Type {text/html; charset=UTF-8}
my puts [my html header {My Dynamic Page}]
my puts "<BODY>"
my puts "You Sent<p>"
my puts "<TABLE>"
foreach {f v} $form {
my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
}
my puts "</TABLE><p>"
my puts "Send some info:<p>"
my puts "<FORM action=/[my http_info get REQUEST_PATH] method POST>"
my puts "<TABLE>"
foreach field {name rank serial_number} {
set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
if {[dict exists $form $field]} {
append line " value=\"[dict get $form $field]\"""
}
append line " /></TD></TR>"
my puts $line
}
my puts "</TABLE>"
my puts [my html footer]
}
}
</pre>
</dd>
<dt><a name="32">method <b class="cmd">EncodeStatus</b> <i class="arg">status</i></a></dt>
<dd><p>Formulate a standard HTTP status header from he string provided.</p></dd>
<dt><a name="33">method FormData</a></dt>
<dd><p>For GET requests, converts the QUERY_DATA header into a key/value list.
For POST requests, reads the Post data and converts that information to
a key/value list for application/x-www-form-urlencoded posts. For multipart
posts, it composites all of the MIME headers of the post to a singular key/value
list, and provides MIME_* information as computed by the <b class="cmd"><a href="../mime/mime.html">mime</a></b> package, including
the MIME_TOKEN, which can be fed back into the mime package to read out the contents.</p></dd>
<dt><a name="34">method MimeParse <i class="arg">mimetext</i></a></dt>
<dd><p>Converts a block of mime encoded text to a key/value list. If an exception is encountered,
the method will generate its own call to the <b class="cmd"><a href="../../../../index.html#error">error</a></b> method, and immediately invoke
the <b class="cmd">output</b> method to produce an error code and close the connection.</p></dd>
<dt><a name="35">method <b class="cmd">DoOutput</b></a></dt>
<dd><p>Generates the the HTTP reply, and streams that reply back across <i class="arg">chan</i>.</p></dd>
<dt><a name="36">method PostData <i class="arg">length</i></a></dt>
<dd><p>Stream <i class="arg">length</i> bytes from the <i class="arg">chan</i> socket, but only of the request is a
POST or PUSH. Returns an empty string otherwise.</p></dd>
<dt><a name="37">method <b class="cmd">puts</b> <i class="arg">string</i></a></dt>
<dd><p>Appends the value of <i class="arg">string</i> to the end of <i class="arg">reply_body</i>, as well as a trailing newline
character.</p></dd>
<dt><a name="38">method <b class="cmd">reset</b></a></dt>
<dd><p>Clear the contents of the <i class="arg">reply_body</i> variable, and reset all headers in the <b class="cmd">reply</b>
structure back to the defaults for this object.</p></dd>
<dt><a name="39">method <b class="cmd">timeOutCheck</b></a></dt>
<dd><p>Called from the <b class="cmd">http::server</b> object which spawned this reply. Checks to see
if too much time has elapsed while waiting for data or generating a reply, and issues
a timeout error to the request if it has, as well as destroy the object and close the
<i class="arg">chan</i> socket.</p></dd>
<dt><a name="40">method <b class="cmd"><a href="../../../../index.html#timestamp">timestamp</a></b></a></dt>
<dd><p>Return the current system time in the format:</p>
<pre class="doctools_example">%a, %d %b %Y %T %Z</pre>
</dd>
<dt><a name="41">method <b class="cmd">TransferComplete</b> <i class="arg">args</i></a></dt>
<dd><p>Intended to be invoked from <b class="cmd">chan copy</b> as a callback. This closes every channel
fed to it on the command line, and then destroys the object.</p>
<pre class="doctools_example">
###
# Output the body
###
chan configure $sock -translation binary -blocking 0 -buffering full -buffersize 4096
chan configure $chan -translation binary -blocking 0 -buffering full -buffersize 4096
if {$length} {
###
# Send any POST/PUT/etc content
###
chan copy $sock $chan -size $SIZE -command [info coroutine]
yield
}
catch {close $sock}
chan flush $chan
</pre>
</dd>
<dt><a name="42">method <b class="cmd">Url_Decode</b> <i class="arg">string</i></a></dt>
<dd><p>De-httpizes a string.</p></dd>
</dl>
</div>
<div id="section10" class="doctools_section"><h2><a name="section10">Class ::httpd::content</a></h2>
<p>The httpd module includes several ready to use implementations of content mixins
for common use cases. Options are passed in to the <b class="cmd">add_uri</b> method of the server.</p>
</div>
<div id="section11" class="doctools_section"><h2><a name="section11">Class ::httpd::content.cgi</a></h2>
<p>An implementation to relay requests to process which will accept post data
streamed in vie stdin, and sent a reply streamed to stdout.</p>
<dl class="doctools_definitions">
<dt><a name="43">method cgi_info</a></dt>
<dd><p>Mandatory method to be replaced by the end user. If needed, activates the
process to proxy, and then returns a list of three values:
<i class="arg">exec</i> - The arguments to send to exec to fire off the responding process, minus the stdin/stdout redirection.</p></dd>
</dl>
</div>
<div id="section12" class="doctools_section"><h2><a name="section12">Class ::httpd::content.file</a></h2>
<p>An implementation to deliver files from the local file system.</p>
<dl class="doctools_definitions">
<dt><a name="44">option <b class="cmd">path</b></a></dt>
<dd><p>The root directory on the local file system to be exposed via http.</p></dd>
<dt><a name="45">option <b class="cmd"><a href="../../../../index.html#prefix">prefix</a></b></a></dt>
<dd><p>The prefix of the URI portion to ignore when calculating relative file paths.</p></dd>
</dl>
</div>
<div id="section13" class="doctools_section"><h2><a name="section13">Class ::httpd::content.proxy</a></h2>
<p>An implementation to relay requests to another HTTP server, and relay
the results back across the request channel.</p>
<dl class="doctools_definitions">
<dt><a name="46">method proxy_info</a></dt>
<dd><p>Mandatory method to be replaced by the end user. If needed, activates the
process to proxy, and then returns a list of three values:
<i class="arg">proxyhost</i> - The hostname where the proxy is located
<i class="arg">proxyport</i> - The port to connect to
<i class="arg">proxyscript</i> - A pre-amble block of text to send prior to the mirrored request</p></dd>
</dl>
</div>
<div id="section14" class="doctools_section"><h2><a name="section14">Class ::httpd::content.scgi</a></h2>
<p>An implementation to relay requests to a server listening on a socket
expecting SCGI encoded requests, and relay
the results back across the request channel.</p>
<dl class="doctools_definitions">
<dt><a name="47">method scgi_info</a></dt>
<dd><p>Mandatory method to be replaced by the end user. If needed, activates the
process to proxy, and then returns a list of three values:
<i class="arg">scgihost</i> - The hostname where the scgi listener is located
<i class="arg">scgiport</i> - The port to connect to
<i class="arg">scgiscript</i> - The contents of the <i class="arg">SCRIPT_NAME</i> header to be sent</p></dd>
</dl>
</div>
<div id="section15" class="doctools_section"><h2><a name="section15">Class ::httpd::content.websocket</a></h2>
<p>A placeholder for a future implementation to manage requests that can expect to be
promoted to a Websocket. Currently it is an empty class.</p>
</div>
<div id="section16" class="doctools_section"><h2><a name="section16">SCGI Server Functions</a></h2>
<p>The HTTP module also provides an SCGI server implementation, as well as an HTTP
implementation. To use the SCGI functions, create an object of the <b class="cmd">http::server.scgi</b>
class instead of the <b class="cmd">http::server</b> class.</p>
</div>
<div id="section17" class="doctools_section"><h2><a name="section17">Class ::httpd::reply.scgi</a></h2>
<p>An modified <b class="cmd">http::reply</b> implementation that understands how to deal with
netstring encoded headers.</p>
</div>
<div id="section18" class="doctools_section"><h2><a name="section18">Class ::httpd::server.scgi</a></h2>
<p>A modified <b class="cmd">http::server</b> which is tailored to replying to request according to
the SCGI standard instead of the HTTP standard.</p>
</div>
<div id="section19" class="doctools_section"><h2><a name="section19">AUTHORS</a></h2>
<p>Sean Woods</p>
</div>
<div id="section20" class="doctools_section"><h2><a name="section20">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>network</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tcloo">TclOO</a>, <a href="../../../../index.html#www">WWW</a>, <a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#httpd">httpd</a>, <a href="../../../../index.html#httpserver">httpserver</a>, <a href="../../../../index.html#services">services</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2018 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ident/ident.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<div class='fossil-doc' data-title='ident - Identification protocol client'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ident(n) 0.42 tcllib "Identification protocol client"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ident - Ident protocol client</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">ident <span class="opt">?0.42?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ident::query</b> <i class="arg">socket</i> <span class="opt">?<i class="arg">callback</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">ident</b> package provides a client implementation of the ident
protocol as defined in
RFC 1413 (<a href="http://www.rfc-editor.org/rfc/rfc1413.txt">http://www.rfc-editor.org/rfc/rfc1413.txt</a>).</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ident::query</b> <i class="arg">socket</i> <span class="opt">?<i class="arg">callback</i>?</span></a></dt>
<dd><p>This command queries the ident daemon on the remote side of the given
socket, and returns the result of the query as a dictionary.
Interpreting the dictionary as list the first key will always be
<b class="const">resp-type</b>, and can have one of the values <b class="const">USERID</b>,
<b class="const">ERROR</b>, and <b class="const">FATAL</b>. These <i class="term">response types</i> have
the following meanings:</p>
<dl class="doctools_definitions">
<dt>USERID</dt>
<dd><p>This indicates a successful response. Two more keys and associated
values are returned, <b class="const">opsys</b>, and <b class="const">user-id</b>.</p></dd>
<dt>ERROR</dt>
<dd><p>This means the ident server has returned an error. A second key named
<b class="const">error</b> is present whose value contains the <b class="const">error-type</b>
field from the server response.</p></dd>
<dt>FATAL</dt>
<dd><p>Fatal errors happen when no ident server is listening on the remote
side, or when the ident server gives a response that does not conform
to the RFC. A detailed error message is returned under the
<b class="const">error</b> key.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ident</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ident">ident</a>, <a href="../../../../index.html#identification">identification</a>, <a href="../../../../index.html#rfc_1413">rfc 1413</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Reinhard Max <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/imap4/imap4.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
|
<div class='fossil-doc' data-title='imap4 - imap client'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">imap4(n) 0.5.3 tcllib "imap client"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>imap4 - imap client-side tcl implementation of imap protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">imap4 <span class="opt">?0.5.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::imap4::open</b> <i class="arg">hostname</i> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::imap4::starttls</b> <i class="arg">chan</i></a></li>
<li><a href="#3"><b class="cmd">::imap4::login</b> <i class="arg">chan</i> <i class="arg">user</i> <i class="arg">pass</i></a></li>
<li><a href="#4"><b class="cmd">::imap4::folders</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">-inline</i>?</span> <span class="opt">?<i class="arg">mboxref</i>?</span> <span class="opt">?<i class="arg">mboxname</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::imap4::select</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">mailbox</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::imap4::examine</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">mailbox</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::imap4::fetch</b> <i class="arg">chan</i> <i class="arg">range</i> <span class="opt">?<i class="arg">-inline</i>?</span> <span class="opt">?<i class="arg">attr ...</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::imap4::noop</b> <i class="arg">chan</i></a></li>
<li><a href="#9"><b class="cmd">::imap4::check</b> <i class="arg">chan</i></a></li>
<li><a href="#10"><b class="cmd">::imap4::folderinfo</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">info</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::imap4::msginfo</b> <i class="arg">chan</i> <i class="arg">msgid</i> <span class="opt">?<i class="arg">info</i>?</span> <span class="opt">?<i class="arg">defval</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::imap4::mboxinfo</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">info</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::imap4::isableto</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">capability</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::imap4::create</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></li>
<li><a href="#15"><b class="cmd">::imap4::delete</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></li>
<li><a href="#16"><b class="cmd">::imap4::rename</b> <i class="arg">chan</i> <i class="arg">oldname</i> <i class="arg">newname</i></a></li>
<li><a href="#17"><b class="cmd">::imap4::subscribe</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></li>
<li><a href="#18"><b class="cmd">::imap4::unsubscribe</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></li>
<li><a href="#19"><b class="cmd">::imap4::search</b> <i class="arg">chan</i> <i class="arg">expr</i> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#20"><b class="cmd">::imap4::close</b> <i class="arg">chan</i></a></li>
<li><a href="#21"><b class="cmd">::imap4::cleanup</b> <i class="arg">chan</i></a></li>
<li><a href="#22"><b class="cmd">::imap4::debugmode</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">errormsg</i>?</span></a></li>
<li><a href="#23"><b class="cmd">::imap4::store</b> <i class="arg">chan</i> <i class="arg">range</i> <i class="arg">data</i> <i class="arg">flaglist</i></a></li>
<li><a href="#24"><b class="cmd">::imap4::expunge</b> <i class="arg">chan</i></a></li>
<li><a href="#25"><b class="cmd">::imap4::copy</b> <i class="arg">chan</i> <i class="arg">msgid</i> <i class="arg">mailbox</i></a></li>
<li><a href="#26"><b class="cmd">::imap4::logout</b> <i class="arg">chan</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">imap4</b> library package provides the client side of the
<em>Internet Message Access Protocol</em> (IMAP) using standard
sockets or secure connection via TLS/SSL.
The package is fully implemented in Tcl.</p>
<p>This document describes the procedures and explains their usage.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>This package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::imap4::open</b> <i class="arg">hostname</i> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Open a new IMAP connection and initalize the handler,
the imap communication channel (handler) is returned.</p>
<p><i class="arg">hostname</i> - mail server</p>
<p><i class="arg">port</i> - connection port, defaults to 143</p>
<p>The namespace variable <b class="option">::imap4::use_ssl</b>
can be used to establish to a secure connection
via TSL/SSL if set to true. In this case default connection port
defaults to 993.</p>
<p><em>Note:</em>
For connecting via SSL the Tcl module <em>tls</em> must be already
loaded otherwise an error is raised.</p>
<pre class="doctools_example">
package require tls ; # must be loaded for TLS/SSL
set ::imap4::use_ssl 1 ; # request a secure connection
set chan [::imap4::open $server] ; # default port is now 993 </pre>
</dd>
<dt><a name="2"><b class="cmd">::imap4::starttls</b> <i class="arg">chan</i></a></dt>
<dd><p>Use this when tasked with connecting to an unsecure port which must be
changed to a secure port prior to user login. This feature is known
as <i class="term">STARTTLS</i>.</p></dd>
<dt><a name="3"><b class="cmd">::imap4::login</b> <i class="arg">chan</i> <i class="arg">user</i> <i class="arg">pass</i></a></dt>
<dd><p>Login using the IMAP LOGIN command, 0 is returned on successful login.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">user</i> - username</p>
<p><i class="arg">pass</i> - password</p></dd>
<dt><a name="4"><b class="cmd">::imap4::folders</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">-inline</i>?</span> <span class="opt">?<i class="arg">mboxref</i>?</span> <span class="opt">?<i class="arg">mboxname</i>?</span></a></dt>
<dd><p>Get list of matching folders, 0 is returned on success.</p>
<p>Wildcards '*' as '%' are allowed for <i class="arg">mboxref</i> and <i class="arg">mboxname</i>,
command <b class="cmd">::imap4::folderinfo</b> can be used to retrieve folder information.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mboxref</i> - mailbox reference, defaults to ""</p>
<p><i class="arg">mboxname</i> - mailbox name, defaults to "*"</p>
<p>If <b class="option">-inline</b> is specified a compact folderlist is
returned instead of the result code. All flags are converted to
lowercase and leading special characters are removed.</p>
<pre class="doctools_example">{{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}</pre>
</dd>
<dt><a name="5"><b class="cmd">::imap4::select</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">mailbox</i>?</span></a></dt>
<dd><p>Select a mailbox, 0 is returned on success.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - Path of the mailbox, defaults to <em>INBOX</em></p>
<p>Prior to examine/select an open mailbox must be closed - see: <b class="cmd">::imap4::close</b>.</p></dd>
<dt><a name="6"><b class="cmd">::imap4::examine</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">mailbox</i>?</span></a></dt>
<dd><p>"Examines" a mailbox, read-only equivalent of <b class="cmd">::imap4::select</b>.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - mailbox name or path to mailbox,
defaults to <em>INBOX</em></p>
<p>Prior to examine/select an open mailbox must be closed - see: <b class="cmd">::imap4::close</b>.</p></dd>
<dt><a name="7"><b class="cmd">::imap4::fetch</b> <i class="arg">chan</i> <i class="arg">range</i> <span class="opt">?<i class="arg">-inline</i>?</span> <span class="opt">?<i class="arg">attr ...</i>?</span></a></dt>
<dd><p>Fetch attributes from messages.</p>
<p>The attributes are fetched and stored in the internal state
which can be retrieved with command <b class="cmd">::imap4::msginfo</b>, 0 is returned
on success.
If <b class="option">-inline</b> is specified, alle records are returned as list
in order as defined in the <i class="arg">attr</i> argument.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">range</i> - message index in format <em>FROM</em>:<em>TO</em></p>
<p><i class="arg">attr</i> - imap attributes to fetch</p>
<p><em>Note:</em>
If <em>FROM</em> is omitted, the 1st message is assumed,
if <em>TO</em> is ommitted the last message is assumed.
All message index ranges are 1-based.</p></dd>
<dt><a name="8"><b class="cmd">::imap4::noop</b> <i class="arg">chan</i></a></dt>
<dd><p>Send NOOP command to server. May get information as untagged data.</p>
<p><i class="arg">chan</i> - imap channel</p></dd>
<dt><a name="9"><b class="cmd">::imap4::check</b> <i class="arg">chan</i></a></dt>
<dd><p>Send CHECK command to server. Flush to disk.</p>
<p><i class="arg">chan</i> - imap channel</p></dd>
<dt><a name="10"><b class="cmd">::imap4::folderinfo</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">info</i>?</span></a></dt>
<dd><p>Get information on the recently selected folderlist.
If the <i class="arg">info</i> argument is omitted or a null string, the full list
of information available for the mailbox is returned.</p>
<p>If the required information name is suffixed with a ? character,
the command returns true if the information is available, or
false if it is not.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">info</i> - folderlist options to retrieve</p>
<p>Currently supported options:
<em>delim</em> - hierarchy delimiter only,
<em>match</em> - ref and mbox search patterns (see <b class="cmd">::imap4::folders</b>),
<em>names</em> - list of folder names only,
<em>flags</em> - list of folder names with flags in format
<em>{ {name {flags}} ... }</em> (see also compact format in function
<b class="cmd">::imap4::folders</b>).</p>
<pre class="doctools_example">
{{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}
</pre>
</dd>
<dt><a name="11"><b class="cmd">::imap4::msginfo</b> <i class="arg">chan</i> <i class="arg">msgid</i> <span class="opt">?<i class="arg">info</i>?</span> <span class="opt">?<i class="arg">defval</i>?</span></a></dt>
<dd><p>Get information (from previously collected using fetch) from a given
<em>msgid</em>. If the 'info' argument is omitted or a null string,
the list of available information options for the given message is
returned.</p>
<p>If the required information name is suffixed with a ? character,
the command returns true if the information is available, or
false if it is not.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">msgid</i> - message number</p>
<p><i class="arg">info</i> - imap keyword to retrieve</p>
<p><i class="arg">defval</i> - default value, returned if info is empty</p>
<p><em>Note:</em>
All message index ranges are 1-based.</p></dd>
<dt><a name="12"><b class="cmd">::imap4::mboxinfo</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">info</i>?</span></a></dt>
<dd><p>Get information on the currently selected mailbox.
If the <i class="arg">info</i> argument is omitted or a null string, the list
of available information options for the mailbox is returned.</p>
<p>If the required information name is suffixed with a ? character,
the command returns true if the information is available, or
false if it is not.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">opt</i> - mailbox option to retrieve</p>
<p>Currently supported options:
<em>EXISTS</em> (noof msgs),
<em>RECENT</em> (noof 'recent' flagged msgs),
<em>FLAGS</em></p>
<p>In conjunction with OK:
<em>PERMFLAGS</em>, <em>UIDNEXT</em>, <em>UIDVAL</em>, <em>UNSEEN</em></p>
<p>Div. states:
<em>CURRENT</em>, <em>FOUND</em>, <em>PERM</em>.</p>
<pre class="doctools_example">
::imap4::select $chan INBOX
puts "[::imap4::mboxinfo $chan exists] mails in INBOX"</pre>
</dd>
<dt><a name="13"><b class="cmd">::imap4::isableto</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">capability</i>?</span></a></dt>
<dd><p>Test for capability.
It returns 1 if requested capability is supported, 0 otherwise.
If <i class="arg">capability</i> is omitted all capability imap
codes are retured as list.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">info</i> - imap keyword to retrieve</p>
<p><em>Note:</em>
Use the capability command to ask the server if not
already done by the user.</p></dd>
<dt><a name="14"><b class="cmd">::imap4::create</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></dt>
<dd><p>Create a new mailbox.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - mailbox name</p></dd>
<dt><a name="15"><b class="cmd">::imap4::delete</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></dt>
<dd><p>Delete a new mailbox.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - mailbox name</p></dd>
<dt><a name="16"><b class="cmd">::imap4::rename</b> <i class="arg">chan</i> <i class="arg">oldname</i> <i class="arg">newname</i></a></dt>
<dd><p>Rename a new mailbox.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - old mailbox name</p>
<p><i class="arg">mailbox</i> - new mailbox name</p></dd>
<dt><a name="17"><b class="cmd">::imap4::subscribe</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></dt>
<dd><p>Subscribe a new mailbox.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - mailbox name</p></dd>
<dt><a name="18"><b class="cmd">::imap4::unsubscribe</b> <i class="arg">chan</i> <i class="arg">mailbox</i></a></dt>
<dd><p>Unsubscribe a new mailbox.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">mailbox</i> - mailbox name</p></dd>
<dt><a name="19"><b class="cmd">::imap4::search</b> <i class="arg">chan</i> <i class="arg">expr</i> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>Search for mails matching search criterions, 0 is returned on success.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">expr</i> - imap search expression</p>
<p><em>Notes:</em>
Currently the following search expressions are handled:</p>
<p><em>Mail header flags:</em>
all mail header entries (ending with a colon ":"), like "From:", "Bcc:", ...</p>
<p><em>Imap message search flags:</em>
ANSWERED, DELETED, DRAFT, FLAGGED, RECENT,
SEEN, NEW, OLD, UNANSWERED, UNDELETED,
UNDRAFT, UNFLAGGED, UNSEEN, ALL</p>
<p><em>Imap header search flags:</em>
BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC</p>
<p><em>Imap conditional search flags:</em>
SMALLER, LARGER, ON, SENTBEFORE, SENTON, SENTSINCE, SINCE,
BEFORE (not implemented),
UID (not implemented)</p>
<p><em>Logical search conditions:</em>
OR, NOT</p>
<pre class="doctools_example">::imap4::search $chan larger 4000 seen
puts "Found messages: [::imap4::mboxinfo $chan found]"
Found messages: 1 3 6 7 8 9 13 14 15 19 20</pre>
</dd>
<dt><a name="20"><b class="cmd">::imap4::close</b> <i class="arg">chan</i></a></dt>
<dd><p>Close the mailbox. Permanently removes \Deleted messages and
return to the AUTH state.</p>
<p><i class="arg">chan</i> - imap channel</p></dd>
<dt><a name="21"><b class="cmd">::imap4::cleanup</b> <i class="arg">chan</i></a></dt>
<dd><p>Destroy an IMAP connection and free the used space.
Close the mailbox. Permanently removes \Deleted messages
and return to the AUTH state.</p>
<p><i class="arg">chan</i> - imap channel</p></dd>
<dt><a name="22"><b class="cmd">::imap4::debugmode</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">errormsg</i>?</span></a></dt>
<dd><p>Switch client into command line debug mode.</p>
<p>This is a developers mode only that pass the control to the
programmer. Every line entered is sent verbatim to the
server (after the addition of the request identifier).
The ::imap4::debug variable is automatically set to '1' on enter.</p>
<p>It's possible to execute Tcl commands starting the line
with a slash.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">errormsg</i> - optional error message to display</p></dd>
<dt><a name="23"><b class="cmd">::imap4::store</b> <i class="arg">chan</i> <i class="arg">range</i> <i class="arg">data</i> <i class="arg">flaglist</i></a></dt>
<dd><p>Alters data associated with a message in the selected
mailbox.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">range</i> - message index in format <em>FROM</em>:<em>TO</em></p>
<p><i class="arg">flaglist</i> - Flags the <i class="arg">data</i> operates on.</p>
<p><i class="arg">data</i> - The currently defined <i class="arg">data</i> items that can be
stored are shown below. <em>Note</em> that all of these data types may
also be suffixed with ".SILENT" to suppress the untagged FETCH
response.</p>
<dl class="doctools_definitions">
<dt>FLAGS</dt>
<dd><p>Replace the flags for the message (other than \Recent) with the
<i class="arg">flaglist</i>.</p></dd>
<dt>+FLAGS</dt>
<dd><p>Add the flags in <i class="arg">flaglist</i> to the existing flags for the message.</p></dd>
<dt>-FLAGS</dt>
<dd><p>Remove the flags in <i class="arg">flaglist</i> to the existing flags for the
message.</p></dd>
</dl>
<p>For example:</p>
<pre class="doctools_example">
::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted"
</pre>
</dd>
<dt><a name="24"><b class="cmd">::imap4::expunge</b> <i class="arg">chan</i></a></dt>
<dd><p>Permanently removes all messages that have the \Deleted flag
set from the currently selected mailbox, without the need to close the
connection.</p>
<p><i class="arg">chan</i> - imap channel</p></dd>
<dt><a name="25"><b class="cmd">::imap4::copy</b> <i class="arg">chan</i> <i class="arg">msgid</i> <i class="arg">mailbox</i></a></dt>
<dd><p>Copies the specified message (identified by its message number)
to the named mailbox, i.e. imap folder.</p>
<p><i class="arg">chan</i> - imap channel</p>
<p><i class="arg">msgid</i> - message number</p>
<p><i class="arg">mailbox</i> - mailbox name</p></dd>
<dt><a name="26"><b class="cmd">::imap4::logout</b> <i class="arg">chan</i></a></dt>
<dd><p>Informs the server that the client is done with the connection
and closes the network connection. Permanently removes \Deleted
messages.</p>
<p>A new connection will need to be established to login once
more.</p>
<p><i class="arg">chan</i> - imap channel</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
set user myusername
set pass xtremescrt
set server imap.test.tld
set FOLDER INBOX
# Connect to server
set imap [::imap4::open $server]
::imap4::login $imap $user $pass
::imap4::select $imap $FOLDER
# Output all the information about that mailbox
foreach info [::imap4::mboxinfo $imap] {
puts "$info -> [::imap4::mboxinfo $imap $info]"
}
# fetch 3 records inline
set fields {from: to: subject: size}
foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] {
puts -nonewline "#[incr idx])"
for {set j 0} {$j<[llength $fields]} {incr j} {
puts "\t[lindex $fields $j] [lindex $rec $j]"
}
}
# Show all the information available about the message ID 1
puts "Available info about message 1: [::imap4::msginfo $imap 1]"
# Use the capability stuff
puts "Capabilities: [::imap4::isableto $imap]"
puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"
# Cleanup
::imap4::cleanup $imap
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<p>Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
RFC 3501, March 2003, <a href="http://www.rfc-editor.org/rfc/rfc3501.txt">http://www.rfc-editor.org/rfc/rfc3501.txt</a></p>
<p>OpenSSL, <a href="http://www.openssl.org/">http://www.openssl.org/</a></p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>imap4</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.
Only a small part of rfc3501 implemented.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../ftp/ftp.html">ftp</a>, <a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#imap">imap</a>, <a href="../mime/mime.html">mime</a>, <a href="../pop3/pop3.html">pop3</a>, <a href="../../../../index.html#tls">tls</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#email">email</a>, <a href="../../../../index.html#imap">imap</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#mail">mail</a>, <a href="../../../../index.html#net">net</a>, <a href="../../../../index.html#rfc3501">rfc3501</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/inifile/ini.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<div class='fossil-doc' data-title='inifile - Parsing of Windows INI files'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">inifile(n) 0.3.1 tcllib "Parsing of Windows INI files"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>inifile - Parsing of Windows INI files</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">inifile <span class="opt">?0.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ini::open</b> <i class="arg">file</i> <span class="opt">?<b class="option">-encoding</b> <i class="arg">encoding</i>?</span> <span class="opt">?<i class="arg">access</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::ini::close</b> <i class="arg">ini</i></a></li>
<li><a href="#3"><b class="cmd">::ini::commit</b> <i class="arg">ini</i></a></li>
<li><a href="#4"><b class="cmd">::ini::revert</b> <i class="arg">ini</i></a></li>
<li><a href="#5"><b class="cmd">::ini::filename</b> <i class="arg">ini</i></a></li>
<li><a href="#6"><b class="cmd">::ini::sections</b> <i class="arg">ini</i></a></li>
<li><a href="#7"><b class="cmd">::ini::keys</b> <i class="arg">ini</i> <i class="arg">section</i></a></li>
<li><a href="#8"><b class="cmd">::ini::get</b> <i class="arg">ini</i> <i class="arg">section</i></a></li>
<li><a href="#9"><b class="cmd">::ini::exists</b> <i class="arg">ini</i> <i class="arg">section</i> <span class="opt">?<i class="arg">key</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::ini::value</b> <i class="arg">ini</i> <i class="arg">section</i> <i class="arg">key</i> <span class="opt">?<i class="arg">default</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::ini::set</b> <i class="arg">ini</i> <i class="arg">section</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#12"><b class="cmd">::ini::delete</b> <i class="arg">ini</i> <i class="arg">section</i> <span class="opt">?<i class="arg">key</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::ini::comment</b> <i class="arg">ini</i> <i class="arg">section</i> <span class="opt">?<i class="arg">key</i>?</span> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::ini::commentchar</b> <span class="opt">?char?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an interface for easy manipulation of Windows INI files.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ini::open</b> <i class="arg">file</i> <span class="opt">?<b class="option">-encoding</b> <i class="arg">encoding</i>?</span> <span class="opt">?<i class="arg">access</i>?</span></a></dt>
<dd><p>Opens an INI file and returns a handle that is used by other commands.
<i class="arg">access</i> is the same as the first form (non POSIX) of the <b class="const">open</b>
command, with the exception that mode <b class="const">a</b> is not supported. The
default mode is <b class="const">r+</b>.</p>
<p>The default <i class="arg">encoding</i> is the system encoding.</p></dd>
<dt><a name="2"><b class="cmd">::ini::close</b> <i class="arg">ini</i></a></dt>
<dd><p>Close the specified handle. If any changes were made and not written by
<b class="const">commit</b> they are lost.</p></dd>
<dt><a name="3"><b class="cmd">::ini::commit</b> <i class="arg">ini</i></a></dt>
<dd><p>Writes the file and all changes to disk. The sections are written in
arbitrary order. The keys in a section are written in alphabetical
order. If the ini was opened in read only mode an error will be thrown.</p></dd>
<dt><a name="4"><b class="cmd">::ini::revert</b> <i class="arg">ini</i></a></dt>
<dd><p>Rolls all changes made to the inifile object back to the last
committed state.</p></dd>
<dt><a name="5"><b class="cmd">::ini::filename</b> <i class="arg">ini</i></a></dt>
<dd><p>Returns the name of the file the <i class="arg">ini</i> object is associated with.</p></dd>
<dt><a name="6"><b class="cmd">::ini::sections</b> <i class="arg">ini</i></a></dt>
<dd><p>Returns a list of all the names of the existing sections in the file handle
specified.</p></dd>
<dt><a name="7"><b class="cmd">::ini::keys</b> <i class="arg">ini</i> <i class="arg">section</i></a></dt>
<dd><p>Returns a list of all they key names in the section and file specified.</p></dd>
<dt><a name="8"><b class="cmd">::ini::get</b> <i class="arg">ini</i> <i class="arg">section</i></a></dt>
<dd><p>Returns a list of key value pairs that exist in the section and file specified.</p></dd>
<dt><a name="9"><b class="cmd">::ini::exists</b> <i class="arg">ini</i> <i class="arg">section</i> <span class="opt">?<i class="arg">key</i>?</span></a></dt>
<dd><p>Returns a boolean value indicating the existance of the specified section as a
whole or the specified key within that section.</p></dd>
<dt><a name="10"><b class="cmd">::ini::value</b> <i class="arg">ini</i> <i class="arg">section</i> <i class="arg">key</i> <span class="opt">?<i class="arg">default</i>?</span></a></dt>
<dd><p>Returns the value of the named key and section. If specified,
the default value will be returned if the key does not exist. If the key does
not exist and no default is specified an error will be thrown.</p></dd>
<dt><a name="11"><b class="cmd">::ini::set</b> <i class="arg">ini</i> <i class="arg">section</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Sets the value of the key in the specified section. If the section does not
exist then a new one is created.</p></dd>
<dt><a name="12"><b class="cmd">::ini::delete</b> <i class="arg">ini</i> <i class="arg">section</i> <span class="opt">?<i class="arg">key</i>?</span></a></dt>
<dd><p>Removes the key or the entire section and all its keys. A section is not
automatically deleted when it has no remaining keys.</p></dd>
<dt><a name="13"><b class="cmd">::ini::comment</b> <i class="arg">ini</i> <i class="arg">section</i> <span class="opt">?<i class="arg">key</i>?</span> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>Reads and modifies comments for sections and keys. To write a section comment use an
empty string for the <i class="arg">key</i>. To remove all comments use an empty string for <i class="arg">text</i>.
<i class="arg">text</i> may consist of a list of lines or one single line. Any embedded newlines in
<i class="arg">text</i> are properly handled. Comments may be written to nonexistant
sections or keys and will not return an error. Reading a comment from a nonexistant
section or key will return an empty string.</p></dd>
<dt><a name="14"><b class="cmd">::ini::commentchar</b> <span class="opt">?char?</span></a></dt>
<dd><p>Reads and sets the comment character. Lines that begin with this character are treated as
comments. When comments are written out each line is preceded by this character. The default
is <b class="const">;</b>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>inifile</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/interp/deleg_method.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<div class='fossil-doc' data-title='deleg_method - Interpreter utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">deleg_method(n) 0.2 tcllib "Interpreter utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>deleg_method - Creation of comm delegates (snit methods)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.1?</span></b></li>
<li>package require <b class="pkgname">interp::delegate::method <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::interp::delegate::method</b> <span class="opt">?<b class="option">-async</b>?</span> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">comm</i> <i class="arg">id</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single command for use within <b class="package"><a href="../snit/snit.html">snit</a></b>
type definition (i.e. actually a <b class="cmd">snit::macro</b>) for the convenient
creation of methods which delegate the actual work to a remote
location via a "channel" created by the package <b class="package"><a href="../comm/comm.html">comm</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::interp::delegate::method</b> <span class="opt">?<b class="option">-async</b>?</span> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">comm</i> <i class="arg">id</i></a></dt>
<dd><p>This commands creates a method which is named by <i class="arg">name</i>. All
invokations of this method will delegate the actual work to the remote
location identified by the comm channel <i class="arg">comm</i> and the endpoint
<i class="arg">id</i>.</p>
<p>The name of the remote method invoked by the delegator is identical to
the name of the method itself.</p>
<p>Normally the generated method marshalls the <i class="arg">arguments</i>, and
returns the result from the remote method as its own result. If
however the option <b class="option">-async</b> was specified then the generated
method will not wait for a result and return immediately.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>interp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comm">comm</a>, <a href="../../../../index.html#delegation">delegation</a>, <a href="../../../../index.html#interpreter">interpreter</a>, <a href="../../../../index.html#method">method</a>, <a href="../../../../index.html#snit">snit</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/interp/deleg_proc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<div class='fossil-doc' data-title='deleg_proc - Interpreter utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">deleg_proc(n) 0.2 tcllib "Interpreter utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>deleg_proc - Creation of comm delegates (procedures)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">interp::delegate::proc <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::interp::delegate::proc</b> <span class="opt">?<b class="option">-async</b>?</span> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">comm</i> <i class="arg">id</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single command for the convenient creation of
procedures which delegate the actual work to a remote location via a
"channel" created by the package <b class="package"><a href="../comm/comm.html">comm</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::interp::delegate::proc</b> <span class="opt">?<b class="option">-async</b>?</span> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">comm</i> <i class="arg">id</i></a></dt>
<dd><p>This commands creates a procedure which is named by <i class="arg">name</i> and
returns its fully-qualified name. All invokations of this procedure
will delegate the actual work to the remote location identified by the
comm channel <i class="arg">comm</i> and the endpoint <i class="arg">id</i>.</p>
<p>The name of the remote procedure invoked by the delegator is
[namespace tail <i class="arg">name</i>]. I.e., namespace information is
stripped from the call.</p>
<p>Normally the generated procedure marshalls the <i class="arg">arguments</i>, and
returns the result from the remote procedure as its own result. If
however the option <b class="option">-async</b> was specified then the generated
procedure will not wait for a result and return immediately.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>interp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comm">comm</a>, <a href="../../../../index.html#delegation">delegation</a>, <a href="../../../../index.html#interpreter">interpreter</a>, <a href="../../../../index.html#procedure">procedure</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/interp/tcllib_interp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
<div class='fossil-doc' data-title='interp - Interpreter utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">interp(n) 0.1.2 tcllib "Interpreter utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>interp - Interp creation and aliasing</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">interp <span class="opt">?0.1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::interp::createEmpty</b> <span class="opt">?<i class="arg">path</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::interp::snitLink</b> <i class="arg">path</i> <i class="arg">methodlist</i></a></li>
<li><a href="#3"><b class="cmd">::interp::snitDictLink</b> <i class="arg">path</i> <i class="arg">methoddict</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a number of commands for the convenient creation
of Tcl interpreters for highly restricted execution.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::interp::createEmpty</b> <span class="opt">?<i class="arg">path</i>?</span></a></dt>
<dd><p>This commands creates an empty Tcl interpreter and returns it
name. Empty means that the new interpreter has neither namespaces, nor
any commands. It is useful only for the creation of aliases.</p>
<p>If a <i class="arg">path</i> is specified then it is taken as the name of the new
interpreter.</p></dd>
<dt><a name="2"><b class="cmd">::interp::snitLink</b> <i class="arg">path</i> <i class="arg">methodlist</i></a></dt>
<dd><p>This command assumes that it was called from within a method of a snit
object, and that the command <b class="cmd">mymethod</b> is available.</p>
<p>It extends the interpreter specified by <i class="arg">path</i> with aliases for
all methods found in the <i class="arg">methodlist</i>, with the alias directing
execution to the same-named method of the snit object invoking this
command.
Each element of <i class="arg">methodlist</i> is actually interpreted as a command
prefix, with the first word of each prefix the name of the method to
link to.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="3"><b class="cmd">::interp::snitDictLink</b> <i class="arg">path</i> <i class="arg">methoddict</i></a></dt>
<dd><p>This command behaves like <b class="cmd">::interp::snitLink</b>, except that it
takes a dictionary mapping from commands to methods as its input, and
not a list of methods.
Like for <b class="cmd">::interp::snitLink</b> the method references are actually
command prefixes.
This command allows the creation of more complex command-method
mappings than <b class="cmd">::interp::snitLink</b>.</p>
<p>The result of the command is the empty string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>interp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#alias">alias</a>, <a href="../../../../index.html#empty_interpreter">empty interpreter</a>, <a href="../../../../index.html#interpreter">interpreter</a>, <a href="../../../../index.html#method">method</a>, <a href="../../../../index.html#snit">snit</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/irc/irc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
|
<div class='fossil-doc' data-title='irc - Low Level Tcl IRC Interface'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">irc(n) 0.6.2 tcllib "Low Level Tcl IRC Interface"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>irc - Create IRC connection and interface.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Per-connection Commands</a></li>
<li class="doctools_section"><a href="#section3">Callback Commands</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl</b></li>
<li>package require <b class="pkgname">irc <span class="opt">?0.6.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::irc::config</b> <span class="opt">?key?</span> <span class="opt">?value?</span></a></li>
<li><a href="#2"><b class="cmd">::irc::connection</b></a></li>
<li><a href="#3"><b class="cmd">::irc::connections</b></a></li>
<li><a href="#4"><i class="arg">net</i> <b class="method">registerevent</b> <i class="arg">event</i> <i class="arg">script</i></a></li>
<li><a href="#5"><i class="arg">net</i> <b class="method">getevent</b> <i class="arg">event</i> <i class="arg">script</i></a></li>
<li><a href="#6"><i class="arg">net</i> <b class="method">eventexists</b> <i class="arg">event</i> <i class="arg">script</i></a></li>
<li><a href="#7"><i class="arg">net</i> <b class="method">connect</b> <i class="arg">hostname</i> <span class="opt">?port?</span></a></li>
<li><a href="#8"><i class="arg">net</i> <b class="method">config</b> <span class="opt">?key?</span> <span class="opt">?value?</span></a></li>
<li><a href="#9"><i class="arg">net</i> <b class="method">log</b> <i class="arg">level</i> <i class="arg">message</i></a></li>
<li><a href="#10"><i class="arg">net</i> <b class="method">logname</b></a></li>
<li><a href="#11"><i class="arg">net</i> <b class="method">connected</b></a></li>
<li><a href="#12"><i class="arg">net</i> <b class="method">sockname</b></a></li>
<li><a href="#13"><i class="arg">net</i> <b class="method">peername</b></a></li>
<li><a href="#14"><i class="arg">net</i> <b class="method">socket</b></a></li>
<li><a href="#15"><i class="arg">net</i> <b class="method">user</b> <i class="arg">username</i> <i class="arg">localhostname</i> <i class="arg">localdomainname</i> <i class="arg">userinfo</i></a></li>
<li><a href="#16"><i class="arg">net</i> <b class="method">nick</b> <i class="arg">nick</i></a></li>
<li><a href="#17"><i class="arg">net</i> <b class="method">ping</b> <i class="arg">target</i></a></li>
<li><a href="#18"><i class="arg">net</i> <b class="method">serverping</b></a></li>
<li><a href="#19"><i class="arg">net</i> <b class="method">join</b> <i class="arg">channel</i> <span class="opt">?<i class="arg">key</i>?</span></a></li>
<li><a href="#20"><i class="arg">net</i> <b class="method">part</b> <i class="arg">channel</i> <span class="opt">?<i class="arg">message</i>?</span></a></li>
<li><a href="#21"><i class="arg">net</i> <b class="method">quit</b> <span class="opt">?<i class="arg">message</i>?</span></a></li>
<li><a href="#22"><i class="arg">net</i> <b class="method">privmsg</b> <i class="arg">target</i> <i class="arg">message</i></a></li>
<li><a href="#23"><i class="arg">net</i> <b class="method">notice</b> <i class="arg">target</i> <i class="arg">message</i></a></li>
<li><a href="#24"><i class="arg">net</i> <b class="method">ctcp</b> <i class="arg">target</i> <i class="arg">message</i></a></li>
<li><a href="#25"><i class="arg">net</i> <b class="method">kick</b> <i class="arg">channel</i> <i class="arg">target</i> <span class="opt">?<i class="arg">message</i>?</span></a></li>
<li><a href="#26"><i class="arg">net</i> <b class="method">mode</b> <i class="arg">target</i> <i class="arg">args</i></a></li>
<li><a href="#27"><i class="arg">net</i> <b class="method">topic</b> <i class="arg">channel</i> <i class="arg">message</i></a></li>
<li><a href="#28"><i class="arg">net</i> <b class="method">invite</b> <i class="arg">channel</i> <i class="arg">target</i></a></li>
<li><a href="#29"><i class="arg">net</i> <b class="method">send</b> <i class="arg">text</i></a></li>
<li><a href="#30"><i class="arg">net</i> <b class="method">destroy</b></a></li>
<li><a href="#31"><b class="cmd">who</b> <span class="opt">?<b class="const">address</b>?</span></a></li>
<li><a href="#32"><b class="cmd">action</b></a></li>
<li><a href="#33"><b class="cmd">target</b></a></li>
<li><a href="#34"><b class="cmd">additional</b></a></li>
<li><a href="#35"><b class="cmd">header</b></a></li>
<li><a href="#36"><b class="cmd">msg</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides low-level commands to deal with the IRC protocol
(Internet Relay Chat) for immediate and interactive multi-cast
communication.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::irc::config</b> <span class="opt">?key?</span> <span class="opt">?value?</span></a></dt>
<dd><p>Sets configuration <span class="opt">?key?</span> to <span class="opt">?value?</span>. The configuration keys
currently defined are the boolean flags <b class="const">logger</b> and <b class="const">debug</b>.
<b class="const">logger</b> makes <b class="package">irc</b> use the logger package for printing
error. <b class="const">debug</b> requires <b class="const">logger</b> and prints extra debug output.
If no <span class="opt">?key?</span> or <span class="opt">?value?</span> is given the current values are returned.</p></dd>
<dt><a name="2"><b class="cmd">::irc::connection</b></a></dt>
<dd><p>The command creates a new object to deal with an IRC connection.
Creating this IRC object does not automatically create the network
connection. It returns a new irc namespace command which can be used
to interact with the new IRC connection. NOTE: the old form of the
connection command, which took a hostname and port as arguments, is
deprecated. Use <b class="cmd">connect</b> instead to specify this information.</p></dd>
<dt><a name="3"><b class="cmd">::irc::connections</b></a></dt>
<dd><p>Returns a list of all the current connections that were created with
<b class="const">connection</b></p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Per-connection Commands</a></h2>
<p>In the following list of available connection methods <i class="arg">net</i>
represents a connection command as returned by
<b class="cmd">::irc::connection</b>.</p>
<dl class="doctools_definitions">
<dt><a name="4"><i class="arg">net</i> <b class="method">registerevent</b> <i class="arg">event</i> <i class="arg">script</i></a></dt>
<dd><p>Registers a callback handler for the specific event. Events available
are those described in RFC 1459
<a href="http://www.rfc-editor.org/rfc/rfc1459.txt">http://www.rfc-editor.org/rfc/rfc1459.txt</a>.
In addition, there are several other events defined.
<b class="const">defaultcmd</b> adds a command that is called if no other callback
is present. <b class="const">EOF</b> is called if the connection signals an End of
File condition. The events <b class="const">defaultcmd</b>, <b class="const">defaultnumeric</b>,
<b class="const">defaultevent</b>, and <b class="const">EOF</b> are required.
<i class="arg">script</i> is executed in the connection namespace, which can take
advantage of several commands (see <span class="sectref"><a href="#section3">Callback Commands</a></span>
below) to aid in the parsing of data.</p></dd>
<dt><a name="5"><i class="arg">net</i> <b class="method">getevent</b> <i class="arg">event</i> <i class="arg">script</i></a></dt>
<dd><p>Returns the current handler for the event if one exists. Otherwise an
empty string is returned.</p></dd>
<dt><a name="6"><i class="arg">net</i> <b class="method">eventexists</b> <i class="arg">event</i> <i class="arg">script</i></a></dt>
<dd><p>Returns a boolean value indicating the existence of the event handler.</p></dd>
<dt><a name="7"><i class="arg">net</i> <b class="method">connect</b> <i class="arg">hostname</i> <span class="opt">?port?</span></a></dt>
<dd><p>This causes the socket to be established. <b class="cmd">::irc::connection</b>
created the namespace and the commands to be used, but did not
actually open the socket. This is done here. NOTE: the older form of
'connect' did not require the user to specify a hostname and port,
which were specified with 'connection'. That form is deprecated.</p></dd>
<dt><a name="8"><i class="arg">net</i> <b class="method">config</b> <span class="opt">?key?</span> <span class="opt">?value?</span></a></dt>
<dd><p>The same as <b class="cmd">::irc::config</b> but sets and gets options for the <i class="arg">net</i>
connection only.</p></dd>
<dt><a name="9"><i class="arg">net</i> <b class="method">log</b> <i class="arg">level</i> <i class="arg">message</i></a></dt>
<dd><p>If logger is turned on by <b class="method">config</b> this will write a log <i class="arg">message</i>
at <i class="arg">level</i>.</p></dd>
<dt><a name="10"><i class="arg">net</i> <b class="method">logname</b></a></dt>
<dd><p>Returns the name of the logger instance if logger is turned on.</p></dd>
<dt><a name="11"><i class="arg">net</i> <b class="method">connected</b></a></dt>
<dd><p>Returns a boolean value indicating if this connection is connected to a server.</p></dd>
<dt><a name="12"><i class="arg">net</i> <b class="method">sockname</b></a></dt>
<dd><p>Returns a 3 element list consisting of the ip address, the hostname, and the port
of the local end of the connection, if currently connected.</p></dd>
<dt><a name="13"><i class="arg">net</i> <b class="method">peername</b></a></dt>
<dd><p>Returns a 3 element list consisting of the ip address, the hostname, and the port
of the remote end of the connection, if currently connected.</p></dd>
<dt><a name="14"><i class="arg">net</i> <b class="method">socket</b></a></dt>
<dd><p>Return the Tcl channel for the socket used by the connection.</p></dd>
<dt><a name="15"><i class="arg">net</i> <b class="method">user</b> <i class="arg">username</i> <i class="arg">localhostname</i> <i class="arg">localdomainname</i> <i class="arg">userinfo</i></a></dt>
<dd><p>Sends USER command to server. <i class="arg">username</i> is the username you want
to appear. <i class="arg">localhostname</i> is the host portion of your hostname, <i class="arg">localdomainname</i>
is your domain name, and <i class="arg">userinfo</i> is a short description of who you are. The 2nd and 3rd
arguments are normally ignored by the IRC server.</p></dd>
<dt><a name="16"><i class="arg">net</i> <b class="method">nick</b> <i class="arg">nick</i></a></dt>
<dd><p>NICK command. <i class="arg">nick</i> is the nickname you wish to use for the
particular connection.</p></dd>
<dt><a name="17"><i class="arg">net</i> <b class="method">ping</b> <i class="arg">target</i></a></dt>
<dd><p>Send a CTCP PING to <i class="arg">target</i>.</p></dd>
<dt><a name="18"><i class="arg">net</i> <b class="method">serverping</b></a></dt>
<dd><p>PING the server.</p></dd>
<dt><a name="19"><i class="arg">net</i> <b class="method">join</b> <i class="arg">channel</i> <span class="opt">?<i class="arg">key</i>?</span></a></dt>
<dd><p><i class="arg">channel</i> is the IRC channel to join. IRC channels typically
begin with a hashmark ("#") or ampersand ("&").</p></dd>
<dt><a name="20"><i class="arg">net</i> <b class="method">part</b> <i class="arg">channel</i> <span class="opt">?<i class="arg">message</i>?</span></a></dt>
<dd><p>Makes the client leave <i class="arg">channel</i>. Some networks may support the optional
argument <i class="arg">message</i></p></dd>
<dt><a name="21"><i class="arg">net</i> <b class="method">quit</b> <span class="opt">?<i class="arg">message</i>?</span></a></dt>
<dd><p>Instructs the IRC server to close the current connection. The package
will use a generic default if no <i class="arg">message</i> was specified.</p></dd>
<dt><a name="22"><i class="arg">net</i> <b class="method">privmsg</b> <i class="arg">target</i> <i class="arg">message</i></a></dt>
<dd><p>Sends <i class="arg">message</i> to <i class="arg">target</i>, which can be either a channel, or
another user, in which case their nick is used.</p></dd>
<dt><a name="23"><i class="arg">net</i> <b class="method">notice</b> <i class="arg">target</i> <i class="arg">message</i></a></dt>
<dd><p>Sends a <b class="const">notice</b> with message <i class="arg">message</i> to <i class="arg">target</i>,
which can be either a channel, or another user, in which case their nick is used.</p></dd>
<dt><a name="24"><i class="arg">net</i> <b class="method">ctcp</b> <i class="arg">target</i> <i class="arg">message</i></a></dt>
<dd><p>Sends a CTCP of type <i class="arg">message</i> to <i class="arg">target</i></p></dd>
<dt><a name="25"><i class="arg">net</i> <b class="method">kick</b> <i class="arg">channel</i> <i class="arg">target</i> <span class="opt">?<i class="arg">message</i>?</span></a></dt>
<dd><p>Kicks the user <i class="arg">target</i> from the channel <i class="arg">channel</i> with a <i class="arg">message</i>.
The latter can be left out.</p></dd>
<dt><a name="26"><i class="arg">net</i> <b class="method">mode</b> <i class="arg">target</i> <i class="arg">args</i></a></dt>
<dd><p>Sets the mode <i class="arg">args</i> on the target <i class="arg">target</i>. <i class="arg">target</i> may be a channel,
a channel user, or yourself.</p></dd>
<dt><a name="27"><i class="arg">net</i> <b class="method">topic</b> <i class="arg">channel</i> <i class="arg">message</i></a></dt>
<dd><p>Sets the topic on <i class="arg">channel</i> to <i class="arg">message</i> specifying an empty string
will remove the topic.</p></dd>
<dt><a name="28"><i class="arg">net</i> <b class="method">invite</b> <i class="arg">channel</i> <i class="arg">target</i></a></dt>
<dd><p>Invites <i class="arg">target</i> to join the channel <i class="arg">channel</i></p></dd>
<dt><a name="29"><i class="arg">net</i> <b class="method">send</b> <i class="arg">text</i></a></dt>
<dd><p>Sends <i class="arg">text</i> to the IRC server.</p></dd>
<dt><a name="30"><i class="arg">net</i> <b class="method">destroy</b></a></dt>
<dd><p>Deletes the connection and its associated namespace and information.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Callback Commands</a></h2>
<p>These commands can be used within callbacks</p>
<dl class="doctools_definitions">
<dt><a name="31"><b class="cmd">who</b> <span class="opt">?<b class="const">address</b>?</span></a></dt>
<dd><p>Returns the nick of the user who performed a command. The optional
keyword <b class="const">address</b> causes the command to return the user in the
format "username@address".</p></dd>
<dt><a name="32"><b class="cmd">action</b></a></dt>
<dd><p>Returns the action performed, such as KICK, PRIVMSG, MODE, etc...
Normally not useful, as callbacks are bound to a particular event.</p></dd>
<dt><a name="33"><b class="cmd">target</b></a></dt>
<dd><p>Returns the target of a particular command, such as the channel or
user to whom a PRIVMSG is sent.</p></dd>
<dt><a name="34"><b class="cmd">additional</b></a></dt>
<dd><p>Returns a list of any additional arguments after the target.</p></dd>
<dt><a name="35"><b class="cmd">header</b></a></dt>
<dd><p>Returns the entire event header (everything up to the :) as a proper list.</p></dd>
<dt><a name="36"><b class="cmd">msg</b></a></dt>
<dd><p>Returns the message portion of the command (the part after the :).</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>irc</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>rfc 1459</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#chat">chat</a>, <a href="../../../../index.html#irc">irc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/irc/picoirc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
<div class='fossil-doc' data-title='picoirc - Simple embeddable IRC interface'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">picoirc(n) 0.5.2 tcllib "Simple embeddable IRC interface"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>picoirc - Small and simple embeddable IRC client.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">CALLBACK</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl</b></li>
<li>package require <b class="pkgname">picoirc <span class="opt">?0.5.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::picoirc::connect</b> <i class="arg">callback</i> <i class="arg">nick</i> <i class="arg">url</i></a></li>
<li><a href="#2"><b class="cmd">::picoirc::post</b> <i class="arg">context</i> <i class="arg">channel</i> <i class="arg">message</i></a></li>
<li><a href="#3"><b class="cmd">::picoirc::splituri</b> <i class="arg">uri</i></a></li>
<li><a href="#4"><b class="cmd">::picoirc::send</b> <i class="arg">context</i> <i class="arg">line</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a general purpose minimal IRC client suitable for
embedding in other applications. All communication with the parent
application is done via an application provided callback procedure.
Each connection has its own state so you can hook up multiple servers
in a single application instance.</p>
<p>To initiate an IRC connection you must call <b class="cmd">picoirc::connect</b>
with a callback procedure, a nick-name to use on IRC and the IRC URL
that describes the connection. This will return a variable name that
is the irc connection context. See <span class="sectref"><a href="#section3">CALLBACK</a></span> for details.</p>
<p>This package is a fairly simple IRC client. If you need something with
more capability investigate the <b class="package"><a href="irc.html">irc</a></b> package.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::picoirc::connect</b> <i class="arg">callback</i> <i class="arg">nick</i> <i class="arg">url</i></a></dt>
<dd><p>Create a new irc connection to the server specified by <i class="arg">url</i> and
login using the <i class="arg">nick</i> as the username. The <i class="arg">callback</i> must be
as specified in <span class="sectref"><a href="#section3">CALLBACK</a></span>. Returns a package-specific variable
that is used when calling other commands in this package.</p></dd>
<dt><a name="2"><b class="cmd">::picoirc::post</b> <i class="arg">context</i> <i class="arg">channel</i> <i class="arg">message</i></a></dt>
<dd><p>This should be called to process user input and send it to the
server. A number of commands are recognised when prefixed with a
forward-slash (/). Such commands are converted to IRC command
sequences and then sent.</p></dd>
<dt><a name="3"><b class="cmd">::picoirc::splituri</b> <i class="arg">uri</i></a></dt>
<dd><p>Splits an IRC scheme uniform resource indicator into its component
parts. Returns a list of server, port and channel. The default port is
6667 and there is no default channel.</p></dd>
<dt><a name="4"><b class="cmd">::picoirc::send</b> <i class="arg">context</i> <i class="arg">line</i></a></dt>
<dd><p>This command is where all raw output to the server is handled. The
default action is to write the <i class="arg">line</i> to the irc socket. However,
before this happens the callback is called with "debug write". This
permits the application author to inspect the raw IRC data and if
desired to return a break error code to halt further processing. In
this way the application can override the default send via the
callback procedure.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CALLBACK</a></h2>
<p>The callback must look like:</p>
<pre class="doctools_example">
proc Callback {context state args} {
}
</pre>
<p>where context is the irc context variable name (in case you need to pass
it back to a picoirc procedure). state is one of a number of states as
described below.</p>
<dl class="doctools_options">
<dt><b class="option">init</b></dt>
<dd><p>called just before the socket is created</p></dd>
<dt><b class="option">connect</b></dt>
<dd><p>called once we have connected, before we join any channels</p></dd>
<dt><b class="option">close</b></dt>
<dd><p>called when the socket gets closed, before the context is deleted. If
an error occurs before we get connected the only argument will be the
socket error message.</p></dd>
<dt><b class="option">userlist</b> <i class="arg">channel</i> <i class="arg">nicklist</i></dt>
<dd><p>called to notify the application of an updated userlist. This is
generated when the output of the NAMES irc command is seen. The
package collects the entire output which can span a number of output
lines from the server and calls this callback when they have all been
received.</p></dd>
<dt><b class="option">chat</b> <i class="arg">target</i> <i class="arg">nick</i> <i class="arg">message</i> <i class="arg">type</i></dt>
<dd><p>called when a message arrives. <i class="arg">target</i> is the identity that the
message was targetted for. This can be the logged in nick or a channel
name. <i class="arg">nick</i> is the name of the sender of the message.
<i class="arg">message</i> is the message text. <i class="arg">type</i> is set to "ACTION" if the
message was sent as a CTCP ACTION</p></dd>
<dt><b class="option">system</b> <i class="arg">channel</i> <i class="arg">message</i></dt>
<dd><p>called when a system message is received</p></dd>
<dt><b class="option">topic</b> <i class="arg">channel</i> <i class="arg">topic</i></dt>
<dd><p>called when the channel topic string is seen. <i class="arg">topic</i> is the text
of the channel topic.</p></dd>
<dt><b class="option">traffic</b> <i class="arg">action</i> <i class="arg">channel</i> <i class="arg">nick</i> <span class="opt">?<i class="arg">newnick</i>?</span></dt>
<dd><p>called when users join, leave or change names.
<i class="arg">action</i> is either entered, left or nickchange and <i class="arg">nick</i>
is the user doing the action. <i class="arg">newnick</i> is
the new name if <i class="arg">action</i> is nickchange.</p>
<p><em>NOTE</em>: <i class="arg">channel</i> is often empty for these messages as nick
activities are global for the irc server. You will have
to manage the nick for all connected channels yourself.</p></dd>
<dt><b class="option">version</b></dt>
<dd><p>This is called to request a version string to use to
override the internal version. If implemented, you should
return as colon delimited string as</p>
<p>Appname:Appversion:LibraryVersion</p>
<p>For example, the default is</p>
<p>PicoIRC:[package provide picoirc]:Tcl [info patchlevel]</p></dd>
<dt><b class="option">debug</b> <i class="arg">type</i> <i class="arg">raw</i></dt>
<dd><p>called when data is either being read or written to the network
socket. <i class="arg">type</i> is set to <b class="const">read</b> when reading data and
<b class="const">write</b> if the data is to be written. <i class="arg">raw</i> is the
unprocessed IRC protocol data.</p>
<p>In both cases the application can return a break error code to
interrupt further processing of the raw data. If this is a
<b class="const">read</b> operation then the package will not handle this line. If
the operation is <b class="const">write</b> then the package will not send the
data. This callback is intended for debugging protocol issues but
could be used to redirect all input and output if desired.</p></dd>
</dl>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>rfc 1459</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#chat">chat</a>, <a href="../../../../index.html#irc">irc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/javascript/javascript.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
<div class='fossil-doc' data-title='javascript - HTML and Java Script Generation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">javascript(n) 1.0.2 tcllib "HTML and Java Script Generation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>javascript - Procedures to generate HTML and Java Script structures.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">javascript <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::javascript::makeSelectorWidget</b> <i class="arg">id leftLabel leftValueList rightLabel rightValueList rightNameList</i> <span class="opt">?<i class="arg">length</i>?</span> <span class="opt">?<i class="arg">minWidth</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::javascript::makeSubmitButton</b> <i class="arg">name value</i></a></li>
<li><a href="#3"><b class="cmd">::javascript::makeProtectedSubmitButton</b> <i class="arg">name value msg</i></a></li>
<li><a href="#4"><b class="cmd">::javascript::makeMasterButton</b> <i class="arg">master value slavePattern boolean</i></a></li>
<li><a href="#5"><b class="cmd">::javascript::makeParentCheckbox</b> <i class="arg">parentName childName</i></a></li>
<li><a href="#6"><b class="cmd">::javascript::makeChildCheckbox</b> <i class="arg">parentName childName</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">::javascript</b> package provides commands that generate
HTML and Java Script code. These commands typically return an HTML
string as their result. In particular, they do not output their
result to <b class="const">stdout</b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::javascript::makeSelectorWidget</b> <i class="arg">id leftLabel leftValueList rightLabel rightValueList rightNameList</i> <span class="opt">?<i class="arg">length</i>?</span> <span class="opt">?<i class="arg">minWidth</i>?</span></a></dt>
<dd><p>Construct HTML code to create a dual-multi-selection megawidget. This
megawidget consists of two side-by-side multi-selection boxes
separated by a left arrow and a right arrow button. The right arrow
button moves all items selected in the left box to the right box. The
left arrow button moves all items selected in the right box to the
left box. The <i class="arg">id</i> argument is the suffix of all HTML objects in
this megawidget. The <i class="arg">leftLabel</i> argument is the text that
appears above the left selection box. The <i class="arg">leftValueList</i>
argument is the values of items in the left selection box. The
<i class="arg">leftNameList</i> argument is the names to appear in the left
selection box. The <i class="arg">rightLabel</i> argument is the text that appears
above the right selection box. The <i class="arg">rightValueList</i> argument is
the values of items in the right selection box. The
<i class="arg">rightNameList</i> argument is the names to appear in the right
selection box. The <i class="arg">length</i> argument (optional) determines the
number of elts to show before adding a vertical scrollbar; it defaults
to 8. The <i class="arg">minWidth</i> argument (optional) is the number of spaces
to determine the minimum box width; it defaults to 32.</p></dd>
<dt><a name="2"><b class="cmd">::javascript::makeSubmitButton</b> <i class="arg">name value</i></a></dt>
<dd><p>Create an HTML submit button that resets a hidden field for each
registered multi-selection box. The <i class="arg">name</i> argument is the name
of the HTML button object to create. The <i class="arg">value</i> argument is the
label of the HTML button object to create.</p></dd>
<dt><a name="3"><b class="cmd">::javascript::makeProtectedSubmitButton</b> <i class="arg">name value msg</i></a></dt>
<dd><p>Create an HTML submit button that prompts the user with a
continue/cancel shutdown warning before the form is submitted. The
<i class="arg">name</i> argument is the name of the HTML button object to create.
The <i class="arg">value</i> argument is the label of the HTML button object to
create. The <i class="arg">msg</i> argument is the message to display when the
button is pressed.</p></dd>
<dt><a name="4"><b class="cmd">::javascript::makeMasterButton</b> <i class="arg">master value slavePattern boolean</i></a></dt>
<dd><p>Create an HTML button that sets its slave checkboxs to the boolean
value. The <i class="arg">master</i> argument is the name of the child's parent
html checkbox object. The <i class="arg">value</i> argument is the value of the
master. The <i class="arg">slaves</i> argument is the name of child html checkbox
object to create. The <i class="arg">boolean</i> argument is the java script
boolean value that will be given to all the slaves; it must be "true"
or "false".</p></dd>
<dt><a name="5"><b class="cmd">::javascript::makeParentCheckbox</b> <i class="arg">parentName childName</i></a></dt>
<dd><p>Create an HTML checkbox and tie its value to that of its child
checkbox. If the parent is unchecked, the child is automatically
unchecked. The <i class="arg">parentName</i> argument is the name of parent html
checkbox object to create. The <i class="arg">childName</i> argument is the name of
the parent's child html checkbox object.</p></dd>
<dt><a name="6"><b class="cmd">::javascript::makeChildCheckbox</b> <i class="arg">parentName childName</i></a></dt>
<dd><p>Create an HTML checkbox and tie its value to that of its parent
checkbox. If the child is checked, the parent is automatically
checked. The <i class="arg">parentName</i> argument is the name of the child's
parent html checkbox object. The <i class="arg">childName</i> argument is the name
of child html checkbox object to create.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>javascript</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../html/html.html">html</a>, <a href="../ncgi/ncgi.html">ncgi</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checkbox">checkbox</a>, <a href="../../../../index.html#html">html</a>, <a href="../../../../index.html#javascript">javascript</a>, <a href="../../../../index.html#selectionbox">selectionbox</a>, <a href="../../../../index.html#submitbutton">submitbutton</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>CGI programming</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/jpeg/jpeg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<div class='fossil-doc' data-title='jpeg - JPEG image manipulation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">jpeg(n) 0.5 tcllib "JPEG image manipulation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>jpeg - JPEG querying and manipulation of meta data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">LIMITATIONS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">jpeg <span class="opt">?0.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::jpeg::isJPEG</b> <i class="arg">file</i></a></li>
<li><a href="#2"><b class="cmd">::jpeg::imageInfo</b> <i class="arg">file</i></a></li>
<li><a href="#3"><b class="cmd">::jpeg::dimensions</b> <i class="arg">file</i></a></li>
<li><a href="#4"><b class="cmd">::jpeg::getThumbnail</b> <i class="arg">file</i></a></li>
<li><a href="#5"><b class="cmd">::jpeg::getExif</b> <i class="arg">file</i> <span class="opt">?<i class="arg">section</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::jpeg::getExifFromChannel</b> <i class="arg">channel</i> <span class="opt">?<i class="arg">section</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::jpeg::formatExif</b> <i class="arg">keys</i></a></li>
<li><a href="#8"><b class="cmd">::jpeg::exifKeys</b></a></li>
<li><a href="#9"><b class="cmd">::jpeg::removeExif</b> <i class="arg">file</i></a></li>
<li><a href="#10"><b class="cmd">::jpeg::stripJPEG</b> <i class="arg">file</i></a></li>
<li><a href="#11"><b class="cmd">::jpeg::getComments</b> <i class="arg">file</i></a></li>
<li><a href="#12"><b class="cmd">::jpeg::addComment</b> <i class="arg">file</i> <i class="arg">text</i>...</a></li>
<li><a href="#13"><b class="cmd">::jpeg::removeComments</b> <i class="arg">file</i></a></li>
<li><a href="#14"><b class="cmd">::jpeg::replaceComment</b> <i class="arg">file</i> <i class="arg">text</i></a></li>
<li><a href="#15"><b class="cmd">::jpeg::debug</b> <i class="arg">file</i></a></li>
<li><a href="#16"><b class="cmd">::jpeg::markers</b> <i class="arg">channel</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to query and modify JPEG images. JPEG
stands for <i class="term">Joint Photography Experts Group</i> and is a standard
for the lossy compression of photographical images. It is specified at
<a href="LINK_HERE">LINK_HERE</a>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::jpeg::isJPEG</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a boolean value indicating if <i class="arg">file</i> is a
JPEG image.</p></dd>
<dt><a name="2"><b class="cmd">::jpeg::imageInfo</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a dictionary with keys <b class="const">version</b>, <b class="const">units</b>,
<b class="const">xdensity</b>, <b class="const">ydensity</b>, <b class="const">xthumb</b>, and
<b class="const">ythumb</b>. The values are the associated properties of the JPEG
image in <i class="arg">file</i>.
Throws an error if <i class="arg">file</i> is not a JPEG image.</p></dd>
<dt><a name="3"><b class="cmd">::jpeg::dimensions</b> <i class="arg">file</i></a></dt>
<dd><p>Returns the dimensions of the JPEG <i class="arg">file</i> as a list of the
horizontal and vertical pixel count.
Throws an error if <i class="arg">file</i> is not a JPEG image.</p></dd>
<dt><a name="4"><b class="cmd">::jpeg::getThumbnail</b> <i class="arg">file</i></a></dt>
<dd><p>This procedure will return the binary thumbnail image data, if a JPEG
thumbnail is included in <i class="arg">file</i>, and the empty string
otherwise. Note that it is possible to include thumbnails in formats
other than JPEG although that is not common. The command finds
thumbnails that are encoded in either the JFXX or EXIF segments of the
JPEG information. If both are present the EXIF thumbnail will take precedence.
Throws an error if <i class="arg">file</i> is not a JPEG image.</p>
<pre class="doctools_example">
set fh [open thumbnail.jpg w+]
fconfigure $fh -translation binary -encoding binary
puts -nonewline $fh [::jpeg::getThumbnail photo.jpg]
close $fh
</pre>
</dd>
<dt><a name="5"><b class="cmd">::jpeg::getExif</b> <i class="arg">file</i> <span class="opt">?<i class="arg">section</i>?</span></a></dt>
<dd><p><i class="arg">section</i> must be one of <b class="const">main</b> or <b class="const">thumbnail</b>.
The default is <b class="const">main</b>.
Returns a dictionary containing the EXIF information for the specified section.
For example:</p>
<pre class="doctools_example">
set exif {
Make Canon
Model {Canon DIGITAL IXUS}
DateTime {2001:06:09 15:17:32}
}
</pre>
<p>Throws an error if <i class="arg">file</i> is not a JPEG image.</p></dd>
<dt><a name="6"><b class="cmd">::jpeg::getExifFromChannel</b> <i class="arg">channel</i> <span class="opt">?<i class="arg">section</i>?</span></a></dt>
<dd><p>This command is as per <b class="cmd">::jpeg::getExif</b> except that it uses a
previously opened channel. <i class="arg">channel</i> should be a seekable channel
and <i class="arg">section</i> is as described in the documentation of
<b class="cmd">::jpeg::getExif</b>.</p>
<p><em>Note</em>: The jpeg parser expects that the start of the
channel is the start of the image data. If working with an image
embedded in a container file format it may be necessary to read the
jpeg data into a temporary container: either a temporary file or a
memory channel.</p>
<p><em>Attention</em>: It is the resonsibility of the caller to close
the channel after its use.</p></dd>
<dt><a name="7"><b class="cmd">::jpeg::formatExif</b> <i class="arg">keys</i></a></dt>
<dd><p>Takes a list of key-value pairs as returned by <b class="cmd">getExif</b> and formats
many of the values into a more human readable form. As few as one key-value
may be passed in, the entire exif is not required.</p>
<pre class="doctools_example">
foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] {
puts "$key: $val"
}
</pre>
<pre class="doctools_example">
array set exif [::jpeg::getExif photo.jpg]
puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]]
</pre>
</dd>
<dt><a name="8"><b class="cmd">::jpeg::exifKeys</b></a></dt>
<dd><p>Returns a list of the EXIF keys which are currently understood.
There may be keys present in <b class="cmd">getExif</b> data that are not understood.
Those keys will appear in a 4 digit hexadecimal format.</p></dd>
<dt><a name="9"><b class="cmd">::jpeg::removeExif</b> <i class="arg">file</i></a></dt>
<dd><p>Removes the Exif data segment from the specified file and replaces
it with a standard JFIF segment.
Throws an error if <i class="arg">file</i> is not a JPEG image.</p></dd>
<dt><a name="10"><b class="cmd">::jpeg::stripJPEG</b> <i class="arg">file</i></a></dt>
<dd><p>Removes all metadata from the JPEG file leaving only
the image. This includes comments, EXIF segments, JFXX
segments, and application specific segments.
Throws an error if <i class="arg">file</i> is not a JPEG image.</p></dd>
<dt><a name="11"><b class="cmd">::jpeg::getComments</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a list containing all the JPEG comments found in
the <i class="arg">file</i>.
Throws an error if <i class="arg">file</i> is not a valid JPEG image.</p></dd>
<dt><a name="12"><b class="cmd">::jpeg::addComment</b> <i class="arg">file</i> <i class="arg">text</i>...</a></dt>
<dd><p>Adds one or more plain <i class="arg">text</i> comments to the JPEG image
in <i class="arg">file</i>.
Throws an error if <i class="arg">file</i> is not a valid JPEG image.</p></dd>
<dt><a name="13"><b class="cmd">::jpeg::removeComments</b> <i class="arg">file</i></a></dt>
<dd><p>Removes all comments from the file specified.
Throws an error if <i class="arg">file</i> is not a valid JPEG image.</p></dd>
<dt><a name="14"><b class="cmd">::jpeg::replaceComment</b> <i class="arg">file</i> <i class="arg">text</i></a></dt>
<dd><p>Replaces the first comment in the file with the new <i class="arg">text</i>.
This is merely a shortcut for <b class="cmd">::jpeg::removeComments</b>
and <b class="cmd">::jpeg::addComment</b>
Throws an error if <i class="arg">file</i> is not a valid JPEG image.</p></dd>
<dt><a name="15"><b class="cmd">::jpeg::debug</b> <i class="arg">file</i></a></dt>
<dd><p>Prints everything we know about the given file in a nice format.</p></dd>
<dt><a name="16"><b class="cmd">::jpeg::markers</b> <i class="arg">channel</i></a></dt>
<dd><p>This is an internal helper command, we document it for use by advanced
users of the package. The argument <i class="arg">channel</i> is an open file
handle positioned at the start of the first marker (usually 2
bytes). The command returns a list with one element for each JFIF
marker found in the file. Each element consists of a list of the
marker name, its offset in the file, and its length. The offset points
to the beginning of the sections data, not the marker itself. The
length is the length of the data from the offset listed to the start
of the next marker.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">LIMITATIONS</a></h2>
<p>can only work with files
cant write exif data
gps exif data not parsed
makernote data not yet implemented</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>jpeg</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comment">comment</a>, <a href="../../../../index.html#exif">exif</a>, <a href="../../../../index.html#image">image</a>, <a href="../../../../index.html#jfif">jfif</a>, <a href="../../../../index.html#jpeg">jpeg</a>, <a href="../../../../index.html#thumbnail">thumbnail</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File formats</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2005, Code: Aaron Faupell <[email protected]><br>
Copyright © 2007, Code: Andreas Kupries <[email protected]><br>
Copyright © 2004-2009, Doc: Andreas Kupries <[email protected]><br>
Copyright © 2011, Code: Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/json/json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
<div class='fossil-doc' data-title='json - JSON'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">json(n) 1.3.4 tcllib "JSON"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>json - JSON parser</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">RELATED</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">json <span class="opt">?1.3.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::json::json2dict</b> <i class="arg">txt</i></a></li>
<li><a href="#2"><b class="cmd">::json::many-json2dict</b> <i class="arg">txt</i> <span class="opt">?<i class="arg">max</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">json</b> package provides a simple Tcl-only library for parsing the
JSON <a href="http://www.json.org/">http://www.json.org/</a> data exchange format as specified in RFC 4627
<a href="http://www.ietf.org/rfc/rfc4627.txt">http://www.ietf.org/rfc/rfc4627.txt</a>.
There is some ambiguity in parsing JSON because JSON has type information that
is not maintained by the Tcl conversion. The <b class="package">json</b> package returns
data as a Tcl <b class="cmd"><a href="../../../../index.html#dict">dict</a></b>. Either the <b class="package"><a href="../../../../index.html#dict">dict</a></b> package or Tcl 8.5 is
required for use.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::json::json2dict</b> <i class="arg">txt</i></a></dt>
<dd><p>Parse JSON formatted text <i class="arg">txt</i> into a Tcl dict and return
the value.</p>
<p>If <i class="arg">txt</i> contains more than one JSON entity only the
first one is returned.</p></dd>
<dt><a name="2"><b class="cmd">::json::many-json2dict</b> <i class="arg">txt</i> <span class="opt">?<i class="arg">max</i>?</span></a></dt>
<dd><p>Parse JSON formatted text <i class="arg">txt</i> containing multiple JSON entities
into a list of dictionaries and return that list.</p>
<p>If <i class="arg">max</i> is specified exactly that many entities are extracted
from <i class="arg">txt</i>. By default the command will attempt to extract all, without
limits. A value of "<i class="arg">max</i> == 0" does not make sense and will cause the
command to throw an error.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>An example of a JSON array converted to Tcl. A JSON array is returned as a
single item with multiple elements.</p>
<pre class="doctools_example">[
{
"precision": "zip",
"Latitude": 37.7668,
"Longitude": -122.3959,
"Address": "",
"City": "SAN FRANCISCO",
"State": "CA",
"Zip": "94107",
"Country": "US"
},
{
"precision": "zip",
"Latitude": 37.371991,
"Longitude": -122.026020,
"Address": "",
"City": "SUNNYVALE",
"State": "CA",
"Zip": "94085",
"Country": "US"
}
]
=>
{Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020}
</pre>
<p>An example of a JSON object converted to Tcl. A JSON object is returned as a
multi-element list (a dict).</p>
<pre class="doctools_example">{
"Image": {
"Width": 800,
"Height": 600,
"Title": "View from 15th Floor",
"Thumbnail": {
"Url": "http://www.example.com/image/481989943",
"Height": 125,
"Width": "100"
},
"IDs": [116, 943, 234, 38793]
}
}
=>
Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">RELATED</a></h2>
<p>To write json, instead of parsing it, see package <b class="package"><a href="json_write.html">json::write</a></b>.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>json</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_exchange">data exchange</a>, <a href="../../../../index.html#exchange_format">exchange format</a>, <a href="../../../../index.html#javascript">javascript</a>, <a href="../../../../index.html#json">json</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>CGI programming</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 ActiveState Software Inc.<br>
Copyright © 2009 Thomas Maeder, Glue Software Engineering AG</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/json/json_write.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<div class='fossil-doc' data-title='json::write - JSON'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">json::write(n) 1.0.3 tcllib "JSON"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>json::write - JSON generation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">RELATED</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">json::write <span class="opt">?1.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::json::write</b> <b class="method">indented</b></a></li>
<li><a href="#2"><b class="cmd">::json::write</b> <b class="method">indented</b> <i class="arg">flag</i></a></li>
<li><a href="#3"><b class="cmd">::json::write</b> <b class="method">aligned</b></a></li>
<li><a href="#4"><b class="cmd">::json::write</b> <b class="method">aligned</b> <i class="arg">flag</i></a></li>
<li><a href="#5"><b class="cmd">::json::write</b> <b class="method">string</b> <i class="arg">s</i></a></li>
<li><a href="#6"><b class="cmd">::json::write</b> <b class="method">array</b> <i class="arg">arg</i>...</a></li>
<li><a href="#7"><b class="cmd">::json::write</b> <b class="method">object</b> <i class="arg">key</i> <i class="arg">value</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">json::write</b> package provides a simple Tcl-only library
for generation of text in the JSON <a href="http://www.json.org/">http://www.json.org/</a> data
exchange format as specified in
RFC 4627 <a href="http://www.ietf.org/rfc/rfc4627.txt">http://www.ietf.org/rfc/rfc4627.txt</a>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::json::write</b> <b class="method">indented</b></a></dt>
<dd><p>This method returns the current state of the indentation setting.</p></dd>
<dt><a name="2"><b class="cmd">::json::write</b> <b class="method">indented</b> <i class="arg">flag</i></a></dt>
<dd><p>This and the method <b class="method">aligned</b> configure the layout of the JSON
generated by the package.</p>
<p>If this <i class="arg">flag</i> is set (default) the package will break the
generated JSON code across lines and indent it according to its inner
structure, with each key of an object on a separate line.</p>
<p>If this flag is not set, the whole JSON object will be written on a
single line, with minimum spacing between all elements.</p></dd>
<dt><a name="3"><b class="cmd">::json::write</b> <b class="method">aligned</b></a></dt>
<dd><p>This method returns the current state of the alignment setting.</p></dd>
<dt><a name="4"><b class="cmd">::json::write</b> <b class="method">aligned</b> <i class="arg">flag</i></a></dt>
<dd><p>This and the method <b class="method">indented</b> configure the layout of the JSON
generated by the package.</p>
<p>If this <i class="arg">flag</i> is set (default) the package ensures that the
values for the keys in an object are vertically aligned with each
other, for a nice table effect. To make this work this also implies
that <b class="variable">indented</b> is set as well.</p>
<p>If this flag is not set, the output is formatted as per the value of
<b class="variable">indented</b>, without trying to align the values for object keys.</p></dd>
<dt><a name="5"><b class="cmd">::json::write</b> <b class="method">string</b> <i class="arg">s</i></a></dt>
<dd><p>This method takes the string <i class="arg">s</i> and returns it properly quoted
for JSON as its result.</p></dd>
<dt><a name="6"><b class="cmd">::json::write</b> <b class="method">array</b> <i class="arg">arg</i>...</a></dt>
<dd><p>This method takes a series of JSON formatted arguments and returns
them as a properly formatted JSON array as its result.</p></dd>
<dt><a name="7"><b class="cmd">::json::write</b> <b class="method">object</b> <i class="arg">key</i> <i class="arg">value</i>...</a></dt>
<dd><p>This method takes a series of key/value arguments, the values already
formatted for JSON, and returns them as a properly formatted JSON
object as its result, with the keys formatted as JSON strings.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">RELATED</a></h2>
<p>To parse json, instead of writing it, see package <b class="package"><a href="json.html">json</a></b>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>json</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_exchange">data exchange</a>, <a href="../../../../index.html#exchange_format">exchange format</a>, <a href="../../../../index.html#javascript">javascript</a>, <a href="../../../../index.html#json">json</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>CGI programming</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2013 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/lambda/lambda.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
<div class='fossil-doc' data-title='lambda - Utility commands for anonymous procedures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">lambda(n) 1 tcllib "Utility commands for anonymous procedures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>lambda - Utility commands for anonymous procedures</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">lambda <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::lambda</b> <i class="arg">arguments</i> <i class="arg">body</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::lambda@</b> <i class="arg">namespace</i> <i class="arg">arguments</i> <i class="arg">body</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides two convenience commands to make the writing of
anonymous procedures, i.e. lambdas more <b class="cmd"><a href="../../../../index.html#proc">proc</a></b>-like. Instead of,
for example, to write</p>
<pre class="doctools_example">
set f {::apply {{x} {
....
}}}
</pre>
<p>with its deep nesting of braces, or</p>
<pre class="doctools_example">
set f [list ::apply {{x y} {
....
}} $value_for_x]
</pre>
<p>with a list command to insert some of the arguments of a partial
application, just write</p>
<pre class="doctools_example">
set f [lambda {x} {
....
}]
</pre>
<p>and</p>
<pre class="doctools_example">
set f [lambda {x y} {
....
} $value_for_x]
</pre>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::lambda</b> <i class="arg">arguments</i> <i class="arg">body</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>The command constructs an anonymous procedure from the list of
arguments, body script and (optional) predefined argument values and
returns a command prefix representing this anonymous procedure.</p>
<p>When invoked the <i class="arg">body</i> is run in a new procedure scope
just underneath the global scope, with the arguments set to the values
supplied at both construction and invokation time.</p></dd>
<dt><a name="2"><b class="cmd">::lambda@</b> <i class="arg">namespace</i> <i class="arg">arguments</i> <i class="arg">body</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>The command constructs an anonymous procedure from the namespace name,
list of arguments, body script and (optional) predefined argument
values and returns a command prefix representing this anonymous
procedure.</p>
<p>When invoked the <i class="arg">body</i> is run in a new procedure scope in
the <i class="arg">namespace</i>, with the arguments set to the values supplied at
both construction and invokation time.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Andreas Kupries</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>lambda</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>apply(n), proc(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#anonymous_procedure">anonymous procedure</a>, <a href="../../../../index.html#callback">callback</a>, <a href="../../../../index.html#command_prefix">command prefix</a>, <a href="../../../../index.html#currying">currying</a>, <a href="../../../../index.html#lambda">lambda</a>, <a href="../../../../index.html#partial_application">partial application</a>, <a href="../../../../index.html#proc">proc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries, BSD licensed</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/lazyset/lazyset.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<div class='fossil-doc' data-title='lazyset - Lazy evaluation for variables and arrays'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">lazyset(n) 1 tcllib "Lazy evaluation for variables and arrays"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>lazyset - Lazy evaluation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">AUTHORS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">lazyset <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::lazyset::variable</b> <span class="opt">?<i class="arg">-array boolean</i>?</span> <span class="opt">?<i class="arg">-appendArgs boolean</i>?</span> <i class="arg">variableName</i> <i class="arg">commandPrefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">lazyset</b> package provides a mechanism for deferring execution
of code until a specific variable or any index of an array is referenced.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::lazyset::variable</b> <span class="opt">?<i class="arg">-array boolean</i>?</span> <span class="opt">?<i class="arg">-appendArgs boolean</i>?</span> <i class="arg">variableName</i> <i class="arg">commandPrefix</i></a></dt>
<dd><p>Arrange for the code specified as <i class="arg">commandPrefix</i> to be executed when
the variable whose name is specified by <i class="arg">variableName</i> is read for
the first time.
If the optional argument <i class="arg">-array boolean</i> is specified as true,
then the variable specified as <i class="arg">variableName</i> is treated as an
array and attempting to read any index of the array causes that
index to be set by the <i class="arg">commandPrefix</i> as they are read.
If the optional argument <i class="arg">-appendArgs boolean</i> is specified as
false, then the variable name and subnames are not appended to the
<i class="arg">commandPrefix</i> before it is evaluated. If the argument
<i class="arg">-appendArgs boolean</i> is not specified or is specified as true
then 1 or 2 additional arguments are appended to the <i class="arg">commandPrefix</i>.
If <i class="arg">-array boolean</i> is specified as true, then 2 arguments are
appended corresponding to the name of the variable and the index,
otherwise 1 argument is appended containing the name of variable.
The <i class="arg">commandPrefix</i> code is run in the same scope as the variable
is read.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
::lazyset::variable page {apply {{name} {
package require http
set token [http::geturl http://www.tcl.tk/]
set data [http::data $token]
return $data
}}}
puts $page
</pre>
<pre class="doctools_example">
::lazyset::variable -array true page {apply {{name index} {
package require http
set token [http::geturl $index]
set data [http::data $token]
return $data
}}}
puts $page(http://www.tcl.tk/)
</pre>
<pre class="doctools_example">
::lazyset::variable -appendArgs false simple {
return -level 0 42
}
puts $simple
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">AUTHORS</a></h2>
<p>Roy Keene</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>utility</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2018 Roy Keene</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ldap/ldap.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
|
<div class='fossil-doc' data-title='ldap - LDAP client'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ldap(n) 1.9.2 tcllib "LDAP client"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ldap - LDAP client</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section3">COMMANDS</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">ldap <span class="opt">?1.9.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ldap::connect</b> <i class="arg">host</i> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::ldap::secure_connect</b> <i class="arg">host</i> <span class="opt">?<i class="arg">port</i>?</span> <span class="opt">?<i class="arg">verify_cert</i>?</span> <span class="opt">?<i class="arg">sni_servername</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::ldap::disconnect</b> <i class="arg">handle</i></a></li>
<li><a href="#4"><b class="cmd">::ldap::starttls</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">cafile</i>?</span> <span class="opt">?<i class="arg">certfile</i>?</span> <span class="opt">?<i class="arg">keyfile</i>?</span> <span class="opt">?<i class="arg">verify_cert</i>?</span> <span class="opt">?<i class="arg">sni_servername</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::ldap::bind</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">name</i>?</span> <span class="opt">?<i class="arg">password</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::ldap::bindSASL</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">name</i>?</span> <span class="opt">?<i class="arg">password</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::ldap::unbind</b> <i class="arg">handle</i></a></li>
<li><a href="#8"><b class="cmd">::ldap::search</b> <i class="arg">handle</i> <i class="arg">baseObject</i> <i class="arg">filterString</i> <i class="arg">attributes</i> <i class="arg">options</i></a></li>
<li><a href="#9"><b class="cmd">::ldap::searchInit</b> <i class="arg">handle</i> <i class="arg">baseObject</i> <i class="arg">filterString</i> <i class="arg">attributes</i> <i class="arg">options</i></a></li>
<li><a href="#10"><b class="cmd">::ldap::searchNext</b> <i class="arg">handle</i></a></li>
<li><a href="#11"><b class="cmd">::ldap::searchEnd</b> <i class="arg">handle</i></a></li>
<li><a href="#12"><b class="cmd">::ldap::modify</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValToReplace</i> <span class="opt">?<i class="arg">attrToDelete</i>?</span> <span class="opt">?<i class="arg">attrValToAdd</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::ldap::modifyMulti</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValToReplace</i> <span class="opt">?<i class="arg">attrValToDelete</i>?</span> <span class="opt">?<i class="arg">attrValToAdd</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::ldap::add</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValueTuples</i></a></li>
<li><a href="#15"><b class="cmd">::ldap::addMulti</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValueTuples</i></a></li>
<li><a href="#16"><b class="cmd">::ldap::delete</b> <i class="arg">handle</i> <i class="arg">dn</i></a></li>
<li><a href="#17"><b class="cmd">::ldap::modifyDN</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">newrdn</i> <span class="opt">?<i class="arg">deleteOld</i>?</span> <span class="opt">?<i class="arg">newSuperior</i>?</span></a></li>
<li><a href="#18"><b class="cmd">::ldap::info</b> <b class="cmd"><a href="../../../../index.html#ip">ip</a></b> <i class="arg">handle</i></a></li>
<li><a href="#19"><b class="cmd">::ldap::info</b> <b class="cmd">bound</b> <i class="arg">handle</i></a></li>
<li><a href="#20"><b class="cmd">::ldap::info</b> <b class="cmd">bounduser</b> <i class="arg">handle</i></a></li>
<li><a href="#21"><b class="cmd">::ldap::info</b> <b class="cmd">connections</b></a></li>
<li><a href="#22"><b class="cmd">::ldap::info</b> <b class="cmd"><a href="../../../../index.html#tls">tls</a></b> <i class="arg">handle</i></a></li>
<li><a href="#23"><b class="cmd">::ldap::info</b> <b class="cmd">saslmechanisms</b> <i class="arg">handle</i></a></li>
<li><a href="#24"><b class="cmd">::ldap::info</b> <b class="cmd"><a href="../control/control.html">control</a></b> <i class="arg">handle</i></a></li>
<li><a href="#25"><b class="cmd">::ldap::info</b> <b class="cmd">extensions</b> <i class="arg">extensions</i></a></li>
<li><a href="#26"><b class="cmd">::ldap::info</b> <b class="cmd">whoami</b> <i class="arg">handle</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">ldap</b> package provides a Tcl-only client library
for the LDAPv3 protocol as specified in
RFC 4511 (<a href="http://www.rfc-editor.org/rfc/rfc4511.txt">http://www.rfc-editor.org/rfc/rfc4511.txt</a>).
It works by opening the standard (or secure) LDAP socket on the
server, and then providing a Tcl API to access the LDAP protocol
commands. All server errors are returned as Tcl errors (thrown) which
must be caught with the Tcl <b class="cmd">catch</b> command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ldap::connect</b> <i class="arg">host</i> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Opens a LDAPv3 connection to the specified <i class="arg">host</i>, at the given
<i class="arg">port</i>, and returns a token for the connection. This token is the
<i class="arg">handle</i> argument for all other commands. If no <i class="arg">port</i> is
specified it will default to <b class="const">389</b>.</p>
<p>The command blocks until the connection has been established, or
establishment definitely failed.</p></dd>
<dt><a name="2"><b class="cmd">::ldap::secure_connect</b> <i class="arg">host</i> <span class="opt">?<i class="arg">port</i>?</span> <span class="opt">?<i class="arg">verify_cert</i>?</span> <span class="opt">?<i class="arg">sni_servername</i>?</span></a></dt>
<dd><p>Like <b class="cmd">::ldap::connect</b>, except that the created connection is
secured by SSL. The port defaults to <b class="const">636</b>. This command
depends on the availability of the package <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, which is a
SSL binding for Tcl. If <b class="package"><a href="../../../../index.html#tls">TLS</a></b> is not available, then this
command will fail.</p>
<p>The command blocks until the connection has been established, or
establishment definitely failed.</p>
<p>If <i class="arg">verify_cert</i> is set to 1, the default, this checks the server certificate against
the known hosts. If <i class="arg">sni_servername</i> is set, the given hostname is used as the
hostname for Server Name Indication in the TLS handshake.</p>
<p>Use <b class="cmd">::tls::init</b> to setup defaults for trusted certificates.</p>
<pre class="doctools_example">
tls::init -cadir /etc/ssl/certs/ca-certificates.crt
</pre>
<p>TLS supports different protocol levels. In common use are the versions 1.0, 1.1 and 1.2.
By default all those versions are offered. If you need to modify the acceptable
protocols, you can change the ::ldap::tlsProtocols list.</p></dd>
<dt><a name="3"><b class="cmd">::ldap::disconnect</b> <i class="arg">handle</i></a></dt>
<dd><p>Closes the ldap connection refered to by the token
<i class="arg">handle</i>. Returns the empty string as its result.</p></dd>
<dt><a name="4"><b class="cmd">::ldap::starttls</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">cafile</i>?</span> <span class="opt">?<i class="arg">certfile</i>?</span> <span class="opt">?<i class="arg">keyfile</i>?</span> <span class="opt">?<i class="arg">verify_cert</i>?</span> <span class="opt">?<i class="arg">sni_servername</i>?</span></a></dt>
<dd><p>Start TLS negotiation on the connection denoted by <i class="arg">handle</i>.
You need to set at least the <i class="arg">cafile</i> argument to a file with trusted certificates, if <i class="arg">verify_cert</i> is 1, which is the default.
The <i class="arg">sni_servername</i> can be used to signal a different hostname during the TLS handshake.
The announced protocols are determined in the same way as <b class="cmd">::ldap::secure_connect</b>.
You can specify a TLS client certificate with the <i class="arg">certfile</i> and <i class="arg">keyfile</i> options.</p></dd>
<dt><a name="5"><b class="cmd">::ldap::bind</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">name</i>?</span> <span class="opt">?<i class="arg">password</i>?</span></a></dt>
<dd><p>This command authenticates the ldap connection refered to by the token
in <i class="arg">handle</i>, with a user name and associated password. It blocks
until a response from the ldap server arrives. Its result is the empty
string.
Both <i class="arg">name</i> and <i class="arg">passwd</i> default to the empty string if they
are not specified.
By leaving out <i class="arg">name</i> and <i class="arg">passwd</i> you can make an anonymous bind to
the ldap server.
You can issue <b class="cmd">::ldap::bind</b> again to bind with different credentials.</p></dd>
<dt><a name="6"><b class="cmd">::ldap::bindSASL</b> <i class="arg">handle</i> <span class="opt">?<i class="arg">name</i>?</span> <span class="opt">?<i class="arg">password</i>?</span></a></dt>
<dd><p>This command uses SASL authentication mechanisms to do a multistage bind.
Its otherwise identical to the standard <b class="cmd">::ldap::bind</b>.
This feature is currently experimental and subject to change. See the documentation
for the <b class="package"><a href="../sasl/sasl.html">SASL</a></b> and the "<b class="file">SASL.txt</b>" in the tcllib CVS repository for
details how to setup and use SASL with openldap.</p></dd>
<dt><a name="7"><b class="cmd">::ldap::unbind</b> <i class="arg">handle</i></a></dt>
<dd><p>This command asks the ldap server to release the last bind done for
the connection refered to by the token in <i class="arg">handle</i>.
The <i class="arg">handle</i> is invalid after the unbind, as the server closes the connection.
So this is effectivly just a more polite disconnect operation.</p></dd>
<dt><a name="8"><b class="cmd">::ldap::search</b> <i class="arg">handle</i> <i class="arg">baseObject</i> <i class="arg">filterString</i> <i class="arg">attributes</i> <i class="arg">options</i></a></dt>
<dd><p>This command performs a LDAP search below the <i class="arg">baseObject</i> tree
using a complex LDAP search expression <i class="arg">filterString</i> and returns
the specified <i class="arg">attributes</i> of all matching objects (DNs). If the
list of <i class="arg">attributes</i> was empty all attributes are returned. The
command blocks until it has received all results.
The valid <i class="arg">options</i> are identical to the options listed for <b class="cmd">::ldap::searchInit</b>.</p>
<p>An example of a search expression is</p>
<pre class="doctools_example">
set filterString "|(cn=Linus*)(sn=Torvalds*)"
</pre>
<p>The return value of the command is a list of nested dictionaries. The
first level keys are object identifiers (DNs), second levels keys are
attribute names. In other words, it is in the form</p>
<pre class="doctools_example">
{dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
</pre>
</dd>
<dt><a name="9"><b class="cmd">::ldap::searchInit</b> <i class="arg">handle</i> <i class="arg">baseObject</i> <i class="arg">filterString</i> <i class="arg">attributes</i> <i class="arg">options</i></a></dt>
<dd><p>This command initiates a LDAP search below the <i class="arg">baseObject</i> tree
using a complex LDAP search expression <i class="arg">filterString</i>.
The search gets the specified <i class="arg">attributes</i> of all matching objects (DNs).
The command itself just starts the search, to retrieve the actual results, use
<b class="cmd">::ldap::searchNext</b>.
A search can be terminated at any time by
<b class="cmd">::ldap::searchEnd</b>. This informs the server that no further results should be sent by sending and ABANDON message
and cleans up the internal state of the search.
Only one <b class="cmd">::ldap::search</b> can be active at a given time, this
includes the introspection commands <b class="cmd">::ldap::info saslmechanisms</b>, <b class="cmd">ldap::info control</b> and
<b class="cmd">ldap::info extensions</b>, which invoke a search internally.
Error responses from the server due to wrong arguments or similar things are returned
with the first <b class="cmd">::ldap::searchNext</b> call and should be checked and dealed with there.
If the list of requested <i class="arg">attributes</i> is empty all attributes will be returned.
The parameter <i class="arg">options</i> specifies the options to be used in the search,
and has the following format:</p>
<pre class="doctools_example">
{-option1 value1 -option2 value2 ... }
</pre>
<p>Following options are available:</p>
<dl class="doctools_options">
<dt><b class="option">-scope</b> base one sub</dt>
<dd><p>Control the scope of the search to be one of <b class="const">base</b>, <b class="const">one</b>, or <b class="const">sub</b>, to specify a base
object, one-level or subtree search. The default is <b class="const">sub</b>.</p></dd>
<dt><b class="option">-derefaliases</b> never search find always</dt>
<dd><p>Control how aliases dereferencing is done. Should be one of <b class="const">never</b>, <b class="const">always</b>, <b class="const">search</b>, or <b class="const">find</b> to
specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or
dereferenced only when locating the base object for the search.
The default is to never dereference aliases.</p></dd>
<dt><b class="option">-sizelimit</b> num</dt>
<dd><p>Determines the maximum number of entries to return in a search. If specified as
0 no limit is enforced. The server may enforce a configuration dependent sizelimit,
which may be lower than the one given by this option. The default is 0, no limit.</p></dd>
<dt><b class="option">-timelimit</b> seconds</dt>
<dd><p>Asks the server to use a timelimit of <i class="arg">seconds</i> for the search. Zero means no
limit. The default is 0, no limit.</p></dd>
<dt><b class="option">-attrsonly</b> boolean</dt>
<dd><p>If set to 1 only the attribute names but not the values will be present in the search result.
The default is to retrieve attribute names and values.</p></dd>
<dt><b class="option">-referencevar</b> varname</dt>
<dd><p>If set the search result reference LDAPURIs, if any, are returned in the given variable.
The caller can than decide to follow those references and query other LDAP servers for
further results.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::ldap::searchNext</b> <i class="arg">handle</i></a></dt>
<dd><p>This command returns the next entry from a LDAP search initiated
by <b class="cmd">::ldap::searchInit</b>. It returns only after a new result is received
or when no further results are available, but takes care to keep
the event loop alive.
The returned entry is a list with
two elements: the first is the DN of the entry, the second is the
list of attributes and values, under the format:</p>
<pre class="doctools_example">
dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
</pre>
<p>The <b class="cmd">::ldap::searchNext</b> command returns an empty list at the
end of the search.</p></dd>
<dt><a name="11"><b class="cmd">::ldap::searchEnd</b> <i class="arg">handle</i></a></dt>
<dd><p>This command terminates a LDAP search initiated
by <b class="cmd">::ldap::searchInit</b>. It also cleans up
the internal state so a new search can be initiated.
If the client has not yet received all results, the client
sends an ABANDON message to inform the server that no
further results for the previous search should to be sent.</p></dd>
<dt><a name="12"><b class="cmd">::ldap::modify</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValToReplace</i> <span class="opt">?<i class="arg">attrToDelete</i>?</span> <span class="opt">?<i class="arg">attrValToAdd</i>?</span></a></dt>
<dd><p>This command modifies the object <i class="arg">dn</i> on the ldap server we are
connected to via <i class="arg">handle</i>. It replaces attributes with new values,
deletes attributes, and adds new attributes with new values.
All arguments are dictionaries mapping attribute names to values. The
optional arguments default to the empty dictionary, which means that
no attributes will be deleted nor added.</p>
<dl class="doctools_arguments">
<dt>dictionary <i class="arg">attrValToReplace</i> (in)</dt>
<dd><p>No attributes will be changed if this argument is empty. The
dictionary contains the new attributes and their values. They
<em>replace all</em> attributes known to the object.</p></dd>
<dt>dictionary <i class="arg">attrToDelete</i> (in)</dt>
<dd><p>No attributes will be deleted if this argument is empty. The
dictionary values are restrictions on the deletion. An attribute
listed here will be deleted if and only if its current value at the
server matches the value specified in the dictionary, or if the value
in the dictionary is the empty string.</p></dd>
<dt>dictionary <i class="arg">attrValToAdd</i> (in)</dt>
<dd><p>No attributes will be added if this argument is empty. The dictionary
values are the values for the new attributes.</p></dd>
</dl>
<p>The command blocks until all modifications have completed. Its result
is the empty string.</p></dd>
<dt><a name="13"><b class="cmd">::ldap::modifyMulti</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValToReplace</i> <span class="opt">?<i class="arg">attrValToDelete</i>?</span> <span class="opt">?<i class="arg">attrValToAdd</i>?</span></a></dt>
<dd><p>This command modifies the object <i class="arg">dn</i> on the ldap server we are
connected to via <i class="arg">handle</i>. It replaces attributes with new values,
deletes attributes, and adds new attributes with new values.
All arguments are lists with the format:</p>
<pre class="doctools_example">
attr1 {val11 val12 ...} attr2 {val21...} ...
</pre>
<p>where each value list may be empty for deleting all attributes.
The optional arguments default to empty lists of attributes to
delete and to add.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">attrValToReplace</i> (in)</dt>
<dd><p>No attributes will be changed if this argument is empty. The
dictionary contains the new attributes and their values. They
<em>replace all</em> attributes known to the object.</p></dd>
<dt>list <i class="arg">attrValToDelete</i> (in)</dt>
<dd><p>No attributes will be deleted if this argument is empty. If no
value is specified, the whole set of values for an attribute
will be deleted.</p></dd>
<dt>list <i class="arg">attrValToAdd</i> (in)</dt>
<dd><p>No attributes will be added if this argument is empty.</p></dd>
</dl>
<p>The command blocks until all modifications have completed. Its result
is the empty string.</p></dd>
<dt><a name="14"><b class="cmd">::ldap::add</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValueTuples</i></a></dt>
<dd><p>This command creates a new object using the specified <i class="arg">dn</i>. The
attributes of the new object are set to the values in the list
<i class="arg">attrValueTuples</i>.
Multiple valuated attributes may be specified using multiple tuples.
The command blocks until the operation has completed. Its result
is the empty string.</p></dd>
<dt><a name="15"><b class="cmd">::ldap::addMulti</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">attrValueTuples</i></a></dt>
<dd><p>This command is the preferred one to create
a new object using the specified <i class="arg">dn</i>. The
attributes of the new object are set to the values in the dictionary
<i class="arg">attrValueTuples</i> (which is keyed by the attribute names).
Each tuple is a list containing multiple values.
The command blocks until the operation has completed. Its result
is the empty string.</p></dd>
<dt><a name="16"><b class="cmd">::ldap::delete</b> <i class="arg">handle</i> <i class="arg">dn</i></a></dt>
<dd><p>This command removes the object specified by <i class="arg">dn</i>, and all its
attributes from the server.
The command blocks until the operation has completed. Its result
is the empty string.</p></dd>
<dt><a name="17"><b class="cmd">::ldap::modifyDN</b> <i class="arg">handle</i> <i class="arg">dn</i> <i class="arg">newrdn</i> <span class="opt">?<i class="arg">deleteOld</i>?</span> <span class="opt">?<i class="arg">newSuperior</i>?</span></a></dt>
<dd><p>This command moves or copies the object specified by <i class="arg">dn</i>
to a new location in the tree of object. This location is
specified by <i class="arg">newrdn</i>, a <em>relative</em> designation,
or by <i class="arg">newrdn</i> and <i class="arg">newSuperior</i>, a <em>absolute</em> designation.
The optional argument <i class="arg">deleteOld</i> defaults to <b class="const">true</b>,
i.e. a move operation. If <i class="arg">deleteOld</i> is not set, then the
operation will create a copy of <i class="arg">dn</i> in the new location.
The optional argument <i class="arg">newSuperior</i> defaults an empty string,
meaning that the object must not be relocated in another branch of
the tree. If this argument is given, the argument <i class="arg">deleteOld</i>
must be specified also.
The command blocks until the operation has completed. Its result
is the empty string.</p></dd>
<dt><a name="18"><b class="cmd">::ldap::info</b> <b class="cmd"><a href="../../../../index.html#ip">ip</a></b> <i class="arg">handle</i></a></dt>
<dd><p>This command returns the IP address of the remote LDAP server the handle is connected to.</p></dd>
<dt><a name="19"><b class="cmd">::ldap::info</b> <b class="cmd">bound</b> <i class="arg">handle</i></a></dt>
<dd><p>This command returns 1 if a handle has successfully completed a <b class="cmd">::ldap::bind</b>.
If no bind was done or it failed, a 0 is returned.</p></dd>
<dt><a name="20"><b class="cmd">::ldap::info</b> <b class="cmd">bounduser</b> <i class="arg">handle</i></a></dt>
<dd><p>This command returns the username used in the bind operation if a handle has successfully completed a <b class="cmd">::ldap::bind</b>.
If no bound was done or it failed, an empty string is returned.</p></dd>
<dt><a name="21"><b class="cmd">::ldap::info</b> <b class="cmd">connections</b></a></dt>
<dd><p>This command returns all currently existing ldap connection handles.</p></dd>
<dt><a name="22"><b class="cmd">::ldap::info</b> <b class="cmd"><a href="../../../../index.html#tls">tls</a></b> <i class="arg">handle</i></a></dt>
<dd><p>This command returns 1 if the ldap connection <i class="arg">handle</i> used TLS/SSL for
connection via <b class="cmd">ldap::secure_connect</b> or completed <b class="cmd">ldap::starttls</b>, 0 otherwise.</p></dd>
<dt><a name="23"><b class="cmd">::ldap::info</b> <b class="cmd">saslmechanisms</b> <i class="arg">handle</i></a></dt>
<dd><p>Return the supported SASL mechanisms advertised by the server. Only valid in a
bound state (anonymous or other).</p></dd>
<dt><a name="24"><b class="cmd">::ldap::info</b> <b class="cmd"><a href="../control/control.html">control</a></b> <i class="arg">handle</i></a></dt>
<dd><p>Return the supported controls advertised by the server as a list of OIDs. Only valid in a bound state.
This is currently experimental and subject to change.</p></dd>
<dt><a name="25"><b class="cmd">::ldap::info</b> <b class="cmd">extensions</b> <i class="arg">extensions</i></a></dt>
<dd><p>Returns the supported LDAP extensions as list of OIDs. Only valid in a bound state.
This is currently experimental and subject to change.</p></dd>
<dt><a name="26"><b class="cmd">::ldap::info</b> <b class="cmd">whoami</b> <i class="arg">handle</i></a></dt>
<dd><p>Returns authzId for the current connection. This implements the RFC 4532
protocol extension.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<p>A small example, extracted from the test application coming with this
code.</p>
<pre class="doctools_example">
package require ldap
# Connect, bind, add a new object, modify it in various ways
set handle [ldap::connect localhost 9009]
set dn "cn=Manager, o=University of Michigan, c=US"
set pw secret
ldap::bind $handle $dn $pw
set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
ldap::add $handle $dn {
objectClass OpenLDAPperson
cn {Test User}
mail [email protected]
uid testuid
sn User
telephoneNumber +31415926535
telephoneNumber +27182818285
}
set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
ldap::addMulti $handle $dn {
objectClass {OpenLDAPperson}
cn {{Anotther User}}
mail {[email protected]}
uid {testuid}
sn {User}
telephoneNumber {+31415926535 +27182818285}
}
# Replace all attributes
ldap::modify $handle $dn [list drink icetea uid JOLO]
# Add some more
ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]
# Delete
ldap::modify $handle $dn {} [list drink water pager ""]
# Move
ldap::modifyDN $handle $dn "cn=Tester"
# Kill the test object, and shut the connection down.
set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
ldap::delete $handle $dn
ldap::unbind $handle
ldap::disconnect $handle
</pre>
<p>And a another example, a simple query, and processing the
results.</p>
<pre class="doctools_example">
package require ldap
set handle [ldap::connect ldap.acme.com 389]
ldap::bind $handle
set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
foreach result $results {
foreach {object attributes} $result break
# The processing here is similar to what 'parray' does.
# I.e. finding the longest attribute name and then
# generating properly aligned output listing all attributes
# and their values.
set width 0
set sortedAttribs {}
foreach {type values} $attributes {
if {[string length $type] > $width} {
set width [string length $type]
}
lappend sortedAttribs [list $type $values]
}
puts "object='$object'"
foreach sortedAttrib $sortedAttribs {
foreach {type values} $sortedAttrib break
foreach value $values {
regsub -all "\[\x01-\x1f\]" $value ? value
puts [format " %-${width}s %s" $type $value]
}
}
puts ""
}
ldap::unbind $handle
ldap::disconnect $handle
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ldap</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#directory_access">directory access</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#ldap">ldap</a>, <a href="../../../../index.html#ldap_client">ldap client</a>, <a href="../../../../index.html#protocol">protocol</a>, <a href="../../../../index.html#rfc_2251">rfc 2251</a>, <a href="../../../../index.html#rfc_4511">rfc 4511</a>, <a href="../../../../index.html#x_500">x.500</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Andreas Kupries <[email protected]><br>
Copyright © 2004 Jochen Loewer <[email protected]><br>
Copyright © 2006 Michael Schlenker <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ldap/ldapx.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
|
<div class='fossil-doc' data-title='ldapx - LDAP extended object interface'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ldapx(n) 1.1 tcllib "LDAP extended object interface"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ldapx - LDAP extended object interface</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a></li>
<li class="doctools_section"><a href="#section3">ENTRY CLASS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Entry Instance Data</a></li>
<li class="doctools_subsection"><a href="#subsection2">Entry Options</a></li>
<li class="doctools_subsection"><a href="#subsection3">Methods for all kinds of entries</a></li>
<li class="doctools_subsection"><a href="#subsection4">Methods for standard entries only</a></li>
<li class="doctools_subsection"><a href="#subsection5">Methods for change entries only</a></li>
<li class="doctools_subsection"><a href="#subsection6">Entry Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">LDAP CLASS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection7">Ldap Instance Data</a></li>
<li class="doctools_subsection"><a href="#subsection8">Ldap Options</a></li>
<li class="doctools_subsection"><a href="#subsection9">Ldap Methods</a></li>
<li class="doctools_subsection"><a href="#subsection10">Ldap Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">LDIF CLASS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection11">Ldif Instance Data</a></li>
<li class="doctools_subsection"><a href="#subsection12">Ldif Options</a></li>
<li class="doctools_subsection"><a href="#subsection13">Ldif Methods</a></li>
<li class="doctools_subsection"><a href="#subsection14">Ldif Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">References</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">ldapx <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><i class="arg">e</i> <b class="method">reset</b></a></li>
<li><a href="#2"><i class="arg">e</i> <b class="method">dn</b> <span class="opt">?<i class="arg">newdn</i>?</span></a></li>
<li><a href="#3"><i class="arg">e</i> <b class="method">rdn</b></a></li>
<li><a href="#4"><i class="arg">e</i> <b class="method">superior</b></a></li>
<li><a href="#5"><i class="arg">e</i> <b class="method">print</b></a></li>
<li><a href="#6"><i class="arg">se</i> <b class="method">isempty</b></a></li>
<li><a href="#7"><i class="arg">se</i> <b class="method">get</b> <i class="arg">attr</i></a></li>
<li><a href="#8"><i class="arg">se</i> <b class="method">get1</b> <i class="arg">attr</i></a></li>
<li><a href="#9"><i class="arg">se</i> <b class="method">set</b> <i class="arg">attr</i> <i class="arg">values</i></a></li>
<li><a href="#10"><i class="arg">se</i> <b class="method">set1</b> <i class="arg">attr</i> <i class="arg">value</i></a></li>
<li><a href="#11"><i class="arg">se</i> <b class="method">add</b> <i class="arg">attr</i> <i class="arg">values</i></a></li>
<li><a href="#12"><i class="arg">se</i> <b class="method">add1</b> <i class="arg">attr</i> <i class="arg">value</i></a></li>
<li><a href="#13"><i class="arg">se</i> <b class="method">del</b> <i class="arg">attr</i> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#14"><i class="arg">se</i> <b class="method">del1</b> <i class="arg">attr</i> <i class="arg">value</i></a></li>
<li><a href="#15"><i class="arg">se</i> <b class="method">getattr</b></a></li>
<li><a href="#16"><i class="arg">se</i> <b class="method">getall</b></a></li>
<li><a href="#17"><i class="arg">se</i> <b class="method">setall</b> <i class="arg">avpairs</i></a></li>
<li><a href="#18"><i class="arg">se</i> <b class="method">backup</b> <span class="opt">?<i class="arg">other</i>?</span></a></li>
<li><a href="#19"><i class="arg">se</i> <b class="method">swap</b></a></li>
<li><a href="#20"><i class="arg">se</i> <b class="method">restore</b> <span class="opt">?<i class="arg">other</i>?</span></a></li>
<li><a href="#21"><i class="arg">se</i> <b class="method">apply</b> <i class="arg">centry</i></a></li>
<li><a href="#22"><i class="arg">ce</i> <b class="method">change</b> <span class="opt">?<i class="arg">new</i>?</span></a></li>
<li><a href="#23"><i class="arg">ce</i> <b class="method">diff</b> <i class="arg">new</i> <span class="opt">?<i class="arg">old</i>?</span></a></li>
<li><a href="#24"><i class="arg">la</i> <b class="method">error</b> <span class="opt">?<i class="arg">newmsg</i>?</span></a></li>
<li><a href="#25"><i class="arg">la</i> <b class="method">connect</b> <i class="arg">url</i> <span class="opt">?<i class="arg">binddn</i>?</span> <span class="opt">?<i class="arg">bindpw</i>?</span></a></li>
<li><a href="#26"><i class="arg">la</i> <b class="method">disconnect</b></a></li>
<li><a href="#27"><i class="arg">la</i> <b class="method">traverse</b> <i class="arg">base</i> <i class="arg">filter</i> <i class="arg">attrs</i> <i class="arg">entry</i> <i class="arg">body</i></a></li>
<li><a href="#28"><i class="arg">la</i> <b class="method">search</b> <i class="arg">base</i> <i class="arg">filter</i> <i class="arg">attrs</i></a></li>
<li><a href="#29"><i class="arg">la</i> <b class="method">read</b> <i class="arg">base</i> <i class="arg">filter</i> <i class="arg">entry</i> ... <i class="arg">entry</i></a></li>
<li><a href="#30"><i class="arg">la</i> <b class="method">commit</b> <i class="arg">entry</i> ... <i class="arg">entry</i></a></li>
<li><a href="#31"><i class="arg">li</i> <b class="method">channel</b> <i class="arg">chan</i></a></li>
<li><a href="#32"><i class="arg">li</i> <b class="method">error</b> <span class="opt">?<i class="arg">newmsg</i>?</span></a></li>
<li><a href="#33"><i class="arg">li</i> <b class="method">read</b> <i class="arg">entry</i></a></li>
<li><a href="#34"><i class="arg">li</i> <b class="method">write</b> <i class="arg">entry</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">ldapx</b> package provides an extended Tcl interface to
LDAP directores and LDIF files. The <b class="package">ldapx</b> package is built
upon the <b class="package"><a href="ldap.html">ldap</a></b> package in order to get low level LDAP access.</p>
<p>LDAP access is compatible with RFC 2251
(<a href="http://www.rfc-editor.org/rfc/rfc2251.txt">http://www.rfc-editor.org/rfc/rfc2251.txt</a>).
LDIF access is compatible with RFC 2849
(<a href="http://www.rfc-editor.org/rfc/rfc2849.txt">http://www.rfc-editor.org/rfc/rfc2849.txt</a>).</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<p>The <b class="package">ldapx</b> package provides objects to interact with LDAP
directories and LDIF files with an easy to use programming interface.
It implements three <b class="package"><a href="../snit/snit.html">snit</a></b>::type classes.</p>
<p>The first class, <b class="class">entry</b>, is used to store individual entries.
Two different formats are available: the first one is the
<em>standard</em> format, which represents an entry as read from the
directory. The second format is the <em>change</em> format, which
stores differences between two standard entries.</p>
<p>With these entries, an application which wants to modify an entry
in a directory needs to read a (standard) entry from the directory,
create a fresh copy into a new (standard) entry, modify the new
copy, and then compute the differences between the two entries into
a new (change) entry, which may be commited to the directory.</p>
<p>Such kinds of modifications are so heavily used that standard entries
may contain their own copy of the original data. With such a copy,
the application described above reads a (standard) entry from the
directory, backs-up the original data, modifies the entry, and
computes the differences between the entry and its backup. These
differences are then commited to the directory.</p>
<p>Methods are provided to compute differences between two entries,
to apply differences to an entry in order to get a new entry, and
to get or set attributes in standard entries.</p>
<p>The second class is the <b class="class">ldap</b> class. It provides a method
to <b class="method">connect</b> and bind to the directory with a uniform access
to LDAP and LDAPS through an URL (ldap:// or ldaps://). The
<b class="method">traverse</b> control structure executes a body for each entry
found in the directory. The <b class="method">commit</b> method applies some
changes (represented as <b class="class">entry</b> objects) to the directory.
Since some attributes are represented as UTF-8 strings, the option
<b class="option">-utf8</b> controls which attributes must be converted and
which attributes must not be converted.</p>
<p>The last class is the <b class="class">ldif</b> class. It provides a method to
associate a standard Tcl <em>channel</em> to an LDIF object. Then,
methods <b class="method">read</b> and <b class="method">write</b> read or write entries from
or to this channel. This class can make use of standard or change
entries, according to the type of the LDIF file which may contain
either standard entries or change entries (but not both at the same
time). The option <b class="option">-utf8</b> works exactly as with the
<b class="class">ldap</b> class.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">ENTRY CLASS</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Entry Instance Data</a></h3>
<p>An instance of the <b class="class">entry</b> class keeps the following data:</p>
<dl class="doctools_definitions">
<dt>dn</dt>
<dd><p>This is the DN of the entry, which includes (in LDAP
terminology) the RDN (relative DN) and the Superior parts.</p></dd>
<dt>format</dt>
<dd><p>The format may be <em>uninitialized</em> (entry not yet used),
<em>standard</em> or <em>change</em>. Most methods check the
format of the entry, which can be reset with the
<b class="method">reset</b> method.</p></dd>
<dt>attrvals</dt>
<dd><p>In a <em>standard</em> entry, this is where the attributes
and associated values are stored. Many methods provide
access to these informations. Attribute names are always
converted into lower case.</p></dd>
<dt>backup</dt>
<dd><p>In a <em>standard</em> entry, the backup may contain a copy
of the dn and all attributes and values. Methods
<b class="method">backup</b> and <b class="method">restore</b> manipulate these data,
and method <b class="method">diff</b> may use this backup.</p></dd>
<dt>change</dt>
<dd><p>In a <em>change</em> entry, these data represent the
modifications. Such modifications are handled by specialized
methods such as <b class="method">apply</b> or <b class="method">commit</b>.
Detailed format should not be used directly by programs.</p>
<p>Internally, modifications are represented as a list of
elements, each element has one of the following formats
(which match the corresponding LDAP operations):</p>
<ol class="doctools_enumerated">
<li><p>{<b class="const">add</b> {attr1 {val1...valn} attr2 {...} ...}}</p>
<p>Addition of a new entry.</p></li>
<li><p>{<b class="const">mod</b> {modop {attr1 <span class="opt">?val1...valn?</span>} attr2 ...} {modop ...} ...}</p>
<p>Modification of one or more attributes and/or values,
where <modop> can be <b class="const">modadd</b>, <b class="const">moddel</b>
or <b class="const">modrepl</b> (see the LDAP modify operation).</p></li>
<li><p>{<b class="const">del</b>}</p>
<p>Deletion of an old entry.</p></li>
<li><p>{<b class="const">modrdn</b> newrdn deleteoldrdn <span class="opt">?newsuperior?</span>}</p>
<p>Renaming of an entry.</p></li>
</ol></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Entry Options</a></h3>
<p>No option is defined by this class.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Methods for all kinds of entries</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><i class="arg">e</i> <b class="method">reset</b></a></dt>
<dd><p>This method resets the entry to an uninitialized state.</p></dd>
<dt><a name="2"><i class="arg">e</i> <b class="method">dn</b> <span class="opt">?<i class="arg">newdn</i>?</span></a></dt>
<dd><p>This method returns the current DN of the entry. If the
optional <i class="arg">newdn</i> is specified, it replaces the current
DN of the entry.</p></dd>
<dt><a name="3"><i class="arg">e</i> <b class="method">rdn</b></a></dt>
<dd><p>This method returns the RDN part of the DN of the entry.</p></dd>
<dt><a name="4"><i class="arg">e</i> <b class="method">superior</b></a></dt>
<dd><p>This method returns the superior part of the DN of the entry.</p></dd>
<dt><a name="5"><i class="arg">e</i> <b class="method">print</b></a></dt>
<dd><p>This method returns the entry as a string ready to be printed.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Methods for standard entries only</a></h3>
<p>In all methods, attribute names are converted in lower case.</p>
<dl class="doctools_definitions">
<dt><a name="6"><i class="arg">se</i> <b class="method">isempty</b></a></dt>
<dd><p>This method returns 1 if the entry is empty (i.e. without
any attribute).</p></dd>
<dt><a name="7"><i class="arg">se</i> <b class="method">get</b> <i class="arg">attr</i></a></dt>
<dd><p>This method returns all values of the attribute <i class="arg">attr</i>,
or the empty list if the attribute is not fond.</p></dd>
<dt><a name="8"><i class="arg">se</i> <b class="method">get1</b> <i class="arg">attr</i></a></dt>
<dd><p>This method returns the first value of the attribute.</p></dd>
<dt><a name="9"><i class="arg">se</i> <b class="method">set</b> <i class="arg">attr</i> <i class="arg">values</i></a></dt>
<dd><p>This method sets the values (list <i class="arg">values</i>) of the
attribute <i class="arg">attr</i>. If the list is empty, this method
deletes all</p></dd>
<dt><a name="10"><i class="arg">se</i> <b class="method">set1</b> <i class="arg">attr</i> <i class="arg">value</i></a></dt>
<dd><p>This method sets the values of the attribute <i class="arg">attr</i> to
be an unique value <i class="arg">value</i>. Previous values, if any,
are replaced by the new value.</p></dd>
<dt><a name="11"><i class="arg">se</i> <b class="method">add</b> <i class="arg">attr</i> <i class="arg">values</i></a></dt>
<dd><p>This method adds all elements the list <i class="arg">values</i> to the
values of the attribute <i class="arg">attr</i>.</p></dd>
<dt><a name="12"><i class="arg">se</i> <b class="method">add1</b> <i class="arg">attr</i> <i class="arg">value</i></a></dt>
<dd><p>This method adds a single value given by the parameter
<i class="arg">value</i> to the attribute <i class="arg">attr</i>.</p></dd>
<dt><a name="13"><i class="arg">se</i> <b class="method">del</b> <i class="arg">attr</i> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>If the optional list <i class="arg">values</i> is specified, this method
deletes all specified values from the attribute <i class="arg">attr</i>.
If the argument <i class="arg">values</i> is not specified, this method
deletes all values.</p></dd>
<dt><a name="14"><i class="arg">se</i> <b class="method">del1</b> <i class="arg">attr</i> <i class="arg">value</i></a></dt>
<dd><p>This method deletes a unique <i class="arg">value</i> from the attribute
<i class="arg">attr</i>.</p></dd>
<dt><a name="15"><i class="arg">se</i> <b class="method">getattr</b></a></dt>
<dd><p>This method returns all attributes names.</p></dd>
<dt><a name="16"><i class="arg">se</i> <b class="method">getall</b></a></dt>
<dd><p>This method returns all attributes and values from the
entry, packed in a list of pairs <attribute, list of values>.</p></dd>
<dt><a name="17"><i class="arg">se</i> <b class="method">setall</b> <i class="arg">avpairs</i></a></dt>
<dd><p>This method sets at once all attributes and values. The
format of the <i class="arg">avpairs</i> argument is the same as the one
returned by method <b class="method">getall</b>.</p></dd>
<dt><a name="18"><i class="arg">se</i> <b class="method">backup</b> <span class="opt">?<i class="arg">other</i>?</span></a></dt>
<dd><p>This method stores in an <i class="arg">other</i> standard entry object
a copy of the current DN and attributes/values. If the
optional <i class="arg">other</i> argument is not specified, copy is
done in the current entry (in a specific place, see section
<span class="sectref"><a href="#section2">OVERVIEW</a></span>).</p></dd>
<dt><a name="19"><i class="arg">se</i> <b class="method">swap</b></a></dt>
<dd><p>This method swaps the current and backup contexts of the
entry.</p></dd>
<dt><a name="20"><i class="arg">se</i> <b class="method">restore</b> <span class="opt">?<i class="arg">other</i>?</span></a></dt>
<dd><p>If the optional argument <i class="arg">other</i> is given, which must
then be a <em>standard</em> entry, this method restores the
current entry into the <i class="arg">other</i> entry. If the argument
<i class="arg">other</i> argument is not specified, this methods restores
the current entry from its internal backup (see section
<span class="sectref"><a href="#section2">OVERVIEW</a></span>).</p></dd>
<dt><a name="21"><i class="arg">se</i> <b class="method">apply</b> <i class="arg">centry</i></a></dt>
<dd><p>This method applies changes defined in the <i class="arg">centry</i>
argument, which must be a <em>change</em> entry.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Methods for change entries only</a></h3>
<dl class="doctools_definitions">
<dt><a name="22"><i class="arg">ce</i> <b class="method">change</b> <span class="opt">?<i class="arg">new</i>?</span></a></dt>
<dd><p>If the optional argument <i class="arg">new</i> is specified, this method
modifies the change list (see subsection <span class="sectref"><a href="#subsection1">Entry Instance Data</a></span> for
the exact format). In both cases, current change list is
returned.
Warning: values returned by this method should only be used
by specialized methods such as <b class="method">apply</b> or
<b class="method">commit</b>.</p></dd>
<dt><a name="23"><i class="arg">ce</i> <b class="method">diff</b> <i class="arg">new</i> <span class="opt">?<i class="arg">old</i>?</span></a></dt>
<dd><p>This method computes the differences between the <i class="arg">new</i>
and <i class="arg">old</i> entries under the form of a change list, and
stores this list into the current <em>change</em> entry. If
the optional argument <i class="arg">old</i> is not specified, difference
is computed from the entry and its internal backup (see
section <span class="sectref"><a href="#section2">OVERVIEW</a></span>). Return value is the computed
change list.</p></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Entry Example</a></h3>
<pre class="doctools_example">
package require ldapx
#
# Create an entry and fill it as a standard entry with
# attributes and values
#
::ldapx::entry create e
e dn "uid=joe,ou=people,o=mycomp"
e set1 "uid" "joe"
e set "objectClass" {person anotherObjectClass}
e set1 "givenName" "Joe"
e set1 "sn" "User"
e set "telephoneNumber" {+31415926535 +2182818}
e set1 "anotherAttr" "This is a beautiful day, isn't it?"
puts stdout "e\n[e print]"
#
# Create a second entry as a backup of the first, and
# make some changes on it.
# Entry is named automatically by snit.
#
set b [::ldapx::entry create %AUTO%]
e backup $b
puts stdout "$b\n[$b print]"
$b del "anotherAttr"
$b del1 "objectClass" "anotherObjectClass"
#
# Create a change entry, a compute differences between first
# and second entry.
#
::ldapx::entry create c
c diff e $b
puts stdout "$c\n[$c print]"
#
# Apply changes to first entry. It should be the same as the
# second entry, now.
#
e apply c
::ldapx::entry create nc
nc diff e $b
puts stdout "nc\n[nc print]"
#
# Clean-up
#
e destroy
$b destroy
c destroy
nc destroy
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">LDAP CLASS</a></h2>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Ldap Instance Data</a></h3>
<p>An instance of the <b class="class">ldap</b> class keeps the following data:</p>
<dl class="doctools_definitions">
<dt>channel</dt>
<dd><p>This is the channel used by the <b class="package"><a href="ldap.html">ldap</a></b> package for
communication with the LDAP server.</p></dd>
<dt>lastError</dt>
<dd><p>This variable contains the error message which appeared in
the last method of the <b class="class">ldap</b> class (this string is
modified in nearly all methods). The <b class="method">error</b> method
may be used to fetch this message.</p></dd>
</dl>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Ldap Options</a></h3>
<p>A first set of options of the <b class="class">ldap</b> class is used during
search operations (methods <b class="method">traverse</b>, <b class="method">search</b> and
<b class="method">read</b>, see below).</p>
<dl class="doctools_options">
<dt><b class="option">-scope</b> <b class="const">base</b>|<b class="const">one</b>|<b class="const">sub</b></dt>
<dd><p>Specify the scope of the LDAP search to be one of
<b class="const">base</b>, <b class="const">one</b> or <b class="const">sub</b> to specify
a base object, one-level or subtree search.</p>
<p>The default is <b class="const">sub</b>.</p></dd>
<dt><b class="option">-derefaliases</b> <b class="const">never</b>|<b class="const">seach</b>|<b class="const">find</b>|<b class="const">always</b></dt>
<dd><p>Specify how aliases dereferencing is handled:
<b class="const">never</b> is used to specify that aliases are never derefenced,
<b class="const">always</b> that aliases are always derefenced,
<b class="const">search</b> that aliases are dereferenced when searching,
or <b class="const">find</b> that aliases are dereferenced only when
locating the base object for the search.</p>
<p>The default is <b class="const">never</b>.</p></dd>
<dt><b class="option">-sizelimit</b> integer</dt>
<dd><p>Specify the maximum number of entries to be retreived
during a search. A value of <b class="const">0</b> means no limit.</p>
<p>Default is <b class="const">0</b>.</p></dd>
<dt><b class="option">-timelimit</b> integer</dt>
<dd><p>Specify the time limit for a search to complete.
A value of <b class="const">0</b> means no limit.</p>
<p>Default is <b class="const">0</b>.</p></dd>
<dt><b class="option">-attrsonly</b> <b class="const">0</b>|<b class="const">1</b></dt>
<dd><p>Specify if only attribute names are to be retrieved (value
<b class="const">1</b>). Normally (value <b class="const">0</b>), attribute values
are also retrieved.</p>
<p>Default is <b class="const">0</b>.</p></dd>
</dl>
<p>The last option is used when getting entries or committing changes
in the directory:</p>
<dl class="doctools_options">
<dt><b class="option">-utf8</b> pattern-yes pattern-no</dt>
<dd><p>Specify which attribute values are encoded in UTF-8. This
information is specific to the LDAP schema in use by the
application, since some attributes such as jpegPhoto, for
example, are not encoded in UTF-8. This option takes the
form of a list with two regular expressions suitable for
the <b class="cmd">regexp</b> command (anchored by ^ and $).
The first specifies which attribute names are to be UTF-8
encoded, and the second selects, among those, the attribute
names which will not be UTF-8 encoded. It is thus possible
to say: convert all attributes, except jpegPhoto.</p>
<p>Default is {{.*} {}}, meaning: all attributes are converted,
without exception.</p></dd>
</dl>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Ldap Methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="24"><i class="arg">la</i> <b class="method">error</b> <span class="opt">?<i class="arg">newmsg</i>?</span></a></dt>
<dd><p>This method returns the error message that occurred in the
last call to a <b class="class">ldap</b> class method. If the optional
argument <i class="arg">newmsg</i> is supplied, it becomes the last
error message.</p></dd>
<dt><a name="25"><i class="arg">la</i> <b class="method">connect</b> <i class="arg">url</i> <span class="opt">?<i class="arg">binddn</i>?</span> <span class="opt">?<i class="arg">bindpw</i>?</span></a></dt>
<dd><p>This method connects to the LDAP server using given URL
(which can be of the form <a href="ldap://host:port">ldap://host:port</a> or
<a href="ldaps://host:port">ldaps://host:port</a>). If an optional <i class="arg">binddn</i>
argument is given together with the <i class="arg">bindpw</i> argument,
the <b class="method">connect</b> binds to the LDAP server using the
specified DN and password.</p></dd>
<dt><a name="26"><i class="arg">la</i> <b class="method">disconnect</b></a></dt>
<dd><p>This method disconnects (and unbinds, if necessary) from
the LDAP server.</p></dd>
<dt><a name="27"><i class="arg">la</i> <b class="method">traverse</b> <i class="arg">base</i> <i class="arg">filter</i> <i class="arg">attrs</i> <i class="arg">entry</i> <i class="arg">body</i></a></dt>
<dd><p>This method is a new control structure. It searches the
LDAP directory from the specified base DN (given by the
<i class="arg">base</i> argument) and selects entries based on the
argument <i class="arg">filter</i>. For each entry found, this method
fetches attributes specified by the <i class="arg">attrs</i> argument
(or all attributes if it is an empty list), stores them in
the <i class="arg">entry</i> instance of class <b class="class">entry</b> and executes
the script defined by the argument <i class="arg">body</i>. Options are
used to refine the search.</p>
<p>Caution: when this method is used, the script <i class="arg">body</i>
cannot perform another LDAP search (methods <b class="method">traverse</b>,
<b class="method">search</b> or <b class="method">read</b>).</p></dd>
<dt><a name="28"><i class="arg">la</i> <b class="method">search</b> <i class="arg">base</i> <i class="arg">filter</i> <i class="arg">attrs</i></a></dt>
<dd><p>This method searches the directory using the same way as
method <b class="method">traverse</b>. All found entries are stored in
newly created instances of class <b class="class">entry</b>, which are
returned in a list. The newly created instances should be
destroyed when they are no longer used.</p></dd>
<dt><a name="29"><i class="arg">la</i> <b class="method">read</b> <i class="arg">base</i> <i class="arg">filter</i> <i class="arg">entry</i> ... <i class="arg">entry</i></a></dt>
<dd><p>This method reads one or more entries, using the same search
criteria as methods <b class="method">traverse</b> and <b class="method">search</b>.
All attributes are stored in the entries. This method
provides a quick way to read some entries. It returns the
number of entries found in the directory (which may be more
than the number of read entries). If called without any
<i class="arg">entry</i> argument, this method just returns the number
of entries found, without returning any data.</p></dd>
<dt><a name="30"><i class="arg">la</i> <b class="method">commit</b> <i class="arg">entry</i> ... <i class="arg">entry</i></a></dt>
<dd><p>This method commits the changes stored in the <i class="arg">entry</i>
arguments. Each <i class="arg">entry</i> may be either a <em>change</em>
entry, or a <em>standard</em> entry with a backup.</p>
<p>Note: in the future, this method should use the LDAP
transaction extension provided by OpenLDAP 2.3 and later.</p></dd>
</dl>
</div>
<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Ldap Example</a></h3>
<pre class="doctools_example">
package require ldapx
#
# Connects to the LDAP directory
#
::ldapx::ldap create l
set url "ldap://server.mycomp.com"
if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then {
puts stderr "error: [l error]"
exit 1
}
#
# Search all entries matching some criterion
#
l configure -scope one
::ldapx::entry create e
set n 0
l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
puts "dn: [e dn]"
puts " sn: [e get1 sn]"
puts " givenName: [e get1 givenName]"
incr n
}
puts "$n entries found"
e destroy
#
# Add a telephone number to some entries
# Note this modification cannot be done in the "traverse" operation.
#
set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
::ldapx::entry create c
foreach e $lent {
$e backup
$e add1 "telephoneNumber" "+31415926535"
c diff $e
if {! [l commit c]} then {
puts stderr "error: [l error]"
exit 1
}
$e destroy
}
c destroy
l disconnect
l destroy
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">LDIF CLASS</a></h2>
<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Ldif Instance Data</a></h3>
<p>An instance of the <b class="class">ldif</b> class keeps the following data:</p>
<dl class="doctools_definitions">
<dt>channel</dt>
<dd><p>This is the Tcl channel used to retrieve or store LDIF file
contents. The association between an instance and a channel
is made by the method <b class="method">channel</b>. There is no need
to disrupt this association when the LDIF file operation
has ended.</p></dd>
<dt>format</dt>
<dd><p>LDIF files may contain <em>standard</em> entries or
<em>change</em> entries, but not both. This variable contains
the detected format of the file (when reading) or the format
of entries written to the file (when writing).</p></dd>
<dt>lastError</dt>
<dd><p>This variable contains the error message which appeared in
the last method of the <b class="class">ldif</b> class (this string is
modified in nearly all methods). The <b class="method">error</b> method
may be used to fetch this message.</p></dd>
<dt>version</dt>
<dd><p>This is the version of the LDIF file. Only version 1 is
supported: the method <b class="method">read</b> can only read from
version 1 files, and method <b class="method">write</b> only creates
version 1 files.</p></dd>
</dl>
</div>
<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Ldif Options</a></h3>
<p>This class defines two options:</p>
<dl class="doctools_options">
<dt><b class="option">-ignore</b> list-of-attributes</dt>
<dd><p>This option is used to ignore certain attribute names on
reading. For example, to read OpenLDAP replica files (replog),
one must ignore <b class="const">replica</b> and <b class="const">time</b> attributes
since they do not conform to the RFC 2849 standard for LDIF
files.</p>
<p>Default is empty list: no attribute is ignored.</p></dd>
<dt><b class="option">-utf8</b> pattern-yes pattern-no</dt>
<dd><p>Specify which attribute values are encoded in UTF-8. This
information is specific to the LDAP schema in use by the
application, since some attributes such as jpegPhoto, for
example, are not encoded in UTF-8. This option takes the
form of a list with two regular expressions suitable for
the <b class="cmd">regexp</b> command (anchored by ^ and $).
The first specifies which attribute names are to be UTF-8
encoded, and the second selects, among those, the attribute
names which will not be UTF-8 encoded. It is thus possible
to say: convert all attributes, except jpegPhoto.</p>
<p>Default is {{.*} {}}, meaning: all attributes are converted,
without exception.</p></dd>
</dl>
</div>
<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Ldif Methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="31"><i class="arg">li</i> <b class="method">channel</b> <i class="arg">chan</i></a></dt>
<dd><p>This method associates the Tcl channel named <i class="arg">chan</i>
with the LDIF instance. It resets the type of LDIF object
to <em>uninitialized</em>.</p></dd>
<dt><a name="32"><i class="arg">li</i> <b class="method">error</b> <span class="opt">?<i class="arg">newmsg</i>?</span></a></dt>
<dd><p>This method returns the error message that occurred in the
last call to a <b class="class">ldif</b> class method. If the optional
argument <i class="arg">newmsg</i> is supplied, it becomes the last
error message.</p></dd>
<dt><a name="33"><i class="arg">li</i> <b class="method">read</b> <i class="arg">entry</i></a></dt>
<dd><p>This method reads the next entry from the LDIF file and
stores it in the <i class="arg">entry</i> object of class <b class="class">entry</b>.
The entry may be a <em>standard</em> or <em>change</em> entry.</p></dd>
<dt><a name="34"><i class="arg">li</i> <b class="method">write</b> <i class="arg">entry</i></a></dt>
<dd><p>This method writes the entry given in the argument
<i class="arg">entry</i> to the LDIF file.</p></dd>
</dl>
</div>
<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Ldif Example</a></h3>
<pre class="doctools_example">
package require ldapx
# This examples reads a LDIF file containing entries,
# compare them to a LDAP directory, and writes on standard
# output an LDIF file containing changes to apply to the
# LDAP directory to match exactly the LDIF file.
::ldapx::ldif create liin
liin channel stdin
::ldapx::ldif create liout
liout channel stdout
::ldapx::ldap create la
if {! [la connect "ldap://server.mycomp.com"]} then {
puts stderr "error: [la error]"
exit 1
}
la configure -scope one
# Reads LDIF file
::ldapx::entry create e1
::ldapx::entry create e2
::ldapx::entry create c
while {[liin read e1] != 0} {
set base [e1 superior]
set id [e1 rdn]
if {[la read $base "($id)" e2] == 0} then {
e2 reset
}
c diff e1 e2
if {[llength [c change]] != 0} then {
liout write c
}
}
la disconnect
la destroy
e1 destroy
e2 destroy
c destroy
liout destroy
liin destroy
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">References</a></h2>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ldap</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#directory_access">directory access</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#ldap">ldap</a>, <a href="../../../../index.html#ldap_client">ldap client</a>, <a href="../../../../index.html#ldif">ldif</a>, <a href="../../../../index.html#protocol">protocol</a>, <a href="../../../../index.html#rfc_2251">rfc 2251</a>, <a href="../../../../index.html#rfc_2849">rfc 2849</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2018 Pierre David <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/log/log.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
|
<div class='fossil-doc' data-title='log - Logging facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">log(n) 1.4 tcllib "Logging facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>log - Procedures to log messages of libraries and applications.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">LEVELS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">log <span class="opt">?1.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::log::levels</b></a></li>
<li><a href="#2"><b class="cmd">::log::lv2longform</b> <i class="arg">level</i></a></li>
<li><a href="#3"><b class="cmd">::log::lv2color</b> <i class="arg">level</i></a></li>
<li><a href="#4"><b class="cmd">::log::lv2priority</b> <i class="arg">level</i></a></li>
<li><a href="#5"><b class="cmd">::log::lv2cmd</b> <i class="arg">level</i></a></li>
<li><a href="#6"><b class="cmd">::log::lv2channel</b> <i class="arg">level</i></a></li>
<li><a href="#7"><b class="cmd">::log::lvCompare</b> <i class="arg">level1</i> <i class="arg">level2</i></a></li>
<li><a href="#8"><b class="cmd">::log::lvSuppress</b> <i class="arg">level</i> {<i class="arg">suppress</i> 1}</a></li>
<li><a href="#9"><b class="cmd">::log::lvSuppressLE</b> <i class="arg">level</i> {<i class="arg">suppress</i> 1}</a></li>
<li><a href="#10"><b class="cmd">::log::lvIsSuppressed</b> <i class="arg">level</i></a></li>
<li><a href="#11"><b class="cmd">::log::lvCmd</b> <i class="arg">level</i> <i class="arg">cmd</i></a></li>
<li><a href="#12"><b class="cmd">::log::lvCmdForall</b> <i class="arg">cmd</i></a></li>
<li><a href="#13"><b class="cmd">::log::lvChannel</b> <i class="arg">level</i> <i class="arg">chan</i></a></li>
<li><a href="#14"><b class="cmd">::log::lvChannelForall</b> <i class="arg">chan</i></a></li>
<li><a href="#15"><b class="cmd">::log::lvColor</b> <i class="arg">level</i> <i class="arg">color</i></a></li>
<li><a href="#16"><b class="cmd">::log::lvColorForall</b> <i class="arg">color</i></a></li>
<li><a href="#17"><b class="cmd">::log::log</b> <i class="arg">level</i> <i class="arg">text</i></a></li>
<li><a href="#18"><b class="cmd">::log::logarray</b> <i class="arg">level</i> <i class="arg">arrayvar</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#19"><b class="cmd">::log::loghex</b> <i class="arg">level</i> <i class="arg">text</i> <i class="arg">data</i></a></li>
<li><a href="#20"><b class="cmd">::log::logsubst</b> <i class="arg">level</i> <i class="arg">msg</i></a></li>
<li><a href="#21"><b class="cmd">::log::logMsg</b> <i class="arg">text</i></a></li>
<li><a href="#22"><b class="cmd">::log::logError</b> <i class="arg">text</i></a></li>
<li><a href="#23"><b class="cmd">::log::Puts</b> <i class="arg">level</i> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">log</b> package provides commands that allow libraries and
applications to selectively log information about their internal
operation and state.</p>
<p>To use the package just execute</p>
<pre class="doctools_example">
package require log
log::log notice "Some message"
</pre>
<p>As can be seen above, each message given to the log facility is
associated with a <em>level</em> determining the importance of the
message. The user can then select which levels to log, what commands
to use for the logging of each level and the channel to write the
message to. In the following example the logging of all message with
level <b class="const">debug</b> is deactivated.</p>
<pre class="doctools_example">
package require log
log::lvSuppress debug
log::log debug "Unseen message" ; # No output
</pre>
<p>By default all messages associated with an error-level
(<b class="const">emergency</b>, <b class="const">alert</b>, <b class="const">critical</b>, and
<b class="const">error</b>) are written to <b class="const">stderr</b>. Messages with any
other level are written to <b class="const">stdout</b>. In the following example
the log module is reconfigured to write <b class="const">debug</b> messages to
<b class="const">stderr</b> too.</p>
<pre class="doctools_example">
package require log
log::lvChannel debug stderr
log::log debug "Written to stderr"
</pre>
<p>Each message level is also associated with a command to use when
logging a message with that level. The behaviour above for example
relies on the fact that all message levels use by default the standard
command <b class="cmd">::log::Puts</b> to log any message. In the following example
all messages of level <b class="const">notice</b> are given to the non-standard
command <b class="cmd">toText</b> for logging. This disables the channel setting
for such messages, assuming that <b class="cmd">toText</b> does not use it by
itself.</p>
<pre class="doctools_example">
package require log
log::lvCmd notice toText
log::log notice "Handled by \"toText\""
</pre>
<p>Another database maintained by this facility is a map from message
levels to colors. The information in this database has <em>no</em>
influence on the behaviour of the module. It is merely provided as a
convenience and in anticipation of the usage of this facility in
<b class="package">tk</b>-based application which may want to colorize message
logs.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The following commands are available:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::log::levels</b></a></dt>
<dd><p>Returns the names of all known levels, in alphabetical order.</p></dd>
<dt><a name="2"><b class="cmd">::log::lv2longform</b> <i class="arg">level</i></a></dt>
<dd><p>Converts any unique abbreviation of a level name to the full level
name.</p></dd>
<dt><a name="3"><b class="cmd">::log::lv2color</b> <i class="arg">level</i></a></dt>
<dd><p>Converts any level name including unique abbreviations to the
corresponding color.</p></dd>
<dt><a name="4"><b class="cmd">::log::lv2priority</b> <i class="arg">level</i></a></dt>
<dd><p>Converts any level name including unique abbreviations to the
corresponding priority.</p></dd>
<dt><a name="5"><b class="cmd">::log::lv2cmd</b> <i class="arg">level</i></a></dt>
<dd><p>Converts any level name including unique abbreviations to the command
prefix used to write messages with that level.</p></dd>
<dt><a name="6"><b class="cmd">::log::lv2channel</b> <i class="arg">level</i></a></dt>
<dd><p>Converts any level name including unique abbreviations to the channel
used by <b class="cmd">::log::Puts</b> to write messages with that level.</p></dd>
<dt><a name="7"><b class="cmd">::log::lvCompare</b> <i class="arg">level1</i> <i class="arg">level2</i></a></dt>
<dd><p>Compares two levels (including unique abbreviations) with respect to
their priority. This command can be used by the -command option of
lsort. The result is one of -1, 0 or 1 or an error. A result of -1
signals that level1 is of less priority than level2. 0 signals that
both levels have the same priority. 1 signals that level1 has higher
priority than level2.</p></dd>
<dt><a name="8"><b class="cmd">::log::lvSuppress</b> <i class="arg">level</i> {<i class="arg">suppress</i> 1}</a></dt>
<dd><p>(Un)suppresses the output of messages having the specified
level. Unique abbreviations for the level are allowed here too.</p></dd>
<dt><a name="9"><b class="cmd">::log::lvSuppressLE</b> <i class="arg">level</i> {<i class="arg">suppress</i> 1}</a></dt>
<dd><p>(Un)suppresses the output of messages having the specified level or
one of lesser priority. Unique abbreviations for the level are allowed
here too.</p></dd>
<dt><a name="10"><b class="cmd">::log::lvIsSuppressed</b> <i class="arg">level</i></a></dt>
<dd><p>Asks the package whether the specified level is currently
suppressed. Unique abbreviations of level names are allowed.</p></dd>
<dt><a name="11"><b class="cmd">::log::lvCmd</b> <i class="arg">level</i> <i class="arg">cmd</i></a></dt>
<dd><p>Defines for the specified level with which command to write the
messages having this level. Unique abbreviations of level names are
allowed. The command is actually a command prefix and this facility
will append 2 arguments before calling it, the level of the message
and the message itself, in this order.</p></dd>
<dt><a name="12"><b class="cmd">::log::lvCmdForall</b> <i class="arg">cmd</i></a></dt>
<dd><p>Defines for all known levels with which command to write the messages
having this level. The command is actually a command prefix and this
facility will append 2 arguments before calling it, the level of the
message and the message itself, in this order.</p></dd>
<dt><a name="13"><b class="cmd">::log::lvChannel</b> <i class="arg">level</i> <i class="arg">chan</i></a></dt>
<dd><p>Defines for the specified level into which channel <b class="cmd">::log::Puts</b>
(the standard command) shall write the messages having this
level. Unique abbreviations of level names are allowed. The command is
actually a command prefix and this facility will append 2 arguments
before calling it, the level of the message and the message itself, in
this order.</p></dd>
<dt><a name="14"><b class="cmd">::log::lvChannelForall</b> <i class="arg">chan</i></a></dt>
<dd><p>Defines for all known levels with which which channel
<b class="cmd">::log::Puts</b> (the standard command) shall write the messages
having this level. The command is actually a command prefix and this
facility will append 2 arguments before calling it, the level of the
message and the message itself, in this order.</p></dd>
<dt><a name="15"><b class="cmd">::log::lvColor</b> <i class="arg">level</i> <i class="arg">color</i></a></dt>
<dd><p>Defines for the specified level the color to return for it in a call
to <b class="cmd">::log::lv2color</b>. Unique abbreviations of level names are
allowed.</p></dd>
<dt><a name="16"><b class="cmd">::log::lvColorForall</b> <i class="arg">color</i></a></dt>
<dd><p>Defines for all known levels the color to return for it in a call to
<b class="cmd">::log::lv2color</b>. Unique abbreviations of level names are
allowed.</p></dd>
<dt><a name="17"><b class="cmd">::log::log</b> <i class="arg">level</i> <i class="arg">text</i></a></dt>
<dd><p>Log a message according to the specifications for commands, channels
and suppression. In other words: The command will do nothing if the
specified level is suppressed. If it is not suppressed the actual
logging is delegated to the specified command. If there is no command
specified for the level the message won't be logged. The standard
command <b class="cmd">::log::Puts</b> will write the message to the channel
specified for the given level. If no channel is specified for the
level the message won't be logged. Unique abbreviations of level names
are allowed. Errors in the actual logging command are <em>not</em>
caught, but propagated to the caller, as they may indicate
misconfigurations of the log facility or errors in the callers code
itself.</p></dd>
<dt><a name="18"><b class="cmd">::log::logarray</b> <i class="arg">level</i> <i class="arg">arrayvar</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Like <b class="cmd">::log::log</b>, but logs the contents of the specified array
variable <i class="arg">arrayvar</i>, possibly restricted to entries matching the
<i class="arg">pattern</i>. The pattern defaults to <b class="const">*</b> (i.e. all entries) if
none was specified.</p></dd>
<dt><a name="19"><b class="cmd">::log::loghex</b> <i class="arg">level</i> <i class="arg">text</i> <i class="arg">data</i></a></dt>
<dd><p>Like <b class="cmd">::log::log</b>, but assumes that <i class="arg">data</i> contains binary
data. It converts this into a mixed hex/ascii representation before
writing them to the log.</p></dd>
<dt><a name="20"><b class="cmd">::log::logsubst</b> <i class="arg">level</i> <i class="arg">msg</i></a></dt>
<dd><p>Like <b class="cmd">::log::log</b>, but <i class="arg">msg</i> may contain substitutions and variable references, which are evaluated in the caller scope first.
The purpose of this command is to avoid overhead in the non-logging case, if the log message building is expensive.
Any substitution errors raise an error in the command execution.
The following example shows an xml text representation, which is only generated in debug mode:</p>
<pre class="doctools_example">
log::logsubst debug {XML of node $node is '[$node toXml]'}
</pre>
</dd>
<dt><a name="21"><b class="cmd">::log::logMsg</b> <i class="arg">text</i></a></dt>
<dd><p>Convenience wrapper around <b class="cmd">::log::log</b>.
Equivalent to <b class="cmd">::log::log info text</b>.</p></dd>
<dt><a name="22"><b class="cmd">::log::logError</b> <i class="arg">text</i></a></dt>
<dd><p>Convenience wrapper around <b class="cmd">::log::log</b>.
Equivalent to <b class="cmd">::log::log error text</b>.</p></dd>
<dt><a name="23"><b class="cmd">::log::Puts</b> <i class="arg">level</i> <i class="arg">text</i></a></dt>
<dd><p>The standard log command, it writes messages and their levels to
user-specified channels. Assumes that the suppression checks were done
by the caller. Expects full level names, abbreviations are
<em>not allowed</em>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">LEVELS</a></h2>
<p>The package currently defines the following log levels, the level of
highest importance listed first.</p>
<ul class="doctools_itemized">
<li><p>emergency</p></li>
<li><p>alert</p></li>
<li><p>critical</p></li>
<li><p>error</p></li>
<li><p>warning</p></li>
<li><p>notice</p></li>
<li><p>info</p></li>
<li><p>debug</p></li>
</ul>
<p><em>Note</em> that by default all messages with levels <b class="const">warning</b> down to
<b class="const">debug</b> are suppressed. This is done intentionally, because (we believe
that) in most situations debugging output is not wanted. Most people wish to
have such output only when actually debugging an application.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>log</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#log">log</a>, <a href="../../../../index.html#log_level">log level</a>, <a href="../../../../index.html#message">message</a>, <a href="../../../../index.html#message_level">message level</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2001-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/log/logger.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
|
<div class='fossil-doc' data-title='logger - Object Oriented logging facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">logger(n) 0.9.4 tcllib "Object Oriented logging facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>logger - System to control logging of events.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">IMPLEMENTATION</a></li>
<li class="doctools_section"><a href="#section3">Logprocs and Callstack</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">logger <span class="opt">?0.9.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">logger::init</b> <i class="arg">service</i></a></li>
<li><a href="#2"><b class="cmd">logger::import</b> <span class="opt">?<b class="option">-all</b>?</span> <span class="opt">?<b class="option">-force</b>?</span> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefix</i>?</span> <span class="opt">?<b class="option">-namespace</b> <i class="arg">namespace</i>?</span> <i class="arg">service</i></a></li>
<li><a href="#3"><b class="cmd">logger::initNamespace</b> <i class="arg">ns</i> <span class="opt">?<i class="arg">level</i>?</span></a></li>
<li><a href="#4"><b class="cmd">logger::services</b></a></li>
<li><a href="#5"><b class="cmd">logger::enable</b> <i class="arg">level</i></a></li>
<li><a href="#6"><b class="cmd">logger::disable</b> <i class="arg">level</i></a></li>
<li><a href="#7"><b class="cmd">logger::setlevel</b> <i class="arg">level</i></a></li>
<li><a href="#8"><b class="cmd">logger::levels</b></a></li>
<li><a href="#9"><b class="cmd">logger::servicecmd</b> <i class="arg">service</i></a></li>
<li><a href="#10"><b class="cmd">${log}::debug</b> <i class="arg">message</i></a></li>
<li><a href="#11"><b class="cmd">${log}::info</b> <i class="arg">message</i></a></li>
<li><a href="#12"><b class="cmd">${log}::notice</b> <i class="arg">message</i></a></li>
<li><a href="#13"><b class="cmd">${log}::warn</b> <i class="arg">message</i></a></li>
<li><a href="#14"><b class="cmd">${log}::error</b> <i class="arg">message</i></a></li>
<li><a href="#15"><b class="cmd">${log}::critical</b> <i class="arg">message</i></a></li>
<li><a href="#16"><b class="cmd">${log}::alert</b> <i class="arg">message</i></a></li>
<li><a href="#17"><b class="cmd">${log}::emergency</b> <i class="arg">message</i></a></li>
<li><a href="#18"><b class="cmd">${log}::setlevel</b> <i class="arg">level</i></a></li>
<li><a href="#19"><b class="cmd">${log}::enable</b> <i class="arg">level</i></a></li>
<li><a href="#20"><b class="cmd">${log}::disable</b> <i class="arg">level</i></a></li>
<li><a href="#21"><b class="cmd">${log}::lvlchangeproc</b> <i class="arg">command</i></a></li>
<li><a href="#22"><b class="cmd">${log}::lvlchangeproc</b></a></li>
<li><a href="#23"><b class="cmd">${log}::logproc</b> <i class="arg">level</i></a></li>
<li><a href="#24"><b class="cmd">${log}::logproc</b> <i class="arg">level</i> <i class="arg">command</i></a></li>
<li><a href="#25"><b class="cmd">${log}::logproc</b> <i class="arg">level</i> <i class="arg">argname</i> <i class="arg">body</i></a></li>
<li><a href="#26"><b class="cmd">${log}::services</b></a></li>
<li><a href="#27"><b class="cmd">${log}::servicename</b></a></li>
<li><a href="#28"><b class="cmd">${log}::currentloglevel</b></a></li>
<li><a href="#29"><b class="cmd">${log}::delproc</b> <i class="arg">command</i></a></li>
<li><a href="#30"><b class="cmd">${log}::delproc</b></a></li>
<li><a href="#31"><b class="cmd">${log}::delete</b></a></li>
<li><a href="#32"><b class="cmd">${log}::trace</b> <i class="arg">command</i></a></li>
<li><a href="#33"><b class="cmd">${log}::trace</b> <b class="cmd">on</b></a></li>
<li><a href="#34"><b class="cmd">${log}::trace</b> <b class="cmd">off</b></a></li>
<li><a href="#35"><b class="cmd">${log}::trace</b> <b class="cmd">status</b> <span class="opt">?procName?</span> <span class="opt">?...?</span></a></li>
<li><a href="#36"><b class="cmd">${log}::trace</b> <b class="cmd">add</b> <i class="arg">procName</i> <span class="opt">?...?</span></a></li>
<li><a href="#37"><b class="cmd">${log}::trace</b> <b class="cmd">add</b> <span class="opt">?-ns?</span> <i class="arg">nsName</i> <span class="opt">?...?</span></a></li>
<li><a href="#38"><b class="cmd">${log}::trace</b> <b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <i class="arg">procName</i> <span class="opt">?...?</span></a></li>
<li><a href="#39"><b class="cmd">${log}::trace</b> <b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <span class="opt">?-ns?</span> <i class="arg">nsName</i> <span class="opt">?...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">logger</b> package provides a flexible system for logging messages
from different services, at priority levels, with different commands.</p>
<p>To begin using the logger package, we do the following:</p>
<pre class="doctools_example">
package require logger
set log [logger::init myservice]
${log}::notice "Initialized myservice logging"
... code ...
${log}::notice "Ending myservice logging"
${log}::delete
</pre>
<p>In the above code, after the package is loaded, the following things
happen:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">logger::init</b> <i class="arg">service</i></a></dt>
<dd><p>Initializes the service <i class="arg">service</i> for logging. The service names
are actually Tcl namespace names, so they are separated with '::'.
The service name may not be the empty string or only ':'s.
When a logger service is initialized, it "inherits" properties from its
parents. For instance, if there were a service <i class="term">foo</i>, and
we did a <b class="cmd">logger::init</b> <i class="arg">foo::bar</i> (to create a <i class="term">bar</i>
service underneath <i class="term">foo</i>), <i class="term">bar</i> would copy the current
configuration of the <i class="term">foo</i> service, although it would of
course, also be possible to then separately configure <i class="term">bar</i>.
If a logger service is initialized and the parent does not yet exist, the
parent is also created.
The new logger service is initialized with the default loglevel set
with <b class="cmd">logger::setlevel</b>.</p></dd>
<dt><a name="2"><b class="cmd">logger::import</b> <span class="opt">?<b class="option">-all</b>?</span> <span class="opt">?<b class="option">-force</b>?</span> <span class="opt">?<b class="option">-prefix</b> <i class="arg">prefix</i>?</span> <span class="opt">?<b class="option">-namespace</b> <i class="arg">namespace</i>?</span> <i class="arg">service</i></a></dt>
<dd><p>Import the logger service commands into the current namespace. Without the <b class="option">-all</b> option
only the commands corresponding to the log levels are imported. If <b class="option">-all</b> is given,
all the <b class="cmd">${log}::cmd</b> style commands are imported. If the import would overwrite a command
an error is returned and no command is imported. Use the <b class="option">-force</b> option to force the import
and overwrite existing commands without complaining.
If the <b class="option">-prefix</b> option is given, the commands are imported with the given <i class="arg">prefix</i>
prepended to their names.
If the <b class="option">-namespace</b> option is given, the commands are imported into the given namespace. If the
namespace does not exist, it is created. If a namespace without a leading :: is given, it is interpreted as
a child namespace to the current namespace.</p></dd>
<dt><a name="3"><b class="cmd">logger::initNamespace</b> <i class="arg">ns</i> <span class="opt">?<i class="arg">level</i>?</span></a></dt>
<dd><p>Convenience command for setting up a namespace for logging. Creates a
logger service named after the namespace <i class="arg">ns</i> (a :: prefix is
stripped), imports all the log commands into the namespace, and sets
the default logging level, either as specified by <i class="arg">level</i>, or
inherited from a service in the parent namespace, or a hardwired
default, <b class="const">warn</b>.</p></dd>
<dt><a name="4"><b class="cmd">logger::services</b></a></dt>
<dd><p>Returns a list of all the available services.</p></dd>
<dt><a name="5"><b class="cmd">logger::enable</b> <i class="arg">level</i></a></dt>
<dd><p>Globally enables logging at and "above" the given level. Levels are
<b class="const">debug</b>, <b class="const">info</b>, <b class="const">notice</b>, <b class="const">warn</b>, <b class="const">error</b>,
<b class="const">critical</b>, <b class="const">alert</b>, <b class="const">emergency</b>.</p></dd>
<dt><a name="6"><b class="cmd">logger::disable</b> <i class="arg">level</i></a></dt>
<dd><p>Globally disables logging at and "below" the given level. Levels are
those listed above.</p></dd>
<dt><a name="7"><b class="cmd">logger::setlevel</b> <i class="arg">level</i></a></dt>
<dd><p>Globally enable logging at and "above" the given level. Levels are those
listed above. This command changes the default loglevel for new loggers
created with <b class="cmd">logger::init</b>.</p></dd>
<dt><a name="8"><b class="cmd">logger::levels</b></a></dt>
<dd><p>Returns a list of the available log levels (also listed above under <b class="cmd">enable</b>).</p></dd>
<dt><a name="9"><b class="cmd">logger::servicecmd</b> <i class="arg">service</i></a></dt>
<dd><p>Returns the <b class="cmd">${log}</b> token created by <b class="cmd">logger::init</b> for this service.</p></dd>
<dt><a name="10"><b class="cmd">${log}::debug</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="11"><b class="cmd">${log}::info</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="12"><b class="cmd">${log}::notice</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="13"><b class="cmd">${log}::warn</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="14"><b class="cmd">${log}::error</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="15"><b class="cmd">${log}::critical</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="16"><b class="cmd">${log}::alert</b> <i class="arg">message</i></a></dt>
<dd></dd>
<dt><a name="17"><b class="cmd">${log}::emergency</b> <i class="arg">message</i></a></dt>
<dd><p>These are the commands called to actually log a message about an
event. <b class="variable">${log}</b> is the variable obtained from <b class="cmd">logger::init</b>.</p></dd>
<dt><a name="18"><b class="cmd">${log}::setlevel</b> <i class="arg">level</i></a></dt>
<dd><p>Enable logging, in the service referenced by <b class="variable">${log}</b>, and its
children, at and above the level specified, and disable logging below
it.</p></dd>
<dt><a name="19"><b class="cmd">${log}::enable</b> <i class="arg">level</i></a></dt>
<dd><p>Enable logging, in the service referenced by <b class="variable">${log}</b>, and its
children, at and above the level specified. Note that this does <em>not</em> disable logging below this level, so you should probably use
<b class="cmd">setlevel</b> instead.</p></dd>
<dt><a name="20"><b class="cmd">${log}::disable</b> <i class="arg">level</i></a></dt>
<dd><p>Disable logging, in the service referenced by <b class="variable">${log}</b>, and its
children, at and below the level specified. Note that this does <em>not</em> enable logging above this level,
so you should probably use <b class="cmd">setlevel</b> instead.
Disabling the loglevel <b class="const">emergency</b> switches logging off for the service and its children.</p></dd>
<dt><a name="21"><b class="cmd">${log}::lvlchangeproc</b> <i class="arg">command</i></a></dt>
<dd></dd>
<dt><a name="22"><b class="cmd">${log}::lvlchangeproc</b></a></dt>
<dd><p>Set the script to call when the log instance in question changes its log level.
If called without a command it returns the currently registered command. The command gets two arguments
appended, the old and the new loglevel. The callback is invoked after all changes have been done.
If child loggers are affected, their callbacks are called before their parents callback.</p>
<pre class="doctools_example">
proc lvlcallback {old new} {
puts "Loglevel changed from $old to $new"
}
${log}::lvlchangeproc lvlcallback
</pre>
</dd>
<dt><a name="23"><b class="cmd">${log}::logproc</b> <i class="arg">level</i></a></dt>
<dd></dd>
<dt><a name="24"><b class="cmd">${log}::logproc</b> <i class="arg">level</i> <i class="arg">command</i></a></dt>
<dd></dd>
<dt><a name="25"><b class="cmd">${log}::logproc</b> <i class="arg">level</i> <i class="arg">argname</i> <i class="arg">body</i></a></dt>
<dd><p>This command comes in three forms - the third, older one is deprecated
and may be removed from future versions of the logger package.
The current set version takes one argument, a command to be executed when the
level is called. The callback command takes on argument, the text to
be logged. If called only with a valid level <b class="cmd">logproc</b> returns the name of the command
currently registered as callback command.
<b class="cmd">logproc</b> specifies which command will perform the actual logging
for a given level. The logger package ships with default commands for
all log levels, but with <b class="cmd">logproc</b> it is possible to replace them
with custom code. This would let you send your logs over the network,
to a database, or anything else. For example:</p>
<pre class="doctools_example">
proc logtoserver {txt} {
variable socket
puts $socket "Notice: $txt"
}
${log}::logproc notice logtoserver
</pre>
<p>Trace logs are slightly different: instead of a plain text argument,
the argument provided to the logproc is a dictionary consisting of the
<b class="const">enter</b> or <b class="const">leave</b> keyword along with another dictionary of
details about the trace. These include:</p>
<ul class="doctools_itemized">
<li><p><b class="const">proc</b> - Name of the procedure being traced.</p></li>
<li><p><b class="const">level</b> - The stack level for the procedure invocation
(from <b class="cmd"><a href="../../../../index.html#info">info</a></b> <b class="cmd">level</b>).</p></li>
<li><p><b class="const">script</b> - The name of the file in which the procedure is
defined, or an empty string if defined in interactive mode.</p></li>
<li><p><b class="const">caller</b> - The name of the procedure calling the procedure
being traced, or an empty string if the procedure was called from the
global scope (stack level 0).</p></li>
<li><p><b class="const">procargs</b> - A dictionary consisting of the names of arguments
to the procedure paired with values given for those arguments (<b class="const">enter</b>
traces only).</p></li>
<li><p><b class="const">status</b> - The Tcl return code (e.g. <b class="const">ok</b>,
<b class="const">continue</b>, etc.) (<b class="const">leave</b> traces only).</p></li>
<li><p><b class="const">result</b> - The value returned by the procedure (<b class="const">leave</b>
traces only).</p></li>
</ul></dd>
<dt><a name="26"><b class="cmd">${log}::services</b></a></dt>
<dd><p>Returns a list of the registered logging services which are children of this service.</p></dd>
<dt><a name="27"><b class="cmd">${log}::servicename</b></a></dt>
<dd><p>Returns the name of this service.</p></dd>
<dt><a name="28"><b class="cmd">${log}::currentloglevel</b></a></dt>
<dd><p>Returns the currently enabled log level for this service. If no logging is enabled returns <b class="const">none</b>.</p></dd>
<dt><a name="29"><b class="cmd">${log}::delproc</b> <i class="arg">command</i></a></dt>
<dd></dd>
<dt><a name="30"><b class="cmd">${log}::delproc</b></a></dt>
<dd><p>Set the script to call when the log instance in question is deleted.
If called without a command it returns the currently registered command.
For example:</p>
<pre class="doctools_example">
${log}::delproc [list closesock $logsock]
</pre>
</dd>
<dt><a name="31"><b class="cmd">${log}::delete</b></a></dt>
<dd><p>This command deletes a particular logging service, and its children.
You must call this to clean up the resources used by a service.</p></dd>
<dt><a name="32"><b class="cmd">${log}::trace</b> <i class="arg">command</i></a></dt>
<dd><p>This command controls logging of enter/leave traces for specified procedures.
It is used to enable and disable tracing, query tracing status, and
specify procedures are to be traced. Trace handlers are unregistered when
tracing is disabled. As a result, there is not performance impact to a
library when tracing is disabled, just as with other log level commands.</p>
<pre class="doctools_example">
proc tracecmd { dict } {
puts $dict
}
set log [::logger::init example]
${log}::logproc trace tracecmd
proc foo { args } {
puts "In foo"
bar 1
return "foo_result"
}
proc bar { x } {
puts "In bar"
return "bar_result"
}
${log}::trace add foo bar
${log}::trace on
foo
# Output:
enter {proc ::foo level 1 script {} caller {} procargs {args {}}}
In foo
enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}}
In bar
leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result}
leave {proc ::foo level 1 script {} caller {} status ok result foo_result}
</pre>
</dd>
<dt><a name="33"><b class="cmd">${log}::trace</b> <b class="cmd">on</b></a></dt>
<dd><p>Turns on trace logging for procedures registered through the <b class="cmd"><a href="../../../../index.html#trace">trace</a></b>
<b class="cmd">add</b> command. This is similar to the <b class="cmd">enable</b> command for other
logging levels, but allows trace logging to take place at any level.
The trace logging mechanism takes advantage of the execution trace feature
of Tcl 8.4 and later. The <b class="cmd"><a href="../../../../index.html#trace">trace</a></b> <b class="cmd">on</b> command will return an
error if called from earlier versions of Tcl.</p></dd>
<dt><a name="34"><b class="cmd">${log}::trace</b> <b class="cmd">off</b></a></dt>
<dd><p>Turns off trace logging for procedures registered for trace logging
through the <b class="cmd"><a href="../../../../index.html#trace">trace</a></b> <b class="cmd">add</b> command. This is similar to the
<b class="cmd">disable</b> command for other logging levels, but allows trace logging
to take place at any level.
Procedures are not unregistered, so logging for them can be turned back
on with the <b class="cmd"><a href="../../../../index.html#trace">trace</a></b> <b class="cmd">on</b> command. There is no overhead imposed
by trace registration when trace logging is disabled.</p></dd>
<dt><a name="35"><b class="cmd">${log}::trace</b> <b class="cmd">status</b> <span class="opt">?procName?</span> <span class="opt">?...?</span></a></dt>
<dd><p>This command returns a list of the procedures currently registered for
trace logging, or a flag indicating whether or not a trace is registered
for one or more specified procedures.</p></dd>
<dt><a name="36"><b class="cmd">${log}::trace</b> <b class="cmd">add</b> <i class="arg">procName</i> <span class="opt">?...?</span></a></dt>
<dd></dd>
<dt><a name="37"><b class="cmd">${log}::trace</b> <b class="cmd">add</b> <span class="opt">?-ns?</span> <i class="arg">nsName</i> <span class="opt">?...?</span></a></dt>
<dd><p>This command registers one or more procedures for logging of entry/exit
traces. Procedures can be specified via a list of procedure names or
namespace names (in which case all procedure within the namespace
are targeted by the operation). By default, each name is first
interpreted as a procedure name or glob-style search pattern, and if
not found its interpreted as a namespace name. The <i class="arg">-ns</i> option can
be used to force interpretation of all provided arguments as namespace names.
Procedures must be defined prior to registering them for tracing
through the <b class="cmd"><a href="../../../../index.html#trace">trace</a></b> <b class="cmd">add</b> command. Any procedure or namespace
names/patterns that don't match any existing procedures will be
silently ignored.</p></dd>
<dt><a name="38"><b class="cmd">${log}::trace</b> <b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <i class="arg">procName</i> <span class="opt">?...?</span></a></dt>
<dd></dd>
<dt><a name="39"><b class="cmd">${log}::trace</b> <b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <span class="opt">?-ns?</span> <i class="arg">nsName</i> <span class="opt">?...?</span></a></dt>
<dd><p>This command unregisters one or more procedures so that they will no
longer have trace logging performed, with the same matching rules as
that of the <b class="cmd"><a href="../../../../index.html#trace">trace</a></b> <b class="cmd">add</b> command.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">IMPLEMENTATION</a></h2>
<p>The logger package is implemented in such a way as to optimize (for
Tcl 8.4 and newer) log procedures which are disabled. They are
aliased to a proc which has no body, which is compiled to a no op in
bytecode. This should make the peformance hit minimal. If you really
want to pull out all the stops, you can replace the ${log} token in
your code with the actual namespace and command (${log}::warn becomes
::logger::tree::myservice::warn), so that no variable lookup is done.
This puts the performance of disabled logger commands very close to no
logging at all.</p>
<p>The "object orientation" is done through a hierarchy of namespaces.
Using an actual object oriented system would probably be a better way
of doing things, or at least provide for a cleaner implementation.</p>
<p>The service "object orientation" is done with namespaces.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Logprocs and Callstack</a></h2>
<p>The logger package takes extra care to keep the logproc out of the call stack.
This enables logprocs to execute code in the callers scope by using uplevel or
linking to local variables by using upvar. This may fire traces with all usual
side effects.</p>
<pre class="doctools_example">
# Print caller and current vars in the calling proc
proc log_local_var {txt} {
set caller [info level -1]
set vars [uplevel 1 info vars]
foreach var [lsort $vars] {
if {[uplevel 1 [list array exists $var]] == 1} {
lappend val $var <Array>
} else {
lappend val $var [uplevel 1 [list set $var]]
}
}
puts "$txt"
puts "Caller: $caller"
puts "Variables in callers scope:"
foreach {var value} $val {
puts "$var = $value"
}
}
# install as logproc
${log}::logproc debug log_local_var
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>logger</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#log">log</a>, <a href="../../../../index.html#log_level">log level</a>, <a href="../../../../index.html#logger">logger</a>, <a href="../../../../index.html#service">service</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/log/loggerAppender.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<div class='fossil-doc' data-title='logger::appender - Object Oriented logging facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">logger::appender(n) 1.2 tcllib "Object Oriented logging facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>logger::appender - Collection of predefined appenders for logger</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">logger::appender <span class="opt">?1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::logger::appender::console</b> <b class="option">-level</b> <i class="arg">level</i> <b class="option">-service</b> <i class="arg">service</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::logger::appender::colorConsole</b> <b class="option">-level</b> <i class="arg">level</i> <b class="option">-service</b> <i class="arg">service</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a predefined set of logger templates.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::logger::appender::console</b> <b class="option">-level</b> <i class="arg">level</i> <b class="option">-service</b> <i class="arg">service</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><dl class="doctools_options">
<dt><b class="option">-level</b> level</dt>
<dd><p>Name of the level to fill in as "priority" in the log procedure.</p></dd>
<dt><b class="option">-service</b> service</dt>
<dd><p>Name of the service to fill in as "category" in the log procedure.</p></dd>
<dt><b class="option">-appenderArgs</b> appenderArgs</dt>
<dd><p>Any additional arguments for the log procedure in list form</p></dd>
<dt><b class="option">-conversionPattern</b> conversionPattern</dt>
<dd><p>The log pattern to use (see <b class="cmd">logger::utils::createLogProc</b> for the
allowed substitutions).</p></dd>
<dt><b class="option">-procName</b> procName</dt>
<dd><p>Explicitly set the name of the created procedure.</p></dd>
<dt><b class="option">-procNameVar</b> procNameVar</dt>
<dd><p>Name of the variable to set in the calling context. This variable will
contain the name of the procedure.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::logger::appender::colorConsole</b> <b class="option">-level</b> <i class="arg">level</i> <b class="option">-service</b> <i class="arg">service</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>See <b class="cmd">::logger::appender::colorConsole</b> for a description of the
applicable options.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>logger</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#appender">appender</a>, <a href="../../../../index.html#logger">logger</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Aamer Akhter <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/log/loggerUtils.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
<div class='fossil-doc' data-title='logger::utils - Object Oriented logging facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">logger::utils(n) 1.3 tcllib "Object Oriented logging facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>logger::utils - Utilities for logger</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">logger::utils <span class="opt">?1.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::logger::utils::createFormatCmd</b> <i class="arg">formatString</i></a></li>
<li><a href="#2"><b class="cmd">::logger::utils::createLogProc</b> <b class="option">-procName</b> <i class="arg">procName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">::logger::utils::applyAppender</b> <b class="option">-appender</b> <i class="arg">appenderType</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#4"><b class="cmd">::logger::utils::autoApplyAppender</b> <i class="arg">command</i> <i class="arg">command-string</i> <i class="arg">log</i> <i class="arg">op</i> <i class="arg">args</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package adds template based <i class="term">appenders</i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::logger::utils::createFormatCmd</b> <i class="arg">formatString</i></a></dt>
<dd><p>This command translates <i class="arg">formatString</i> into an expandable command
string.
The following strings are the known substitutions (from log4perl)
allowed to occur in the <i class="arg">formatString</i>:</p>
<dl class="doctools_definitions">
<dt>%c</dt>
<dd><p>Category of the logging event</p></dd>
<dt>%C</dt>
<dd><p>Fully qualified name of logging event</p></dd>
<dt>%d</dt>
<dd><p>Current date in yyyy/MM/dd hh:mm:ss</p></dd>
<dt>%H</dt>
<dd><p>Hostname</p></dd>
<dt>%m</dt>
<dd><p>Message to be logged</p></dd>
<dt>%M</dt>
<dd><p>Method where logging event was issued</p></dd>
<dt>%p</dt>
<dd><p>Priority of logging event</p></dd>
<dt>%P</dt>
<dd><p>Pid of current process</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::logger::utils::createLogProc</b> <b class="option">-procName</b> <i class="arg">procName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command ...</p>
<dl class="doctools_options">
<dt><b class="option">-procName</b> procName</dt>
<dd><p>The name of the procedure to create.</p></dd>
<dt><b class="option">-conversionPattern</b> pattern</dt>
<dd><p>See <b class="cmd">::logger::utils::createFormatCmd</b> for the substitutions
allowed in the <i class="arg">pattern</i>.</p></dd>
<dt><b class="option">-category</b> category</dt>
<dd><p>The category (service).</p></dd>
<dt><b class="option">-priority</b> priority</dt>
<dd><p>The priority (level).</p></dd>
<dt><b class="option">-outputChannel</b> channel</dt>
<dd><p>channel to output on (default stdout)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::logger::utils::applyAppender</b> <b class="option">-appender</b> <i class="arg">appenderType</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command will create an appender for the specified logger
services. If no service is specified then the appender will be added
as the default appender for the specified levels. If no levels are
specified, then all levels are assumed.</p>
<dl class="doctools_options">
<dt><b class="option">-service</b> loggerservices</dt>
<dd></dd>
<dt><b class="option">-serviceCmd</b> loggerserviceCmds</dt>
<dd><p>Name of the logger instance to modify. <b class="option">-serviceCmd</b> takes as
input the return of <b class="cmd">logger::init</b>.</p></dd>
<dt><b class="option">-appender</b> appenderType</dt>
<dd><p>Type of the appender to use.
One of <b class="const">console</b>, <b class="const">colorConsole</b>.</p></dd>
<dt><b class="option">-appenderArgs</b> appenderArgs</dt>
<dd><p>Additional arguments to apply to the appender.
The argument of the option is a list of options
and their arguments.</p>
<p>For example</p>
<pre class="doctools_example">
logger::utils::applyAppender -serviceCmd $log -appender console -appenderArgs {-conversionPattern {\[%M\] \[%p\] - %m}}
</pre>
<p>The usual Tcl quoting rules apply.</p></dd>
<dt><b class="option">-levels</b> levelList</dt>
<dd><p>The list of levels to apply this appender to. If not specified all
levels are assumed.</p></dd>
</dl>
<p>Example of usage:</p>
<pre class="doctools_example">
% set log [logger::init testLog]
::logger::tree::testLog
% logger::utils::applyAppender -appender console -serviceCmd $log
% ${log}::error "this is an error"
[2005/08/22 10:14:13] [testLog] [global] [error] this is an error
</pre>
</dd>
<dt><a name="4"><b class="cmd">::logger::utils::autoApplyAppender</b> <i class="arg">command</i> <i class="arg">command-string</i> <i class="arg">log</i> <i class="arg">op</i> <i class="arg">args</i>...</a></dt>
<dd><p>This command is designed to be added via <b class="cmd">trace leave</b> to calls
of <b class="cmd">logger::init</b>. It will look at preconfigured state (via
<b class="cmd">::logger::utils::applyAppender</b>) to autocreate appenders for
newly created logger instances.
It will return its argument <i class="arg">log</i>.</p>
<p>Example of usage:</p>
<pre class="doctools_example">
logger::utils::applyAppender -appender console
set log [logger::init applyAppender-3]
${log}::error "this is an error"
</pre>
</dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>logger</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#appender">appender</a>, <a href="../../../../index.html#logger">logger</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Aamer Akhter <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
<div class='fossil-doc' data-title='map::geocode::nominatim - Mapping utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">map::geocode::nominatim(n) 0.1 tcllib "Mapping utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>map::geocode::nominatim - Resolving geographical names with a Nominatim service</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Options</a></li>
<li class="doctools_subsection"><a href="#subsection2">Methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">http</b></li>
<li>package require <b class="pkgname">json</b></li>
<li>package require <b class="pkgname">uri</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">map::geocode::nominatim <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::map::geocode::nominatim</b> <i class="arg">requestor</i> <span class="opt">?<b class="option">-baseurl</b> <i class="arg">url</i>?</span> <span class="opt">?<b class="option">-callback</b> <i class="arg">callback</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">error callback</i>?</span></a></li>
<li><a href="#2"><b class="cmd">$cmdprefix</b> <i class="arg">result</i></a></li>
<li><a href="#3"><b class="cmd">$cmdprefix</b> <i class="arg">errorstring</i></a></li>
<li><a href="#4"><i class="arg">requestor</i> <b class="method">search</b> <i class="arg">query</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for accessing geocoding services which implement
the <i class="term"><a href="../../../../index.html#nominatim">Nominatim</a></i> interface (see <span class="sectref"><a href="#section3">References</a></span>)</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::map::geocode::nominatim</b> <i class="arg">requestor</i> <span class="opt">?<b class="option">-baseurl</b> <i class="arg">url</i>?</span> <span class="opt">?<b class="option">-callback</b> <i class="arg">callback</i>?</span> <span class="opt">?<b class="option">-error</b> <i class="arg">error callback</i>?</span></a></dt>
<dd><p>Creates a geocoding request object <i class="arg">requestor</i>, which will send its requests to
the <i class="term"><a href="../../../../index.html#nominatim">Nominatim</a></i> server.</p>
<p>The result of the command is <i class="arg">name</i>.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Options</a></h3>
<dl class="doctools_options">
<dt><b class="option">-baseurl</b> <i class="arg">url</i></dt>
<dd><p>The base URL of the <i class="term"><a href="../../../../index.html#nominatim">Nominatim</a></i> service. Default value is <i class="term">OpenStreetMap's</i> service at
<a href="http://nominatim.openstreetmap.org/search">http://nominatim.openstreetmap.org/search</a> A possible free alternative is at
<a href="http://open.mapquestapi.com//nominatim/v1/search">http://open.mapquestapi.com//nominatim/v1/search</a></p></dd>
<dt><b class="option">-callback</b> <i class="arg">cmdprefix</i></dt>
<dd><p>A command prefix to be invoked when search result become available.
The default setting, active when nothing was specified on object creation, is to print
the <i class="arg">result</i> (see below) to <i class="term"><a href="../../../../index.html#stdout">stdout</a></i>. The result of the command prefix is
ignored. Errors thrown by the command prefix are caught and cause the invokation of
the error callback (see option <b class="option">-error</b> below), with the error message as argument.</p>
<p>The signature of the command prefix is:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">$cmdprefix</b> <i class="arg">result</i></a></dt>
<dd><p>The <i class="arg">result</i> is a list of dictionaries, containing one item per hit.
Each dictionary will have the following entries:</p>
<dl class="doctools_definitions">
<dt>place_id</dt>
<dd><p>The place ID (FIXME: what's this?)</p></dd>
<dt>licence</dt>
<dd><p>The data licence string</p></dd>
<dt>osm_type</dt>
<dd><p>The OSM type of the location</p></dd>
<dt>osm_id</dt>
<dd><p>FIXME</p></dd>
<dt>boundingbox</dt>
<dd><p>The coordinates of the bounding box (min and max latitude, min and max longitude)</p></dd>
<dt>lat</dt>
<dd><p>The location's latitude</p></dd>
<dt>lon</dt>
<dd><p>The location's longitude</p></dd>
<dt>display_name</dt>
<dd><p>the location's human readable name</p></dd>
<dt>class</dt>
<dd><p>FIXME</p></dd>
<dt>type</dt>
<dd><p>FIXME</p></dd>
<dt>icon</dt>
<dd><p>FIXME</p></dd>
</dl></dd>
</dl></dd>
<dt><b class="option">-error</b> <i class="arg">cmdprefix</i></dt>
<dd><p>A command prefix to be invoked when encountering errors. Typically these are HTTP errors.
The default setting, active when nothing was specified on object creation, is to print
the <i class="arg">errorstring</i> (see below) to <i class="term">stderr</i>. The result of the command prefix is
ignored. Errors thrown by the command prefix are passed to higher levels.</p>
<p>The signature of the command prefix is:</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">$cmdprefix</b> <i class="arg">errorstring</i></a></dt>
<dd></dd>
</dl></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="4"><i class="arg">requestor</i> <b class="method">search</b> <i class="arg">query</i></a></dt>
<dd><p>This method returns a list of dictionaries, one item per hit for the specified <i class="arg">query</i>.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://wiki.openstreetmap.org/wiki/Nominatim">http://wiki.openstreetmap.org/wiki/Nominatim</a></p></li>
<li><p><a href="http://open.mapquestapi.com/nominatim/">http://open.mapquestapi.com/nominatim/</a></p></li>
</ol>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#geocoding">geocoding</a>, <a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#location">location</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#nominatim">nominatim</a>, <a href="../../../../index.html#server">server</a>, <a href="../../../../index.html#url">url</a></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/map/map_slippy.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
<div class='fossil-doc' data-title='map::slippy - Mapping utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">map::slippy(n) 0.5 tcllib "Mapping utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>map::slippy - Common code for slippy based map packages</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Coordinate systems</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Geographic</a></li>
<li class="doctools_subsection"><a href="#subsection2">Tiles</a></li>
<li class="doctools_subsection"><a href="#subsection3">Pixels/Points</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">References</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">Tk 8.4</b></li>
<li>package require <b class="pkgname">map::slippy <span class="opt">?0.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::map::slippy</b> <b class="method">length</b> <i class="arg">level</i></a></li>
<li><a href="#2"><b class="cmd">::map::slippy</b> <b class="method">tiles</b> <i class="arg">level</i></a></li>
<li><a href="#3"><b class="cmd">::map::slippy</b> <b class="method">tile size</b></a></li>
<li><a href="#4"><b class="cmd">::map::slippy</b> <b class="method">tile valid</b> <i class="arg">tile</i> <i class="arg">levels</i> <span class="opt">?<i class="arg">msgvar</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::map::slippy</b> <b class="method">geo 2tile</b> <i class="arg">geo</i></a></li>
<li><a href="#6"><b class="cmd">::map::slippy</b> <b class="method">geo 2tile.float</b> <i class="arg">geo</i></a></li>
<li><a href="#7"><b class="cmd">::map::slippy</b> <b class="method">geo 2point</b> <i class="arg">geo</i></a></li>
<li><a href="#8"><b class="cmd">::map::slippy</b> <b class="method">tile 2geo</b> <i class="arg">tile</i></a></li>
<li><a href="#9"><b class="cmd">::map::slippy</b> <b class="method">tile 2point</b> <i class="arg">tile</i></a></li>
<li><a href="#10"><b class="cmd">::map::slippy</b> <b class="method">point 2geo</b> <i class="arg">point</i></a></li>
<li><a href="#11"><b class="cmd">::map::slippy</b> <b class="method">point 2tile</b> <i class="arg">point</i></a></li>
<li><a href="#12"><b class="cmd">::map::slippy</b> <b class="method">fit geobox</b> <i class="arg">canvdim</i> <i class="arg">geobox</i> <i class="arg">zmin</i> <i class="arg">zmax</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a number of methods doing things needed by all
types of slippy-based map packages.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::map::slippy</b> <b class="method">length</b> <i class="arg">level</i></a></dt>
<dd><p>This method returns the width/height of a slippy-based map at the
specified zoom <i class="arg">level</i>, in pixels. This is, in essence, the result
of</p>
<pre class="doctools_example">
expr { [tiles $level] * [tile size] }
</pre>
</dd>
<dt><a name="2"><b class="cmd">::map::slippy</b> <b class="method">tiles</b> <i class="arg">level</i></a></dt>
<dd><p>This method returns the width/height of a slippy-based map at the
specified zoom <i class="arg">level</i>, in <i class="term">tiles</i>.</p></dd>
<dt><a name="3"><b class="cmd">::map::slippy</b> <b class="method">tile size</b></a></dt>
<dd><p>This method returns the width/height of a tile in a slippy-based map,
in pixels.</p></dd>
<dt><a name="4"><b class="cmd">::map::slippy</b> <b class="method">tile valid</b> <i class="arg">tile</i> <i class="arg">levels</i> <span class="opt">?<i class="arg">msgvar</i>?</span></a></dt>
<dd><p>This method checks whether <i class="arg">tile</i> described a valid tile in a
slippy-based map containing that many zoom <i class="arg">levels</i>. The result is
a boolean value, <b class="const">true</b> if the tile is valid, and <b class="const">false</b>
otherwise. For the latter a message is left in the variable named by
<i class="arg">msgvar</i>, should it be specified.</p>
<p>A tile identifier as stored in <i class="arg">tile</i> is a list containing zoom
level, tile row, and tile column, in this order. The command
essentially checks this, i.e. the syntax, that the zoom level is
between 0 and "<i class="arg">levels</i>-1", and that the row/col information is
within the boundaries for the zoom level, i.e. 0 ...
"[tiles $zoom]-1".</p></dd>
<dt><a name="5"><b class="cmd">::map::slippy</b> <b class="method">geo 2tile</b> <i class="arg">geo</i></a></dt>
<dd><p>Converts a geographical location at a zoom level (<i class="arg">geo</i>, a list
containing zoom level, latitude, and longitude, in this order) to a
tile identifier (list containing zoom level, row, and column) at that
level. The tile identifier uses pure integer numbers for the tile
coordinates, for all geographic coordinates mapping to that tile.</p></dd>
<dt><a name="6"><b class="cmd">::map::slippy</b> <b class="method">geo 2tile.float</b> <i class="arg">geo</i></a></dt>
<dd><p>Converts a geographical location at a zoom level (<i class="arg">geo</i>, a list
containing zoom level, latitude, and longitude, in this order) to a
tile identifier (list containing zoom level, row, and column) at that
level. The tile identifier uses floating point numbers for the tile
coordinates, representing not only the tile the geographic coordinates
map to, but also the fractional location inside of that tile.</p></dd>
<dt><a name="7"><b class="cmd">::map::slippy</b> <b class="method">geo 2point</b> <i class="arg">geo</i></a></dt>
<dd><p>Converts a geographical location at a zoom level (<i class="arg">geo</i>, a list
containing zoom level, latitude, and longitude, in this order) to a
pixel position (list containing zoom level, y, and x) at that level.</p></dd>
<dt><a name="8"><b class="cmd">::map::slippy</b> <b class="method">tile 2geo</b> <i class="arg">tile</i></a></dt>
<dd><p>Converts a tile identifier at a zoom level (<i class="arg">tile</i>, list
containing zoom level, row, and column) to a geographical location
(list containing zoom level, latitude, and longitude, in this order)
at that level.</p></dd>
<dt><a name="9"><b class="cmd">::map::slippy</b> <b class="method">tile 2point</b> <i class="arg">tile</i></a></dt>
<dd><p>Converts a tile identifier at a zoom level (<i class="arg">tile</i>, a list
containing zoom level, row, and column, in this order) to a pixel
position (list containing zoom level, y, and x) at that level.</p></dd>
<dt><a name="10"><b class="cmd">::map::slippy</b> <b class="method">point 2geo</b> <i class="arg">point</i></a></dt>
<dd><p>Converts a pixel position at a zoom level (<i class="arg">point</i>, list
containing zoom level, y, and x) to a geographical location (list
containing zoom level, latitude, and longitude, in this order) at that
level.</p></dd>
<dt><a name="11"><b class="cmd">::map::slippy</b> <b class="method">point 2tile</b> <i class="arg">point</i></a></dt>
<dd><p>Converts a pixel position at a zoom level (<i class="arg">point</i>, a list
containing zoom level, y, and x, in this order) to a tile identifier
(list containing zoom level, row, and column) at that level.</p></dd>
<dt><a name="12"><b class="cmd">::map::slippy</b> <b class="method">fit geobox</b> <i class="arg">canvdim</i> <i class="arg">geobox</i> <i class="arg">zmin</i> <i class="arg">zmax</i></a></dt>
<dd><p>Calculates the zoom level (whithin the bounds <i class="arg">zmin</i> and
<i class="arg">zmax</i>) such that <i class="arg">geobox</i> (a 4-element list containing the
latitudes and longitudes lat0, lat1, lon0 and lon1 of a geo box,
in this order) fits into a viewport given by <i class="arg">canvdim</i>, a
2-element list containing the width and height of the viewport, in
this order.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Coordinate systems</a></h2>
<p>The commands of this package operate on three distinct coordinate
systems, which are explained below.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Geographic</a></h3>
<p><i class="term">Geographic</i>al coordinates are represented by <i class="term">Latitude</i> and
<i class="term"><a href="../../../../index.html#longitude">Longitude</a></i>, each of which is measured in degrees, as they are
essentially angles.</p>
<p><b class="const">Zero</b> longitude is the <i class="term">Greenwich meridian</i>, with
positive values going <i class="term">east</i>, and negative values going
<i class="term">west</i>, for a total range of +/- 180 degrees. Note that +180 and
-180 longitude are the same <i class="term">meridian</i>, opposite to greenwich.</p>
<p><b class="const">zero</b> latitude the <i class="term">Equator</i>, with positive values
going <i class="term">north</i> and negative values going <i class="term">south</i>. While the
true range is +/- 90 degrees the projection used by the package
requires us to cap the range at +/- 85.05112877983284 degrees. This
means that north and south pole are not representable and not part of
any map.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Tiles</a></h3>
<p>While <span class="sectref"><a href="#subsection1">Geographic</a></span>al coordinates of the previous section are
independent of zoom level the <i class="term">tile coordinates</i> are not.</p>
<p>Generally the integer part of tile coordinates represent the
row and column number of the tile in question, wheras the fractional
parts signal how far inside the tile the location in question is, with
pure integer coordinates (no fractional part) representing the upper
left corner of the tile.</p>
<p>The zero point of the map is at the upper left corner,
regardless of zoom level, with larger coordinates going right (east)
and down (south), and smaller coordinates going left (west) and up
(north). Again regardless of zxoom level.</p>
<p>Negative tile coordinates are not allowed.</p>
<p>At zoom level 0 the whole map is represented by a single,
putting the geographic zero at 1/2, 1/2 of tile coordinates, and the
range of tile coordinates as [0...1].</p>
<p>To go from a zoom level N to the next deeper level N+1 each
tile of level N is split into its four quadrants, which then are the
tiles of level N+1.</p>
<p>This means that at zoom level N the map is sliced (horizontally
and vertically) into 2^N stripes, for a total of 4^N tiles, with tile
coordinates ranging from 0 to 2^N+1.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Pixels/Points</a></h3>
<p><i class="term">pixel coordinates</i>, also called <i class="term">point coordinates</i> are
in essence <span class="sectref"><a href="#subsection2">tile coordinates</a></span> scaled by the size of
the image representing a tile. This tile size currently has a fixed
value, <b class="const">256</b>.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://wiki.openstreetmap.org/wiki/Main_Page">http://wiki.openstreetmap.org/wiki/Main_Page</a></p></li>
</ol>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#geodesy">geodesy</a>, <a href="../../../../index.html#geography">geography</a>, <a href="../../../../index.html#latitute">latitute</a>, <a href="../../../../index.html#location">location</a>, <a href="../../../../index.html#longitude">longitude</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#slippy">slippy</a>, <a href="../../../../index.html#zoom">zoom</a></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/map/map_slippy_cache.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<div class='fossil-doc' data-title='map::slippy::cache - Mapping utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">map::slippy::cache(n) 0.2 tcllib "Mapping utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>map::slippy::cache - Management of a tile cache in the local filesystem</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">Tk 8.4</b></li>
<li>package require <b class="pkgname">img::png</b></li>
<li>package require <b class="pkgname">map::slippy</b></li>
<li>package require <b class="pkgname">map::slippy::cache <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::map::slippy::cache</b> <i class="arg">cacheName</i> <i class="arg">cachedir</i> <i class="arg">provider</i></a></li>
<li><a href="#2"><i class="arg">cacheName</i> <b class="method">valid</b> <i class="arg">tile</i> <span class="opt">?<i class="arg">msgvar</i>?</span></a></li>
<li><a href="#3"><i class="arg">cacheName</i> <b class="method">exists</b> <i class="arg">tile</i></a></li>
<li><a href="#4"><i class="arg">cacheName</i> <b class="method">get</b> <i class="arg">tile</i> <i class="arg">donecmd</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for managing a cache of tiles for
slippy-based maps in the local filesystem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::map::slippy::cache</b> <i class="arg">cacheName</i> <i class="arg">cachedir</i> <i class="arg">provider</i></a></dt>
<dd><p>Creates the cache <i class="arg">cacheName</i> and configures it with both the path
to the directory contaiing the locally cached tiles (<i class="arg">cachedir</i>),
and the command prefix from which it will pull tiles asked for and not
yet known to the cache itself (<i class="arg">provider</i>).</p>
<p>The result of the command is <i class="arg">cacheName</i>.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">cacheName</i> <b class="method">valid</b> <i class="arg">tile</i> <span class="opt">?<i class="arg">msgvar</i>?</span></a></dt>
<dd><p>This method checks the validity of a the given <i class="arg">tile</i> identifier.
This is a convenience wrapper to <b class="cmd">::map::slippy tile valid</b> and
has the same interface.</p></dd>
<dt><a name="3"><i class="arg">cacheName</i> <b class="method">exists</b> <i class="arg">tile</i></a></dt>
<dd><p>This methods tests whether the cache contains the specified <i class="arg">tile</i>
or not. The result is a boolean value, <b class="const">true</b> if the tile is
known, and <b class="const">false</b> otherwise. The tile is identified by a list
containing three elements, zoom level, row, and column number, in this
order.</p></dd>
<dt><a name="4"><i class="arg">cacheName</i> <b class="method">get</b> <i class="arg">tile</i> <i class="arg">donecmd</i></a></dt>
<dd><p>This is the main method of the cache, retrieving the image for the
specified <i class="arg">tile</i> from the cache. The tile identifier is a list
containing three elements, the zoom level, row, and column number of
the tile, in this order.</p>
<p>The command refix <i class="arg">donecmd</i> will be invoked when the cache
either knows the image for the tile or that no image will forthcoming.
It will be invoked with either 2 or 3 arguments, i.e.</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">set</b>, the <i class="arg">tile</i>, and the image.</p></li>
<li><p>The string <b class="const">unset</b>, and the <i class="arg">tile</i>.</p></li>
</ol>
<p>These two possibilities are used to either signal the image for the
<i class="arg">tile</i>, or that the <i class="arg">tile</i> has no image defined for it.</p>
<p>When the cache has no information about the tile it will invoke the
<i class="arg">provider</i> command prefix specified during its construction,
adding three arguments: The string <b class="const">get</b>, the <i class="arg">tile</i>, and a
callback into the cache. The latter will be invoked by the provider to
either transfer the image to the cache, or signal that the tile has no
image.</p>
<p>When multiple requests for the same tile are made only one request
will be issued to the provider.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://wiki.openstreetmap.org/wiki/Main_Page">http://wiki.openstreetmap.org/wiki/Main_Page</a></p></li>
</ol>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cache">cache</a>, <a href="../../../../index.html#filesystem">filesystem</a>, <a href="../../../../index.html#location">location</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#slippy">slippy</a>, <a href="../../../../index.html#tile">tile</a>, <a href="../../../../index.html#zoom">zoom</a></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='map::slippy::fetcher - Mapping utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">map::slippy::fetcher(n) 0.4 tcllib "Mapping utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>map::slippy::fetcher - Accessing a server providing tiles for slippy-based maps</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">Tk 8.4</b></li>
<li>package require <b class="pkgname">img::png</b></li>
<li>package require <b class="pkgname">map::slippy</b></li>
<li>package require <b class="pkgname">map::slippy::fetcher <span class="opt">?0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::map::slippy::fetcher</b> <i class="arg">fetcherName</i> <i class="arg">levels</i> <i class="arg">url</i></a></li>
<li><a href="#2"><i class="arg">fetcherName</i> <b class="method">levels</b></a></li>
<li><a href="#3"><i class="arg">fetcherName</i> <b class="method">tileheight</b></a></li>
<li><a href="#4"><i class="arg">fetcherName</i> <b class="method">tilewidth</b></a></li>
<li><a href="#5"><i class="arg">fetcherName</i> <b class="method">get</b> <i class="arg">tile</i> <i class="arg">donecmd</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for accessing http servers providing
tiles for slippy-based maps.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::map::slippy::fetcher</b> <i class="arg">fetcherName</i> <i class="arg">levels</i> <i class="arg">url</i></a></dt>
<dd><p>Creates the fetcher <i class="arg">fetcherName</i> and configures it with the
number of zoom <i class="arg">levels</i> supported by the tile server, and the
<i class="arg">url</i> it is listening on for tile requests.</p>
<p>The result of the command is <i class="arg">fetcherName</i>.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">fetcherName</i> <b class="method">levels</b></a></dt>
<dd><p>This method returns the number of zoom levels supported by the fetcher
object, and the tile server it is accessing.</p></dd>
<dt><a name="3"><i class="arg">fetcherName</i> <b class="method">tileheight</b></a></dt>
<dd><p>This method returns the height of tiles served, in pixels.</p></dd>
<dt><a name="4"><i class="arg">fetcherName</i> <b class="method">tilewidth</b></a></dt>
<dd><p>This method returns the width of tiles served, in pixels.</p></dd>
<dt><a name="5"><i class="arg">fetcherName</i> <b class="method">get</b> <i class="arg">tile</i> <i class="arg">donecmd</i></a></dt>
<dd><p>This is the main method of the fetcher, retrieving the image for the
specified <i class="arg">tile</i>. The tile identifier is a list containing three
elements, the zoom level, row, and column number of the tile, in this
order.</p>
<p>The command refix <i class="arg">donecmd</i> will be invoked when the fetcher
either knows the image for the tile or that no image will forthcoming.
It will be invoked with either 2 or 3 arguments, i.e.</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">set</b>, the <i class="arg">tile</i>, and the image.</p></li>
<li><p>The string <b class="const">unset</b>, and the <i class="arg">tile</i>.</p></li>
</ol>
<p>These two possibilities are used to either signal the image for the
<i class="arg">tile</i>, or that the <i class="arg">tile</i> has no image defined for it.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://wiki.openstreetmap.org/wiki/Main_Page">http://wiki.openstreetmap.org/wiki/Main_Page</a></p></li>
</ol>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#location">location</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#server">server</a>, <a href="../../../../index.html#slippy">slippy</a>, <a href="../../../../index.html#tile">tile</a>, <a href="../../../../index.html#url">url</a>, <a href="../../../../index.html#zoom">zoom</a></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/mapproj/mapproj.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
|
<div class='fossil-doc' data-title='mapproj - Tcl Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">mapproj(n) 0.1 tcllib "Tcl Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>mapproj - Map projection routines</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Arguments</a></li>
<li class="doctools_section"><a href="#section4">Results</a></li>
<li class="doctools_section"><a href="#section5">Choosing a projection</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">math::interpolate <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">math::special <span class="opt">?0.2.1?</span></b></li>
<li>package require <b class="pkgname">mapproj <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::mapproj::toPlateCarree</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#2"><b class="cmd">::mapproj::fromPlateCarree</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#3"><b class="cmd">::mapproj::toCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#4"><b class="cmd">::mapproj::fromCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#5"><b class="cmd">::mapproj::toMercator</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#6"><b class="cmd">::mapproj::fromMercator</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#7"><b class="cmd">::mapproj::toMillerCylindrical</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#8"><b class="cmd">::mapproj::fromMillerCylindrical</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#9"><b class="cmd">::mapproj::toSinusoidal</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#10"><b class="cmd">::mapproj::fromSinusoidal</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#11"><b class="cmd">::mapproj::toMollweide</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#12"><b class="cmd">::mapproj::fromMollweide</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#13"><b class="cmd">::mapproj::toEckertIV</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#14"><b class="cmd">::mapproj::fromEckertIV</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#15"><b class="cmd">::mapproj::toEckertVI</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#16"><b class="cmd">::mapproj::fromEckertVI</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#17"><b class="cmd">::mapproj::toRobinson</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#18"><b class="cmd">::mapproj::fromRobinson</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#19"><b class="cmd">::mapproj::toCassini</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#20"><b class="cmd">::mapproj::fromCassini</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#21"><b class="cmd">::mapproj::toPeirceQuincuncial</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#22"><b class="cmd">::mapproj::fromPeirceQuincuncial</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#23"><b class="cmd">::mapproj::toOrthographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#24"><b class="cmd">::mapproj::fromOrthographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#25"><b class="cmd">::mapproj::toStereographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#26"><b class="cmd">::mapproj::fromStereographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#27"><b class="cmd">::mapproj::toGnomonic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#28"><b class="cmd">::mapproj::fromGnomonic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#29"><b class="cmd">::mapproj::toAzimuthalEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#30"><b class="cmd">::mapproj::fromAzimuthalEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#31"><b class="cmd">::mapproj::toLambertAzimuthalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#32"><b class="cmd">::mapproj::fromLambertAzimuthalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#33"><b class="cmd">::mapproj::toHammer</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#34"><b class="cmd">::mapproj::fromHammer</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#35"><b class="cmd">::mapproj::toConicEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#36"><b class="cmd">::mapproj::fromConicEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#37"><b class="cmd">::mapproj::toAlbersEqualAreaConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#38"><b class="cmd">::mapproj::fromAlbersEqualAreaConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#39"><b class="cmd">::mapproj::toLambertConformalConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#40"><b class="cmd">::mapproj::fromLambertConformalConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#41"><b class="cmd">::mapproj::toLambertCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#42"><b class="cmd">::mapproj::fromLambertCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#43"><b class="cmd">::mapproj::toBehrmann</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#44"><b class="cmd">::mapproj::fromBehrmann</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#45"><b class="cmd">::mapproj::toTrystanEdwards</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#46"><b class="cmd">::mapproj::fromTrystanEdwards</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#47"><b class="cmd">::mapproj::toHoboDyer</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#48"><b class="cmd">::mapproj::fromHoboDyer</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#49"><b class="cmd">::mapproj::toGallPeters</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#50"><b class="cmd">::mapproj::fromGallPeters</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#51"><b class="cmd">::mapproj::toBalthasart</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></li>
<li><a href="#52"><b class="cmd">::mapproj::fromBalthasart</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">mapproj</b> package provides a set of procedures for
converting between world co-ordinates (latitude and longitude) and map
co-ordinates on a number of different map projections.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<p>The following commands convert between world co-ordinates and
map co-ordinates:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::mapproj::toPlateCarree</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the <em>plate carrée</em> (cylindrical equidistant)
projection.</p></dd>
<dt><a name="2"><b class="cmd">::mapproj::fromPlateCarree</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the <em>plate carrée</em> (cylindrical equidistant)
projection.</p></dd>
<dt><a name="3"><b class="cmd">::mapproj::toCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the cylindrical equal-area projection.</p></dd>
<dt><a name="4"><b class="cmd">::mapproj::fromCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the cylindrical equal-area projection.</p></dd>
<dt><a name="5"><b class="cmd">::mapproj::toMercator</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Mercator (cylindrical conformal) projection.</p></dd>
<dt><a name="6"><b class="cmd">::mapproj::fromMercator</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Mercator (cylindrical conformal) projection.</p></dd>
<dt><a name="7"><b class="cmd">::mapproj::toMillerCylindrical</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Miller Cylindrical projection.</p></dd>
<dt><a name="8"><b class="cmd">::mapproj::fromMillerCylindrical</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Miller Cylindrical projection.</p></dd>
<dt><a name="9"><b class="cmd">::mapproj::toSinusoidal</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the sinusoidal (Sanson-Flamsteed) projection.
projection.</p></dd>
<dt><a name="10"><b class="cmd">::mapproj::fromSinusoidal</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the sinusoidal (Sanson-Flamsteed) projection.
projection.</p></dd>
<dt><a name="11"><b class="cmd">::mapproj::toMollweide</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Mollweide projection.</p></dd>
<dt><a name="12"><b class="cmd">::mapproj::fromMollweide</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Mollweide projection.</p></dd>
<dt><a name="13"><b class="cmd">::mapproj::toEckertIV</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Eckert IV projection.</p></dd>
<dt><a name="14"><b class="cmd">::mapproj::fromEckertIV</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Eckert IV projection.</p></dd>
<dt><a name="15"><b class="cmd">::mapproj::toEckertVI</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Eckert VI projection.</p></dd>
<dt><a name="16"><b class="cmd">::mapproj::fromEckertVI</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Eckert VI projection.</p></dd>
<dt><a name="17"><b class="cmd">::mapproj::toRobinson</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Robinson projection.</p></dd>
<dt><a name="18"><b class="cmd">::mapproj::fromRobinson</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Robinson projection.</p></dd>
<dt><a name="19"><b class="cmd">::mapproj::toCassini</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Cassini (transverse cylindrical equidistant)
projection.</p></dd>
<dt><a name="20"><b class="cmd">::mapproj::fromCassini</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Cassini (transverse cylindrical equidistant)
projection.</p></dd>
<dt><a name="21"><b class="cmd">::mapproj::toPeirceQuincuncial</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Peirce Quincuncial Projection.</p></dd>
<dt><a name="22"><b class="cmd">::mapproj::fromPeirceQuincuncial</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Peirce Quincuncial Projection.</p></dd>
<dt><a name="23"><b class="cmd">::mapproj::toOrthographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the orthographic projection.</p></dd>
<dt><a name="24"><b class="cmd">::mapproj::fromOrthographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the orthographic projection.</p></dd>
<dt><a name="25"><b class="cmd">::mapproj::toStereographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the stereographic (azimuthal conformal) projection.</p></dd>
<dt><a name="26"><b class="cmd">::mapproj::fromStereographic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the stereographic (azimuthal conformal) projection.</p></dd>
<dt><a name="27"><b class="cmd">::mapproj::toGnomonic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the gnomonic projection.</p></dd>
<dt><a name="28"><b class="cmd">::mapproj::fromGnomonic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the gnomonic projection.</p></dd>
<dt><a name="29"><b class="cmd">::mapproj::toAzimuthalEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the azimuthal equidistant projection.</p></dd>
<dt><a name="30"><b class="cmd">::mapproj::fromAzimuthalEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the azimuthal equidistant projection.</p></dd>
<dt><a name="31"><b class="cmd">::mapproj::toLambertAzimuthalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Lambert azimuthal equal-area projection.</p></dd>
<dt><a name="32"><b class="cmd">::mapproj::fromLambertAzimuthalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Lambert azimuthal equal-area projection.</p></dd>
<dt><a name="33"><b class="cmd">::mapproj::toHammer</b> <i class="arg">lambda_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Hammer projection.</p></dd>
<dt><a name="34"><b class="cmd">::mapproj::fromHammer</b> <i class="arg">lambda_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Hammer projection.</p></dd>
<dt><a name="35"><b class="cmd">::mapproj::toConicEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the conic equidistant projection.</p></dd>
<dt><a name="36"><b class="cmd">::mapproj::fromConicEquidistant</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the conic equidistant projection.</p></dd>
<dt><a name="37"><b class="cmd">::mapproj::toAlbersEqualAreaConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Albers equal-area conic projection.</p></dd>
<dt><a name="38"><b class="cmd">::mapproj::fromAlbersEqualAreaConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Albers equal-area conic projection.</p></dd>
<dt><a name="39"><b class="cmd">::mapproj::toLambertConformalConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Lambert conformal conic projection.</p></dd>
<dt><a name="40"><b class="cmd">::mapproj::fromLambertConformalConic</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">phi_1</i> <i class="arg">phi_2</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Lambert conformal conic projection.</p></dd>
</dl>
<p>Among the cylindrical equal-area projections, there are a number of
choices of standard parallels that have names:</p>
<dl class="doctools_definitions">
<dt><a name="41"><b class="cmd">::mapproj::toLambertCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Lambert cylindrical equal area projection. (standard parallel
is the Equator.)</p></dd>
<dt><a name="42"><b class="cmd">::mapproj::fromLambertCylindricalEqualArea</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Lambert cylindrical equal area projection. (standard parallel
is the Equator.)</p></dd>
<dt><a name="43"><b class="cmd">::mapproj::toBehrmann</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Behrmann cylindrical equal area projection. (standard parallels
are 30 degrees North and South)</p></dd>
<dt><a name="44"><b class="cmd">::mapproj::fromBehrmann</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Behrmann cylindrical equal area projection. (standard parallels
are 30 degrees North and South.)</p></dd>
<dt><a name="45"><b class="cmd">::mapproj::toTrystanEdwards</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Trystan Edwards cylindrical equal area projection. (standard parallels
are 37.4 degrees North and South)</p></dd>
<dt><a name="46"><b class="cmd">::mapproj::fromTrystanEdwards</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Trystan Edwards cylindrical equal area projection. (standard parallels
are 37.4 degrees North and South.)</p></dd>
<dt><a name="47"><b class="cmd">::mapproj::toHoboDyer</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Hobo-Dyer cylindrical equal area projection. (standard parallels
are 37.5 degrees North and South)</p></dd>
<dt><a name="48"><b class="cmd">::mapproj::fromHoboDyer</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Hobo-Dyer cylindrical equal area projection. (standard parallels
are 37.5 degrees North and South.)</p></dd>
<dt><a name="49"><b class="cmd">::mapproj::toGallPeters</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Gall-Peters cylindrical equal area projection. (standard parallels
are 45 degrees North and South)</p></dd>
<dt><a name="50"><b class="cmd">::mapproj::fromGallPeters</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Gall-Peters cylindrical equal area projection. (standard parallels
are 45 degrees North and South.)</p></dd>
<dt><a name="51"><b class="cmd">::mapproj::toBalthasart</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">lambda</i> <i class="arg">phi</i></a></dt>
<dd><p>Converts to the Balthasart cylindrical equal area projection. (standard parallels
are 50 degrees North and South)</p></dd>
<dt><a name="52"><b class="cmd">::mapproj::fromBalthasart</b> <i class="arg">lambda_0</i> <i class="arg">phi_0</i> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Converts from the Balthasart cylindrical equal area projection. (standard parallels
are 50 degrees North and South.)</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Arguments</a></h2>
<p>The following arguments are accepted by the projection commands:</p>
<dl class="doctools_definitions">
<dt><i class="arg">lambda</i></dt>
<dd><p>Longitude of the point to be projected, in degrees.</p></dd>
<dt><i class="arg">phi</i></dt>
<dd><p>Latitude of the point to be projected, in degrees.</p></dd>
<dt><i class="arg">lambda_0</i></dt>
<dd><p>Longitude of the center of the sheet, in degrees. For many projections,
this figure is also the reference meridian of the projection.</p></dd>
<dt><i class="arg">phi_0</i></dt>
<dd><p>Latitude of the center of the sheet, in degrees. For the azimuthal
projections, this figure is also the latitude of the center of the projection.</p></dd>
<dt><i class="arg">phi_1</i></dt>
<dd><p>Latitude of the first reference parallel, for projections that use reference
parallels.</p></dd>
<dt><i class="arg">phi_2</i></dt>
<dd><p>Latitude of the second reference parallel, for projections that use reference
parallels.</p></dd>
<dt><i class="arg">x</i></dt>
<dd><p>X co-ordinate of a point on the map, in units of Earth radii.</p></dd>
<dt><i class="arg">y</i></dt>
<dd><p>Y co-ordinate of a point on the map, in units of Earth radii.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Results</a></h2>
<p>For all of the procedures whose names begin with 'to', the return value
is a list comprising an <em>x</em> co-ordinate and a <em>y</em> co-ordinate.
The co-ordinates are relative to the center of the map sheet to be drawn,
measured in Earth radii at the reference location on the map.
For all of the functions whose names begin with 'from', the return value
is a list comprising the longitude and latitude, in degrees.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Choosing a projection</a></h2>
<p>This package offers a great many projections, because no single projection
is appropriate to all maps. This section attempts to provide guidance
on how to choose a projection.</p>
<p>First, consider the type of data that you intend to display on the map.
If the data are <em>directional</em> (<em>e.g.,</em> winds, ocean currents, or
magnetic fields) then you need to use a projection that preserves
angles; these are known as <em>conformal</em> projections. Conformal
projections include the Mercator, the Albers azimuthal equal-area,
the stereographic, and the Peirce Quincuncial projection. If the
data are <em>thematic</em>, describing properties of land or water, such
as temperature, population density, land use, or demographics; then
you need a projection that will show these data with the areas on the map
proportional to the areas in real life. These so-called <em>equal area</em>
projections include the various cylindrical equal area projections,
the sinusoidal projection, the Lambert azimuthal equal-area projection,
the Albers equal-area conic projection, and several of the world-map
projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson,
and Hammer). If the significant factor in your data is distance from a
central point or line (such as air routes), then you will do best with
an <em>equidistant</em> projection such as <em>plate carrée</em>,
Cassini, azimuthal equidistant, or conic equidistant. If direction from
a central point is a critical factor in your data (for instance,
air routes, radio antenna pointing), then you will almost surely want to
use one of the azimuthal projections. Appropriate choices are azimuthal
equidistant, azimuthal equal-area, stereographic, and perhaps orthographic.</p>
<p>Next, consider how much of the Earth your map will cover, and the general
shape of the area of interest. For maps of the entire Earth,
the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer
projections are good overall choices. The Mercator projection is traditional,
but the extreme distortions of area at high latitudes make it
a poor choice unless a conformal projection is required. The Peirce
projection is a better choice of conformal projection, having less distortion
of landforms. The Miller Cylindrical is a compromise designed to give
shapes similar to the traditional Mercator, but with less polar stretching.
The Peirce Quincuncial projection shows all the continents with acceptable
distortion if a reference meridian close to +20 degrees is chosen.
The Robinson projection yields attractive maps for things like political
divisions, but should be avoided in presenting scientific data, since other
projections have moe useful geometric properties.</p>
<p>If the map will cover a hemisphere, then choose stereographic,
azimuthal-equidistant, Hammer, or Mollweide projections; these all project
the hemisphere into a circle.</p>
<p>If the map will cover a large area (at least a few hundred km on a side),
but less than
a hemisphere, then you have several choices. Azimuthal projections
are usually good (choose stereographic, azimuthal equidistant, or
Lambert azimuthal equal-area according to whether shapes, distances from
a central point, or areas are important). Azimuthal projections (and possibly
the Cassini projection) are the only
really good choices for mapping the polar regions.</p>
<p>If the large area is in one of the temperate zones and is round or has
a primarily east-west extent, then the conic projections are good choices.
Choose the Lambert conformal conic, the conic equidistant, or the Albers
equal-area conic according to whether shape, distance, or area are the
most important parameters. For any of these, the reference parallels
should be chosen at approximately 1/6 and 5/6 of the range of latitudes
to be displayed. For instance, maps of the 48 coterminous United States
are attractive with reference parallels of 28.5 and 45.5 degrees.</p>
<p>If the large area is equatorial and is round or has a primarily east-west
extent, then the Mercator projection is a good choice for a conformal
projection; Lambert cylindrical equal-area and sinusoidal projections are
good equal-area projections; and the <em>plate carrée</em> is a
good equidistant projection.</p>
<p>Large areas having a primarily North-South aspect, particularly those
spanning the Equator, need some other choices. The Cassini projection
is a good choice for an equidistant projection (for instance, a Cassini
projection with a central meridian of 80 degrees West produces an
attractive map of the Americas). The cylindrical equal-area, Albers
equal-area conic, sinusoidal, Mollweide and Hammer
projections are possible choices for equal-area projections.
A good conformal projection in this situation is the Transverse
Mercator, which alas, is not yet implemented.</p>
<p>Small areas begin to get into a realm where the ellipticity of the
Earth affects the map scale. This package does not attempt to
handle accurate mapping for large-scale topographic maps. If
slight scale errors are acceptable in your application, then any
of the projections appropriate to large areas should work for
small ones as well.</p>
<p>There are a few projections that are included for their special
properties. The orthographic projection produces views of the
Earth as seen from space. The gnomonic projection produces a
map on which all great circles (the shortest distance between
two points on the Earth's surface) are rendered as straight lines.
While this projection is useful for navigational planning, it
has extreme distortions of shape and area, and can display
only a limited area of the Earth (substantially less than a hemisphere).</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#geodesy">geodesy</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#projection">projection</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Kevin B. Kenny <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/markdown/markdown.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<div class='fossil-doc' data-title='markdown - Markdown to HTML Converter'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">markdown(n) 1.1 tcllib "Markdown to HTML Converter"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>markdown - Converts Markdown text to HTML</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">Markdown 1.1</b></li>
<li>package require <b class="pkgname">textutil <span class="opt">?0.8?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::Markdown::convert</b> <i class="arg">markdown</i></a></li>
<li><a href="#2"><b class="cmd">::Markdown::register</b> <i class="arg">langspec</i> <i class="arg">converter</i></a></li>
<li><a href="#3"><b class="cmd">::Markdown::get_lang_counter</b></a></li>
<li><a href="#4"><b class="cmd">::Markdown::reset_lang_counter</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">Markdown</b> provides a command to convert
Markdown annotated text into HMTL.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::Markdown::convert</b> <i class="arg">markdown</i></a></dt>
<dd><p>This command takes in a block of Markdown text, and returns a block
of HTML.</p>
<p>The converter supports two types of syntax highlighting for
fenced code blocks: highlighting via a registered converter
(see <b class="cmd">::Markdown::register</b>), or pure JavaScript highlighting,
e.g. via "highlight.js", where the language specifier used in the
markup is set as CSS class of the "code" element in the returned markup.</p></dd>
<dt><a name="2"><b class="cmd">::Markdown::register</b> <i class="arg">langspec</i> <i class="arg">converter</i></a></dt>
<dd><p>Register a language specific converter for prettifying a code block
(e.g. syntax highlighting). Markdown supports fenced code blocks with
an optional language specifier (e.g. "tcl"). When the markdown parser
processes such a code block and a converter for the specified langspec
is registered, the converter is called with the raw code block as
argument. The converter is supposed to return the markup of the code
block as result. The specified converter can be an arbitrary Tcl
command, the raw text block is added as last argument upon invocation.</p></dd>
<dt><a name="3"><b class="cmd">::Markdown::get_lang_counter</b></a></dt>
<dd><p>Return a dict of language specifier and number of occurrences in
fenced code blocks. This function can be used e.g. to detect, whether
some CSS or JavaScript headers should be included for rendering
without the need of postprocessing the rendered result.</p></dd>
<dt><a name="4"><b class="cmd">::Markdown::reset_lang_counter</b></a></dt>
<dd><p>Reset the language counters.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/bigfloat.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
|
<div class='fossil-doc' data-title='math::bigfloat - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::bigfloat(n) 2.0.1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::bigfloat - Arbitrary precision floating-point numbers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">INTRODUCTION</a></li>
<li class="doctools_section"><a href="#section3">ARITHMETICS</a></li>
<li class="doctools_section"><a href="#section4">COMPARISONS</a></li>
<li class="doctools_section"><a href="#section5">ANALYSIS</a></li>
<li class="doctools_section"><a href="#section6">ROUNDING</a></li>
<li class="doctools_section"><a href="#section7">PRECISION</a></li>
<li class="doctools_section"><a href="#section8">WHAT ABOUT TCL 8.4 ?</a></li>
<li class="doctools_section"><a href="#section9">NAMESPACES AND OTHER PACKAGES</a></li>
<li class="doctools_section"><a href="#section10">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section11">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">math::bigfloat <span class="opt">?2.0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">fromstr</b> <i class="arg">number</i> <span class="opt">?<i class="arg">trailingZeros</i>?</span></a></li>
<li><a href="#2"><b class="cmd">tostr</b> <span class="opt">?<b class="option">-nosci</b>?</span> <i class="arg">number</i></a></li>
<li><a href="#3"><b class="cmd">fromdouble</b> <i class="arg">double</i> <span class="opt">?<i class="arg">decimals</i>?</span></a></li>
<li><a href="#4"><b class="cmd">todouble</b> <i class="arg">number</i></a></li>
<li><a href="#5"><b class="cmd">isInt</b> <i class="arg">number</i></a></li>
<li><a href="#6"><b class="cmd">isFloat</b> <i class="arg">number</i></a></li>
<li><a href="#7"><b class="cmd">int2float</b> <i class="arg">integer</i> <span class="opt">?<i class="arg">decimals</i>?</span></a></li>
<li><a href="#8"><b class="cmd">add</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#9"><b class="cmd">sub</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#10"><b class="cmd">mul</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#11"><b class="cmd">div</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#12"><b class="cmd">mod</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#13"><b class="cmd">abs</b> <i class="arg">x</i></a></li>
<li><a href="#14"><b class="cmd">opp</b> <i class="arg">x</i></a></li>
<li><a href="#15"><b class="cmd">pow</b> <i class="arg">x</i> <i class="arg">n</i></a></li>
<li><a href="#16"><b class="cmd">iszero</b> <i class="arg">x</i></a></li>
<li><a href="#17"><b class="cmd"><a href="../../../../index.html#equal">equal</a></b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#18"><b class="cmd">compare</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#19"><b class="cmd">sqrt</b> <i class="arg">x</i></a></li>
<li><a href="#20"><b class="cmd"><a href="../log/log.html">log</a></b> <i class="arg">x</i></a></li>
<li><a href="#21"><b class="cmd">exp</b> <i class="arg">x</i></a></li>
<li><a href="#22"><b class="cmd">cos</b> <i class="arg">x</i></a></li>
<li><a href="#23"><b class="cmd">sin</b> <i class="arg">x</i></a></li>
<li><a href="#24"><b class="cmd">tan</b> <i class="arg">x</i></a></li>
<li><a href="#25"><b class="cmd">cotan</b> <i class="arg">x</i></a></li>
<li><a href="#26"><b class="cmd">acos</b> <i class="arg">x</i></a></li>
<li><a href="#27"><b class="cmd">asin</b> <i class="arg">x</i></a></li>
<li><a href="#28"><b class="cmd">atan</b> <i class="arg">x</i></a></li>
<li><a href="#29"><b class="cmd">cosh</b> <i class="arg">x</i></a></li>
<li><a href="#30"><b class="cmd">sinh</b> <i class="arg">x</i></a></li>
<li><a href="#31"><b class="cmd">tanh</b> <i class="arg">x</i></a></li>
<li><a href="#32"><b class="cmd"><a href="../../../../index.html#pi">pi</a></b> <i class="arg">n</i></a></li>
<li><a href="#33"><b class="cmd">rad2deg</b> <i class="arg">radians</i></a></li>
<li><a href="#34"><b class="cmd">deg2rad</b> <i class="arg">degrees</i></a></li>
<li><a href="#35"><b class="cmd">round</b> <i class="arg">x</i></a></li>
<li><a href="#36"><b class="cmd">ceil</b> <i class="arg">x</i></a></li>
<li><a href="#37"><b class="cmd">floor</b> <i class="arg">x</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The bigfloat package provides arbitrary precision floating-point math
capabilities to the Tcl language. It is designed to work with Tcl 8.5,
but for Tcl 8.4 is provided an earlier version of this package.
See <span class="sectref"><a href="#section8">WHAT ABOUT TCL 8.4 ?</a></span> for more explanations.
By convention, we will talk about the numbers treated in this library as :</p>
<ul class="doctools_itemized">
<li><p>BigFloat for floating-point numbers of arbitrary length.</p></li>
<li><p>integers for arbitrary length signed integers, just as basic integers since Tcl 8.5.</p></li>
</ul>
<p>Each BigFloat is an interval, namely [<em>m-d, m+d</em>],
where <em>m</em> is the mantissa and <em>d</em> the uncertainty, representing the
limitation of that number's precision.
This is why we call such mathematics <em>interval computations</em>.
Just take an example in physics : when you measure a temperature, not all
digits you read are <em>significant</em>. Sometimes you just cannot trust all digits - not to mention if doubles (f.p. numbers) can handle all these digits.
BigFloat can handle this problem - trusting the digits you get - plus the ability to store numbers with an arbitrary precision.
BigFloats are internally represented at Tcl lists: this
package provides a set of procedures operating against
the internal representation in order to :</p>
<ul class="doctools_itemized">
<li><p>perform math operations on BigFloats and (optionnaly) with integers.</p></li>
<li><p>convert BigFloats from their internal representations to strings, and vice versa.</p></li>
</ul>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">INTRODUCTION</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">fromstr</b> <i class="arg">number</i> <span class="opt">?<i class="arg">trailingZeros</i>?</span></a></dt>
<dd><p>Converts <em>number</em> into a BigFloat. Its precision
is at least the number of digits provided by <em>number</em>.
If the <i class="arg">number</i> contains only digits and eventually a minus sign, it is considered as
an integer. Subsequently, no conversion is done at all.</p>
<p><i class="arg">trailingZeros</i> - the number of zeros to append at the end of the floating-point number
to get more precision. It cannot be applied to an integer.</p>
<pre class="doctools_example">
# x and y are BigFloats : the first string contained a dot, and the second an e sign
set x [fromstr -1.000000]
set y [fromstr 2000e30]
# let's see how we get integers
set t 20000000000000
# the old way (package 1.2) is still supported for backwards compatibility :
set m [fromstr 10000000000]
# but we do not need fromstr for integers anymore
set n -39
# t, m and n are integers
</pre>
<p>The <em>number</em>'s last digit is considered by the procedure to be true at +/-1,
For example, 1.00 is the interval [0.99, 1.01],
and 0.43 the interval [0.42, 0.44].
The Pi constant may be approximated by the number "3.1415".
This string could be considered as the interval [3.1414 , 3.1416] by <b class="cmd">fromstr</b>.
So, when you mean 1.0 as a double, you may have to write 1.000000 to get enough precision.
To learn more about this subject, see <span class="sectref"><a href="#section7">PRECISION</a></span>.</p>
<p>For example :</p>
<pre class="doctools_example">
set x [fromstr 1.0000000000]
# the next line does the same, but smarter
set y [fromstr 1. 10]
</pre>
</dd>
<dt><a name="2"><b class="cmd">tostr</b> <span class="opt">?<b class="option">-nosci</b>?</span> <i class="arg">number</i></a></dt>
<dd><p>Returns a string form of a BigFloat, in which all digits are exacts.
<em>All exact digits</em> means a rounding may occur, for example to zero,
if the uncertainty interval does not clearly show the true digits.
<em>number</em> may be an integer, causing the command to return exactly the input argument.
With the <b class="option">-nosci</b> option, the number returned is never shown in scientific
notation, i.e. not like '3.4523e+5' but like '345230.'.</p>
<pre class="doctools_example">
puts [tostr [fromstr 0.99999]] ;# 1.0000
puts [tostr [fromstr 1.00001]] ;# 1.0000
puts [tostr [fromstr 0.002]] ;# 0.e-2
</pre>
<p>See <span class="sectref"><a href="#section7">PRECISION</a></span> for that matter.
See also <b class="cmd">iszero</b> for how to detect zeros, which is useful when performing a division.</p></dd>
<dt><a name="3"><b class="cmd">fromdouble</b> <i class="arg">double</i> <span class="opt">?<i class="arg">decimals</i>?</span></a></dt>
<dd><p>Converts a double (a simple floating-point value) to a BigFloat, with
exactly <i class="arg">decimals</i> digits. Without the <i class="arg">decimals</i> argument,
it behaves like <b class="cmd">fromstr</b>.
Here, the only important feature you might care of is the ability
to create BigFloats with a fixed number of <i class="arg">decimals</i>.</p>
<pre class="doctools_example">
tostr [fromstr 1.111 4]
# returns : 1.111000 (3 zeros)
tostr [fromdouble 1.111 4]
# returns : 1.111
</pre>
</dd>
<dt><a name="4"><b class="cmd">todouble</b> <i class="arg">number</i></a></dt>
<dd><p>Returns a double, that may be used in <em>expr</em>,
from a BigFloat.</p></dd>
<dt><a name="5"><b class="cmd">isInt</b> <i class="arg">number</i></a></dt>
<dd><p>Returns 1 if <em>number</em> is an integer, 0 otherwise.</p></dd>
<dt><a name="6"><b class="cmd">isFloat</b> <i class="arg">number</i></a></dt>
<dd><p>Returns 1 if <em>number</em> is a BigFloat, 0 otherwise.</p></dd>
<dt><a name="7"><b class="cmd">int2float</b> <i class="arg">integer</i> <span class="opt">?<i class="arg">decimals</i>?</span></a></dt>
<dd><p>Converts an integer to a BigFloat with <em>decimals</em> trailing zeros.
The default, and minimal, number of <em>decimals</em> is 1.
When converting back to string, one decimal is lost:</p>
<pre class="doctools_example">
set n 10
set x [int2float $n]; # like fromstr 10.0
puts [tostr $x]; # prints "10."
set x [int2float $n 3]; # like fromstr 10.000
puts [tostr $x]; # prints "10.00"
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">ARITHMETICS</a></h2>
<dl class="doctools_definitions">
<dt><a name="8"><b class="cmd">add</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd></dd>
<dt><a name="9"><b class="cmd">sub</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd></dd>
<dt><a name="10"><b class="cmd">mul</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Return the sum, difference and product of <em>x</em> by <em>y</em>.
<i class="arg">x</i> - may be either a BigFloat or an integer
<i class="arg">y</i> - may be either a BigFloat or an integer
When both are integers, these commands behave like <b class="cmd">expr</b>.</p></dd>
<dt><a name="11"><b class="cmd">div</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd></dd>
<dt><a name="12"><b class="cmd">mod</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Return the quotient and the rest of <em>x</em> divided by <em>y</em>.
Each argument (<em>x</em> and <em>y</em>) can be either a BigFloat or an integer,
but you cannot divide an integer by a BigFloat
Divide by zero throws an error.</p></dd>
<dt><a name="13"><b class="cmd">abs</b> <i class="arg">x</i></a></dt>
<dd><p>Returns the absolute value of <em>x</em></p></dd>
<dt><a name="14"><b class="cmd">opp</b> <i class="arg">x</i></a></dt>
<dd><p>Returns the opposite of <em>x</em></p></dd>
<dt><a name="15"><b class="cmd">pow</b> <i class="arg">x</i> <i class="arg">n</i></a></dt>
<dd><p>Returns <em>x</em> taken to the <em>n</em>th power.
It only works if <em>n</em> is an integer.
<em>x</em> might be a BigFloat or an integer.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">COMPARISONS</a></h2>
<dl class="doctools_definitions">
<dt><a name="16"><b class="cmd">iszero</b> <i class="arg">x</i></a></dt>
<dd><p>Returns 1 if <em>x</em> is :</p>
<ul class="doctools_itemized">
<li><p>a BigFloat close enough to zero to raise "divide by zero".</p></li>
<li><p>the integer 0.</p></li>
</ul>
<p>See here how numbers that are close to zero are converted to strings:</p>
<pre class="doctools_example">
tostr [fromstr 0.001] ; # -> 0.e-2
tostr [fromstr 0.000000] ; # -> 0.e-5
tostr [fromstr -0.000001] ; # -> 0.e-5
tostr [fromstr 0.0] ; # -> 0.
tostr [fromstr 0.002] ; # -> 0.e-2
set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003
tostr $a ; # 0.e-2
iszero $a ; # false
set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002
tostr $a ; # 0.e-2
iszero $a ; # true
</pre>
</dd>
<dt><a name="17"><b class="cmd"><a href="../../../../index.html#equal">equal</a></b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Returns 1 if <em>x</em> and <em>y</em> are equal, 0 elsewhere.</p></dd>
<dt><a name="18"><b class="cmd">compare</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Returns 0 if both BigFloat arguments are equal,
1 if <em>x</em> is greater than <em>y</em>,
and -1 if <em>x</em> is lower than <em>y</em>.
You would not be able to compare an integer to a BigFloat :
the operands should be both BigFloats, or both integers.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ANALYSIS</a></h2>
<dl class="doctools_definitions">
<dt><a name="19"><b class="cmd">sqrt</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="20"><b class="cmd"><a href="../log/log.html">log</a></b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="21"><b class="cmd">exp</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="22"><b class="cmd">cos</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="23"><b class="cmd">sin</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="24"><b class="cmd">tan</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="25"><b class="cmd">cotan</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="26"><b class="cmd">acos</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="27"><b class="cmd">asin</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="28"><b class="cmd">atan</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="29"><b class="cmd">cosh</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="30"><b class="cmd">sinh</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="31"><b class="cmd">tanh</b> <i class="arg">x</i></a></dt>
<dd><p>The above functions return, respectively, the following :
square root, logarithm, exponential, cosine, sine,
tangent, cotangent, arc cosine, arc sine, arc tangent, hyperbolic
cosine, hyperbolic sine, hyperbolic tangent, of a BigFloat named <em>x</em>.</p></dd>
<dt><a name="32"><b class="cmd"><a href="../../../../index.html#pi">pi</a></b> <i class="arg">n</i></a></dt>
<dd><p>Returns a BigFloat representing the Pi constant with <em>n</em> digits after the dot.
<em>n</em> is a positive integer.</p></dd>
<dt><a name="33"><b class="cmd">rad2deg</b> <i class="arg">radians</i></a></dt>
<dd></dd>
<dt><a name="34"><b class="cmd">deg2rad</b> <i class="arg">degrees</i></a></dt>
<dd><p><i class="arg">radians</i> - angle expressed in radians (BigFloat)</p>
<p><i class="arg">degrees</i> - angle expressed in degrees (BigFloat)</p>
<p>Convert an angle from radians to degrees, and <em>vice versa</em>.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">ROUNDING</a></h2>
<dl class="doctools_definitions">
<dt><a name="35"><b class="cmd">round</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="36"><b class="cmd">ceil</b> <i class="arg">x</i></a></dt>
<dd></dd>
<dt><a name="37"><b class="cmd">floor</b> <i class="arg">x</i></a></dt>
<dd><p>The above functions return the <em>x</em> BigFloat,
rounded like with the same mathematical function in <em>expr</em>,
and returns it as an integer.</p></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">PRECISION</a></h2>
<p>How do conversions work with precision ?</p>
<ul class="doctools_itemized">
<li><p>When a BigFloat is converted from string, the internal representation
holds its uncertainty as 1 at the level of the last digit.</p></li>
<li><p>During computations, the uncertainty of each result
is internally computed the closest to the reality, thus saving the memory used.</p></li>
<li><p>When converting back to string, the digits that are printed
are not subject to uncertainty. However, some rounding is done, as not doing so
causes severe problems.</p></li>
</ul>
<p>Uncertainties are kept in the internal representation of the number ;
it is recommended to use <b class="cmd">tostr</b> only for outputting data (on the screen or in a file),
and NEVER call <b class="cmd">fromstr</b> with the result of <b class="cmd">tostr</b>.
It is better to always keep operands in their internal representation.
Due to the internals of this library, the uncertainty interval may be slightly
wider than expected, but this should not cause false digits.</p>
<p>Now you may ask this question : What precision am I going to get
after calling add, sub, mul or div?
First you set a number from the string representation and,
by the way, its uncertainty is set:</p>
<pre class="doctools_example">
set a [fromstr 1.230]
# $a belongs to [1.229, 1.231]
set a [fromstr 1.000]
# $a belongs to [0.999, 1.001]
# $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value)
</pre>
<p>The uncertainty of the sum, or the difference, of two numbers, is the sum
of their respective uncertainties.</p>
<pre class="doctools_example">
set a [fromstr 1.230]
set b [fromstr 2.340]
set sum [add $a $b]]
# the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2)
tostr $sum ; # 3.57
</pre>
<p>But when, for example, we add or substract an integer to a BigFloat,
the relative uncertainty of the result is unchanged. So it is desirable
not to convert integers to BigFloats:</p>
<pre class="doctools_example">
set a [fromstr 0.999999999]
# now something dangerous
set b [fromstr 2.000]
# the result has only 3 digits
tostr [add $a $b]
# how to keep precision at its maximum
puts [tostr [add $a 2]]
</pre>
<p>For multiplication and division, the relative uncertainties of the product
or the quotient, is the sum of the relative uncertainties of the operands.
Take care of division by zero : check each divider with <b class="cmd">iszero</b>.</p>
<pre class="doctools_example">
set num [fromstr 4.00]
set denom [fromstr 0.01]
puts [iszero $denom];# true
set quotient [div $num $denom];# error : divide by zero
# opposites of our operands
puts [compare $num [opp $num]]; # 1
puts [compare $denom [opp $denom]]; # 0 !!!
# No suprise ! 0 and its opposite are the same...
</pre>
<p>Effects of the precision of a number considered equal to zero
to the cos function:</p>
<pre class="doctools_example">
puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000
puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000
puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000
puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000
</pre>
<p>BigFloats with different internal representations may be converted
to the same string.</p>
<p>For most analysis functions (cosine, square root, logarithm, etc.), determining the precision
of the result is difficult.
It seems however that in many cases, the loss of precision in the result
is of one or two digits.
There are some exceptions : for example,</p>
<pre class="doctools_example">
tostr [exp [fromstr 100.0 10]]
# returns : 2.688117142e+43 which has only 10 digits of precision, although the entry
# has 14 digits of precision.
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">WHAT ABOUT TCL 8.4 ?</a></h2>
<p>If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be loaded,
switching back to <em>math::bigfloat</em> 1.2. Indeed, an important function introduced in Tcl 8.5
is required - the ability to handle bignums, that we can do with <b class="cmd">expr</b>.
Before 8.5, this ability was provided by several packages,
including the pure-Tcl <em>math::bignum</em> package provided by <em>tcllib</em>.
In this case, all you need to know, is that arguments to the commands explained here,
are expected to be in their internal representation.
So even with integers, you will need to call <b class="cmd">fromstr</b>
and <b class="cmd">tostr</b> in order to convert them between string and internal representations.</p>
<pre class="doctools_example">
#
# with Tcl 8.5
# ============
set a [pi 20]
# round returns an integer and 'everything is a string' applies to integers
# whatever big they are
puts [round [mul $a 10000000000]]
#
# the same with Tcl 8.4
# =====================
set a [pi 20]
# bignums (arbitrary length integers) need a conversion hook
set b [fromstr 10000000000]
# round returns a bignum:
# before printing it, we need to convert it with 'tostr'
puts [tostr [round [mul $a $b]]]
</pre>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">NAMESPACES AND OTHER PACKAGES</a></h2>
<p>We have not yet discussed about namespaces
because we assumed that you had imported public commands into the global namespace,
like this:</p>
<pre class="doctools_example">
namespace import ::math::bigfloat::*
</pre>
<p>If you matter much about avoiding names conflicts,
I considere it should be resolved by the following :</p>
<pre class="doctools_example">
package require math::bigfloat
# beware: namespace ensembles are not available in Tcl 8.4
namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat}
# from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands
set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]]
puts [bigfloat tostr $a]
</pre>
</div>
<div id="section10" class="doctools_section"><h2><a name="section10">EXAMPLES</a></h2>
<p>Guess what happens when you are doing some astronomy. Here is an example :</p>
<pre class="doctools_example">
# convert acurrate angles with a millisecond-rated accuracy
proc degree-angle {degrees minutes seconds milliseconds} {
set result 0
set div 1
foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] {
# we convert each entry var into milliseconds
set div [expr {$div*$factor}]
incr result [expr {$var*$div}]
}
return [div [int2float $result] $div]
}
# load the package
package require math::bigfloat
namespace import ::math::bigfloat::*
# work with angles : a standard formula for navigation (taking bearings)
set angle1 [deg2rad [degree-angle 20 30 40 0]]
set angle2 [deg2rad [degree-angle 21 0 50 500]]
set opposite3 [deg2rad [degree-angle 51 0 50 500]]
set sinProduct [mul [sin $angle1] [sin $angle2]]
set cosProduct [mul [cos $angle1] [cos $angle2]]
set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]]
puts "angle3 : [tostr [rad2deg $angle3]]"
</pre>
</div>
<div id="section11" class="doctools_section"><h2><a name="section11">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: bignum :: float</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#computations">computations</a>, <a href="../../../../index.html#floating_point">floating-point</a>, <a href="../../../../index.html#interval">interval</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#multiprecision">multiprecision</a>, <a href="../../../../index.html#tcl">tcl</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2008, by Stephane Arnold <stephanearnold at yahoo dot fr></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/bignum.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
<div class='fossil-doc' data-title='math::bignum - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::bignum(n) 3.1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::bignum - Arbitrary precision integer numbers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">math::bignum <span class="opt">?3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::bignum::fromstr</b> <i class="arg">string</i> ?<i class="arg">radix</i>?</a></li>
<li><a href="#2"><b class="cmd">::math::bignum::tostr</b> <i class="arg">bignum</i> ?<i class="arg">radix</i>?</a></li>
<li><a href="#3"><b class="cmd">::math::bignum::sign</b> <i class="arg">bignum</i></a></li>
<li><a href="#4"><b class="cmd">::math::bignum::abs</b> <i class="arg">bignum</i></a></li>
<li><a href="#5"><b class="cmd">::math::bignum::cmp</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#6"><b class="cmd">::math::bignum::iszero</b> <i class="arg">bignum</i></a></li>
<li><a href="#7"><b class="cmd">::math::bignum::lt</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#8"><b class="cmd">::math::bignum::le</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#9"><b class="cmd">::math::bignum::gt</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#10"><b class="cmd">::math::bignum::ge</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#11"><b class="cmd">::math::bignum::eq</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#12"><b class="cmd">::math::bignum::ne</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#13"><b class="cmd">::math::bignum::isodd</b> <i class="arg">bignum</i></a></li>
<li><a href="#14"><b class="cmd">::math::bignum::iseven</b> <i class="arg">bignum</i></a></li>
<li><a href="#15"><b class="cmd">::math::bignum::add</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#16"><b class="cmd">::math::bignum::sub</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#17"><b class="cmd">::math::bignum::mul</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#18"><b class="cmd">::math::bignum::divqr</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#19"><b class="cmd">::math::bignum::div</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#20"><b class="cmd">::math::bignum::rem</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#21"><b class="cmd">::math::bignum::mod</b> <i class="arg">n</i> <i class="arg">m</i></a></li>
<li><a href="#22"><b class="cmd">::math::bignum::pow</b> <i class="arg">base</i> <i class="arg">exp</i></a></li>
<li><a href="#23"><b class="cmd">::math::bignum::powm</b> <i class="arg">base</i> <i class="arg">exp</i> <i class="arg">m</i></a></li>
<li><a href="#24"><b class="cmd">::math::bignum::sqrt</b> <i class="arg">bignum</i></a></li>
<li><a href="#25"><b class="cmd">::math::bignum::rand</b> <i class="arg">bits</i></a></li>
<li><a href="#26"><b class="cmd">::math::bignum::lshift</b> <i class="arg">bignum</i> <i class="arg">bits</i></a></li>
<li><a href="#27"><b class="cmd">::math::bignum::rshift</b> <i class="arg">bignum</i> <i class="arg">bits</i></a></li>
<li><a href="#28"><b class="cmd">::math::bignum::bitand</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#29"><b class="cmd">::math::bignum::bitor</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#30"><b class="cmd">::math::bignum::bitxor</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#31"><b class="cmd">::math::bignum::setbit</b> <i class="arg">bignumVar</i> <i class="arg">bit</i></a></li>
<li><a href="#32"><b class="cmd">::math::bignum::clearbit</b> <i class="arg">bignumVar</i> <i class="arg">bit</i></a></li>
<li><a href="#33"><b class="cmd">::math::bignum::testbit</b> <i class="arg">bignum</i> <i class="arg">bit</i></a></li>
<li><a href="#34"><b class="cmd">::math::bignum::bits</b> <i class="arg">bignum</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The bignum package provides arbitrary precision integer math
(also known as "big numbers") capabilities to the Tcl language.
Big numbers are internally represented at Tcl lists: this
package provides a set of procedures operating against
the internal representation in order to:</p>
<ul class="doctools_itemized">
<li><p>perform math operations</p></li>
<li><p>convert bignums from the internal representation to a string in
the desired radix and vice versa.</p></li>
</ul>
<p>But the two constants "0" and "1" are automatically converted to
the internal representation, in order to easily compare a number to zero,
or increment a big number.</p>
<p>The bignum interface is opaque, so
operations on bignums that are not returned by procedures
in this package (but created by hand) may lead to unspecified behaviours.
It's safe to treat bignums as pure values, so there is no need
to free a bignum, or to duplicate it via a special operation.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>This section shows some simple example. This library being just
a way to perform math operations, examples may be the simplest way
to learn how to work with it. Consult the API section of
this man page for information about individual procedures.</p>
<pre class="doctools_example">
package require math::bignum
# Multiplication of two bignums
set a [::math::bignum::fromstr 88888881111111]
set b [::math::bignum::fromstr 22222220000000]
set c [::math::bignum::mul $a $b]
puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000
set c [::math::bignum::sqrt $c]
puts [::math::bignum::tostr $c] ; # => will output 44444440277777
# From/To string conversion in different radix
set a [::math::bignum::fromstr 1100010101010111001001111010111 2]
puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7
# Factorial example
proc fact n {
# fromstr is not needed for 0 and 1
set z 1
for {set i 2} {$i <= $n} {incr i} {
set z [::math::bignum::mul $z [::math::bignum::fromstr $i]]
}
return $z
}
puts [::math::bignum::tostr [fact 100]]
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::bignum::fromstr</b> <i class="arg">string</i> ?<i class="arg">radix</i>?</a></dt>
<dd><p>Convert <em>string</em> into a bignum. If <em>radix</em> is omitted or zero,
the string is interpreted in hex if prefixed with
<em>0x</em>, in octal if prefixed with <em>ox</em>,
in binary if it's pefixed with <em>bx</em>, as a number in
radix 10 otherwise. If instead the <em>radix</em> argument
is specified in the range 2-36, the <em>string</em> is interpreted
in the given radix. Please note that this conversion is
not needed for two constants : <em>0</em> and <em>1</em>. (see the example)</p></dd>
<dt><a name="2"><b class="cmd">::math::bignum::tostr</b> <i class="arg">bignum</i> ?<i class="arg">radix</i>?</a></dt>
<dd><p>Convert <em>bignum</em> into a string representing the number
in the specified radix. If <em>radix</em> is omitted, the
default is 10.</p></dd>
<dt><a name="3"><b class="cmd">::math::bignum::sign</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return the sign of the bignum.
The procedure returns 0 if the number is positive, 1 if it's negative.</p></dd>
<dt><a name="4"><b class="cmd">::math::bignum::abs</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return the absolute value of the bignum.</p></dd>
<dt><a name="5"><b class="cmd">::math::bignum::cmp</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two bignums a and b, returning <em>0</em> if <em>a == b</em>,
<em>1</em> if <em>a > b</em>, and <em>-1</em> if <em>a < b</em>.</p></dd>
<dt><a name="6"><b class="cmd">::math::bignum::iszero</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return true if <em>bignum</em> value is zero, otherwise false is returned.</p></dd>
<dt><a name="7"><b class="cmd">::math::bignum::lt</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return true if <em>a < b</em>, otherwise false is returned.</p></dd>
<dt><a name="8"><b class="cmd">::math::bignum::le</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return true if <em>a <= b</em>, otherwise false is returned.</p></dd>
<dt><a name="9"><b class="cmd">::math::bignum::gt</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return true if <em>a > b</em>, otherwise false is returned.</p></dd>
<dt><a name="10"><b class="cmd">::math::bignum::ge</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return true if <em>a >= b</em>, otherwise false is returned.</p></dd>
<dt><a name="11"><b class="cmd">::math::bignum::eq</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return true if <em>a == b</em>, otherwise false is returned.</p></dd>
<dt><a name="12"><b class="cmd">::math::bignum::ne</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return true if <em>a != b</em>, otherwise false is returned.</p></dd>
<dt><a name="13"><b class="cmd">::math::bignum::isodd</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return true if <em>bignum</em> is odd.</p></dd>
<dt><a name="14"><b class="cmd">::math::bignum::iseven</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return true if <em>bignum</em> is even.</p></dd>
<dt><a name="15"><b class="cmd">::math::bignum::add</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the sum of the two bignums <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="16"><b class="cmd">::math::bignum::sub</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the difference of the two bignums <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="17"><b class="cmd">::math::bignum::mul</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the product of the two bignums <em>a</em> and <em>b</em>.
The implementation uses Karatsuba multiplication if both
the numbers are bigger than a given threshold, otherwise
the direct algorith is used.</p></dd>
<dt><a name="18"><b class="cmd">::math::bignum::divqr</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return a two-elements list containing as first element
the quotient of the division between the two bignums
<em>a</em> and <em>b</em>, and the remainder of the division as second element.</p></dd>
<dt><a name="19"><b class="cmd">::math::bignum::div</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the quotient of the division between the two
bignums <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="20"><b class="cmd">::math::bignum::rem</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the remainder of the division between the two
bignums <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="21"><b class="cmd">::math::bignum::mod</b> <i class="arg">n</i> <i class="arg">m</i></a></dt>
<dd><p>Return <em>n</em> modulo <em>m</em>. This operation is
called modular reduction.</p></dd>
<dt><a name="22"><b class="cmd">::math::bignum::pow</b> <i class="arg">base</i> <i class="arg">exp</i></a></dt>
<dd><p>Return <em>base</em> raised to the exponent <em>exp</em>.</p></dd>
<dt><a name="23"><b class="cmd">::math::bignum::powm</b> <i class="arg">base</i> <i class="arg">exp</i> <i class="arg">m</i></a></dt>
<dd><p>Return <em>base</em> raised to the exponent <em>exp</em>,
modulo <em>m</em>. This function is often used in the field
of cryptography.</p></dd>
<dt><a name="24"><b class="cmd">::math::bignum::sqrt</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return the integer part of the square root of <em>bignum</em></p></dd>
<dt><a name="25"><b class="cmd">::math::bignum::rand</b> <i class="arg">bits</i></a></dt>
<dd><p>Return a random number of at most <em>bits</em> bits.
The returned number is internally generated using Tcl's <em>expr rand()</em>
function and is not suitable where an unguessable and cryptographically
secure random number is needed.</p></dd>
<dt><a name="26"><b class="cmd">::math::bignum::lshift</b> <i class="arg">bignum</i> <i class="arg">bits</i></a></dt>
<dd><p>Return the result of left shifting <em>bignum</em>'s binary
representation of <em>bits</em> positions on the left.
This is equivalent to multiplying by 2^<em>bits</em> but much faster.</p></dd>
<dt><a name="27"><b class="cmd">::math::bignum::rshift</b> <i class="arg">bignum</i> <i class="arg">bits</i></a></dt>
<dd><p>Return the result of right shifting <em>bignum</em>'s binary
representation of <em>bits</em> positions on the right.
This is equivalent to dividing by <em>2^bits</em> but much faster.</p></dd>
<dt><a name="28"><b class="cmd">::math::bignum::bitand</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the result of doing a bitwise AND operation on a
and b. The operation is restricted to positive numbers,
including zero. When negative numbers are provided as
arguments the result is undefined.</p></dd>
<dt><a name="29"><b class="cmd">::math::bignum::bitor</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the result of doing a bitwise OR operation on a
and b. The operation is restricted to positive numbers,
including zero. When negative numbers are provided as
arguments the result is undefined.</p></dd>
<dt><a name="30"><b class="cmd">::math::bignum::bitxor</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the result of doing a bitwise XOR operation on a
and b. The operation is restricted to positive numbers,
including zero. When negative numbers are provided as
arguments the result is undefined.</p></dd>
<dt><a name="31"><b class="cmd">::math::bignum::setbit</b> <i class="arg">bignumVar</i> <i class="arg">bit</i></a></dt>
<dd><p>Set the bit at <em>bit</em> position to 1 in the bignum stored
in the variable <em>bignumVar</em>. Bit 0 is the least significant.</p></dd>
<dt><a name="32"><b class="cmd">::math::bignum::clearbit</b> <i class="arg">bignumVar</i> <i class="arg">bit</i></a></dt>
<dd><p>Set the bit at <em>bit</em> position to 0 in the bignum stored
in the variable <em>bignumVar</em>. Bit 0 is the least significant.</p></dd>
<dt><a name="33"><b class="cmd">::math::bignum::testbit</b> <i class="arg">bignum</i> <i class="arg">bit</i></a></dt>
<dd><p>Return true if the bit at the <em>bit</em> position of <em>bignum</em>
is on, otherwise false is returned. If <em>bit</em> is out of
range, it is considered as set to zero.</p></dd>
<dt><a name="34"><b class="cmd">::math::bignum::bits</b> <i class="arg">bignum</i></a></dt>
<dd><p>Return the number of bits needed to represent bignum in radix 2.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: bignum</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bignums">bignums</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#multiprecision">multiprecision</a>, <a href="../../../../index.html#tcl">tcl</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Salvatore Sanfilippo <antirez at invece dot org><br>
Copyright © 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/calculus.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
|
<div class='fossil-doc' data-title='math::calculus - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::calculus(n) 0.8.2 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::calculus - Integration and ordinary differential equations</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">math::calculus 0.8.2</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::calculus::integral</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">nosteps</i> <i class="arg">func</i></a></li>
<li><a href="#2"><b class="cmd">::math::calculus::integralExpr</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">nosteps</i> <i class="arg">expression</i></a></li>
<li><a href="#3"><b class="cmd">::math::calculus::integral2D</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">func</i></a></li>
<li><a href="#4"><b class="cmd">::math::calculus::integral2D_accurate</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">func</i></a></li>
<li><a href="#5"><b class="cmd">::math::calculus::integral3D</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">zinterval</i> <i class="arg">func</i></a></li>
<li><a href="#6"><b class="cmd">::math::calculus::integral3D_accurate</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">zinterval</i> <i class="arg">func</i></a></li>
<li><a href="#7"><b class="cmd">::math::calculus::qk15</b> <i class="arg">xstart</i> <i class="arg">xend</i> <i class="arg">func</i> <i class="arg">nosteps</i></a></li>
<li><a href="#8"><b class="cmd">::math::calculus::qk15_detailed</b> <i class="arg">xstart</i> <i class="arg">xend</i> <i class="arg">func</i> <i class="arg">nosteps</i></a></li>
<li><a href="#9"><b class="cmd">::math::calculus::eulerStep</b> <i class="arg">t</i> <i class="arg">tstep</i> <i class="arg">xvec</i> <i class="arg">func</i></a></li>
<li><a href="#10"><b class="cmd">::math::calculus::heunStep</b> <i class="arg">t</i> <i class="arg">tstep</i> <i class="arg">xvec</i> <i class="arg">func</i></a></li>
<li><a href="#11"><b class="cmd">::math::calculus::rungeKuttaStep</b> <i class="arg">t</i> <i class="arg">tstep</i> <i class="arg">xvec</i> <i class="arg">func</i></a></li>
<li><a href="#12"><b class="cmd">::math::calculus::boundaryValueSecondOrder</b> <i class="arg">coeff_func</i> <i class="arg">force_func</i> <i class="arg">leftbnd</i> <i class="arg">rightbnd</i> <i class="arg">nostep</i></a></li>
<li><a href="#13"><b class="cmd">::math::calculus::solveTriDiagonal</b> <i class="arg">acoeff</i> <i class="arg">bcoeff</i> <i class="arg">ccoeff</i> <i class="arg">dvalue</i></a></li>
<li><a href="#14"><b class="cmd">::math::calculus::newtonRaphson</b> <i class="arg">func</i> <i class="arg">deriv</i> <i class="arg">initval</i></a></li>
<li><a href="#15"><b class="cmd">::math::calculus::newtonRaphsonParameters</b> <i class="arg">maxiter</i> <i class="arg">tolerance</i></a></li>
<li><a href="#16"><b class="cmd">::math::calculus::regula_falsi</b> <i class="arg">f</i> <i class="arg">xb</i> <i class="arg">xe</i> <i class="arg">eps</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements several simple mathematical algorithms:</p>
<ul class="doctools_itemized">
<li><p>The integration of a function over an interval</p></li>
<li><p>The numerical integration of a system of ordinary differential
equations.</p></li>
<li><p>Estimating the root(s) of an equation of one variable.</p></li>
</ul>
<p>The package is fully implemented in Tcl. No particular attention has
been paid to the accuracy of the calculations. Instead, well-known
algorithms have been used in a straightforward manner.</p>
<p>This document describes the procedures and explains their usage.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>This package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::calculus::integral</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">nosteps</i> <i class="arg">func</i></a></dt>
<dd><p>Determine the integral of the given function using the Simpson
rule. The interval for the integration is [<i class="arg">begin</i>, <i class="arg">end</i>].
The remaining arguments are:</p>
<dl class="doctools_definitions">
<dt><i class="arg">nosteps</i></dt>
<dd><p>Number of steps in which the interval is divided.</p></dd>
<dt><i class="arg">func</i></dt>
<dd><p>Function to be integrated. It should take one single argument.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::calculus::integralExpr</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">nosteps</i> <i class="arg">expression</i></a></dt>
<dd><p>Similar to the previous proc, this one determines the integral of
the given <i class="arg">expression</i> using the Simpson rule.
The interval for the integration is [<i class="arg">begin</i>, <i class="arg">end</i>].
The remaining arguments are:</p>
<dl class="doctools_definitions">
<dt><i class="arg">nosteps</i></dt>
<dd><p>Number of steps in which the interval is divided.</p></dd>
<dt><i class="arg">expression</i></dt>
<dd><p>Expression to be integrated. It should
use the variable "x" as the only variable (the "integrate")</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::calculus::integral2D</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">func</i></a></dt>
<dd></dd>
<dt><a name="4"><b class="cmd">::math::calculus::integral2D_accurate</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">func</i></a></dt>
<dd><p>The commands <b class="cmd">integral2D</b> and <b class="cmd">integral2D_accurate</b> calculate the
integral of a function of two variables over the rectangle given by the
first two arguments, each a list of three items, the start and
stop interval for the variable and the number of steps.</p>
<p>The command <b class="cmd">integral2D</b> evaluates the function at the centre of
each rectangle, whereas the command <b class="cmd">integral2D_accurate</b> uses a
four-point quadrature formula. This results in an exact integration of
polynomials of third degree or less.</p>
<p>The function must take two arguments and return the function
value.</p></dd>
<dt><a name="5"><b class="cmd">::math::calculus::integral3D</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">zinterval</i> <i class="arg">func</i></a></dt>
<dd></dd>
<dt><a name="6"><b class="cmd">::math::calculus::integral3D_accurate</b> <i class="arg">xinterval</i> <i class="arg">yinterval</i> <i class="arg">zinterval</i> <i class="arg">func</i></a></dt>
<dd><p>The commands <b class="cmd">integral3D</b> and <b class="cmd">integral3D_accurate</b> are the
three-dimensional equivalent of <b class="cmd">integral2D</b> and <b class="cmd">integral3D_accurate</b>.
The function <em>func</em> takes three arguments and is integrated over the block in
3D space given by three intervals.</p></dd>
<dt><a name="7"><b class="cmd">::math::calculus::qk15</b> <i class="arg">xstart</i> <i class="arg">xend</i> <i class="arg">func</i> <i class="arg">nosteps</i></a></dt>
<dd><p>Determine the integral of the given function using the Gauss-Kronrod 15 points quadrature rule.
The returned value is the estimate of the integral over the interval [<i class="arg">xstart</i>, <i class="arg">xend</i>].
The remaining arguments are:</p>
<dl class="doctools_definitions">
<dt><i class="arg">func</i></dt>
<dd><p>Function to be integrated. It should take one single argument.</p></dd>
<dt><span class="opt">?nosteps?</span></dt>
<dd><p>Number of steps in which the interval is divided. Defaults to 1.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::calculus::qk15_detailed</b> <i class="arg">xstart</i> <i class="arg">xend</i> <i class="arg">func</i> <i class="arg">nosteps</i></a></dt>
<dd><p>Determine the integral of the given function using the Gauss-Kronrod 15 points quadrature rule.
The interval for the integration is [<i class="arg">xstart</i>, <i class="arg">xend</i>].
The procedure returns a list of four values:</p>
<ul class="doctools_itemized">
<li><p>The estimate of the integral over the specified interval (I).</p></li>
<li><p>An estimate of the absolute error in I.</p></li>
<li><p>The estimate of the integral of the absolute value of the function over the interval.</p></li>
<li><p>The estimate of the integral of the absolute value of the function minus its mean over the interval.</p></li>
</ul>
<p>The remaining arguments are:</p>
<dl class="doctools_definitions">
<dt><i class="arg">func</i></dt>
<dd><p>Function to be integrated. It should take one single argument.</p></dd>
<dt><span class="opt">?nosteps?</span></dt>
<dd><p>Number of steps in which the interval is divided. Defaults to 1.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::calculus::eulerStep</b> <i class="arg">t</i> <i class="arg">tstep</i> <i class="arg">xvec</i> <i class="arg">func</i></a></dt>
<dd><p>Set a single step in the numerical integration of a system of
differential equations. The method used is Euler's.</p>
<dl class="doctools_definitions">
<dt><i class="arg">t</i></dt>
<dd><p>Value of the independent variable (typically time)
at the beginning of the step.</p></dd>
<dt><i class="arg">tstep</i></dt>
<dd><p>Step size for the independent variable.</p></dd>
<dt><i class="arg">xvec</i></dt>
<dd><p>List (vector) of dependent values</p></dd>
<dt><i class="arg">func</i></dt>
<dd><p>Function of t and the dependent values, returning
a list of the derivatives of the dependent values. (The lengths of
xvec and the return value of "func" must match).</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::calculus::heunStep</b> <i class="arg">t</i> <i class="arg">tstep</i> <i class="arg">xvec</i> <i class="arg">func</i></a></dt>
<dd><p>Set a single step in the numerical integration of a system of
differential equations. The method used is Heun's.</p>
<dl class="doctools_definitions">
<dt><i class="arg">t</i></dt>
<dd><p>Value of the independent variable (typically time)
at the beginning of the step.</p></dd>
<dt><i class="arg">tstep</i></dt>
<dd><p>Step size for the independent variable.</p></dd>
<dt><i class="arg">xvec</i></dt>
<dd><p>List (vector) of dependent values</p></dd>
<dt><i class="arg">func</i></dt>
<dd><p>Function of t and the dependent values, returning
a list of the derivatives of the dependent values. (The lengths of
xvec and the return value of "func" must match).</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::calculus::rungeKuttaStep</b> <i class="arg">t</i> <i class="arg">tstep</i> <i class="arg">xvec</i> <i class="arg">func</i></a></dt>
<dd><p>Set a single step in the numerical integration of a system of
differential equations. The method used is Runge-Kutta 4th
order.</p>
<dl class="doctools_definitions">
<dt><i class="arg">t</i></dt>
<dd><p>Value of the independent variable (typically time)
at the beginning of the step.</p></dd>
<dt><i class="arg">tstep</i></dt>
<dd><p>Step size for the independent variable.</p></dd>
<dt><i class="arg">xvec</i></dt>
<dd><p>List (vector) of dependent values</p></dd>
<dt><i class="arg">func</i></dt>
<dd><p>Function of t and the dependent values, returning
a list of the derivatives of the dependent values. (The lengths of
xvec and the return value of "func" must match).</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::math::calculus::boundaryValueSecondOrder</b> <i class="arg">coeff_func</i> <i class="arg">force_func</i> <i class="arg">leftbnd</i> <i class="arg">rightbnd</i> <i class="arg">nostep</i></a></dt>
<dd><p>Solve a second order linear differential equation with boundary
values at two sides. The equation has to be of the form (the
"conservative" form):</p>
<pre class="doctools_example">
d dy d
-- A(x)-- + -- B(x)y + C(x)y = D(x)
dx dx dx
</pre>
<p>Ordinarily, such an equation would be written as:</p>
<pre class="doctools_example">
d2y dy
a(x)--- + b(x)-- + c(x) y = D(x)
dx2 dx
</pre>
<p>The first form is easier to discretise (by integrating over a
finite volume) than the second form. The relation between the two
forms is fairly straightforward:</p>
<pre class="doctools_example">
A(x) = a(x)
B(x) = b(x) - a'(x)
C(x) = c(x) - B'(x) = c(x) - b'(x) + a''(x)
</pre>
<p>Because of the differentiation, however, it is much easier to ask
the user to provide the functions A, B and C directly.</p>
<dl class="doctools_definitions">
<dt><i class="arg">coeff_func</i></dt>
<dd><p>Procedure returning the three coefficients
(A, B, C) of the equation, taking as its one argument the x-coordinate.</p></dd>
<dt><i class="arg">force_func</i></dt>
<dd><p>Procedure returning the right-hand side
(D) as a function of the x-coordinate.</p></dd>
<dt><i class="arg">leftbnd</i></dt>
<dd><p>A list of two values: the x-coordinate of the
left boundary and the value at that boundary.</p></dd>
<dt><i class="arg">rightbnd</i></dt>
<dd><p>A list of two values: the x-coordinate of the
right boundary and the value at that boundary.</p></dd>
<dt><i class="arg">nostep</i></dt>
<dd><p>Number of steps by which to discretise the
interval.
The procedure returns a list of x-coordinates and the approximated
values of the solution.</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::calculus::solveTriDiagonal</b> <i class="arg">acoeff</i> <i class="arg">bcoeff</i> <i class="arg">ccoeff</i> <i class="arg">dvalue</i></a></dt>
<dd><p>Solve a system of linear equations Ax = b with A a tridiagonal
matrix. Returns the solution as a list.</p>
<dl class="doctools_definitions">
<dt><i class="arg">acoeff</i></dt>
<dd><p>List of values on the lower diagonal</p></dd>
<dt><i class="arg">bcoeff</i></dt>
<dd><p>List of values on the main diagonal</p></dd>
<dt><i class="arg">ccoeff</i></dt>
<dd><p>List of values on the upper diagonal</p></dd>
<dt><i class="arg">dvalue</i></dt>
<dd><p>List of values on the righthand-side</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::math::calculus::newtonRaphson</b> <i class="arg">func</i> <i class="arg">deriv</i> <i class="arg">initval</i></a></dt>
<dd><p>Determine the root of an equation given by</p>
<pre class="doctools_example">
func(x) = 0
</pre>
<p>using the method of Newton-Raphson. The procedure takes the following
arguments:</p>
<dl class="doctools_definitions">
<dt><i class="arg">func</i></dt>
<dd><p>Procedure that returns the value the function at x</p></dd>
<dt><i class="arg">deriv</i></dt>
<dd><p>Procedure that returns the derivative of the function at x</p></dd>
<dt><i class="arg">initval</i></dt>
<dd><p>Initial value for x</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::calculus::newtonRaphsonParameters</b> <i class="arg">maxiter</i> <i class="arg">tolerance</i></a></dt>
<dd><p>Set the numerical parameters for the Newton-Raphson method:</p>
<dl class="doctools_definitions">
<dt><i class="arg">maxiter</i></dt>
<dd><p>Maximum number of iteration steps (defaults to 20)</p></dd>
<dt><i class="arg">tolerance</i></dt>
<dd><p>Relative precision (defaults to 0.001)</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::calculus::regula_falsi</b> <i class="arg">f</i> <i class="arg">xb</i> <i class="arg">xe</i> <i class="arg">eps</i></a></dt>
<dd><p>Return an estimate of the zero or one of the zeros of the function
contained in the interval [xb,xe]. The error in this estimate is of the
order of eps*abs(xe-xb), the actual error may be slightly larger.</p>
<p>The method used is the so-called <em>regula falsi</em> or
<em>false position</em> method. It is a straightforward implementation.
The method is robust, but requires that the interval brackets a zero or
at least an uneven number of zeros, so that the value of the function at
the start has a different sign than the value at the end.</p>
<p>In contrast to Newton-Raphson there is no need for the computation of
the function's derivative.</p>
<dl class="doctools_arguments">
<dt>command <i class="arg">f</i></dt>
<dd><p>Name of the command that evaluates the function for
which the zero is to be returned</p></dd>
<dt>float <i class="arg">xb</i></dt>
<dd><p>Start of the interval in which the zero is supposed
to lie</p></dd>
<dt>float <i class="arg">xe</i></dt>
<dd><p>End of the interval</p></dd>
<dt>float <i class="arg">eps</i></dt>
<dd><p>Relative allowed error (defaults to 1.0e-4)</p></dd>
</dl></dd>
</dl>
<p><em>Notes:</em></p>
<p>Several of the above procedures take the <em>names</em> of procedures as
arguments. To avoid problems with the <em>visibility</em> of these
procedures, the fully-qualified name of these procedures is determined
inside the calculus routines. For the user this has only one
consequence: the named procedure must be visible in the calling
procedure. For instance:</p>
<pre class="doctools_example">
namespace eval ::mySpace {
namespace export calcfunc
proc calcfunc { x } { return $x }
}
#
# Use a fully-qualified name
#
namespace eval ::myCalc {
proc detIntegral { begin end } {
return [integral $begin $end 100 ::mySpace::calcfunc]
}
}
#
# Import the name
#
namespace eval ::myCalc {
namespace import ::mySpace::calcfunc
proc detIntegral { begin end } {
return [integral $begin $end 100 calcfunc]
}
}
</pre>
<p>Enhancements for the second-order boundary value problem:</p>
<ul class="doctools_itemized">
<li><p>Other types of boundary conditions (zero gradient, zero flux)</p></li>
<li><p>Other schematisation of the first-order term (now central
differences are used, but upstream differences might be useful too).</p></li>
</ul>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>Let us take a few simple examples:</p>
<p>Integrate x over the interval [0,100] (20 steps):</p>
<pre class="doctools_example">
proc linear_func { x } { return $x }
puts "Integral: [::math::calculus::integral 0 100 20 linear_func]"
</pre>
<p>For simple functions, the alternative could be:</p>
<pre class="doctools_example">
puts "Integral: [::math::calculus::integralExpr 0 100 20 {$x}]"
</pre>
<p>Do not forget the braces!</p>
<p>The differential equation for a dampened oscillator:</p>
<pre class="doctools_example">
x'' + rx' + wx = 0
</pre>
<p>can be split into a system of first-order equations:</p>
<pre class="doctools_example">
x' = y
y' = -ry - wx
</pre>
<p>Then this system can be solved with code like this:</p>
<pre class="doctools_example">
proc dampened_oscillator { t xvec } {
set x [lindex $xvec 0]
set x1 [lindex $xvec 1]
return [list $x1 [expr {-$x1-$x}]]
}
set xvec { 1.0 0.0 }
set t 0.0
set tstep 0.1
for { set i 0 } { $i < 20 } { incr i } {
set result [::math::calculus::eulerStep $t $tstep $xvec dampened_oscillator]
puts "Result ($t): $result"
set t [expr {$t+$tstep}]
set xvec $result
}
</pre>
<p>Suppose we have the boundary value problem:</p>
<pre class="doctools_example">
Dy'' + ky = 0
x = 0: y = 1
x = L: y = 0
</pre>
<p>This boundary value problem could originate from the diffusion of a
decaying substance.</p>
<p>It can be solved with the following fragment:</p>
<pre class="doctools_example">
proc coeffs { x } { return [list $::Diff 0.0 $::decay] }
proc force { x } { return 0.0 }
set Diff 1.0e-2
set decay 0.0001
set length 100.0
set y [::math::calculus::boundaryValueSecondOrder \
coeffs force {0.0 1.0} [list $length 0.0] 100]
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: calculus</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>romberg</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#calculus">calculus</a>, <a href="../../../../index.html#differential_equations">differential equations</a>, <a href="../../../../index.html#integration">integration</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#roots">roots</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002,2003,2004 Arjen Markus</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/combinatorics.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
<div class='fossil-doc' data-title='math::combinatorics - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::combinatorics(n) 1.2.3 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::combinatorics - Combinatorial functions in the Tcl Math Library</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">math <span class="opt">?1.2.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::ln_Gamma</b> <i class="arg">z</i></a></li>
<li><a href="#2"><b class="cmd">::math::factorial</b> <i class="arg">x</i></a></li>
<li><a href="#3"><b class="cmd">::math::choose</b> <i class="arg">n k</i></a></li>
<li><a href="#4"><b class="cmd">::math::Beta</b> <i class="arg">z w</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package"><a href="math.html">math</a></b> package contains implementations of several
functions useful in combinatorial problems.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::ln_Gamma</b> <i class="arg">z</i></a></dt>
<dd><p>Returns the natural logarithm of the Gamma function for the argument
<i class="arg">z</i>.</p>
<p>The Gamma function is defined as the improper integral from zero to
positive infinity of</p>
<pre class="doctools_example">
t**(x-1)*exp(-t) dt
</pre>
<p>The approximation used in the Tcl Math Library is from Lanczos,
<em>ISIAM J. Numerical Analysis, series B,</em> volume 1, p. 86.
For "<b class="variable">x</b> > 1", the absolute error of the result is claimed to be
smaller than 5.5*10**-10 -- that is, the resulting value of Gamma when</p>
<pre class="doctools_example">
exp( ln_Gamma( x) )
</pre>
<p>is computed is expected to be precise to better than nine significant
figures.</p></dd>
<dt><a name="2"><b class="cmd">::math::factorial</b> <i class="arg">x</i></a></dt>
<dd><p>Returns the factorial of the argument <i class="arg">x</i>.</p>
<p>For integer <i class="arg">x</i>, 0 <= <i class="arg">x</i> <= 12, an exact integer result is
returned.</p>
<p>For integer <i class="arg">x</i>, 13 <= <i class="arg">x</i> <= 21, an exact floating-point
result is returned on machines with IEEE floating point.</p>
<p>For integer <i class="arg">x</i>, 22 <= <i class="arg">x</i> <= 170, the result is exact to 1
ULP.</p>
<p>For real <i class="arg">x</i>, <i class="arg">x</i> >= 0, the result is approximated by
computing <i class="term">Gamma(x+1)</i> using the <b class="cmd">::math::ln_Gamma</b>
function, and the result is expected to be precise to better than nine
significant figures.</p>
<p>It is an error to present <i class="arg">x</i> <= -1 or <i class="arg">x</i> > 170, or a value
of <i class="arg">x</i> that is not numeric.</p></dd>
<dt><a name="3"><b class="cmd">::math::choose</b> <i class="arg">n k</i></a></dt>
<dd><p>Returns the binomial coefficient <i class="term">C(n, k)</i></p>
<pre class="doctools_example">
C(n,k) = n! / k! (n-k)!
</pre>
<p>If both parameters are integers and the result fits in 32 bits, the
result is rounded to an integer.</p>
<p>Integer results are exact up to at least <i class="arg">n</i> = 34. Floating point
results are precise to better than nine significant figures.</p></dd>
<dt><a name="4"><b class="cmd">::math::Beta</b> <i class="arg">z w</i></a></dt>
<dd><p>Returns the Beta function of the parameters <i class="arg">z</i> and <i class="arg">w</i>.</p>
<pre class="doctools_example">
Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w)
</pre>
<p>Results are returned as a floating point number precise to better than
nine significant digits provided that <i class="arg">w</i> and <i class="arg">z</i> are both at
least 1.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/constants.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
<div class='fossil-doc' data-title='math::constants - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::constants(n) 1.0.2 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::constants - Mathematical and numerical constants</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">Constants</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.3?</span></b></li>
<li>package require <b class="pkgname">math::constants <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::constants::constants</b> <i class="arg">args</i></a></li>
<li><a href="#2"><b class="cmd">::math::constants::print-constants</b> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package defines some common mathematical and numerical constants.
By using the package you get consistent values for numbers like pi and
ln(10).</p>
<p>It defines two commands:</p>
<ul class="doctools_itemized">
<li><p>One for importing the constants</p></li>
<li><p>One for reporting which constants are defined and what values they
actually have.</p></li>
</ul>
<p>The motivation for this package is that quite often, with
(mathematical) computations, you need a good approximation to, say,
the ratio of degrees to radians. You can, of course, define this
like:</p>
<pre class="doctools_example">
variable radtodeg [expr {180.0/(4.0*atan(1.0))}]
</pre>
<p>and use the variable radtodeg whenever you need the conversion.</p>
<p>This has two drawbacks:</p>
<ul class="doctools_itemized">
<li><p>You need to remember the proper formula or value and that is
error-prone.</p></li>
<li><p>Especially with the use of mathematical functions like <em>atan</em>
you assume that they have been accurately implemented. This is seldom or
never the case and for each platform you can get subtle differences.</p></li>
</ul>
<p>Here is the way you can do it with the <em>math::constants</em> package:</p>
<pre class="doctools_example">
package require math::constants
::math::constants::constants radtodeg degtorad
</pre>
<p>which creates two variables, radtodeg and (its reciprocal) degtorad
in the calling namespace.</p>
<p>Constants that have been defined (their values are mostly taken
from mathematical tables with more precision than usually can be
handled) include:</p>
<ul class="doctools_itemized">
<li><p>basic constants like pi, e, gamma (Euler's constant)</p></li>
<li><p>derived values like ln(10) and sqrt(2)</p></li>
<li><p>purely numerical values such as 1/3 that are included for convenience
and for the fact that certain seemingly trivial computations like:</p>
<pre class="doctools_example">
set value [expr {3.0*$onethird}]
</pre>
<p>give <em>exactly</em> the value you expect (if IEEE arithmetic is
available).</p></li>
</ul>
<p>The full set of named constants is listed in section <span class="sectref"><a href="#section3">Constants</a></span>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::constants::constants</b> <i class="arg">args</i></a></dt>
<dd><p>Import the constants whose names are given as arguments</p></dd>
<dt><a name="2"><b class="cmd">::math::constants::print-constants</b> <i class="arg">args</i></a></dt>
<dd><p>Print the constants whose names are given as arguments on the screen
(name, value and description) or, if no arguments are given, print all
defined constants. This is mainly a convenience procedure.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Constants</a></h2>
<dl class="doctools_definitions">
<dt><b class="const">pi</b></dt>
<dd><p>Ratio of circle circumference to diameter</p></dd>
<dt><b class="const">e</b></dt>
<dd><p>Base for natural logarithm</p></dd>
<dt><b class="const">ln10</b></dt>
<dd><p>Natural logarithm of 10</p></dd>
<dt><b class="const">phi</b></dt>
<dd><p>Golden ratio</p></dd>
<dt><b class="const">gamma</b></dt>
<dd><p>Euler's constant</p></dd>
<dt><b class="const">sqrt2</b></dt>
<dd><p>Square root of 2</p></dd>
<dt><b class="const">thirdrt2</b></dt>
<dd><p>One-third power of 2</p></dd>
<dt><b class="const">sqrt3</b></dt>
<dd><p>Square root of 3</p></dd>
<dt><b class="const">radtodeg</b></dt>
<dd><p>Conversion from radians to degrees</p></dd>
<dt><b class="const">degtorad</b></dt>
<dd><p>Conversion from degrees to radians</p></dd>
<dt><b class="const">onethird</b></dt>
<dd><p>One third (0.3333....)</p></dd>
<dt><b class="const">twothirds</b></dt>
<dd><p>Two thirds (0.6666....)</p></dd>
<dt><b class="const">onesixth</b></dt>
<dd><p>One sixth (0.1666....)</p></dd>
<dt><b class="const">huge</b></dt>
<dd><p>(Approximately) largest number</p></dd>
<dt><b class="const">tiny</b></dt>
<dd><p>(Approximately) smallest number not equal zero</p></dd>
<dt><b class="const">eps</b></dt>
<dd><p>Smallest number such that 1+eps != 1</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: constants</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#constants">constants</a>, <a href="../../../../index.html#degrees">degrees</a>, <a href="../../../../index.html#e">e</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#pi">pi</a>, <a href="../../../../index.html#radians">radians</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/decimal.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<div class='fossil-doc' data-title='math::decimal - Tcl Decimal Arithmetic Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::decimal(n) 1.0.3 tcllib "Tcl Decimal Arithmetic Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::decimal - General decimal arithmetic</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.5?</span></b></li>
<li>package require <b class="pkgname">math::decimal 1.0.3</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::decimal::fromstr</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::math::decimal::tostr</b> <i class="arg">decimal</i></a></li>
<li><a href="#3"><b class="cmd">::math::decimal::setVariable</b> <i class="arg">variable</i> <i class="arg">setting</i></a></li>
<li><a href="#4"><b class="cmd">::math::decimal::add</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#5"><b class="cmd">::math::decimal::+</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#6"><b class="cmd">::math::decimal::subtract</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#7"><b class="cmd">::math::decimal::-</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#8"><b class="cmd">::math::decimal::multiply</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#9"><b class="cmd">::math::decimal::*</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#10"><b class="cmd">::math::decimal::divide</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#11"><b class="cmd">::math::decimal::/</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#12"><b class="cmd">::math::decimal::divideint</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#13"><b class="cmd">::math::decimal::remainder</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#14"><b class="cmd">::math::decimal::abs</b> <i class="arg">decimal</i></a></li>
<li><a href="#15"><b class="cmd">::math::decimal::compare</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#16"><b class="cmd">::math::decimal::max</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#17"><b class="cmd">::math::decimal::maxmag</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#18"><b class="cmd">::math::decimal::min</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#19"><b class="cmd">::math::decimal::minmag</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#20"><b class="cmd">::math::decimal::plus</b> <i class="arg">a</i></a></li>
<li><a href="#21"><b class="cmd">::math::decimal::minus</b> <i class="arg">a</i></a></li>
<li><a href="#22"><b class="cmd">::math::decimal::copynegate</b> <i class="arg">a</i></a></li>
<li><a href="#23"><b class="cmd">::math::decimal::copysign</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#24"><b class="cmd">::math::decimal::is-signed</b> <i class="arg">decimal</i></a></li>
<li><a href="#25"><b class="cmd">::math::decimal::is-zero</b> <i class="arg">decimal</i></a></li>
<li><a href="#26"><b class="cmd">::math::decimal::is-NaN</b> <i class="arg">decimal</i></a></li>
<li><a href="#27"><b class="cmd">::math::decimal::is-infinite</b> <i class="arg">decimal</i></a></li>
<li><a href="#28"><b class="cmd">::math::decimal::is-finite</b> <i class="arg">decimal</i></a></li>
<li><a href="#29"><b class="cmd">::math::decimal::fma</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">c</i></a></li>
<li><a href="#30"><b class="cmd">::math::decimal::round_half_even</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#31"><b class="cmd">::math::decimal::round_half_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#32"><b class="cmd">::math::decimal::round_half_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#33"><b class="cmd">::math::decimal::round_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#34"><b class="cmd">::math::decimal::round_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#35"><b class="cmd">::math::decimal::round_floor</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#36"><b class="cmd">::math::decimal::round_ceiling</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#37"><b class="cmd">::math::decimal::round_05up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The decimal package provides decimal arithmetic support for both limited
precision floating point and arbitrary precision floating point.
Additionally, integer arithmetic is supported.</p>
<p>More information and the specifications on which this package depends can be
found on the general decimal arithmetic page at http://speleotrove.com/decimal
This package provides for:</p>
<ul class="doctools_itemized">
<li><p>A new data type decimal which is represented as a list containing sign,
mantissa and exponent.</p></li>
<li><p>Arithmetic operations on those decimal numbers such as addition, subtraction,
multiplication, etc...</p></li>
</ul>
<p>Numbers are converted to decimal format using the operation ::math::decimal::fromstr.</p>
<p>Numbers are converted back to string format using the operation
::math::decimal::tostr.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>This section shows some simple examples. Since the purpose of this library
is to perform decimal math operations, examples may be the simplest way
to learn how to work with it and to see the difference between using this
package and sticking with expr. Consult the API section of
this man page for information about individual procedures.</p>
<pre class="doctools_example">
package require math::decimal
# Various operations on two numbers.
# We first convert them to decimal format.
set a [::math::decimal::fromstr 8.2]
set b [::math::decimal::fromstr .2]
# Then we perform our operations. Here we add
set c [::math::decimal::+ $a $b]
# Finally we convert back to string format for presentation to the user.
puts [::math::decimal::tostr $c] ; # => will output 8.4
# Other examples
#
# Subtraction
set c [::math::decimal::- $a $b]
puts [::math::decimal::tostr $c] ; # => will output 8.0
# Why bother using this instead of simply expr?
puts [expr {8.2 + .2}] ; # => will output 8.399999999999999
puts [expr {8.2 - .2}] ; # => will output 7.999999999999999
# See http://speleotrove.com/decimal to learn more about why this happens.
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::decimal::fromstr</b> <i class="arg">string</i></a></dt>
<dd><p>Convert <em>string</em> into a decimal.</p></dd>
<dt><a name="2"><b class="cmd">::math::decimal::tostr</b> <i class="arg">decimal</i></a></dt>
<dd><p>Convert <em>decimal</em> into a string representing the number in base 10.</p></dd>
<dt><a name="3"><b class="cmd">::math::decimal::setVariable</b> <i class="arg">variable</i> <i class="arg">setting</i></a></dt>
<dd><p>Sets the <em>variable</em> to <em>setting</em>. Valid variables are:</p>
<ul class="doctools_itemized">
<li><p><i class="arg">rounding</i> - Method of rounding to use during rescale. Valid
methods are round_half_even, round_half_up, round_half_down,
round_down, round_up, round_floor, round_ceiling.</p></li>
<li><p><i class="arg">precision</i> - Maximum number of digits allowed in mantissa.</p></li>
<li><p><i class="arg">extended</i> - Set to 1 for extended mode. 0 for simplified mode.</p></li>
<li><p><i class="arg">maxExponent</i> - Maximum value for the exponent. Defaults to 999.</p></li>
<li><p><i class="arg">minExponent</i> - Minimum value for the exponent. Default to -998.</p></li>
</ul></dd>
<dt><a name="4"><b class="cmd">::math::decimal::add</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">::math::decimal::+</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the sum of the two decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="6"><b class="cmd">::math::decimal::subtract</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="7"><b class="cmd">::math::decimal::-</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the differnece of the two decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="8"><b class="cmd">::math::decimal::multiply</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="9"><b class="cmd">::math::decimal::*</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the product of the two decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="10"><b class="cmd">::math::decimal::divide</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="11"><b class="cmd">::math::decimal::/</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the quotient of the division between the two
decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="12"><b class="cmd">::math::decimal::divideint</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return a the integer portion of the quotient of the division between
decimals <em>a</em> and <em>b</em></p></dd>
<dt><a name="13"><b class="cmd">::math::decimal::remainder</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the remainder of the division between the two
decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="14"><b class="cmd">::math::decimal::abs</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return the absolute value of the decimal.</p></dd>
<dt><a name="15"><b class="cmd">::math::decimal::compare</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b, returning <em>0</em> if <em>a == b</em>,
<em>1</em> if <em>a > b</em>, and <em>-1</em> if <em>a < b</em>.</p></dd>
<dt><a name="16"><b class="cmd">::math::decimal::max</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b, and return <em>a</em> if <em>a >= b</em>, and <em>b</em> if <em>a < b</em>.</p></dd>
<dt><a name="17"><b class="cmd">::math::decimal::maxmag</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b while ignoring their signs, and return <em>a</em> if <em>abs(a) >= abs(b)</em>, and <em>b</em> if <em>abs(a) < abs(b)</em>.</p></dd>
<dt><a name="18"><b class="cmd">::math::decimal::min</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b, and return <em>a</em> if <em>a <= b</em>, and <em>b</em> if <em>a > b</em>.</p></dd>
<dt><a name="19"><b class="cmd">::math::decimal::minmag</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b while ignoring their signs, and return <em>a</em> if <em>abs(a) <= abs(b)</em>, and <em>b</em> if <em>abs(a) > abs(b)</em>.</p></dd>
<dt><a name="20"><b class="cmd">::math::decimal::plus</b> <i class="arg">a</i></a></dt>
<dd><p>Return the result from <em>::math::decimal::+ 0 $a</em>.</p></dd>
<dt><a name="21"><b class="cmd">::math::decimal::minus</b> <i class="arg">a</i></a></dt>
<dd><p>Return the result from <em>::math::decimal::- 0 $a</em>.</p></dd>
<dt><a name="22"><b class="cmd">::math::decimal::copynegate</b> <i class="arg">a</i></a></dt>
<dd><p>Returns <em>a</em> with the sign flipped.</p></dd>
<dt><a name="23"><b class="cmd">::math::decimal::copysign</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Returns <em>a</em> with the sign set to the sign of the <em>b</em>.</p></dd>
<dt><a name="24"><b class="cmd">::math::decimal::is-signed</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return the sign of the decimal.
The procedure returns 0 if the number is positive, 1 if it's negative.</p></dd>
<dt><a name="25"><b class="cmd">::math::decimal::is-zero</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is zero, otherwise false is returned.</p></dd>
<dt><a name="26"><b class="cmd">::math::decimal::is-NaN</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is NaN (not a number), otherwise false is returned.</p></dd>
<dt><a name="27"><b class="cmd">::math::decimal::is-infinite</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is Infinite, otherwise false is returned.</p></dd>
<dt><a name="28"><b class="cmd">::math::decimal::is-finite</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is finite, otherwise false is returned.</p></dd>
<dt><a name="29"><b class="cmd">::math::decimal::fma</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">c</i></a></dt>
<dd><p>Return the result from first multiplying <em>a</em> by <em>b</em> and then adding <em>c</em>. Rescaling only occurs after completion of all operations. In this way the result may vary from that returned by performing the operations individually.</p></dd>
<dt><a name="30"><b class="cmd">::math::decimal::round_half_even</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round to the nearest. If equidistant, round so the final digit is even.</p></dd>
<dt><a name="31"><b class="cmd">::math::decimal::round_half_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round to the nearest. If equidistant, round up.</p></dd>
<dt><a name="32"><b class="cmd">::math::decimal::round_half_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round to the nearest. If equidistant, round down.</p></dd>
<dt><a name="33"><b class="cmd">::math::decimal::round_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round toward 0. (Truncate)</p></dd>
<dt><a name="34"><b class="cmd">::math::decimal::round_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round away from 0</p></dd>
<dt><a name="35"><b class="cmd">::math::decimal::round_floor</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round toward -Infinity.</p></dd>
<dt><a name="36"><b class="cmd">::math::decimal::round_ceiling</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round toward Infinity</p></dd>
<dt><a name="37"><b class="cmd">::math::decimal::round_05up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow
the result is the same as for round-down.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>decimal</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#decimal">decimal</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#tcl">tcl</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Mark Alston <mark at beernut dot com></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/exact.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
<div class='fossil-doc' data-title='math::exact - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::exact(n) 1.0.1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::exact - Exact Real Arithmetic</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Procedures</a></li>
<li class="doctools_section"><a href="#section3">Parameters</a></li>
<li class="doctools_section"><a href="#section4">Expressions</a></li>
<li class="doctools_section"><a href="#section5">Functions</a></li>
<li class="doctools_section"><a href="#section6">Summary</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">grammar::aycock 1.0</b></li>
<li>package require <b class="pkgname">math::exact 1.0.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::exact::exactexpr</b> <i class="arg">expr</i></a></li>
<li><a href="#2"><i class="arg">number</i> <b class="cmd">ref</b></a></li>
<li><a href="#3"><i class="arg">number</i> <b class="cmd">unref</b></a></li>
<li><a href="#4"><i class="arg">number</i> <b class="cmd">asPrint</b> <i class="arg">precision</i></a></li>
<li><a href="#5"><i class="arg">number</i> <b class="cmd">asFloat</b> <i class="arg">precision</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">exactexpr</b> command in the <b class="cmd">math::exact</b> package
allows for exact computations over the computable real numbers.
These are not arbitrary-precision calculations; rather they are
exact, with numbers represented by algorithms that produce successive
approximations. At the end of a calculation, the caller can
request a given precision for the end result, and intermediate results are
computed to whatever precision is necessary to satisfy the request.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Procedures</a></h2>
<p>The following procedure is the primary entry into the <b class="cmd">math::exact</b>
package.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::exact::exactexpr</b> <i class="arg">expr</i></a></dt>
<dd><p>Accepts a mathematical expression in Tcl syntax, and returns an object
that represents the program to calculate successive approximations to
the expression's value. The result will be referred to as an
exact real number.</p></dd>
<dt><a name="2"><i class="arg">number</i> <b class="cmd">ref</b></a></dt>
<dd><p>Increases the reference count of a given exact real number.</p></dd>
<dt><a name="3"><i class="arg">number</i> <b class="cmd">unref</b></a></dt>
<dd><p>Decreases the reference count of a given exact real number, and destroys
the number if the reference count is zero.</p></dd>
<dt><a name="4"><i class="arg">number</i> <b class="cmd">asPrint</b> <i class="arg">precision</i></a></dt>
<dd><p>Formats the given <i class="arg">number</i> for printing, with the specified <i class="arg">precision</i>.
(See below for how <i class="arg">precision</i> is interpreted). Numbers that are known to
be rational are formatted as fractions.</p></dd>
<dt><a name="5"><i class="arg">number</i> <b class="cmd">asFloat</b> <i class="arg">precision</i></a></dt>
<dd><p>Formats the given <i class="arg">number</i> for printing, with the specified <i class="arg">precision</i>.
(See below for how <i class="arg">precision</i> is interpreted). All numbers are formatted
in floating-point E format.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Parameters</a></h2>
<dl class="doctools_definitions">
<dt><i class="arg">expr</i></dt>
<dd><p>Expression to evaluate. The syntax for expressions is the same as it is in Tcl,
but the set of operations is smaller. See <span class="sectref"><a href="#section4">Expressions</a></span> below
for details.</p></dd>
<dt><i class="arg">number</i></dt>
<dd><p>The object returned by an earlier invocation of <b class="cmd">math::exact::exactexpr</b></p></dd>
<dt><i class="arg">precision</i></dt>
<dd><p>The requested 'precision' of the result. The precision is (approximately)
the absolute value of the binary exponent plus the number of bits of the
binary significand. For instance, to return results to IEEE-754 double
precision, 56 bits plus the exponent are required. Numbers between 1/2 and 2
will require a precision of 57; numbers between 1/4 and 1/2 or between 2 and 4
will require 58; numbers between 1/8 and 1/4 or between 4 and 8 will require
59; and so on.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Expressions</a></h2>
<p>The <b class="cmd">math::exact::exactexpr</b> command accepts expressions in a subset
of Tcl's syntax. The following components may be used in an expression.</p>
<ul class="doctools_itemized">
<li><p>Decimal integers.</p></li>
<li><p>Variable references with the dollar sign (<b class="const">$</b>).
The value of the variable must be the result of another call to
<b class="cmd">math::exact::exactexpr</b>. The reference count of the value
will be increased by one for each position at which it appears
in the expression.</p></li>
<li><p>The exponentiation operator (<b class="const">**</b>).</p></li>
<li><p>Unary plus (<b class="const">+</b>) and minus (<b class="const">-</b>) operators.</p></li>
<li><p>Multiplication (<b class="const">*</b>) and division (<b class="const">/</b>) operators.</p></li>
<li><p>Parentheses used for grouping.</p></li>
<li><p>Functions. See <span class="sectref"><a href="#section5">Functions</a></span> below for the functions that are
available.</p></li>
</ul>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Functions</a></h2>
<p>The following functions are available for use within exact real expressions.</p>
<dl class="doctools_definitions">
<dt><b class="const">acos(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The inverse cosine of <i class="arg">x</i>. The result is expressed in radians.
The absolute value of <i class="arg">x</i> must be less than 1.</p></dd>
<dt><b class="const">acosh(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The inverse hyperbolic cosine of <i class="arg">x</i>.
<i class="arg">x</i> must be greater than 1.</p></dd>
<dt><b class="const">asin(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The inverse sine of <i class="arg">x</i>. The result is expressed in radians.
The absolute value of <i class="arg">x</i> must be less than 1.</p></dd>
<dt><b class="const">asinh(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The inverse hyperbolic sine of <i class="arg">x</i>.</p></dd>
<dt><b class="const">atan(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The inverse tangent of <i class="arg">x</i>. The result is expressed in radians.</p></dd>
<dt><b class="const">atanh(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The inverse hyperbolic tangent of <i class="arg">x</i>.
The absolute value of <i class="arg">x</i> must be less than 1.</p></dd>
<dt><b class="const">cos(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The cosine of <i class="arg">x</i>. <i class="arg">x</i> is expressed in radians.</p></dd>
<dt><b class="const">cosh(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The hyperbolic cosine of <i class="arg">x</i>.</p></dd>
<dt><b class="const">e()</b></dt>
<dd><p>The base of the natural logarithms = <b class="const">2.71828...</b></p></dd>
<dt><b class="const">exp(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The exponential function of <i class="arg">x</i>.</p></dd>
<dt><b class="const">log(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The natural logarithm of <i class="arg">x</i>. <i class="arg">x</i> must be positive.</p></dd>
<dt><b class="const">pi()</b></dt>
<dd><p>The value of pi = <b class="const">3.15159...</b></p></dd>
<dt><b class="const">sin(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The sine of <i class="arg">x</i>. <i class="arg">x</i> is expressed in radians.</p></dd>
<dt><b class="const">sinh(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The hyperbolic sine of <i class="arg">x</i>.</p></dd>
<dt><b class="const">sqrt(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The square root of <i class="arg">x</i>. <i class="arg">x</i> must be positive.</p></dd>
<dt><b class="const">tan(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The tangent of <i class="arg">x</i>. <i class="arg">x</i> is expressed in radians.</p></dd>
<dt><b class="const">tanh(</b><i class="arg">x</i><b class="const">)</b></dt>
<dd><p>The hyperbolic tangent of <i class="arg">x</i>.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Summary</a></h2>
<p>The <b class="cmd">math::exact::exactexpr</b> command provides a system that
performs exact arithmetic over computable real numbers, representing
the numbers as algorithms for successive approximation.
An example, which implements the high-school quadratic formula,
is shown below.</p>
<pre class="doctools_example">
namespace import math::exact::exactexpr
proc exactquad {a b c} {
set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref]
set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref]
set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref]
$d unref
return [list $r0 $r1]
}
set a [[exactexpr 1] ref]
set b [[exactexpr 200] ref]
set c [[exactexpr {(-3/2) * 10**-12}] ref]
lassign [exactquad $a $b $c] r0 r1
$a unref; $b unref; $c unref
puts [list [$r0 asFloat 70] [$r1 asFloat 110]]
$r0 unref; $r1 unref
</pre>
<p>The program prints the result:</p>
<pre class="doctools_example">
-2.000000000000000075e2 7.499999999999999719e-15
</pre>
<p>Note that if IEEE-754 floating point had been used, a catastrophic
roundoff error would yield a smaller root that is a factor of two
too high:</p>
<pre class="doctools_example">
-200.0 1.4210854715202004e-14
</pre>
<p>The invocations of <b class="cmd">exactexpr</b> should be fairly self-explanatory.
The other commands of note are <b class="cmd">ref</b> and <b class="cmd">unref</b>. It is necessary
for the caller to keep track of references to exact expressions - to call
<b class="cmd">ref</b> every time an exact expression is stored in a variable and
<b class="cmd">unref</b> every time the variable goes out of scope or is overwritten.
The <b class="cmd">asFloat</b> method emits decimal digits as long as the requested
precision supports them. It terminates when the requested precision
yields an uncertainty of more than one unit in the least significant digit.</p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015 Kevin B. Kenny <[email protected]><br>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/fourier.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
<div class='fossil-doc' data-title='math::fourier - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::fourier(n) 1.0.2 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::fourier - Discrete and fast fourier transforms</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">GENERAL INFORMATION</a></li>
<li class="doctools_section"><a href="#section3">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">math::fourier 1.0.2</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::fourier::dft</b> <i class="arg">in_data</i></a></li>
<li><a href="#2"><b class="cmd">::math::fourier::inverse_dft</b> <i class="arg">in_data</i></a></li>
<li><a href="#3"><b class="cmd">::math::fourier::lowpass</b> <i class="arg">cutoff</i> <i class="arg">in_data</i></a></li>
<li><a href="#4"><b class="cmd">::math::fourier::highpass</b> <i class="arg">cutoff</i> <i class="arg">in_data</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">math::fourier</b> package implements two versions of discrete
Fourier transforms, the ordinary transform and the fast Fourier
transform. It also provides a few simple filter procedures as an
illustrations of how such filters can be implemented.</p>
<p>The purpose of this document is to describe the implemented procedures
and provide some examples of their usage. As there is ample literature
on the algorithms involved, we refer to relevant text books for more
explanations. We also refer to the original Wiki page on the subject
which describes some of the considerations behind the current
implementation.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">GENERAL INFORMATION</a></h2>
<p>The two top-level procedures defined are</p>
<ul class="doctools_itemized">
<li><p>dft data-list</p></li>
<li><p>inverse_dft data-list</p></li>
</ul>
<p>Both take a list of <em>complex numbers</em> and apply a Discrete Fourier
Transform (DFT) or its inverse respectively to these lists of numbers.
A "complex number" in this case is either (i) a pair (two element list) of
numbers, interpreted as the real and imaginary parts of the complex number,
or (ii) a single number, interpreted as the real part of a complex number
whose imaginary part is zero. The return value is always in the
first format. (The DFT generally produces complex results even if the
input is purely real.) Applying first one and then the other of these
procedures to a list of complex numbers will (modulo rounding errors
due to floating point arithmetic) return the original list of numbers.</p>
<p>If the input length N is a power of two then these procedures will
utilize the O(N log N) Fast Fourier Transform algorithm. If input
length is not a power of two then the DFT will instead be computed
using a the naive quadratic algorithm.</p>
<p>Some examples:</p>
<pre class="doctools_example">
% dft {1 2 3 4}
{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}
% inverse_dft {{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}}
{1.0 0.0} {2.0 0.0} {3.0 0.0} {4.0 0.0}
% dft {1 2 3 4 5}
{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}
% inverse_dft {{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}}
{1.0 0.0} {2.0 8.881784197e-17} {3.0 4.4408920985e-17} {4.0 4.4408920985e-17} {5.0 -8.881784197e-17}
</pre>
<p>In the last case, the imaginary parts <1e-16 would have been zero in exact
arithmetic, but aren't here due to rounding errors.</p>
<p>Internally, the procedures use a flat list format where every even
index element of a list is a real part and every odd index element
is an imaginary part. This is reflected in the variable names by Re_
and Im_ prefixes.</p>
<p>The package includes two simple filters. They have an analogue
equivalent in a simple electronic circuit, a resistor and a capacitance
in series. Using these filters requires the
<b class="package"><a href="qcomplex.html">math::complexnumbers</a></b> package.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROCEDURES</a></h2>
<p>The public Fourier transform procedures are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::fourier::dft</b> <i class="arg">in_data</i></a></dt>
<dd><p>Determine the <em>Fourier transform</em> of the given list of complex
numbers. The result is a list of complex numbers representing the
(complex) amplitudes of the Fourier components.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">in_data</i></dt>
<dd><p>List of data</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::fourier::inverse_dft</b> <i class="arg">in_data</i></a></dt>
<dd><p>Determine the <em>inverse Fourier transform</em> of the given list of
complex numbers (interpreted as amplitudes). The result is a list of
complex numbers representing the original (complex) data</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">in_data</i></dt>
<dd><p>List of data (amplitudes)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::fourier::lowpass</b> <i class="arg">cutoff</i> <i class="arg">in_data</i></a></dt>
<dd><p>Filter the (complex) amplitudes so that high-frequency components
are suppressed. The implemented filter is a first-order low-pass filter,
the discrete equivalent of a simple electronic circuit with a resistor
and a capacitance.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">cutoff</i></dt>
<dd><p>Cut-off frequency</p></dd>
<dt>list <i class="arg">in_data</i></dt>
<dd><p>List of data (amplitudes)</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::fourier::highpass</b> <i class="arg">cutoff</i> <i class="arg">in_data</i></a></dt>
<dd><p>Filter the (complex) amplitudes so that low-frequency components
are suppressed. The implemented filter is a first-order low-pass filter,
the discrete equivalent of a simple electronic circuit with a resistor
and a capacitance.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">cutoff</i></dt>
<dd><p>Cut-off frequency</p></dd>
<dt>list <i class="arg">in_data</i></dt>
<dd><p>List of data (amplitudes)</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: fourier</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fft">FFT</a>, <a href="../../../../index.html#fourier_transform">Fourier transform</a>, <a href="../../../../index.html#complex_numbers">complex numbers</a>, <a href="../../../../index.html#mathematics">mathematics</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/fuzzy.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
<div class='fossil-doc' data-title='math::fuzzy - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::fuzzy(n) 0.2 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::fuzzy - Fuzzy comparison of floating-point numbers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">TEST CASES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.3?</span></b></li>
<li>package require <b class="pkgname">math::fuzzy <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::fuzzy::teq</b> <i class="arg">value1</i> <i class="arg">value2</i></a></li>
<li><a href="#2"><b class="cmd">::math::fuzzy::tne</b> <i class="arg">value1</i> <i class="arg">value2</i></a></li>
<li><a href="#3"><b class="cmd">::math::fuzzy::tge</b> <i class="arg">value1</i> <i class="arg">value2</i></a></li>
<li><a href="#4"><b class="cmd">::math::fuzzy::tle</b> <i class="arg">value1</i> <i class="arg">value2</i></a></li>
<li><a href="#5"><b class="cmd">::math::fuzzy::tlt</b> <i class="arg">value1</i> <i class="arg">value2</i></a></li>
<li><a href="#6"><b class="cmd">::math::fuzzy::tgt</b> <i class="arg">value1</i> <i class="arg">value2</i></a></li>
<li><a href="#7"><b class="cmd">::math::fuzzy::tfloor</b> <i class="arg">value</i></a></li>
<li><a href="#8"><b class="cmd">::math::fuzzy::tceil</b> <i class="arg">value</i></a></li>
<li><a href="#9"><b class="cmd">::math::fuzzy::tround</b> <i class="arg">value</i></a></li>
<li><a href="#10"><b class="cmd">::math::fuzzy::troundn</b> <i class="arg">value</i> <i class="arg">ndigits</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package Fuzzy is meant to solve common problems with floating-point
numbers in a systematic way:</p>
<ul class="doctools_itemized">
<li><p>Comparing two numbers that are "supposed" to be identical, like
1.0 and 2.1/(1.2+0.9) is not guaranteed to give the
intuitive result.</p></li>
<li><p>Rounding a number that is halfway two integer numbers can cause
strange errors, like int(100.0*2.8) != 28 but 27</p></li>
</ul>
<p>The Fuzzy package is meant to help sorting out this type of problems
by defining "fuzzy" comparison procedures for floating-point numbers.
It does so by allowing for a small margin that is determined
automatically - the margin is three times the "epsilon" value, that is
three times the smallest number <em>eps</em> such that 1.0 and 1.0+$eps
canbe distinguished. In Tcl, which uses double precision floating-point
numbers, this is typically 1.1e-16.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>Effectively the package provides the following procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::fuzzy::teq</b> <i class="arg">value1</i> <i class="arg">value2</i></a></dt>
<dd><p>Compares two floating-point numbers and returns 1 if their values
fall within a small range. Otherwise it returns 0.</p></dd>
<dt><a name="2"><b class="cmd">::math::fuzzy::tne</b> <i class="arg">value1</i> <i class="arg">value2</i></a></dt>
<dd><p>Returns the negation, that is, if the difference is larger than
the margin, it returns 1.</p></dd>
<dt><a name="3"><b class="cmd">::math::fuzzy::tge</b> <i class="arg">value1</i> <i class="arg">value2</i></a></dt>
<dd><p>Compares two floating-point numbers and returns 1 if their values
either fall within a small range or if the first number is larger
than the second. Otherwise it returns 0.</p></dd>
<dt><a name="4"><b class="cmd">::math::fuzzy::tle</b> <i class="arg">value1</i> <i class="arg">value2</i></a></dt>
<dd><p>Returns 1 if the two numbers are equal according to
[teq] or if the first is smaller than the second.</p></dd>
<dt><a name="5"><b class="cmd">::math::fuzzy::tlt</b> <i class="arg">value1</i> <i class="arg">value2</i></a></dt>
<dd><p>Returns the opposite of [tge].</p></dd>
<dt><a name="6"><b class="cmd">::math::fuzzy::tgt</b> <i class="arg">value1</i> <i class="arg">value2</i></a></dt>
<dd><p>Returns the opposite of [tle].</p></dd>
<dt><a name="7"><b class="cmd">::math::fuzzy::tfloor</b> <i class="arg">value</i></a></dt>
<dd><p>Returns the integer number that is lower or equal
to the given floating-point number, within a well-defined
tolerance.</p></dd>
<dt><a name="8"><b class="cmd">::math::fuzzy::tceil</b> <i class="arg">value</i></a></dt>
<dd><p>Returns the integer number that is greater or equal to the given
floating-point number, within a well-defined tolerance.</p></dd>
<dt><a name="9"><b class="cmd">::math::fuzzy::tround</b> <i class="arg">value</i></a></dt>
<dd><p>Rounds the floating-point number off.</p></dd>
<dt><a name="10"><b class="cmd">::math::fuzzy::troundn</b> <i class="arg">value</i> <i class="arg">ndigits</i></a></dt>
<dd><p>Rounds the floating-point number off to the
specified number of decimals (Pro memorie).</p></dd>
</dl>
<p>Usage:</p>
<pre class="doctools_example">
if { [teq $x $y] } { puts "x == y" }
if { [tne $x $y] } { puts "x != y" }
if { [tge $x $y] } { puts "x >= y" }
if { [tgt $x $y] } { puts "x > y" }
if { [tlt $x $y] } { puts "x < y" }
if { [tle $x $y] } { puts "x <= y" }
set fx [tfloor $x]
set fc [tceil $x]
set rounded [tround $x]
set roundn [troundn $x $nodigits]
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TEST CASES</a></h2>
<p>The problems that can occur with floating-point numbers are illustrated
by the test cases in the file "fuzzy.test":</p>
<ul class="doctools_itemized">
<li><p>Several test case use the ordinary comparisons, and they
fail invariably to produce understandable results</p></li>
<li><p>One test case uses [expr] without braces ({ and }). It too
fails.</p></li>
</ul>
<p>The conclusion from this is that any expression should be surrounded by
braces, because otherwise very awkward things can happen if you need
accuracy. Furthermore, accuracy and understandable results are
enhanced by using these "tolerant" or fuzzy comparisons.</p>
<p>Note that besides the Tcl-only package, there is also a C-based version.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<p>Original implementation in Fortran by dr. H.D. Knoble (Penn State
University).</p>
<p>P. E. Hagerty, "More on Fuzzy Floor and Ceiling,"
APL QUOTE QUAD 8(4):20-24, June 1978. Note that TFLOOR=FL5 took five
years of refereed evolution (publication).</p>
<p>L. M. Breed, "Definitions for Fuzzy Floor and Ceiling",
APL QUOTE QUAD 8(3):16-23, March 1978.</p>
<p>D. Knuth, Art of Computer Programming,
Vol. 1, Problem 1.2.4-5.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: fuzzy</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#floating_point">floating-point</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#rounding">rounding</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/interpolate.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
|
<div class='fossil-doc' data-title='math::interpolate - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::interpolate(n) 1.1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::interpolate - Interpolation routines</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">INCOMPATIBILITY WITH VERSION 1.0.3</a></li>
<li class="doctools_section"><a href="#section3">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">struct</b></li>
<li>package require <b class="pkgname">math::interpolate <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::interpolate::defineTable</b> <i class="arg">name</i> <i class="arg">colnames</i> <i class="arg">values</i></a></li>
<li><a href="#2"><b class="cmd">::math::interpolate::interp-1d-table</b> <i class="arg">name</i> <i class="arg">xval</i></a></li>
<li><a href="#3"><b class="cmd">::math::interpolate::interp-table</b> <i class="arg">name</i> <i class="arg">xval</i> <i class="arg">yval</i></a></li>
<li><a href="#4"><b class="cmd">::math::interpolate::interp-linear</b> <i class="arg">xyvalues</i> <i class="arg">xval</i></a></li>
<li><a href="#5"><b class="cmd">::math::interpolate::interp-lagrange</b> <i class="arg">xyvalues</i> <i class="arg">xval</i></a></li>
<li><a href="#6"><b class="cmd">::math::interpolate::prepare-cubic-splines</b> <i class="arg">xcoord</i> <i class="arg">ycoord</i></a></li>
<li><a href="#7"><b class="cmd">::math::interpolate::interp-cubic-splines</b> <i class="arg">coeffs</i> <i class="arg">x</i></a></li>
<li><a href="#8"><b class="cmd">::math::interpolate::interp-spatial</b> <i class="arg">xyvalues</i> <i class="arg">coord</i></a></li>
<li><a href="#9"><b class="cmd">::math::interpolate::interp-spatial-params</b> <i class="arg">max_search</i> <i class="arg">power</i></a></li>
<li><a href="#10"><b class="cmd">::math::interpolate::neville</b> <i class="arg">xlist</i> <i class="arg">ylist</i> <i class="arg">x</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements several interpolation algorithms:</p>
<ul class="doctools_itemized">
<li><p>Interpolation into a table (one or two independent variables), this is useful
for example, if the data are static, like with tables of statistical functions.</p></li>
<li><p>Linear interpolation into a given set of data (organised as (x,y) pairs).</p></li>
<li><p>Lagrange interpolation. This is mainly of theoretical interest, because there is
no guarantee about error bounds. One possible use: if you need a line or
a parabola through given points (it will calculate the values, but not return
the coefficients).</p>
<p>A variation is Neville's method which has better behaviour and error
bounds.</p></li>
<li><p>Spatial interpolation using a straightforward distance-weight method. This procedure
allows any number of spatial dimensions and any number of dependent variables.</p></li>
<li><p>Interpolation in one dimension using cubic splines.</p></li>
</ul>
<p>This document describes the procedures and explains their usage.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">INCOMPATIBILITY WITH VERSION 1.0.3</a></h2>
<p>The interpretation of the tables in the <b class="cmd">::math::interpolate::interpolate-1d-table</b> command
has been changed to be compatible with the interpretation for 2D interpolation in
the <b class="cmd">::math::interpolate::interpolate-table</b> command. As a consequence this version is
incompatible with the previous versions of the command (1.0.x).</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROCEDURES</a></h2>
<p>The interpolation package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::interpolate::defineTable</b> <i class="arg">name</i> <i class="arg">colnames</i> <i class="arg">values</i></a></dt>
<dd><p>Define a table with one or two independent variables (the distinction is implicit in
the data). The procedure returns the name of the table - this name is used whenever you
want to interpolate the values. <em>Note:</em> this procedure is a convenient wrapper for the
struct::matrix procedure. Therefore you can access the data at any location in your program.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">name</i> (in)</dt>
<dd><p>Name of the table to be created</p></dd>
<dt>list <i class="arg">colnames</i> (in)</dt>
<dd><p>List of column names</p></dd>
<dt>list <i class="arg">values</i> (in)</dt>
<dd><p>List of values (the number of elements should be a
multiple of the number of columns. See <span class="sectref"><a href="#section4">EXAMPLES</a></span> for more information on the
interpretation of the data.</p>
<p>The values must be sorted with respect to the independent variable(s).</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::interpolate::interp-1d-table</b> <i class="arg">name</i> <i class="arg">xval</i></a></dt>
<dd><p>Interpolate into the one-dimensional table "name" and return a list of values, one for
each dependent column.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">name</i> (in)</dt>
<dd><p>Name of an existing table</p></dd>
<dt>float <i class="arg">xval</i> (in)</dt>
<dd><p>Value of the independent <em>row</em> variable</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::interpolate::interp-table</b> <i class="arg">name</i> <i class="arg">xval</i> <i class="arg">yval</i></a></dt>
<dd><p>Interpolate into the two-dimensional table "name" and return the interpolated value.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">name</i> (in)</dt>
<dd><p>Name of an existing table</p></dd>
<dt>float <i class="arg">xval</i> (in)</dt>
<dd><p>Value of the independent <em>row</em> variable</p></dd>
<dt>float <i class="arg">yval</i> (in)</dt>
<dd><p>Value of the independent <em>column</em> variable</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::interpolate::interp-linear</b> <i class="arg">xyvalues</i> <i class="arg">xval</i></a></dt>
<dd><p>Interpolate linearly into the list of x,y pairs and return the interpolated value.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xyvalues</i> (in)</dt>
<dd><p>List of pairs of (x,y) values, sorted to increasing x.
They are used as the breakpoints of a piecewise linear function.</p></dd>
<dt>float <i class="arg">xval</i> (in)</dt>
<dd><p>Value of the independent variable for which the value of y
must be computed.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::interpolate::interp-lagrange</b> <i class="arg">xyvalues</i> <i class="arg">xval</i></a></dt>
<dd><p>Use the list of x,y pairs to construct the unique polynomial of lowest degree
that passes through all points and return the interpolated value.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xyvalues</i> (in)</dt>
<dd><p>List of pairs of (x,y) values</p></dd>
<dt>float <i class="arg">xval</i> (in)</dt>
<dd><p>Value of the independent variable for which the value of y
must be computed.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::math::interpolate::prepare-cubic-splines</b> <i class="arg">xcoord</i> <i class="arg">ycoord</i></a></dt>
<dd><p>Returns a list of coefficients for the second routine
<em>interp-cubic-splines</em> to actually interpolate.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xcoord</i></dt>
<dd><p>List of x-coordinates for the value of the
function to be interpolated is known. The coordinates must be strictly
ascending. At least three points are required.</p></dd>
<dt>list <i class="arg">ycoord</i></dt>
<dd><p>List of y-coordinates (the values of the
function at the given x-coordinates).</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::interpolate::interp-cubic-splines</b> <i class="arg">coeffs</i> <i class="arg">x</i></a></dt>
<dd><p>Returns the interpolated value at coordinate x. The coefficients are
computed by the procedure <em>prepare-cubic-splines</em>.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">coeffs</i></dt>
<dd><p>List of coefficients as returned by
prepare-cubic-splines</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>x-coordinate at which to estimate the function. Must
be between the first and last x-coordinate for which values were given.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::interpolate::interp-spatial</b> <i class="arg">xyvalues</i> <i class="arg">coord</i></a></dt>
<dd><p>Use a straightforward interpolation method with weights as function of the
inverse distance to interpolate in 2D and N-dimensional space</p>
<p>The list xyvalues is a list of lists:</p>
<pre class="doctools_example">
{ {x1 y1 z1 {v11 v12 v13 v14}}
{x2 y2 z2 {v21 v22 v23 v24}}
...
}
</pre>
<p>The last element of each inner list is either a single number or a list in itself.
In the latter case the return value is a list with the same number of elements.</p>
<p>The method is influenced by the search radius and the power of the inverse distance</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xyvalues</i> (in)</dt>
<dd><p>List of lists, each sublist being a list of coordinates and
of dependent values.</p></dd>
<dt>list <i class="arg">coord</i> (in)</dt>
<dd><p>List of coordinates for which the values must be calculated</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::interpolate::interp-spatial-params</b> <i class="arg">max_search</i> <i class="arg">power</i></a></dt>
<dd><p>Set the parameters for spatial interpolation</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">max_search</i> (in)</dt>
<dd><p>Search radius (data points further than this are ignored)</p></dd>
<dt>integer <i class="arg">power</i> (in)</dt>
<dd><p>Power for the distance (either 1 or 2; defaults to 2)</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::interpolate::neville</b> <i class="arg">xlist</i> <i class="arg">ylist</i> <i class="arg">x</i></a></dt>
<dd><p>Interpolates between the tabulated values of a function
whose abscissae are <i class="arg">xlist</i>
and whose ordinates are <i class="arg">ylist</i> to produce an estimate for the value
of the function at <i class="arg">x</i>. The result is a two-element list; the first
element is the function's estimated value, and the second is an estimate
of the absolute error of the result. Neville's algorithm for polynomial
interpolation is used. Note that a large table of values will use an
interpolating polynomial of high degree, which is likely to result in
numerical instabilities; one is better off using only a few tabulated
values near the desired abscissa.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<p><em>Example of using one-dimensional tables:</em></p>
<p>Suppose you have several tabulated functions of one variable:</p>
<pre class="doctools_example">
x y1 y2
0.0 0.0 0.0
1.0 1.0 1.0
2.0 4.0 8.0
3.0 9.0 27.0
4.0 16.0 64.0
</pre>
<p>Then to estimate the values at 0.5, 1.5, 2.5 and 3.5, you can use:</p>
<pre class="doctools_example">
set table [::math::interpolate::defineTable table1 {x y1 y2} { - 1 2
0.0 0.0 0.0
1.0 1.0 1.0
2.0 4.0 8.0
3.0 9.0 27.0
4.0 16.0 64.0}]
foreach x {0.5 1.5 2.5 3.5} {
puts "$x: [::math::interpolate::interp-1d-table $table $x]"
}
</pre>
<p>For one-dimensional tables the first row is not used. For two-dimensional
tables, the first row represents the values for the second independent variable.</p>
<p><em>Example of using the cubic splines:</em></p>
<p>Suppose the following values are given:</p>
<pre class="doctools_example">
x y
0.1 1.0
0.3 2.1
0.4 2.2
0.8 4.11
1.0 4.12
</pre>
<p>Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use:</p>
<pre class="doctools_example">
set coeffs [::math::interpolate::prepare-cubic-splines {0.1 0.3 0.4 0.8 1.0} {1.0 2.1 2.2 4.11 4.12}]
foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} {
puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]"
}
</pre>
<p>to get the following output:</p>
<pre class="doctools_example">
0.1: 1.0
0.2: 1.68044117647
0.3: 2.1
0.4: 2.2
0.5: 3.11221507353
0.6: 4.25242647059
0.7: 5.41804227941
0.8: 4.11
0.9: 3.95675857843
1.0: 4.12
</pre>
<p>As you can see, the values at the abscissae are reproduced perfectly.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: interpolate</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#interpolation">interpolation</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#spatial_interpolation">spatial interpolation</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]><br>
Copyright © 2004 Kevn B. Kenny <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/linalg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
|
<div class='fossil-doc' data-title='math::linearalgebra - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::linearalgebra(n) 1.1.5 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::linearalgebra - Linear Algebra</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">STORAGE</a></li>
<li class="doctools_section"><a href="#section4">REMARKS ON THE IMPLEMENTATION</a></li>
<li class="doctools_section"><a href="#section5">TODO</a></li>
<li class="doctools_section"><a href="#section6">NAMING CONFLICT</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">math::linearalgebra <span class="opt">?1.1.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::linearalgebra::mkVector</b> <i class="arg">ndim</i> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">::math::linearalgebra::mkUnitVector</b> <i class="arg">ndim</i> <i class="arg">ndir</i></a></li>
<li><a href="#3"><b class="cmd">::math::linearalgebra::mkMatrix</b> <i class="arg">nrows</i> <i class="arg">ncols</i> <i class="arg">value</i></a></li>
<li><a href="#4"><b class="cmd">::math::linearalgebra::getrow</b> <i class="arg">matrix</i> <i class="arg">row</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></li>
<li><a href="#5"><b class="cmd">::math::linearalgebra::setrow</b> <i class="arg">matrix</i> <i class="arg">row</i> <i class="arg">newvalues</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></li>
<li><a href="#6"><b class="cmd">::math::linearalgebra::getcol</b> <i class="arg">matrix</i> <i class="arg">col</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></li>
<li><a href="#7"><b class="cmd">::math::linearalgebra::setcol</b> <i class="arg">matrix</i> <i class="arg">col</i> <i class="arg">newvalues</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></li>
<li><a href="#8"><b class="cmd">::math::linearalgebra::getelem</b> <i class="arg">matrix</i> <i class="arg">row</i> <i class="arg">col</i></a></li>
<li><a href="#9"><b class="cmd">::math::linearalgebra::setelem</b> <i class="arg">matrix</i> <i class="arg">row</i> <span class="opt">?col?</span> <i class="arg">newvalue</i></a></li>
<li><a href="#10"><b class="cmd">::math::linearalgebra::swaprows</b> <i class="arg">matrix</i> <i class="arg">irow1</i> <i class="arg">irow2</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></li>
<li><a href="#11"><b class="cmd">::math::linearalgebra::swapcols</b> <i class="arg">matrix</i> <i class="arg">icol1</i> <i class="arg">icol2</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></li>
<li><a href="#12"><b class="cmd">::math::linearalgebra::show</b> <i class="arg">obj</i> <span class="opt">?format?</span> <span class="opt">?rowsep?</span> <span class="opt">?colsep?</span></a></li>
<li><a href="#13"><b class="cmd">::math::linearalgebra::dim</b> <i class="arg">obj</i></a></li>
<li><a href="#14"><b class="cmd">::math::linearalgebra::shape</b> <i class="arg">obj</i></a></li>
<li><a href="#15"><b class="cmd">::math::linearalgebra::conforming</b> <i class="arg">type</i> <i class="arg">obj1</i> <i class="arg">obj2</i></a></li>
<li><a href="#16"><b class="cmd">::math::linearalgebra::symmetric</b> <i class="arg">matrix</i> <span class="opt">?eps?</span></a></li>
<li><a href="#17"><b class="cmd">::math::linearalgebra::norm</b> <i class="arg">vector</i> <i class="arg">type</i></a></li>
<li><a href="#18"><b class="cmd">::math::linearalgebra::norm_one</b> <i class="arg">vector</i></a></li>
<li><a href="#19"><b class="cmd">::math::linearalgebra::norm_two</b> <i class="arg">vector</i></a></li>
<li><a href="#20"><b class="cmd">::math::linearalgebra::norm_max</b> <i class="arg">vector</i> <span class="opt">?index?</span></a></li>
<li><a href="#21"><b class="cmd">::math::linearalgebra::normMatrix</b> <i class="arg">matrix</i> <i class="arg">type</i></a></li>
<li><a href="#22"><b class="cmd">::math::linearalgebra::dotproduct</b> <i class="arg">vect1</i> <i class="arg">vect2</i></a></li>
<li><a href="#23"><b class="cmd">::math::linearalgebra::unitLengthVector</b> <i class="arg">vector</i></a></li>
<li><a href="#24"><b class="cmd">::math::linearalgebra::normalizeStat</b> <i class="arg">mv</i></a></li>
<li><a href="#25"><b class="cmd">::math::linearalgebra::axpy</b> <i class="arg">scale</i> <i class="arg">mv1</i> <i class="arg">mv2</i></a></li>
<li><a href="#26"><b class="cmd">::math::linearalgebra::add</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></li>
<li><a href="#27"><b class="cmd">::math::linearalgebra::sub</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></li>
<li><a href="#28"><b class="cmd">::math::linearalgebra::scale</b> <i class="arg">scale</i> <i class="arg">mv</i></a></li>
<li><a href="#29"><b class="cmd">::math::linearalgebra::rotate</b> <i class="arg">c</i> <i class="arg">s</i> <i class="arg">vect1</i> <i class="arg">vect2</i></a></li>
<li><a href="#30"><b class="cmd">::math::linearalgebra::transpose</b> <i class="arg">matrix</i></a></li>
<li><a href="#31"><b class="cmd">::math::linearalgebra::matmul</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></li>
<li><a href="#32"><b class="cmd">::math::linearalgebra::angle</b> <i class="arg">vect1</i> <i class="arg">vect2</i></a></li>
<li><a href="#33"><b class="cmd">::math::linearalgebra::crossproduct</b> <i class="arg">vect1</i> <i class="arg">vect2</i></a></li>
<li><a href="#34"><b class="cmd">::math::linearalgebra::matmul</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></li>
<li><a href="#35"><b class="cmd">::math::linearalgebra::mkIdentity</b> <i class="arg">size</i></a></li>
<li><a href="#36"><b class="cmd">::math::linearalgebra::mkDiagonal</b> <i class="arg">diag</i></a></li>
<li><a href="#37"><b class="cmd">::math::linearalgebra::mkRandom</b> <i class="arg">size</i></a></li>
<li><a href="#38"><b class="cmd">::math::linearalgebra::mkTriangular</b> <i class="arg">size</i> <span class="opt">?uplo?</span> <span class="opt">?value?</span></a></li>
<li><a href="#39"><b class="cmd">::math::linearalgebra::mkHilbert</b> <i class="arg">size</i></a></li>
<li><a href="#40"><b class="cmd">::math::linearalgebra::mkDingdong</b> <i class="arg">size</i></a></li>
<li><a href="#41"><b class="cmd">::math::linearalgebra::mkOnes</b> <i class="arg">size</i></a></li>
<li><a href="#42"><b class="cmd">::math::linearalgebra::mkMoler</b> <i class="arg">size</i></a></li>
<li><a href="#43"><b class="cmd">::math::linearalgebra::mkFrank</b> <i class="arg">size</i></a></li>
<li><a href="#44"><b class="cmd">::math::linearalgebra::mkBorder</b> <i class="arg">size</i></a></li>
<li><a href="#45"><b class="cmd">::math::linearalgebra::mkWilkinsonW+</b> <i class="arg">size</i></a></li>
<li><a href="#46"><b class="cmd">::math::linearalgebra::mkWilkinsonW-</b> <i class="arg">size</i></a></li>
<li><a href="#47"><b class="cmd">::math::linearalgebra::solveGauss</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></li>
<li><a href="#48"><b class="cmd">::math::linearalgebra::solvePGauss</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></li>
<li><a href="#49"><b class="cmd">::math::linearalgebra::solveTriangular</b> <i class="arg">matrix</i> <i class="arg">bvect</i> <span class="opt">?uplo?</span></a></li>
<li><a href="#50"><b class="cmd">::math::linearalgebra::solveGaussBand</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></li>
<li><a href="#51"><b class="cmd">::math::linearalgebra::solveTriangularBand</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></li>
<li><a href="#52"><b class="cmd">::math::linearalgebra::determineSVD</b> <i class="arg">A</i> <i class="arg">eps</i></a></li>
<li><a href="#53"><b class="cmd">::math::linearalgebra::eigenvectorsSVD</b> <i class="arg">A</i> <i class="arg">eps</i></a></li>
<li><a href="#54"><b class="cmd">::math::linearalgebra::leastSquaresSVD</b> <i class="arg">A</i> <i class="arg">y</i> <i class="arg">qmin</i> <i class="arg">eps</i></a></li>
<li><a href="#55"><b class="cmd">::math::linearalgebra::choleski</b> <i class="arg">matrix</i></a></li>
<li><a href="#56"><b class="cmd">::math::linearalgebra::orthonormalizeColumns</b> <i class="arg">matrix</i></a></li>
<li><a href="#57"><b class="cmd">::math::linearalgebra::orthonormalizeRows</b> <i class="arg">matrix</i></a></li>
<li><a href="#58"><b class="cmd">::math::linearalgebra::dger</b> <i class="arg">matrix</i> <i class="arg">alpha</i> <i class="arg">x</i> <i class="arg">y</i> <span class="opt">?scope?</span></a></li>
<li><a href="#59"><b class="cmd">::math::linearalgebra::dgetrf</b> <i class="arg">matrix</i></a></li>
<li><a href="#60"><b class="cmd">::math::linearalgebra::det</b> <i class="arg">matrix</i></a></li>
<li><a href="#61"><b class="cmd">::math::linearalgebra::largesteigen</b> <i class="arg">matrix</i> <i class="arg">tolerance</i> <i class="arg">maxiter</i></a></li>
<li><a href="#62"><b class="cmd">::math::linearalgebra::to_LA</b> <i class="arg">mv</i></a></li>
<li><a href="#63"><b class="cmd">::math::linearalgebra::from_LA</b> <i class="arg">mv</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package offers both low-level procedures and high-level algorithms
to deal with linear algebra problems:</p>
<ul class="doctools_itemized">
<li><p>robust solution of linear equations or least squares problems</p></li>
<li><p>determining eigenvectors and eigenvalues of symmetric matrices</p></li>
<li><p>various decompositions of general matrices or matrices of a specific
form</p></li>
<li><p>(limited) support for matrices in band storage, a common type of sparse
matrices</p></li>
</ul>
<p>It arose as a re-implementation of Hume's LA package and the desire to
offer low-level procedures as found in the well-known BLAS library.
Matrices are implemented as lists of lists rather linear lists with
reserved elements, as in the original LA package, as it was found that
such an implementation is actually faster.</p>
<p>It is advisable, however, to use the procedures that are offered, such
as <em>setrow</em> and <em>getrow</em>, rather than rely on this
representation explicitly: that way it is to switch to a possibly even
faster compiled implementation that supports the same API.</p>
<p><em>Note:</em> When using this package in combination with Tk, there may
be a naming conflict, as both this package and Tk define a command
<em>scale</em>. See the <span class="sectref"><a href="#section6">NAMING CONFLICT</a></span> section below.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following public procedures (several exist as
specialised procedures, see below):</p>
<p><em>Constructing matrices and vectors</em></p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::linearalgebra::mkVector</b> <i class="arg">ndim</i> <i class="arg">value</i></a></dt>
<dd><p>Create a vector with ndim elements, each with the value <em>value</em>.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">ndim</i></dt>
<dd><p>Dimension of the vector (number of components)</p></dd>
<dt>double <i class="arg">value</i></dt>
<dd><p>Uniform value to be used (default: 0.0)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::linearalgebra::mkUnitVector</b> <i class="arg">ndim</i> <i class="arg">ndir</i></a></dt>
<dd><p>Create a unit vector in <em>ndim</em>-dimensional space, along the
<em>ndir</em>-th direction.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">ndim</i></dt>
<dd><p>Dimension of the vector (number of components)</p></dd>
<dt>integer <i class="arg">ndir</i></dt>
<dd><p>Direction (0, ..., ndim-1)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::linearalgebra::mkMatrix</b> <i class="arg">nrows</i> <i class="arg">ncols</i> <i class="arg">value</i></a></dt>
<dd><p>Create a matrix with <em>nrows</em> rows and <em>ncols</em> columns. All
elements have the value <em>value</em>.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">nrows</i></dt>
<dd><p>Number of rows</p></dd>
<dt>integer <i class="arg">ncols</i></dt>
<dd><p>Number of columns</p></dd>
<dt>double <i class="arg">value</i></dt>
<dd><p>Uniform value to be used (default: 0.0)</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::linearalgebra::getrow</b> <i class="arg">matrix</i> <i class="arg">row</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></dt>
<dd><p>Returns a single row of a matrix as a list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix in question</p></dd>
<dt>integer <i class="arg">row</i></dt>
<dd><p>Index of the row to return</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Minimum index of the column (default: 0)</p></dd>
<dt>integer <i class="arg">imax</i></dt>
<dd><p>Maximum index of the column (default: ncols-1)</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::linearalgebra::setrow</b> <i class="arg">matrix</i> <i class="arg">row</i> <i class="arg">newvalues</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></dt>
<dd><p>Set a single row of a matrix to new values (this list must have the same
number of elements as the number of <em>columns</em> in the matrix)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p><em>name</em> of the matrix in question</p></dd>
<dt>integer <i class="arg">row</i></dt>
<dd><p>Index of the row to update</p></dd>
<dt>list <i class="arg">newvalues</i></dt>
<dd><p>List of new values for the row</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Minimum index of the column (default: 0)</p></dd>
<dt>integer <i class="arg">imax</i></dt>
<dd><p>Maximum index of the column (default: ncols-1)</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::math::linearalgebra::getcol</b> <i class="arg">matrix</i> <i class="arg">col</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></dt>
<dd><p>Returns a single column of a matrix as a list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix in question</p></dd>
<dt>integer <i class="arg">col</i></dt>
<dd><p>Index of the column to return</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Minimum index of the row (default: 0)</p></dd>
<dt>integer <i class="arg">imax</i></dt>
<dd><p>Maximum index of the row (default: nrows-1)</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::linearalgebra::setcol</b> <i class="arg">matrix</i> <i class="arg">col</i> <i class="arg">newvalues</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></dt>
<dd><p>Set a single column of a matrix to new values (this list must have
the same number of elements as the number of <em>rows</em> in the matrix)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p><em>name</em> of the matrix in question</p></dd>
<dt>integer <i class="arg">col</i></dt>
<dd><p>Index of the column to update</p></dd>
<dt>list <i class="arg">newvalues</i></dt>
<dd><p>List of new values for the column</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Minimum index of the row (default: 0)</p></dd>
<dt>integer <i class="arg">imax</i></dt>
<dd><p>Maximum index of the row (default: nrows-1)</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::linearalgebra::getelem</b> <i class="arg">matrix</i> <i class="arg">row</i> <i class="arg">col</i></a></dt>
<dd><p>Returns a single element of a matrix/vector</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix or vector in question</p></dd>
<dt>integer <i class="arg">row</i></dt>
<dd><p>Row of the element</p></dd>
<dt>integer <i class="arg">col</i></dt>
<dd><p>Column of the element (not present for vectors)</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::linearalgebra::setelem</b> <i class="arg">matrix</i> <i class="arg">row</i> <span class="opt">?col?</span> <i class="arg">newvalue</i></a></dt>
<dd><p>Set a single element of a matrix (or vector) to a new value</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p><em>name</em> of the matrix in question</p></dd>
<dt>integer <i class="arg">row</i></dt>
<dd><p>Row of the element</p></dd>
<dt>integer <i class="arg">col</i></dt>
<dd><p>Column of the element (not present for vectors)</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::linearalgebra::swaprows</b> <i class="arg">matrix</i> <i class="arg">irow1</i> <i class="arg">irow2</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></dt>
<dd><p>Swap two rows in a matrix completely or only a selected part</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p><em>name</em> of the matrix in question</p></dd>
<dt>integer <i class="arg">irow1</i></dt>
<dd><p>Index of first row</p></dd>
<dt>integer <i class="arg">irow2</i></dt>
<dd><p>Index of second row</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Minimum column index (default: 0)</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Maximum column index (default: ncols-1)</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::linearalgebra::swapcols</b> <i class="arg">matrix</i> <i class="arg">icol1</i> <i class="arg">icol2</i> <span class="opt">?imin?</span> <span class="opt">?imax?</span></a></dt>
<dd><p>Swap two columns in a matrix completely or only a selected part</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p><em>name</em> of the matrix in question</p></dd>
<dt>integer <i class="arg">irow1</i></dt>
<dd><p>Index of first column</p></dd>
<dt>integer <i class="arg">irow2</i></dt>
<dd><p>Index of second column</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Minimum row index (default: 0)</p></dd>
<dt>integer <i class="arg">imin</i></dt>
<dd><p>Maximum row index (default: nrows-1)</p></dd>
</dl></dd>
</dl>
<p><em>Querying matrices and vectors</em></p>
<dl class="doctools_definitions">
<dt><a name="12"><b class="cmd">::math::linearalgebra::show</b> <i class="arg">obj</i> <span class="opt">?format?</span> <span class="opt">?rowsep?</span> <span class="opt">?colsep?</span></a></dt>
<dd><p>Return a string representing the vector or matrix, for easy printing.
(There is currently no way to print fixed sets of columns)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">obj</i></dt>
<dd><p>Matrix or vector in question</p></dd>
<dt>string <i class="arg">format</i></dt>
<dd><p>Format for printing the numbers (default: %6.4f)</p></dd>
<dt>string <i class="arg">rowsep</i></dt>
<dd><p>String to use for separating rows (default: newline)</p></dd>
<dt>string <i class="arg">colsep</i></dt>
<dd><p>String to use for separating columns (default: space)</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::linearalgebra::dim</b> <i class="arg">obj</i></a></dt>
<dd><p>Returns the number of dimensions for the object (either 0 for a scalar,
1 for a vector and 2 for a matrix)</p>
<dl class="doctools_arguments">
<dt>any <i class="arg">obj</i></dt>
<dd><p>Scalar, vector, or matrix</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::math::linearalgebra::shape</b> <i class="arg">obj</i></a></dt>
<dd><p>Returns the number of elements in each dimension for the object (either
an empty list for a scalar, a single number for a vector and a list of
the number of rows and columns for a matrix)</p>
<dl class="doctools_arguments">
<dt>any <i class="arg">obj</i></dt>
<dd><p>Scalar, vector, or matrix</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::linearalgebra::conforming</b> <i class="arg">type</i> <i class="arg">obj1</i> <i class="arg">obj2</i></a></dt>
<dd><p>Checks if two objects (vector or matrix) have conforming shapes, that is
if they can be applied in an operation like addition or matrix
multiplication.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">type</i></dt>
<dd><p>Type of check:</p>
<ul class="doctools_itemized">
<li><p>"shape" - the two objects have the same shape (for all element-wise
operations)</p></li>
<li><p>"rows" - the two objects have the same number of rows (for use as A and
b in a system of linear equations <em>Ax = b</em></p></li>
<li><p>"matmul" - the first object has the same number of columns as the number
of rows of the second object. Useful for matrix-matrix or matrix-vector
multiplication.</p></li>
</ul></dd>
<dt>list <i class="arg">obj1</i></dt>
<dd><p>First vector or matrix (left operand)</p></dd>
<dt>list <i class="arg">obj2</i></dt>
<dd><p>Second vector or matrix (right operand)</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::linearalgebra::symmetric</b> <i class="arg">matrix</i> <span class="opt">?eps?</span></a></dt>
<dd><p>Checks if the given (square) matrix is symmetric. The argument eps
is the tolerance.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix to be inspected</p></dd>
<dt>float <i class="arg">eps</i></dt>
<dd><p>Tolerance for determining approximate equality
(defaults to 1.0e-8)</p></dd>
</dl></dd>
</dl>
<p><em>Basic operations</em></p>
<dl class="doctools_definitions">
<dt><a name="17"><b class="cmd">::math::linearalgebra::norm</b> <i class="arg">vector</i> <i class="arg">type</i></a></dt>
<dd><p>Returns the norm of the given vector. The type argument can be: 1,
2, inf or max, respectively the sum of absolute values, the ordinary
Euclidean norm or the max norm.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vector</i></dt>
<dd><p>Vector, list of coefficients</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>Type of norm (default: 2, the Euclidean norm)</p></dd>
</dl></dd>
<dt><a name="18"><b class="cmd">::math::linearalgebra::norm_one</b> <i class="arg">vector</i></a></dt>
<dd><p>Returns the L1 norm of the given vector, the sum of absolute values</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vector</i></dt>
<dd><p>Vector, list of coefficients</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">::math::linearalgebra::norm_two</b> <i class="arg">vector</i></a></dt>
<dd><p>Returns the L2 norm of the given vector, the ordinary Euclidean norm</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vector</i></dt>
<dd><p>Vector, list of coefficients</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">::math::linearalgebra::norm_max</b> <i class="arg">vector</i> <span class="opt">?index?</span></a></dt>
<dd><p>Returns the Linf norm of the given vector, the maximum absolute
coefficient</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vector</i></dt>
<dd><p>Vector, list of coefficients</p></dd>
<dt>integer <i class="arg">index</i></dt>
<dd><p>(optional) if non zero, returns a list made of the maximum
value and the index where that maximum was found.
if zero, returns the maximum value.</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">::math::linearalgebra::normMatrix</b> <i class="arg">matrix</i> <i class="arg">type</i></a></dt>
<dd><p>Returns the norm of the given matrix. The type argument can be: 1,
2, inf or max, respectively the sum of absolute values, the ordinary
Euclidean norm or the max norm.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix, list of row vectors</p></dd>
<dt>string <i class="arg">type</i></dt>
<dd><p>Type of norm (default: 2, the Euclidean norm)</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">::math::linearalgebra::dotproduct</b> <i class="arg">vect1</i> <i class="arg">vect2</i></a></dt>
<dd><p>Determine the inproduct or dot product of two vectors. These must have
the same shape (number of dimensions)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vect1</i></dt>
<dd><p>First vector, list of coefficients</p></dd>
<dt>list <i class="arg">vect2</i></dt>
<dd><p>Second vector, list of coefficients</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">::math::linearalgebra::unitLengthVector</b> <i class="arg">vector</i></a></dt>
<dd><p>Return a vector in the same direction with length 1.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vector</i></dt>
<dd><p>Vector to be normalized</p></dd>
</dl></dd>
<dt><a name="24"><b class="cmd">::math::linearalgebra::normalizeStat</b> <i class="arg">mv</i></a></dt>
<dd><p>Normalize the matrix or vector in a statistical sense: the mean of the
elements of the columns of the result is zero and the standard deviation
is 1.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv</i></dt>
<dd><p>Vector or matrix to be normalized in the above sense</p></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">::math::linearalgebra::axpy</b> <i class="arg">scale</i> <i class="arg">mv1</i> <i class="arg">mv2</i></a></dt>
<dd><p>Return a vector or matrix that results from a "daxpy" operation, that
is: compute a*x+y (a a scalar and x and y both vectors or matrices of
the same shape) and return the result.</p>
<p>Specialised variants are: axpy_vect and axpy_mat (slightly faster,
but no check on the arguments)</p>
<dl class="doctools_arguments">
<dt>double <i class="arg">scale</i></dt>
<dd><p>The scale factor for the first vector/matrix (a)</p></dd>
<dt>list <i class="arg">mv1</i></dt>
<dd><p>First vector or matrix (x)</p></dd>
<dt>list <i class="arg">mv2</i></dt>
<dd><p>Second vector or matrix (y)</p></dd>
</dl></dd>
<dt><a name="26"><b class="cmd">::math::linearalgebra::add</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></dt>
<dd><p>Return a vector or matrix that is the sum of the two arguments (x+y)</p>
<p>Specialised variants are: add_vect and add_mat (slightly faster,
but no check on the arguments)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv1</i></dt>
<dd><p>First vector or matrix (x)</p></dd>
<dt>list <i class="arg">mv2</i></dt>
<dd><p>Second vector or matrix (y)</p></dd>
</dl></dd>
<dt><a name="27"><b class="cmd">::math::linearalgebra::sub</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></dt>
<dd><p>Return a vector or matrix that is the difference of the two arguments
(x-y)</p>
<p>Specialised variants are: sub_vect and sub_mat (slightly faster,
but no check on the arguments)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv1</i></dt>
<dd><p>First vector or matrix (x)</p></dd>
<dt>list <i class="arg">mv2</i></dt>
<dd><p>Second vector or matrix (y)</p></dd>
</dl></dd>
<dt><a name="28"><b class="cmd">::math::linearalgebra::scale</b> <i class="arg">scale</i> <i class="arg">mv</i></a></dt>
<dd><p>Scale a vector or matrix and return the result, that is: compute a*x.</p>
<p>Specialised variants are: scale_vect and scale_mat (slightly faster,
but no check on the arguments)</p>
<dl class="doctools_arguments">
<dt>double <i class="arg">scale</i></dt>
<dd><p>The scale factor for the vector/matrix (a)</p></dd>
<dt>list <i class="arg">mv</i></dt>
<dd><p>Vector or matrix (x)</p></dd>
</dl></dd>
<dt><a name="29"><b class="cmd">::math::linearalgebra::rotate</b> <i class="arg">c</i> <i class="arg">s</i> <i class="arg">vect1</i> <i class="arg">vect2</i></a></dt>
<dd><p>Apply a planar rotation to two vectors and return the result as a list
of two vectors: c*x-s*y and s*x+c*y. In algorithms you can often easily
determine the cosine and sine of the angle, so it is more efficient to
pass that information directly.</p>
<dl class="doctools_arguments">
<dt>double <i class="arg">c</i></dt>
<dd><p>The cosine of the angle</p></dd>
<dt>double <i class="arg">s</i></dt>
<dd><p>The sine of the angle</p></dd>
<dt>list <i class="arg">vect1</i></dt>
<dd><p>First vector (x)</p></dd>
<dt>list <i class="arg">vect2</i></dt>
<dd><p>Seocnd vector (x)</p></dd>
</dl></dd>
<dt><a name="30"><b class="cmd">::math::linearalgebra::transpose</b> <i class="arg">matrix</i></a></dt>
<dd><p>Transpose a matrix</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix to be transposed</p></dd>
</dl></dd>
<dt><a name="31"><b class="cmd">::math::linearalgebra::matmul</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></dt>
<dd><p>Multiply a vector/matrix with another vector/matrix. The result is
a matrix, if both x and y are matrices or both are vectors, in
which case the "outer product" is computed. If one is a vector and the
other is a matrix, then the result is a vector.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv1</i></dt>
<dd><p>First vector/matrix (x)</p></dd>
<dt>list <i class="arg">mv2</i></dt>
<dd><p>Second vector/matrix (y)</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">::math::linearalgebra::angle</b> <i class="arg">vect1</i> <i class="arg">vect2</i></a></dt>
<dd><p>Compute the angle between two vectors (in radians)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vect1</i></dt>
<dd><p>First vector</p></dd>
<dt>list <i class="arg">vect2</i></dt>
<dd><p>Second vector</p></dd>
</dl></dd>
<dt><a name="33"><b class="cmd">::math::linearalgebra::crossproduct</b> <i class="arg">vect1</i> <i class="arg">vect2</i></a></dt>
<dd><p>Compute the cross product of two (three-dimensional) vectors</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vect1</i></dt>
<dd><p>First vector</p></dd>
<dt>list <i class="arg">vect2</i></dt>
<dd><p>Second vector</p></dd>
</dl></dd>
<dt><a name="34"><b class="cmd">::math::linearalgebra::matmul</b> <i class="arg">mv1</i> <i class="arg">mv2</i></a></dt>
<dd><p>Multiply a vector/matrix with another vector/matrix. The result is
a matrix, if both x and y are matrices or both are vectors, in
which case the "outer product" is computed. If one is a vector and the
other is a matrix, then the result is a vector.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv1</i></dt>
<dd><p>First vector/matrix (x)</p></dd>
<dt>list <i class="arg">mv2</i></dt>
<dd><p>Second vector/matrix (y)</p></dd>
</dl></dd>
</dl>
<p><em>Common matrices and test matrices</em></p>
<dl class="doctools_definitions">
<dt><a name="35"><b class="cmd">::math::linearalgebra::mkIdentity</b> <i class="arg">size</i></a></dt>
<dd><p>Create an identity matrix of dimension <em>size</em>.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="36"><b class="cmd">::math::linearalgebra::mkDiagonal</b> <i class="arg">diag</i></a></dt>
<dd><p>Create a diagonal matrix whose diagonal elements are the elements of the
vector <em>diag</em>.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">diag</i></dt>
<dd><p>Vector whose elements are used for the diagonal</p></dd>
</dl></dd>
<dt><a name="37"><b class="cmd">::math::linearalgebra::mkRandom</b> <i class="arg">size</i></a></dt>
<dd><p>Create a square matrix whose elements are uniformly distributed random
numbers between 0 and 1 of dimension <em>size</em>.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="38"><b class="cmd">::math::linearalgebra::mkTriangular</b> <i class="arg">size</i> <span class="opt">?uplo?</span> <span class="opt">?value?</span></a></dt>
<dd><p>Create a triangular matrix with non-zero elements in the upper or lower
part, depending on argument <em>uplo</em>.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
<dt>string <i class="arg">uplo</i></dt>
<dd><p>Fill the upper (U) or lower part (L)</p></dd>
<dt>double <i class="arg">value</i></dt>
<dd><p>Value to fill the matrix with</p></dd>
</dl></dd>
<dt><a name="39"><b class="cmd">::math::linearalgebra::mkHilbert</b> <i class="arg">size</i></a></dt>
<dd><p>Create a Hilbert matrix of dimension <em>size</em>.
Hilbert matrices are very ill-conditioned with respect to
eigenvalue/eigenvector problems. Therefore they
are good candidates for testing the accuracy
of algorithms and implementations.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="40"><b class="cmd">::math::linearalgebra::mkDingdong</b> <i class="arg">size</i></a></dt>
<dd><p>Create a "dingdong" matrix of dimension <em>size</em>.
Dingdong matrices are imprecisely represented,
but have the property of being very stable in
such algorithms as Gauss elimination.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="41"><b class="cmd">::math::linearalgebra::mkOnes</b> <i class="arg">size</i></a></dt>
<dd><p>Create a square matrix of dimension <em>size</em> whose entries are all 1.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="42"><b class="cmd">::math::linearalgebra::mkMoler</b> <i class="arg">size</i></a></dt>
<dd><p>Create a Moler matrix of size <em>size</em>. (Moler matrices have
a very simple Choleski decomposition. It has one small eigenvalue
and it can easily upset elimination methods for systems of linear
equations.)</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="43"><b class="cmd">::math::linearalgebra::mkFrank</b> <i class="arg">size</i></a></dt>
<dd><p>Create a Frank matrix of size <em>size</em>. (Frank matrices are
fairly well-behaved matrices)</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="44"><b class="cmd">::math::linearalgebra::mkBorder</b> <i class="arg">size</i></a></dt>
<dd><p>Create a bordered matrix of size <em>size</em>. (Bordered matrices have
a very low rank and can upset certain specialised algorithms.)</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="45"><b class="cmd">::math::linearalgebra::mkWilkinsonW+</b> <i class="arg">size</i></a></dt>
<dd><p>Create a Wilkinson W+ of size <em>size</em>. This kind of matrix
has pairs of eigenvalues that are very close together. Usually
the order (size) is odd.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
<dt><a name="46"><b class="cmd">::math::linearalgebra::mkWilkinsonW-</b> <i class="arg">size</i></a></dt>
<dd><p>Create a Wilkinson W- of size <em>size</em>. This kind of matrix
has pairs of eigenvalues with opposite signs, when the order (size)
is odd.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">size</i></dt>
<dd><p>Dimension of the matrix</p></dd>
</dl></dd>
</dl>
<p><em>Common algorithms</em></p>
<dl class="doctools_definitions">
<dt><a name="47"><b class="cmd">::math::linearalgebra::solveGauss</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></dt>
<dd><p>Solve a system of linear equations (Ax=b) using Gauss elimination.
Returns the solution (x) as a vector or matrix of the same shape as
bvect.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Square matrix (matrix A)</p></dd>
<dt>list <i class="arg">bvect</i></dt>
<dd><p>Vector or matrix whose columns are the individual
b-vectors</p></dd>
</dl></dd>
<dt><a name="48"><b class="cmd">::math::linearalgebra::solvePGauss</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></dt>
<dd><p>Solve a system of linear equations (Ax=b) using Gauss elimination with
partial pivoting. Returns the solution (x) as a vector or matrix of the
same shape as bvect.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Square matrix (matrix A)</p></dd>
<dt>list <i class="arg">bvect</i></dt>
<dd><p>Vector or matrix whose columns are the individual
b-vectors</p></dd>
</dl></dd>
<dt><a name="49"><b class="cmd">::math::linearalgebra::solveTriangular</b> <i class="arg">matrix</i> <i class="arg">bvect</i> <span class="opt">?uplo?</span></a></dt>
<dd><p>Solve a system of linear equations (Ax=b) by backward substitution. The
matrix is supposed to be upper-triangular.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Lower or upper-triangular matrix (matrix A)</p></dd>
<dt>list <i class="arg">bvect</i></dt>
<dd><p>Vector or matrix whose columns are the individual
b-vectors</p></dd>
<dt>string <i class="arg">uplo</i></dt>
<dd><p>Indicates whether the matrix is lower-triangular
(L) or upper-triangular (U). Defaults to "U".</p></dd>
</dl></dd>
<dt><a name="50"><b class="cmd">::math::linearalgebra::solveGaussBand</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></dt>
<dd><p>Solve a system of linear equations (Ax=b) using Gauss elimination,
where the matrix is stored as a band matrix (<em>cf.</em> <span class="sectref"><a href="#section3">STORAGE</a></span>).
Returns the solution (x) as a vector or matrix of the same shape as
bvect.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Square matrix (matrix A; in band form)</p></dd>
<dt>list <i class="arg">bvect</i></dt>
<dd><p>Vector or matrix whose columns are the individual
b-vectors</p></dd>
</dl></dd>
<dt><a name="51"><b class="cmd">::math::linearalgebra::solveTriangularBand</b> <i class="arg">matrix</i> <i class="arg">bvect</i></a></dt>
<dd><p>Solve a system of linear equations (Ax=b) by backward substitution. The
matrix is supposed to be upper-triangular and stored in band form.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Upper-triangular matrix (matrix A)</p></dd>
<dt>list <i class="arg">bvect</i></dt>
<dd><p>Vector or matrix whose columns are the individual
b-vectors</p></dd>
</dl></dd>
<dt><a name="52"><b class="cmd">::math::linearalgebra::determineSVD</b> <i class="arg">A</i> <i class="arg">eps</i></a></dt>
<dd><p>Determines the Singular Value Decomposition of a matrix: A = U S Vtrans.
Returns a list with the matrix U, the vector of singular values S and
the matrix V.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">A</i></dt>
<dd><p>Matrix to be decomposed</p></dd>
<dt>float <i class="arg">eps</i></dt>
<dd><p>Tolerance (defaults to 2.3e-16)</p></dd>
</dl></dd>
<dt><a name="53"><b class="cmd">::math::linearalgebra::eigenvectorsSVD</b> <i class="arg">A</i> <i class="arg">eps</i></a></dt>
<dd><p>Determines the eigenvectors and eigenvalues of a real
<em>symmetric</em> matrix, using SVD. Returns a list with the matrix of
normalized eigenvectors and their eigenvalues.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">A</i></dt>
<dd><p>Matrix whose eigenvalues must be determined</p></dd>
<dt>float <i class="arg">eps</i></dt>
<dd><p>Tolerance (defaults to 2.3e-16)</p></dd>
</dl></dd>
<dt><a name="54"><b class="cmd">::math::linearalgebra::leastSquaresSVD</b> <i class="arg">A</i> <i class="arg">y</i> <i class="arg">qmin</i> <i class="arg">eps</i></a></dt>
<dd><p>Determines the solution to a least-sqaures problem Ax ~ y via singular
value decomposition. The result is the vector x.</p>
<p>Note that if you add a column of 1s to the matrix, then this column will
represent a constant like in: y = a*x1 + b*x2 + c. To force the
intercept to be zero, simply leave it out.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">A</i></dt>
<dd><p>Matrix of independent variables</p></dd>
<dt>list <i class="arg">y</i></dt>
<dd><p>List of observed values</p></dd>
<dt>float <i class="arg">qmin</i></dt>
<dd><p>Minimum singular value to be considered (defaults to 0.0)</p></dd>
<dt>float <i class="arg">eps</i></dt>
<dd><p>Tolerance (defaults to 2.3e-16)</p></dd>
</dl></dd>
<dt><a name="55"><b class="cmd">::math::linearalgebra::choleski</b> <i class="arg">matrix</i></a></dt>
<dd><p>Determine the Choleski decomposition of a symmetric positive
semidefinite matrix (this condition is not checked!). The result
is the lower-triangular matrix L such that L Lt = matrix.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix to be decomposed</p></dd>
</dl></dd>
<dt><a name="56"><b class="cmd">::math::linearalgebra::orthonormalizeColumns</b> <i class="arg">matrix</i></a></dt>
<dd><p>Use the modified Gram-Schmidt method to orthogonalize and normalize
the <em>columns</em> of the given matrix and return the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix whose columns must be orthonormalized</p></dd>
</dl></dd>
<dt><a name="57"><b class="cmd">::math::linearalgebra::orthonormalizeRows</b> <i class="arg">matrix</i></a></dt>
<dd><p>Use the modified Gram-Schmidt method to orthogonalize and normalize
the <em>rows</em> of the given matrix and return the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix whose rows must be orthonormalized</p></dd>
</dl></dd>
<dt><a name="58"><b class="cmd">::math::linearalgebra::dger</b> <i class="arg">matrix</i> <i class="arg">alpha</i> <i class="arg">x</i> <i class="arg">y</i> <span class="opt">?scope?</span></a></dt>
<dd><p>Perform the rank 1 operation A + alpha*x*y' inline (that is: the matrix A is adjusted).
For convenience the new matrix is also returned as the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Matrix whose rows must be adjusted</p></dd>
<dt>double <i class="arg">alpha</i></dt>
<dd><p>Scale factor</p></dd>
<dt>list <i class="arg">x</i></dt>
<dd><p>A column vector</p></dd>
<dt>list <i class="arg">y</i></dt>
<dd><p>A column vector</p></dd>
<dt>list <i class="arg">scope</i></dt>
<dd><p>If not provided, the operation is performed on all rows/columns of A
if provided, it is expected to be the list {imin imax jmin jmax}
where:</p>
<ul class="doctools_itemized">
<li><p><i class="term">imin</i> Minimum row index</p></li>
<li><p><i class="term">imax</i> Maximum row index</p></li>
<li><p><i class="term">jmin</i> Minimum column index</p></li>
<li><p><i class="term">jmax</i> Maximum column index</p></li>
</ul></dd>
</dl></dd>
<dt><a name="59"><b class="cmd">::math::linearalgebra::dgetrf</b> <i class="arg">matrix</i></a></dt>
<dd><p>Computes an LU factorization of a general matrix, using partial,
pivoting with row interchanges. Returns the permutation vector.</p>
<p>The factorization has the form</p>
<pre class="doctools_example">
P * A = L * U
</pre>
<p>where P is a permutation matrix, L is lower triangular with unit
diagonal elements, and U is upper triangular.
Returns the permutation vector, as a list of length n-1.
The last entry of the permutation is not stored, since it is
implicitely known, with value n (the last row is not swapped
with any other row).
At index #i of the permutation is stored the index of the row #j
which is swapped with row #i at step #i. That means that each
index of the permutation gives the permutation at each step, not the
cumulated permutation matrix, which is the product of permutations.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>On entry, the matrix to be factored.
On exit, the factors L and U from the factorization
P*A = L*U; the unit diagonal elements of L are not stored.</p></dd>
</dl></dd>
<dt><a name="60"><b class="cmd">::math::linearalgebra::det</b> <i class="arg">matrix</i></a></dt>
<dd><p>Returns the determinant of the given matrix, based on PA=LU
decomposition, i.e. Gauss partial pivotal.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Square matrix (matrix A)</p></dd>
<dt>list <i class="arg">ipiv</i></dt>
<dd><p>The pivots (optionnal).
If the pivots are not provided, a PA=LU decomposition
is performed.
If the pivots are provided, we assume that it
contains the pivots and that the matrix A contains the
L and U factors, as provided by dgterf.
b-vectors</p></dd>
</dl></dd>
<dt><a name="61"><b class="cmd">::math::linearalgebra::largesteigen</b> <i class="arg">matrix</i> <i class="arg">tolerance</i> <i class="arg">maxiter</i></a></dt>
<dd><p>Returns a list made of the largest eigenvalue (in magnitude)
and associated eigenvector.
Uses iterative Power Method as provided as algorithm #7.3.3 of Golub & Van Loan.
This algorithm is used here for a dense matrix (but is usually
used for sparse matrices).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">matrix</i></dt>
<dd><p>Square matrix (matrix A)</p></dd>
<dt>double <i class="arg">tolerance</i></dt>
<dd><p>The relative tolerance of the eigenvalue (default:1.e-8).</p></dd>
<dt>integer <i class="arg">maxiter</i></dt>
<dd><p>The maximum number of iterations (default:10).</p></dd>
</dl></dd>
</dl>
<p><em>Compability with the LA package</em>
Two procedures are provided for compatibility with Hume's LA package:</p>
<dl class="doctools_definitions">
<dt><a name="62"><b class="cmd">::math::linearalgebra::to_LA</b> <i class="arg">mv</i></a></dt>
<dd><p>Transforms a vector or matrix into the format used by the original LA
package.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv</i></dt>
<dd><p>Matrix or vector</p></dd>
</dl></dd>
<dt><a name="63"><b class="cmd">::math::linearalgebra::from_LA</b> <i class="arg">mv</i></a></dt>
<dd><p>Transforms a vector or matrix from the format used by the original LA
package into the format used by the present implementation.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">mv</i></dt>
<dd><p>Matrix or vector as used by the LA package</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">STORAGE</a></h2>
<p>While most procedures assume that the matrices are given in full form,
the procedures <em>solveGaussBand</em> and <em>solveTriangularBand</em>
assume that the matrices are stored as <em>band matrices</em>. This
common type of "sparse" matrices is related to ordinary matrices as
follows:</p>
<ul class="doctools_itemized">
<li><p>"A" is a full-size matrix with N rows and M columns.</p></li>
<li><p>"B" is a band matrix, with m upper and lower diagonals and n rows.</p></li>
<li><p>"B" can be stored in an ordinary matrix of (2m+1) columns (one for
each off-diagonal and the main diagonal) and n rows.</p></li>
<li><p>Element i,j (i = -m,...,m; j =1,...,n) of "B" corresponds to element
k,j of "A" where k = M+i-1 and M is at least (!) n, the number of rows
in "B".</p></li>
<li><p>To set element (i,j) of matrix "B" use:</p>
<pre class="doctools_example">
setelem B $j [expr {$N+$i-1}] $value
</pre>
</li>
</ul>
<p>(There is no convenience procedure for this yet)</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REMARKS ON THE IMPLEMENTATION</a></h2>
<p>There is a difference between the original LA package by Hume and the
current implementation. Whereas the LA package uses a linear list, the
current package uses lists of lists to represent matrices. It turns out
that with this representation, the algorithms are faster and easier to
implement.</p>
<p>The LA package was used as a model and in fact the implementation of,
for instance, the SVD algorithm was taken from that package. The set of
procedures was expanded using ideas from the well-known BLAS library and
some algorithms were updated from the second edition of J.C. Nash's
book, Compact Numerical Methods for Computers, (Adam Hilger, 1990) that
inspired the LA package.</p>
<p>Two procedures are provided to make the transition between the two
implementations easier: <em>to_LA</em> and <em>from_LA</em>. They are
described above.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">TODO</a></h2>
<p>Odds and ends: the following algorithms have not been implemented yet:</p>
<ul class="doctools_itemized">
<li><p>determineQR</p></li>
<li><p>certainlyPositive, diagonallyDominant</p></li>
</ul>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">NAMING CONFLICT</a></h2>
<p>If you load this package in a Tk-enabled shell like wish, then the
command</p>
<pre class="doctools_example">namespace import ::math::linearalgebra</pre>
<p>results in an error
message about "scale". This is due to the fact that Tk defines all
its commands in the global namespace. The solution is to import
the linear algebra commands in a namespace that is not the global one:</p>
<pre class="doctools_example">
package require math::linearalgebra
namespace eval compute {
namespace import ::math::linearalgebra::*
... use the linear algebra version of scale ...
}
</pre>
<p>To use Tk's scale command in that same namespace you can rename it:</p>
<pre class="doctools_example">
namespace eval compute {
rename ::scale scaleTk
scaleTk .scale ...
}
</pre>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: linearalgebra</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#least_squares">least squares</a>, <a href="../../../../index.html#linear_algebra">linear algebra</a>, <a href="../../../../index.html#linear_equations">linear equations</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#matrices">matrices</a>, <a href="../../../../index.html#matrix">matrix</a>, <a href="../../../../index.html#vectors">vectors</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2008 Arjen Markus <[email protected]><br>
Copyright © 2004 Ed Hume <http://www.hume.com/contact.us.htm><br>
Copyright © 2008 Michael Buadin <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/machineparameters.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<div class='fossil-doc' data-title='tclrep/machineparameters - tclrep'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tclrep/machineparameters(n) 1.0 tcllib "tclrep"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tclrep/machineparameters - Compute double precision machine parameters.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section3">REFERENCES</a></li>
<li class="doctools_section"><a href="#section4">CLASS API</a></li>
<li class="doctools_section"><a href="#section5">OBJECT API</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">math::machineparameters 0.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">machineparameters</b> create <i class="arg">objectname</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectname</i> <b class="method">configure</b> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#3"><i class="arg">objectname</i> <b class="method">cget</b> <i class="arg">opt</i></a></li>
<li><a href="#4"><i class="arg">objectname</i> <b class="method">destroy</b></a></li>
<li><a href="#5"><i class="arg">objectname</i> <b class="method">compute</b></a></li>
<li><a href="#6"><i class="arg">objectname</i> <b class="method">get</b> <i class="arg">key</i></a></li>
<li><a href="#7"><i class="arg">objectname</i> <b class="method">tostring</b></a></li>
<li><a href="#8"><i class="arg">objectname</i> <b class="method">print</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <em>math::machineparameters</em> package
is the Tcl equivalent of the DLAMCH LAPACK function.
In floating point systems, a floating point number is represented
by</p>
<pre class="doctools_example">
x = +/- d1 d2 ... dt basis^e
</pre>
<p>where digits satisfy</p>
<pre class="doctools_example">
0 <= di <= basis - 1, i = 1, t
</pre>
<p>with the convention :</p>
<ul class="doctools_itemized">
<li><p>t is the size of the mantissa</p></li>
<li><p>basis is the basis (the "radix")</p></li>
</ul>
<p>The <b class="method">compute</b> method computes all machine parameters.
Then, the <b class="method">get</b> method can be used to get each
parameter.
The <b class="method">print</b> method prints a report on standard output.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLE</a></h2>
<p>In the following example, one compute the parameters of a desktop
under Linux with the following Tcl 8.4.19 properties :</p>
<pre class="doctools_example">
% parray tcl_platform
tcl_platform(byteOrder) = littleEndian
tcl_platform(machine) = i686
tcl_platform(os) = Linux
tcl_platform(osVersion) = 2.6.24-19-generic
tcl_platform(platform) = unix
tcl_platform(tip,268) = 1
tcl_platform(tip,280) = 1
tcl_platform(user) = <username>
tcl_platform(wordSize) = 4
</pre>
<p>The following example creates a machineparameters object,
computes the properties and displays it.</p>
<pre class="doctools_example">
set pp [machineparameters create %AUTO%]
$pp compute
$pp print
$pp destroy
</pre>
<p>This prints out :</p>
<pre class="doctools_example">
Machine parameters
Epsilon : 1.11022302463e-16
Beta : 2
Rounding : proper
Mantissa : 53
Maximum exponent : 1024
Minimum exponent : -1021
Overflow threshold : 8.98846567431e+307
Underflow threshold : 2.22507385851e-308
</pre>
<p>That compares well with the results produced by Lapack 3.1.1 :</p>
<pre class="doctools_example">
Epsilon = 1.11022302462515654E-016
Safe minimum = 2.22507385850720138E-308
Base = 2.0000000000000000
Precision = 2.22044604925031308E-016
Number of digits in mantissa = 53.000000000000000
Rounding mode = 1.00000000000000000
Minimum exponent = -1021.0000000000000
Underflow threshold = 2.22507385850720138E-308
Largest exponent = 1024.0000000000000
Overflow threshold = 1.79769313486231571E+308
Reciprocal of safe minimum = 4.49423283715578977E+307
</pre>
<p>The following example creates a machineparameters object,
computes the properties and gets the epsilon for
the machine.</p>
<pre class="doctools_example">
set pp [machineparameters create %AUTO%]
$pp compute
set eps [$pp get -epsilon]
$pp destroy
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">REFERENCES</a></h2>
<ul class="doctools_itemized">
<li><p>"Algorithms to Reveal Properties of Floating-Point Arithmetic", Michael A. Malcolm, Stanford University, Communications of the ACM, Volume 15 , Issue 11 (November 1972), Pages: 949 - 951</p></li>
<li><p>"More on Algorithms that Reveal Properties of Floating, Point Arithmetic Units", W. Morven Gentleman, University of Waterloo, Scott B. Marovich, Purdue University, Communications of the ACM, Volume 17 , Issue 5 (May 1974), Pages: 276 - 277</p></li>
</ul>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">CLASS API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">machineparameters</b> create <i class="arg">objectname</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>The command creates a new machineparameters object and returns the fully
qualified name of the object command as its result.</p>
<dl class="doctools_options">
<dt><b class="option">-verbose</b> <i class="arg">verbose</i></dt>
<dd><p>Set this option to 1 to enable verbose logging.
This option is mainly for debug purposes.
The default value of <i class="arg">verbose</i> is 0.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">OBJECT API</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectname</i> <b class="method">configure</b> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>The command configure the options of the object <i class="arg">objectname</i>. The options
are the same as the static method <b class="method">create</b>.</p></dd>
<dt><a name="3"><i class="arg">objectname</i> <b class="method">cget</b> <i class="arg">opt</i></a></dt>
<dd><p>Returns the value of the option which name is <i class="arg">opt</i>. The options
are the same as the method <b class="method">create</b> and <b class="method">configure</b>.</p></dd>
<dt><a name="4"><i class="arg">objectname</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the object <i class="arg">objectname</i>.</p></dd>
<dt><a name="5"><i class="arg">objectname</i> <b class="method">compute</b></a></dt>
<dd><p>Computes the machine parameters.</p></dd>
<dt><a name="6"><i class="arg">objectname</i> <b class="method">get</b> <i class="arg">key</i></a></dt>
<dd><p>Returns the value corresponding with given key.
The following is the list of available keys.</p>
<ul class="doctools_itemized">
<li><p>-epsilon : smallest value so that 1+epsilon>1 is false</p></li>
<li><p>-rounding : The rounding mode used on the machine.
The rounding occurs when more than t digits would be required to
represent the number.
Two modes can be determined with the current system :
"chop" means than only t digits are kept, no matter the value of the number
"proper" means that another rounding mode is used, be it "round to nearest",
"round up", "round down".</p></li>
<li><p>-basis : the basis of the floating-point representation.
The basis is usually 2, i.e. binary representation (for example IEEE 754 machines),
but some machines (like HP calculators for example) uses 10, or 16, etc...</p></li>
<li><p>-mantissa : the number of bits in the mantissa</p></li>
<li><p>-exponentmax : the largest positive exponent before overflow occurs</p></li>
<li><p>-exponentmin : the largest negative exponent before (gradual) underflow occurs</p></li>
<li><p>-vmax : largest positive value before overflow occurs</p></li>
<li><p>-vmin : largest negative value before (gradual) underflow occurs</p></li>
</ul></dd>
<dt><a name="7"><i class="arg">objectname</i> <b class="method">tostring</b></a></dt>
<dd><p>Return a report for machine parameters.</p></dd>
<dt><a name="8"><i class="arg">objectname</i> <b class="method">print</b></a></dt>
<dd><p>Print machine parameters on standard output.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Michael Baudin <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/math.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<div class='fossil-doc' data-title='math - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math(n) 1.2.5 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math - Tcl Math Library</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">BASIC COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">math <span class="opt">?1.2.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::cov</b> <i class="arg">value</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::math::integrate</b> <i class="arg">list of xy value pairs</i></a></li>
<li><a href="#3"><b class="cmd">::math::fibonacci</b> <i class="arg">n</i></a></li>
<li><a href="#4"><b class="cmd">::math::max</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::math::mean</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::math::min</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::math::product</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::math::random</b> <span class="opt">?<i class="arg">value1</i>?</span> <span class="opt">?<i class="arg">value2</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::math::sigma</b> <i class="arg">value</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::math::stats</b> <i class="arg">value</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::math::sum</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">math</b> package provides utility math functions.</p>
<p>Besides a set of basic commands, available via the package <em>math</em>,
there are more specialised packages:</p>
<ul class="doctools_itemized">
<li><p><b class="package"><a href="bigfloat.html">math::bigfloat</a></b> - Arbitrary-precision floating-point
arithmetic</p></li>
<li><p><b class="package"><a href="bignum.html">math::bignum</a></b> - Arbitrary-precision integer arithmetic</p></li>
<li><p><b class="package"><a href="romberg.html">math::calculus::romberg</a></b> - Robust integration methods for
functions of one variable, using Romberg integration</p></li>
<li><p><b class="package"><a href="calculus.html">math::calculus</a></b> - Integration of functions, solving ordinary
differential equations</p></li>
<li><p><b class="package"><a href="combinatorics.html">math::combinatorics</a></b> - Procedures for various combinatorial
functions (for instance the Gamma function and "k out of n")</p></li>
<li><p><b class="package"><a href="qcomplex.html">math::complexnumbers</a></b> - Complex number arithmetic</p></li>
<li><p><b class="package"><a href="constants.html">math::constants</a></b> - A set of well-known mathematical
constants, such as Pi, E, and the golden ratio</p></li>
<li><p><b class="package"><a href="fourier.html">math::fourier</a></b> - Discrete Fourier transforms</p></li>
<li><p><b class="package"><a href="fuzzy.html">math::fuzzy</a></b> - Fuzzy comparisons of floating-point numbers</p></li>
<li><p><b class="package"><a href="math_geometry.html">math::geometry</a></b> - 2D geometrical computations</p></li>
<li><p><b class="package"><a href="interpolate.html">math::interpolate</a></b> - Various interpolation methods</p></li>
<li><p><b class="package"><a href="linalg.html">math::linearalgebra</a></b> - Linear algebra package</p></li>
<li><p><b class="package"><a href="optimize.html">math::optimize</a></b> - Optimization methods</p></li>
<li><p><b class="package"><a href="polynomials.html">math::polynomials</a></b> - Polynomial arithmetic (includes families
of classical polynomials)</p></li>
<li><p><b class="package"><a href="rational_funcs.html">math::rationalfunctions</a></b> - Arithmetic of rational functions</p></li>
<li><p><b class="package"><a href="roman.html">math::roman</a></b> - Manipulation (including arithmetic) of Roman
numerals</p></li>
<li><p><b class="package"><a href="special.html">math::special</a></b> - Approximations of special functions from
mathematical physics</p></li>
<li><p><b class="package"><a href="statistics.html">math::statistics</a></b> - Statistical operations and tests</p></li>
</ul>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">BASIC COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::cov</b> <i class="arg">value</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the coefficient of variation expressed as percent of two or
more numeric values.</p></dd>
<dt><a name="2"><b class="cmd">::math::integrate</b> <i class="arg">list of xy value pairs</i></a></dt>
<dd><p>Return the area under a "curve" defined by a set of x,y pairs and the
error bound as a list.</p></dd>
<dt><a name="3"><b class="cmd">::math::fibonacci</b> <i class="arg">n</i></a></dt>
<dd><p>Return the <i class="arg">n</i>'th Fibonacci number.</p></dd>
<dt><a name="4"><b class="cmd">::math::max</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the maximum of one or more numeric values.</p></dd>
<dt><a name="5"><b class="cmd">::math::mean</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the mean, or "average" of one or more numeric values.</p></dd>
<dt><a name="6"><b class="cmd">::math::min</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the minimum of one or more numeric values.</p></dd>
<dt><a name="7"><b class="cmd">::math::product</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the product of one or more numeric values.</p></dd>
<dt><a name="8"><b class="cmd">::math::random</b> <span class="opt">?<i class="arg">value1</i>?</span> <span class="opt">?<i class="arg">value2</i>?</span></a></dt>
<dd><p>Return a random number. If no arguments are given, the number is a
floating point value between 0 and 1. If one argument is given, the
number is an integer value between 0 and <i class="arg">value1</i>. If two
arguments are given, the number is an integer value between
<i class="arg">value1</i> and <i class="arg">value2</i>.</p></dd>
<dt><a name="9"><b class="cmd">::math::sigma</b> <i class="arg">value</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the population standard deviation of two or more numeric
values.</p></dd>
<dt><a name="10"><b class="cmd">::math::stats</b> <i class="arg">value</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the mean, standard deviation, and coefficient of variation (as
percent) as a list.</p></dd>
<dt><a name="11"><b class="cmd">::math::sum</b> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Return the sum of one or more numeric values.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#statistics">statistics</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/math_geometry.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
<div class='fossil-doc' data-title='math::geometry - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::geometry(n) 1.3.0 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::geometry - Geometrical computations</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.5?</span></b></li>
<li>package require <b class="pkgname">math::geometry <span class="opt">?1.3.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::geometry::+</b> <i class="arg">point1</i> <i class="arg">point2</i></a></li>
<li><a href="#2"><b class="cmd">::math::geometry::-</b> <i class="arg">point1</i> <i class="arg">point2</i></a></li>
<li><a href="#3"><b class="cmd">::math::geometry::p</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#4"><b class="cmd">::math::geometry::distance</b> <i class="arg">point1</i> <i class="arg">point2</i></a></li>
<li><a href="#5"><b class="cmd">::math::geometry::length</b> <i class="arg">point</i></a></li>
<li><a href="#6"><b class="cmd">::math::geometry::s*</b> <i class="arg">factor</i> <i class="arg">point</i></a></li>
<li><a href="#7"><b class="cmd">::math::geometry::direction</b> <i class="arg">angle</i></a></li>
<li><a href="#8"><b class="cmd">::math::geometry::h</b> <i class="arg">length</i></a></li>
<li><a href="#9"><b class="cmd">::math::geometry::v</b> <i class="arg">length</i></a></li>
<li><a href="#10"><b class="cmd">::math::geometry::between</b> <i class="arg">point1</i> <i class="arg">point2</i> <i class="arg">s</i></a></li>
<li><a href="#11"><b class="cmd">::math::geometry::octant</b> <i class="arg">point</i></a></li>
<li><a href="#12"><b class="cmd">::math::geometry::rect</b> <i class="arg">nw</i> <i class="arg">se</i></a></li>
<li><a href="#13"><b class="cmd">::math::geometry::nwse</b> <i class="arg">rect</i></a></li>
<li><a href="#14"><b class="cmd">::math::geometry::angle</b> <i class="arg">line</i></a></li>
<li><a href="#15"><b class="cmd">::math::geometry::calculateDistanceToLine</b> <i class="arg">P</i> <i class="arg">line</i></a></li>
<li><a href="#16"><b class="cmd">::math::geometry::calculateDistanceToLineSegment</b> <i class="arg">P</i> <i class="arg">linesegment</i></a></li>
<li><a href="#17"><b class="cmd">::math::geometry::calculateDistanceToPolyline</b> <i class="arg">P</i> <i class="arg">polyline</i></a></li>
<li><a href="#18"><b class="cmd">::math::geometry::calculateDistanceToPolygon</b> <i class="arg">P</i> <i class="arg">polygon</i></a></li>
<li><a href="#19"><b class="cmd">::math::geometry::findClosestPointOnLine</b> <i class="arg">P</i> <i class="arg">line</i></a></li>
<li><a href="#20"><b class="cmd">::math::geometry::findClosestPointOnLineSegment</b> <i class="arg">P</i> <i class="arg">linesegment</i></a></li>
<li><a href="#21"><b class="cmd">::math::geometry::findClosestPointOnPolyline</b> <i class="arg">P</i> <i class="arg">polyline</i></a></li>
<li><a href="#22"><b class="cmd">::math::geometry::lengthOfPolyline</b> <i class="arg">polyline</i></a></li>
<li><a href="#23"><b class="cmd">::math::geometry::movePointInDirection</b> <i class="arg">P</i> <i class="arg">direction</i> <i class="arg">dist</i></a></li>
<li><a href="#24"><b class="cmd">::math::geometry::lineSegmentsIntersect</b> <i class="arg">linesegment1</i> <i class="arg">linesegment2</i></a></li>
<li><a href="#25"><b class="cmd">::math::geometry::findLineSegmentIntersection</b> <i class="arg">linesegment1</i> <i class="arg">linesegment2</i></a></li>
<li><a href="#26"><b class="cmd">::math::geometry::findLineIntersection</b> <i class="arg">line1</i> <i class="arg">line2</i></a></li>
<li><a href="#27"><b class="cmd">::math::geometry::polylinesIntersect</b> <i class="arg">polyline1</i> <i class="arg">polyline2</i></a></li>
<li><a href="#28"><b class="cmd">::math::geometry::polylinesBoundingIntersect</b> <i class="arg">polyline1</i> <i class="arg">polyline2</i> <i class="arg">granularity</i></a></li>
<li><a href="#29"><b class="cmd">::math::geometry::intervalsOverlap</b> <i class="arg">y1</i> <i class="arg">y2</i> <i class="arg">y3</i> <i class="arg">y4</i> <i class="arg">strict</i></a></li>
<li><a href="#30"><b class="cmd">::math::geometry::rectanglesOverlap</b> <i class="arg">P1</i> <i class="arg">P2</i> <i class="arg">Q1</i> <i class="arg">Q2</i> <i class="arg">strict</i></a></li>
<li><a href="#31"><b class="cmd">::math::geometry::bbox</b> <i class="arg">polyline</i></a></li>
<li><a href="#32"><b class="cmd">::math::geometry::pointInsidePolygon</b> <i class="arg">P</i> <i class="arg">polyline</i></a></li>
<li><a href="#33"><b class="cmd">::math::geometry::pointInsidePolygonAlt</b> <i class="arg">P</i> <i class="arg">polyline</i></a></li>
<li><a href="#34"><b class="cmd">::math::geometry::rectangleInsidePolygon</b> <i class="arg">P1</i> <i class="arg">P2</i> <i class="arg">polyline</i></a></li>
<li><a href="#35"><b class="cmd">::math::geometry::areaPolygon</b> <i class="arg">polygon</i></a></li>
<li><a href="#36"><b class="cmd">::math::geometry::translate</b> <i class="arg">vector</i> <i class="arg">polyline</i></a></li>
<li><a href="#37"><b class="cmd">::math::geometry::rotate</b> <i class="arg">angle</i> <i class="arg">polyline</i></a></li>
<li><a href="#38"><b class="cmd">::math::geometry::reflect</b> <i class="arg">angle</i> <i class="arg">polyline</i></a></li>
<li><a href="#39"><b class="cmd">::math::geometry::degToRad</b> <i class="arg">angle</i></a></li>
<li><a href="#40"><b class="cmd">::math::geometry::radToDeg</b> <i class="arg">angle</i></a></li>
<li><a href="#41"><b class="cmd">::math::geometry::circle</b> <i class="arg">centre</i> <i class="arg">radius</i></a></li>
<li><a href="#42"><b class="cmd">::math::geometry::circleTwoPoints</b> <i class="arg">point1</i> <i class="arg">point2</i></a></li>
<li><a href="#43"><b class="cmd">::math::geometry::pointInsideCircle</b> <i class="arg">point</i> <i class="arg">circle</i></a></li>
<li><a href="#44"><b class="cmd">::math::geometry::lineIntersectsCircle</b> <i class="arg">line</i> <i class="arg">circle</i></a></li>
<li><a href="#45"><b class="cmd">::math::geometry::lineSegmentIntersectsCircle</b> <i class="arg">segment</i> <i class="arg">circle</i></a></li>
<li><a href="#46"><b class="cmd">::math::geometry::intersectionLineWithCircle</b> <i class="arg">line</i> <i class="arg">circle</i></a></li>
<li><a href="#47"><b class="cmd">::math::geometry::intersectionCircleWithCircle</b> <i class="arg">circle1</i> <i class="arg">circle2</i></a></li>
<li><a href="#48"><b class="cmd">::math::geometry::tangentLinesToCircle</b> <i class="arg">point</i> <i class="arg">circle</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">math::geometry</b> package is a collection of functions for
computations and manipulations on two-dimensional geometrical objects,
such as points, lines and polygons.</p>
<p>The geometrical objects are implemented as plain lists of coordinates.
For instance a line is defined by a list of four numbers, the x- and
y-coordinate of a first point and the x- and y-coordinates of a second
point on the line.</p>
<p>The various types of object are recognised by the number of coordinate
pairs and the context in which they are used: a list of four elements
can be regarded as an infinite line, a finite line segment but also
as a polyline of one segment and a point set of two points.</p>
<p>Currently the following types of objects are distinguished:</p>
<ul class="doctools_itemized">
<li><p><em>point</em> - a list of two coordinates representing the x- and
y-coordinates respectively.</p></li>
<li><p><em>line</em> - a list of four coordinates, interpreted as the x- and
y-coordinates of two distinct points on the line.</p></li>
<li><p><em>line segment</em> - a list of four coordinates, interpreted as the
x- and y-coordinates of the first and the last points on the line
segment.</p></li>
<li><p><em>polyline</em> - a list of an even number of coordinates,
interpreted as the x- and y-coordinates of an ordered set of points.</p></li>
<li><p><em>polygon</em> - like a polyline, but the implicit assumption is that
the polyline is closed (if the first and last points do not coincide,
the missing segment is automatically added).</p></li>
<li><p><em>point set</em> - again a list of an even number of coordinates, but
the points are regarded without any ordering.</p></li>
<li><p><em>circle</em> - a list of three numbers, the first two are the coordinates of the
centre and the third is the radius.</p></li>
</ul>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::geometry::+</b> <i class="arg">point1</i> <i class="arg">point2</i></a></dt>
<dd><p>Compute the sum of the two vectors given as points and return it.
The result is a vector as well.</p></dd>
<dt><a name="2"><b class="cmd">::math::geometry::-</b> <i class="arg">point1</i> <i class="arg">point2</i></a></dt>
<dd><p>Compute the difference (point1 - point2) of the two vectors
given as points and return it. The result is a vector as well.</p></dd>
<dt><a name="3"><b class="cmd">::math::geometry::p</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Construct a point from its coordinates and return it as the
result of the command.</p></dd>
<dt><a name="4"><b class="cmd">::math::geometry::distance</b> <i class="arg">point1</i> <i class="arg">point2</i></a></dt>
<dd><p>Compute the distance between the two points and return it as the
result of the command. This is in essence the same as</p>
<pre class="doctools_example">
math::geometry::length [math::geomtry::- point1 point2]
</pre>
</dd>
<dt><a name="5"><b class="cmd">::math::geometry::length</b> <i class="arg">point</i></a></dt>
<dd><p>Compute the length of the vector and return it as the
result of the command.</p></dd>
<dt><a name="6"><b class="cmd">::math::geometry::s*</b> <i class="arg">factor</i> <i class="arg">point</i></a></dt>
<dd><p>Scale the vector by the factor and return it as the
result of the command. This is a vector as well.</p></dd>
<dt><a name="7"><b class="cmd">::math::geometry::direction</b> <i class="arg">angle</i></a></dt>
<dd><p>Given the angle in degrees this command computes and returns
the unit vector pointing into this direction. The vector for
angle == 0 points to the right (up), and for angle == 90 up (north).</p></dd>
<dt><a name="8"><b class="cmd">::math::geometry::h</b> <i class="arg">length</i></a></dt>
<dd><p>Returns a horizontal vector on the X-axis of the specified length.
Positive lengths point to the right (east).</p></dd>
<dt><a name="9"><b class="cmd">::math::geometry::v</b> <i class="arg">length</i></a></dt>
<dd><p>Returns a vertical vector on the Y-axis of the specified length.
Positive lengths point down (south).</p></dd>
<dt><a name="10"><b class="cmd">::math::geometry::between</b> <i class="arg">point1</i> <i class="arg">point2</i> <i class="arg">s</i></a></dt>
<dd><p>Compute the point which is at relative distance <i class="arg">s</i> between the two
points and return it as the result of the command. A relative distance of
<b class="const">0</b> returns <i class="arg">point1</i>, the distance <b class="const">1</b> returns <i class="arg">point2</i>.
Distances < 0 or > 1 extrapolate along the line between the two point.</p></dd>
<dt><a name="11"><b class="cmd">::math::geometry::octant</b> <i class="arg">point</i></a></dt>
<dd><p>Compute the octant of the circle the point is in and return it as the result
of the command. The possible results are</p>
<ol class="doctools_enumerated">
<li><p>east</p></li>
<li><p>northeast</p></li>
<li><p>north</p></li>
<li><p>northwest</p></li>
<li><p>west</p></li>
<li><p>southwest</p></li>
<li><p>south</p></li>
<li><p>southeast</p></li>
</ol>
<p>Each octant is the arc of the circle +/- 22.5 degrees from the cardinal direction
the octant is named for.</p></dd>
<dt><a name="12"><b class="cmd">::math::geometry::rect</b> <i class="arg">nw</i> <i class="arg">se</i></a></dt>
<dd><p>Construct a rectangle from its northwest and southeast corners and return
it as the result of the command.</p></dd>
<dt><a name="13"><b class="cmd">::math::geometry::nwse</b> <i class="arg">rect</i></a></dt>
<dd><p>Extract the northwest and southeast corners of the rectangle and return
them as the result of the command (a 2-element list containing the
points, in the named order).</p></dd>
<dt><a name="14"><b class="cmd">::math::geometry::angle</b> <i class="arg">line</i></a></dt>
<dd><p>Calculate the angle from the positive x-axis to a given line
(in two dimensions only).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">line</i></dt>
<dd><p>Coordinates of the line</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::geometry::calculateDistanceToLine</b> <i class="arg">P</i> <i class="arg">line</i></a></dt>
<dd><p>Calculate the distance of point P to the (infinite) line and return the
result</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">line</i></dt>
<dd><p>List of four numbers, the coordinates of two points
on the line</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::geometry::calculateDistanceToLineSegment</b> <i class="arg">P</i> <i class="arg">linesegment</i></a></dt>
<dd><p>Calculate the distance of point P to the (finite) line segment and
return the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">linesegment</i></dt>
<dd><p>List of four numbers, the coordinates of the
first and last points of the line segment</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">::math::geometry::calculateDistanceToPolyline</b> <i class="arg">P</i> <i class="arg">polyline</i></a></dt>
<dd><p>Calculate the distance of point P to the polyline and
return the result. Note that a polyline needs not to be closed.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>List of numbers, the coordinates of the
vertices of the polyline</p></dd>
</dl></dd>
<dt><a name="18"><b class="cmd">::math::geometry::calculateDistanceToPolygon</b> <i class="arg">P</i> <i class="arg">polygon</i></a></dt>
<dd><p>Calculate the distance of point P to the polygon and
return the result. If the list of coordinates is not closed (first and last
points differ), it is automatically closed.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">polygon</i></dt>
<dd><p>List of numbers, the coordinates of the
vertices of the polygon</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">::math::geometry::findClosestPointOnLine</b> <i class="arg">P</i> <i class="arg">line</i></a></dt>
<dd><p>Return the point on a line which is closest to a given point.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">line</i></dt>
<dd><p>List of four numbers, the coordinates of two points
on the line</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">::math::geometry::findClosestPointOnLineSegment</b> <i class="arg">P</i> <i class="arg">linesegment</i></a></dt>
<dd><p>Return the point on a <em>line segment</em> which is closest to a given
point.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">linesegment</i></dt>
<dd><p>List of four numbers, the first and last
points on the line segment</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">::math::geometry::findClosestPointOnPolyline</b> <i class="arg">P</i> <i class="arg">polyline</i></a></dt>
<dd><p>Return the point on a <em>polyline</em> which is closest to a given
point.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>List of two numbers, the coordinates of the point</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>List of numbers, the vertices of the polyline</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">::math::geometry::lengthOfPolyline</b> <i class="arg">polyline</i></a></dt>
<dd><p>Return the length of the <em>polyline</em> (note: it not regarded as a
polygon)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyline</i></dt>
<dd><p>List of numbers, the vertices of the polyline</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">::math::geometry::movePointInDirection</b> <i class="arg">P</i> <i class="arg">direction</i> <i class="arg">dist</i></a></dt>
<dd><p>Move a point over a given distance in a given direction and return the
new coordinates (in two dimensions only).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>Coordinates of the point to be moved</p></dd>
<dt>double <i class="arg">direction</i></dt>
<dd><p>Direction (in degrees; 0 is to the right, 90
upwards)</p></dd>
<dt>list <i class="arg">dist</i></dt>
<dd><p>Distance over which to move the point</p></dd>
</dl></dd>
<dt><a name="24"><b class="cmd">::math::geometry::lineSegmentsIntersect</b> <i class="arg">linesegment1</i> <i class="arg">linesegment2</i></a></dt>
<dd><p>Check if two line segments intersect or coincide. Returns 1 if that is
the case, 0 otherwise (in two dimensions only). If an endpoint of one segment lies on
the other segment (or is very close to the segment), they are considered to intersect</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">linesegment1</i></dt>
<dd><p>First line segment</p></dd>
<dt>list <i class="arg">linesegment2</i></dt>
<dd><p>Second line segment</p></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">::math::geometry::findLineSegmentIntersection</b> <i class="arg">linesegment1</i> <i class="arg">linesegment2</i></a></dt>
<dd><p>Find the intersection point of two line segments. Return the coordinates
or the keywords "coincident" or "none" if the line segments coincide or
have no points in common (in two dimensions only).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">linesegment1</i></dt>
<dd><p>First line segment</p></dd>
<dt>list <i class="arg">linesegment2</i></dt>
<dd><p>Second line segment</p></dd>
</dl></dd>
<dt><a name="26"><b class="cmd">::math::geometry::findLineIntersection</b> <i class="arg">line1</i> <i class="arg">line2</i></a></dt>
<dd><p>Find the intersection point of two (infinite) lines. Return the coordinates
or the keywords "coincident" or "none" if the lines coincide or
have no points in common (in two dimensions only).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">line1</i></dt>
<dd><p>First line</p></dd>
<dt>list <i class="arg">line2</i></dt>
<dd><p>Second line</p></dd>
</dl>
<p>See section <span class="sectref"><a href="#section3">References</a></span> for details on the algorithm and math behind it.</p></dd>
<dt><a name="27"><b class="cmd">::math::geometry::polylinesIntersect</b> <i class="arg">polyline1</i> <i class="arg">polyline2</i></a></dt>
<dd><p>Check if two polylines intersect or not (in two dimensions only).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyline1</i></dt>
<dd><p>First polyline</p></dd>
<dt>list <i class="arg">polyline2</i></dt>
<dd><p>Second polyline</p></dd>
</dl></dd>
<dt><a name="28"><b class="cmd">::math::geometry::polylinesBoundingIntersect</b> <i class="arg">polyline1</i> <i class="arg">polyline2</i> <i class="arg">granularity</i></a></dt>
<dd><p>Check whether two polylines intersect, but reduce
the correctness of the result to the given granularity.
Use this for faster, but weaker, intersection checking.</p>
<p>How it works:</p>
<p>Each polyline is split into a number of smaller polylines,
consisting of granularity points each. If a pair of those smaller
lines' bounding boxes intersect, then this procedure returns 1,
otherwise it returns 0.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyline1</i></dt>
<dd><p>First polyline</p></dd>
<dt>list <i class="arg">polyline2</i></dt>
<dd><p>Second polyline</p></dd>
<dt>int <i class="arg">granularity</i></dt>
<dd><p>Number of points in each part (<=1 means check
every edge)</p></dd>
</dl></dd>
<dt><a name="29"><b class="cmd">::math::geometry::intervalsOverlap</b> <i class="arg">y1</i> <i class="arg">y2</i> <i class="arg">y3</i> <i class="arg">y4</i> <i class="arg">strict</i></a></dt>
<dd><p>Check if two intervals overlap.</p>
<dl class="doctools_arguments">
<dt>double <i class="arg">y1,y2</i></dt>
<dd><p>Begin and end of first interval</p></dd>
<dt>double <i class="arg">y3,y4</i></dt>
<dd><p>Begin and end of second interval</p></dd>
<dt>logical <i class="arg">strict</i></dt>
<dd><p>Check for strict or non-strict overlap</p></dd>
</dl></dd>
<dt><a name="30"><b class="cmd">::math::geometry::rectanglesOverlap</b> <i class="arg">P1</i> <i class="arg">P2</i> <i class="arg">Q1</i> <i class="arg">Q2</i> <i class="arg">strict</i></a></dt>
<dd><p>Check if two rectangles overlap.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P1</i></dt>
<dd><p>upper-left corner of the first rectangle</p></dd>
<dt>list <i class="arg">P2</i></dt>
<dd><p>lower-right corner of the first rectangle</p></dd>
<dt>list <i class="arg">Q1</i></dt>
<dd><p>upper-left corner of the second rectangle</p></dd>
<dt>list <i class="arg">Q2</i></dt>
<dd><p>lower-right corner of the second rectangle</p></dd>
<dt>list <i class="arg">strict</i></dt>
<dd><p>choosing strict or non-strict interpretation</p></dd>
</dl></dd>
<dt><a name="31"><b class="cmd">::math::geometry::bbox</b> <i class="arg">polyline</i></a></dt>
<dd><p>Calculate the bounding box of a polyline. Returns a list of four
coordinates: the upper-left and the lower-right corner of the box.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyline</i></dt>
<dd><p>The polyline to be examined</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">::math::geometry::pointInsidePolygon</b> <i class="arg">P</i> <i class="arg">polyline</i></a></dt>
<dd><p>Determine if a point is completely inside a polygon. If the point
touches the polygon, then the point is not completely inside the
polygon.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>Coordinates of the point</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>The polyline to be examined</p></dd>
</dl></dd>
<dt><a name="33"><b class="cmd">::math::geometry::pointInsidePolygonAlt</b> <i class="arg">P</i> <i class="arg">polyline</i></a></dt>
<dd><p>Determine if a point is completely inside a polygon. If the point
touches the polygon, then the point is not completely inside the
polygon. <em>Note:</em> this alternative procedure uses the so-called
winding number to determine this. It handles self-intersecting polygons
in a "natural" way.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P</i></dt>
<dd><p>Coordinates of the point</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>The polyline to be examined</p></dd>
</dl></dd>
<dt><a name="34"><b class="cmd">::math::geometry::rectangleInsidePolygon</b> <i class="arg">P1</i> <i class="arg">P2</i> <i class="arg">polyline</i></a></dt>
<dd><p>Determine if a rectangle is completely inside a polygon. If polygon
touches the rectangle, then the rectangle is not complete inside the
polygon.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">P1</i></dt>
<dd><p>Upper-left corner of the rectangle</p></dd>
<dt>list <i class="arg">P2</i></dt>
<dd><p>Lower-right corner of the rectangle</p></dd>
<dt>list <i class="arg">polygon</i></dt>
<dd><p>The polygon in question</p></dd>
</dl></dd>
<dt><a name="35"><b class="cmd">::math::geometry::areaPolygon</b> <i class="arg">polygon</i></a></dt>
<dd><p>Calculate the area of a polygon.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polygon</i></dt>
<dd><p>The polygon in question</p></dd>
</dl></dd>
<dt><a name="36"><b class="cmd">::math::geometry::translate</b> <i class="arg">vector</i> <i class="arg">polyline</i></a></dt>
<dd><p>Translate a polyline over a given vector</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">vector</i></dt>
<dd><p>Translation vector</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>The polyline to be rotated</p></dd>
</dl></dd>
<dt><a name="37"><b class="cmd">::math::geometry::rotate</b> <i class="arg">angle</i> <i class="arg">polyline</i></a></dt>
<dd><p>Rotate a polyline over a given angle (degrees) around the origin</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">angle</i></dt>
<dd><p>Angle over which to rotate the polyline (degrees)</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>The polyline to be translated</p></dd>
</dl></dd>
<dt><a name="38"><b class="cmd">::math::geometry::reflect</b> <i class="arg">angle</i> <i class="arg">polyline</i></a></dt>
<dd><p>Reflect a polyline in a line through the origin at a given angle (degrees) to the x-axis</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">angle</i></dt>
<dd><p>Angle of the line of reflection (degrees)</p></dd>
<dt>list <i class="arg">polyline</i></dt>
<dd><p>The polyline to be reflected</p></dd>
</dl></dd>
<dt><a name="39"><b class="cmd">::math::geometry::degToRad</b> <i class="arg">angle</i></a></dt>
<dd><p>Convert from degrees to radians</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">angle</i></dt>
<dd><p>Angle in degrees</p></dd>
</dl></dd>
<dt><a name="40"><b class="cmd">::math::geometry::radToDeg</b> <i class="arg">angle</i></a></dt>
<dd><p>Convert from radians to degrees</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">angle</i></dt>
<dd><p>Angle in radians</p></dd>
</dl></dd>
<dt><a name="41"><b class="cmd">::math::geometry::circle</b> <i class="arg">centre</i> <i class="arg">radius</i></a></dt>
<dd><p>Convenience procedure to create a circle from a point and a radius.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">centre</i></dt>
<dd><p>Coordinates of the circle centre</p></dd>
<dt>list <i class="arg">radius</i></dt>
<dd><p>Radius of the circle</p></dd>
</dl></dd>
<dt><a name="42"><b class="cmd">::math::geometry::circleTwoPoints</b> <i class="arg">point1</i> <i class="arg">point2</i></a></dt>
<dd><p>Convenience procedure to create a circle from two points on its circumference
The centre is the point between the two given points, the radius is half the
distance between them.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">point1</i></dt>
<dd><p>First point</p></dd>
<dt>list <i class="arg">point2</i></dt>
<dd><p>Second point</p></dd>
</dl></dd>
<dt><a name="43"><b class="cmd">::math::geometry::pointInsideCircle</b> <i class="arg">point</i> <i class="arg">circle</i></a></dt>
<dd><p>Determine if the given point is inside the circle or on the circumference (1)
or outside (0).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">point</i></dt>
<dd><p>Point to be checked</p></dd>
<dt>list <i class="arg">circle</i></dt>
<dd><p>Circle that may or may not contain the point</p></dd>
</dl></dd>
<dt><a name="44"><b class="cmd">::math::geometry::lineIntersectsCircle</b> <i class="arg">line</i> <i class="arg">circle</i></a></dt>
<dd><p>Determine if the given line intersects the circle or touches it (1)
or does not (0).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">line</i></dt>
<dd><p>Line to be checked</p></dd>
<dt>list <i class="arg">circle</i></dt>
<dd><p>Circle that may or may not be intersected</p></dd>
</dl></dd>
<dt><a name="45"><b class="cmd">::math::geometry::lineSegmentIntersectsCircle</b> <i class="arg">segment</i> <i class="arg">circle</i></a></dt>
<dd><p>Determine if the given line segment intersects the circle or touches it (1)
or does not (0).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">segment</i></dt>
<dd><p>Line segment to be checked</p></dd>
<dt>list <i class="arg">circle</i></dt>
<dd><p>Circle that may or may not be intersected</p></dd>
</dl></dd>
<dt><a name="46"><b class="cmd">::math::geometry::intersectionLineWithCircle</b> <i class="arg">line</i> <i class="arg">circle</i></a></dt>
<dd><p>Determine the points at which the given line intersects the circle. There can
be zero, one or two points. (If the line touches the circle or is close to it,
then one point is returned. An arbitrary margin of 1.0e-10 times the radius
is used to determine this situation.)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">line</i></dt>
<dd><p>Line to be checked</p></dd>
<dt>list <i class="arg">circle</i></dt>
<dd><p>Circle that may or may not be intersected</p></dd>
</dl></dd>
<dt><a name="47"><b class="cmd">::math::geometry::intersectionCircleWithCircle</b> <i class="arg">circle1</i> <i class="arg">circle2</i></a></dt>
<dd><p>Determine the points at which the given two circles intersect. There can
be zero, one or two points. (If the two circles touch the circle or are very close,
then one point is returned. An arbitrary margin of 1.0e-10 times the mean of the radii of
the two circles is used to determine this situation.)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">circle1</i></dt>
<dd><p>First circle</p></dd>
<dt>list <i class="arg">circle2</i></dt>
<dd><p>Second circle</p></dd>
</dl></dd>
<dt><a name="48"><b class="cmd">::math::geometry::tangentLinesToCircle</b> <i class="arg">point</i> <i class="arg">circle</i></a></dt>
<dd><p>Determine the tangent lines from the given point to the circle. There can
be zero, one or two lines. (If the point is on the cirucmference or very close to
the circle, then one line is returned. An arbitrary margin of 1.0e-10 times the
radius of the circle is used to determine this situation.)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">point</i></dt>
<dd><p>Point in question</p></dd>
<dt>list <i class="arg">circle</i></dt>
<dd><p>Circle to which the tangent lines are to be determined</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http:/wiki.tcl.tk/12070">Polygon Intersection</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Line-line_intersection">http://en.wikipedia.org/wiki/Line-line_intersection</a></p></li>
<li><p><a href="http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/">http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/</a></p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: geometry</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#angle">angle</a>, <a href="../../../../index.html#distance">distance</a>, <a href="../../../../index.html#line">line</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#plane_geometry">plane geometry</a>, <a href="../../../../index.html#point">point</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2001 by Ideogramic ApS and other parties<br>
Copyright © 2010 by Andreas Kupries<br>
Copyright © 2010 by Kevin Kenny<br>
Copyright © 2018 by Arjen Markus</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/numtheory.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
<div class='fossil-doc' data-title='math::numtheory - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::numtheory(n) 1.1.1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::numtheory - Number Theory</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.5?</span></b></li>
<li>package require <b class="pkgname">math::numtheory <span class="opt">?1.1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">math::numtheory::isprime</b> <i class="arg">N</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#2"><b class="cmd">math::numtheory::firstNprimes</b> <i class="arg">N</i></a></li>
<li><a href="#3"><b class="cmd">math::numtheory::primesLowerThan</b> <i class="arg">N</i></a></li>
<li><a href="#4"><b class="cmd">math::numtheory::primeFactors</b> <i class="arg">N</i></a></li>
<li><a href="#5"><b class="cmd">math::numtheory::primesLowerThan</b> <i class="arg">N</i></a></li>
<li><a href="#6"><b class="cmd">math::numtheory::primeFactors</b> <i class="arg">N</i></a></li>
<li><a href="#7"><b class="cmd">math::numtheory::uniquePrimeFactors</b> <i class="arg">N</i></a></li>
<li><a href="#8"><b class="cmd">math::numtheory::factors</b> <i class="arg">N</i></a></li>
<li><a href="#9"><b class="cmd">math::numtheory::totient</b> <i class="arg">N</i></a></li>
<li><a href="#10"><b class="cmd">math::numtheory::moebius</b> <i class="arg">N</i></a></li>
<li><a href="#11"><b class="cmd">math::numtheory::legendre</b> <i class="arg">a</i> <i class="arg">p</i></a></li>
<li><a href="#12"><b class="cmd">math::numtheory::jacobi</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#13"><b class="cmd">math::numtheory::gcd</b> <i class="arg">m</i> <i class="arg">n</i></a></li>
<li><a href="#14"><b class="cmd">math::numtheory::lcm</b> <i class="arg">m</i> <i class="arg">n</i></a></li>
<li><a href="#15"><b class="cmd">math::numtheory::numberPrimesGauss</b> <i class="arg">N</i></a></li>
<li><a href="#16"><b class="cmd">math::numtheory::numberPrimesLegendre</b> <i class="arg">N</i></a></li>
<li><a href="#17"><b class="cmd">math::numtheory::numberPrimesLegendreModified</b> <i class="arg">N</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is for collecting various number-theoretic operations, with
a slight bias to prime numbers.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">math::numtheory::isprime</b> <i class="arg">N</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>The <b class="cmd">isprime</b> command tests whether the integer <i class="arg">N</i> is a
prime, returning a boolean true value for prime <i class="arg">N</i> and a
boolean false value for non-prime <i class="arg">N</i>. The formal definition of
'prime' used is the conventional, that the number being tested is
greater than 1 and only has trivial divisors.</p>
<p>To be precise, the return value is one of <b class="const">0</b> (if <i class="arg">N</i> is
definitely not a prime), <b class="const">1</b> (if <i class="arg">N</i> is definitely a
prime), and <b class="const">on</b> (if <i class="arg">N</i> is probably prime); the latter
two are both boolean true values. The case that an integer may be
classified as "probably prime" arises because the Miller-Rabin
algorithm used in the test implementation is basically probabilistic,
and may if we are unlucky fail to detect that a number is in fact
composite. Options may be used to select the risk of such
"false positives" in the test. <b class="const">1</b> is returned for "small"
<i class="arg">N</i> (which currently means <i class="arg">N</i> < 118670087467), where it is
known that no false positives are possible.</p>
<p>The only option currently defined is:</p>
<dl class="doctools_options">
<dt><b class="option">-randommr</b> <i class="arg">repetitions</i></dt>
<dd><p>which controls how many times the Miller-Rabin test should be
repeated with randomly chosen bases. Each repetition reduces the
probability of a false positive by a factor at least 4. The
default for <i class="arg">repetitions</i> is 4.</p></dd>
</dl>
<p>Unknown options are silently ignored.</p></dd>
<dt><a name="2"><b class="cmd">math::numtheory::firstNprimes</b> <i class="arg">N</i></a></dt>
<dd><p>Return the first N primes</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number of primes to return</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">math::numtheory::primesLowerThan</b> <i class="arg">N</i></a></dt>
<dd><p>Return the prime numbers lower/equal to N</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Maximum number to consider</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">math::numtheory::primeFactors</b> <i class="arg">N</i></a></dt>
<dd><p>Return a list of the prime numbers in the number N</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number to be factorised</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">math::numtheory::primesLowerThan</b> <i class="arg">N</i></a></dt>
<dd><p>Return the prime numbers lower/equal to N</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Maximum number to consider</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">math::numtheory::primeFactors</b> <i class="arg">N</i></a></dt>
<dd><p>Return a list of the prime numbers in the number N</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number to be factorised</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">math::numtheory::uniquePrimeFactors</b> <i class="arg">N</i></a></dt>
<dd><p>Return a list of the <em>unique</em> prime numbers in the number N</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number to be factorised</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">math::numtheory::factors</b> <i class="arg">N</i></a></dt>
<dd><p>Return a list of all <em>unique</em> factors in the number N, including 1 and N itself</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number to be factorised</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">math::numtheory::totient</b> <i class="arg">N</i></a></dt>
<dd><p>Evaluate the Euler totient function for the number N (number of numbers
relatively prime to N)</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number in question</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">math::numtheory::moebius</b> <i class="arg">N</i></a></dt>
<dd><p>Evaluate the Moebius function for the number N</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number in question</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">math::numtheory::legendre</b> <i class="arg">a</i> <i class="arg">p</i></a></dt>
<dd><p>Evaluate the Legendre symbol (a/p)</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">a</i> (in)</dt>
<dd><p>Upper number in the symbol</p></dd>
<dt>integer <i class="arg">p</i> (in)</dt>
<dd><p>Lower number in the symbol (must be non-zero)</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">math::numtheory::jacobi</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Evaluate the Jacobi symbol (a/b)</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">a</i> (in)</dt>
<dd><p>Upper number in the symbol</p></dd>
<dt>integer <i class="arg">b</i> (in)</dt>
<dd><p>Lower number in the symbol (must be odd)</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">math::numtheory::gcd</b> <i class="arg">m</i> <i class="arg">n</i></a></dt>
<dd><p>Return the greatest common divisor of <i class="term">m</i> and <i class="term">n</i></p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">m</i> (in)</dt>
<dd><p>First number</p></dd>
<dt>integer <i class="arg">n</i> (in)</dt>
<dd><p>Second number</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">math::numtheory::lcm</b> <i class="arg">m</i> <i class="arg">n</i></a></dt>
<dd><p>Return the lowest common multiple of <i class="term">m</i> and <i class="term">n</i></p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">m</i> (in)</dt>
<dd><p>First number</p></dd>
<dt>integer <i class="arg">n</i> (in)</dt>
<dd><p>Second number</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">math::numtheory::numberPrimesGauss</b> <i class="arg">N</i></a></dt>
<dd><p>Estimate the number of primes according the formula by Gauss.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number in question</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">math::numtheory::numberPrimesLegendre</b> <i class="arg">N</i></a></dt>
<dd><p>Estimate the number of primes according the formula by Legendre.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number in question</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">math::numtheory::numberPrimesLegendreModified</b> <i class="arg">N</i></a></dt>
<dd><p>Estimate the number of primes according the modified formula by Legendre.</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">N</i> (in)</dt>
<dd><p>Number in question</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: numtheory</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#number_theory">number theory</a>, <a href="../../../../index.html#prime">prime</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010 Lars Hellström <Lars dot Hellstrom at residenset dot net></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/optimize.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
|
<div class='fossil-doc' data-title='math::optimize - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::optimize(n) 1.0 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::optimize - Optimisation routines</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">NOTES</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">math::optimize <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::optimize::minimum</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">func</i> <i class="arg">maxerr</i></a></li>
<li><a href="#2"><b class="cmd">::math::optimize::maximum</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">func</i> <i class="arg">maxerr</i></a></li>
<li><a href="#3"><b class="cmd">::math::optimize::min_bound_1d</b> <i class="arg">func</i> <i class="arg">begin</i> <i class="arg">end</i> <span class="opt">?<b class="option">-relerror</b> <i class="arg">reltol</i>?</span> <span class="opt">?<b class="option">-abserror</b> <i class="arg">abstol</i>?</span> <span class="opt">?<b class="option">-maxiter</b> <i class="arg">maxiter</i>?</span> <span class="opt">?<b class="option">-trace</b> <i class="arg">traceflag</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::math::optimize::min_unbound_1d</b> <i class="arg">func</i> <i class="arg">begin</i> <i class="arg">end</i> <span class="opt">?<b class="option">-relerror</b> <i class="arg">reltol</i>?</span> <span class="opt">?<b class="option">-abserror</b> <i class="arg">abstol</i>?</span> <span class="opt">?<b class="option">-maxiter</b> <i class="arg">maxiter</i>?</span> <span class="opt">?<b class="option">-trace</b> <i class="arg">traceflag</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::math::optimize::solveLinearProgram</b> <i class="arg">objective</i> <i class="arg">constraints</i></a></li>
<li><a href="#6"><b class="cmd">::math::optimize::linearProgramMaximum</b> <i class="arg">objective</i> <i class="arg">result</i></a></li>
<li><a href="#7"><b class="cmd">::math::optimize::nelderMead</b> <i class="arg">objective</i> <i class="arg">xVector</i> <span class="opt">?<b class="option">-scale</b> <i class="arg">xScaleVector</i>?</span> <span class="opt">?<b class="option">-ftol</b> <i class="arg">epsilon</i>?</span> <span class="opt">?<b class="option">-maxiter</b> <i class="arg">count</i>?</span> <span class="opt">?<span class="opt">?-trace?</span> <i class="arg">flag</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements several optimisation algorithms:</p>
<ul class="doctools_itemized">
<li><p>Minimize or maximize a function over a given interval</p></li>
<li><p>Solve a linear program (maximize a linear function subject to linear
constraints)</p></li>
<li><p>Minimize a function of several variables given an initial guess for the
location of the minimum.</p></li>
</ul>
<p>The package is fully implemented in Tcl. No particular attention has
been paid to the accuracy of the calculations. Instead, the
algorithms have been used in a straightforward manner.</p>
<p>This document describes the procedures and explains their usage.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>This package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::optimize::minimum</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">func</i> <i class="arg">maxerr</i></a></dt>
<dd><p>Minimize the given (continuous) function by examining the values in the
given interval. The procedure determines the values at both ends and in the
centre of the interval and then constructs a new interval of 1/2 length
that includes the minimum. No guarantee is made that the <em>global</em>
minimum is found.</p>
<p>The procedure returns the "x" value for which the function is minimal.</p>
<p><em>This procedure has been deprecated - use min_bound_1d instead</em></p>
<p><i class="arg">begin</i> - Start of the interval</p>
<p><i class="arg">end</i> - End of the interval</p>
<p><i class="arg">func</i> - Name of the function to be minimized (a procedure taking
one argument).</p>
<p><i class="arg">maxerr</i> - Maximum relative error (defaults to 1.0e-4)</p></dd>
<dt><a name="2"><b class="cmd">::math::optimize::maximum</b> <i class="arg">begin</i> <i class="arg">end</i> <i class="arg">func</i> <i class="arg">maxerr</i></a></dt>
<dd><p>Maximize the given (continuous) function by examining the values in the
given interval. The procedure determines the values at both ends and in the
centre of the interval and then constructs a new interval of 1/2 length
that includes the maximum. No guarantee is made that the <em>global</em>
maximum is found.</p>
<p>The procedure returns the "x" value for which the function is maximal.</p>
<p><em>This procedure has been deprecated - use max_bound_1d instead</em></p>
<p><i class="arg">begin</i> - Start of the interval</p>
<p><i class="arg">end</i> - End of the interval</p>
<p><i class="arg">func</i> - Name of the function to be maximized (a procedure taking
one argument).</p>
<p><i class="arg">maxerr</i> - Maximum relative error (defaults to 1.0e-4)</p></dd>
<dt><a name="3"><b class="cmd">::math::optimize::min_bound_1d</b> <i class="arg">func</i> <i class="arg">begin</i> <i class="arg">end</i> <span class="opt">?<b class="option">-relerror</b> <i class="arg">reltol</i>?</span> <span class="opt">?<b class="option">-abserror</b> <i class="arg">abstol</i>?</span> <span class="opt">?<b class="option">-maxiter</b> <i class="arg">maxiter</i>?</span> <span class="opt">?<b class="option">-trace</b> <i class="arg">traceflag</i>?</span></a></dt>
<dd><p>Miminizes a function of one variable in the given interval. The procedure
uses Brent's method of parabolic interpolation, protected by golden-section
subdivisions if the interpolation is not converging. No guarantee is made
that a <em>global</em> minimum is found. The function to evaluate, <i class="arg">func</i>,
must be a single Tcl command; it will be evaluated with an abscissa appended
as the last argument.</p>
<p><i class="arg">x1</i> and <i class="arg">x2</i> are the two bounds of
the interval in which the minimum is to be found. They need not be in
increasing order.</p>
<p><i class="arg">reltol</i>, if specified, is the desired upper bound
on the relative error of the result; default is 1.0e-7. The given value
should never be smaller than the square root of the machine's floating point
precision, or else convergence is not guaranteed. <i class="arg">abstol</i>, if specified,
is the desired upper bound on the absolute error of the result; default
is 1.0e-10. Caution must be used with small values of <i class="arg">abstol</i> to
avoid overflow/underflow conditions; if the minimum is expected to lie
about a small but non-zero abscissa, you consider either shifting the
function or changing its length scale.</p>
<p><i class="arg">maxiter</i> may be used to constrain the number of function evaluations
to be performed; default is 100. If the command evaluates the function
more than <i class="arg">maxiter</i> times, it returns an error to the caller.</p>
<p><i class="arg">traceFlag</i> is a Boolean value. If true, it causes the command to
print a message on the standard output giving the abscissa and ordinate
at each function evaluation, together with an indication of what type
of interpolation was chosen. Default is 0 (no trace).</p></dd>
<dt><a name="4"><b class="cmd">::math::optimize::min_unbound_1d</b> <i class="arg">func</i> <i class="arg">begin</i> <i class="arg">end</i> <span class="opt">?<b class="option">-relerror</b> <i class="arg">reltol</i>?</span> <span class="opt">?<b class="option">-abserror</b> <i class="arg">abstol</i>?</span> <span class="opt">?<b class="option">-maxiter</b> <i class="arg">maxiter</i>?</span> <span class="opt">?<b class="option">-trace</b> <i class="arg">traceflag</i>?</span></a></dt>
<dd><p>Miminizes a function of one variable over the entire real number line.
The procedure uses parabolic extrapolation combined with golden-section
dilatation to search for a region where a minimum exists, followed by
Brent's method of parabolic interpolation, protected by golden-section
subdivisions if the interpolation is not converging. No guarantee is made
that a <em>global</em> minimum is found. The function to evaluate, <i class="arg">func</i>,
must be a single Tcl command; it will be evaluated with an abscissa appended
as the last argument.</p>
<p><i class="arg">x1</i> and <i class="arg">x2</i> are two initial guesses at where the minimum
may lie. <i class="arg">x1</i> is the starting point for the minimization, and
the difference between <i class="arg">x2</i> and <i class="arg">x1</i> is used as a hint at the
characteristic length scale of the problem.</p>
<p><i class="arg">reltol</i>, if specified, is the desired upper bound
on the relative error of the result; default is 1.0e-7. The given value
should never be smaller than the square root of the machine's floating point
precision, or else convergence is not guaranteed. <i class="arg">abstol</i>, if specified,
is the desired upper bound on the absolute error of the result; default
is 1.0e-10. Caution must be used with small values of <i class="arg">abstol</i> to
avoid overflow/underflow conditions; if the minimum is expected to lie
about a small but non-zero abscissa, you consider either shifting the
function or changing its length scale.</p>
<p><i class="arg">maxiter</i> may be used to constrain the number of function evaluations
to be performed; default is 100. If the command evaluates the function
more than <i class="arg">maxiter</i> times, it returns an error to the caller.</p>
<p><i class="arg">traceFlag</i> is a Boolean value. If true, it causes the command to
print a message on the standard output giving the abscissa and ordinate
at each function evaluation, together with an indication of what type
of interpolation was chosen. Default is 0 (no trace).</p></dd>
<dt><a name="5"><b class="cmd">::math::optimize::solveLinearProgram</b> <i class="arg">objective</i> <i class="arg">constraints</i></a></dt>
<dd><p>Solve a <em>linear program</em> in standard form using a straightforward
implementation of the Simplex algorithm. (In the explanation below: The
linear program has N constraints and M variables).</p>
<p>The procedure returns a list of M values, the values for which the
objective function is maximal or a single keyword if the linear program
is not feasible or unbounded (either "unfeasible" or "unbounded")</p>
<p><i class="arg">objective</i> - The M coefficients of the objective function</p>
<p><i class="arg">constraints</i> - Matrix of coefficients plus maximum values that
implement the linear constraints. It is expected to be a list of N lists
of M+1 numbers each, M coefficients and the maximum value.</p></dd>
<dt><a name="6"><b class="cmd">::math::optimize::linearProgramMaximum</b> <i class="arg">objective</i> <i class="arg">result</i></a></dt>
<dd><p>Convenience function to return the maximum for the solution found by the
solveLinearProgram procedure.</p>
<p><i class="arg">objective</i> - The M coefficients of the objective function</p>
<p><i class="arg">result</i> - The result as returned by solveLinearProgram</p></dd>
<dt><a name="7"><b class="cmd">::math::optimize::nelderMead</b> <i class="arg">objective</i> <i class="arg">xVector</i> <span class="opt">?<b class="option">-scale</b> <i class="arg">xScaleVector</i>?</span> <span class="opt">?<b class="option">-ftol</b> <i class="arg">epsilon</i>?</span> <span class="opt">?<b class="option">-maxiter</b> <i class="arg">count</i>?</span> <span class="opt">?<span class="opt">?-trace?</span> <i class="arg">flag</i>?</span></a></dt>
<dd><p>Minimizes, in unconstrained fashion, a function of several variable over all
of space. The function to evaluate, <i class="arg">objective</i>, must be a single Tcl
command. To it will be appended as many elements as appear in the initial guess at
the location of the minimum, passed in as a Tcl list, <i class="arg">xVector</i>.</p>
<p><i class="arg">xScaleVector</i> is an initial guess at the problem scale; the first
function evaluations will be made by varying the co-ordinates in <i class="arg">xVector</i>
by the amounts in <i class="arg">xScaleVector</i>. If <i class="arg">xScaleVector</i> is not supplied,
the co-ordinates will be varied by a factor of 1.0001 (if the co-ordinate
is non-zero) or by a constant 0.0001 (if the co-ordinate is zero).</p>
<p><i class="arg">epsilon</i> is the desired relative error in the value of the function
evaluated at the minimum. The default is 1.0e-7, which usually gives three
significant digits of accuracy in the values of the x's.</p>
<p>pp
<i class="arg">count</i> is a limit on the number of trips through the main loop of
the optimizer. The number of function evaluations may be several times
this number. If the optimizer fails to find a minimum to within <i class="arg">ftol</i>
in <i class="arg">maxiter</i> iterations, it returns its current best guess and an
error status. Default is to allow 500 iterations.</p>
<p><i class="arg">flag</i> is a flag that, if true, causes a line to be written to the
standard output for each evaluation of the objective function, giving
the arguments presented to the function and the value returned. Default is
false.</p>
<p>The <b class="cmd">nelderMead</b> procedure returns a list of alternating keywords and
values suitable for use with <b class="cmd">array set</b>. The meaning of the keywords is:</p>
<p><i class="arg">x</i> is the approximate location of the minimum.</p>
<p><i class="arg">y</i> is the value of the function at <i class="arg">x</i>.</p>
<p><i class="arg">yvec</i> is a vector of the best N+1 function values achieved, where
N is the dimension of <i class="arg">x</i></p>
<p><i class="arg">vertices</i> is a list of vectors giving the function arguments
corresponding to the values in <i class="arg">yvec</i>.</p>
<p><i class="arg">nIter</i> is the number of iterations required to achieve convergence or
fail.</p>
<p><i class="arg">status</i> is 'ok' if the operation succeeded, or 'too-many-iterations'
if the maximum iteration count was exceeded.</p>
<p><b class="cmd">nelderMead</b> minimizes the given function using the downhill
simplex method of Nelder and Mead. This method is quite slow - much
faster methods for minimization are known - but has the advantage of being
extremely robust in the face of problems where the minimum lies in
a valley of complex topology.</p>
<p><b class="cmd">nelderMead</b> can occasionally find itself "stuck" at a point where
it can make no further progress; it is recommended that the caller
run it at least a second time, passing as the initial guess the
result found by the previous call. The second run is usually very
fast.</p>
<p><b class="cmd">nelderMead</b> can be used in some cases for constrained optimization.
To do this, add a large value to the objective function if the parameters
are outside the feasible region. To work effectively in this mode,
<b class="cmd">nelderMead</b> requires that the initial guess be feasible and
usually requires that the feasible region be convex.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">NOTES</a></h2>
<p>Several of the above procedures take the <em>names</em> of procedures as
arguments. To avoid problems with the <em>visibility</em> of these
procedures, the fully-qualified name of these procedures is determined
inside the optimize routines. For the user this has only one
consequence: the named procedure must be visible in the calling
procedure. For instance:</p>
<pre class="doctools_example">
namespace eval ::mySpace {
namespace export calcfunc
proc calcfunc { x } { return $x }
}
#
# Use a fully-qualified name
#
namespace eval ::myCalc {
puts [min_bound_1d ::myCalc::calcfunc $begin $end]
}
#
# Import the name
#
namespace eval ::myCalc {
namespace import ::mySpace::calcfunc
puts [min_bound_1d calcfunc $begin $end]
}
</pre>
<p>The simple procedures <em>minimum</em> and <em>maximum</em> have been
deprecated: the alternatives are much more flexible, robust and
require less function evaluations.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<p>Let us take a few simple examples:</p>
<p>Determine the maximum of f(x) = x^3 exp(-3x), on the interval (0,10):</p>
<pre class="doctools_example">
proc efunc { x } { expr {$x*$x*$x * exp(-3.0*$x)} }
puts "Maximum at: [::math::optimize::max_bound_1d efunc 0.0 10.0]"
</pre>
<p>The maximum allowed error determines the number of steps taken (with
each step in the iteration the interval is reduced with a factor 1/2).
Hence, a maximum error of 0.0001 is achieved in approximately 14 steps.</p>
<p>An example of a <em>linear program</em> is:</p>
<p>Optimise the expression 3x+2y, where:</p>
<pre class="doctools_example">
x >= 0 and y >= 0 (implicit constraints, part of the
definition of linear programs)
x + y <= 1 (constraints specific to the problem)
2x + 5y <= 10
</pre>
<p>This problem can be solved as follows:</p>
<pre class="doctools_example">
set solution [::math::optimize::solveLinearProgram { 3.0 2.0 } { { 1.0 1.0 1.0 }
{ 2.0 5.0 10.0 } } ]
</pre>
<p>Note, that a constraint like:</p>
<pre class="doctools_example">
x + y >= 1
</pre>
<p>can be turned into standard form using:</p>
<pre class="doctools_example">
-x -y <= -1
</pre>
<p>The theory of linear programming is the subject of many a text book and
the Simplex algorithm that is implemented here is the best-known
method to solve this type of problems, but it is not the only one.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: optimize</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#linear_program">linear program</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#maximum">maximum</a>, <a href="../../../../index.html#minimum">minimum</a>, <a href="../../../../index.html#optimization">optimization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]><br>
Copyright © 2004,2005 Kevn B. Kenny <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/pca.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<div class='fossil-doc' data-title='math::PCA - Principal Components Analysis'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::PCA(n) 1.0 tcllib "Principal Components Analysis"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::PCA - Package for Principal Component Analysis</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.6?</span></b></li>
<li>package require <b class="pkgname">math::linearalgebra 1.0</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::PCA::createPCA</b> <i class="arg">data</i> <span class="opt">?args?</span></a></li>
<li><a href="#2"><b class="cmd">$pca using</b> <span class="opt">?number?</span>|<span class="opt">?-minproportion value?</span></a></li>
<li><a href="#3"><b class="cmd">$pca eigenvectors</b> <span class="opt">?option?</span></a></li>
<li><a href="#4"><b class="cmd">$pca eigenvalues</b> <span class="opt">?option?</span></a></li>
<li><a href="#5"><b class="cmd">$pca proportions</b> <span class="opt">?option?</span></a></li>
<li><a href="#6"><b class="cmd">$pca approximate</b> <i class="arg">observation</i></a></li>
<li><a href="#7"><b class="cmd">$pca approximatOriginal</b></a></li>
<li><a href="#8"><b class="cmd">$pca scores</b> <i class="arg">observation</i></a></li>
<li><a href="#9"><b class="cmd">$pca distance</b> <i class="arg">observation</i></a></li>
<li><a href="#10"><b class="cmd">$pca qstatistic</b> <i class="arg">observation</i> <span class="opt">?option?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The PCA package provides a means to perform principal components analysis
in Tcl, using an object-oriented technique as facilitated by TclOO. It
actually defines a single public method, <i class="term">::math::PCA::createPCA</i>,
which constructs an object based on the data that are passed to perform
the actual analysis.</p>
<p>The methods of the PCA objects that are created with this command allow one
to examine the principal components, to approximate (new) observations
using all or a selected number of components only and to examine the
properties of the components and the statistics of the approximations.</p>
<p>The package has been modelled after the PCA example provided by the
original linear algebra package by Ed Hume.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<p>The <i class="term">math::PCA</i> package provides one public command:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::PCA::createPCA</b> <i class="arg">data</i> <span class="opt">?args?</span></a></dt>
<dd><p>Create a new object, based on the data that are passed via the <i class="term">data</i> argument.
The principal components may be based on either correlations or covariances.
All observations will be normalised according to the mean and standard deviation
of the original data.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- A list of observations (see the example below).</p></dd>
<dt>list <i class="arg">args</i></dt>
<dd><p>- A list of key-value pairs defining the options. Currently there is
only one key: <i class="term">-covariances</i>. This indicates if covariances are to be used
(if the value is 1) or instead correlations (value is 0). The default is to use
correlations.</p></dd>
</dl></dd>
</dl>
<p>The PCA object that is created has the following methods:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">$pca using</b> <span class="opt">?number?</span>|<span class="opt">?-minproportion value?</span></a></dt>
<dd><p>Set the number of components to be used in the analysis (the number of retained components).
Returns the number of components, also if no argument is given.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">number</i></dt>
<dd><p>- The number of components to be retained</p></dd>
<dt>double <i class="arg">value</i></dt>
<dd><p>- Select the number of components based on the minimum proportion
of variation that is retained by them. Should be a value between 0 and 1.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">$pca eigenvectors</b> <span class="opt">?option?</span></a></dt>
<dd><p>Return the eigenvectors as a list of lists.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">option</i></dt>
<dd><p>- By default only the <em>retained</em> components are returned.
If all eigenvectors are required, use the option <i class="term">-all</i>.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">$pca eigenvalues</b> <span class="opt">?option?</span></a></dt>
<dd><p>Return the eigenvalues as a list of lists.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">option</i></dt>
<dd><p>- By default only the eigenvalues of the <em>retained</em> components are returned.
If all eigenvalues are required, use the option <i class="term">-all</i>.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">$pca proportions</b> <span class="opt">?option?</span></a></dt>
<dd><p>Return the proportions for all components, that is, the amount of variations that each
components can explain.</p></dd>
<dt><a name="6"><b class="cmd">$pca approximate</b> <i class="arg">observation</i></a></dt>
<dd><p>Return an approximation of the observation based on the retained components</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">observation</i></dt>
<dd><p>- The values for the observation.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">$pca approximatOriginal</b></a></dt>
<dd><p>Return an approximation of the original data, using the retained components. It is
a convenience method that works on the complete set of original data.</p></dd>
<dt><a name="8"><b class="cmd">$pca scores</b> <i class="arg">observation</i></a></dt>
<dd><p>Return the scores per retained component for the given observation.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">observation</i></dt>
<dd><p>- The values for the observation.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">$pca distance</b> <i class="arg">observation</i></a></dt>
<dd><p>Return the distance between the given observation and its approximation. (Note:
this distance is based on the normalised vectors.)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">observation</i></dt>
<dd><p>- The values for the observation.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">$pca qstatistic</b> <i class="arg">observation</i> <span class="opt">?option?</span></a></dt>
<dd><p>Return the Q statistic, basically the square of the distance, for the given observation.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">observation</i></dt>
<dd><p>- The values for the observation.</p></dd>
<dt>string <i class="arg">option</i></dt>
<dd><p>- If the observation is part of the original data, you may want
to use the corrected Q statistic. This is achieved with the option "-original".</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLE</a></h2>
<p>TODO: NIST example</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>PCA</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#pca">PCA</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#statistics">statistics</a>, <a href="../../../../index.html#tcl">tcl</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/polynomials.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
<div class='fossil-doc' data-title='math::polynomials - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::polynomials(n) 1.0.1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::polynomials - Polynomial functions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">REMARKS ON THE IMPLEMENTATION</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.3?</span></b></li>
<li>package require <b class="pkgname">math::polynomials <span class="opt">?1.0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::polynomials::polynomial</b> <i class="arg">coeffs</i></a></li>
<li><a href="#2"><b class="cmd">::math::polynomials::polynCmd</b> <i class="arg">coeffs</i></a></li>
<li><a href="#3"><b class="cmd">::math::polynomials::evalPolyn</b> <i class="arg">polynomial</i> <i class="arg">x</i></a></li>
<li><a href="#4"><b class="cmd">::math::polynomials::addPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></li>
<li><a href="#5"><b class="cmd">::math::polynomials::subPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></li>
<li><a href="#6"><b class="cmd">::math::polynomials::multPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></li>
<li><a href="#7"><b class="cmd">::math::polynomials::divPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></li>
<li><a href="#8"><b class="cmd">::math::polynomials::remainderPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></li>
<li><a href="#9"><b class="cmd">::math::polynomials::derivPolyn</b> <i class="arg">polyn</i></a></li>
<li><a href="#10"><b class="cmd">::math::polynomials::primitivePolyn</b> <i class="arg">polyn</i></a></li>
<li><a href="#11"><b class="cmd">::math::polynomials::degreePolyn</b> <i class="arg">polyn</i></a></li>
<li><a href="#12"><b class="cmd">::math::polynomials::coeffPolyn</b> <i class="arg">polyn</i> <i class="arg">index</i></a></li>
<li><a href="#13"><b class="cmd">::math::polynomials::allCoeffsPolyn</b> <i class="arg">polyn</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package deals with polynomial functions of one variable:</p>
<ul class="doctools_itemized">
<li><p>the basic arithmetic operations are extended to polynomials</p></li>
<li><p>computing the derivatives and primitives of these functions</p></li>
<li><p>evaluation through a general procedure or via specific procedures)</p></li>
</ul>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::polynomials::polynomial</b> <i class="arg">coeffs</i></a></dt>
<dd><p>Return an (encoded) list that defines the polynomial. A polynomial</p>
<pre class="doctools_example">
f(x) = a + b.x + c.x**2 + d.x**3
</pre>
<p>can be defined via:</p>
<pre class="doctools_example">
set f [::math::polynomials::polynomial [list $a $b $c $d]
</pre>
<dl class="doctools_arguments">
<dt>list <i class="arg">coeffs</i></dt>
<dd><p>Coefficients of the polynomial (in ascending
order)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::polynomials::polynCmd</b> <i class="arg">coeffs</i></a></dt>
<dd><p>Create a new procedure that evaluates the polynomial. The name of the
polynomial is automatically generated. Useful if you need to evualuate
the polynomial many times, as the procedure consists of a single
[expr] command.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">coeffs</i></dt>
<dd><p>Coefficients of the polynomial (in ascending
order) or the polynomial definition returned by the <em>polynomial</em>
command.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::polynomials::evalPolyn</b> <i class="arg">polynomial</i> <i class="arg">x</i></a></dt>
<dd><p>Evaluate the polynomial at x.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polynomial</i></dt>
<dd><p>The polynomial's definition (as returned by
the polynomial command).
order)</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>The coordinate at which to evaluate the polynomial</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::polynomials::addPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></dt>
<dd><p>Return a new polynomial which is the sum of the two others.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn1</i></dt>
<dd><p>The first polynomial operand</p></dd>
<dt>list <i class="arg">polyn2</i></dt>
<dd><p>The second polynomial operand</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::polynomials::subPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></dt>
<dd><p>Return a new polynomial which is the difference of the two others.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn1</i></dt>
<dd><p>The first polynomial operand</p></dd>
<dt>list <i class="arg">polyn2</i></dt>
<dd><p>The second polynomial operand</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::math::polynomials::multPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></dt>
<dd><p>Return a new polynomial which is the product of the two others. If one
of the arguments is a scalar value, the other polynomial is simply
scaled.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn1</i></dt>
<dd><p>The first polynomial operand or a scalar</p></dd>
<dt>list <i class="arg">polyn2</i></dt>
<dd><p>The second polynomial operand or a scalar</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::polynomials::divPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></dt>
<dd><p>Divide the first polynomial by the second polynomial and return the
result. The remainder is dropped</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn1</i></dt>
<dd><p>The first polynomial operand</p></dd>
<dt>list <i class="arg">polyn2</i></dt>
<dd><p>The second polynomial operand</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::polynomials::remainderPolyn</b> <i class="arg">polyn1</i> <i class="arg">polyn2</i></a></dt>
<dd><p>Divide the first polynomial by the second polynomial and return the
remainder.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn1</i></dt>
<dd><p>The first polynomial operand</p></dd>
<dt>list <i class="arg">polyn2</i></dt>
<dd><p>The second polynomial operand</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::polynomials::derivPolyn</b> <i class="arg">polyn</i></a></dt>
<dd><p>Differentiate the polynomial and return the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn</i></dt>
<dd><p>The polynomial to be differentiated</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::polynomials::primitivePolyn</b> <i class="arg">polyn</i></a></dt>
<dd><p>Integrate the polynomial and return the result. The integration
constant is set to zero.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn</i></dt>
<dd><p>The polynomial to be integrated</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::polynomials::degreePolyn</b> <i class="arg">polyn</i></a></dt>
<dd><p>Return the degree of the polynomial.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn</i></dt>
<dd><p>The polynomial to be examined</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::math::polynomials::coeffPolyn</b> <i class="arg">polyn</i> <i class="arg">index</i></a></dt>
<dd><p>Return the coefficient of the term of the index'th degree of the
polynomial.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn</i></dt>
<dd><p>The polynomial to be examined</p></dd>
<dt>int <i class="arg">index</i></dt>
<dd><p>The degree of the term</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::polynomials::allCoeffsPolyn</b> <i class="arg">polyn</i></a></dt>
<dd><p>Return the coefficients of the polynomial (in ascending order).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">polyn</i></dt>
<dd><p>The polynomial in question</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">REMARKS ON THE IMPLEMENTATION</a></h2>
<p>The implementation for evaluating the polynomials at some point uses
Horn's rule, which guarantees numerical stability and a minimum of
arithmetic operations.
To recognise that a polynomial definition is indeed a correct
definition, it consists of a list of two elements: the keyword
"POLYNOMIAL" and the list of coefficients in descending order. The
latter makes it easier to implement Horner's rule.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: polynomials</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#polynomial_functions">polynomial functions</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/qcomplex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<div class='fossil-doc' data-title='math::complexnumbers - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::complexnumbers(n) 1.0.2 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::complexnumbers - Straightforward complex number package</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">AVAILABLE PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">math::complexnumbers <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::complexnumbers::+</b> <i class="arg">z1</i> <i class="arg">z2</i></a></li>
<li><a href="#2"><b class="cmd">::math::complexnumbers::-</b> <i class="arg">z1</i> <i class="arg">z2</i></a></li>
<li><a href="#3"><b class="cmd">::math::complexnumbers::*</b> <i class="arg">z1</i> <i class="arg">z2</i></a></li>
<li><a href="#4"><b class="cmd">::math::complexnumbers::/</b> <i class="arg">z1</i> <i class="arg">z2</i></a></li>
<li><a href="#5"><b class="cmd">::math::complexnumbers::conj</b> <i class="arg">z1</i></a></li>
<li><a href="#6"><b class="cmd">::math::complexnumbers::real</b> <i class="arg">z1</i></a></li>
<li><a href="#7"><b class="cmd">::math::complexnumbers::imag</b> <i class="arg">z1</i></a></li>
<li><a href="#8"><b class="cmd">::math::complexnumbers::mod</b> <i class="arg">z1</i></a></li>
<li><a href="#9"><b class="cmd">::math::complexnumbers::arg</b> <i class="arg">z1</i></a></li>
<li><a href="#10"><b class="cmd">::math::complexnumbers::complex</b> <i class="arg">real</i> <i class="arg">imag</i></a></li>
<li><a href="#11"><b class="cmd">::math::complexnumbers::tostring</b> <i class="arg">z1</i></a></li>
<li><a href="#12"><b class="cmd">::math::complexnumbers::exp</b> <i class="arg">z1</i></a></li>
<li><a href="#13"><b class="cmd">::math::complexnumbers::sin</b> <i class="arg">z1</i></a></li>
<li><a href="#14"><b class="cmd">::math::complexnumbers::cos</b> <i class="arg">z1</i></a></li>
<li><a href="#15"><b class="cmd">::math::complexnumbers::tan</b> <i class="arg">z1</i></a></li>
<li><a href="#16"><b class="cmd">::math::complexnumbers::log</b> <i class="arg">z1</i></a></li>
<li><a href="#17"><b class="cmd">::math::complexnumbers::sqrt</b> <i class="arg">z1</i></a></li>
<li><a href="#18"><b class="cmd">::math::complexnumbers::pow</b> <i class="arg">z1</i> <i class="arg">z2</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The mathematical module <em>complexnumbers</em> provides a straightforward
implementation of complex numbers in pure Tcl. The philosophy is that
the user knows he or she is dealing with complex numbers in an abstract
way and wants as high a performance as can be had within the limitations
of an interpreted language.</p>
<p>Therefore the procedures defined in this package assume that the
arguments are valid (representations of) "complex numbers", that is,
lists of two numbers defining the real and imaginary part of a
complex number (though this is a mere detail: rely on the
<em>complex</em> command to construct a valid number.)</p>
<p>Most procedures implement the basic arithmetic operations or elementary
functions whereas several others convert to and from different
representations:</p>
<pre class="doctools_example">
set z [complex 0 1]
puts "z = [tostring $z]"
puts "z**2 = [* $z $z]
</pre>
<p>would result in:</p>
<pre class="doctools_example">
z = i
z**2 = -1
</pre>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">AVAILABLE PROCEDURES</a></h2>
<p>The package implements all or most basic operations and elementary
functions.</p>
<p><em>The arithmetic operations are:</em></p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::complexnumbers::+</b> <i class="arg">z1</i> <i class="arg">z2</i></a></dt>
<dd><p>Add the two arguments and return the resulting complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>First argument in the summation</p></dd>
<dt>complex <i class="arg">z2</i> (in)</dt>
<dd><p>Second argument in the summation</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::complexnumbers::-</b> <i class="arg">z1</i> <i class="arg">z2</i></a></dt>
<dd><p>Subtract the second argument from the first and return the
resulting complex number. If there is only one argument, the
opposite of z1 is returned (i.e. -z1)</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>First argument in the subtraction</p></dd>
<dt>complex <i class="arg">z2</i> (in)</dt>
<dd><p>Second argument in the subtraction (optional)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::complexnumbers::*</b> <i class="arg">z1</i> <i class="arg">z2</i></a></dt>
<dd><p>Multiply the two arguments and return the resulting complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>First argument in the multiplication</p></dd>
<dt>complex <i class="arg">z2</i> (in)</dt>
<dd><p>Second argument in the multiplication</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::complexnumbers::/</b> <i class="arg">z1</i> <i class="arg">z2</i></a></dt>
<dd><p>Divide the first argument by the second and return the resulting complex
number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>First argument (numerator) in the division</p></dd>
<dt>complex <i class="arg">z2</i> (in)</dt>
<dd><p>Second argument (denominator) in the division</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::complexnumbers::conj</b> <i class="arg">z1</i></a></dt>
<dd><p>Return the conjugate of the given complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>Complex number in question</p></dd>
</dl></dd>
</dl>
<p><em>Conversion/inquiry procedures:</em></p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="cmd">::math::complexnumbers::real</b> <i class="arg">z1</i></a></dt>
<dd><p>Return the real part of the given complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>Complex number in question</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::complexnumbers::imag</b> <i class="arg">z1</i></a></dt>
<dd><p>Return the imaginary part of the given complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>Complex number in question</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::complexnumbers::mod</b> <i class="arg">z1</i></a></dt>
<dd><p>Return the modulus of the given complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>Complex number in question</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::complexnumbers::arg</b> <i class="arg">z1</i></a></dt>
<dd><p>Return the argument ("angle" in radians) of the given complex number</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>Complex number in question</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::complexnumbers::complex</b> <i class="arg">real</i> <i class="arg">imag</i></a></dt>
<dd><p>Construct the complex number "real + imag*i" and return it</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">real</i> (in)</dt>
<dd><p>The real part of the new complex number</p></dd>
<dt>float <i class="arg">imag</i> (in)</dt>
<dd><p>The imaginary part of the new complex number</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::complexnumbers::tostring</b> <i class="arg">z1</i></a></dt>
<dd><p>Convert the complex number to the form "real + imag*i" and return the
string</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">complex</i> (in)</dt>
<dd><p>The complex number to be converted</p></dd>
</dl></dd>
</dl>
<p><em>Elementary functions:</em></p>
<dl class="doctools_definitions">
<dt><a name="12"><b class="cmd">::math::complexnumbers::exp</b> <i class="arg">z1</i></a></dt>
<dd><p>Calculate the exponential for the given complex argument and return the
result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex argument for the function</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::complexnumbers::sin</b> <i class="arg">z1</i></a></dt>
<dd><p>Calculate the sine function for the given complex argument and return
the result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex argument for the function</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::math::complexnumbers::cos</b> <i class="arg">z1</i></a></dt>
<dd><p>Calculate the cosine function for the given complex argument and return
the result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex argument for the function</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::complexnumbers::tan</b> <i class="arg">z1</i></a></dt>
<dd><p>Calculate the tangent function for the given complex argument and
return the result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex argument for the function</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::complexnumbers::log</b> <i class="arg">z1</i></a></dt>
<dd><p>Calculate the (principle value of the) logarithm for the given complex
argument and return the result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex argument for the function</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">::math::complexnumbers::sqrt</b> <i class="arg">z1</i></a></dt>
<dd><p>Calculate the (principle value of the) square root for the given complex
argument and return the result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex argument for the function</p></dd>
</dl></dd>
<dt><a name="18"><b class="cmd">::math::complexnumbers::pow</b> <i class="arg">z1</i> <i class="arg">z2</i></a></dt>
<dd><p>Calculate "z1 to the power of z2" and return the result</p>
<dl class="doctools_arguments">
<dt>complex <i class="arg">z1</i> (in)</dt>
<dd><p>The complex number to be raised to a power</p></dd>
<dt>complex <i class="arg">z2</i> (in)</dt>
<dd><p>The complex power to be used</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: complexnumbers</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#complex_numbers">complex numbers</a>, <a href="../../../../index.html#math">math</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/rational_funcs.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
<div class='fossil-doc' data-title='math::rationalfunctions - Math'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::rationalfunctions(n) 1.0.1 tcllib "Math"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::rationalfunctions - Polynomial functions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">REMARKS ON THE IMPLEMENTATION</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">math::rationalfunctions <span class="opt">?1.0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::rationalfunctions::rationalFunction</b> <i class="arg">num</i> <i class="arg">den</i></a></li>
<li><a href="#2"><b class="cmd">::math::rationalfunctions::ratioCmd</b> <i class="arg">num</i> <i class="arg">den</i></a></li>
<li><a href="#3"><b class="cmd">::math::rationalfunctions::evalRatio</b> <i class="arg">rational</i> <i class="arg">x</i></a></li>
<li><a href="#4"><b class="cmd">::math::rationalfunctions::addRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></li>
<li><a href="#5"><b class="cmd">::math::rationalfunctions::subRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></li>
<li><a href="#6"><b class="cmd">::math::rationalfunctions::multRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></li>
<li><a href="#7"><b class="cmd">::math::rationalfunctions::divRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></li>
<li><a href="#8"><b class="cmd">::math::rationalfunctions::derivPolyn</b> <i class="arg">ratio</i></a></li>
<li><a href="#9"><b class="cmd">::math::rationalfunctions::coeffsNumerator</b> <i class="arg">ratio</i></a></li>
<li><a href="#10"><b class="cmd">::math::rationalfunctions::coeffsDenominator</b> <i class="arg">ratio</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package deals with rational functions of one variable:</p>
<ul class="doctools_itemized">
<li><p>the basic arithmetic operations are extended to rational functions</p></li>
<li><p>computing the derivatives of these functions</p></li>
<li><p>evaluation through a general procedure or via specific procedures)</p></li>
</ul>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::rationalfunctions::rationalFunction</b> <i class="arg">num</i> <i class="arg">den</i></a></dt>
<dd><p>Return an (encoded) list that defines the rational function. A
rational function</p>
<pre class="doctools_example">
1 + x^3
f(x) = ------------
1 + 2x + x^2
</pre>
<p>can be defined via:</p>
<pre class="doctools_example">
set f [::math::rationalfunctions::rationalFunction [list 1 0 0 1] [list 1 2 1]]
</pre>
<dl class="doctools_arguments">
<dt>list <i class="arg">num</i></dt>
<dd><p>Coefficients of the numerator of the rational
function (in ascending order)</p></dd>
<dt>list <i class="arg">den</i></dt>
<dd><p>Coefficients of the denominator of the rational
function (in ascending order)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::rationalfunctions::ratioCmd</b> <i class="arg">num</i> <i class="arg">den</i></a></dt>
<dd><p>Create a new procedure that evaluates the rational function. The name of the
function is automatically generated. Useful if you need to evaluate
the function many times, as the procedure consists of a single
[expr] command.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">num</i></dt>
<dd><p>Coefficients of the numerator of the rational
function (in ascending order)</p></dd>
<dt>list <i class="arg">den</i></dt>
<dd><p>Coefficients of the denominator of the rational
function (in ascending order)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::rationalfunctions::evalRatio</b> <i class="arg">rational</i> <i class="arg">x</i></a></dt>
<dd><p>Evaluate the rational function at x.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">rational</i></dt>
<dd><p>The rational function's definition (as returned
by the rationalFunction command).
order)</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>The coordinate at which to evaluate the function</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::rationalfunctions::addRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></dt>
<dd><p>Return a new rational function which is the sum of the two others.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio1</i></dt>
<dd><p>The first rational function operand</p></dd>
<dt>list <i class="arg">ratio2</i></dt>
<dd><p>The second rational function operand</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::rationalfunctions::subRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></dt>
<dd><p>Return a new rational function which is the difference of the two
others.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio1</i></dt>
<dd><p>The first rational function operand</p></dd>
<dt>list <i class="arg">ratio2</i></dt>
<dd><p>The second rational function operand</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::math::rationalfunctions::multRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></dt>
<dd><p>Return a new rational function which is the product of the two others.
If one of the arguments is a scalar value, the other rational function is
simply scaled.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio1</i></dt>
<dd><p>The first rational function operand or a scalar</p></dd>
<dt>list <i class="arg">ratio2</i></dt>
<dd><p>The second rational function operand or a scalar</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::rationalfunctions::divRatio</b> <i class="arg">ratio1</i> <i class="arg">ratio2</i></a></dt>
<dd><p>Divide the first rational function by the second rational function and
return the result. The remainder is dropped</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio1</i></dt>
<dd><p>The first rational function operand</p></dd>
<dt>list <i class="arg">ratio2</i></dt>
<dd><p>The second rational function operand</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::rationalfunctions::derivPolyn</b> <i class="arg">ratio</i></a></dt>
<dd><p>Differentiate the rational function and return the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio</i></dt>
<dd><p>The rational function to be differentiated</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::rationalfunctions::coeffsNumerator</b> <i class="arg">ratio</i></a></dt>
<dd><p>Return the coefficients of the numerator of the rational function.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio</i></dt>
<dd><p>The rational function to be examined</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::rationalfunctions::coeffsDenominator</b> <i class="arg">ratio</i></a></dt>
<dd><p>Return the coefficients of the denominator of the rational
function.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">ratio</i></dt>
<dd><p>The rational function to be examined</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">REMARKS ON THE IMPLEMENTATION</a></h2>
<p>The implementation of the rational functions relies on the
math::polynomials package. For further remarks see the documentation on
that package.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: rationalfunctions</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#rational_functions">rational functions</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/roman.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<div class='fossil-doc' data-title='math::roman - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::roman() 1.0 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::roman - Tools for creating and manipulating roman numerals</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">math::roman <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::roman::toroman</b> <i class="arg">i</i></a></li>
<li><a href="#2"><b class="cmd">::math::roman::tointeger</b> <i class="arg">r</i></a></li>
<li><a href="#3"><b class="cmd">::math::roman::sort</b> <i class="arg">list</i></a></li>
<li><a href="#4"><b class="cmd">::math::roman::expr</b> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><b class="cmd">::math::roman</b> is a pure-Tcl library for converting between integers
and roman numerals. It also provides utility functions for sorting and performing
arithmetic on roman numerals.</p>
<p>This code was originally harvested from the Tcler's wiki at
http://wiki.tcl.tk/1823 and as such is free for any use for
any purpose. Many thanks to the ingeneous folk who devised
these clever routines and generously contributed them to the
Tcl community.</p>
<p>While written and tested under Tcl 8.3, I expect this library
will work under all 8.x versions of Tcl.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::roman::toroman</b> <i class="arg">i</i></a></dt>
<dd><p>Convert an integer to roman numerals. The result is always in
upper case. The value zero is converted to an empty string.</p></dd>
<dt><a name="2"><b class="cmd">::math::roman::tointeger</b> <i class="arg">r</i></a></dt>
<dd><p>Convert a roman numeral into an integer.</p></dd>
<dt><a name="3"><b class="cmd">::math::roman::sort</b> <i class="arg">list</i></a></dt>
<dd><p>Sort a list of roman numerals from smallest to largest.</p></dd>
<dt><a name="4"><b class="cmd">::math::roman::expr</b> <i class="arg">args</i></a></dt>
<dd><p>Evaluate an expression where the operands are all roman numerals.</p></dd>
</dl>
<p>Of these commands both <em>toroman</em> and <em>tointeger</em> are exported
for easier use. The other two are not, as they could interfer or be
confused with existing Tcl commands.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: roman</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#integer">integer</a>, <a href="../../../../index.html#roman_numeral">roman numeral</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Kenneth Green <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/romberg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
|
<div class='fossil-doc' data-title='math::calculus::romberg - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::calculus::romberg(n) 0.6 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::calculus::romberg - Romberg integration</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">PARAMETERS</a></li>
<li class="doctools_section"><a href="#section4">OPTIONS</a></li>
<li class="doctools_section"><a href="#section5">DESCRIPTION</a></li>
<li class="doctools_section"><a href="#section6">IMPROPER INTEGRALS</a></li>
<li class="doctools_section"><a href="#section7">OTHER CHANGES OF VARIABLE</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">math::calculus 0.6</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::calculus::romberg</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::math::calculus::romberg_infinity</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">::math::calculus::romberg_sqrtSingLower</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#4"><b class="cmd">::math::calculus::romberg_sqrtSingUpper</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#5"><b class="cmd">::math::calculus::romberg_powerLawLower</b> <i class="arg">gamma</i> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#6"><b class="cmd">::math::calculus::romberg_powerLawUpper</b> <i class="arg">gamma</i> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#7"><b class="cmd">::math::calculus::romberg_expLower</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
<li><a href="#8"><b class="cmd">::math::calculus::romberg_expUpper</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">romberg</b> procedures in the <b class="cmd"><a href="calculus.html">math::calculus</a></b> package
perform numerical integration of a function of one variable. They
are intended to be of "production quality" in that they are robust,
precise, and reasonably efficient in terms of the number of function
evaluations.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The following procedures are available for Romberg integration:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::calculus::romberg</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates an analytic function over a given interval.</p></dd>
<dt><a name="2"><b class="cmd">::math::calculus::romberg_infinity</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates an analytic function over a half-infinite interval.</p></dd>
<dt><a name="3"><b class="cmd">::math::calculus::romberg_sqrtSingLower</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates a function that is expected to be analytic over an interval
except for the presence of an inverse square root singularity at the
lower limit.</p></dd>
<dt><a name="4"><b class="cmd">::math::calculus::romberg_sqrtSingUpper</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates a function that is expected to be analytic over an interval
except for the presence of an inverse square root singularity at the
upper limit.</p></dd>
<dt><a name="5"><b class="cmd">::math::calculus::romberg_powerLawLower</b> <i class="arg">gamma</i> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates a function that is expected to be analytic over an interval
except for the presence of a power law singularity at the
lower limit.</p></dd>
<dt><a name="6"><b class="cmd">::math::calculus::romberg_powerLawUpper</b> <i class="arg">gamma</i> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates a function that is expected to be analytic over an interval
except for the presence of a power law singularity at the
upper limit.</p></dd>
<dt><a name="7"><b class="cmd">::math::calculus::romberg_expLower</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates an exponentially growing function; the lower limit of the
region of integration may be arbitrarily large and negative.</p></dd>
<dt><a name="8"><b class="cmd">::math::calculus::romberg_expUpper</b> <i class="arg">f</i> <i class="arg">a</i> <i class="arg">b</i> <span class="opt">?<i class="arg">-option value</i>...?</span></a></dt>
<dd><p>Integrates an exponentially decaying function; the upper limit of the
region of integration may be arbitrarily large.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PARAMETERS</a></h2>
<dl class="doctools_definitions">
<dt><i class="arg">f</i></dt>
<dd><p>Function to integrate. Must be expressed as a single Tcl command,
to which will be appended a single argument, specifically, the
abscissa at which the function is to be evaluated. The first word
of the command will be processed with <b class="cmd">namespace which</b> in the
caller's scope prior to any evaluation. Given this processing, the
command may local to the calling namespace rather than needing to be
global.</p></dd>
<dt><i class="arg">a</i></dt>
<dd><p>Lower limit of the region of integration.</p></dd>
<dt><i class="arg">b</i></dt>
<dd><p>Upper limit of the region of integration. For the
<b class="cmd">romberg_sqrtSingLower</b>, <b class="cmd">romberg_sqrtSingUpper</b>,
<b class="cmd">romberg_powerLawLower</b>, <b class="cmd">romberg_powerLawUpper</b>,
<b class="cmd">romberg_expLower</b>, and <b class="cmd">romberg_expUpper</b> procedures,
the lower limit must be strictly less than the upper. For
the other procedures, the limits may appear in either order.</p></dd>
<dt><i class="arg">gamma</i></dt>
<dd><p>Power to use for a power law singularity; see section
<span class="sectref"><a href="#section6">IMPROPER INTEGRALS</a></span> for details.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt><b class="option">-abserror</b> <i class="arg">epsilon</i></dt>
<dd><p>Requests that the integration machinery proceed at most until
the estimated absolute error of the integral is less than
<i class="arg">epsilon</i>. The error may be seriously over- or underestimated
if the function (or any of its derivatives) contains singularities;
see section <span class="sectref"><a href="#section6">IMPROPER INTEGRALS</a></span> for details. Default
is 1.0e-08.</p></dd>
<dt><b class="option">-relerror</b> <i class="arg">epsilon</i></dt>
<dd><p>Requests that the integration machinery proceed at most until
the estimated relative error of the integral is less than
<i class="arg">epsilon</i>. The error may be seriously over- or underestimated
if the function (or any of its derivatives) contains singularities;
see section <span class="sectref"><a href="#section6">IMPROPER INTEGRALS</a></span> for details. Default is
1.0e-06.</p></dd>
<dt><b class="option">-maxiter</b> <i class="arg">m</i></dt>
<dd><p>Requests that integration terminate after at most <i class="arg">n</i> triplings of
the number of evaluations performed. In other words, given <i class="arg">n</i>
for <b class="option">-maxiter</b>, the integration machinery will make at most
3**<i class="arg">n</i> evaluations of the function. Default is 14, corresponding
to a limit approximately 4.8 million evaluations. (Well-behaved
functions will seldom require more than a few hundred evaluations.)</p></dd>
<dt><b class="option">-degree</b> <i class="arg">d</i></dt>
<dd><p>Requests that an extrapolating polynomial of degree <i class="arg">d</i> be used
in Romberg integration; see section <span class="sectref"><a href="#section5">DESCRIPTION</a></span> for
details. Default is 4. Can be at most <i class="arg">m</i>-1.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">DESCRIPTION</a></h2>
<p>The <b class="cmd">romberg</b> procedure performs Romberg integration using
the modified midpoint rule. Romberg integration is an iterative
process. At the first step, the function is evaluated at the
midpoint of the region of integration, and the value is multiplied by
the width of the interval for the coarsest possible estimate.
At the second step, the interval is divided into three parts,
and the function is evaluated at the midpoint of each part; the
sum of the values is multiplied by three. At the third step,
nine parts are used, at the fourth twenty-seven, and so on,
tripling the number of subdivisions at each step.</p>
<p>Once the interval has been divided at least <i class="arg">d</i> times,
a polynomial is fitted to the integrals estimated in the last
<i class="arg">d</i>+1 divisions. The integrals are considered to be a
function of the square of the width of the subintervals
(any good numerical analysis text will discuss this process
under "Romberg integration"). The polynomial is extrapolated
to a step size of zero, computing a value for the integral and
an estimate of the error.</p>
<p>This process will be well-behaved only if the function is analytic
over the region of integration; there may be removable singularities
at either end of the region provided that the limit of the function
(and of all its derivatives) exists as the ends are approached.
Thus, <b class="cmd">romberg</b> may be used to integrate a function like
f(x)=sin(x)/x over an interval beginning or ending at zero.</p>
<p>Note that <b class="cmd">romberg</b> will either fail to converge or else return
incorrect error estimates if the function, or any of its derivatives,
has a singularity anywhere in the region of integration (except for
the case mentioned above). Care must be used, therefore, in
integrating a function like 1/(1-x**2) to avoid the places
where the derivative is singular.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">IMPROPER INTEGRALS</a></h2>
<p>Romberg integration is also useful for integrating functions over
half-infinite intervals or functions that have singularities.
The trick is to make a change of variable to eliminate the
singularity, and to put the singularity at one end or the other
of the region of integration. The <b class="cmd"><a href="calculus.html">math::calculus</a></b> package
supplies a number of <b class="cmd">romberg</b> procedures to deal with the
commoner cases.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">romberg_infinity</b></dt>
<dd><p>Integrates a function over a half-infinite interval; either
<i class="arg">a</i> or <i class="arg">b</i> may be infinite. <i class="arg">a</i> and <i class="arg">b</i> must be
of the same sign; if you need to integrate across the axis,
say, from a negative value to positive infinity,
use <b class="cmd">romberg</b> to integrate from the negative
value to a small positive value, and then <b class="cmd">romberg_infinity</b>
to integrate from the positive value to positive infinity. The
<b class="cmd">romberg_infinity</b> procedure works by making the change of
variable u=1/x, so that the integral from a to b of f(x) is
evaluated as the integral from 1/a to 1/b of f(1/u)/u**2.</p></dd>
<dt><b class="cmd">romberg_powerLawLower</b> and <b class="cmd">romberg_powerLawUpper</b></dt>
<dd><p>Integrate a function that has an integrable power law singularity
at either the lower or upper bound of the region of integration
(or has a derivative with a power law singularity there).
These procedures take a first parameter, <i class="arg">gamma</i>, which gives
the power law. The function or its first derivative are presumed to diverge as
(x-<i class="arg">a</i>)**(-<i class="arg">gamma</i>) or (<i class="arg">b</i>-x)**(-<i class="arg">gamma</i>). <i class="arg">gamma</i>
must be greater than zero and less than 1.</p>
<p>These procedures are useful not only in integrating functions
that go to infinity at one end of the region of integration, but
also functions whose derivatives do not exist at the end of
the region. For instance, integrating f(x)=pow(x,0.25) with the
origin as one end of the region will result in the <b class="cmd">romberg</b>
procedure greatly underestimating the error in the integral.
The problem can be fixed by observing that the first derivative
of f(x), f'(x)=x**(-3/4)/4, goes to infinity at the origin. Integrating
using <b class="cmd">romberg_powerLawLower</b> with <i class="arg">gamma</i> set to 0.75
gives much more orderly convergence.</p>
<p>These procedures operate by making the change of variable
u=(x-a)**(1-gamma) (<b class="cmd">romberg_powerLawLower</b>) or
u=(b-x)**(1-gamma) (<b class="cmd">romberg_powerLawUpper</b>).</p>
<p>To summarize the meaning of gamma:</p>
<ul class="doctools_itemized">
<li><p>If f(x) ~ x**(-a) (0 < a < 1), use gamma = a</p></li>
<li><p>If f'(x) ~ x**(-b) (0 < b < 1), use gamma = b</p></li>
</ul></dd>
<dt><b class="cmd">romberg_sqrtSingLower</b> and <b class="cmd">romberg_sqrtSingUpper</b></dt>
<dd><p>These procedures behave identically to <b class="cmd">romberg_powerLawLower</b> and
<b class="cmd">romberg_powerLawUpper</b> for the common case of <i class="arg">gamma</i>=0.5;
that is, they integrate a function with an inverse square root
singularity at one end of the interval. They have a simpler
implementation involving square roots rather than arbitrary powers.</p></dd>
<dt><b class="cmd">romberg_expLower</b> and <b class="cmd">romberg_expUpper</b></dt>
<dd><p>These procedures are for integrating a function that grows or
decreases exponentially over a half-infinite interval.
<b class="cmd">romberg_expLower</b> handles exponentially growing functions, and
allows the lower limit of integration to be an arbitrarily large
negative number. <b class="cmd">romberg_expUpper</b> handles exponentially
decaying functions and allows the upper limit of integration to
be an arbitrary large positive number. The functions make the
change of variable u=exp(-x) and u=exp(x) respectively.</p></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">OTHER CHANGES OF VARIABLE</a></h2>
<p>If you need an improper integral other than the ones listed here,
a change of variable can be written in very few lines of Tcl.
Because the Tcl coding that does it is somewhat arcane,
we offer a worked example here.</p>
<p>Let's say that the function that we want to integrate is
f(x)=exp(x)/sqrt(1-x*x) (not a very natural
function, but a good example), and we want to integrate
it over the interval (-1,1). The denominator falls to zero
at both ends of the interval. We wish to make a change of variable
from x to u
so that dx/sqrt(1-x**2) maps to du. Choosing x=sin(u), we can
find that dx=cos(u)*du, and sqrt(1-x**2)=cos(u). The integral
from a to b of f(x) is the integral from asin(a) to asin(b)
of f(sin(u))*cos(u).</p>
<p>We can make a function <b class="cmd">g</b> that accepts an arbitrary function
<b class="cmd">f</b> and the parameter u, and computes this new integrand.</p>
<pre class="doctools_example">
proc g { f u } {
set x [expr { sin($u) }]
set cmd $f; lappend cmd $x; set y [eval $cmd]
return [expr { $y / cos($u) }]
}
</pre>
<p>Now integrating <b class="cmd">f</b> from <i class="arg">a</i> to <i class="arg">b</i> is the same
as integrating <b class="cmd">g</b> from <i class="arg">asin(a)</i> to <i class="arg">asin(b)</i>.
It's a little tricky to get <b class="cmd">f</b> consistently evaluated in
the caller's scope; the following procedure does it.</p>
<pre class="doctools_example">
proc romberg_sine { f a b args } {
set f [lreplace $f 0 0 [uplevel 1 [list namespace which [lindex $f 0]]]]
set f [list g $f]
return [eval [linsert $args 0 romberg $f [expr { asin($a) }] [expr { asin($b) }]]]
}
</pre>
<p>This <b class="cmd">romberg_sine</b> procedure will do any function with
sqrt(1-x*x) in the denominator. Our sample function is
f(x)=exp(x)/sqrt(1-x*x):</p>
<pre class="doctools_example">
proc f { x } {
expr { exp($x) / sqrt( 1. - $x*$x ) }
}
</pre>
<p>Integrating it is a matter of applying <b class="cmd">romberg_sine</b>
as we would any of the other <b class="cmd">romberg</b> procedures:</p>
<pre class="doctools_example">
foreach { value error } [romberg_sine f -1.0 1.0] break
puts [format "integral is %.6g +/- %.6g" $value $error]
integral is 3.97746 +/- 2.3557e-010
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: calculus</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="calculus.html">math::calculus</a>, <a href="interpolate.html">math::interpolate</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Kevin B. Kenny <[email protected]>. All rights reserved. Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/special.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
|
<div class='fossil-doc' data-title='math::special - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::special(n) 0.3 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::special - Special mathematical functions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a></li>
<li class="doctools_section"><a href="#section3">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section4">THE ORTHOGONAL POLYNOMIALS</a></li>
<li class="doctools_section"><a href="#section5">REMARKS ON THE IMPLEMENTATION</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.3?</span></b></li>
<li>package require <b class="pkgname">math::special <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::special::Beta</b> <i class="arg">x</i> <i class="arg">y</i></a></li>
<li><a href="#2"><b class="cmd">::math::special::Gamma</b> <i class="arg">x</i></a></li>
<li><a href="#3"><b class="cmd">::math::special::erf</b> <i class="arg">x</i></a></li>
<li><a href="#4"><b class="cmd">::math::special::erfc</b> <i class="arg">x</i></a></li>
<li><a href="#5"><b class="cmd">::math::special::invnorm</b> <i class="arg">p</i></a></li>
<li><a href="#6"><b class="cmd">::math::special::J0</b> <i class="arg">x</i></a></li>
<li><a href="#7"><b class="cmd">::math::special::J1</b> <i class="arg">x</i></a></li>
<li><a href="#8"><b class="cmd">::math::special::Jn</b> <i class="arg">n</i> <i class="arg">x</i></a></li>
<li><a href="#9"><b class="cmd">::math::special::J1/2</b> <i class="arg">x</i></a></li>
<li><a href="#10"><b class="cmd">::math::special::J-1/2</b> <i class="arg">x</i></a></li>
<li><a href="#11"><b class="cmd">::math::special::I_n</b> <i class="arg">x</i></a></li>
<li><a href="#12"><b class="cmd">::math::special::cn</b> <i class="arg">u</i> <i class="arg">k</i></a></li>
<li><a href="#13"><b class="cmd">::math::special::dn</b> <i class="arg">u</i> <i class="arg">k</i></a></li>
<li><a href="#14"><b class="cmd">::math::special::sn</b> <i class="arg">u</i> <i class="arg">k</i></a></li>
<li><a href="#15"><b class="cmd">::math::special::elliptic_K</b> <i class="arg">k</i></a></li>
<li><a href="#16"><b class="cmd">::math::special::elliptic_E</b> <i class="arg">k</i></a></li>
<li><a href="#17"><b class="cmd">::math::special::exponential_Ei</b> <i class="arg">x</i></a></li>
<li><a href="#18"><b class="cmd">::math::special::exponential_En</b> <i class="arg">n</i> <i class="arg">x</i></a></li>
<li><a href="#19"><b class="cmd">::math::special::exponential_li</b> <i class="arg">x</i></a></li>
<li><a href="#20"><b class="cmd">::math::special::exponential_Ci</b> <i class="arg">x</i></a></li>
<li><a href="#21"><b class="cmd">::math::special::exponential_Si</b> <i class="arg">x</i></a></li>
<li><a href="#22"><b class="cmd">::math::special::exponential_Chi</b> <i class="arg">x</i></a></li>
<li><a href="#23"><b class="cmd">::math::special::exponential_Shi</b> <i class="arg">x</i></a></li>
<li><a href="#24"><b class="cmd">::math::special::fresnel_C</b> <i class="arg">x</i></a></li>
<li><a href="#25"><b class="cmd">::math::special::fresnel_S</b> <i class="arg">x</i></a></li>
<li><a href="#26"><b class="cmd">::math::special::sinc</b> <i class="arg">x</i></a></li>
<li><a href="#27"><b class="cmd">::math::special::legendre</b> <i class="arg">n</i></a></li>
<li><a href="#28"><b class="cmd">::math::special::chebyshev</b> <i class="arg">n</i></a></li>
<li><a href="#29"><b class="cmd">::math::special::laguerre</b> <i class="arg">alpha</i> <i class="arg">n</i></a></li>
<li><a href="#30"><b class="cmd">::math::special::hermite</b> <i class="arg">n</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements several so-called special functions, like
the Gamma function, the Bessel functions and such.</p>
<p>Each function is implemented by a procedure that bears its name (well,
in close approximation):</p>
<ul class="doctools_itemized">
<li><p>J0 for the zeroth-order Bessel function of the first kind</p></li>
<li><p>J1 for the first-order Bessel function of the first kind</p></li>
<li><p>Jn for the nth-order Bessel function of the first kind</p></li>
<li><p>J1/2 for the half-order Bessel function of the first kind</p></li>
<li><p>J-1/2 for the minus-half-order Bessel function of the first kind</p></li>
<li><p>I_n for the modified Bessel function of the first kind of order n</p></li>
<li><p>Gamma for the Gamma function, erf and erfc for the error function and
the complementary error function</p></li>
<li><p>fresnel_C and fresnel_S for the Fresnel integrals</p></li>
<li><p>elliptic_K and elliptic_E (complete elliptic integrals)</p></li>
<li><p>exponent_Ei and other functions related to the so-called exponential
integrals</p></li>
<li><p>legendre, hermite: some of the classical orthogonal polynomials.</p></li>
</ul>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<p>In the following table several characteristics of the functions in this
package are summarized: the domain for the argument, the values for the
parameters and error bounds.</p>
<pre class="doctools_example">
Family | Function | Domain x | Parameter | Error bound
-------------+-------------+-------------+-------------+--------------
Bessel | J0, J1, | all of R | n = integer | < 1.0e-8
| Jn | | | (|x|<20, n<20)
Bessel | J1/2, J-1/2,| x > 0 | n = integer | exact
Bessel | I_n | all of R | n = integer | < 1.0e-6
| | | |
Elliptic | cn | 0 <= x <= 1 | -- | < 1.0e-10
functions | dn | 0 <= x <= 1 | -- | < 1.0e-10
| sn | 0 <= x <= 1 | -- | < 1.0e-10
Elliptic | K | 0 <= x < 1 | -- | < 1.0e-6
integrals | E | 0 <= x < 1 | -- | < 1.0e-6
| | | |
Error | erf | | -- |
functions | erfc | | |
| | | |
Inverse | invnorm | 0 < x < 1 | -- | < 1.2e-9
normal | | | |
distribution | | | |
| | | |
Exponential | Ei | x != 0 | -- | < 1.0e-10 (relative)
integrals | En | x > 0 | -- | as Ei
| li | x > 0 | -- | as Ei
| Chi | x > 0 | -- | < 1.0e-8
| Shi | x > 0 | -- | < 1.0e-8
| Ci | x > 0 | -- | < 2.0e-4
| Si | x > 0 | -- | < 2.0e-4
| | | |
Fresnel | C | all of R | -- | < 2.0e-3
integrals | S | all of R | -- | < 2.0e-3
| | | |
general | Beta | (see Gamma) | -- | < 1.0e-9
| Gamma | x != 0,-1, | -- | < 1.0e-9
| | -2, ... | |
| sinc | all of R | -- | exact
| | | |
orthogonal | Legendre | all of R | n = 0,1,... | exact
polynomials | Chebyshev | all of R | n = 0,1,... | exact
| Laguerre | all of R | n = 0,1,... | exact
| | | alpha el. R |
| Hermite | all of R | n = 0,1,... | exact
</pre>
<p><em>Note:</em> Some of the error bounds are estimated, as no
"formal" bounds were available with the implemented approximation
method, others hold for the auxiliary functions used for estimating
the primary functions.</p>
<p>The following well-known functions are currently missing from the package:</p>
<ul class="doctools_itemized">
<li><p>Bessel functions of the second kind (Y_n, K_n)</p></li>
<li><p>Bessel functions of arbitrary order (and hence the Airy functions)</p></li>
<li><p>Chebyshev polynomials of the second kind (U_n)</p></li>
<li><p>The digamma function (psi)</p></li>
<li><p>The incomplete gamma and beta functions</p></li>
</ul>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROCEDURES</a></h2>
<p>The package defines the following public procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::special::Beta</b> <i class="arg">x</i> <i class="arg">y</i></a></dt>
<dd><p>Compute the Beta function for arguments "x" and "y"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>First argument for the Beta function</p></dd>
<dt>float <i class="arg">y</i></dt>
<dd><p>Second argument for the Beta function</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::special::Gamma</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the Gamma function for argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the Gamma function</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::special::erf</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the error function for argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the error function</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::special::erfc</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the complementary error function for argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the complementary error function</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::special::invnorm</b> <i class="arg">p</i></a></dt>
<dd><p>Compute the inverse of the normal distribution function for argument "p"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">p</i></dt>
<dd><p>Argument for the inverse normal distribution function
(p must be greater than 0 and lower than 1)</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::math::special::J0</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the zeroth-order Bessel function of the first kind for the
argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the Bessel function</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::special::J1</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the first-order Bessel function of the first kind for the
argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the Bessel function</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::special::Jn</b> <i class="arg">n</i> <i class="arg">x</i></a></dt>
<dd><p>Compute the nth-order Bessel function of the first kind for the
argument "x"</p>
<dl class="doctools_arguments">
<dt>integer <i class="arg">n</i></dt>
<dd><p>Order of the Bessel function</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the Bessel function</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::special::J1/2</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the half-order Bessel function of the first kind for the
argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the Bessel function</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::special::J-1/2</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the minus-half-order Bessel function of the first kind for the
argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the Bessel function</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::special::I_n</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the modified Bessel function of the first kind of order n for
the argument "x"</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">x</i></dt>
<dd><p>Positive integer order of the function</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::math::special::cn</b> <i class="arg">u</i> <i class="arg">k</i></a></dt>
<dd><p>Compute the elliptic function <em>cn</em> for the argument "u" and
parameter "k".</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">u</i></dt>
<dd><p>Argument for the function</p></dd>
<dt>float <i class="arg">k</i></dt>
<dd><p>Parameter</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::special::dn</b> <i class="arg">u</i> <i class="arg">k</i></a></dt>
<dd><p>Compute the elliptic function <em>dn</em> for the argument "u" and
parameter "k".</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">u</i></dt>
<dd><p>Argument for the function</p></dd>
<dt>float <i class="arg">k</i></dt>
<dd><p>Parameter</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::math::special::sn</b> <i class="arg">u</i> <i class="arg">k</i></a></dt>
<dd><p>Compute the elliptic function <em>sn</em> for the argument "u" and
parameter "k".</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">u</i></dt>
<dd><p>Argument for the function</p></dd>
<dt>float <i class="arg">k</i></dt>
<dd><p>Parameter</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::special::elliptic_K</b> <i class="arg">k</i></a></dt>
<dd><p>Compute the complete elliptic integral of the first kind
for the argument "k"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">k</i></dt>
<dd><p>Argument for the function</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::special::elliptic_E</b> <i class="arg">k</i></a></dt>
<dd><p>Compute the complete elliptic integral of the second kind
for the argument "k"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">k</i></dt>
<dd><p>Argument for the function</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">::math::special::exponential_Ei</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the exponential integral of the second kind
for the argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x != 0)</p></dd>
</dl></dd>
<dt><a name="18"><b class="cmd">::math::special::exponential_En</b> <i class="arg">n</i> <i class="arg">x</i></a></dt>
<dd><p>Compute the exponential integral of the first kind
for the argument "x" and order n</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>Order of the integral (n >= 0)</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x >= 0)</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">::math::special::exponential_li</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the logarithmic integral for the argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x > 0)</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">::math::special::exponential_Ci</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the cosine integral for the argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x > 0)</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">::math::special::exponential_Si</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the sine integral for the argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x > 0)</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">::math::special::exponential_Chi</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the hyperbolic cosine integral for the argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x > 0)</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">::math::special::exponential_Shi</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the hyperbolic sine integral for the argument "x"</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function (x > 0)</p></dd>
</dl></dd>
<dt><a name="24"><b class="cmd">::math::special::fresnel_C</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the Fresnel cosine integral for real argument x</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function</p></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">::math::special::fresnel_S</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the Fresnel sine integral for real argument x</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function</p></dd>
</dl></dd>
<dt><a name="26"><b class="cmd">::math::special::sinc</b> <i class="arg">x</i></a></dt>
<dd><p>Compute the sinc function for real argument x</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>Argument for the function</p></dd>
</dl></dd>
<dt><a name="27"><b class="cmd">::math::special::legendre</b> <i class="arg">n</i></a></dt>
<dd><p>Return the Legendre polynomial of degree n
(see <span class="sectref"><a href="#section4">THE ORTHOGONAL POLYNOMIALS</a></span>)</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>Degree of the polynomial</p></dd>
</dl></dd>
<dt><a name="28"><b class="cmd">::math::special::chebyshev</b> <i class="arg">n</i></a></dt>
<dd><p>Return the Chebyshev polynomial of degree n (of the first kind)</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>Degree of the polynomial</p></dd>
</dl></dd>
<dt><a name="29"><b class="cmd">::math::special::laguerre</b> <i class="arg">alpha</i> <i class="arg">n</i></a></dt>
<dd><p>Return the Laguerre polynomial of degree n with parameter alpha</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>Parameter of the Laguerre polynomial</p></dd>
<dt>int <i class="arg">n</i></dt>
<dd><p>Degree of the polynomial</p></dd>
</dl></dd>
<dt><a name="30"><b class="cmd">::math::special::hermite</b> <i class="arg">n</i></a></dt>
<dd><p>Return the Hermite polynomial of degree n</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>Degree of the polynomial</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">THE ORTHOGONAL POLYNOMIALS</a></h2>
<p>For dealing with the classical families of orthogonal polynomials, the
package relies on the <em>math::polynomials</em> package. To evaluate the
polynomial at some coordinate, use the <em>evalPolyn</em> command:</p>
<pre class="doctools_example">
set leg2 [::math::special::legendre 2]
puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]"
</pre>
<p>The return value from the <em>legendre</em> and other commands is actually
the definition of the corresponding polynomial as used in that package.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REMARKS ON THE IMPLEMENTATION</a></h2>
<p>It should be noted, that the actual implementation of J0 and J1 depends
on straightforward Gaussian quadrature formulas. The (absolute) accuracy
of the results is of the order 1.0e-4 or better. The main reason to
implement them like that was that it was fast to do (the formulas are
simple) and the computations are fast too.</p>
<p>The implementation of J1/2 does not suffer from this: this function can
be expressed exactly in terms of elementary functions.</p>
<p>The functions J0 and J1 are the ones you will encounter most frequently
in practice.</p>
<p>The computation of I_n is based on Miller's algorithm for computing the
minimal function from recurrence relations.</p>
<p>The computation of the Gamma and Beta functions relies on the
combinatorics package, whereas that of the error functions relies on the
statistics package.</p>
<p>The computation of the complete elliptic integrals uses the AGM
algorithm.</p>
<p>Much information about these functions can be found in:</p>
<p>Abramowitz and Stegun: <em>Handbook of Mathematical Functions</em>
(Dover, ISBN 486-61272-4)</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: special</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bessel_functions">Bessel functions</a>, <a href="../../../../index.html#error_function">error function</a>, <a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#special_functions">special functions</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/statistics.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
|
<div class='fossil-doc' data-title='math::statistics - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::statistics(n) 1 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::statistics - Basic statistical functions and procedures</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">GENERAL PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">MULTIVARIATE LINEAR REGRESSION</a></li>
<li class="doctools_section"><a href="#section4">STATISTICAL DISTRIBUTIONS</a></li>
<li class="doctools_section"><a href="#section5">DATA MANIPULATION</a></li>
<li class="doctools_section"><a href="#section6">PLOT PROCEDURES</a></li>
<li class="doctools_section"><a href="#section7">THINGS TO DO</a></li>
<li class="doctools_section"><a href="#section8">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section9">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">math::statistics 1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::statistics::mean</b> <i class="arg">data</i></a></li>
<li><a href="#2"><b class="cmd">::math::statistics::min</b> <i class="arg">data</i></a></li>
<li><a href="#3"><b class="cmd">::math::statistics::max</b> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::math::statistics::number</b> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::math::statistics::stdev</b> <i class="arg">data</i></a></li>
<li><a href="#6"><b class="cmd">::math::statistics::var</b> <i class="arg">data</i></a></li>
<li><a href="#7"><b class="cmd">::math::statistics::pstdev</b> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::math::statistics::pvar</b> <i class="arg">data</i></a></li>
<li><a href="#9"><b class="cmd">::math::statistics::median</b> <i class="arg">data</i></a></li>
<li><a href="#10"><b class="cmd">::math::statistics::basic-stats</b> <i class="arg">data</i></a></li>
<li><a href="#11"><b class="cmd">::math::statistics::histogram</b> <i class="arg">limits</i> <i class="arg">values</i> <span class="opt">?weights?</span></a></li>
<li><a href="#12"><b class="cmd">::math::statistics::histogram-alt</b> <i class="arg">limits</i> <i class="arg">values</i> <span class="opt">?weights?</span></a></li>
<li><a href="#13"><b class="cmd">::math::statistics::corr</b> <i class="arg">data1</i> <i class="arg">data2</i></a></li>
<li><a href="#14"><b class="cmd">::math::statistics::interval-mean-stdev</b> <i class="arg">data</i> <i class="arg">confidence</i></a></li>
<li><a href="#15"><b class="cmd">::math::statistics::t-test-mean</b> <i class="arg">data</i> <i class="arg">est_mean</i> <i class="arg">est_stdev</i> <i class="arg">alpha</i></a></li>
<li><a href="#16"><b class="cmd">::math::statistics::test-normal</b> <i class="arg">data</i> <i class="arg">significance</i></a></li>
<li><a href="#17"><b class="cmd">::math::statistics::lillieforsFit</b> <i class="arg">data</i></a></li>
<li><a href="#18"><b class="cmd">::math::statistics::test-Duckworth</b> <i class="arg">list1</i> <i class="arg">list2</i> <i class="arg">significance</i></a></li>
<li><a href="#19"><b class="cmd">::math::statistics::test-anova-F</b> <i class="arg">alpha</i> <i class="arg">args</i></a></li>
<li><a href="#20"><b class="cmd">::math::statistics::test-Tukey-range</b> <i class="arg">alpha</i> <i class="arg">args</i></a></li>
<li><a href="#21"><b class="cmd">::math::statistics::test-Dunnett</b> <i class="arg">alpha</i> <i class="arg">control</i> <i class="arg">args</i></a></li>
<li><a href="#22"><b class="cmd">::math::statistics::quantiles</b> <i class="arg">data</i> <i class="arg">confidence</i></a></li>
<li><a href="#23"><b class="cmd">::math::statistics::quantiles</b> <i class="arg">limits</i> <i class="arg">counts</i> <i class="arg">confidence</i></a></li>
<li><a href="#24"><b class="cmd">::math::statistics::autocorr</b> <i class="arg">data</i></a></li>
<li><a href="#25"><b class="cmd">::math::statistics::crosscorr</b> <i class="arg">data1</i> <i class="arg">data2</i></a></li>
<li><a href="#26"><b class="cmd">::math::statistics::mean-histogram-limits</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">number</i></a></li>
<li><a href="#27"><b class="cmd">::math::statistics::minmax-histogram-limits</b> <i class="arg">min</i> <i class="arg">max</i> <i class="arg">number</i></a></li>
<li><a href="#28"><b class="cmd">::math::statistics::linear-model</b> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">intercept</i></a></li>
<li><a href="#29"><b class="cmd">::math::statistics::linear-residuals</b> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">intercept</i></a></li>
<li><a href="#30"><b class="cmd">::math::statistics::test-2x2</b> <i class="arg">n11</i> <i class="arg">n21</i> <i class="arg">n12</i> <i class="arg">n22</i></a></li>
<li><a href="#31"><b class="cmd">::math::statistics::print-2x2</b> <i class="arg">n11</i> <i class="arg">n21</i> <i class="arg">n12</i> <i class="arg">n22</i></a></li>
<li><a href="#32"><b class="cmd">::math::statistics::control-xbar</b> <i class="arg">data</i> <span class="opt">?nsamples?</span></a></li>
<li><a href="#33"><b class="cmd">::math::statistics::control-Rchart</b> <i class="arg">data</i> <span class="opt">?nsamples?</span></a></li>
<li><a href="#34"><b class="cmd">::math::statistics::test-xbar</b> <i class="arg">control</i> <i class="arg">data</i></a></li>
<li><a href="#35"><b class="cmd">::math::statistics::test-Rchart</b> <i class="arg">control</i> <i class="arg">data</i></a></li>
<li><a href="#36"><b class="cmd">::math::statistics::test-Kruskal-Wallis</b> <i class="arg">confidence</i> <i class="arg">args</i></a></li>
<li><a href="#37"><b class="cmd">::math::statistics::analyse-Kruskal-Wallis</b> <i class="arg">args</i></a></li>
<li><a href="#38"><b class="cmd">::math::statistics::group-rank</b> <i class="arg">args</i></a></li>
<li><a href="#39"><b class="cmd">::math::statistics::test-Wilcoxon</b> <i class="arg">sample_a</i> <i class="arg">sample_b</i></a></li>
<li><a href="#40"><b class="cmd">::math::statistics::spearman-rank</b> <i class="arg">sample_a</i> <i class="arg">sample_b</i></a></li>
<li><a href="#41"><b class="cmd">::math::statistics::spearman-rank-extended</b> <i class="arg">sample_a</i> <i class="arg">sample_b</i></a></li>
<li><a href="#42"><b class="cmd">::math::statistics::kernel-density</b> <i class="arg">data</i> opt <i class="arg">-option value</i> ...</a></li>
<li><a href="#43"><b class="cmd">::math::statistics::bootstrap</b> <i class="arg">data</i> <i class="arg">sampleSize</i> <span class="opt">?numberSamples?</span></a></li>
<li><a href="#44"><b class="cmd">::math::statistics::wasserstein-distance</b> <i class="arg">prob1</i> <i class="arg">prob2</i></a></li>
<li><a href="#45"><b class="cmd">::math::statistics::kl-divergence</b> <i class="arg">prob1</i> <i class="arg">prob2</i></a></li>
<li><a href="#46"><b class="cmd">::math::statistics::logistic-model</b> <i class="arg">xdata</i> <i class="arg">ydata</i></a></li>
<li><a href="#47"><b class="cmd">::math::statistics::logistic-probability</b> <i class="arg">coeffs</i> <i class="arg">x</i></a></li>
<li><a href="#48"><b class="cmd">::math::statistics::tstat</b> <i class="arg">dof</i> <span class="opt">?alpha?</span></a></li>
<li><a href="#49"><b class="cmd">::math::statistics::mv-wls</b> <i class="arg">wt1</i> <i class="arg">weights_and_values</i></a></li>
<li><a href="#50"><b class="cmd">::math::statistics::mv-ols</b> <i class="arg">values</i></a></li>
<li><a href="#51"><b class="cmd">::math::statistics::pdf-normal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></li>
<li><a href="#52"><b class="cmd">::math::statistics::pdf-lognormal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></li>
<li><a href="#53"><b class="cmd">::math::statistics::pdf-exponential</b> <i class="arg">mean</i> <i class="arg">value</i></a></li>
<li><a href="#54"><b class="cmd">::math::statistics::pdf-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">value</i></a></li>
<li><a href="#55"><b class="cmd">::math::statistics::pdf-gamma</b> <i class="arg">alpha</i> <i class="arg">beta</i> <i class="arg">value</i></a></li>
<li><a href="#56"><b class="cmd">::math::statistics::pdf-poisson</b> <i class="arg">mu</i> <i class="arg">k</i></a></li>
<li><a href="#57"><b class="cmd">::math::statistics::pdf-chisquare</b> <i class="arg">df</i> <i class="arg">value</i></a></li>
<li><a href="#58"><b class="cmd">::math::statistics::pdf-student-t</b> <i class="arg">df</i> <i class="arg">value</i></a></li>
<li><a href="#59"><b class="cmd">::math::statistics::pdf-gamma</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">value</i></a></li>
<li><a href="#60"><b class="cmd">::math::statistics::pdf-beta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">value</i></a></li>
<li><a href="#61"><b class="cmd">::math::statistics::pdf-weibull</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></li>
<li><a href="#62"><b class="cmd">::math::statistics::pdf-gumbel</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></li>
<li><a href="#63"><b class="cmd">::math::statistics::pdf-pareto</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></li>
<li><a href="#64"><b class="cmd">::math::statistics::pdf-cauchy</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></li>
<li><a href="#65"><b class="cmd">::math::statistics::cdf-normal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></li>
<li><a href="#66"><b class="cmd">::math::statistics::cdf-lognormal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></li>
<li><a href="#67"><b class="cmd">::math::statistics::cdf-exponential</b> <i class="arg">mean</i> <i class="arg">value</i></a></li>
<li><a href="#68"><b class="cmd">::math::statistics::cdf-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">value</i></a></li>
<li><a href="#69"><b class="cmd">::math::statistics::cdf-students-t</b> <i class="arg">degrees</i> <i class="arg">value</i></a></li>
<li><a href="#70"><b class="cmd">::math::statistics::cdf-gamma</b> <i class="arg">alpha</i> <i class="arg">beta</i> <i class="arg">value</i></a></li>
<li><a href="#71"><b class="cmd">::math::statistics::cdf-poisson</b> <i class="arg">mu</i> <i class="arg">k</i></a></li>
<li><a href="#72"><b class="cmd">::math::statistics::cdf-beta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">value</i></a></li>
<li><a href="#73"><b class="cmd">::math::statistics::cdf-weibull</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></li>
<li><a href="#74"><b class="cmd">::math::statistics::cdf-gumbel</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></li>
<li><a href="#75"><b class="cmd">::math::statistics::cdf-pareto</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></li>
<li><a href="#76"><b class="cmd">::math::statistics::cdf-cauchy</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></li>
<li><a href="#77"><b class="cmd">::math::statistics::cdf-F</b> <i class="arg">nf1</i> <i class="arg">nf2</i> <i class="arg">value</i></a></li>
<li><a href="#78"><b class="cmd">::math::statistics::empirical-distribution</b> <i class="arg">values</i></a></li>
<li><a href="#79"><b class="cmd">::math::statistics::random-normal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">number</i></a></li>
<li><a href="#80"><b class="cmd">::math::statistics::random-lognormal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">number</i></a></li>
<li><a href="#81"><b class="cmd">::math::statistics::random-exponential</b> <i class="arg">mean</i> <i class="arg">number</i></a></li>
<li><a href="#82"><b class="cmd">::math::statistics::random-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">number</i></a></li>
<li><a href="#83"><b class="cmd">::math::statistics::random-gamma</b> <i class="arg">alpha</i> <i class="arg">beta</i> <i class="arg">number</i></a></li>
<li><a href="#84"><b class="cmd">::math::statistics::random-poisson</b> <i class="arg">mu</i> <i class="arg">number</i></a></li>
<li><a href="#85"><b class="cmd">::math::statistics::random-chisquare</b> <i class="arg">df</i> <i class="arg">number</i></a></li>
<li><a href="#86"><b class="cmd">::math::statistics::random-student-t</b> <i class="arg">df</i> <i class="arg">number</i></a></li>
<li><a href="#87"><b class="cmd">::math::statistics::random-beta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">number</i></a></li>
<li><a href="#88"><b class="cmd">::math::statistics::random-weibull</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">number</i></a></li>
<li><a href="#89"><b class="cmd">::math::statistics::random-gumbel</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">number</i></a></li>
<li><a href="#90"><b class="cmd">::math::statistics::random-pareto</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">number</i></a></li>
<li><a href="#91"><b class="cmd">::math::statistics::random-cauchy</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">number</i></a></li>
<li><a href="#92"><b class="cmd">::math::statistics::histogram-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">limits</i> <i class="arg">number</i></a></li>
<li><a href="#93"><b class="cmd">::math::statistics::incompleteGamma</b> <i class="arg">x</i> <i class="arg">p</i> <span class="opt">?tol?</span></a></li>
<li><a href="#94"><b class="cmd">::math::statistics::incompleteBeta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">x</i> <span class="opt">?tol?</span></a></li>
<li><a href="#95"><b class="cmd">::math::statistics::estimate-pareto</b> <i class="arg">values</i></a></li>
<li><a href="#96"><b class="cmd">::math::statistics::filter</b> <i class="arg">varname</i> <i class="arg">data</i> <i class="arg">expression</i></a></li>
<li><a href="#97"><b class="cmd">::math::statistics::map</b> <i class="arg">varname</i> <i class="arg">data</i> <i class="arg">expression</i></a></li>
<li><a href="#98"><b class="cmd">::math::statistics::samplescount</b> <i class="arg">varname</i> <i class="arg">list</i> <i class="arg">expression</i></a></li>
<li><a href="#99"><b class="cmd">::math::statistics::subdivide</b></a></li>
<li><a href="#100"><b class="cmd">::math::statistics::plot-scale</b> <i class="arg">canvas</i> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">ymin</i> <i class="arg">ymax</i></a></li>
<li><a href="#101"><b class="cmd">::math::statistics::plot-xydata</b> <i class="arg">canvas</i> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">tag</i></a></li>
<li><a href="#102"><b class="cmd">::math::statistics::plot-xyline</b> <i class="arg">canvas</i> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">tag</i></a></li>
<li><a href="#103"><b class="cmd">::math::statistics::plot-tdata</b> <i class="arg">canvas</i> <i class="arg">tdata</i> <i class="arg">tag</i></a></li>
<li><a href="#104"><b class="cmd">::math::statistics::plot-tline</b> <i class="arg">canvas</i> <i class="arg">tdata</i> <i class="arg">tag</i></a></li>
<li><a href="#105"><b class="cmd">::math::statistics::plot-histogram</b> <i class="arg">canvas</i> <i class="arg">counts</i> <i class="arg">limits</i> <i class="arg">tag</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">math::statistics</b> package contains functions and procedures for
basic statistical data analysis, such as:</p>
<ul class="doctools_itemized">
<li><p>Descriptive statistical parameters (mean, minimum, maximum, standard
deviation)</p></li>
<li><p>Estimates of the distribution in the form of histograms and quantiles</p></li>
<li><p>Basic testing of hypotheses</p></li>
<li><p>Probability and cumulative density functions</p></li>
</ul>
<p>It is meant to help in developing data analysis applications or doing
ad hoc data analysis, it is not in itself a full application, nor is it
intended to rival with full (non-)commercial statistical packages.</p>
<p>The purpose of this document is to describe the implemented procedures
and provide some examples of their usage. As there is ample literature
on the algorithms involved, we refer to relevant text books for more
explanations.
The package contains a fairly large number of public procedures. They
can be distinguished in three sets: general procedures, procedures
that deal with specific statistical distributions, list procedures to
select or transform data and simple plotting procedures (these require
Tk).
<em>Note:</em> The data that need to be analyzed are always contained in a
simple list. Missing values are represented as empty list elements.
<em>Note:</em> With version 1.0.1 a mistake in the procs <i class="term">pdf-lognormal</i>,
<i class="term">cdf-lognormal</i> and <i class="term">random-lognormal</i> has been corrected. In
previous versions the argument for the standard deviation was actually
used as if it was the variance.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">GENERAL PROCEDURES</a></h2>
<p>The general statistical procedures are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::statistics::mean</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">mean</i> value of the given list of data.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::statistics::min</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term"><a href="../../../../index.html#minimum">minimum</a></i> value of the given list of data.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::math::statistics::max</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term"><a href="../../../../index.html#maximum">maximum</a></i> value of the given list of data.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::statistics::number</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">number</i> of non-missing data in the given list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::statistics::stdev</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">sample standard deviation</i> of the data in the
given list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::math::statistics::var</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">sample variance</i> of the data in the given list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::statistics::pstdev</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">population standard deviation</i> of the data
in the given list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::statistics::pvar</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">population variance</i> of the data in the
given list</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::math::statistics::median</b> <i class="arg">data</i></a></dt>
<dd><p>Determine the <i class="term">median</i> of the data in the given list
(Note that this requires sorting the data, which may be a
costly operation)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::statistics::basic-stats</b> <i class="arg">data</i></a></dt>
<dd><p>Determine a list of all the descriptive parameters: mean, minimum,
maximum, number of data, sample standard deviation, sample variance,
population standard deviation and population variance.</p>
<p>(This routine is called whenever either or all of the basic statistical
parameters are required. Hence all calculations are done and the
relevant values are returned.)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::statistics::histogram</b> <i class="arg">limits</i> <i class="arg">values</i> <span class="opt">?weights?</span></a></dt>
<dd><p>Determine histogram information for the given list of data. Returns a
list consisting of the number of values that fall into each interval.
(The first interval consists of all values lower than the first limit,
the last interval consists of all values greater than the last limit.
There is one more interval than there are limits.)</p>
<p>Optionally, you can use weights to influence the histogram.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">limits</i></dt>
<dd><p>- List of upper limits (in ascending order) for the
intervals of the histogram.</p></dd>
<dt>list <i class="arg">values</i></dt>
<dd><p>- List of data</p></dd>
<dt>list <i class="arg">weights</i></dt>
<dd><p>- List of weights, one weight per value</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::math::statistics::histogram-alt</b> <i class="arg">limits</i> <i class="arg">values</i> <span class="opt">?weights?</span></a></dt>
<dd><p>Alternative implementation of the histogram procedure: the open end of the intervals
is at the lower bound instead of the upper bound.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">limits</i></dt>
<dd><p>- List of upper limits (in ascending order) for the
intervals of the histogram.</p></dd>
<dt>list <i class="arg">values</i></dt>
<dd><p>- List of data</p></dd>
<dt>list <i class="arg">weights</i></dt>
<dd><p>- List of weights, one weight per value</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::statistics::corr</b> <i class="arg">data1</i> <i class="arg">data2</i></a></dt>
<dd><p>Determine the correlation coefficient between two sets of data.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data1</i></dt>
<dd><p>- First list of data</p></dd>
<dt>list <i class="arg">data2</i></dt>
<dd><p>- Second list of data</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::math::statistics::interval-mean-stdev</b> <i class="arg">data</i> <i class="arg">confidence</i></a></dt>
<dd><p>Return the interval containing the mean value and one
containing the standard deviation with a certain
level of confidence (assuming a normal distribution)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of raw data values (small sample)</p></dd>
<dt>float <i class="arg">confidence</i></dt>
<dd><p>- Confidence level (0.95 or 0.99 for instance)</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::statistics::t-test-mean</b> <i class="arg">data</i> <i class="arg">est_mean</i> <i class="arg">est_stdev</i> <i class="arg">alpha</i></a></dt>
<dd><p>Test whether the mean value of a sample is in accordance with the
estimated normal distribution with a certain probability.
Returns 1 if the test succeeds or 0 if the mean is unlikely to fit
the given distribution.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of raw data values (small sample)</p></dd>
<dt>float <i class="arg">est_mean</i></dt>
<dd><p>- Estimated mean of the distribution</p></dd>
<dt>float <i class="arg">est_stdev</i></dt>
<dd><p>- Estimated stdev of the distribution</p></dd>
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Probability level (0.95 or 0.99 for instance)</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::statistics::test-normal</b> <i class="arg">data</i> <i class="arg">significance</i></a></dt>
<dd><p>Test whether the given data follow a normal distribution
with a certain level of significance.
Returns 1 if the data are normally distributed within the level of
significance, returns 0 if not. The underlying test is the Lilliefors
test. Smaller values of the significance mean a stricter testing.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of raw data values</p></dd>
<dt>float <i class="arg">significance</i></dt>
<dd><p>- Significance level (one of 0.01, 0.05, 0.10, 0.15 or 0.20). For compatibility
reasons the values "1-significance", 0.80, 0.85, 0.90, 0.95 or 0.99 are also accepted.</p></dd>
</dl>
<p>Compatibility issue: the original implementation and documentation used the term "confidence" and used a value
1-significance (see ticket 2812473fff). This has been corrected as of version 0.9.3.</p></dd>
<dt><a name="17"><b class="cmd">::math::statistics::lillieforsFit</b> <i class="arg">data</i></a></dt>
<dd><p>Returns the goodness of fit to a normal distribution according to
Lilliefors. The higher the number, the more likely the data are indeed
normally distributed. The test requires at least <em>five</em> data
points.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of raw data values</p></dd>
</dl></dd>
<dt><a name="18"><b class="cmd">::math::statistics::test-Duckworth</b> <i class="arg">list1</i> <i class="arg">list2</i> <i class="arg">significance</i></a></dt>
<dd><p>Determine if two data sets have the same median according to the Tukey-Duckworth test.
The procedure returns 0 if the medians are unequal, 1 if they are equal, -1 if the test can not
be conducted (the smallest value must be in a different set than the greatest value).
#
# Arguments:
# list1 Values in the first data set
# list2 Values in the second data set
# significance Significance level (either 0.05, 0.01 or 0.001)
#
# Returns:
Test whether the given data follow a normal distribution
with a certain level of significance.
Returns 1 if the data are normally distributed within the level of
significance, returns 0 if not. The underlying test is the Lilliefors
test. Smaller values of the significance mean a stricter testing.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">list1</i></dt>
<dd><p>- First list of data</p></dd>
<dt>list <i class="arg">list2</i></dt>
<dd><p>- Second list of data</p></dd>
<dt>float <i class="arg">significance</i></dt>
<dd><p>- Significance level (either 0.05, 0.01 or 0.001)</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">::math::statistics::test-anova-F</b> <i class="arg">alpha</i> <i class="arg">args</i></a></dt>
<dd><p>Determine if two or more groups with normally distributed data have the same means.
The procedure returns 0 if the means are likely unequal, 1 if they are. This is
a one-way ANOVA test. The groups may also be stored in a nested list:
The procedure returns a list of the comparison results for each pair of groups. Each
element of this list contains: the index of the first group and that of the second group,
whether the means are likely to be different (1) or not (0) and the confidence interval
the conclusion is based on. The groups may also be stored in a nested list:</p>
<pre class="doctools_example">
test-anova-F 0.05 $A $B $C
#
# Or equivalently:
#
test-anova-F 0.05 [list $A $B $C]
</pre>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Significance level</p></dd>
<dt>list <i class="arg">args</i></dt>
<dd><p>- Two or more groups of data to be checked</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">::math::statistics::test-Tukey-range</b> <i class="arg">alpha</i> <i class="arg">args</i></a></dt>
<dd><p>Determine if two or more groups with normally distributed data have the same means,
using Tukey's range test. It is complementary to the ANOVA test.
The procedure returns a list of the comparison results for each pair of groups. Each
element of this list contains: the index of the first group and that of the second group,
whether the means are likely to be different (1) or not (0) and the confidence interval
the conclusion is based on. The groups may also be stored in a nested list, just as with
the ANOVA test.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Significance level - either 0.05 or 0.01</p></dd>
<dt>list <i class="arg">args</i></dt>
<dd><p>- Two or more groups of data to be checked</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">::math::statistics::test-Dunnett</b> <i class="arg">alpha</i> <i class="arg">control</i> <i class="arg">args</i></a></dt>
<dd><p>Determine if one or more groups with normally distributed data have the same means as
the group of control data, using Dunnett's test. It is complementary to the ANOVA test.
The procedure returns a list of the comparison results for each group with the control group. Each
element of this list contains: whether the means are likely to be different (1) or not (0)
and the confidence interval the conclusion is based on. The groups may also be stored in a
nested list, just as with the ANOVA test.</p>
<p>Note: some care is required if there is only one group to compare the control with:</p>
<pre class="doctools_example">
test-Dunnett-F 0.05 $control [list $A]
</pre>
<p>Otherwise the group A is split up into groups of one element - this is due to an ambiguity.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Significance level - either 0.05 or 0.01</p></dd>
<dt>list <i class="arg">args</i></dt>
<dd><p>- One or more groups of data to be checked</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">::math::statistics::quantiles</b> <i class="arg">data</i> <i class="arg">confidence</i></a></dt>
<dd><p>Return the quantiles for a given set of data</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of raw data values</p></dd>
<dt>float <i class="arg">confidence</i></dt>
<dd><p>- Confidence level (0.95 or 0.99 for instance) or a list of confidence levels.</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">::math::statistics::quantiles</b> <i class="arg">limits</i> <i class="arg">counts</i> <i class="arg">confidence</i></a></dt>
<dd><p>Return the quantiles based on histogram information (alternative to the
call with two arguments)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">limits</i></dt>
<dd><p>- List of upper limits from histogram</p></dd>
<dt>list <i class="arg">counts</i></dt>
<dd><p>- List of counts for for each interval in histogram</p></dd>
<dt>float <i class="arg">confidence</i></dt>
<dd><p>- Confidence level (0.95 or 0.99 for instance) or a list of confidence levels.</p></dd>
</dl></dd>
<dt><a name="24"><b class="cmd">::math::statistics::autocorr</b> <i class="arg">data</i></a></dt>
<dd><p>Return the autocorrelation function as a list of values (assuming
equidistance between samples, about 1/2 of the number of raw data)</p>
<p>The correlation is determined in such a way that the first value is
always 1 and all others are equal to or smaller than 1. The number of
values involved will diminish as the "time" (the index in the list of
returned values) increases</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- Raw data for which the autocorrelation must be determined</p></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">::math::statistics::crosscorr</b> <i class="arg">data1</i> <i class="arg">data2</i></a></dt>
<dd><p>Return the cross-correlation function as a list of values (assuming
equidistance between samples, about 1/2 of the number of raw data)</p>
<p>The correlation is determined in such a way that the values can never
exceed 1 in magnitude. The number of values involved will diminish
as the "time" (the index in the list of returned values) increases.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data1</i></dt>
<dd><p>- First list of data</p></dd>
<dt>list <i class="arg">data2</i></dt>
<dd><p>- Second list of data</p></dd>
</dl></dd>
<dt><a name="26"><b class="cmd">::math::statistics::mean-histogram-limits</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">number</i></a></dt>
<dd><p>Determine reasonable limits based on mean and standard deviation
for a histogram
Convenience function - the result is suitable for the histogram function.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean of the data</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of limits to generate (defaults to 8)</p></dd>
</dl></dd>
<dt><a name="27"><b class="cmd">::math::statistics::minmax-histogram-limits</b> <i class="arg">min</i> <i class="arg">max</i> <i class="arg">number</i></a></dt>
<dd><p>Determine reasonable limits based on a minimum and maximum for a histogram</p>
<p>Convenience function - the result is suitable for the histogram function.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">min</i></dt>
<dd><p>- Expected minimum</p></dd>
<dt>float <i class="arg">max</i></dt>
<dd><p>- Expected maximum</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of limits to generate (defaults to 8)</p></dd>
</dl></dd>
<dt><a name="28"><b class="cmd">::math::statistics::linear-model</b> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">intercept</i></a></dt>
<dd><p>Determine the coefficients for a linear regression between
two series of data (the model: Y = A + B*X). Returns a list of
parameters describing the fit</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xdata</i></dt>
<dd><p>- List of independent data</p></dd>
<dt>list <i class="arg">ydata</i></dt>
<dd><p>- List of dependent data to be fitted</p></dd>
<dt>boolean <i class="arg">intercept</i></dt>
<dd><p>- (Optional) compute the intercept (1, default) or fit
to a line through the origin (0)</p>
<p>The result consists of the following list:</p>
<ul class="doctools_itemized">
<li><p>(Estimate of) Intercept A</p></li>
<li><p>(Estimate of) Slope B</p></li>
<li><p>Standard deviation of Y relative to fit</p></li>
<li><p>Correlation coefficient R2</p></li>
<li><p>Number of degrees of freedom df</p></li>
<li><p>Standard error of the intercept A</p></li>
<li><p>Significance level of A</p></li>
<li><p>Standard error of the slope B</p></li>
<li><p>Significance level of B</p></li>
</ul></dd>
</dl></dd>
<dt><a name="29"><b class="cmd">::math::statistics::linear-residuals</b> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">intercept</i></a></dt>
<dd><p>Determine the difference between actual data and predicted from
the linear model.</p>
<p>Returns a list of the differences between the actual data and the
predicted values.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xdata</i></dt>
<dd><p>- List of independent data</p></dd>
<dt>list <i class="arg">ydata</i></dt>
<dd><p>- List of dependent data to be fitted</p></dd>
<dt>boolean <i class="arg">intercept</i></dt>
<dd><p>- (Optional) compute the intercept (1, default) or fit
to a line through the origin (0)</p></dd>
</dl></dd>
<dt><a name="30"><b class="cmd">::math::statistics::test-2x2</b> <i class="arg">n11</i> <i class="arg">n21</i> <i class="arg">n12</i> <i class="arg">n22</i></a></dt>
<dd><p>Determine if two set of samples, each from a binomial distribution,
differ significantly or not (implying a different parameter).</p>
<p>Returns the "chi-square" value, which can be used to the determine the
significance.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n11</i></dt>
<dd><p>- Number of outcomes with the first value from the first sample.</p></dd>
<dt>int <i class="arg">n21</i></dt>
<dd><p>- Number of outcomes with the first value from the second sample.</p></dd>
<dt>int <i class="arg">n12</i></dt>
<dd><p>- Number of outcomes with the second value from the first sample.</p></dd>
<dt>int <i class="arg">n22</i></dt>
<dd><p>- Number of outcomes with the second value from the second sample.</p></dd>
</dl></dd>
<dt><a name="31"><b class="cmd">::math::statistics::print-2x2</b> <i class="arg">n11</i> <i class="arg">n21</i> <i class="arg">n12</i> <i class="arg">n22</i></a></dt>
<dd><p>Determine if two set of samples, each from a binomial distribution,
differ significantly or not (implying a different parameter).</p>
<p>Returns a short report, useful in an interactive session.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n11</i></dt>
<dd><p>- Number of outcomes with the first value from the first sample.</p></dd>
<dt>int <i class="arg">n21</i></dt>
<dd><p>- Number of outcomes with the first value from the second sample.</p></dd>
<dt>int <i class="arg">n12</i></dt>
<dd><p>- Number of outcomes with the second value from the first sample.</p></dd>
<dt>int <i class="arg">n22</i></dt>
<dd><p>- Number of outcomes with the second value from the second sample.</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">::math::statistics::control-xbar</b> <i class="arg">data</i> <span class="opt">?nsamples?</span></a></dt>
<dd><p>Determine the control limits for an xbar chart. The number of data
in each subsample defaults to 4. At least 20 subsamples are required.</p>
<p>Returns the mean, the lower limit, the upper limit and the number of
data per subsample.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of observed data</p></dd>
<dt>int <i class="arg">nsamples</i></dt>
<dd><p>- Number of data per subsample</p></dd>
</dl></dd>
<dt><a name="33"><b class="cmd">::math::statistics::control-Rchart</b> <i class="arg">data</i> <span class="opt">?nsamples?</span></a></dt>
<dd><p>Determine the control limits for an R chart. The number of data
in each subsample (nsamples) defaults to 4. At least 20 subsamples are required.</p>
<p>Returns the mean range, the lower limit, the upper limit and the number
of data per subsample.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of observed data</p></dd>
<dt>int <i class="arg">nsamples</i></dt>
<dd><p>- Number of data per subsample</p></dd>
</dl></dd>
<dt><a name="34"><b class="cmd">::math::statistics::test-xbar</b> <i class="arg">control</i> <i class="arg">data</i></a></dt>
<dd><p>Determine if the data exceed the control limits for the xbar chart.</p>
<p>Returns a list of subsamples (their indices) that indeed violate the
limits.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">control</i></dt>
<dd><p>- Control limits as returned by the "control-xbar" procedure</p></dd>
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of observed data</p></dd>
</dl></dd>
<dt><a name="35"><b class="cmd">::math::statistics::test-Rchart</b> <i class="arg">control</i> <i class="arg">data</i></a></dt>
<dd><p>Determine if the data exceed the control limits for the R chart.</p>
<p>Returns a list of subsamples (their indices) that indeed violate the
limits.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">control</i></dt>
<dd><p>- Control limits as returned by the "control-Rchart" procedure</p></dd>
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of observed data</p></dd>
</dl></dd>
<dt><a name="36"><b class="cmd">::math::statistics::test-Kruskal-Wallis</b> <i class="arg">confidence</i> <i class="arg">args</i></a></dt>
<dd><p>Check if the population medians of two or more groups are equal with a
given confidence level, using the Kruskal-Wallis test.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">confidence</i></dt>
<dd><p>- Confidence level to be used (0-1)</p></dd>
<dt>list <i class="arg">args</i></dt>
<dd><p>- Two or more lists of data</p></dd>
</dl></dd>
<dt><a name="37"><b class="cmd">::math::statistics::analyse-Kruskal-Wallis</b> <i class="arg">args</i></a></dt>
<dd><p>Compute the statistical parameters for the Kruskal-Wallis test.
Returns the Kruskal-Wallis statistic and the probability that that
value would occur assuming the medians of the populations are
equal.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">args</i></dt>
<dd><p>- Two or more lists of data</p></dd>
</dl></dd>
<dt><a name="38"><b class="cmd">::math::statistics::group-rank</b> <i class="arg">args</i></a></dt>
<dd><p>Rank the groups of data with respect to the complete set.
Returns a list consisting of the group ID, the value and the rank
(possibly a rational number, in case of ties) for each data item.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">args</i></dt>
<dd><p>- Two or more lists of data</p></dd>
</dl></dd>
<dt><a name="39"><b class="cmd">::math::statistics::test-Wilcoxon</b> <i class="arg">sample_a</i> <i class="arg">sample_b</i></a></dt>
<dd><p>Compute the Wilcoxon test statistic to determine if two samples have the
same median or not. (The statistic can be regarded as standard normal, if the
sample sizes are both larger than 10. Returns the value of this statistic.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">sample_a</i></dt>
<dd><p>- List of data comprising the first sample</p></dd>
<dt>list <i class="arg">sample_b</i></dt>
<dd><p>- List of data comprising the second sample</p></dd>
</dl></dd>
<dt><a name="40"><b class="cmd">::math::statistics::spearman-rank</b> <i class="arg">sample_a</i> <i class="arg">sample_b</i></a></dt>
<dd><p>Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation
coefficient. The two samples should have the same number of data.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">sample_a</i></dt>
<dd><p>- First list of data</p></dd>
<dt>list <i class="arg">sample_b</i></dt>
<dd><p>- Second list of data</p></dd>
</dl></dd>
<dt><a name="41"><b class="cmd">::math::statistics::spearman-rank-extended</b> <i class="arg">sample_a</i> <i class="arg">sample_b</i></a></dt>
<dd><p>Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation
coefficient as well as additional data. The two samples should have the same number of data.
The procedure returns the correlation coefficient, the number of data pairs used and the
z-score, an approximately standard normal statistic, indicating the significance of the correlation.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">sample_a</i></dt>
<dd><p>- First list of data</p></dd>
<dt>list <i class="arg">sample_b</i></dt>
<dd><p>- Second list of data</p></dd>
</dl></dd>
<dt><a name="42"><b class="cmd">::math::statistics::kernel-density</b> <i class="arg">data</i> opt <i class="arg">-option value</i> ...</a></dt>
<dd><p>Return the density function based on kernel density estimation. The procedure is controlled by
a small set of options, each of which is given a reasonable default.</p>
<p>The return value consists of three lists: the centres of the bins, the associated probability
density and a list of computational parameters (begin and end of the interval, mean and standard
deviation and the used bandwidth). The computational parameters can be used for further analysis.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>- The data to be examined</p></dd>
<dt>list <i class="arg">args</i></dt>
<dd><p>- Option-value pairs:</p>
<dl class="doctools_definitions">
<dt><b class="option">-weights</b> <i class="arg">weights</i></dt>
<dd><p>Per data point the weight (default: 1 for all data)</p></dd>
<dt><b class="option">-bandwidth</b> <i class="arg">value</i></dt>
<dd><p>Bandwidth to be used for the estimation (default: determined from standard deviation)</p></dd>
<dt><b class="option">-number</b> <i class="arg">value</i></dt>
<dd><p>Number of bins to be returned (default: 100)</p></dd>
<dt><b class="option">-interval</b> <i class="arg">{begin end}</i></dt>
<dd><p>Begin and end of the interval for
which the density is returned (default: mean +/- 3*standard deviation)</p></dd>
<dt><b class="option">-kernel</b> <i class="arg">function</i></dt>
<dd><p>Kernel to be used (One of: gaussian, cosine,
epanechnikov, uniform, triangular, biweight, logistic; default: gaussian)</p></dd>
</dl></dd>
</dl></dd>
<dt><a name="43"><b class="cmd">::math::statistics::bootstrap</b> <i class="arg">data</i> <i class="arg">sampleSize</i> <span class="opt">?numberSamples?</span></a></dt>
<dd><p>Create a subsample or subsamples from a given list of data. The data in the samples are chosen
from this list - multiples may occur. If there is only one subsample, the sample itself
is returned (as a list of "sampleSize" values), otherwise a list of samples is returned.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">data</i></dt>
<dd><p>List of values to chose from</p></dd>
<dt>int <i class="arg">sampleSize</i></dt>
<dd><p>Number of values per sample</p></dd>
<dt>int <i class="arg">numberSamples</i></dt>
<dd><p>Number of samples (default: 1)</p></dd>
</dl></dd>
<dt><a name="44"><b class="cmd">::math::statistics::wasserstein-distance</b> <i class="arg">prob1</i> <i class="arg">prob2</i></a></dt>
<dd><p>Compute the Wasserstein distance or earth mover's distance for two equidstantly spaced histograms
or probability densities. The histograms need not to be normalised to sum to one,
but they must have the same number of entries.</p>
<p>Note: the histograms are assumed to be based on the same equidistant intervals.
As the bounds are not passed, the value is expressed in the length of the intervals.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">prob1</i></dt>
<dd><p>List of values for the first histogram/probability density</p></dd>
<dt>list <i class="arg">prob2</i></dt>
<dd><p>List of values for the second histogram/probability density</p></dd>
</dl></dd>
<dt><a name="45"><b class="cmd">::math::statistics::kl-divergence</b> <i class="arg">prob1</i> <i class="arg">prob2</i></a></dt>
<dd><p>Compute the Kullback-Leibler (KL) divergence for two equidstantly spaced histograms
or probability densities. The histograms need not to be normalised to sum to one,
but they must have the same number of entries.</p>
<p>Note: the histograms are assumed to be based on the same equidistant intervals.
As the bounds are not passed, the value is expressed in the length of the intervals.</p>
<p>Note also that the KL divergence is not symmetric and that the second histogram
should not contain zeroes in places where the first histogram has non-zero values.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">prob1</i></dt>
<dd><p>List of values for the first histogram/probability density</p></dd>
<dt>list <i class="arg">prob2</i></dt>
<dd><p>List of values for the second histogram/probability density</p></dd>
</dl></dd>
<dt><a name="46"><b class="cmd">::math::statistics::logistic-model</b> <i class="arg">xdata</i> <i class="arg">ydata</i></a></dt>
<dd><p>Estimate the coefficients of the logistic model that fits the data best. The data consist
of independent x-values and the outcome 0 or 1 for each of the x-values. The result
can be used to estimate the probability that a certain x-value gives 1.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">xdata</i></dt>
<dd><p>List of values for which the success (1) or failure (0) is known</p></dd>
<dt>list <i class="arg">ydata</i></dt>
<dd><p>List of successes or failures corresponding to each value in <i class="term">xdata</i>.</p></dd>
</dl></dd>
<dt><a name="47"><b class="cmd">::math::statistics::logistic-probability</b> <i class="arg">coeffs</i> <i class="arg">x</i></a></dt>
<dd><p>Calculate the probability of success for the value <i class="term">x</i> given the coefficients of the
logistic model.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">coeffs</i></dt>
<dd><p>List of coefficients as determine by the <b class="cmd">logistic-model</b> command</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>X-value for which the probability needs to be determined</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">MULTIVARIATE LINEAR REGRESSION</a></h2>
<p>Besides the linear regression with a single independent variable, the
statistics package provides two procedures for doing ordinary
least squares (OLS) and weighted least squares (WLS) linear regression
with several variables. They were written by Eric Kemp-Benedict.</p>
<p>In addition to these two, it provides a procedure (tstat)
for calculating the value of the t-statistic for the specified number of
degrees of freedom that is required to demonstrate a given level of
significance.</p>
<p>Note: These procedures depend on the math::linearalgebra package.</p>
<p><em>Description of the procedures</em></p>
<dl class="doctools_definitions">
<dt><a name="48"><b class="cmd">::math::statistics::tstat</b> <i class="arg">dof</i> <span class="opt">?alpha?</span></a></dt>
<dd><p>Returns the value of the t-distribution t* satisfying</p>
<pre class="doctools_example">
P(t*) = 1 - alpha/2
P(-t*) = alpha/2
</pre>
<p>for the number of degrees of freedom dof.</p>
<p>Given a sample of normally-distributed data x, with an
estimate xbar for the mean and sbar for the standard deviation,
the alpha confidence interval for the estimate of the mean can
be calculated as</p>
<pre class="doctools_example">
( xbar - t* sbar , xbar + t* sbar)
</pre>
<p>The return values from this procedure can be compared to
an estimated t-statistic to determine whether the estimated
value of a parameter is significantly different from zero at
the given confidence level.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">dof</i></dt>
<dd><p>Number of degrees of freedom</p></dd>
<dt>float <i class="arg">alpha</i></dt>
<dd><p>Confidence level of the t-distribution. Defaults to 0.05.</p></dd>
</dl></dd>
<dt><a name="49"><b class="cmd">::math::statistics::mv-wls</b> <i class="arg">wt1</i> <i class="arg">weights_and_values</i></a></dt>
<dd><p>Carries out a weighted least squares linear regression for
the data points provided, with weights assigned to each point.</p>
<p>The linear model is of the form</p>
<pre class="doctools_example">
y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error
</pre>
<p>and each point satisfies</p>
<pre class="doctools_example">
yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i
</pre>
<p>The procedure returns a list with the following elements:</p>
<ul class="doctools_itemized">
<li><p>The r-squared statistic</p></li>
<li><p>The adjusted r-squared statistic</p></li>
<li><p>A list containing the estimated coefficients b1, ... bN, b0
(The constant b0 comes last in the list.)</p></li>
<li><p>A list containing the standard errors of the coefficients</p></li>
<li><p>A list containing the 95% confidence bounds of the coefficients,
with each set of bounds returned as a list with two values</p></li>
</ul>
<p>Arguments:</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">weights_and_values</i></dt>
<dd><p>A list consisting of: the weight for the first observation, the data
for the first observation (as a sublist), the weight for the second
observation (as a sublist) and so on. The sublists of data are organised
as lists of the value of the dependent variable y and the independent
variables x1, x2 to xN.</p></dd>
</dl></dd>
<dt><a name="50"><b class="cmd">::math::statistics::mv-ols</b> <i class="arg">values</i></a></dt>
<dd><p>Carries out an ordinary least squares linear regression for
the data points provided.</p>
<p>This procedure simply calls ::mvlinreg::wls with the weights
set to 1.0, and returns the same information.</p></dd>
</dl>
<p><em>Example of the use:</em></p>
<pre class="doctools_example">
# Store the value of the unicode value for the "+/-" character
set pm "\u00B1"
# Provide some data
set data {{ -.67 14.18 60.03 -7.5 }
{ 36.97 15.52 34.24 14.61 }
{-29.57 21.85 83.36 -7. }
{-16.9 11.79 51.67 -6.56 }
{ 14.09 16.24 36.97 -12.84}
{ 31.52 20.93 45.99 -25.4 }
{ 24.05 20.69 50.27 17.27}
{ 22.23 16.91 45.07 -4.3 }
{ 40.79 20.49 38.92 -.73 }
{-10.35 17.24 58.77 18.78}}
# Call the ols routine
set results [::math::statistics::mv-ols $data]
# Pretty-print the results
puts "R-squared: [lindex $results 0]"
puts "Adj R-squared: [lindex $results 1]"
puts "Coefficients $pm s.e. -- \[95% confidence interval\]:"
foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] {
set lb [lindex $bounds 0]
set ub [lindex $bounds 1]
puts " $val $pm $se -- \[$lb to $ub\]"
}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">STATISTICAL DISTRIBUTIONS</a></h2>
<p>In the literature a large number of probability distributions can be
found. The statistics package supports:</p>
<ul class="doctools_itemized">
<li><p>The normal or Gaussian distribution as well as the log-normal distribution</p></li>
<li><p>The uniform distribution - equal probability for all data within a given
interval</p></li>
<li><p>The exponential distribution - useful as a model for certain
extreme-value distributions.</p></li>
<li><p>The gamma distribution - based on the incomplete Gamma integral</p></li>
<li><p>The beta distribution</p></li>
<li><p>The chi-square distribution</p></li>
<li><p>The student's T distribution</p></li>
<li><p>The Poisson distribution</p></li>
<li><p>The Pareto distribution</p></li>
<li><p>The Gumbel distribution</p></li>
<li><p>The Weibull distribution</p></li>
<li><p>The Cauchy distribution</p></li>
<li><p>The F distribution (only the cumulative density function)</p></li>
<li><p>PM - binomial.</p></li>
</ul>
<p>In principle for each distribution one has procedures for:</p>
<ul class="doctools_itemized">
<li><p>The probability density (pdf-*)</p></li>
<li><p>The cumulative density (cdf-*)</p></li>
<li><p>Quantiles for the given distribution (quantiles-*)</p></li>
<li><p>Histograms for the given distribution (histogram-*)</p></li>
<li><p>List of random values with the given distribution (random-*)</p></li>
</ul>
<p>The following procedures have been implemented:</p>
<dl class="doctools_definitions">
<dt><a name="51"><b class="cmd">::math::statistics::pdf-normal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a normal distribution with
given mean and standard deviation.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="52"><b class="cmd">::math::statistics::pdf-lognormal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a log-normal distribution with
given mean and standard deviation.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="53"><b class="cmd">::math::statistics::pdf-exponential</b> <i class="arg">mean</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for an exponential
distribution with given mean.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="54"><b class="cmd">::math::statistics::pdf-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a uniform
distribution with given extremes.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Minimum value of the distribution</p></dd>
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Maximum value of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="55"><b class="cmd">::math::statistics::pdf-gamma</b> <i class="arg">alpha</i> <i class="arg">beta</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Gamma
distribution with given shape and rate parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">beta</i></dt>
<dd><p>- Rate parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="56"><b class="cmd">::math::statistics::pdf-poisson</b> <i class="arg">mu</i> <i class="arg">k</i></a></dt>
<dd><p>Return the probability of a given number of occurrences in the same
interval (k) for a Poisson distribution with given mean (mu)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mu</i></dt>
<dd><p>- Mean number of occurrences</p></dd>
<dt>int <i class="arg">k</i></dt>
<dd><p>- Number of occurences</p></dd>
</dl></dd>
<dt><a name="57"><b class="cmd">::math::statistics::pdf-chisquare</b> <i class="arg">df</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a chi square
distribution with given degrees of freedom</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">df</i></dt>
<dd><p>- Degrees of freedom</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="58"><b class="cmd">::math::statistics::pdf-student-t</b> <i class="arg">df</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Student's t
distribution with given degrees of freedom</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">df</i></dt>
<dd><p>- Degrees of freedom</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="59"><b class="cmd">::math::statistics::pdf-gamma</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Gamma
distribution with given shape and rate parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">a</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">b</i></dt>
<dd><p>- Rate parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="60"><b class="cmd">::math::statistics::pdf-beta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Beta
distribution with given shape parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">a</i></dt>
<dd><p>- First shape parameter</p></dd>
<dt>float <i class="arg">b</i></dt>
<dd><p>- Second shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="61"><b class="cmd">::math::statistics::pdf-weibull</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Weibull
distribution with given scale and shape parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="62"><b class="cmd">::math::statistics::pdf-gumbel</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Gumbel
distribution with given location and shape parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Location parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="63"><b class="cmd">::math::statistics::pdf-pareto</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Pareto
distribution with given scale and shape parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">shape</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="64"><b class="cmd">::math::statistics::pdf-cauchy</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></dt>
<dd><p>Return the probability of a given value for a Cauchy
distribution with given location and shape parameters. Note that the Cauchy distribution
has no finite higher-order moments.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Location parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="65"><b class="cmd">::math::statistics::cdf-normal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a normal
distribution with given mean and standard deviation, that is the
probability for values up to the given one.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="66"><b class="cmd">::math::statistics::cdf-lognormal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a log-normal
distribution with given mean and standard deviation, that is the
probability for values up to the given one.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="67"><b class="cmd">::math::statistics::cdf-exponential</b> <i class="arg">mean</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for an exponential
distribution with given mean.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="68"><b class="cmd">::math::statistics::cdf-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a uniform
distribution with given extremes.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Minimum value of the distribution</p></dd>
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Maximum value of the distribution</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="69"><b class="cmd">::math::statistics::cdf-students-t</b> <i class="arg">degrees</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Student's t
distribution with given number of degrees.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">degrees</i></dt>
<dd><p>- Number of degrees of freedom</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="70"><b class="cmd">::math::statistics::cdf-gamma</b> <i class="arg">alpha</i> <i class="arg">beta</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Gamma
distribution with given shape and rate parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">beta</i></dt>
<dd><p>- Rate parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the cumulative probability is required</p></dd>
</dl></dd>
<dt><a name="71"><b class="cmd">::math::statistics::cdf-poisson</b> <i class="arg">mu</i> <i class="arg">k</i></a></dt>
<dd><p>Return the cumulative probability of a given number of occurrences in
the same interval (k) for a Poisson distribution with given mean (mu).</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mu</i></dt>
<dd><p>- Mean number of occurrences</p></dd>
<dt>int <i class="arg">k</i></dt>
<dd><p>- Number of occurences</p></dd>
</dl></dd>
<dt><a name="72"><b class="cmd">::math::statistics::cdf-beta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Beta
distribution with given shape parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">a</i></dt>
<dd><p>- First shape parameter</p></dd>
<dt>float <i class="arg">b</i></dt>
<dd><p>- Second shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="73"><b class="cmd">::math::statistics::cdf-weibull</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Weibull
distribution with given scale and shape parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">shape</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="74"><b class="cmd">::math::statistics::cdf-gumbel</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Gumbel
distribution with given location and scale parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Location parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="75"><b class="cmd">::math::statistics::cdf-pareto</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Pareto
distribution with given scale and shape parameters</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">shape</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="76"><b class="cmd">::math::statistics::cdf-cauchy</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for a Cauchy
distribution with given location and scale parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Location parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="77"><b class="cmd">::math::statistics::cdf-F</b> <i class="arg">nf1</i> <i class="arg">nf2</i> <i class="arg">value</i></a></dt>
<dd><p>Return the cumulative probability of a given value for an F
distribution with nf1 and nf2 degrees of freedom.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">nf1</i></dt>
<dd><p>- Degrees of freedom for the numerator</p></dd>
<dt>float <i class="arg">nf2</i></dt>
<dd><p>- Degrees of freedom for the denominator</p></dd>
<dt>float <i class="arg">value</i></dt>
<dd><p>- Value for which the probability is required</p></dd>
</dl></dd>
<dt><a name="78"><b class="cmd">::math::statistics::empirical-distribution</b> <i class="arg">values</i></a></dt>
<dd><p>Return a list of values and their empirical probability. The values are sorted in increasing order.
(The implementation follows the description at the corresponding Wikipedia page)</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">values</i></dt>
<dd><p>- List of data to be examined</p></dd>
</dl></dd>
<dt><a name="79"><b class="cmd">::math::statistics::random-normal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying a normal
distribution with given mean and standard deviation.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation of the distribution</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="80"><b class="cmd">::math::statistics::random-lognormal</b> <i class="arg">mean</i> <i class="arg">stdev</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying a log-normal
distribution with given mean and standard deviation.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>- Standard deviation of the distribution</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="81"><b class="cmd">::math::statistics::random-exponential</b> <i class="arg">mean</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying an exponential
distribution with given mean.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>- Mean value of the distribution</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="82"><b class="cmd">::math::statistics::random-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying a uniform
distribution with given extremes.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Minimum value of the distribution</p></dd>
<dt>float <i class="arg">xmax</i></dt>
<dd><p>- Maximum value of the distribution</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="83"><b class="cmd">::math::statistics::random-gamma</b> <i class="arg">alpha</i> <i class="arg">beta</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Gamma distribution with given shape and rate parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">alpha</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>float <i class="arg">beta</i></dt>
<dd><p>- Rate parameter</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="84"><b class="cmd">::math::statistics::random-poisson</b> <i class="arg">mu</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Poisson distribution with given mean.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mu</i></dt>
<dd><p>- Mean of the distribution</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="85"><b class="cmd">::math::statistics::random-chisquare</b> <i class="arg">df</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a chi square distribution with given degrees of freedom.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">df</i></dt>
<dd><p>- Degrees of freedom</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="86"><b class="cmd">::math::statistics::random-student-t</b> <i class="arg">df</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Student's t distribution with given degrees of freedom.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">df</i></dt>
<dd><p>- Degrees of freedom</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="87"><b class="cmd">::math::statistics::random-beta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Beta distribution with given shape parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">a</i></dt>
<dd><p>- First shape parameter</p></dd>
<dt>float <i class="arg">b</i></dt>
<dd><p>- Second shape parameter</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="88"><b class="cmd">::math::statistics::random-weibull</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Weibull distribution with given scale and shape parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">shape</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="89"><b class="cmd">::math::statistics::random-gumbel</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Gumbel distribution with given location and scale parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Location parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="90"><b class="cmd">::math::statistics::random-pareto</b> <i class="arg">scale</i> <i class="arg">shape</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Pareto distribution with given scale and shape parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>float <i class="arg">shape</i></dt>
<dd><p>- Shape parameter</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="91"><b class="cmd">::math::statistics::random-cauchy</b> <i class="arg">location</i> <i class="arg">scale</i> <i class="arg">number</i></a></dt>
<dd><p>Return a list of "number" random values satisfying
a Cauchy distribution with given location and scale parameters.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">location</i></dt>
<dd><p>- Location parameter</p></dd>
<dt>float <i class="arg">scale</i></dt>
<dd><p>- Scale parameter</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Number of values to be returned</p></dd>
</dl></dd>
<dt><a name="92"><b class="cmd">::math::statistics::histogram-uniform</b> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">limits</i> <i class="arg">number</i></a></dt>
<dd><p>Return the expected histogram for a uniform distribution.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Minimum value of the distribution</p></dd>
<dt>float <i class="arg">xmax</i></dt>
<dd><p>- Maximum value of the distribution</p></dd>
<dt>list <i class="arg">limits</i></dt>
<dd><p>- Upper limits for the buckets in the histogram</p></dd>
<dt>int <i class="arg">number</i></dt>
<dd><p>- Total number of "observations" in the histogram</p></dd>
</dl></dd>
<dt><a name="93"><b class="cmd">::math::statistics::incompleteGamma</b> <i class="arg">x</i> <i class="arg">p</i> <span class="opt">?tol?</span></a></dt>
<dd><p>Evaluate the incomplete Gamma integral</p>
<pre class="doctools_example">
1 / x p-1
P(p,x) = -------- | dt exp(-t) * t
Gamma(p) / 0
</pre>
<dl class="doctools_arguments">
<dt>float <i class="arg">x</i></dt>
<dd><p>- Value of x (limit of the integral)</p></dd>
<dt>float <i class="arg">p</i></dt>
<dd><p>- Value of p in the integrand</p></dd>
<dt>float <i class="arg">tol</i></dt>
<dd><p>- Required tolerance (default: 1.0e-9)</p></dd>
</dl></dd>
<dt><a name="94"><b class="cmd">::math::statistics::incompleteBeta</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">x</i> <span class="opt">?tol?</span></a></dt>
<dd><p>Evaluate the incomplete Beta integral</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">a</i></dt>
<dd><p>- First shape parameter</p></dd>
<dt>float <i class="arg">b</i></dt>
<dd><p>- Second shape parameter</p></dd>
<dt>float <i class="arg">x</i></dt>
<dd><p>- Value of x (limit of the integral)</p></dd>
<dt>float <i class="arg">tol</i></dt>
<dd><p>- Required tolerance (default: 1.0e-9)</p></dd>
</dl></dd>
<dt><a name="95"><b class="cmd">::math::statistics::estimate-pareto</b> <i class="arg">values</i></a></dt>
<dd><p>Estimate the parameters for the Pareto distribution that comes closest to the given values.
Returns the estimated scale and shape parameters, as well as the standard error for the shape parameter.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">values</i></dt>
<dd><p>- List of values, assumed to be distributed according to a Pareto distribution</p></dd>
</dl></dd>
</dl>
<p>TO DO: more function descriptions to be added</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">DATA MANIPULATION</a></h2>
<p>The data manipulation procedures act on lists or lists of lists:</p>
<dl class="doctools_definitions">
<dt><a name="96"><b class="cmd">::math::statistics::filter</b> <i class="arg">varname</i> <i class="arg">data</i> <i class="arg">expression</i></a></dt>
<dd><p>Return a list consisting of the data for which the logical
expression is true (this command works analogously to the command <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b>).</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">varname</i></dt>
<dd><p>- Name of the variable used in the expression</p></dd>
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
<dt>string <i class="arg">expression</i></dt>
<dd><p>- Logical expression using the variable name</p></dd>
</dl></dd>
<dt><a name="97"><b class="cmd">::math::statistics::map</b> <i class="arg">varname</i> <i class="arg">data</i> <i class="arg">expression</i></a></dt>
<dd><p>Return a list consisting of the data that are transformed via the
expression.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">varname</i></dt>
<dd><p>- Name of the variable used in the expression</p></dd>
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of data</p></dd>
<dt>string <i class="arg">expression</i></dt>
<dd><p>- Expression to be used to transform (map) the data</p></dd>
</dl></dd>
<dt><a name="98"><b class="cmd">::math::statistics::samplescount</b> <i class="arg">varname</i> <i class="arg">list</i> <i class="arg">expression</i></a></dt>
<dd><p>Return a list consisting of the <i class="term">counts</i> of all data in the
sublists of the "list" argument for which the expression is true.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">varname</i></dt>
<dd><p>- Name of the variable used in the expression</p></dd>
<dt>list <i class="arg">data</i></dt>
<dd><p>- List of sublists, each containing the data</p></dd>
<dt>string <i class="arg">expression</i></dt>
<dd><p>- Logical expression to test the data (defaults to
"true").</p></dd>
</dl></dd>
<dt><a name="99"><b class="cmd">::math::statistics::subdivide</b></a></dt>
<dd><p>Routine <em>PM</em> - not implemented yet</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PLOT PROCEDURES</a></h2>
<p>The following simple plotting procedures are available:</p>
<dl class="doctools_definitions">
<dt><a name="100"><b class="cmd">::math::statistics::plot-scale</b> <i class="arg">canvas</i> <i class="arg">xmin</i> <i class="arg">xmax</i> <i class="arg">ymin</i> <i class="arg">ymax</i></a></dt>
<dd><p>Set the scale for a plot in the given canvas. All plot routines expect
this function to be called first. There is no automatic scaling
provided.</p>
<dl class="doctools_arguments">
<dt>widget <i class="arg">canvas</i></dt>
<dd><p>- Canvas widget to use</p></dd>
<dt>float <i class="arg">xmin</i></dt>
<dd><p>- Minimum x value</p></dd>
<dt>float <i class="arg">xmax</i></dt>
<dd><p>- Maximum x value</p></dd>
<dt>float <i class="arg">ymin</i></dt>
<dd><p>- Minimum y value</p></dd>
<dt>float <i class="arg">ymax</i></dt>
<dd><p>- Maximum y value</p></dd>
</dl></dd>
<dt><a name="101"><b class="cmd">::math::statistics::plot-xydata</b> <i class="arg">canvas</i> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">tag</i></a></dt>
<dd><p>Create a simple XY plot in the given canvas - the data are
shown as a collection of dots. The tag can be used to manipulate the
appearance.</p>
<dl class="doctools_arguments">
<dt>widget <i class="arg">canvas</i></dt>
<dd><p>- Canvas widget to use</p></dd>
<dt>float <i class="arg">xdata</i></dt>
<dd><p>- Series of independent data</p></dd>
<dt>float <i class="arg">ydata</i></dt>
<dd><p>- Series of dependent data</p></dd>
<dt>string <i class="arg">tag</i></dt>
<dd><p>- Tag to give to the plotted data (defaults to xyplot)</p></dd>
</dl></dd>
<dt><a name="102"><b class="cmd">::math::statistics::plot-xyline</b> <i class="arg">canvas</i> <i class="arg">xdata</i> <i class="arg">ydata</i> <i class="arg">tag</i></a></dt>
<dd><p>Create a simple XY plot in the given canvas - the data are
shown as a line through the data points. The tag can be used to
manipulate the appearance.</p>
<dl class="doctools_arguments">
<dt>widget <i class="arg">canvas</i></dt>
<dd><p>- Canvas widget to use</p></dd>
<dt>list <i class="arg">xdata</i></dt>
<dd><p>- Series of independent data</p></dd>
<dt>list <i class="arg">ydata</i></dt>
<dd><p>- Series of dependent data</p></dd>
<dt>string <i class="arg">tag</i></dt>
<dd><p>- Tag to give to the plotted data (defaults to xyplot)</p></dd>
</dl></dd>
<dt><a name="103"><b class="cmd">::math::statistics::plot-tdata</b> <i class="arg">canvas</i> <i class="arg">tdata</i> <i class="arg">tag</i></a></dt>
<dd><p>Create a simple XY plot in the given canvas - the data are
shown as a collection of dots. The horizontal coordinate is equal to the
index. The tag can be used to manipulate the appearance.
This type of presentation is suitable for autocorrelation functions for
instance or for inspecting the time-dependent behaviour.</p>
<dl class="doctools_arguments">
<dt>widget <i class="arg">canvas</i></dt>
<dd><p>- Canvas widget to use</p></dd>
<dt>list <i class="arg">tdata</i></dt>
<dd><p>- Series of dependent data</p></dd>
<dt>string <i class="arg">tag</i></dt>
<dd><p>- Tag to give to the plotted data (defaults to xyplot)</p></dd>
</dl></dd>
<dt><a name="104"><b class="cmd">::math::statistics::plot-tline</b> <i class="arg">canvas</i> <i class="arg">tdata</i> <i class="arg">tag</i></a></dt>
<dd><p>Create a simple XY plot in the given canvas - the data are
shown as a line. See plot-tdata for an explanation.</p>
<dl class="doctools_arguments">
<dt>widget <i class="arg">canvas</i></dt>
<dd><p>- Canvas widget to use</p></dd>
<dt>list <i class="arg">tdata</i></dt>
<dd><p>- Series of dependent data</p></dd>
<dt>string <i class="arg">tag</i></dt>
<dd><p>- Tag to give to the plotted data (defaults to xyplot)</p></dd>
</dl></dd>
<dt><a name="105"><b class="cmd">::math::statistics::plot-histogram</b> <i class="arg">canvas</i> <i class="arg">counts</i> <i class="arg">limits</i> <i class="arg">tag</i></a></dt>
<dd><p>Create a simple histogram in the given canvas</p>
<dl class="doctools_arguments">
<dt>widget <i class="arg">canvas</i></dt>
<dd><p>- Canvas widget to use</p></dd>
<dt>list <i class="arg">counts</i></dt>
<dd><p>- Series of bucket counts</p></dd>
<dt>list <i class="arg">limits</i></dt>
<dd><p>- Series of upper limits for the buckets</p></dd>
<dt>string <i class="arg">tag</i></dt>
<dd><p>- Tag to give to the plotted data (defaults to xyplot)</p></dd>
</dl></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">THINGS TO DO</a></h2>
<p>The following procedures are yet to be implemented:</p>
<ul class="doctools_itemized">
<li><p>F-test-stdev</p></li>
<li><p>interval-mean-stdev</p></li>
<li><p>histogram-normal</p></li>
<li><p>histogram-exponential</p></li>
<li><p>test-histogram</p></li>
<li><p>test-corr</p></li>
<li><p>quantiles-*</p></li>
<li><p>fourier-coeffs</p></li>
<li><p>fourier-residuals</p></li>
<li><p>onepar-function-fit</p></li>
<li><p>onepar-function-residuals</p></li>
<li><p>plot-linear-model</p></li>
<li><p>subdivide</p></li>
</ul>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">EXAMPLES</a></h2>
<p>The code below is a small example of how you can examine a set of
data:</p>
<pre class="doctools_example">
# Simple example:
# - Generate data (as a cheap way of getting some)
# - Perform statistical analysis to describe the data
#
package require math::statistics
#
# Two auxiliary procs
#
proc pause {time} {
set wait 0
after [expr {$time*1000}] {set ::wait 1}
vwait wait
}
proc print-histogram {counts limits} {
foreach count $counts limit $limits {
if { $limit != {} } {
puts [format "<%12.4g\t%d" $limit $count]
set prev_limit $limit
} else {
puts [format ">%12.4g\t%d" $prev_limit $count]
}
}
}
#
# Our source of arbitrary data
#
proc generateData { data1 data2 } {
upvar 1 $data1 _data1
upvar 1 $data2 _data2
set d1 0.0
set d2 0.0
for { set i 0 } { $i < 100 } { incr i } {
set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}]
set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}]
lappend _data1 $d1
lappend _data2 $d2
}
return {}
}
#
# The analysis session
#
package require Tk
console show
canvas .plot1
canvas .plot2
pack .plot1 .plot2 -fill both -side top
generateData data1 data2
puts "Basic statistics:"
set b1 [::math::statistics::basic-stats $data1]
set b2 [::math::statistics::basic-stats $data2]
foreach label {mean min max number stdev var} v1 $b1 v2 $b2 {
puts "$label\t$v1\t$v2"
}
puts "Plot the data as function of \"time\" and against each other"
::math::statistics::plot-scale .plot1 0 100 0 20
::math::statistics::plot-scale .plot2 0 20 0 20
::math::statistics::plot-tline .plot1 $data1
::math::statistics::plot-tline .plot1 $data2
::math::statistics::plot-xydata .plot2 $data1 $data2
puts "Correlation coefficient:"
puts [::math::statistics::corr $data1 $data2]
pause 2
puts "Plot histograms"
.plot2 delete all
::math::statistics::plot-scale .plot2 0 20 0 100
set limits [::math::statistics::minmax-histogram-limits 7 16]
set histogram_data [::math::statistics::histogram $limits $data1]
::math::statistics::plot-histogram .plot2 $histogram_data $limits
puts "First series:"
print-histogram $histogram_data $limits
pause 2
set limits [::math::statistics::minmax-histogram-limits 0 15 10]
set histogram_data [::math::statistics::histogram $limits $data2]
::math::statistics::plot-histogram .plot2 $histogram_data $limits d2
.plot2 itemconfigure d2 -fill red
puts "Second series:"
print-histogram $histogram_data $limits
puts "Autocorrelation function:"
set autoc [::math::statistics::autocorr $data1]
puts [::math::statistics::map $autoc {[format "%.2f" $x]}]
puts "Cross-correlation function:"
set crossc [::math::statistics::crosscorr $data1 $data2]
puts [::math::statistics::map $crossc {[format "%.2f" $x]}]
::math::statistics::plot-scale .plot1 0 100 -1 4
::math::statistics::plot-tline .plot1 $autoc "autoc"
::math::statistics::plot-tline .plot1 $crossc "crossc"
.plot1 itemconfigure autoc -fill green
.plot1 itemconfigure crossc -fill yellow
puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9"
puts "First: [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]"
puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]"
</pre>
<p>If you run this example, then the following should be clear:</p>
<ul class="doctools_itemized">
<li><p>There is a strong correlation between two time series, as displayed by
the raw data and especially by the correlation functions.</p></li>
<li><p>Both time series show a significant periodic component</p></li>
<li><p>The histograms are not very useful in identifying the nature of the time
series - they do not show the periodic nature.</p></li>
</ul>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: statistics</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_analysis">data analysis</a>, <a href="../../../../index.html#mathematics">mathematics</a>, <a href="../../../../index.html#statistics">statistics</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/symdiff.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
<div class='fossil-doc' data-title='math::calculus::symdiff - Symbolic differentiation for Tcl'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::calculus::symdiff(n) 1.0.1 tcllib "Symbolic differentiation for Tcl"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::calculus::symdiff - Symbolic differentiation for Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Procedures</a></li>
<li class="doctools_section"><a href="#section3">Expressions</a></li>
<li class="doctools_section"><a href="#section4">Examples</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">grammar::aycock 1.0</b></li>
<li>package require <b class="pkgname">math::calculus::symdiff 1.0.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">math::calculus::symdiff::symdiff</b> <i class="arg">expression</i> <i class="arg">variable</i></a></li>
<li><a href="#2"><b class="cmd">math::calculus::jacobian</b> <i class="arg">variableDict</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">math::calculus::symdiff</b> package provides a symbolic differentiation
facility for Tcl math expressions. It is useful for providing derivatives
to packages that either require the Jacobian of a set of functions or else
are more efficient or stable when the Jacobian is provided.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Procedures</a></h2>
<p>The <b class="cmd">math::calculus::symdiff</b> package exports the two procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">math::calculus::symdiff::symdiff</b> <i class="arg">expression</i> <i class="arg">variable</i></a></dt>
<dd><p>Differentiates the given <i class="arg">expression</i> with respect to the specified
<i class="arg">variable</i>. (See <span class="sectref"><a href="#section3">Expressions</a></span> below for a discussion of the
subset of Tcl math expressions that are acceptable to
<b class="cmd">math::calculus::symdiff</b>.)
The result is a Tcl expression that evaluates the derivative. Returns an
error if <i class="arg">expression</i> is not a well-formed expression or is not
differentiable.</p></dd>
<dt><a name="2"><b class="cmd">math::calculus::jacobian</b> <i class="arg">variableDict</i></a></dt>
<dd><p>Computes the Jacobian of a system of equations.
The system is given by the dictionary <i class="arg">variableDict</i>, whose keys
are the names of variables in the system, and whose values are Tcl expressions
giving the values of those variables. (See <span class="sectref"><a href="#section3">Expressions</a></span> below
for a discussion of the subset of Tcl math expressions that are acceptable
to <b class="cmd">math::calculus::symdiff</b>. The result is a list of lists:
the i'th element of the j'th sublist is the partial derivative of
the i'th variable with respect to the j'th variable. Returns an error if
any of the expressions cannot be differentiated, or if <i class="arg">variableDict</i>
is not a well-formed dictionary.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Expressions</a></h2>
<p>The <b class="cmd">math::calculus::symdiff</b> package accepts only a small subset of the expressions
that are acceptable to Tcl commands such as <b class="cmd">expr</b> or <b class="cmd">if</b>.
Specifically, the only constructs accepted are:</p>
<ul class="doctools_itemized">
<li><p>Floating-point constants such as <b class="const">5</b> or <b class="const">3.14159e+00</b>.</p></li>
<li><p>References to Tcl variable using $-substitution. The variable names
must consist of alphanumerics and underscores: the <b class="const">${...}</b> notation
is not accepted.</p></li>
<li><p>Parentheses.</p></li>
<li><p>The <b class="const">+</b>, <b class="const">-</b>, <b class="const">*</b>, <b class="const">/</b>. and <b class="const">**</b>
operators.</p></li>
<li><p>Calls to the functions <b class="cmd">acos</b>, <b class="cmd">asin</b>, <b class="cmd">atan</b>,
<b class="cmd">atan2</b>, <b class="cmd">cos</b>, <b class="cmd">cosh</b>, <b class="cmd">exp</b>, <b class="cmd">hypot</b>, <b class="cmd"><a href="../log/log.html">log</a></b>,
<b class="cmd">log10</b>, <b class="cmd">pow</b>, <b class="cmd">sin</b>, <b class="cmd">sinh</b>. <b class="cmd">sqrt</b>, <b class="cmd">tan</b>,
and <b class="cmd">tanh</b>.</p></li>
</ul>
<p>Command substitution, backslash substitution, and argument expansion are
not accepted.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Examples</a></h2>
<pre class="doctools_example">
math::calculus::symdiff::symdiff {($a*$x+$b)*($c*$x+$d)} x
==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d)))
math::calculus::symdiff::jacobian {x {$a * $x + $b * $y}
y {$c * $x + $d * $y}}
==> {{$a} {$b}} {{$c} {$d}}
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: calculus</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="calculus.html">math::calculus</a>, <a href="interpolate.html">math::interpolate</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010 by Kevin B. Kenny <[email protected]><br>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/math/trig.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
|
<div class='fossil-doc' data-title='math::trig - Tcl Math Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::trig(n) 1.0.0 tcllib "Tcl Math Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::trig - Trigonometric anf hyperbolic functions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">FUNCTIONS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">math::trig 1.0.0</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::trig::radian_reduced</b> <i class="arg">angle</i></a></li>
<li><a href="#2"><b class="cmd">::math::trig::degree_reduced</b> <i class="arg">angle</i></a></li>
<li><a href="#3"><b class="cmd">::math::trig::cosec</b> <i class="arg">angle</i></a></li>
<li><a href="#4"><b class="cmd">::math::trig::sec</b> <i class="arg">angle</i></a></li>
<li><a href="#5"><b class="cmd">::math::trig::cotan</b> <i class="arg">angle</i></a></li>
<li><a href="#6"><b class="cmd">::math::trig::acosec</b> <i class="arg">value</i></a></li>
<li><a href="#7"><b class="cmd">::math::trig::asec</b> <i class="arg">value</i></a></li>
<li><a href="#8"><b class="cmd">::math::trig::acotan</b> <i class="arg">value</i></a></li>
<li><a href="#9"><b class="cmd">::math::trig::cosech</b> <i class="arg">value</i></a></li>
<li><a href="#10"><b class="cmd">::math::trig::sech</b> <i class="arg">value</i></a></li>
<li><a href="#11"><b class="cmd">::math::trig::cotanh</b> <i class="arg">value</i></a></li>
<li><a href="#12"><b class="cmd">::math::trig::asinh</b> <i class="arg">value</i></a></li>
<li><a href="#13"><b class="cmd">::math::trig::acosh</b> <i class="arg">value</i></a></li>
<li><a href="#14"><b class="cmd">::math::trig::atanh</b> <i class="arg">value</i></a></li>
<li><a href="#15"><b class="cmd">::math::trig::acosech</b> <i class="arg">value</i></a></li>
<li><a href="#16"><b class="cmd">::math::trig::asech</b> <i class="arg">value</i></a></li>
<li><a href="#17"><b class="cmd">::math::trig::acotanh</b> <i class="arg">value</i></a></li>
<li><a href="#18"><b class="cmd">::math::trig::sind</b> <i class="arg">angle</i></a></li>
<li><a href="#19"><b class="cmd">::math::trig::cosd</b> <i class="arg">angle</i></a></li>
<li><a href="#20"><b class="cmd">::math::trig::tand</b> <i class="arg">angle</i></a></li>
<li><a href="#21"><b class="cmd">::math::trig::cosecd</b> <i class="arg">angle</i></a></li>
<li><a href="#22"><b class="cmd">::math::trig::secd</b> <i class="arg">angle</i></a></li>
<li><a href="#23"><b class="cmd">::math::trig::cotand</b> <i class="arg">angle</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <i class="term">math::trig</i> package defines a set of trigonomic and hyperbolic functions
and their inverses. In addition it defines versions of the trigonomic functions
that take arguments in degrees instead of radians.</p>
<p>For easy use these functions may be imported into the <i class="term">tcl::mathfunc</i> namespace,
so that they can be used directly in the <i class="term">expr</i> command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">FUNCTIONS</a></h2>
<p>The functions <i class="term">radian_reduced</i> and <i class="term">degree_reduced</i> return a reduced angle, in
respectively radians and degrees, in the intervals [0, 2pi) and [0, 360):</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::trig::radian_reduced</b> <i class="arg">angle</i></a></dt>
<dd><p>Return the equivalent angle in the interval [0, 2pi).</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in radians)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::math::trig::degree_reduced</b> <i class="arg">angle</i></a></dt>
<dd><p>Return the equivalent angle in the interval [0, 360).</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in degrees)</p></dd>
</dl></dd>
</dl>
<p>The following trigonomic functions are defined in addition to the ones defined
in the <i class="term">expr</i> command:</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::math::trig::cosec</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the cosecant of the angle (1/cos(angle))</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in radians)</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::math::trig::sec</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the secant of the angle (1/sin(angle))</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in radians)</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::math::trig::cotan</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the cotangent of the angle (1/tan(angle))</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in radians)</p></dd>
</dl></dd>
</dl>
<p>For these functions also the inverses are defined:</p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="cmd">::math::trig::acosec</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc cosecant of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::math::trig::asec</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc secant of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::math::trig::acotan</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc cotangent of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
</dl>
<p>The following hyperbolic and inverse hyperbolic functions are defined:</p>
<dl class="doctools_definitions">
<dt><a name="9"><b class="cmd">::math::trig::cosech</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the hyperbolic cosecant of the value (1/sinh(value))</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::math::trig::sech</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the hyperbolic secant of the value (1/cosh(value))</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::math::trig::cotanh</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the hyperbolic cotangent of the value (1/tanh(value))</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::math::trig::asinh</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc hyperbolic sine of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::math::trig::acosh</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc hyperbolic cosine of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::math::trig::atanh</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc hyperbolic tangent of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::math::trig::acosech</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc hyperbolic cosecant of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::math::trig::asech</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc hyperbolic secant of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">::math::trig::acotanh</b> <i class="arg">value</i></a></dt>
<dd><p>Calculate the arc hyperbolic cotangent of the value</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">value</i></dt>
<dd><p>Value of the argument</p></dd>
</dl></dd>
</dl>
<p>The following versions of the common trigonometric functions and their
inverses are defined:</p>
<dl class="doctools_definitions">
<dt><a name="18"><b class="cmd">::math::trig::sind</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the sine of the angle (in degrees)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in degrees)</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">::math::trig::cosd</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the cosine of the angle (in degrees)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in radians)</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">::math::trig::tand</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the cotangent of the angle (in degrees)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in degrees)</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">::math::trig::cosecd</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the cosecant of the angle (in degrees)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in degrees)</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">::math::trig::secd</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the secant of the angle (in degrees)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in degrees)</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">::math::trig::cotand</b> <i class="arg">angle</i></a></dt>
<dd><p>Calculate the cotangent of the angle (in degrees)</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">angle</i></dt>
<dd><p>Angle (in degrees)</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>math :: trig</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#trigonometry">trigonometry</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2018 Arjen Markus</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/md4/md4.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
<div class='fossil-doc' data-title='md4 - MD4 Message-Digest Algorithm'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">md4(n) 1.0.7 tcllib "MD4 Message-Digest Algorithm"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>md4 - MD4 Message-Digest Algorithm</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">md4 <span class="opt">?1.0.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::md4::md4</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::md4::hmac</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#3"><b class="cmd">::md4::MD4Init</b></a></li>
<li><a href="#4"><b class="cmd">::md4::MD4Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::md4::MD4Final</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::md4::HMACInit</b> <i class="arg">key</i></a></li>
<li><a href="#7"><b class="cmd">::md4::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::md4::HMACFinal</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the MD4 message-digest
algorithm as described in RFC 1320 (1) and (2). This algorithm takes
an arbitrary quantity of data and generates a 128-bit message digest
from the input. The MD4 algorithm is faster but potentially weaker than
the related MD5 algorithm (3).</p>
<p>If you have <b class="package">critcl</b> and have built the <b class="package">tcllibc</b> package
then the implementation of the hashing function will be performed by compiled
code. Alternatively if <b class="package">cryptkit</b> is available this will be
used. If no accelerator package can be found then the pure-tcl
implementation is used. The programming interface remains the same in
all cases.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::md4::md4</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate the MD4 digest of the data given in string. This is returned
as a binary string by default. Giving the <i class="arg">-hex</i> option will
return a hexadecimal encoded version of the digest.</p>
<p>The data to be hashed can be specified either as a string argument to
the md4 command, or as a filename or a pre-opened channel. If the
<i class="arg">-filename</i> argument is given then the file is opened, the data read
and hashed and the file is closed. If the <i class="arg">-channel</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed.</p>
<p>Only one of <i class="arg">-file</i>, <i class="arg">-channel</i> or <i class="arg">string</i> should be given.</p></dd>
<dt><a name="2"><b class="cmd">::md4::hmac</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate an Hashed Message Authentication digest (HMAC) using the MD4
digest algorithm. HMACs are described in RFC 2104 (4) and provide an MD4
digest that includes a key. All options other than <i class="arg">-key</i> are as
for the <b class="cmd">::md4::md4</b> command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>For the programmer, the MD4 hash can be viewed as a bucket into which
one pours data. When you have finished, you extract a value that is
derived from the data that was poured into the bucket. The programming
interface to the MD4 hash operates on a token (equivalent to the
bucket). You call <b class="cmd">MD4Init</b> to obtain a token and then call
<b class="cmd">MD4Update</b> as many times as required to add data to the hash. To
release any resources and obtain the hash value, you then call
<b class="cmd">MD4Final</b>. An equivalent set of functions gives you a keyed digest (HMAC).</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::md4::MD4Init</b></a></dt>
<dd><p>Begins a new MD4 hash. Returns a token ID that must be used for the
remaining functions.</p></dd>
<dt><a name="4"><b class="cmd">::md4::MD4Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the hash identified by token. Calling
<em>MD4Update $token "abcd"</em> is equivalent to calling
<em>MD4Update $token "ab"</em> followed by
<em>MD4Update $token "cb"</em>. See <span class="sectref"><a href="#section4">EXAMPLES</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::md4::MD4Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the hash value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a binary string of 16 bytes representing the 128 bit MD4
digest value.</p></dd>
<dt><a name="6"><b class="cmd">::md4::HMACInit</b> <i class="arg">key</i></a></dt>
<dd><p>This is equivalent to the <b class="cmd">::md4::MD4Init</b> command except that
it requires the key that will be included in the HMAC.</p></dd>
<dt><a name="7"><b class="cmd">::md4::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="8"><b class="cmd">::md4::HMACFinal</b> <i class="arg">token</i></a></dt>
<dd><p>These commands are identical to the MD4 equivalent commands.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% md4::md4 -hex "Tcl does MD4"
858da9b31f57648a032230447bd15f25
</pre>
<pre class="doctools_example">
% md4::hmac -hex -key Sekret "Tcl does MD4"
c324088e5752872689caedf2a0464758
</pre>
<pre class="doctools_example">
% set tok [md4::MD4Init]
::md4::1
% md4::MD4Update $tok "Tcl "
% md4::MD4Update $tok "does "
% md4::MD4Update $tok "MD4"
% md4::Hex [md4::MD4Final $tok]
858da9b31f57648a032230447bd15f25
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes
and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90
Proceedings, pages 303-311, Springer-Verlag, 1991.</p></li>
<li><p>Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and
RSA Data Security, Inc, April 1992.
(<a href="http://www.rfc-editor.org/rfc/rfc1321.txt">http://www.rfc-editor.org/rfc/rfc1321.txt</a>)</p></li>
<li><p>Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
Message Authentication", RFC 2104, February 1997.
(<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">http://www.rfc-editor.org/rfc/rfc2104.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>md4</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md5/md5.html">md5</a>, <a href="../sha1/sha1.html">sha1</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#md4">md4</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#rfc_1320">rfc 1320</a>, <a href="../../../../index.html#rfc_1321">rfc 1321</a>, <a href="../../../../index.html#rfc_2104">rfc 2104</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/md5/md5.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<div class='fossil-doc' data-title='md5 - MD5 Message-Digest Algorithm'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">md5(n) 2.0.7 tcllib "MD5 Message-Digest Algorithm"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>md5 - MD5 Message-Digest Algorithm</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">md5 <span class="opt">?2.0.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::md5::md5</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::md5::hmac</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#3"><b class="cmd">::md5::MD5Init</b></a></li>
<li><a href="#4"><b class="cmd">::md5::MD5Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::md5::MD5Final</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::md5::HMACInit</b> <i class="arg">key</i></a></li>
<li><a href="#7"><b class="cmd">::md5::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::md5::HMACFinal</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the MD5 message-digest
algorithm as described in RFC 1321 (1). This algorithm takes
an arbitrary quantity of data and generates a 128-bit message digest
from the input. The MD5 algorithm is related to the MD4 algorithm (2)
but has been strengthened against certain types of potential
attack. MD5 should be used in preference to MD4 for new applications.</p>
<p>If you have <b class="package">critcl</b> and have built the <b class="package">tcllibc</b>
package then the implementation of the hashing function will be
performed by compiled code. Alternatively if you have either
<b class="package">cryptkit</b> or <b class="package">Trf</b> then either of these can be used to
accelerate the digest computation. If no suitable compiled package is
available then the pure-Tcl implementation wil be used. The
programming interface remains the same in all cases.</p>
<p><em>Note</em> the previous version of this package always returned a
hex encoded string. This has been changed to simplify the programming
interface and to make this version more compatible with other
implementations. To obtain the previous usage, either explicitly
specify package version 1 or use the <i class="arg">-hex</i> option to the
<b class="cmd">md5</b> command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::md5::md5</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate the MD5 digest of the data given in string. This is returned
as a binary string by default. Giving the <i class="arg">-hex</i> option will
return a hexadecimal encoded version of the digest.</p>
<p>The data to be hashed can be specified either as a string argument to
the <b class="cmd">md5</b> command, or as a filename or a pre-opened channel. If the
<i class="arg">-filename</i> argument is given then the file is opened, the data read
and hashed and the file is closed. If the <i class="arg">-channel</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed.</p>
<p>Only one of <i class="arg">-file</i>, <i class="arg">-channel</i> or <i class="arg">string</i> should be given.</p></dd>
<dt><a name="2"><b class="cmd">::md5::hmac</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate an Hashed Message Authentication digest (HMAC) using the MD5
digest algorithm. HMACs are described in RFC 2104 (3) and provide an MD5
digest that includes a key. All options other than <i class="arg">-key</i> are as
for the <b class="cmd">::md5::md5</b> command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>For the programmer, the MD5 hash can be viewed as a bucket into which
one pours data. When you have finished, you extract a value that is
derived from the data that was poured into the bucket. The programming
interface to the MD5 hash operates on a token (equivalent to the
bucket). You call <b class="cmd">MD5Init</b> to obtain a token and then call
<b class="cmd">MD5Update</b> as many times as required to add data to the hash. To
release any resources and obtain the hash value, you then call
<b class="cmd">MD5Final</b>. An equivalent set of functions gives you a keyed digest
(HMAC).</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::md5::MD5Init</b></a></dt>
<dd><p>Begins a new MD5 hash. Returns a token ID that must be used for the
remaining functions.</p></dd>
<dt><a name="4"><b class="cmd">::md5::MD5Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the hash identified by token. Calling
<em>MD5Update $token "abcd"</em> is equivalent to calling
<em>MD5Update $token "ab"</em> followed by
<em>MD5Update $token "cb"</em>. See <span class="sectref"><a href="#section4">EXAMPLES</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::md5::MD5Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the hash value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a binary string of 16 bytes representing the 128 bit MD5
digest value.</p></dd>
<dt><a name="6"><b class="cmd">::md5::HMACInit</b> <i class="arg">key</i></a></dt>
<dd><p>This is equivalent to the <b class="cmd">::md5::MD5Init</b> command except that
it requires the key that will be included in the HMAC.</p></dd>
<dt><a name="7"><b class="cmd">::md5::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="8"><b class="cmd">::md5::HMACFinal</b> <i class="arg">token</i></a></dt>
<dd><p>These commands are identical to the MD5 equivalent commands.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% md5::md5 -hex "Tcl does MD5"
8AAC1EE01E20BB347104FABB90310433
</pre>
<pre class="doctools_example">
% md5::hmac -hex -key Sekret "Tcl does MD5"
35BBA244FD56D3EDF5F3C47474DACB5D
</pre>
<pre class="doctools_example">
% set tok [md5::MD5Init]
::md5::1
% md5::MD5Update $tok "Tcl "
% md5::MD5Update $tok "does "
% md5::MD5Update $tok "MD5"
% md5::Hex [md5::MD5Final $tok]
8AAC1EE01E20BB347104FABB90310433
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and
RSA Data Security, Inc, April 1992.
(<a href="http://www.rfc-editor.org/rfc/rfc1321.txt">http://www.rfc-editor.org/rfc/rfc1321.txt</a>)</p></li>
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
Message Authentication", RFC 2104, February 1997.
(<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">http://www.rfc-editor.org/rfc/rfc2104.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>md5</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md4/md4.html">md4</a>, <a href="../sha1/sha1.html">sha1</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#md5">md5</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#rfc_1320">rfc 1320</a>, <a href="../../../../index.html#rfc_1321">rfc 1321</a>, <a href="../../../../index.html#rfc_2104">rfc 2104</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/md5crypt/md5crypt.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
<div class='fossil-doc' data-title='md5crypt - MD5-based password encryption'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">md5crypt(n) 1.1.0 tcllib "MD5-based password encryption"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>md5crypt - MD5-based password encryption</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">SALT</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">md5 2.0</b></li>
<li>package require <b class="pkgname">md5crypt <span class="opt">?1.1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::md5crypt::md5crypt</b> <i class="arg">password</i> <i class="arg">salt</i></a></li>
<li><a href="#2"><b class="cmd">::md5crypt::aprcrypt</b> <i class="arg">password</i> <i class="arg">salt</i></a></li>
<li><a href="#3"><b class="cmd">::md5crypt::salt</b> <span class="opt">?<i class="arg">length</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an implementation of the MD5-crypt password
encryption algorithm as pioneered by FreeBSD and currently in use as a
replacement for the unix crypt(3) function in many modern
systems. An implementation of the closely related Apache MD5-crypt is
also available.
The output of these commands are compatible with the BSD and OpenSSL
implementation of md5crypt and the Apache 2 htpasswd program.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::md5crypt::md5crypt</b> <i class="arg">password</i> <i class="arg">salt</i></a></dt>
<dd><p>Generate a BSD compatible md5-encoded password hash from the plaintext
password and a random salt (see SALT).</p></dd>
<dt><a name="2"><b class="cmd">::md5crypt::aprcrypt</b> <i class="arg">password</i> <i class="arg">salt</i></a></dt>
<dd><p>Generate an Apache compatible md5-encoded password hash from the plaintext
password and a random salt (see SALT).</p></dd>
<dt><a name="3"><b class="cmd">::md5crypt::salt</b> <span class="opt">?<i class="arg">length</i>?</span></a></dt>
<dd><p>Generate a random salt string suitable for use with the <b class="cmd">md5crypt</b> and
<b class="cmd">aprcrypt</b> commands.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">SALT</a></h2>
<p>The salt passed to either of the encryption schemes implemented here
is checked to see if it begins with the encryption scheme magic string
(either "$1$" for MD5-crypt or "$apr1$" for Apache crypt). If so, this
is removed. The remaining characters up to the next $ and up to a
maximum of 8 characters are then used as the salt. The salt text
should probably be restricted the set of ASCII alphanumeric characters
plus "./" (dot and forward-slash) - this is to preserve maximum
compatability with the unix password file format.</p>
<p>If a password is being generated rather than checked from a password
file then the <b class="cmd">salt</b> command may be used to generate a random salt.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% md5crypt::md5crypt password 01234567
$1$01234567$b5lh2mHyD2PdJjFfALlEz1
</pre>
<pre class="doctools_example">
% md5crypt::aprcrypt password 01234567
$apr1$01234567$IXBaQywhAhc0d75ZbaSDp/
</pre>
<pre class="doctools_example">
% md5crypt::md5crypt password [md5crypt::salt]
$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb.
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>md5crypt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md5/md5.html">md5</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#md5">md5</a>, <a href="../../../../index.html#md5crypt">md5crypt</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/mime/mime.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
|
<div class='fossil-doc' data-title='mime - Mime'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">mime(n) 1.6 tcllib "Mime"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>mime - Manipulation of MIME body parts</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">KNOWN BUGS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">mime <span class="opt">?1.6?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::mime::initialize</b> <span class="opt">?<b class="option">-canonical</b> <i class="arg">type/subtype</i> <span class="opt">?<b class="option">-param</b> {<i class="arg">key value</i>}...?</span> <span class="opt">?<b class="option">-encoding</b> <i class="arg">value</i>?</span> <span class="opt">?<b class="option">-header</b> {<i class="arg">key value</i>}...?</span>?</span> (<b class="option">-file</b> <i class="arg">name</i> | <b class="option">-string</b> <i class="arg">value</i> | <b class="option">-parts</b> {<i class="arg">token1</i> ... <i class="arg">tokenN</i>})</a></li>
<li><a href="#2"><b class="cmd">::mime::finalize</b> <i class="arg">token</i> <span class="opt">?<b class="option">-subordinates</b> <b class="const">all</b> | <b class="const">dynamic</b> | <b class="const">none</b>?</span></a></li>
<li><a href="#3"><b class="cmd">::mime::getproperty</b> <i class="arg">token</i> <span class="opt">?<i class="arg">property</i> | <b class="option">-names</b>?</span></a></li>
<li><a href="#4"><b class="cmd">::mime::getheader</b> <i class="arg">token</i> <span class="opt">?<i class="arg">key</i> | <b class="option">-names</b>?</span></a></li>
<li><a href="#5"><b class="cmd">::mime::setheader</b> <i class="arg">token</i> <i class="arg">key value</i> <span class="opt">?<b class="option">-mode</b> <b class="const">write</b> | <b class="const">append</b> | <b class="const">delete</b>?</span></a></li>
<li><a href="#6"><b class="cmd">::mime::getbody</b> <i class="arg">token</i> <span class="opt">?<b class="option">-decode</b>?</span> <span class="opt">?<b class="option">-command</b> <i class="arg">callback</i> <span class="opt">?<b class="option">-blocksize</b> <i class="arg">octets</i>?</span>?</span></a></li>
<li><a href="#7"><b class="cmd">::mime::copymessage</b> <i class="arg">token</i> <i class="arg">channel</i></a></li>
<li><a href="#8"><b class="cmd">::mime::buildmessage</b> <i class="arg">token</i></a></li>
<li><a href="#9"><b class="cmd">::mime::parseaddress</b> <i class="arg">string</i></a></li>
<li><a href="#10"><b class="cmd">::mime::parsedatetime</b> (<i class="arg">string</i> | <b class="option">-now</b>) <i class="arg">property</i></a></li>
<li><a href="#11"><b class="cmd">::mime::mapencoding</b> <i class="arg">encoding_name</i></a></li>
<li><a href="#12"><b class="cmd">::mime::reversemapencoding</b> <i class="arg">charset_type</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">mime</b> library package provides the commands to create and
manipulate MIME body parts.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::mime::initialize</b> <span class="opt">?<b class="option">-canonical</b> <i class="arg">type/subtype</i> <span class="opt">?<b class="option">-param</b> {<i class="arg">key value</i>}...?</span> <span class="opt">?<b class="option">-encoding</b> <i class="arg">value</i>?</span> <span class="opt">?<b class="option">-header</b> {<i class="arg">key value</i>}...?</span>?</span> (<b class="option">-file</b> <i class="arg">name</i> | <b class="option">-string</b> <i class="arg">value</i> | <b class="option">-parts</b> {<i class="arg">token1</i> ... <i class="arg">tokenN</i>})</a></dt>
<dd><p>This command creates a MIME part and returns a token representing it.</p>
<ul class="doctools_itemized">
<li><p>If the <b class="option">-canonical</b> option is present, then the body is in
canonical (raw) form and is found by consulting either the
<b class="option">-file</b>, <b class="option">-string</b>, or <b class="option">-parts</b> option.</p>
<p>In addition, both the <b class="option">-param</b> and <b class="option">-header</b> options may
occur zero or more times to specify <b class="const">Content-Type</b> parameters
(e.g., <b class="const">charset</b>) and header keyword/values (e.g.,
<b class="const">Content-Disposition</b>), respectively.</p>
<p>Also, <b class="option">-encoding</b>, if present, specifies the
<b class="const">Content-Transfer-Encoding</b> when copying the body.</p></li>
<li><p>If the <b class="option">-canonical</b> option is not present, then the MIME part
contained in either the <b class="option">-file</b> or the <b class="option">-string</b> option
is parsed, dynamically generating subordinates as appropriate.</p></li>
</ul></dd>
<dt><a name="2"><b class="cmd">::mime::finalize</b> <i class="arg">token</i> <span class="opt">?<b class="option">-subordinates</b> <b class="const">all</b> | <b class="const">dynamic</b> | <b class="const">none</b>?</span></a></dt>
<dd><p>This command destroys the MIME part represented by <i class="arg">token</i>. It
returns an empty string.</p>
<p>If the <b class="option">-subordinates</b> option is present, it specifies which
subordinates should also be destroyed. The default value is
<b class="const">dynamic</b>, destroying all subordinates which were created by
<b class="cmd">::mime::initialize</b> together with the containing body part.</p></dd>
<dt><a name="3"><b class="cmd">::mime::getproperty</b> <i class="arg">token</i> <span class="opt">?<i class="arg">property</i> | <b class="option">-names</b>?</span></a></dt>
<dd><p>This command returns a string or a list of strings containing the
properties of a MIME part. If the command is invoked with the name of
a specific property, then the corresponding value is returned;
instead, if <b class="option">-names</b> is specified, a list of all properties is
returned; otherwise, a serialized array of properties and values is
returned.</p>
<p>The possible properties are:</p>
<dl class="doctools_definitions">
<dt><b class="const">content</b></dt>
<dd><p>The type/subtype describing the content</p></dd>
<dt><b class="const">encoding</b></dt>
<dd><p>The "Content-Transfer-Encoding"</p></dd>
<dt><b class="const">params</b></dt>
<dd><p>A list of "Content-Type" parameters</p></dd>
<dt><b class="const">parts</b></dt>
<dd><p>A list of tokens for the part's subordinates. This property is
present only if the MIME part has subordinates.</p></dd>
<dt><b class="const">size</b></dt>
<dd><p>The approximate size of the content (unencoded)</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::mime::getheader</b> <i class="arg">token</i> <span class="opt">?<i class="arg">key</i> | <b class="option">-names</b>?</span></a></dt>
<dd><p>This command returns the header of a MIME part, as a list of strings.</p>
<p>A header consists of zero or more key/value pairs. Each value is a
list containing one or more strings.</p>
<p>If this command is invoked with the name of a specific <i class="arg">key</i>, then
a list containing the corresponding value(s) is returned; instead, if
-names is specified, a list of all keys is returned; otherwise, a
serialized array of keys and values is returned. Note that when a key
is specified (e.g., "Subject"), the list returned usually contains
exactly one string; however, some keys (e.g., "Received") often occur
more than once in the header, accordingly the list returned usually
contains more than one string.</p></dd>
<dt><a name="5"><b class="cmd">::mime::setheader</b> <i class="arg">token</i> <i class="arg">key value</i> <span class="opt">?<b class="option">-mode</b> <b class="const">write</b> | <b class="const">append</b> | <b class="const">delete</b>?</span></a></dt>
<dd><p>This command writes, appends to, or deletes the <i class="arg">value</i> associated
with a <i class="arg">key</i> in the header. It returns a list of strings
containing the previous value associated with the key.</p>
<p>The value for <b class="option">-mode</b> is one of:</p>
<dl class="doctools_definitions">
<dt><b class="const">write</b></dt>
<dd><p>The <i class="arg">key</i>/<i class="arg">value</i> is either created or overwritten (the default).</p></dd>
<dt><b class="const">append</b></dt>
<dd><p>A new <i class="arg">value</i> is appended for the <i class="arg">key</i> (creating it as necessary).</p></dd>
<dt><b class="const">delete</b></dt>
<dd><p>All values associated with the key are removed (the <i class="arg">value</i>
parameter is ignored).</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::mime::getbody</b> <i class="arg">token</i> <span class="opt">?<b class="option">-decode</b>?</span> <span class="opt">?<b class="option">-command</b> <i class="arg">callback</i> <span class="opt">?<b class="option">-blocksize</b> <i class="arg">octets</i>?</span>?</span></a></dt>
<dd><p>This command returns a string containing the body of the leaf MIME
part represented by <i class="arg">token</i> in canonical form.</p>
<p>If the <b class="option">-command</b> option is present, then it is repeatedly
invoked with a fragment of the body as this:</p>
<pre class="doctools_example">
uplevel #0 $callback [list "data" $fragment]
</pre>
<p>(The <b class="option">-blocksize</b> option, if present, specifies the maximum
size of each fragment passed to the callback.)</p>
<p>When the end of the body is reached, the callback is invoked as:</p>
<pre class="doctools_example">
uplevel #0 $callback "end"
</pre>
<p>Alternatively, if an error occurs, the callback is invoked as:</p>
<pre class="doctools_example">
uplevel #0 $callback [list "error" reason]
</pre>
<p>Regardless, the return value of the final invocation of the callback
is propagated upwards by <b class="cmd">::mime::getbody</b>.</p>
<p>If the <b class="option">-command</b> option is absent, then the return value of
<b class="cmd">::mime::getbody</b> is a string containing the MIME part's entire
body.</p>
<p>If the option <b class="option">-decode</b> is absent the return value computed
above is returned as is. This means that it will be in the charset
specified for the token and not the usual utf-8.
If the option <b class="option">-decode</b> is present however the command will use
the charset information associated with the token to convert the
string from its encoding into utf-8 before returning it.</p></dd>
<dt><a name="7"><b class="cmd">::mime::copymessage</b> <i class="arg">token</i> <i class="arg">channel</i></a></dt>
<dd><p>This command copies the MIME represented by <i class="arg">token</i> part to the
specified <i class="arg">channel</i>. The command operates synchronously, and uses
fileevent to allow asynchronous operations to proceed
independently. It returns an empty string.</p></dd>
<dt><a name="8"><b class="cmd">::mime::buildmessage</b> <i class="arg">token</i></a></dt>
<dd><p>This command returns the MIME part represented by <i class="arg">token</i> as a
string. It is similar to <b class="cmd">::mime::copymessage</b>, only it returns
the data as a return string instead of writing to a channel.</p></dd>
<dt><a name="9"><b class="cmd">::mime::parseaddress</b> <i class="arg">string</i></a></dt>
<dd><p>This command takes a string containing one or more 822-style address
specifications and returns a list of serialized arrays, one element
for each address specified in the argument. If the string contains
more than one address they will be separated by commas.</p>
<p>Each serialized array contains the properties below. Note that one or
more of these properties may be empty.</p>
<dl class="doctools_definitions">
<dt><b class="const">address</b></dt>
<dd><p>local@domain</p></dd>
<dt><b class="const">comment</b></dt>
<dd><p>822-style comment</p></dd>
<dt><b class="const">domain</b></dt>
<dd><p>the domain part (rhs)</p></dd>
<dt><b class="const">error</b></dt>
<dd><p>non-empty on a parse error</p></dd>
<dt><b class="const">group</b></dt>
<dd><p>this address begins a group</p></dd>
<dt><b class="const">friendly</b></dt>
<dd><p>user-friendly rendering</p></dd>
<dt><b class="const">local</b></dt>
<dd><p>the local part (lhs)</p></dd>
<dt><b class="const">memberP</b></dt>
<dd><p>this address belongs to a group</p></dd>
<dt><b class="const">phrase</b></dt>
<dd><p>the phrase part</p></dd>
<dt><b class="const">proper</b></dt>
<dd><p>822-style address specification</p></dd>
<dt><b class="const">route</b></dt>
<dd><p>822-style route specification (obsolete)</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::mime::parsedatetime</b> (<i class="arg">string</i> | <b class="option">-now</b>) <i class="arg">property</i></a></dt>
<dd><p>This command takes a string containing an 822-style date-time
specification and returns the specified property as a serialized
array.</p>
<p>The list of properties and their ranges are:</p>
<dl class="doctools_definitions">
<dt><b class="const">hour</b></dt>
<dd><p>0 .. 23</p></dd>
<dt><b class="const">lmonth</b></dt>
<dd><p>January, February, ..., December</p></dd>
<dt><b class="const">lweekday</b></dt>
<dd><p>Sunday, Monday, ... Saturday</p></dd>
<dt><b class="const">mday</b></dt>
<dd><p>1 .. 31</p></dd>
<dt><b class="const">min</b></dt>
<dd><p>0 .. 59</p></dd>
<dt><b class="const">mon</b></dt>
<dd><p>1 .. 12</p></dd>
<dt><b class="const">month</b></dt>
<dd><p>Jan, Feb, ..., Dec</p></dd>
<dt><b class="const">proper</b></dt>
<dd><p>822-style date-time specification</p></dd>
<dt><b class="const">rclock</b></dt>
<dd><p>elapsed seconds between then and now</p></dd>
<dt><b class="const">sec</b></dt>
<dd><p>0 .. 59</p></dd>
<dt><b class="const">wday</b></dt>
<dd><p>0 .. 6 (Sun .. Mon)</p></dd>
<dt><b class="const">weekday</b></dt>
<dd><p>Sun, Mon, ..., Sat</p></dd>
<dt><b class="const">yday</b></dt>
<dd><p>1 .. 366</p></dd>
<dt><b class="const">year</b></dt>
<dd><p>1900 ...</p></dd>
<dt><b class="const">zone</b></dt>
<dd><p>-720 .. 720 (minutes east of GMT)</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::mime::mapencoding</b> <i class="arg">encoding_name</i></a></dt>
<dd><p>This commansd maps tcl encodings onto the proper names for their MIME
charset type. This is only done for encodings whose charset types
were known. The remaining encodings return "" for now.</p></dd>
<dt><a name="12"><b class="cmd">::mime::reversemapencoding</b> <i class="arg">charset_type</i></a></dt>
<dd><p>This command maps MIME charset types onto tcl encoding names. Those
that are unknown return "".</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">KNOWN BUGS</a></h2>
<dl class="doctools_definitions">
<dt>Tcllib Bug #447037</dt>
<dd><p>This problem affects only people which are using Tcl and Mime on a
64-bit system. The currently recommended fix for this problem is to
upgrade to Tcl version 8.4. This version has extended 64 bit support
and the bug does not appear anymore.</p>
<p>The problem could have been generally solved by requiring the use of
Tcl 8.4 for this package. We decided against this solution as it would
force a large number of unaffected users to upgrade their Tcl
interpreter for no reason.</p>
<p>See <a href="/tktview?name=447037">Ticket 447037</a> for additional information.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>mime</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../ftp/ftp.html">ftp</a>, <a href="../../../../index.html#http">http</a>, <a href="../pop3/pop3.html">pop3</a>, <a href="smtp.html">smtp</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#email">email</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#mail">mail</a>, <a href="../../../../index.html#mime">mime</a>, <a href="../../../../index.html#net">net</a>, <a href="../../../../index.html#rfc_2045">rfc 2045</a>, <a href="../../../../index.html#rfc_2046">rfc 2046</a>, <a href="../../../../index.html#rfc_2049">rfc 2049</a>, <a href="../../../../index.html#rfc_821">rfc 821</a>, <a href="../../../../index.html#rfc_822">rfc 822</a>, <a href="../../../../index.html#smtp">smtp</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 1999-2000 Marshall T. Rose</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/mime/smtp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
|
<div class='fossil-doc' data-title='smtp - smtp client'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">smtp(n) 1.5 tcllib "smtp client"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>smtp - Client-side tcl implementation of the smtp protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Authentication</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section4">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl</b></li>
<li>package require <b class="pkgname">mime <span class="opt">?1.5.4?</span></b></li>
<li>package require <b class="pkgname">smtp <span class="opt">?1.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::smtp::sendmessage</b> <i class="arg">token</i> <i class="arg">option</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">smtp</b> library package provides the client side of the
Simple Mail Transfer Protocol (SMTP) (1) (2).</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::smtp::sendmessage</b> <i class="arg">token</i> <i class="arg">option</i>...</a></dt>
<dd><p>This command sends the MIME part (see package <b class="package"><a href="mime.html">mime</a></b>)
represented by <i class="arg">token</i> to an SMTP server. <i class="arg">options</i> is a list
of options and their associated values. The recognized options are:</p>
<dl class="doctools_definitions">
<dt><b class="option">-servers</b></dt>
<dd><p>A list of SMTP servers. The default is <b class="const">localhost</b>.</p>
<p>If multiple servers are specified they are tried in sequence.
Note that the <b class="option">-ports</b> are iterated over in tandem with the
servers. If there are not enough ports for the number of servers the
default port (see below) is used. If there are more ports than servers
the superfluous ports are ignored.</p></dd>
<dt><b class="option">-ports</b></dt>
<dd><p>A list of SMTP ports. The default is <b class="const">25</b>.</p>
<p>See option <b class="option">-servers</b> above regardig the behaviour for
then multiple servers and ports are specified.</p></dd>
<dt><b class="option">-client</b></dt>
<dd><p>The name to use as our hostname when connecting to the server. By
default this is either localhost if one of the servers is localhost,
or is set to the string returned by <b class="cmd">info hostname</b>.</p></dd>
<dt><b class="option">-queue</b></dt>
<dd><p>Indicates that the SMTP server should be asked to queue the message
for later processing. A boolean value.</p></dd>
<dt><b class="option">-atleastone</b></dt>
<dd><p>Indicates that the SMTP server must find at least one recipient
acceptable for the message to be sent. A boolean value.</p></dd>
<dt><b class="option">-originator</b></dt>
<dd><p>A string containing an 822-style address specification. If present the
header isn't examined for an originator address.</p></dd>
<dt><b class="option">-recipients</b></dt>
<dd><p>A string containing one or more 822-style address specifications. If
present the header isn't examined for recipient addresses). If the
string contains more than one address they will be separated by
commas.</p></dd>
<dt><b class="option">-header</b></dt>
<dd><p>A list containing two elements, an smtp header and its associated
value (the -header option may occur zero or more times).</p></dd>
<dt><b class="option">-usetls</b></dt>
<dd><p>This package supports the RFC 3207 TLS extension (3) by default provided the
tls package is available. You can turn this off with this boolean option.</p></dd>
<dt><b class="option">-tlsimport</b></dt>
<dd><p>This boolean flag is <b class="const">false</b> by default.
When this flag is set the package will import TLS on a sucessfully
opened channel. This is needed for connections using native TLS
negotiation instead of <b class="const">STARTTLS</b>. The <b class="package"><a href="../../../../index.html#tls">tls</a></b> package
is automatically required when needed.</p></dd>
<dt><b class="option">-tlspolicy</b></dt>
<dd><p>This option lets you specify a command to be called if an error occurs
during TLS setup. The command is called with the SMTP code and diagnostic
message appended. The command should return 'secure' or 'insecure' where
insecure will cause the package to continue on the unencrypted channel.
Returning 'secure' will cause the socket to be closed and the next server
in the <b class="option">-servers</b> list to be tried.</p></dd>
<dt><b class="option">-username</b></dt>
<dd></dd>
<dt><b class="option">-password</b></dt>
<dd><p>If your SMTP server requires authentication (RFC 2554 (4)) before
accepting mail you can use <b class="option">-username</b> and <b class="option">-password</b>
to provide your authentication details to the server. Currently this
package supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication
methods. The most secure method will be tried first and each method
tried in turn until we are either authorized or we run out of
methods. Note that if the server permits a TLS connection, then the
authorization will occur after we begin using the secure channel.</p>
<p>Please also read the section on <span class="sectref"><a href="#section2">Authentication</a></span>, it details
the necessary prequisites, i.e. packages needed to support these
options and authentication.</p></dd>
</dl>
<p>If the <b class="option">-originator</b> option is not present, the originator
address is taken from <b class="const">From</b> (or <b class="const">Resent-From</b>);
similarly, if the <b class="option">-recipients</b> option is not present,
recipient addresses are taken from <b class="const">To</b>, <b class="const">cc</b>, and
<b class="const">Bcc</b> (or <b class="const">Resent-To</b>, and so on). Note that the header
key/values supplied by the <b class="option">-header</b> option (not those present
in the MIME part) are consulted. Regardless, header key/values are
added to the outgoing message as necessary to ensure that a valid
822-style message is sent.</p>
<p>The command returns a list indicating which recipients were
unacceptable to the SMTP server. Each element of the list is another
list, containing the address, an SMTP error code, and a textual
diagnostic. Depending on the <b class="option">-atleastone</b> option and the
intended recipients, a non-empty list may still indicate that the
message was accepted by the server.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Authentication</a></h2>
<p>Beware. SMTP authentication uses <b class="package"><a href="../sasl/sasl.html">SASL</a></b>. I.e. if the user
has to authenticate a connection, i.e. use the options <b class="option">-user</b>
and <b class="option">-password</b> (see above) it is necessary to have the
<b class="package">sasl</b> package available so that <b class="package">smtp</b> can load it.</p>
<p>This is a soft dependency because not everybody requires authentication,
and <b class="package">sasl</b> depends on a lot of the cryptographic (secure) hashes,
i.e. all of <b class="package"><a href="../md5/md5.html">md5</a></b>, <b class="package"><a href="../otp/otp.html">otp</a></b>, <b class="package"><a href="../md4/md4.html">md4</a></b>, <b class="package"><a href="../sha1/sha1.html">sha1</a></b>,
and <b class="package"><a href="../ripemd/ripemd160.html">ripemd160</a></b>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLE</a></h2>
<pre class="doctools_example">
proc send_simple_message {recipient email_server subject body} {
package require smtp
package require mime
set token [mime::initialize -canonical text/plain \\
-string $body]
mime::setheader $token Subject $subject
smtp::sendmessage $token \\
-recipients $recipient -servers $email_server
mime::finalize $token
}
send_simple_message [email protected] localhost \\
"This is the subject." "This is the message."
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982.
(<a href="http://www.rfc-editor.org/rfc/rfc821.txt">http://www.rfc-editor.org/rfc/rfc821.txt</a>)</p></li>
<li><p>J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001.
(<a href="http://www.rfc-editor.org/rfc/rfc2821.txt">http://www.rfc-editor.org/rfc/rfc2821.txt</a>)</p></li>
<li><p>P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport
Layer Security", RFC 3207, February 2002.
(<a href="http://www.rfc-editor.org/rfc/rfc3207.txt">http://www.rfc-editor.org/rfc/rfc3207.txt</a>)</p></li>
<li><p>J. Myers, "SMTP Service Extension for Authentication",
RFC 2554, March 1999.
(<a href="http://www.rfc-editor.org/rfc/rfc2554.txt">http://www.rfc-editor.org/rfc/rfc2554.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>smtp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../ftp/ftp.html">ftp</a>, <a href="../../../../index.html#http">http</a>, <a href="mime.html">mime</a>, <a href="../pop3/pop3.html">pop3</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#email">email</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#mail">mail</a>, <a href="../../../../index.html#mime">mime</a>, <a href="../../../../index.html#net">net</a>, <a href="../../../../index.html#rfc_2554">rfc 2554</a>, <a href="../../../../index.html#rfc_2821">rfc 2821</a>, <a href="../../../../index.html#rfc_3207">rfc 3207</a>, <a href="../../../../index.html#rfc_821">rfc 821</a>, <a href="../../../../index.html#rfc_822">rfc 822</a>, <a href="../../../../index.html#smtp">smtp</a>, <a href="../../../../index.html#tls">tls</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 1999-2000 Marshall T. Rose and others</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/multiplexer/multiplexer.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
<div class='fossil-doc' data-title='multiplexer - One-to-many communication with sockets.'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">multiplexer(n) 0.2 tcllib "One-to-many communication with sockets."</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>multiplexer - One-to-many communication with sockets.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">multiplexer <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::multiplexer::create</b></a></li>
<li><a href="#2"><b class="cmd">${multiplexer_instance}::Init</b> <i class="arg">port</i></a></li>
<li><a href="#3"><b class="cmd">${multiplexer_instance}::Config</b> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#4"><b class="cmd">${multiplexer_instance}::AddFilter</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#5"><b class="cmd">cmdprefix</b> <i class="arg">data</i> <i class="arg">chan</i> <i class="arg">clientaddress</i> <i class="arg">clientport</i></a></li>
<li><a href="#6"><b class="cmd">${multiplexer_instance}::AddAccessFilter</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#7"><b class="cmd">cmdprefix</b> <i class="arg">chan</i> <i class="arg">clientaddress</i> <i class="arg">clientport</i></a></li>
<li><a href="#8"><b class="cmd">${multiplexer_instance}::AddExitFilter</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#9"><b class="cmd">cmdprefix</b> <i class="arg">chan</i> <i class="arg">clientaddress</i> <i class="arg">clientport</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">multiplexer</b> package provides a generic system for one-to-many
communication utilizing sockets. For example, think of a chat system
where one user sends a message which is then broadcast to all the
other connected users.</p>
<p>It is possible to have different multiplexers running concurrently.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::multiplexer::create</b></a></dt>
<dd><p>The <b class="cmd">create</b> command creates a new multiplexer 'instance'. For
example:</p>
<pre class="doctools_example">set mp [::multiplexer::create]</pre>
<p>This instance can then be manipulated like so:</p>
<pre class="doctools_example">${mp}::Init 35100</pre>
</dd>
<dt><a name="2"><b class="cmd">${multiplexer_instance}::Init</b> <i class="arg">port</i></a></dt>
<dd><p>This starts the multiplexer listening on the specified port.</p></dd>
<dt><a name="3"><b class="cmd">${multiplexer_instance}::Config</b> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Use <b class="cmd">Config</b> to configure the multiplexer instance. Configuration
options currently include:</p>
<dl class="doctools_options">
<dt><b class="option">sendtoorigin</b></dt>
<dd><p>A boolean flag. If <b class="const">true</b>, the sender will receive a copy of the
sent message. Defaults to <b class="const">false</b>.</p></dd>
<dt><b class="option">debuglevel</b></dt>
<dd><p>Sets the debug level to use for the multiplexer instance, according to
those specified by the <b class="package"><a href="../log/logger.html">logger</a></b> package (debug, info, notice,
warn, error, critical).</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">${multiplexer_instance}::AddFilter</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Command to add a filter for data that passes through the multiplexer
instance.
The registered <i class="arg">cmdprefix</i> is called when data arrives at a
multiplexer instance. If there is more than one filter command
registered at the instance they will be called in the order of
registristation, and each filter will get the result of the preceding
filter as its argument. The first filter gets the incoming data as its
argument. The result returned by the last filter is the data which
will be broadcast to all clients of the multiplexer instance.
The command prefix is called as</p>
<dl class="doctools_definitions">
<dt><a name="5"><b class="cmd">cmdprefix</b> <i class="arg">data</i> <i class="arg">chan</i> <i class="arg">clientaddress</i> <i class="arg">clientport</i></a></dt>
<dd><p>Takes the incoming <i class="arg">data</i>, modifies it, and returns that as its
result. The last three arguments contain information about the client
which sent the data to filter: The channel connecting us to the
client, its ip-address, and its ip-port.</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">${multiplexer_instance}::AddAccessFilter</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Command to add an access filter.
The registered <i class="arg">cmdprefix</i> is called when a new client socket
tries to connect to the multixer instance. If there is more than one
access filter command registered at the instance they will be called
in the order of registristation. If any of the called commands returns
<b class="const">-1</b> the access to the multiplexer instance is denied and the
client channel is closed immediately. Any other result grants the
client access to the multiplexer instance.
The command prefix is called as</p>
<dl class="doctools_definitions">
<dt><a name="7"><b class="cmd">cmdprefix</b> <i class="arg">chan</i> <i class="arg">clientaddress</i> <i class="arg">clientport</i></a></dt>
<dd><p>The arguments contain information about the client which tries to
connected to the instance: The channel connecting us to the client,
its ip-address, and its ip-port.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">${multiplexer_instance}::AddExitFilter</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Adds filter to be run when client socket generates an EOF condition.
The registered <i class="arg">cmdprefix</i> is called when a client socket of the
multixer signals EOF. If there is more than one exit filter command
registered at the instance they will be called in the order of
registristation. Errors thrown by an exit filter are ignored, but
logged. Any result returned by an exit filter is ignored.
The command prefix is called as</p>
<dl class="doctools_definitions">
<dt><a name="9"><b class="cmd">cmdprefix</b> <i class="arg">chan</i> <i class="arg">clientaddress</i> <i class="arg">clientport</i></a></dt>
<dd><p>The arguments contain information about the client which signaled the
EOF: The channel connecting us to the client, its ip-address, and its
ip-port.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>multiplexer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#chat">chat</a>, <a href="../../../../index.html#multiplexer">multiplexer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/namespacex/namespacex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<div class='fossil-doc' data-title='namespacex - Namespace utility commands'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">namespacex(n) 0.2 tcllib "Namespace utility commands"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>namespacex - Namespace utility commands</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">namespacex <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::namespacex hook add</b> <span class="opt">?<i class="arg">namespace</i>?</span> <i class="arg">cmdprefix</i></a></li>
<li><a href="#2"><b class="cmd">::namespacex hook proc</b> <span class="opt">?<i class="arg">namespace</i>?</span> <i class="arg">arguments</i> <i class="arg">body</i></a></li>
<li><a href="#3"><b class="cmd">::namespacex hook on</b> <span class="opt">?<i class="arg">namespace</i>?</span> <i class="arg">guardcmdprefix</i> <i class="arg">actioncmdprefix</i></a></li>
<li><a href="#4"><b class="cmd">::namespacex hook next</b> <i class="arg">arg</i>...</a></li>
<li><a href="#5"><b class="cmd">::namespacex import fromns</b> <i class="arg">cmdname <span class="opt">?<i class="arg">newname</i> ...?</span></i></a></li>
<li><a href="#6"><b class="cmd">::namespacex info allchildren</b> <i class="arg">namespace</i></a></li>
<li><a href="#7"><b class="cmd">::namespacex info allvars</b> <i class="arg">namespace</i></a></li>
<li><a href="#8"><b class="cmd">::namespacex normalize</b> <i class="arg">namespace</i></a></li>
<li><a href="#9"><b class="cmd">::namespacex info vars</b> <i class="arg">namespace</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::namespacex state get</b> <i class="arg">namespace</i></a></li>
<li><a href="#11"><b class="cmd">::namespacex state set</b> <i class="arg">namespace</i> <i class="arg">dict</i></a></li>
<li><a href="#12"><b class="cmd">::namespacex state drop</b> <i class="arg">namespace</i></a></li>
<li><a href="#13"><b class="cmd">::namespacex strip</b> <i class="arg">prefix</i> <i class="arg">namespaces</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a number of utility commands for working with
namespaces.
The commands fall into four categories:</p>
<ol class="doctools_enumerated">
<li><p>Hook commands provide and manipulate a chain of commands which
replaces the single regular <b class="cmd"><a href="../../../../index.html#namespace_unknown">namespace unknown</a></b> handler.</p></li>
<li><p>An import command provides the ability to import any command
from another namespace.</p></li>
<li><p>Information commands allow querying of variables and child
namespaces.</p></li>
<li><p>State commands provide a means to serialize variable values in
a namespace.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::namespacex hook add</b> <span class="opt">?<i class="arg">namespace</i>?</span> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Adds the <i class="arg">cmdprefix</i> to the chain of unknown command handlers that
are invoked when the <i class="arg">namespace</i> would otherwise invoke its
unknown handler.
If <i class="arg">namespace</i> is not specified, then <i class="arg">cmdprefix</i> is added to
the chain of handlers for the namespace of the caller.</p>
<p>The chain of <i class="arg">cmdprefix</i> are executed in reverse order of
addition, <em>i.e.</em> the most recently added <i class="arg">cmdprefix</i> is
executed first.
When executed, <i class="arg">cmdprefix</i> has additional arguments appended to it
as would any namespace unknown handler.</p></dd>
<dt><a name="2"><b class="cmd">::namespacex hook proc</b> <span class="opt">?<i class="arg">namespace</i>?</span> <i class="arg">arguments</i> <i class="arg">body</i></a></dt>
<dd><p>Adds an anonymous procedure to the chain of namespace unknown handlers
for the <i class="arg">namespace</i>.</p>
<p>If <i class="arg">namespace</i> is not specified, then the handler is added
to the chain of handlers for the namespace of the caller.</p>
<p>The <i class="arg">arguments</i> and <i class="arg">body</i> are specified as for the
core <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> command.</p></dd>
<dt><a name="3"><b class="cmd">::namespacex hook on</b> <span class="opt">?<i class="arg">namespace</i>?</span> <i class="arg">guardcmdprefix</i> <i class="arg">actioncmdprefix</i></a></dt>
<dd><p>Adds a guarded action to the chain of namespace unknown handlers for
the <i class="arg">namespace</i>.</p>
<p>If <i class="arg">namespace</i> is not specified, then the handler is added
to the chain of handlers for the namespace of the caller.</p>
<p>The <i class="arg">guardcmdprefix</i> is executed first. If it returns a
value that can be interpreted as false, then the next unknown hander
in the chain is executed. Otherwise, <i class="arg">actioncmdprefix</i> is executed
and the return value of the handler is the value returned by
<i class="arg">actioncmdprefix</i>.</p>
<p>When executed, both <i class="arg">guardcmdprefix</i> and
<i class="arg">actioncmdprefix</i> have the same additional arguments appended as
for any namespace unknown handler.</p></dd>
<dt><a name="4"><b class="cmd">::namespacex hook next</b> <i class="arg">arg</i>...</a></dt>
<dd><p>This command is available to namespace hooks to execute the next hook
in the chain of handlers for the namespace.</p></dd>
<dt><a name="5"><b class="cmd">::namespacex import fromns</b> <i class="arg">cmdname <span class="opt">?<i class="arg">newname</i> ...?</span></i></a></dt>
<dd><p>Imports the command <i class="arg">cmdname</i> from the <i class="arg">fromns</i> namespace into
the namespace of the caller.
The <i class="arg">cmdname</i> command is imported even if the <i class="arg">fromns</i> did not
originally export the command.</p>
<p>If <i class="arg">newname</i> is specified, then the imported command will
be known by that name. Otherwise, the command retains is original name
as given by <i class="arg">cmdname</i>.</p>
<p>Additional pairs of <i class="arg">cmdname</i> / <i class="arg">newname</i> arguments may
also be specified.</p></dd>
<dt><a name="6"><b class="cmd">::namespacex info allchildren</b> <i class="arg">namespace</i></a></dt>
<dd><p>Returns a list containing the names of all child namespaces in the
specified <i class="arg">namespace</i> and its children. The names are all fully
qualified.</p></dd>
<dt><a name="7"><b class="cmd">::namespacex info allvars</b> <i class="arg">namespace</i></a></dt>
<dd><p>Returns a list containing the names of all variables in the specified
<i class="arg">namespace</i> and its children. The names are all given relative to
<i class="arg">namespace</i>, and <em>not</em> fully qualified.</p></dd>
<dt><a name="8"><b class="cmd">::namespacex normalize</b> <i class="arg">namespace</i></a></dt>
<dd><p>Returns the absolute name of <i class="arg">namespace</i>, which is resolved
relative to the namespace of the caller, with all unneeded colon
characters removed.</p></dd>
<dt><a name="9"><b class="cmd">::namespacex info vars</b> <i class="arg">namespace</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list containing the names of all variables in
the specified <i class="arg">namespace</i>.
If the <i class="arg">pattern</i> argument is specified, then only variables
matching <i class="arg">pattern</i> are returned. Matching is determined using the
same rules as for <b class="cmd">string match</b>.</p></dd>
<dt><a name="10"><b class="cmd">::namespacex state get</b> <i class="arg">namespace</i></a></dt>
<dd><p>Returns a dictionary holding the names and values of all variables in
the specified <i class="arg">namespace</i> and its child namespaces.</p>
<p>Note that the names are all relative to <i class="arg">namespace</i>, and
<em>not</em> fully qualified.</p></dd>
<dt><a name="11"><b class="cmd">::namespacex state set</b> <i class="arg">namespace</i> <i class="arg">dict</i></a></dt>
<dd><p>Takes a dictionary holding the names and values for a set of variables
and replaces the current state of the specified <i class="arg">namespace</i> and
its child namespaces with this state.
The result of the command is the empty string.</p></dd>
<dt><a name="12"><b class="cmd">::namespacex state drop</b> <i class="arg">namespace</i></a></dt>
<dd><p>Unsets all variables in the specified <i class="arg">namespace</i> and its child
namespaces.
The result of the command is the empty string.</p></dd>
<dt><a name="13"><b class="cmd">::namespacex strip</b> <i class="arg">prefix</i> <i class="arg">namespaces</i></a></dt>
<dd><p>Each item in <i class="arg">namespaces</i> must be the absolute normalized name of
a child namespace of namespace <i class="arg">prefix</i>.
Returns the corresponding list of relative names of child namespaces.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>namespacex</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#extended_namespace">extended namespace</a>, <a href="../../../../index.html#info">info</a>, <a href="../../../../index.html#namespace_unknown">namespace unknown</a>, <a href="../../../../index.html#namespace_utilities">namespace utilities</a>, <a href="../../../../index.html#state_de_serialization">state (de)serialization</a>, <a href="../../../../index.html#unknown_hooking">unknown hooking</a>, <a href="../../../../index.html#utilities">utilities</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 200? Neil Madden (http://wiki.tcl.tk/12790)<br>
Copyright © 200? Various (http://wiki.tcl.tk/1489)<br>
Copyright © 2010 Documentation, Andreas Kupries</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ncgi/ncgi.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
|
<div class='fossil-doc' data-title='ncgi - CGI Support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ncgi(n) 1.4.3 tcllib "CGI Support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ncgi - Procedures to manipulate CGI values.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">ncgi <span class="opt">?1.4.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ncgi::cookie</b> <i class="arg">cookie</i></a></li>
<li><a href="#2"><b class="cmd">::ncgi::decode</b> <i class="arg">str</i></a></li>
<li><a href="#3"><b class="cmd">::ncgi::empty</b> <i class="arg">name</i></a></li>
<li><a href="#4"><b class="cmd">::ncgi::exists</b> <i class="arg">name</i></a></li>
<li><a href="#5"><b class="cmd">::ncgi::encode</b> <i class="arg">string</i></a></li>
<li><a href="#6"><b class="cmd">::ncgi::header</b> <span class="opt">?<i class="arg">type</i>?</span> <i class="arg">args</i></a></li>
<li><a href="#7"><b class="cmd">::ncgi::import</b> <i class="arg">cginame</i> <span class="opt">?<i class="arg">tclname</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::ncgi::importAll</b> <i class="arg">args</i></a></li>
<li><a href="#9"><b class="cmd">::ncgi::importFile</b> <i class="arg">cmd</i> <i class="arg">cginame</i> <span class="opt">?<i class="arg">filename</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::ncgi::input</b> <span class="opt">?<i class="arg">fakeinput</i>?</span> <span class="opt">?<i class="arg">fakecookie</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::ncgi::multipart</b> <i class="arg">type query</i></a></li>
<li><a href="#12"><b class="cmd">::ncgi::nvlist</b></a></li>
<li><a href="#13"><b class="cmd">::ncgi::names</b></a></li>
<li><a href="#14"><b class="cmd">::ncgi::parse</b></a></li>
<li><a href="#15"><b class="cmd">::ncgi::parseMimeValue</b> <i class="arg">value</i></a></li>
<li><a href="#16"><b class="cmd">::ncgi::query</b></a></li>
<li><a href="#17"><b class="cmd">::ncgi::redirect</b> <i class="arg">url</i></a></li>
<li><a href="#18"><b class="cmd">::ncgi::reset</b> <i class="arg">query type</i></a></li>
<li><a href="#19"><b class="cmd">::ncgi::setCookie</b> <i class="arg">args</i></a></li>
<li><a href="#20"><b class="cmd">::ncgi::setDefaultValue</b> <i class="arg">key defvalue</i></a></li>
<li><a href="#21"><b class="cmd">::ncgi::setDefaultValueList</b> <i class="arg">key defvaluelist</i></a></li>
<li><a href="#22"><b class="cmd">::ncgi::setValue</b> <i class="arg">key value</i></a></li>
<li><a href="#23"><b class="cmd">::ncgi::setValueList</b> <i class="arg">key valuelist</i></a></li>
<li><a href="#24"><b class="cmd">::ncgi::type</b></a></li>
<li><a href="#25"><b class="cmd">::ncgi::urlStub</b> <span class="opt">?<i class="arg">url</i>?</span></a></li>
<li><a href="#26"><b class="cmd">::ncgi::value</b> <i class="arg">key</i> <span class="opt">?<i class="arg">default</i>?</span></a></li>
<li><a href="#27"><b class="cmd">::ncgi::valueList</b> <i class="arg">key</i> <span class="opt">?<i class="arg">default</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">ncgi</b> package provides commands that manipulate CGI
values. These are values that come from Web forms and are processed
either by CGI scripts or web pages with embedded Tcl code. Use the
<b class="package">ncgi</b> package to query these values, set and get cookies, and
encode and decode www-url-encoded values.</p>
<p>In the simplest case, a CGI script first calls <b class="cmd">::ncgi::parse</b> and
then calls <b class="cmd">::ncgi::value</b> to get different form values. If a CGI
value is repeated, you should use <b class="cmd">::ncgi::valueList</b> to get back
the complete list of values.</p>
<p>An alternative to <b class="cmd">::ncgi::parse</b> is <b class="cmd">::ncgi::input</b>, which
has semantics similar to Don Libes' <b class="cmd">cgi_input</b> procedure.
<b class="cmd">::ncgi::input</b> restricts repeated CGI values to have names that
end with "List". In this case, <b class="cmd">::ncgi::value</b> will return the
complete list of values, and <b class="cmd">::ncgi::input</b> will raise errors if
it find repeated form elements without the right name.</p>
<p>The <b class="cmd">::ncgi::reset</b> procedure can be used in test suites and Web
servers to initialize the source of the CGI values. Otherwise the
values are read in from the CGI environment.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ncgi::cookie</b> <i class="arg">cookie</i></a></dt>
<dd><p>Return a list of values for <i class="arg">cookie</i>, if any. It is possible that
more than one cookie with the same name can be present, so this
procedure returns a list.</p></dd>
<dt><a name="2"><b class="cmd">::ncgi::decode</b> <i class="arg">str</i></a></dt>
<dd><p>Decode strings in www-url-encoding, which represents special
characters with a %xx sequence, where xx is the character code in hex.</p></dd>
<dt><a name="3"><b class="cmd">::ncgi::empty</b> <i class="arg">name</i></a></dt>
<dd><p>Returns 1 if the CGI variable <i class="arg">name</i> is not present or has the
empty string as its value.</p></dd>
<dt><a name="4"><b class="cmd">::ncgi::exists</b> <i class="arg">name</i></a></dt>
<dd><p>The return value is a boolean. It returns <b class="const">0</b> if the CGI
variable <i class="arg">name</i> is not present, and <b class="const">1</b> otherwise.</p></dd>
<dt><a name="5"><b class="cmd">::ncgi::encode</b> <i class="arg">string</i></a></dt>
<dd><p>Encode <i class="arg">string</i> into www-url-encoded format.</p></dd>
<dt><a name="6"><b class="cmd">::ncgi::header</b> <span class="opt">?<i class="arg">type</i>?</span> <i class="arg">args</i></a></dt>
<dd><p>Output the CGI header to standard output. This emits a Content-Type:
header and additional headers based on <i class="arg">args</i>, which is a list of
header names and header values. The <i class="arg">type</i> defaults to
"text/html".</p></dd>
<dt><a name="7"><b class="cmd">::ncgi::import</b> <i class="arg">cginame</i> <span class="opt">?<i class="arg">tclname</i>?</span></a></dt>
<dd><p>This creates a variable in the current scope with the value of the CGI
variable <i class="arg">cginame</i>. The name of the variable is <i class="arg">tclname</i>, or
<i class="arg">cginame</i> if <i class="arg">tclname</i> is empty (default).</p></dd>
<dt><a name="8"><b class="cmd">::ncgi::importAll</b> <i class="arg">args</i></a></dt>
<dd><p>This imports several CGI variables as Tcl variables. If <i class="arg">args</i> is
empty, then every CGI value is imported. Otherwise each CGI variable
listed in <i class="arg">args</i> is imported.</p></dd>
<dt><a name="9"><b class="cmd">::ncgi::importFile</b> <i class="arg">cmd</i> <i class="arg">cginame</i> <span class="opt">?<i class="arg">filename</i>?</span></a></dt>
<dd><p>This provides information about an uploaded file from a form input
field of type <b class="const">file</b> with name <i class="arg">cginame</i>. <i class="arg">cmd</i> can be
one of <b class="option">-server</b> <b class="option">-client</b>, <b class="option">-type</b> or
<b class="option">-data</b>.</p>
<dl class="doctools_definitions">
<dt><b class="option">-client</b> <i class="arg">cginame</i></dt>
<dd><p>returns the filename as sent by the client.</p></dd>
<dt><b class="option">-type</b> <i class="arg">cginame</i></dt>
<dd><p>returns the mime type of the uploaded file.</p></dd>
<dt><b class="option">-data</b> <i class="arg">cginame</i></dt>
<dd><p>returns the contents of the file.</p></dd>
<dt><b class="option">-server</b> <i class="arg">cginame</i> <i class="arg">filename</i></dt>
<dd><p>writes the file contents to a local temporary file (or <i class="arg">filename</i>
if supplied) and returns the name of the file. The caller is
responsible for deleting this file after use.</p></dd>
</dl></dd>
<dt><a name="10"><b class="cmd">::ncgi::input</b> <span class="opt">?<i class="arg">fakeinput</i>?</span> <span class="opt">?<i class="arg">fakecookie</i>?</span></a></dt>
<dd><p>This reads and decodes the CGI values from the environment. It
restricts repeated form values to have a trailing "List" in their
name. The CGI values are obtained later with the <b class="cmd">::ncgi::value</b>
procedure.</p></dd>
<dt><a name="11"><b class="cmd">::ncgi::multipart</b> <i class="arg">type query</i></a></dt>
<dd><p>This procedure parses a multipart/form-data <i class="arg">query</i>. This is used
by <b class="cmd">::ncgi::nvlist</b> and not normally called directly. It returns
an alternating list of names and structured values. Each structure
value is in turn a list of two elements. The first element is
meta-data from the multipart/form-data structure. The second element
is the form value. If you use <b class="cmd">::ncgi::value</b> you just get the
form value. If you use <b class="cmd">::ncgi::valueList</b> you get the structured
value with meta data and the value.</p>
<p>The <i class="arg">type</i> is the whole Content-Type, including the parameters
like <i class="arg">boundary</i>. This returns a list of names and values that
describe the multipart data. The values are a nested list structure
that has some descriptive information first, and the actual form value
second. The descriptive information is list of header names and
values that describe the content.</p></dd>
<dt><a name="12"><b class="cmd">::ncgi::nvlist</b></a></dt>
<dd><p>This returns all the query data as a name, value list. In the case of
multipart/form-data, the values are structured as described in
<b class="cmd">::ncgi::multipart</b>.</p></dd>
<dt><a name="13"><b class="cmd">::ncgi::names</b></a></dt>
<dd><p>This returns all names found in the query data, as a list.
<b class="cmd">::ncgi::multipart</b>.</p></dd>
<dt><a name="14"><b class="cmd">::ncgi::parse</b></a></dt>
<dd><p>This reads and decodes the CGI values from the environment. The CGI
values are obtained later with the <b class="cmd">::ncgi::value</b> procedure. IF
a CGI value is repeated, then you should use <b class="cmd">::ncgi::valueList</b>
to get the complete list of values.</p></dd>
<dt><a name="15"><b class="cmd">::ncgi::parseMimeValue</b> <i class="arg">value</i></a></dt>
<dd><p>This decodes the Content-Type and other MIME headers that have the
form of "primary value; param=val; p2=v2" It returns a list, where the
first element is the primary value, and the second element is a list
of parameter names and values.</p></dd>
<dt><a name="16"><b class="cmd">::ncgi::query</b></a></dt>
<dd><p>This returns the raw query data.</p></dd>
<dt><a name="17"><b class="cmd">::ncgi::redirect</b> <i class="arg">url</i></a></dt>
<dd><p>Generate a response that causes a 302 redirect by the Web server. The
<i class="arg">url</i> is the new URL that is the target of the redirect. The URL
will be qualified with the current server and current directory, if
necessary, to convert it into a full URL.</p></dd>
<dt><a name="18"><b class="cmd">::ncgi::reset</b> <i class="arg">query type</i></a></dt>
<dd><p>Set the query data and Content-Type for the current CGI session. This
is used by the test suite and by Web servers to initialize the ncgi
module so it does not try to read standard input or use environment
variables to get its data. If neither <i class="arg">query</i> or <i class="arg">type</i> are
specified, then the <b class="package">ncgi</b> module will look in the standard
CGI environment for its data.</p></dd>
<dt><a name="19"><b class="cmd">::ncgi::setCookie</b> <i class="arg">args</i></a></dt>
<dd><p>Set a cookie value that will be returned as part of the reply. This
must be done before <b class="cmd">::ncgi::header</b> or <b class="cmd">::ncgi::redirect</b> is
called in order for the cookie to be returned properly. The
<i class="arg">args</i> are a set of flags and values:</p>
<dl class="doctools_definitions">
<dt><b class="option">-name</b> <i class="arg">name</i></dt>
<dd></dd>
<dt><b class="option">-value</b> <i class="arg">value</i></dt>
<dd></dd>
<dt><b class="option">-expires</b> <i class="arg">date</i></dt>
<dd></dd>
<dt><b class="option">-path</b> <i class="arg">path restriction</i></dt>
<dd></dd>
<dt><b class="option">-domain</b> <i class="arg">domain restriction</i></dt>
<dd></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">::ncgi::setDefaultValue</b> <i class="arg">key defvalue</i></a></dt>
<dd><p>Set a CGI value if it does not already exists. This affects future
calls to <b class="cmd">::ncgi::value</b> (but not future calls to
<b class="cmd">::ncgi::nvlist</b>). If the CGI value already is present, then this
procedure has no side effects.</p></dd>
<dt><a name="21"><b class="cmd">::ncgi::setDefaultValueList</b> <i class="arg">key defvaluelist</i></a></dt>
<dd><p>Like <b class="cmd">::ncgi::setDefaultValue</b> except that the value already has
list structure to represent multiple checkboxes or a multi-selection.</p></dd>
<dt><a name="22"><b class="cmd">::ncgi::setValue</b> <i class="arg">key value</i></a></dt>
<dd><p>Set a CGI value, overriding whatever was present in the CGI
environment already. This affects future calls to <b class="cmd">::ncgi::value</b>
(but not future calls to <b class="cmd">::ncgi::nvlist</b>).</p></dd>
<dt><a name="23"><b class="cmd">::ncgi::setValueList</b> <i class="arg">key valuelist</i></a></dt>
<dd><p>Like <b class="cmd">::ncgi::setValue</b> except that the value already has list
structure to represent multiple checkboxes or a multi-selection.</p></dd>
<dt><a name="24"><b class="cmd">::ncgi::type</b></a></dt>
<dd><p>Returns the Content-Type of the current CGI values.</p></dd>
<dt><a name="25"><b class="cmd">::ncgi::urlStub</b> <span class="opt">?<i class="arg">url</i>?</span></a></dt>
<dd><p>Returns the current URL, but without the protocol, server, and port.
If <i class="arg">url</i> is specified, then it defines the URL for the current
session. That value will be returned by future calls to
<b class="cmd">::ncgi::urlStub</b></p></dd>
<dt><a name="26"><b class="cmd">::ncgi::value</b> <i class="arg">key</i> <span class="opt">?<i class="arg">default</i>?</span></a></dt>
<dd><p>Return the CGI value identified by <i class="arg">key</i>. If the CGI value is not
present, then the <i class="arg">default</i> value is returned instead. This value
defaults to the empty string.</p>
<p>If the form value <i class="arg">key</i> is repeated, then there are two cases: if
<b class="cmd">::ncgi::parse</b> was called, then <b class="cmd">::ncgi::value</b> only returns
the first value associated with <i class="arg">key</i>. If <b class="cmd">::ncgi::input</b> was
called, then <b class="cmd">::ncgi::value</b> returns a Tcl list value and
<i class="arg">key</i> must end in "List" (e.g., "skuList"). In the case of
multipart/form-data, this procedure just returns the value of the form
element. If you want the meta-data associated with each form value,
then use <b class="cmd">::ncgi::valueList</b>.</p></dd>
<dt><a name="27"><b class="cmd">::ncgi::valueList</b> <i class="arg">key</i> <span class="opt">?<i class="arg">default</i>?</span></a></dt>
<dd><p>Like <b class="cmd">::ncgi::value</b>, but this always returns a list of values
(even if there is only one value). In the case of
multipart/form-data, this procedure returns a list of two elements.
The first element is meta-data in the form of a parameter, value list.
The second element is the form value.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>Uploading a file</p>
<pre class="doctools_example">
HTML:
<html>
<form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
Path: <input type="file" name="filedata"><br>
Name: <input type="text" name="filedesc"><br>
<input type="submit">
</form>
</html>
TCL: upload.cgi
#!/usr/local/bin/tclsh
::ncgi::parse
set filedata [::ncgi::value filedata]
set filedesc [::ncgi::value filedesc]
puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"
set filename /www/images/$filedesc
set fh [open $filename w]
puts -nonewline $fh $filedata
close $fh
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ncgi</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../html/html.html">html</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cgi">CGI</a>, <a href="../../../../index.html#cookie">cookie</a>, <a href="../../../../index.html#form">form</a>, <a href="../../../../index.html#html">html</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>CGI programming</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nettool/nettool.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
<div class='fossil-doc' data-title='nettool - nettool'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nettool(n) 0.5.2 tcllib "nettool"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nettool - Tools for networked applications</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">nettool <span class="opt">?0.5.2?</span></b></li>
<li>package require <b class="pkgname">twapi 3.1</b></li>
<li>package require <b class="pkgname">ip 0.1</b></li>
<li>package require <b class="pkgname">platform 0.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::cat</b> <i class="arg">filename</i></a></li>
<li><a href="#2"><b class="cmd">::nettool::allocate_port</b> <i class="arg">startingport</i></a></li>
<li><a href="#3"><b class="cmd">::nettool::arp_table</b></a></li>
<li><a href="#4"><b class="cmd">::nettool::broadcast_list</b></a></li>
<li><a href="#5"><b class="cmd">::nettool::claim_port</b> <i class="arg">port</i> <span class="opt">?<i class="arg">protocol</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::nettool::cpuinfo</b> <i class="arg">args</i></a></li>
<li><a href="#7"><b class="cmd">::nettool::find_port</b> <i class="arg">startingport</i></a></li>
<li><a href="#8"><b class="cmd">::nettool::hwid_list</b></a></li>
<li><a href="#9"><b class="cmd">::nettool::ip_list</b></a></li>
<li><a href="#10"><b class="cmd">::nettool::mac_list</b></a></li>
<li><a href="#11"><b class="cmd">::nettool::network_list</b></a></li>
<li><a href="#12"><b class="cmd">::nettool::port_busy</b> <i class="arg">port</i></a></li>
<li><a href="#13"><b class="cmd">::nettool::release_port</b> <i class="arg">port</i> <span class="opt">?<i class="arg">protocol</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::nettool::status</b></a></li>
<li><a href="#15"><b class="cmd">::nettool::user_data_root</b> <i class="arg">appname</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">nettool</b> package consists of a Pure-tcl set of tools
to perform common network functions that would normally require
different packages or calls to exec, in a standard Tcl interface.
At present nettool has reference implementations for the following operating
systems: Windows, MacOSX, and Linux (debian).</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::cat</b> <i class="arg">filename</i></a></dt>
<dd><p>Dump the contents of a file as a result.</p></dd>
<dt><a name="2"><b class="cmd">::nettool::allocate_port</b> <i class="arg">startingport</i></a></dt>
<dd><p>Attempt to allocate <i class="arg">startingport</i>, or, if busy, advance the port
number sequentially until a free port is found, and claim that port.
This command uses a built-in database of known ports to avoid returning a
port which is in common use. (For example: http (80))</p></dd>
<dt><a name="3"><b class="cmd">::nettool::arp_table</b></a></dt>
<dd><p>Dump the contents of this computer's Address Resolution Protocol (ARP) table.
The result will be a Tcl formatted list: <i class="arg">macid</i> <i class="arg">ipaddrlist</i> ...</p></dd>
<dt><a name="4"><b class="cmd">::nettool::broadcast_list</b></a></dt>
<dd><p>Returns a list of broadcast addresses (suitable for UDP multicast)
that this computer is associated with.</p></dd>
<dt><a name="5"><b class="cmd">::nettool::claim_port</b> <i class="arg">port</i> <span class="opt">?<i class="arg">protocol</i>?</span></a></dt>
<dd><p>Mark <i class="arg">port</i> as busy, optionally as either <b class="const">tcp</b> (default) or <b class="const">udp</b>.</p></dd>
<dt><a name="6"><b class="cmd">::nettool::cpuinfo</b> <i class="arg">args</i></a></dt>
<dd><p>If no arguments are given, return a key/value list describing the
CPU of the present machine. Included in the matrix is info on the number
of cores/processors that are available for parallel tasking, installed physical
RAM, and processor family.</p>
<p>The exact contents are platform specific.</p>
<p>For Linux, information is drawn from /proc/cpuinfo and /proc/meminfo.</p>
<p>For MacOSX, information is drawn from sysctl</p>
<p>For Windows, information is draw from TWAPI.</p>
<p>If arguments are given, the result with be a key/value list limited to the
fields requested.</p>
<p>Canonical fields for all platforms:</p>
<dl class="doctools_definitions">
<dt>cpus</dt>
<dd><p>Count of CPUs/cores/execution units</p></dd>
<dt>speed</dt>
<dd><p>Clock speed of processor(s) in Mhz</p></dd>
<dt>memory</dt>
<dd><p>Installed RAM (in MB)</p></dd>
<dt>vendor</dt>
<dd><p>Manufacturer</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::nettool::find_port</b> <i class="arg">startingport</i></a></dt>
<dd><p>Return <i class="arg">startingport</i> if it is available, or the next free port after
<i class="arg">startingport</i>. Note: Unlike <b class="cmd">::nettool::allocate_port</b>, this
command does not claim the port.</p>
<p>This command uses a built-in database of known ports to avoid returning a
port which is in common use. (For example: http (80))</p></dd>
<dt><a name="8"><b class="cmd">::nettool::hwid_list</b></a></dt>
<dd><p>Return a list of hardware specific identifiers from this computer. The source
and content will vary by platform.</p>
<p>For MacOSX, the motherboard serial number and macids for all network devices is returned.</p>
<p>For Windows, the volume serial number of C and macids for all network devices is returned.</p>
<p>For Linux, macids for all network devices is returned.</p></dd>
<dt><a name="9"><b class="cmd">::nettool::ip_list</b></a></dt>
<dd><p>Return a list of IP addresses associated with this computer.</p></dd>
<dt><a name="10"><b class="cmd">::nettool::mac_list</b></a></dt>
<dd><p>Return a list of MACIDs for the network cards attached to this machine. The MACID of the
primary network card is returned first.</p></dd>
<dt><a name="11"><b class="cmd">::nettool::network_list</b></a></dt>
<dd><p>Return a list of networks associated with this computer. Networks are formated with
<b class="cmd">ip::nativeToPrefix</b>.</p></dd>
<dt><a name="12"><b class="cmd">::nettool::port_busy</b> <i class="arg">port</i></a></dt>
<dd><p>Return true if <i class="arg">port</i> is claimed, false otherwise.</p></dd>
<dt><a name="13"><b class="cmd">::nettool::release_port</b> <i class="arg">port</i> <span class="opt">?<i class="arg">protocol</i>?</span></a></dt>
<dd><p>Mark <i class="arg">port</i> as not busy, optionally as either <b class="const">tcp</b> (default) or <b class="const">udp</b>.</p></dd>
<dt><a name="14"><b class="cmd">::nettool::status</b></a></dt>
<dd><p>Return a key/value list describing the status of the computer. The output
is designed to be comparable to the output of <b class="cmd">top</b> for all platforms.</p>
<p>Common fields include:</p>
<dl class="doctools_definitions">
<dt>load</dt>
<dd><p>Processes per processing unit</p></dd>
<dt>memory_total</dt>
<dd><p>Total physical RAM (MB)</p></dd>
<dt>memory_free</dt>
<dd><p>Total physical RAM unused (MB)</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">::nettool::user_data_root</b> <i class="arg">appname</i></a></dt>
<dd><p>Return a fully qualified path to a folder where <i class="arg">appname</i> should store it's data.
The path is not created, only computed, by this command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>odie</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#nettool">nettool</a>, <a href="../../../../index.html#odie">odie</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>System</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015-2018 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nmea/nmea.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
<div class='fossil-doc' data-title='nmea - NMEA protocol implementation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nmea(n) 1.0.0 tcllib "NMEA protocol implementation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nmea - Process NMEA data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">nmea <span class="opt">?1.0.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::nmea::input</b> <i class="arg">sentence</i></a></li>
<li><a href="#2"><b class="cmd">::nmea::open_port</b> <i class="arg">port</i> <span class="opt">?speed?</span></a></li>
<li><a href="#3"><b class="cmd">::nmea::close_port</b></a></li>
<li><a href="#4"><b class="cmd">::nmea::configure_port</b> <i class="arg">settings</i></a></li>
<li><a href="#5"><b class="cmd">::nmea::open_file</b> <i class="arg">file</i> <span class="opt">?rate?</span></a></li>
<li><a href="#6"><b class="cmd">::nmea::close_file</b></a></li>
<li><a href="#7"><b class="cmd">::nmea::do_line</b></a></li>
<li><a href="#8"><b class="cmd">::nmea::rate</b></a></li>
<li><a href="#9"><b class="cmd">::nmea::log</b> <span class="opt">?file?</span></a></li>
<li><a href="#10"><b class="cmd">::nmea::checksum</b> <i class="arg">data</i></a></li>
<li><a href="#11"><b class="cmd">::nmea::write</b> <i class="arg">sentence</i> <i class="arg">data</i></a></li>
<li><a href="#12"><b class="cmd">::nmea::event</b> <i class="arg">setence</i> <span class="opt">?command?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a standard interface for writing software which recieves
NMEA standard input data. It allows for reading data from COM ports, files,
or programmatic input. It also supports the checksumming and logging of incoming data.
After parsing, input is dispatched to user defined handler commands for processing.
To define a handler, see the <b class="cmd"><a href="../../../../index.html#event">event</a></b> command. There are no GPS specific functions
in this package. NMEA data consists of a sentence type, followed by a list of data.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::nmea::input</b> <i class="arg">sentence</i></a></dt>
<dd><p>Processes and dispatches the supplied sentence. If <i class="arg">sentence</i> contains no commas it is treated as a Tcl list, otherwise it must be standard comma delimited NMEA data, with an optional checksum and leading <b class="const">$</b>.</p>
<pre class="doctools_example">
nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39}
nmea::input [list GPGSA A 3 04 05 09 12 "" "" 24 "" "" "" 2.5 1.3 2.1]
</pre>
</dd>
<dt><a name="2"><b class="cmd">::nmea::open_port</b> <i class="arg">port</i> <span class="opt">?speed?</span></a></dt>
<dd><p>Open the specified COM port and read NMEA sentences when available. Port speed is set to
4800bps by default or to <i class="arg">speed</i>.</p></dd>
<dt><a name="3"><b class="cmd">::nmea::close_port</b></a></dt>
<dd><p>Close the com port connection if one is open.</p></dd>
<dt><a name="4"><b class="cmd">::nmea::configure_port</b> <i class="arg">settings</i></a></dt>
<dd><p>Changes the current port settings. <i class="arg">settings</i> has the same format as fconfigure -mode.</p></dd>
<dt><a name="5"><b class="cmd">::nmea::open_file</b> <i class="arg">file</i> <span class="opt">?rate?</span></a></dt>
<dd><p>Open file <i class="arg">file</i> and read NMEA sentences, one per line, at the rate specified by <span class="opt">?rate?</span> in milliseconds.
The file format may omit the leading <b class="const">$</b> and/or the checksum. If rate is <= 0 (the default) then lines
will only be processed when a call to <b class="cmd">do_line</b> is made.</p></dd>
<dt><a name="6"><b class="cmd">::nmea::close_file</b></a></dt>
<dd><p>Close the open file if one exists.</p></dd>
<dt><a name="7"><b class="cmd">::nmea::do_line</b></a></dt>
<dd><p>If there is a currently open file, this command will read and process a single line from it.
Returns the number of lines read.</p></dd>
<dt><a name="8"><b class="cmd">::nmea::rate</b></a></dt>
<dd><p>Sets the rate at which lines are processed from the open file, in milliseconds. The rate remains
consistant across files, there does not need to be a file currently open to use this command.
Set to 0 to disable automatic line processing.</p></dd>
<dt><a name="9"><b class="cmd">::nmea::log</b> <span class="opt">?file?</span></a></dt>
<dd><p>Starts or stops input logging. If a file name is specified then all NMEA data recieved on
the open port will be logged to the <span class="opt">?file?</span> in append mode. If file is an empty string then
any logging will be stopped. If no file is specified then returns a boolean value indicating
if logging is currently enabled. Data written to the port by <b class="cmd">write</b>,
data read from files, or input made using <b class="cmd">input</b>, is not logged.</p></dd>
<dt><a name="10"><b class="cmd">::nmea::checksum</b> <i class="arg">data</i></a></dt>
<dd><p>Returns the checksum of the supplied data.</p></dd>
<dt><a name="11"><b class="cmd">::nmea::write</b> <i class="arg">sentence</i> <i class="arg">data</i></a></dt>
<dd><p>If there is a currently open port, this command will write the specified sentence and data to the port
in proper NMEA checksummed format.</p></dd>
<dt><a name="12"><b class="cmd">::nmea::event</b> <i class="arg">setence</i> <span class="opt">?command?</span></a></dt>
<dd><p>Registers a handler proc for a given NMEA <i class="arg">sentence</i>. There may be at most one handler per
sentence, any existing handler is replaced.
If no command is specified, returns the name of the current handler for the given <i class="arg">setence</i>
or an empty string if none exists. In addition to the incoming sentences there are 2 builtin types,
EOF and DEFAULT. The handler for the DEFAULT setence is invoked if there is not a specific handler
for that sentence. The EOF handler is invoked when End Of File is reached on the open file or port.</p>
<p>The handler procedures, with the exception of the builtin types,must take exactly one argument,
which is a list of the data values.
The DEFAULT handler should have two arguments, the sentence type and the data values.
The EOF handler has no arguments.</p>
<pre class="doctools_example">
nmea::event gpgsa parse_sat_detail
nmea::event default handle_unknown
proc parse_sat_detail {data} {
puts [lindex $data 1]
}
proc handle_unknown {name data} {
puts "unknown data type $name"
}
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nmea</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#gps">gps</a>, <a href="../../../../index.html#nmea">nmea</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2009, Aaron Faupell <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nns/nns_auto.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<div class='fossil-doc' data-title='nameserv::auto - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nameserv::auto(n) 0.3 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nameserv::auto - Name service facility, Client Extension</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">EVENTS</a></li>
<li class="doctools_section"><a href="#section5">DESIGN</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">nameserv::auto <span class="opt">?0.3?</span></b></li>
<li>package require <b class="pkgname">nameserv</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read the document <i class="term"><a href="nns_intro.html">Name service facility, introduction</a></i>
first.</p>
<p>This package provides the <em>exact</em> same API as is provided by
package <b class="package"><a href="nns_client.html">nameserv</a></b>, i.e. the regular name service client. It
differs from the former by taking measures to ensure that longer-lived
data, i.e. bound names, continuous and unfullfilled async searches,
survive the loss of the connection to the name server as much as is
possible.</p>
<p>This means that the bound names and continuous and unfullfilled async
searches are remembered client-side and automatically re-entered into
the server when the connection comes back after its loss. For bound
names there is one important limitation to such restoration: It is
possible that a name of this client was bound by a different client
while the connection was gone. Such names are fully lost, and the best
the package can and will do is to inform the user of this.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The user-visible API is mainly identical to the API of <b class="package"><a href="nns_client.html">nameserv</a></b>
and is therefore not described here. Please read the documentation of
<b class="package"><a href="nns_client.html">nameserv</a></b>.</p>
<p>The differences are explained below, in the sections <span class="sectref"><a href="#section3">OPTIONS</a></span> and
<span class="sectref"><a href="#section4">EVENTS</a></span>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<p>This package supports all the options of package <b class="package"><a href="nns_client.html">nameserv</a></b>,
plus one more. The additional option allows the user to specify the
time interval between attempts to restore a lost connection.</p>
<dl class="doctools_options">
<dt><b class="option">-delay</b> <i class="arg">milliseconds</i></dt>
<dd><p>The value of this option is an integer value > 0 which specifies the
interval to wait between attempts to restore a lost connection, in
milliseconds. The default value is <b class="const">1000</b>, i.e. one second.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EVENTS</a></h2>
<p>This package generates all of the events of package <b class="package"><a href="nns_client.html">nameserv</a></b>,
plus two more. Both events are generated for the tag <i class="term"><a href="nns_client.html">nameserv</a></i>.</p>
<dl class="doctools_definitions">
<dt><i class="term">lost-name</i></dt>
<dd><p>This event is generated when a bound name is truly lost, i.e. could
not be restored after the temporary loss of the connection to the name
server. It indicates that a different client took ownership of the
name while this client was out of contact.</p>
<p>The detail information of the event will be a Tcl dictionary
containing two keys, <b class="const">name</b>, and <b class="const">data</b>. Their values hold
all the information about the lost name.</p></dd>
<dt><i class="term">re-connection</i></dt>
<dd><p>This event is generated when the connection to the server is
restored. The remembered data has been restored when the event is
posted.</p>
<p>The event has no detail information.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">DESIGN</a></h2>
<p>The package is implemented on top of the regular nameservice client,
i.e. package <b class="package"><a href="nns_client.html">nameserv</a></b>. It detects the loss of the
connection by listening for <i class="term">lost-connection</i> events, on the tag
<i class="term"><a href="nns_client.html">nameserv</a></i>.</p>
<p>It reacts to such events by starting a periodic timer and trying to
reconnect to the server whenver this timer triggers. On success the
timer is canceled, a <i class="term">re-connection</i> event generated, and the
package proceeds to re-enter the remembered bound names and continuous
searches.</p>
<p>Another loss of the connection, be it during or after re-entering the
remembered information simply restarts the timer and subsequent
reconnection attempts.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="nns_client.html">nameserv(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#automatic">automatic</a>, <a href="../../../../index.html#client">client</a>, <a href="../../../../index.html#name_service">name service</a>, <a href="../../../../index.html#reconnect">reconnect</a>, <a href="../../../../index.html#restore">restore</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nns/nns_client.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
|
<div class='fossil-doc' data-title='nameserv - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nameserv(n) 0.4.2 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nameserv - Name service facility, Client</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">CONNECTION HANDLING</a></li>
<li class="doctools_section"><a href="#section4">EVENTS</a></li>
<li class="doctools_section"><a href="#section5">OPTIONS</a></li>
<li class="doctools_section"><a href="#section6">ASYNCHRONOUS AND CONTINUOUS SEARCHES</a></li>
<li class="doctools_section"><a href="#section7">HISTORY</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">nameserv <span class="opt">?0.4.2?</span></b></li>
<li>package require <b class="pkgname">comm</b></li>
<li>package require <b class="pkgname">logger</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::nameserv::bind</b> <i class="arg">name</i> <i class="arg">data</i></a></li>
<li><a href="#2"><b class="cmd">::nameserv::release</b></a></li>
<li><a href="#3"><b class="cmd">::nameserv::search</b> <span class="opt">?<b class="option">-async</b>|<b class="option">-continuous</b>?</span> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::nameserv::protocol</b></a></li>
<li><a href="#5"><b class="cmd">::nameserv::server_protocol</b></a></li>
<li><a href="#6"><b class="cmd">::nameserv::server_features</b></a></li>
<li><a href="#7"><b class="cmd">::nameserv::cget</b> <b class="option">-option</b></a></li>
<li><a href="#8"><b class="cmd">::nameserv::configure</b></a></li>
<li><a href="#9"><b class="cmd">::nameserv::configure</b> <b class="option">-option</b></a></li>
<li><a href="#10"><b class="cmd">::nameserv::configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
<li><a href="#11"><b class="cmd">$result</b> <b class="method">destroy</b></a></li>
<li><a href="#12"><b class="cmd">$result</b> <b class="method">filled</b></a></li>
<li><a href="#13"><b class="cmd">$result</b> <b class="method">get</b> <i class="arg">name</i></a></li>
<li><a href="#14"><b class="cmd">$result</b> <b class="method">names</b></a></li>
<li><a href="#15"><b class="cmd">$result</b> <b class="method">size</b></a></li>
<li><a href="#16"><b class="cmd">$result</b> <b class="method">getall</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read <i class="term"><a href="nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>This package provides a client for the name service facility
implemented by the package <b class="package"><a href="nns_server.html">nameserv::server</a></b>.</p>
<p>This service is built in top of and for the package <b class="package"><a href="../comm/comm.html">comm</a></b>.
It has nothing to do with the Internet's Domain Name System. If the
reader is looking for a package dealing with that please see Tcllib's
packages <b class="package"><a href="../dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports eight commands, as specified below:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::nameserv::bind</b> <i class="arg">name</i> <i class="arg">data</i></a></dt>
<dd><p>The caller of this command registers the given <i class="arg">name</i> as its name
in the configured name service, and additionally associates a piece of
<i class="arg">data</i> with it. The service does nothing with this information
beyond storing it and delivering it as part of search results. The
meaning is entirely up to the applications using the name service.</p>
<p>A generally useful choice would for example be an identifier for a
communication endpoint managed by the package <b class="package"><a href="../comm/comm.html">comm</a></b>. Anybody
retrieving the name becomes immediately able to talk to this endpoint,
i.e. the registering application.</p>
<p>Of further importance is that a caller can register itself under more
than one name, and each name can have its own piece of <i class="arg">data</i>.</p>
<p>Note that the name service, and thwerefore this command, will throw an
error if the chosen name is already registered.</p></dd>
<dt><a name="2"><b class="cmd">::nameserv::release</b></a></dt>
<dd><p>Invoking this command releases all names (and their data) registered
by all previous calls to <b class="cmd">::nameserv::bind</b> of this client. Note
that the name service will run this command implicitly when it loses
the connection to this client.</p></dd>
<dt><a name="3"><b class="cmd">::nameserv::search</b> <span class="opt">?<b class="option">-async</b>|<b class="option">-continuous</b>?</span> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>This command searches the name service for all registered names
matching the specified glob-<i class="arg">pattern</i>. If not specified the
pattern defaults to <b class="const">*</b>, matching everything. The result of the
command is a dictionary mapping the matching names to the data
associated with them at <i class="term"><a href="../../../../index.html#bind">bind</a></i>-time.</p>
<p>If either option <b class="option">-async</b> or <b class="option">-continuous</b> were
specified the result of this command changes and becomes the Tcl
command of an object holding the actual result.
These two options are supported if and only if the service the client
is connected to supports the protocol feature
<i class="term">Search/Continuous</i>.</p>
<p>For <b class="option">-async</b> the result object is asynchronously filled with
the entries matching the pattern at the time of the search and then
not modified any more.
The option <b class="option">-continuous</b> extends this behaviour by additionally
continuously monitoring the service for the addition and removal of
entries which match the pattern, and updating the object's contents
appropriately.</p>
<p><em>Note</em> that the caller is responsible for configuring the object
with a callback for proper notification when the current result (or
further changes) arrive.</p>
<p>For more information about this object see section
<span class="sectref"><a href="#section6">ASYNCHRONOUS AND CONTINUOUS SEARCHES</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::nameserv::protocol</b></a></dt>
<dd><p>This command returns the highest version of the name service protocol
supported by the package.</p></dd>
<dt><a name="5"><b class="cmd">::nameserv::server_protocol</b></a></dt>
<dd><p>This command returns the highest version of the name service protocol
supported by the name service the client is currently connected to.</p></dd>
<dt><a name="6"><b class="cmd">::nameserv::server_features</b></a></dt>
<dd><p>This command returns a list containing the names of the features of
the name service protocol which are supported by the name service the
client is currently connected to.</p></dd>
<dt><a name="7"><b class="cmd">::nameserv::cget</b> <b class="option">-option</b></a></dt>
<dd><p>This command returns the currently configured value for the specified
<b class="option">-option</b>. The list of supported options and their meaning can
be found in section <span class="sectref"><a href="#section5">OPTIONS</a></span>.</p></dd>
<dt><a name="8"><b class="cmd">::nameserv::configure</b></a></dt>
<dd><p>In this form the command returns a dictionary of all supported
options, and their current values. The list of supported options and
their meaning can be found in section <span class="sectref"><a href="#section5">OPTIONS</a></span>.</p></dd>
<dt><a name="9"><b class="cmd">::nameserv::configure</b> <b class="option">-option</b></a></dt>
<dd><p>In this form the command is an alias for
"<b class="cmd">::nameserv::cget</b> <b class="option">-option</b>".
The list of supported options and their meaning can be found in
section <span class="sectref"><a href="#section5">OPTIONS</a></span>.</p></dd>
<dt><a name="10"><b class="cmd">::nameserv::configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>In this form the command is used to configure one or more of the
supported options. At least one option has to be specified, and each
option is followed by its new value.
The list of supported options and their meaning can be found in
section <span class="sectref"><a href="#section5">OPTIONS</a></span>.</p>
<p>This form can be used only as long as the client has not contacted the
name service yet. After contact has been made reconfiguration is not
possible anymore. This means that this form of the command is for the
initalization of the client before it use.
The command forcing a contact with the name service are</p>
<dl class="doctools_commands">
<dt><b class="cmd"><a href="../../../../index.html#bind">bind</a></b></dt>
<dd></dd>
<dt><b class="cmd">release</b></dt>
<dd></dd>
<dt><b class="cmd">search</b></dt>
<dd></dd>
<dt><b class="cmd">server_protocol</b></dt>
<dd></dd>
<dt><b class="cmd">server_features</b></dt>
<dd></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CONNECTION HANDLING</a></h2>
<p>The client automatically connects to the service when one of the
commands below is run for the first time, or whenever one of the
commands is run after the connection was lost, when it was lost.</p>
<dl class="doctools_commands">
<dt><b class="cmd"><a href="../../../../index.html#bind">bind</a></b></dt>
<dd></dd>
<dt><b class="cmd">release</b></dt>
<dd></dd>
<dt><b class="cmd">search</b></dt>
<dd></dd>
<dt><b class="cmd">server_protocol</b></dt>
<dd></dd>
<dt><b class="cmd">server_features</b></dt>
<dd></dd>
</dl>
<p>Since version 0.2 of the client it will generate an event when the
connection is lost, allowing higher layers to perform additional
actions. This is done via the support package <b class="package"><a href="../uev/uevent.html">uevent</a></b>. This
and all other name service related packages hereby reserve the
uevent-tag <i class="term">nameserv</i>. All their events will be posted to that
tag.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EVENTS</a></h2>
<p>This package generates only one event, <i class="term">lost-connection</i>. The
detail information provided to that event is a Tcl dictionary. The
only key contained in the dictionnary is <b class="const">reason</b>, and its value
will be a string describing why the connection was lost.
This string is supplied by the underlying communication package,
i.e. <b class="package"><a href="../comm/comm.html">comm</a></b>.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">OPTIONS</a></h2>
<p>The options supported by the client are for the specification of which
name service to contact, i.e. of the location of the name service.
They are:</p>
<dl class="doctools_options">
<dt><b class="option">-host</b> <i class="arg">name</i>|<i class="arg">ipaddress</i></dt>
<dd><p>This option specifies the host name service to contact is running on,
either by <i class="arg">name</i>, or by <i class="arg">ipaddress</i>. The initial default is
<b class="const">localhost</b>, i.e. it is expected to contact a name service
running on the same host as the application using this package.</p></dd>
<dt><b class="option">-port</b> <i class="arg">number</i></dt>
<dd><p>This option specifies the port the name service to contact is
listening on. It has to be a positive integer number (> 0) not greater
than 65536 (unsigned short). The initial default is the number
returned by the command <b class="cmd">::nameserv::common::port</b>, as provided by
the package <b class="package">::nameserv::common</b>.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">ASYNCHRONOUS AND CONTINUOUS SEARCHES</a></h2>
<p>Asynchronous and continuous searches are invoked by using either
option <b class="option">-async</b> or <b class="option">-continuous</b> as argument to the
command <b class="cmd">::nameserv::search</b>.</p>
<p><em>Note</em> that these two options are supported if and only if the
service the client is connected to supports the protocol feature
<i class="term">Search/Continuous</i>. The service provided by the package
<b class="package">::nameserv::server</b> does this since version 0.3.</p>
<p>For such searches the result of the search command is the Tcl command
of an object holding the actual result. The API provided by these
objects is:</p>
<dl class="doctools_definitions">
<dt>Options:</dt>
<dd><dl class="doctools_options">
<dt><b class="option">-command</b> <i class="arg">command_prefix</i></dt>
<dd><p>This option has to be set if a user of the result object wishes to get
asynchronous notifications when the search result or changes to it
arrive.</p>
<p><em>Note</em> that while it is possible to poll for the arrival of the
initial search result via the method <b class="method">filled</b>, and for
subsequent changes by comparing the output of method <b class="method">getall</b>
against a saved copy, this is not the recommended behaviour. Setting
the <b class="option">-command</b> callback and processing the notifications as
they arrive is much more efficient.</p>
<p>The <i class="arg">command_prefix</i> is called with two arguments, the type of
change, and the data of the change. The type is either <b class="const">add</b> or
<b class="const">remove</b>, indicating new data, or deleted data, respectively.
The data of the change is always a dictionary listing the
added/removed names and their associated data.</p>
<p>The first change reported for a search is always the set of matching
entries at the time of the search.</p></dd>
</dl></dd>
<dt>Methods:</dt>
<dd><dl class="doctools_definitions">
<dt><a name="11"><b class="cmd">$result</b> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the object and cancels any continuous monitoring of the
service the object may have had active.</p></dd>
<dt><a name="12"><b class="cmd">$result</b> <b class="method">filled</b></a></dt>
<dd><p>The result is a boolean value indicating whether the search result has
already arrived (<b class="const">True</b>), or not (<b class="const">False</b>).</p></dd>
<dt><a name="13"><b class="cmd">$result</b> <b class="method">get</b> <i class="arg">name</i></a></dt>
<dd><p>Returns the data associated with the given <i class="arg">name</i> at
<i class="term"><a href="../../../../index.html#bind">bind</a></i>-time.</p></dd>
<dt><a name="14"><b class="cmd">$result</b> <b class="method">names</b></a></dt>
<dd><p>Returns a list containing all names known to the object at the time of
the invokation.</p></dd>
<dt><a name="15"><b class="cmd">$result</b> <b class="method">size</b></a></dt>
<dd><p>Returns an integer value specifying the size of the result at the time
of the invokation.</p></dd>
<dt><a name="16"><b class="cmd">$result</b> <b class="method">getall</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a dictionary containing the search result at the time of the
invokation, mapping the matching names to the data associated with
them at <i class="term"><a href="../../../../index.html#bind">bind</a></i>-time.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">HISTORY</a></h2>
<dl class="doctools_definitions">
<dt>0.3.1</dt>
<dd><p>Fixed SF Bug 1954771.</p></dd>
<dt>0.3</dt>
<dd><p>Extended the client with the ability to perform asynchronous and
continuous searches.</p></dd>
<dt>0.2</dt>
<dd><p>Extended the client with the ability to generate events when it loses
its connection to the name service. Based on package <b class="package"><a href="../uev/uevent.html">uevent</a></b>.</p></dd>
<dt>0.1</dt>
<dd><p>Initial implementation of the client.</p></dd>
</dl>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="nns_common.html">nameserv::common(n)</a>, <a href="nns_server.html">nameserv::server(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#client">client</a>, <a href="../../../../index.html#name_service">name service</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nns/nns_common.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<div class='fossil-doc' data-title='nameserv::common - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nameserv::common(n) 0.1 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nameserv::common - Name service facility, shared definitions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8</b></li>
<li>package require <b class="pkgname">nameserv::common <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::nameserv::common::port</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read <i class="term"><a href="nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>This package is internal and of no interest to users. It provides the
commands of the name service facility which are shared by the client
and server implemented by the packages <b class="package"><a href="nns_server.html">nameserv::server</a></b> and
<b class="package"><a href="nns_client.html">nameserv</a></b> (the client).</p>
<p>This service is built in top of and for the package <b class="package"><a href="../comm/comm.html">comm</a></b>.
It has nothing to do with the Internet's Domain Name System. If the
reader is looking for a package dealing with that please see Tcllib's
packages <b class="package"><a href="../dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports a single command, as specified below:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::nameserv::common::port</b></a></dt>
<dd><p>The result returned by the command is the id of the default TCP/IP
port a nameservice server will listen on, and a name service client
will try to connect to.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>nameserv::client(n), <a href="nns_server.html">nameserv::server(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#client">client</a>, <a href="../../../../index.html#name_service">name service</a>, <a href="../../../../index.html#server">server</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nns/nns_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<div class='fossil-doc' data-title='nns_intro - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nns_intro(n) 1.0 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nns_intro - Name service facility, introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Applications</a></li>
<li class="doctools_section"><a href="#section3">Packages</a></li>
<li class="doctools_section"><a href="#section4">Internals</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../apps/nns.html">nns</a></i> (short for <em>nano nameservice</em>) is a facility built
for the package <b class="package"><a href="../comm/comm.html">comm</a></b>, adding a simple name service to it.
It is also built on top of <b class="package"><a href="../comm/comm.html">comm</a></b>, using it for the exchange
of messages between the client and server parts.</p>
<p>This name service facility has nothing to do with the Internet's
<i class="term">Domain Name System</i>, otherwise known as <i class="term"><a href="../../../../index.html#dns">DNS</a></i>. If the
reader is looking for a package dealing with that please see either of
the packages <b class="package"><a href="../dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>, both found in Tcllib
too.</p>
<p>Tcllib provides 2 applications and 4 packages which are working
together and provide access to the facility at different levels.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Applications</a></h2>
<p>The application <b class="syscmd"><a href="../../apps/nnsd.html">nnsd</a></b> provides a simple name server which can
be run by anybody anywhere on their system, as they see fit.
It is also an example on the use of the server-side package
<b class="package"><a href="nns_server.html">nameserv::server</a></b>.</p>
<p>Complementing this server is the <b class="syscmd"><a href="../../apps/nns.html">nns</a></b> client application.
A possible, but no very sensible use would be to enter name/port
bindings into a server from a shell script. Not sensible, as shell
scripts normally do not provide a <b class="package"><a href="../comm/comm.html">comm</a></b>-based service.</p>
<p>The only case for this to make some sense would be in a shell script
wrapped around a Tcl script FOO which is using comm, to register the
listening port used by FOO.
However even there it would much more sensible to extend FOO to use
the nameservice directly. And in regard on how to that <b class="syscmd"><a href="../../apps/nns.html">nns</a></b>
can be used as both example and template.
Beyond that it may also be useful to perform nameservice queries from
shell scripts.</p>
<p>The third application, <b class="syscmd"><a href="../../apps/nnslog.html">nnslog</a></b> is a stripped down form of the
<b class="syscmd"><a href="../../apps/nns.html">nns</a></b> client application. It is reduced to perform a continuous
search for all changes and logs all received events to stdout.</p>
<p>Both clients use the <b class="package"><a href="nns_auto.html">nameserv::auto</a></b> package to automatically
hande the loss and restoration of the connection to the server.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Packages</a></h2>
<p>The two main packages implementing the service are <b class="package"><a href="nns_client.html">nameserv</a></b>
and <b class="package"><a href="nns_server.html">nameserv::server</a></b>, i.e. client and server. The latter has
not much of an API, just enough to start, stop, and configure it. See
the application <b class="syscmd"><a href="../../apps/nnsd.html">nnsd</a></b> on how to use it.</p>
<p>The basic client, in package <b class="package"><a href="nns_client.html">nameserv</a></b>, provides the main API
to manipulate and query the service. An example of its use is the
application <b class="syscmd"><a href="../../apps/nns.html">nns</a></b>.</p>
<p>The second client package, <b class="package"><a href="nns_auto.html">nameserv::auto</a></b> is API compatible
to the basic client, but provides the additional functionality that it
will automatically restore data like bound names when the connection
to the name service was lost and then reestablished. I.e. it
automatically detects the loss of the server and re-enters the data
when the server comes back.</p>
<p>The package <b class="package"><a href="nns_common.html">nameserv::common</a></b> is of no interest to users. It
is an internal package containing code and definitions common to the
packages <b class="package"><a href="nns_client.html">nameserv</a></b> and <b class="package"><a href="nns_server.html">nameserv::server</a></b>.</p>
<p>All packages use the <b class="package"><a href="../uev/uevent.html">uevent</a></b> package for the reporting of
special circumstances via events, and reserve the uevent-tag
<i class="term"><a href="nns_client.html">nameserv</a></i> for their exclusive use. All their events will be
posted to that tag.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Internals</a></h2>
<p>The document <i class="term"><a href="nns_protocol.html">Name service facility, client/server protocol</a></i>
specifies the protocol used by the packages <b class="package"><a href="nns_client.html">nameserv</a></b> and
<b class="package"><a href="nns_server.html">nameserv::server</a></b> to talk to each other. It is of no interest
to users of either the packages or applications.</p>
<p>Developers wishing to modify and/or extend or to just understand the
internals of the nameservice facility however are strongly advised to
read it.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="nns_client.html">nameserv(n)</a>, <a href="nns_auto.html">nameserv::auto(n)</a>, <a href="nns_common.html">nameserv::common(n)</a>, <a href="nns_protocol.html">nameserv::protocol(n)</a>, <a href="nns_server.html">nameserv::server(n)</a>, <a href="../../apps/nnsd.html">nnsd(n)</a>, nss(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#client">client</a>, <a href="../../../../index.html#name_service">name service</a>, <a href="../../../../index.html#server">server</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nns/nns_protocol.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
<div class='fossil-doc' data-title='nameserv::protocol - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nameserv::protocol(n) 0.1 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nameserv::protocol - Name service facility, client/server protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Nano Name Service Protocol Version 1</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Basic Layer</a></li>
<li class="doctools_subsection"><a href="#subsection2">Message Layer</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Nano Name Service Protocol Extension: Continuous Search</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="method">Bind</b> <i class="arg">name</i> <i class="arg">data</i></a></li>
<li><a href="#2"><b class="method">Release</b></a></li>
<li><a href="#3"><b class="method">Search</b> <i class="arg">pattern</i></a></li>
<li><a href="#4"><b class="method">ProtocolVersion</b></a></li>
<li><a href="#5"><b class="method">ProtocolFeatures</b></a></li>
<li><a href="#6"><b class="method">Search/Continuous/Start</b> <i class="arg">tag</i> <i class="arg">pattern</i></a></li>
<li><a href="#7"><b class="method">Search/Continuous/Stop</b> <i class="arg">tag</i></a></li>
<li><a href="#8"><b class="method">Search/Continuous/Change</b> <i class="arg">tag</i> <b class="method">add</b>|<b class="method">remove</b> <i class="arg">response</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The packages <b class="package"><a href="nns_server.html">nameserv::server</a></b>, <b class="package"><a href="nns_client.html">nameserv</a></b>, and
<b class="package"><a href="nns_common.html">nameserv::common</a></b> provide a simple unprotected name service
facility for use in small trusted environments.</p>
<p>Please read <i class="term"><a href="nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>This document contains the specification of the network protocol which
is used by client and server to talk to each other, enabling
implementations of the same protocol in other languages.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Nano Name Service Protocol Version 1</a></h2>
<p>This protocol defines the basic set of messages to be supported by a
name service, also called the <i class="term">Core</i> feature.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Basic Layer</a></h3>
<p>The basic communication between client and server is done using the
remote-execution protocol specified by the Tcl package <b class="package"><a href="../comm/comm.html">comm</a></b>.
The relevant document specifying its on-the-wire protocol can be found
in <i class="term"><a href="../comm/comm_wire.html">comm_wire</a></i>.</p>
<p>All the scripts exchanged via this protocol are single commands in
list form and thus can be interpreted as plain messages instead of as
Tcl commands. The commands/messages specified in the next section are
the only commands understood by the server-side. Command and variable
substitutions are not allowed within the messages, i.e. arguments have
to be literal values.</p>
<p>The protocol is synchronous. I.e. for each message sent a response is
expected, and has to be generated. All messages are sent by the client.
The server does not sent messages, only responses to messages.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Message Layer</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="method">Bind</b> <i class="arg">name</i> <i class="arg">data</i></a></dt>
<dd><p>The client sends this message when it registers itself at the service
with a <i class="arg">name</i> and some associated <i class="arg">data</i>. The server has to
send an error response if the <i class="arg">name</i> is already in use. Otherwise
the response has to be an empty string.</p>
<p>The server has to accept multiple names for the same client.</p></dd>
<dt><a name="2"><b class="method">Release</b></a></dt>
<dd><p>The client sends this message to unregister all names it is known
under at the service. The response has to be an empty string, always.</p></dd>
<dt><a name="3"><b class="method">Search</b> <i class="arg">pattern</i></a></dt>
<dd><p>The client sends this message to search the service for names matching
the glob-<i class="arg">pattern</i>. The response has to be a dictionary containing
the matching names as keys, and mapping them to the data associated
with it at <b class="method">Bind</b>-time.</p></dd>
<dt><a name="4"><b class="method">ProtocolVersion</b></a></dt>
<dd><p>The client sends this message to query the service for the highest
version of the name service protocol it supports. The response has to
be a positive integer number.</p>
<p>Servers supporting only <i class="term">Nano Name Service Protocol Version 1</i>
have to return <b class="const">1</b>.</p></dd>
<dt><a name="5"><b class="method">ProtocolFeatures</b></a></dt>
<dd><p>The client sends this message to query the service for the features of
the name service protocol it supports. The response has to be a
list containing feature names.</p>
<p>Servers supporting only <i class="term">Nano Name Service Protocol Version 1</i>
have to return <b class="const">{Core}</b>.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Nano Name Service Protocol Extension: Continuous Search</a></h2>
<p>This protocol defines an extended set of messages to be supported by a
name service, also called the <i class="term">Search/Continuous</i> feature. This
feature defines additional messages between client and server, and is
otherwise identical to version 1 of the protocol. See the last section
for the details of our foundation.</p>
<p>A service supporting this feature has to put the feature name
<b class="const">Search/Continuous</b> into the list of features returned by the
message <i class="term">ProtocolFeatures</i>.</p>
<p>For this extension the protocol is asynchronous. No direct response is
expected for any of the messages in the extension. Furthermore the
server will start sending messages on its own, instead of only
responses to messages, and the client has to be able to handle these
notifications.</p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="method">Search/Continuous/Start</b> <i class="arg">tag</i> <i class="arg">pattern</i></a></dt>
<dd><p>The client sends this message to start searching the service for names
matching the glob-<i class="arg">pattern</i>.
In contrast to the regular <i class="term">Search</i> request this one asks the
server to continuously monitor the database for the addition and
removal of matching entries and to notify the client of all such
changes. The particular search is identified by the <i class="arg">tag</i>.</p>
<p>No direct response is expected, rather the clients expect to be
notified of changes via explicit <i class="term">Search/Continuous/Result</i>
messages generated by the service.</p>
<p>It is further expected that the <i class="arg">tag</i> information is passed
unchanged to the <i class="term">Search/Continuous/Result</i> messages. This
tagging of the results enables clients to start multiple searches and
distinguish between the different results.</p></dd>
<dt><a name="7"><b class="method">Search/Continuous/Stop</b> <i class="arg">tag</i></a></dt>
<dd><p>The client sends this message to stop the continuous search identified
by the <i class="arg">tag</i>.</p></dd>
<dt><a name="8"><b class="method">Search/Continuous/Change</b> <i class="arg">tag</i> <b class="method">add</b>|<b class="method">remove</b> <i class="arg">response</i></a></dt>
<dd><p>This message is sent by the service to clients with active continuous
searches to transfer found changes. The first such message for a new
continuous search has to contains the current set of matching entries.</p>
<p>To ensure this a service has to generate an <b class="method">add</b>-message with
an empty <i class="arg">response</i> if there were no matching entries at the time.</p>
<p>The <i class="arg">response</i> has to be a dictionary containing the matching
names as keys, and mapping them to the data associated with it at
<b class="method">Bind</b>-time.
The argument coming before the response tells the client whether the
names in the response were added or removed from the service.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../comm/comm_wire.html">comm_wire(n)</a>, <a href="nns_client.html">nameserv(n)</a>, <a href="nns_server.html">nameserv::server(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comm">comm</a>, <a href="../../../../index.html#name_service">name service</a>, <a href="../../../../index.html#protocol">protocol</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nns/nns_server.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
<div class='fossil-doc' data-title='nameserv::server - Name service facility'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nameserv::server(n) 0.3.2 tcllib "Name service facility"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nameserv::server - Name service facility, Server</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">HISTORY</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">nameserv::server <span class="opt">?0.3.2?</span></b></li>
<li>package require <b class="pkgname">comm</b></li>
<li>package require <b class="pkgname">interp</b></li>
<li>package require <b class="pkgname">logger</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::nameserv::server::start</b></a></li>
<li><a href="#2"><b class="cmd">::nameserv::server::stop</b></a></li>
<li><a href="#3"><b class="cmd">::nameserv::server::active?</b></a></li>
<li><a href="#4"><b class="cmd">::nameserv::server::cget</b> <b class="option">-option</b></a></li>
<li><a href="#5"><b class="cmd">::nameserv::server::configure</b></a></li>
<li><a href="#6"><b class="cmd">::nameserv::server::configure</b> <b class="option">-option</b></a></li>
<li><a href="#7"><b class="cmd">::nameserv::server::configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Please read <i class="term"><a href="nns_intro.html">Name service facility, introduction</a></i> first.</p>
<p>This package provides an implementation of the serviver side of the
name service facility queried by the client provided by the package
<b class="package"><a href="nns_client.html">nameserv</a></b>. All information required by the server will be
held in memory. There is no persistent state.</p>
<p>This service is built in top of and for the package <b class="package"><a href="../comm/comm.html">comm</a></b>.
It has nothing to do with the Internet's Domain Name System. If the
reader is looking for a package dealing with that please see Tcllib's
packages <b class="package"><a href="../dns/tcllib_dns.html">dns</a></b> and <b class="package">resolv</b>.</p>
<p>This server supports the <i class="term">Core</i> protocol feature, and since
version 0.3 the <i class="term">Search/Continuous</i> feature as well.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports five commands, as specified below:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::nameserv::server::start</b></a></dt>
<dd><p>This command starts the server and causes it to listen on the
configured port. From now on clients are able to connect and make
requests. The result of the command is the empty string.</p>
<p>Note that any incoming requests will only be handled if the
application the server is part of does enter an event loop after this
command has been run.</p></dd>
<dt><a name="2"><b class="cmd">::nameserv::server::stop</b></a></dt>
<dd><p>Invoking this command stops the server and releases all information it
had. Existing connections are shut down, and no new connections will
be accepted any longer. The result of the command is the empty string.</p></dd>
<dt><a name="3"><b class="cmd">::nameserv::server::active?</b></a></dt>
<dd><p>This command returns a boolean value indicating the state of the
server. The result will be <b class="const">true</b> if the server is active,
i.e. has been started, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="4"><b class="cmd">::nameserv::server::cget</b> <b class="option">-option</b></a></dt>
<dd><p>This command returns the currently configured value for the specified
<b class="option">-option</b>. The list of supported options and their meaning can
be found in section <span class="sectref"><a href="#section3">OPTIONS</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::nameserv::server::configure</b></a></dt>
<dd><p>In this form the command returns a dictionary of all supported
options, and their current values. The list of supported options and
their meaning can be found in section <span class="sectref"><a href="#section3">OPTIONS</a></span>.</p></dd>
<dt><a name="6"><b class="cmd">::nameserv::server::configure</b> <b class="option">-option</b></a></dt>
<dd><p>In this form the command is an alias for
"<b class="cmd">::nameserv::server::cget</b> <b class="option">-option</b>".
The list of supported options and their meaning can be found in
section <span class="sectref"><a href="#section3">OPTIONS</a></span>.</p></dd>
<dt><a name="7"><b class="cmd">::nameserv::server::configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>In this form the command is used to configure one or more of the
supported options. At least one option has to be specified, and each
option is followed by its new value.
The list of supported options and their meaning can be found in
section <span class="sectref"><a href="#section3">OPTIONS</a></span>.</p>
<p>This form can be used only if the server is not active, i.e. has not
been started yet, or has been stopped. While the server is active it
cannot be reconfigured.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<p>The options supported by the server are for the specification of the
TCP port to listen on, and whether to accept non-local connections or
not.
They are:</p>
<dl class="doctools_options">
<dt><b class="option">-localonly</b> <i class="arg">bool</i></dt>
<dd><p>This option specifies whether to accept only local connections
(-localonly 1) or remote connections as well (-localonly 0). The
default is to accept only local connections.</p></dd>
<dt><b class="option">-port</b> <i class="arg">number</i></dt>
<dd><p>This option specifies the port the name service will listen on after
it has been started. It has to be a positive integer number (> 0) not
greater than 65536 (unsigned short). The initial default is the number
returned by the command <b class="cmd">::nameserv::server::common::port</b>, as
provided by the package <b class="package">::nameserv::server::common</b>.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">HISTORY</a></h2>
<dl class="doctools_definitions">
<dt>0.3</dt>
<dd><p>Extended the server with the ability to perform asynchronous and
continuous searches.</p></dd>
<dt>0.2</dt>
<dd><p>Changed name of -local switch to -localonly.</p></dd>
<dt>0.1</dt>
<dd><p>Initial implementation of the server.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>nameserv::client(n), <a href="nns_common.html">nameserv::common(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#name_service">name service</a>, <a href="../../../../index.html#server">server</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/nntp/nntp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
|
<div class='fossil-doc' data-title='nntp - Tcl NNTP Client Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">nntp(n) 1.5.1 tcllib "Tcl NNTP Client Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>nntp - Tcl client for the NNTP protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLE</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">nntp <span class="opt">?0.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::nntp::nntp</b> <span class="opt">?<i class="arg">host</i>?</span> <span class="opt">?<i class="arg">port</i>?</span> <span class="opt">?<i class="arg">nntpName</i>?</span></a></li>
<li><a href="#2"><i class="arg">nntpName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">nntpName</i> <b class="method">article</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></li>
<li><a href="#4"><i class="arg">nntpName</i> <b class="method">authinfo</b> <span class="opt">?<i class="arg">user</i>?</span> <span class="opt">?<i class="arg">pass</i>?</span></a></li>
<li><a href="#5"><i class="arg">nntpName</i> <b class="method">body</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></li>
<li><a href="#6"><i class="arg">nntpName</i> <b class="method">configure</b></a></li>
<li><a href="#7"><i class="arg">nntpName</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#8"><i class="arg">nntpName</i> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i> ...</a></li>
<li><a href="#9"><i class="arg">nntpName</i> <b class="method">cget</b> <i class="arg">option</i></a></li>
<li><a href="#10"><i class="arg">nntpName</i> <b class="method">date</b></a></li>
<li><a href="#11"><i class="arg">nntpName</i> <b class="method">group</b> <span class="opt">?<i class="arg">group</i>?</span></a></li>
<li><a href="#12"><i class="arg">nntpName</i> <b class="method">head</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></li>
<li><a href="#13"><i class="arg">nntpName</i> <b class="method">help</b></a></li>
<li><a href="#14"><i class="arg">nntpName</i> <b class="method">last</b></a></li>
<li><a href="#15"><i class="arg">nntpName</i> <b class="method">list</b></a></li>
<li><a href="#16"><i class="arg">nntpName</i> <b class="method">listgroup</b> <span class="opt">?<i class="arg">group</i>?</span></a></li>
<li><a href="#17"><i class="arg">nntpName</i> <b class="method">mode_reader</b></a></li>
<li><a href="#18"><i class="arg">nntpName</i> <b class="method">newgroups</b> <i class="arg">since</i></a></li>
<li><a href="#19"><i class="arg">nntpName</i> <b class="method">newnews</b></a></li>
<li><a href="#20"><i class="arg">nntpName</i> <b class="method">newnews</b> <i class="arg">since</i></a></li>
<li><a href="#21"><i class="arg">nntpName</i> <b class="method">newnews</b> <i class="arg">group</i> <span class="opt">?<i class="arg">since</i>?</span></a></li>
<li><a href="#22"><i class="arg">nntpName</i> <b class="method">next</b></a></li>
<li><a href="#23"><i class="arg">nntpName</i> <b class="method">post</b> <i class="arg">article</i></a></li>
<li><a href="#24"><i class="arg">nntpName</i> <b class="method">slave</b></a></li>
<li><a href="#25"><i class="arg">nntpName</i> <b class="method">stat</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></li>
<li><a href="#26"><i class="arg">nntpName</i> <b class="method">quit</b></a></li>
<li><a href="#27"><i class="arg">nntpName</i> <b class="method">xgtitle</b> <span class="opt">?<i class="arg">group_pattern</i>?</span></a></li>
<li><a href="#28"><i class="arg">nntpName</i> <b class="method">xhdr</b> <i class="arg">field</i> <span class="opt">?<i class="arg">range</i>?</span></a></li>
<li><a href="#29"><i class="arg">nntpName</i> <b class="method">xover</b> <span class="opt">?<i class="arg">range</i>?</span></a></li>
<li><a href="#30"><i class="arg">nntpName</i> <b class="method">xpat</b> <i class="arg">field</i> <i class="arg">range</i> <span class="opt">?<i class="arg">pattern_list</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">nntp</b> provides a simple Tcl-only client library
for the NNTP protocol. It works by opening the standard NNTP socket
on the server, and then providing a Tcl API to access the NNTP
protocol commands. All server errors are returned as Tcl errors
(thrown) which must be caught with the Tcl <b class="cmd">catch</b> command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::nntp::nntp</b> <span class="opt">?<i class="arg">host</i>?</span> <span class="opt">?<i class="arg">port</i>?</span> <span class="opt">?<i class="arg">nntpName</i>?</span></a></dt>
<dd><p>The command opens a socket connection to the specified NNTP server and
creates a new nntp object with an associated global Tcl command whose
name is <i class="arg">nntpName</i>. This command may be used to access the various
NNTP protocol commands for the new connection. The default <i class="arg">port</i>
number is "119" and the default <i class="arg">host</i> is "news". These defaults
can be overridden with the environment variables <b class="variable">NNTPPORT</b> and
<b class="variable">NNTPHOST</b> respectively.</p>
<p>Some of the commands supported by this package are not part of the
nntp rfc 977 (<a href="http://www.rfc-editor.org/rfc/rfc977.txt">http://www.rfc-editor.org/rfc/rfc977.txt</a>) and will
not be available (or implemented) on all nntp servers.</p>
<p>The access command <i class="arg">nntpName</i> has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">nntpName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl></dd>
<dt><a name="3"><i class="arg">nntpName</i> <b class="method">article</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></dt>
<dd><p>Query the server for article <i class="arg">msgid</i> from the current group. The article
is returned as a valid tcl list which contains the headers, followed by
a blank line, and then followed by the body of the article. Each element
in the list is one line of the article.</p></dd>
<dt><a name="4"><i class="arg">nntpName</i> <b class="method">authinfo</b> <span class="opt">?<i class="arg">user</i>?</span> <span class="opt">?<i class="arg">pass</i>?</span></a></dt>
<dd><p>Send authentication information (username and password) to the server.</p></dd>
<dt><a name="5"><i class="arg">nntpName</i> <b class="method">body</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></dt>
<dd><p>Query the server for the body of the article <i class="arg">msgid</i> from the current
group. The body of the article is returned as a valid tcl list. Each element
in the list is one line of the body of the article.</p></dd>
<dt><a name="6"><i class="arg">nntpName</i> <b class="method">configure</b></a></dt>
<dd></dd>
<dt><a name="7"><i class="arg">nntpName</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd></dd>
<dt><a name="8"><i class="arg">nntpName</i> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i> ...</a></dt>
<dd></dd>
<dt><a name="9"><i class="arg">nntpName</i> <b class="method">cget</b> <i class="arg">option</i></a></dt>
<dd><p>Query and configure options of the nntp connection object. Currently
only one option is supported, <b class="option">-binary</b>. When set articles are
retrieved as binary data instead of text. The only methods affected by
this are <b class="method">article</b> and <b class="method">body</b>.</p>
<p>One application of this option would be the download of articles
containing yEnc encoded images. Although encoded the data is still
mostly binary and retrieving it as text will corrupt the information.</p>
<p>See package <b class="package"><a href="../base64/yencode.html">yencode</a></b> for both encoder and decoder of such data.</p></dd>
<dt><a name="10"><i class="arg">nntpName</i> <b class="method">date</b></a></dt>
<dd><p>Query the server for the servers current date. The date is returned in the
format <em>YYYYMMDDHHMMSS</em>.</p></dd>
<dt><a name="11"><i class="arg">nntpName</i> <b class="method">group</b> <span class="opt">?<i class="arg">group</i>?</span></a></dt>
<dd><p>Optionally set the current group, and retrieve information about the
currently selected group. Returns the estimated number of articles in
the group followed by the number of the first article in the group, followed
by the last article in the group, followed by the name of the group.</p></dd>
<dt><a name="12"><i class="arg">nntpName</i> <b class="method">head</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></dt>
<dd><p>Query the server for the headers of the article <i class="arg">msgid</i> from the current
group. The headers of the article are returned as a valid tcl list. Each element
in the list is one line of the headers of the article.</p></dd>
<dt><a name="13"><i class="arg">nntpName</i> <b class="method">help</b></a></dt>
<dd><p>Retrieves a list of the commands that are supported by the news server that
is currently attached to.</p></dd>
<dt><a name="14"><i class="arg">nntpName</i> <b class="method">last</b></a></dt>
<dd><p>Sets the current article pointer to point to the previous message (if there is
one) and returns the msgid of that message.</p></dd>
<dt><a name="15"><i class="arg">nntpName</i> <b class="method">list</b></a></dt>
<dd><p>Returns a tcl list of valid newsgroups and associated information. Each
newsgroup is returned as an element in the tcl list with the following format:</p>
<pre class="doctools_example">
group last first p
</pre>
<p>where <group> is the name of the newsgroup, <last> is the number of
the last known article currently in that newsgroup, <first> is the
number of the first article currently in the newsgroup, and <p> is
either 'y' or 'n' indicating whether posting to this newsgroup is
allowed ('y') or prohibited ('n').</p>
<p>The <first> and <last> fields will always be numeric. They may have
leading zeros. If the <last> field evaluates to less than the
<first> field, there are no articles currently on file in the
newsgroup.</p></dd>
<dt><a name="16"><i class="arg">nntpName</i> <b class="method">listgroup</b> <span class="opt">?<i class="arg">group</i>?</span></a></dt>
<dd><p>Query the server for a list of all the messages (message numbers) in the
group specified by the argument <i class="arg">group</i> or by the current group if
the <i class="arg">group</i> argument was not passed.</p></dd>
<dt><a name="17"><i class="arg">nntpName</i> <b class="method">mode_reader</b></a></dt>
<dd><p>Query the server for its nntp 'MODE READER' response string.</p></dd>
<dt><a name="18"><i class="arg">nntpName</i> <b class="method">newgroups</b> <i class="arg">since</i></a></dt>
<dd><p>Query the server for a list of all the new newsgroups created since the time
specified by the argument <i class="arg">since</i>. The argument <i class="arg">since</i> can be any
time string that is understood by <b class="cmd">clock scan</b>. The tcl list of newsgroups
is returned in a similar form to the list of groups returned by the
<b class="cmd">nntpName list</b> command. Each element of the list has the form:</p>
<pre class="doctools_example">
group last first p
</pre>
<p>where <group> is the name of the newsgroup, <last> is the number of
the last known article currently in that newsgroup, <first> is the
number of the first article currently in the newsgroup, and <p> is
either 'y' or 'n' indicating whether posting to this newsgroup is
allowed ('y') or prohibited ('n').</p></dd>
<dt><a name="19"><i class="arg">nntpName</i> <b class="method">newnews</b></a></dt>
<dd><p>Query the server for a list of new articles posted to the current group in the
last day.</p></dd>
<dt><a name="20"><i class="arg">nntpName</i> <b class="method">newnews</b> <i class="arg">since</i></a></dt>
<dd><p>Query the server for a list of new articles posted to the current group since
the time specified by the argument <i class="arg">since</i>. The argument <i class="arg">since</i> can
be any time string that is understood by <b class="cmd">clock scan</b>.</p></dd>
<dt><a name="21"><i class="arg">nntpName</i> <b class="method">newnews</b> <i class="arg">group</i> <span class="opt">?<i class="arg">since</i>?</span></a></dt>
<dd><p>Query the server for a list of new articles posted to the group specified by
the argument <i class="arg">group</i> since the time specified by the argument <i class="arg">since</i>
(or in the past day if no <i class="arg">since</i> argument is passed. The argument
<i class="arg">since</i> can be any time string that is understood by <b class="cmd">clock scan</b>.</p></dd>
<dt><a name="22"><i class="arg">nntpName</i> <b class="method">next</b></a></dt>
<dd><p>Sets the current article pointer to point to the next message (if there is
one) and returns the msgid of that message.</p></dd>
<dt><a name="23"><i class="arg">nntpName</i> <b class="method">post</b> <i class="arg">article</i></a></dt>
<dd><p>Posts an article of the form specified in
RFC 1036 (<a href="http://www.rfc-editor.org/rfc/rfc1036.txt">http://www.rfc-editor.org/rfc/rfc1036.txt</a>, successor
to RFC 850) to the current news group.</p></dd>
<dt><a name="24"><i class="arg">nntpName</i> <b class="method">slave</b></a></dt>
<dd><p>Identifies a connection as being made from a slave nntp server. This might
be used to indicate that the connection is serving multiple people and should
be given priority. Actual use is entirely implementation dependent and may
vary from server to server.</p></dd>
<dt><a name="25"><i class="arg">nntpName</i> <b class="method">stat</b> <span class="opt">?<i class="arg">msgid</i>?</span></a></dt>
<dd><p>The stat command is similar to the article command except that no
text is returned. When selecting by message number within a group,
the stat command serves to set the current article pointer without
sending text. The returned acknowledgment response will contain the
message-id, which may be of some value. Using the stat command to
select by message-id is valid but of questionable value, since a
selection by message-id does NOT alter the "current article pointer"</p></dd>
<dt><a name="26"><i class="arg">nntpName</i> <b class="method">quit</b></a></dt>
<dd><p>Gracefully close the connection after sending a NNTP QUIT command down
the socket.</p></dd>
<dt><a name="27"><i class="arg">nntpName</i> <b class="method">xgtitle</b> <span class="opt">?<i class="arg">group_pattern</i>?</span></a></dt>
<dd><p>Returns a tcl list where each element is of the form:</p>
<pre class="doctools_example">
newsgroup description
</pre>
<p>If a <i class="arg">group_pattern</i> is specified then only newsgroups that match
the pattern will have their name and description returned.</p></dd>
<dt><a name="28"><i class="arg">nntpName</i> <b class="method">xhdr</b> <i class="arg">field</i> <span class="opt">?<i class="arg">range</i>?</span></a></dt>
<dd><p>Returns the specified header field value for the current message or for a
list of messages from the current group. <i class="arg">field</i> is the title of a
field in the header such as from, subject, date, etc. If <i class="arg">range</i> is
not specified or is "" then the current message is queried. The command
returns a list of elements where each element has the form of:</p>
<pre class="doctools_example">
msgid value
</pre>
<p>Where msgid is the number of the message and value is the value set for the
queried field. The <i class="arg">range</i> argument can be in any of the following forms:</p>
<dl class="doctools_definitions">
<dt><b class="const">""</b></dt>
<dd><p>The current message is queried.</p></dd>
<dt><i class="arg">msgid1</i>-<i class="arg">msgid2</i></dt>
<dd><p>All messages between <i class="arg">msgid1</i> and <i class="arg">msgid2</i>
(including <i class="arg">msgid1</i> and <i class="arg">msgid2</i>) are queried.</p></dd>
<dt><i class="arg">msgid1</i> <i class="arg">msgid2</i></dt>
<dd><p>All messages between <i class="arg">msgid1</i> and <i class="arg">msgid2</i>
(including <i class="arg">msgid1</i> and <i class="arg">msgid2</i>) are queried.</p></dd>
</dl></dd>
<dt><a name="29"><i class="arg">nntpName</i> <b class="method">xover</b> <span class="opt">?<i class="arg">range</i>?</span></a></dt>
<dd><p>Returns header information for the current message or for a range of messages
from the current group. The information is returned in a tcl list
where each element is of the form:</p>
<pre class="doctools_example">
msgid subject from date idstring bodysize headersize xref
</pre>
<p>If <i class="arg">range</i> is not specified or is "" then the current message is queried.
The <i class="arg">range</i> argument can be in any of the following forms:</p>
<dl class="doctools_definitions">
<dt><b class="const">""</b></dt>
<dd><p>The current message is queried.</p></dd>
<dt><i class="arg">msgid1</i>-<i class="arg">msgid2</i></dt>
<dd><p>All messages between <i class="arg">msgid1</i> and <i class="arg">msgid2</i>
(including <i class="arg">msgid1</i> and <i class="arg">msgid2</i>) are queried.</p></dd>
<dt><i class="arg">msgid1</i> <i class="arg">msgid2</i></dt>
<dd><p>All messages between <i class="arg">msgid1</i> and <i class="arg">msgid2</i>
(including <i class="arg">msgid1</i> and <i class="arg">msgid2</i>) are queried.</p></dd>
</dl></dd>
<dt><a name="30"><i class="arg">nntpName</i> <b class="method">xpat</b> <i class="arg">field</i> <i class="arg">range</i> <span class="opt">?<i class="arg">pattern_list</i>?</span></a></dt>
<dd><p>Returns the specified header field value for a specified message or for a
list of messages from the current group where the messages match the
pattern(s) given in the pattern_list. <i class="arg">field</i> is the title of a
field in the header such as from, subject, date, etc. The information is
returned in a tcl list where each element is of the form:</p>
<pre class="doctools_example">
msgid value
</pre>
<p>Where msgid is the number of the message and value is the value set for the
queried field. The <i class="arg">range</i> argument can be in any of the following forms:</p>
<dl class="doctools_definitions">
<dt><i class="arg">msgid</i></dt>
<dd><p>The message specified by <i class="arg">msgid</i> is queried.</p></dd>
<dt><i class="arg">msgid1</i>-<i class="arg">msgid2</i></dt>
<dd><p>All messages between <i class="arg">msgid1</i> and <i class="arg">msgid2</i>
(including <i class="arg">msgid1</i> and <i class="arg">msgid2</i>) are queried.</p></dd>
<dt><i class="arg">msgid1</i> <i class="arg">msgid2</i></dt>
<dd><p>All messages between <i class="arg">msgid1</i> and <i class="arg">msgid2</i>
(including <i class="arg">msgid1</i> and <i class="arg">msgid2</i>) are queried.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLE</a></h2>
<p>A bigger example for posting a single article.</p>
<pre class="doctools_example">
package require nntp
set n [nntp::nntp NNTP_SERVER]
$n post "From: [email protected] (USER_FULL)
Path: COMPUTERNAME!USERNAME
Newsgroups: alt.test
Subject: Tcl test post -ignore
Message-ID: <[pid][clock seconds]
@COMPUTERNAME>
Date: [clock format [clock seconds] -format "%a, %d %
b %y %H:%M:%S GMT" -gmt true]
Test message body"
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nntp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#news">news</a>, <a href="../../../../index.html#nntp">nntp</a>, <a href="../../../../index.html#nntpclient">nntpclient</a>, <a href="../../../../index.html#rfc_1036">rfc 1036</a>, <a href="../../../../index.html#rfc_977">rfc 977</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ntp/ntp_time.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
<div class='fossil-doc' data-title='ntp_time - Network Time Facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ntp_time(n) 1.2.1 tcllib "Network Time Facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ntp_time - Tcl Time Service Client</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.0</b></li>
<li>package require <b class="pkgname">time <span class="opt">?1.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::time::gettime</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">timeserver</i> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::time::getsntp</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">timeserver</i> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::time::configure</b> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::time::cget</b> <i class="arg">name</i></a></li>
<li><a href="#5"><b class="cmd">::time::unixtime</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::time::status</b> <i class="arg">token</i></a></li>
<li><a href="#7"><b class="cmd">::time::error</b> <i class="arg">token</i></a></li>
<li><a href="#8"><b class="cmd">::time::reset</b> <i class="arg">token</i> <i class="arg"><span class="opt">?reason?</span></i></a></li>
<li><a href="#9"><b class="cmd">::time::wait</b> <i class="arg">token</i></a></li>
<li><a href="#10"><b class="cmd">::time::cleanup</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a client for the RFC 868 TIME protocol
(<a href="http://www.rfc-editor.org/rfc/rfc868.txt">http://www.rfc-editor.org/rfc/rfc868.txt</a>) and also a minimal
client for the RFC 2030 Simple Network Time Protocol
(<a href="http://www.rfc-editor.org/rfc/rfc2030.txt">http://www.rfc-editor.org/rfc/rfc2030.txt</a>).
RFC 868 returns the time in seconds since 1 January 1900
to either tcp or udp clients. RFC 2030 also gives this time but also
provides a fractional part which is not used in this client.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::time::gettime</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">timeserver</i> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Get the time from <i class="arg">timeserver</i>. You may specify any of the options
listed for the <b class="cmd">configure</b> command here. This command returns a
token which must then be used with the remaining commands in this
package. Once you have finished, you should use <b class="cmd"><a href="../../../../index.html#cleanup">cleanup</a></b> to
release all resources. The default port is <b class="const">37</b>.</p></dd>
<dt><a name="2"><b class="cmd">::time::getsntp</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">timeserver</i> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Get the time from an SNTP server. This accepts exactly the same
arguments as <b class="cmd">::time::gettime</b> except that the default port is
<b class="const">123</b>. The result is a token as per <b class="cmd">::time::gettime</b> and
should be handled in the same way.</p>
<p>Note that it is unlikely that any SNTP server will reply using tcp so
you will require the <b class="package">tcludp</b> or the <b class="package">ceptcl</b>
package. If a suitable package can be loaded then the udp protocol
will be used by default.</p></dd>
<dt><a name="3"><b class="cmd">::time::configure</b> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>Called with no arguments this command returns all the current
configuration options and values. Otherwise it should be called with
pairs of option name and value.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">-protocol</b> <i class="arg">number</i></dt>
<dd><p>Set the default network protocol. This defaults to udp if the tcludp
package is available. Otherwise it will use tcp.</p></dd>
<dt><b class="cmd">-port</b> <i class="arg">number</i></dt>
<dd><p>Set the default port to use. RFC 868 uses port <b class="const">37</b>, RFC 2030 uses
port <b class="const">123</b>.</p></dd>
<dt><b class="cmd">-timeout</b> <i class="arg">number</i></dt>
<dd><p>Set the default timeout value in milliseconds. The default is 10 seconds.</p></dd>
<dt><b class="cmd">-command</b> <i class="arg">number</i></dt>
<dd><p>Set a command procedure to be run when a reply is received. The
procedure is called with the time token appended to the argument list.</p></dd>
<dt><b class="cmd">-loglevel</b> <i class="arg">number</i></dt>
<dd><p>Set the logging level. The default is 'warning'.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::time::cget</b> <i class="arg">name</i></a></dt>
<dd><p>Get the current value for the named configuration option.</p></dd>
<dt><a name="5"><b class="cmd">::time::unixtime</b> <i class="arg">token</i></a></dt>
<dd><p>Format the returned time for the unix epoch. RFC 868 time defines
time 0 as 1 Jan 1900, while unix time defines time 0 as 1 Jan
1970. This command converts the reply to unix time.</p></dd>
<dt><a name="6"><b class="cmd">::time::status</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the status flag. For a successfully completed query this will be
<em>ok</em>. May be <em>error</em> or <em>timeout</em> or <em>eof</em>.
See also <b class="cmd">::time::error</b></p></dd>
<dt><a name="7"><b class="cmd">::time::error</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the error message provided for requests whose status is <em>error</em>.
If there is no error message then an empty string is returned.</p></dd>
<dt><a name="8"><b class="cmd">::time::reset</b> <i class="arg">token</i> <i class="arg"><span class="opt">?reason?</span></i></a></dt>
<dd><p>Reset or cancel the query optionally specfying the reason to record
for the <b class="cmd"><a href="../../../../index.html#error">error</a></b> command.</p></dd>
<dt><a name="9"><b class="cmd">::time::wait</b> <i class="arg">token</i></a></dt>
<dd><p>Wait for a query to complete and return the status upon completion.</p></dd>
<dt><a name="10"><b class="cmd">::time::cleanup</b> <i class="arg">token</i></a></dt>
<dd><p>Remove all state variables associated with the request.</p></dd>
</dl>
<pre class="doctools_example">
% set tok [::time::gettime ntp2a.mcc.ac.uk]
% set t [::time::unixtime $tok]
% ::time::cleanup $tok
</pre>
<pre class="doctools_example">
% set tok [::time::getsntp pool.ntp.org]
% set t [::time::unixtime $tok]
% ::time::cleanup $tok
</pre>
<pre class="doctools_example">
proc on_time {token} {
if {[time::status $token] eq "ok"} {
puts [clock format [time::unixtime $token]]
} else {
puts [time::error $token]
}
time::cleanup $token
}
time::getsntp -command on_time pool.ntp.org
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ntp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>ntp</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ntp">NTP</a>, <a href="../../../../index.html#sntp">SNTP</a>, <a href="../../../../index.html#rfc_2030">rfc 2030</a>, <a href="../../../../index.html#rfc_868">rfc 868</a>, <a href="../../../../index.html#time">time</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/oauth/oauth.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
|
<div class='fossil-doc' data-title='oauth - oauth'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">oauth(n) 1.0.2 tcllib "oauth"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>oauth - oauth API base signature</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section3">Commands</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">oauth <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::oauth::config</b></a></li>
<li><a href="#2"><b class="cmd">::oauth::config</b> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">::oauth::header</b> <i class="arg">baseURL</i> <span class="opt">?<i class="arg">postQuery</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::oauth::query</b> <i class="arg">baseURL</i> <span class="opt">?<i class="arg">postQuery</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">oauth</b> package provides a simple Tcl-only library
for communication with <a href="http://oauth.net">oauth</a> APIs.
This current version of the package supports the Oauth 1.0 Protocol,
as specified in <a href="http://tools.ietf.org/rfc/rfc5849.txt">RFC 5849</a>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::oauth::config</b></a></dt>
<dd><p>When this command is invoked without arguments it returns a dictionary
containing the current values of all options.</p></dd>
<dt><a name="2"><b class="cmd">::oauth::config</b> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>When invoked with arguments, options followed by their values, it is used
to set and query various parameters of application and client, like proxy
host and user agent for the HTTP requests. The detailed list of options
is below:</p>
<dl class="doctools_options">
<dt><b class="option">-accesstoken</b> <i class="arg">string</i></dt>
<dd><p>This is the user's token.</p></dd>
<dt><b class="option">-accesstokensecret</b> <i class="arg">string</i></dt>
<dd><p>This is the user's secret token.</p></dd>
<dt><b class="option">-consumerkey</b> <i class="arg">string</i></dt>
<dd><p>This is the public token of your app.</p></dd>
<dt><b class="option">-consumersecret</b> <i class="arg">string</i></dt>
<dd><p>This is the private token of your app.</p></dd>
<dt><b class="option">-debug</b> <i class="arg">bool</i></dt>
<dd><p>The default value is <b class="const">off</b>. If you change this option to <b class="const">on</b>,
the basic signature just created will be printed to stdout, among other
debug output.</p></dd>
<dt><b class="option">-oauthversion</b> <i class="arg">version</i></dt>
<dd><p>This is the version of the OAuth protocol to use.
At the moment only <b class="const">1.0</b> is supported, the default.</p></dd>
<dt><b class="option">-proxyhost</b> <i class="arg">hostname</i></dt>
<dd><p>You can set up a proxy host for send contact the oauth's api server.</p></dd>
<dt><b class="option">-proxyport</b> <i class="arg">port-number</i></dt>
<dd><p>Port number of your proxy.</p></dd>
<dt><b class="option">-signmethod</b> <i class="arg">method</i></dt>
<dd><p>The signature method to use. OAuth 1.0 only supports <b class="const">HMAC-SHA1</b>, the default.</p></dd>
<dt><b class="option">-timeout</b> <i class="arg">milliseconds</i></dt>
<dd><p>Timeout in milliseconds for your query.
The default value is <b class="const">6000</b>, i.e. 6 seconds.</p></dd>
<dt><b class="option">-urlencoding</b> <em>encoding</em></dt>
<dd><p>The encoding used for creating the x-url-encoded URLs with
<b class="cmd">::http::formatQuery</b>. The default is <b class="const">utf-8</b>, as specified
by <a href="http://tools.ietf.org/rfc/rfc2718.txt">RFC 2718</a>.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::oauth::header</b> <i class="arg">baseURL</i> <span class="opt">?<i class="arg">postQuery</i>?</span></a></dt>
<dd><p>This command is the base signature creator. With proper settings for various tokens
and secrets (See <b class="cmd">::oauth::config</b>) the result is the base authentication string
to send to the server.</p>
<p>You do not need to call this procedure to create the query because
<b class="cmd">::oauth::query</b> (see below) will do for it for you.
Doing so is useful for debugging purposes, though.</p>
<dl class="doctools_arguments">
<dt>url <i class="arg">baseURL</i></dt>
<dd><p>This argument is the URI path to the OAuth API server.
If you plan send a GET query, you should provide a full path.</p>
<pre class="doctools_example">
HTTP GET
::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente}
</pre>
</dd>
<dt>url-encoded-string <i class="arg">postQuery</i></dt>
<dd><p>When you have to send a header in POST format, you have to put the query string into this argument.</p>
<pre class="doctools_example">
::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true}
</pre>
</dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::oauth::query</b> <i class="arg">baseURL</i> <span class="opt">?<i class="arg">postQuery</i>?</span></a></dt>
<dd><p>This procedure will use the settings made with <b class="cmd">::oauth::config</b> to create the
basic authentication and then send the command to the server API.
It takes the same arguments as <b class="cmd">::oauth::header</b>.</p>
<p>The returned result will be a list containing 2 elements. The first
element will be a dictionary containing the HTTP header data response.
This allows you, for example, to check the X-Rate-Limit from OAuth.
The second element will be the raw data returned from API server.
This string is usually a json object which can be further decoded with the
functions of package <b class="package"><a href="../json/json.html">json</a></b>, or any other json-parser for Tcl.</p>
<p>Here is an example of how it would work in Twitter. Do not forget to
replace the placeholder tokens and keys of the example with your own tokens
and keys when trying it out.</p>
<pre class="doctools_example">% package require oauth
% package require json
% oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret}
% set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente]
% set jsondata [lindex $response 1]
% set data [json::json2dict $jsondata]
$ set data [lindex $data 0]
% dict for {key val} $data {puts "$key => $val"}
id => 158812437
id_str => 158812437
name => Un Librepensador
screen_name => AbiertaMente
location => Explico mis tuits ahí →
description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mí me sobrarían 20 para contaros todo lo q
url => http://t.co/SGs3k9odBn
entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}}
protected => false
followers_count => 72705
friends_count => 53099
listed_count => 258
created_at => Wed Jun 23 18:29:58 +0000 2010
favourites_count => 297
utc_offset => 7200
time_zone => Madrid
geo_enabled => false
verified => false
statuses_count => 8996
lang => es
status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name ἙλÎνη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und
contributors_enabled => false
is_translator => true
is_translation_enabled => false
profile_background_color => 709397
profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
profile_background_tile => true
profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874
profile_link_color => FF3300
profile_sidebar_border_color => FFFFFF
profile_sidebar_fill_color => A0C5C7
profile_text_color => 333333
profile_use_background_image => true
default_profile => false
default_profile_image => false
following => true
follow_request_sent => false
notifications => false</pre>
</dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>oauth</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#rfc_2718">RFC 2718</a>, <a href="../../../../index.html#rfc_5849">RFC 5849</a>, <a href="../../../../index.html#oauth">oauth</a>, <a href="../../../../index.html#twitter">twitter</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2014 Javi P. <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/oometa/oometa.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
<div class='fossil-doc' data-title='oometa - Data registry for TclOO frameworks'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">oometa(n) 0.7.1 tcllib "Data registry for TclOO frameworks"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>oometa - oo::meta A data registry for classess</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Usage</a></li>
<li class="doctools_section"><a href="#section3">Concept</a></li>
<li class="doctools_section"><a href="#section4">COMMANDS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">oo::meta::info</b></a></li>
<li><a href="#2"><b class="cmd">oo::meta::info branchget</b> <span class="opt">?<i class="arg">key</i>?</span> <span class="opt">?...?</span></a></li>
<li><a href="#3"><b class="cmd">oo::meta::info branchset</b> <span class="opt">?<i class="arg">key...</i>?</span> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#4"><b class="cmd">oo::meta::info dump</b> <i class="arg">class</i></a></li>
<li><a href="#5"><b class="cmd">oo::meta::info</b> <i class="arg">class</i> <b class="cmd">is</b> <i class="arg">type</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#6"><b class="cmd">oo::meta::info</b> <i class="arg">class</i> <b class="cmd"><a href="../../../../index.html#merge">merge</a></b> <span class="opt">?<i class="arg">dict</i>?</span> <span class="opt">?<i class="arg">dict</i>?</span> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#7"><b class="cmd">oo::meta::info</b> <i class="arg">class</i> <b class="cmd">rebuild</b></a></li>
<li><a href="#8"><b class="cmd">oo::meta::metadata</b> <i class="arg">class</i></a></li>
<li><a href="#9"><b class="cmd">oo::define meta</b></a></li>
<li><a href="#10"><b class="cmd">oo::class method meta</b></a></li>
<li><a href="#11"><b class="cmd">oo::object method meta</b></a></li>
<li><a href="#12"><b class="cmd">oo::object method meta cget</b> <span class="opt">?<i class="arg">field</i>?</span> <span class="opt">?<i class="arg">...</i>?</span> <i class="arg">field</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">oo::meta</b> package provides a data registry service for TclOO classes.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Usage</a></h2>
<pre class="doctools_example">
oo::class create animal {
meta set biodata animal: 1
}
oo::class create mammal {
superclass animal
meta set biodata mammal: 1
}
oo::class create cat {
superclass mammal
meta set biodata diet: carnivore
}
cat create felix
puts [felix meta dump biodata]
> animal: 1 mammal: 1 diet: carnivore
felix meta set biodata likes: {birds mice}
puts [felix meta get biodata]
> animal: 1 mammal: 1 diet: carnivore likes: {bird mice}
# Modify a class
mammal meta set biodata metabolism: warm-blooded
puts [felix meta get biodata]
> animal: 1 mammal: 1 metabolism: warm-blooded diet: carnivore likes: {birds mice}
# Overwrite class info
felix meta set biodata mammal: yes
puts [felix meta get biodata]
> animal: 1 mammal: yes metabolism: warm-blooded diet: carnivore likes: {birds mice}
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Concept</a></h2>
<p>The concept behind <b class="cmd">oo::meta</b> is that each class contributes a snippet of <em>local</em> data.
When <b class="cmd">oo::meta::metadata</b> is called, the system walks through the linear ancestry produced by
<b class="cmd">oo::meta::ancestors</b>, and recursively combines all of that local data for all of a class'
ancestors into a single dict.
Instances of oo::object can also combine class data with a local dict stored in the <em>meta</em> variable.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">oo::meta::info</b></a></dt>
<dd><p><b class="cmd">oo::meta::info</b> is intended to work on the metadata of a class in a manner similar to if the aggregate
pieces where assembled into a single dict. The system mimics all of the standard dict commands, and addes
the following:</p></dd>
<dt><a name="2"><b class="cmd">oo::meta::info branchget</b> <span class="opt">?<i class="arg">key</i>?</span> <span class="opt">?...?</span></a></dt>
<dd><p>Returns a dict representation of the element at <em>args</em>, but with any trailing : removed from field names.</p>
<pre class="doctools_example">
::oo::meta::info $myclass set option color {default: green widget: colorselect}
puts [::oo::meta::info $myclass get option color]
> {default: green widget: color}
puts [::oo::meta::info $myclass branchget option color]
> {default green widget color}
</pre>
</dd>
<dt><a name="3"><b class="cmd">oo::meta::info branchset</b> <span class="opt">?<i class="arg">key...</i>?</span> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Merges <em>dict</em> with any other information contaned at node <span class="opt">?<i class="arg">key...</i>?</span>, and adding a trailing :
to all field names.</p>
<pre class="doctools_example">
::oo::meta::info $myclass branchset option color {default green widget colorselect}
puts [::oo::meta::info $myclass get option color]
> {default: green widget: color}
</pre>
</dd>
<dt><a name="4"><b class="cmd">oo::meta::info dump</b> <i class="arg">class</i></a></dt>
<dd><p>Returns the complete snapshot of a class metadata, as producted by <b class="cmd">oo::meta::metadata</b></p></dd>
<dt><a name="5"><b class="cmd">oo::meta::info</b> <i class="arg">class</i> <b class="cmd">is</b> <i class="arg">type</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Returns a boolean true or false if the element <span class="opt">?<i class="arg">args</i>?</span> would match <b class="cmd">string is</b> <i class="arg">type</i> <i class="arg">value</i></p>
<pre class="doctools_example">
::oo::meta::info $myclass set constant mammal 1
puts [::oo::meta::info $myclass is true constant mammal]
> 1
</pre>
</dd>
<dt><a name="6"><b class="cmd">oo::meta::info</b> <i class="arg">class</i> <b class="cmd"><a href="../../../../index.html#merge">merge</a></b> <span class="opt">?<i class="arg">dict</i>?</span> <span class="opt">?<i class="arg">dict</i>?</span> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>Combines all of the arguments into a single dict, which is then stored as the new
local representation for this class.</p></dd>
<dt><a name="7"><b class="cmd">oo::meta::info</b> <i class="arg">class</i> <b class="cmd">rebuild</b></a></dt>
<dd><p>Forces the meta system to destroy any cached representation of a class' metadata before
the next access to <b class="cmd">oo::meta::metadata</b></p></dd>
<dt><a name="8"><b class="cmd">oo::meta::metadata</b> <i class="arg">class</i></a></dt>
<dd><p>Returns an aggregate picture of the metadata for <i class="arg">class</i>, combining its <em>local</em> data
with the <em>local</em> data from its ancestors.</p></dd>
<dt><a name="9"><b class="cmd">oo::define meta</b></a></dt>
<dd><p>The package injects a command <b class="cmd">oo::define::meta</b> which works to provide a class in the
process of definition access to <b class="cmd">oo::meta::info</b>, but without having to look the name up.</p>
<pre class="doctools_example">
oo::define myclass {
meta set foo bar: baz
}
</pre>
</dd>
<dt><a name="10"><b class="cmd">oo::class method meta</b></a></dt>
<dd><p>The package injects a new method <b class="cmd">meta</b> into <b class="cmd">oo::class</b> which works to provide a class
instance access to <b class="cmd">oo::meta::info</b>.</p></dd>
<dt><a name="11"><b class="cmd">oo::object method meta</b></a></dt>
<dd><p>The package injects a new method <b class="cmd">meta</b> into <b class="cmd">oo::object</b>. <b class="cmd">oo::object</b> combines the data
for its class (as provided by <b class="cmd">oo::meta::metadata</b>), with a local variable <em>meta</em> to
produce a local picture of metadata.
This method provides the following additional commands:</p></dd>
<dt><a name="12"><b class="cmd">oo::object method meta cget</b> <span class="opt">?<i class="arg">field</i>?</span> <span class="opt">?<i class="arg">...</i>?</span> <i class="arg">field</i></a></dt>
<dd><p>Attempts to locate a singlar leaf, and return its value. For single option lookups, this
is faster than <b class="cmd">my meta getnull</b> <span class="opt">?<i class="arg">field</i>?</span> <span class="opt">?<i class="arg">...</i>?</span> <i class="arg">field</i>], because
it performs a search instead directly instead of producing the recursive merge product
between the class metadata, the local <em>meta</em> variable, and THEN performing the search.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tcloo</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tool">TOOL</a>, <a href="../../../../index.html#tcloo">TclOO</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>TclOO</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ooutil/ooutil.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
<div class='fossil-doc' data-title='oo::util - Utility commands for TclOO'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">oo::util(n) 1.2.2 tcllib "Utility commands for TclOO"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>oo::util - Utility commands for TclOO</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">oo::util <span class="opt">?1.2.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">mymethod</b> <i class="arg">method</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">classmethod</b> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">body</i></a></li>
<li><a href="#3"><b class="cmd">classvariable</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#4"><b class="cmd">link</b> <i class="arg">method</i>...</a></li>
<li><a href="#5"><b class="cmd">link</b> {<i class="arg">alias</i> <i class="arg">method</i>}...</a></li>
<li><a href="#6"><b class="cmd">ooutil::singleton</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a convenience command for the easy specification
of instance methods as callback commands, like timers, file events, Tk
bindings, etc.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">mymethod</b> <i class="arg">method</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command is available within instance methods. It takes a method
name and, possibly, arguments for the method and returns a command
prefix which, when executed, will invoke the named method of the
object we are in, with the provided arguments, and any others supplied
at the time of actual invokation.</p>
<p>Note: The command is equivalent to and named after the command
provided by the OO package <b class="package"><a href="../snit/snit.html">snit</a></b> for the same purpose.</p></dd>
<dt><a name="2"><b class="cmd">classmethod</b> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">body</i></a></dt>
<dd><p>This command is available within class definitions. It takes a method
name and, possibly, arguments for the method and creates a method on the
class, available to a user of the class and of derived classes.</p>
<p>Note: The command is equivalent to the command <b class="cmd">typemethod</b>
provided by the OO package <b class="package"><a href="../snit/snit.html">snit</a></b> for the same purpose.</p>
<p>Example</p>
<pre class="doctools_example">
oo::class create ActiveRecord {
classmethod find args { puts "[self] called with arguments: $args" }
}
oo::class create Table {
superclass ActiveRecord
}
puts [Table find foo bar]
# ======
# which will write
# ======
# ::Table called with arguments: foo bar
</pre>
</dd>
<dt><a name="3"><b class="cmd">classvariable</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command is available within instance methods. It takes a series
of variable names and makes them available in the method's scope. The
originating scope for the variables is the class (instance) the object
instance belongs to. In other words, the referenced variables are shared
between all instances of their class.</p>
<p>Note: The command is roughly equivalent to the command
<b class="cmd">typevariable</b> provided by the OO package <b class="package"><a href="../snit/snit.html">snit</a></b> for the
same purpose. The difference is that it cannot be used in the class
definition itself.</p>
<p>Example:</p>
<pre class="doctools_example">
% oo::class create Foo {
method bar {z} {
classvariable x y
return [incr x $z],[incr y]
}
}
::Foo
% Foo create a
::a
% Foo create b
::b
% a bar 2
2,1
% a bar 3
5,2
% b bar 7
12,3
% b bar -1
11,4
% a bar 0
11,5
</pre>
</dd>
<dt><a name="4"><b class="cmd">link</b> <i class="arg">method</i>...</a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">link</b> {<i class="arg">alias</i> <i class="arg">method</i>}...</a></dt>
<dd><p>This command is available within instance methods. It takes a list of
method names and/or pairs of alias- and method-name and makes the
named methods available to all instance methods without requiring the
<b class="cmd">my</b> command.</p>
<p>The alias name under which the method becomes available defaults
to the method name, except where explicitly specified through an
alias/method pair.</p>
<p>Examples:</p>
<pre class="doctools_example">
link foo
# The method foo is now directly accessible as foo instead of my foo.
link {bar foo}
# The method foo is now directly accessible as bar.
link a b c
# The methods a, b, and c all become directly acessible under their
# own names.
</pre>
<p>The main use of this command is expected to be in instance constructors,
for convenience, or to set up some methods for use in a mini DSL.</p></dd>
<dt><a name="6"><b class="cmd">ooutil::singleton</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command is a meta-class, i.e. a variant of the builtin
<b class="cmd">oo::class</b> which ensures that it creates only a single
instance of the classes defined with it.</p>
<p>Syntax and results are like for <b class="cmd">oo::class</b>.</p>
<p>Example:</p>
<pre class="doctools_example">
% oo::class create example {
self mixin singleton
method foo {} {self}
}
::example
% [example new] foo
::oo::Obj22
% [example new] foo
::oo::Obj22
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Donal Fellows, Andreas Kupries</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>oo::util</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../snit/snit.html">snit(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tcloo">TclOO</a>, <a href="../../../../index.html#callback">callback</a>, <a href="../../../../index.html#class_methods">class methods</a>, <a href="../../../../index.html#class_variables">class variables</a>, <a href="../../../../index.html#command_prefix">command prefix</a>, <a href="../../../../index.html#currying">currying</a>, <a href="../../../../index.html#method_reference">method reference</a>, <a href="../../../../index.html#my_method">my method</a>, <a href="../../../../index.html#singleton">singleton</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011-2015 Andreas Kupries, BSD licensed</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/otp/otp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<div class='fossil-doc' data-title='otp - RFC 2289 A One-Time Password System'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">otp(n) 1.0.0 tcllib "RFC 2289 A One-Time Password System"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>otp - One-Time Passwords</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">otp <span class="opt">?1.0.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::otp::otp-md4</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></li>
<li><a href="#2"><b class="cmd">::otp::otp-md5</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></li>
<li><a href="#3"><b class="cmd">::otp::otp-sha1</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::otp::otp-rmd160</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the One-Time Password
system as described in RFC 2289 (1). This system uses message-digest
algorithms to sequentially hash a passphrase to create single-use
passwords. The resulting data is then provided to the user as either
hexadecimal digits or encoded using a dictionary of 2048 words. This
system is used by OpenBSD for secure login and can be used as a SASL
mechanism for authenticating users.</p>
<p>In this implementation we provide support for four algorithms that are
included in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4)
and SHA-1 (5).</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::otp::otp-md4</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="2"><b class="cmd">::otp::otp-md5</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="3"><b class="cmd">::otp::otp-sha1</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="4"><b class="cmd">::otp::otp-rmd160</b> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-words</i>?</span> <i class="arg">-seed seed</i> <i class="arg">-count count</i> <i class="arg">data</i></a></dt>
<dd></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
% otp::otp-md5 -count 99 -seed host67821 "My Secret Pass Phrase"
(binary gibberish)
% otp::otp-md5 -words -count 99 -seed host67821 "My Secret Pass Phrase"
SOON ARAB BURG LIMB FILE WAD
% otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase"
e249b58257c80087
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998.
<a href="http://www.rfc-editor.org/rfc/rfc2289.txt">http://www.rfc-editor.org/rfc/rfc2289.txt</a></p></li>
<li><p>Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and
RSA Data Security, Inc, April 1992.
(<a href="http://www.rfc-editor.org/rfc/rfc1321.txt">http://www.rfc-editor.org/rfc/rfc1321.txt</a>)</p></li>
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>H. Dobbertin, A. Bosselaers, B. Preneel,
"RIPEMD-160, a strengthened version of RIPEMD"
<a href="http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf">http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf</a></p></li>
<li><p>"Secure Hash Standard", National Institute of Standards
and Technology, U.S. Department Of Commerce, April 1995.
(<a href="http://www.itl.nist.gov/fipspubs/fip180-1.htm">http://www.itl.nist.gov/fipspubs/fip180-1.htm</a>)</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>otp</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../sasl/sasl.html">SASL</a>, <a href="../md4/md4.html">md4</a>, <a href="../md5/md5.html">md5</a>, <a href="../ripemd/ripemd160.html">ripemd160</a>, <a href="../sha1/sha1.html">sha1</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#password">password</a>, <a href="../../../../index.html#rfc_2289">rfc 2289</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_intro.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
<div class='fossil-doc' data-title='page_intro - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_intro(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_intro - page introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#page">page</a></i> (short for <em>parser generator</em>) stands for a set of
related packages which help in the construction of parser generators,
and other utilities doing text processing.</p>
<p>They are mainly geared towards supporting the Tcllib application
<b class="syscmd"><a href="../../apps/page.html">page</a></b>, with the package <b class="package">page::pluginmgr</b> in a central
role as the plugin management for the application. The other packages
are performing low-level text processing and utility tasks geared
towards parser generation and mainly accessed by <b class="syscmd"><a href="../../apps/page.html">page</a></b> through
plugins.</p>
<p>The packages implementing the plugins are not documented as regular
packages, as they cannot be loaded into a general interpreter, like
tclsh, without extensive preparation of the interpreter. Preparation
which is done for them by the plugin manager.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#text_processing">text processing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_pluginmgr.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
|
<div class='fossil-doc' data-title='page_pluginmgr - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_pluginmgr(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_pluginmgr - page plugin manager</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">CONFIG PLUGIN API</a></li>
<li class="doctools_section"><a href="#section4">READER PLUGIN API</a></li>
<li class="doctools_section"><a href="#section5">WRITER PLUGIN API</a></li>
<li class="doctools_section"><a href="#section6">TRANSFORM PLUGIN API</a></li>
<li class="doctools_section"><a href="#section7">PREDEFINED PLUGINS</a></li>
<li class="doctools_section"><a href="#section8">FEATURES</a></li>
<li class="doctools_section"><a href="#section9">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">page::pluginmgr <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">fileutil</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::page::pluginmgr::reportvia</b> <i class="arg">cmd</i></a></li>
<li><a href="#2"><b class="cmd">::page::pluginmgr::report</b> <i class="arg">level</i> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#3"><b class="cmd">::page::pluginmgr::log</b> <i class="arg">cmd</i></a></li>
<li><a href="#4"><b class="cmd">::page::pluginmgr::configuration</b> <i class="arg">name</i></a></li>
<li><a href="#5"><b class="cmd">::page::pluginmgr::reader</b> <i class="arg">name</i></a></li>
<li><a href="#6"><b class="cmd">::page::pluginmgr::rconfigure</b> <i class="arg">dict</i></a></li>
<li><a href="#7"><b class="cmd">::page::pluginmgr::rtimeable</b></a></li>
<li><a href="#8"><b class="cmd">::page::pluginmgr::rtime</b></a></li>
<li><a href="#9"><b class="cmd">::page::pluginmgr::rgettime</b></a></li>
<li><a href="#10"><b class="cmd">::page::pluginmgr::rhelp</b></a></li>
<li><a href="#11"><b class="cmd">::page::pluginmgr::rlabel</b></a></li>
<li><a href="#12"><b class="cmd">::page::pluginmgr::read</b> <i class="arg">read</i> <i class="arg">eof</i> <span class="opt">?<i class="arg">complete</i>?</span></a></li>
<li><a href="#13"><i class="arg">read</i> <i class="arg">num</i></a></li>
<li><a href="#14"><i class="arg">eof</i></a></li>
<li><a href="#15"><i class="arg">done</i></a></li>
<li><a href="#16"><b class="cmd">::page::pluginmgr::writer</b> <i class="arg">name</i></a></li>
<li><a href="#17"><b class="cmd">::page::pluginmgr::wconfigure</b> <i class="arg">dict</i></a></li>
<li><a href="#18"><b class="cmd">::page::pluginmgr::wtimeable</b></a></li>
<li><a href="#19"><b class="cmd">::page::pluginmgr::wtime</b></a></li>
<li><a href="#20"><b class="cmd">::page::pluginmgr::wgettime</b></a></li>
<li><a href="#21"><b class="cmd">::page::pluginmgr::whelp</b></a></li>
<li><a href="#22"><b class="cmd">::page::pluginmgr::wlabel</b></a></li>
<li><a href="#23"><b class="cmd">::page::pluginmgr::write</b> <i class="arg">chan</i> <i class="arg">data</i></a></li>
<li><a href="#24"><b class="cmd">::page::pluginmgr::transform</b> <i class="arg">name</i></a></li>
<li><a href="#25"><b class="cmd">::page::pluginmgr::tconfigure</b> <i class="arg">id</i> <i class="arg">dict</i></a></li>
<li><a href="#26"><b class="cmd">::page::pluginmgr::ttimeable</b> <i class="arg">id</i></a></li>
<li><a href="#27"><b class="cmd">::page::pluginmgr::ttime</b> <i class="arg">id</i></a></li>
<li><a href="#28"><b class="cmd">::page::pluginmgr::tgettime</b> <i class="arg">id</i></a></li>
<li><a href="#29"><b class="cmd">::page::pluginmgr::thelp</b> <i class="arg">id</i></a></li>
<li><a href="#30"><b class="cmd">::page::pluginmgr::tlabel</b> <i class="arg">id</i></a></li>
<li><a href="#31"><b class="cmd">::page::pluginmgr::transform_do</b> <i class="arg">id</i> <i class="arg">data</i></a></li>
<li><a href="#32"><b class="cmd">page_cdefinition</b></a></li>
<li><a href="#33"><b class="cmd">page_rfeature</b> <i class="arg">name</i></a></li>
<li><a href="#34"><b class="cmd">page_rtime</b></a></li>
<li><a href="#35"><b class="cmd">page_rgettime</b></a></li>
<li><a href="#36"><b class="cmd">page_rlabel</b></a></li>
<li><a href="#37"><b class="cmd">page_rhelp</b></a></li>
<li><a href="#38"><b class="cmd">page_roptions</b></a></li>
<li><a href="#39"><b class="cmd">page_rconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></li>
<li><a href="#40"><b class="cmd">page_rrun</b></a></li>
<li><a href="#41"><b class="cmd">page_read</b> <i class="arg">num</i></a></li>
<li><a href="#42"><b class="cmd">page_read_done</b></a></li>
<li><a href="#43"><b class="cmd">page_eof</b></a></li>
<li><a href="#44"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#45"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#46"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#47"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></li>
<li><a href="#48"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></li>
<li><a href="#49"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></li>
<li><a href="#50"><b class="cmd">page_wfeature</b></a></li>
<li><a href="#51"><b class="cmd">page_wtime</b></a></li>
<li><a href="#52"><b class="cmd">page_wgettime</b></a></li>
<li><a href="#53"><b class="cmd">page_wlabel</b></a></li>
<li><a href="#54"><b class="cmd">page_whelp</b></a></li>
<li><a href="#55"><b class="cmd">page_woptions</b></a></li>
<li><a href="#56"><b class="cmd">page_wconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></li>
<li><a href="#57"><b class="cmd">page_wrun</b> <i class="arg">chan</i> <i class="arg">data</i></a></li>
<li><a href="#58"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#59"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#60"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#61"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></li>
<li><a href="#62"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></li>
<li><a href="#63"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></li>
<li><a href="#64"><b class="cmd">page_tfeature</b></a></li>
<li><a href="#65"><b class="cmd">page_ttime</b></a></li>
<li><a href="#66"><b class="cmd">page_tgettime</b></a></li>
<li><a href="#67"><b class="cmd">page_tlabel</b></a></li>
<li><a href="#68"><b class="cmd">page_thelp</b></a></li>
<li><a href="#69"><b class="cmd">page_toptions</b></a></li>
<li><a href="#70"><b class="cmd">page_tconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></li>
<li><a href="#71"><b class="cmd">page_trun</b> <i class="arg">chan</i> <i class="arg">data</i></a></li>
<li><a href="#72"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#73"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#74"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#75"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></li>
<li><a href="#76"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></li>
<li><a href="#77"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the plugin manager central to the <b class="syscmd"><a href="../../apps/page.html">page</a></b>
application. It manages the various reader, writer, configuration, and
transformation plugins which actually process the text (read,
transform, and write).</p>
<p>All plugins are loaded into slave interpreters specially prepared for
them. While implemented using packages they need this special
environment and are not usable in a plain interpreter, like
tclsh. Because of that they are only described in general terms in
section <span class="sectref"><a href="#section7">PREDEFINED PLUGINS</a></span>, and not documented as regular
packages. It is expected that they follow the APIs specified in the
sections</p>
<ol class="doctools_enumerated">
<li><p><span class="sectref"><a href="#section3">CONFIG PLUGIN API</a></span></p></li>
<li><p><span class="sectref"><a href="#section4">READER PLUGIN API</a></span></p></li>
<li><p><span class="sectref"><a href="#section5">WRITER PLUGIN API</a></span></p></li>
<li><p><span class="sectref"><a href="#section6">TRANSFORM PLUGIN API</a></span></p></li>
</ol>
<p>as per their type.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::page::pluginmgr::reportvia</b> <i class="arg">cmd</i></a></dt>
<dd><p>This command defines the callback command used by
<b class="cmd">::page::pluginmgr::report</b> (see below) to report input errors and
warnings. The default is to write such reports to the standard error
channel.</p></dd>
<dt><a name="2"><b class="cmd">::page::pluginmgr::report</b> <i class="arg">level</i> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>This command is used to report input errors and warnings. By default
such reports are written to the standard error. This can be changed by
setting a user-specific callback command with
<b class="cmd">::page::pluginmgr::reportvia</b> (see above).</p>
<p>The arguments <i class="arg">level</i> and <i class="arg">text</i> specify both the importance
of the message, and the message itself. For the former see the package
<b class="package"><a href="../log/logger.html">logger</a></b> for the allowed values.</p>
<p>The optional argument <i class="arg">from</i> and <i class="arg">to</i> can be used by the
caller to indicate the location (or range) in the input where the
reported problem occured. Each is a list containing two elements, the
line and the column in the input, in this order.</p></dd>
<dt><a name="3"><b class="cmd">::page::pluginmgr::log</b> <i class="arg">cmd</i></a></dt>
<dd><p>This command defines a log callback command to be used by loaded
plugins for the reporting of internal errors, warnings, and general
information. Specifying the empty string as callback disables logging.</p>
<p>Note: The <i class="arg">cmd</i> has to be created by the <b class="package"><a href="../log/logger.html">logger</a></b> package,
or follow the same API as such.</p>
<p>The command returns the empty string as its result.</p></dd>
<dt><a name="4"><b class="cmd">::page::pluginmgr::configuration</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named configuration plugin, retrieves the
options encoded in it, and then immediately unloads it again.</p>
<p>If the <i class="arg">name</i> is the path to a file, then this files will be tried
to be loaded as a plugin first, and, if that fails, opened and its
contents read as a list of options and their arguments, separated by
spaces, tabs and newlines, possibly quotes with single and double
quotes.</p>
<p>See section <span class="sectref"><a href="#section3">CONFIG PLUGIN API</a></span> for the API expected of
configuration plugins.</p>
<p>The result of the command is the list of options retrieved.</p></dd>
<dt><a name="5"><b class="cmd">::page::pluginmgr::reader</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named reader plugin and initializes it. The
result of the command is a list of options the plugin understands.</p>
<p>Only a single reader plugin can be loaded. Loading another reader
plugin causes the previously loaded reader plugin to be de-initialized
and unloaded.</p>
<p>See section <span class="sectref"><a href="#section4">READER PLUGIN API</a></span> for the API expected of
reader plugins.</p></dd>
<dt><a name="6"><b class="cmd">::page::pluginmgr::rconfigure</b> <i class="arg">dict</i></a></dt>
<dd><p>This commands configures the loaded reader plugin. The options and
their values are provided as a Tcl dictionary. The result of the
command is the empty string.</p></dd>
<dt><a name="7"><b class="cmd">::page::pluginmgr::rtimeable</b></a></dt>
<dd><p>This commands checks if the loaded reader plugin is able to collect
timing statistics. The result of the command is a boolean flag. The
result is <b class="const">true</b> if the plugin can be timed, and <b class="const">false</b>
otherwise.</p></dd>
<dt><a name="8"><b class="cmd">::page::pluginmgr::rtime</b></a></dt>
<dd><p>This command activates the collection of timing statistics in the
loaded reader plugin.</p></dd>
<dt><a name="9"><b class="cmd">::page::pluginmgr::rgettime</b></a></dt>
<dd><p>This command retrieves the collected timing statistics of the loaded
reader plugin after it was executed.</p></dd>
<dt><a name="10"><b class="cmd">::page::pluginmgr::rhelp</b></a></dt>
<dd><p>This command retrieves the help string of the loaded reader
plugin. This is expected to be in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="11"><b class="cmd">::page::pluginmgr::rlabel</b></a></dt>
<dd><p>This command retrieves the human-readable name of the loaded reader
plugin.</p></dd>
<dt><a name="12"><b class="cmd">::page::pluginmgr::read</b> <i class="arg">read</i> <i class="arg">eof</i> <span class="opt">?<i class="arg">complete</i>?</span></a></dt>
<dd><p>This command invokes the loaded reader plugin to process the input,
and returns the results of the plugin as its own result. The input is
accessible through the callback commands <i class="arg">read</i>, and <i class="arg">eof</i>. The
optional <i class="arg">done</i> can be used to intrecept when the plugin has
completed its processing. All arguments are command prefixes.</p>
<p>The plugin will invoke the various callbacks in the following
situations:</p>
<dl class="doctools_definitions">
<dt><a name="13"><i class="arg">read</i> <i class="arg">num</i></a></dt>
<dd><p>is invoked whenever input to process is needed, with the number of
characters/bytes it asks for. The result is expected to be the input
the plugin is in need of.</p></dd>
<dt><a name="14"><i class="arg">eof</i></a></dt>
<dd><p>is invoked by the plugin to check if the input has reached the of the
stream. The result is expected to be a boolean flag, <b class="const">true</b> when
the input has hit EOF, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="15"><i class="arg">done</i></a></dt>
<dd><p>is invoked when the plugin has completed the processing of the input.</p></dd>
</dl></dd>
<dt><a name="16"><b class="cmd">::page::pluginmgr::writer</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named writer plugin and initializes it. The
result of the command is a list of options the plugin understands.</p>
<p>Only a single reader plugin can be loaded. Loading another reader
plugin causes the previously loaded reader plugin to be de-initialized
and unloaded.</p>
<p>See section <span class="sectref"><a href="#section5">WRITER PLUGIN API</a></span> for the API expected of
writer plugins.</p></dd>
<dt><a name="17"><b class="cmd">::page::pluginmgr::wconfigure</b> <i class="arg">dict</i></a></dt>
<dd><p>This commands configures the loaded writer plugin. The options and
their values are provided as a Tcl dictionary. The result of the
command is the empty string.</p></dd>
<dt><a name="18"><b class="cmd">::page::pluginmgr::wtimeable</b></a></dt>
<dd><p>This commands checks if the loaded writer plugin is able to measure
execution times. The result of the command is a boolean flag. The
result is <b class="const">true</b> if the plugin can be timed, and <b class="const">false</b>
otherwise.</p></dd>
<dt><a name="19"><b class="cmd">::page::pluginmgr::wtime</b></a></dt>
<dd><p>This command activates the collection of timing statistics in the
loaded writer plugin.</p></dd>
<dt><a name="20"><b class="cmd">::page::pluginmgr::wgettime</b></a></dt>
<dd><p>This command retrieves the collected timing statistics of the loaded
writer plugin after it was executed.</p></dd>
<dt><a name="21"><b class="cmd">::page::pluginmgr::whelp</b></a></dt>
<dd><p>This command retrieves the help string of the loaded writer
plugin. This is expected to be in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="22"><b class="cmd">::page::pluginmgr::wlabel</b></a></dt>
<dd><p>This command retrieves the human-readable name of the loaded writer
plugin.</p></dd>
<dt><a name="23"><b class="cmd">::page::pluginmgr::write</b> <i class="arg">chan</i> <i class="arg">data</i></a></dt>
<dd><p>The loaded writer plugin is invoked to generate the output. It is
given the <i class="arg">data</i> to generate the outpout from, and the Tcl handle
<i class="arg">chan</i> of the channel to write the generated output to. The
command returns th empty string as its result.</p></dd>
<dt><a name="24"><b class="cmd">::page::pluginmgr::transform</b> <i class="arg">name</i></a></dt>
<dd><p>This command loads the named transformation plugin and initializes
it. The result of the command is a 2-element list containing the
plugin id and a list of options the plugin understands, in this order.</p>
<p>Multiple transformations plugins can be loaded and are identified by
handles.</p>
<p>See section <span class="sectref"><a href="#section6">TRANSFORM PLUGIN API</a></span> for the API expected of
transformation plugins.</p></dd>
<dt><a name="25"><b class="cmd">::page::pluginmgr::tconfigure</b> <i class="arg">id</i> <i class="arg">dict</i></a></dt>
<dd><p>This commands configures the identified transformation plugin. The
options and their values are provided as a Tcl dictionary. The result
of the command is the empty string.</p></dd>
<dt><a name="26"><b class="cmd">::page::pluginmgr::ttimeable</b> <i class="arg">id</i></a></dt>
<dd><p>This commands checks if the identified transformation plugin is able
to collect timing statistics. The result of the command is a boolean
flag. The result is <b class="const">true</b> if the plugin can be timed, and
<b class="const">false</b> otherwise.</p></dd>
<dt><a name="27"><b class="cmd">::page::pluginmgr::ttime</b> <i class="arg">id</i></a></dt>
<dd><p>This command activates the collection of timing statistics in the
identified transformation plugin.</p></dd>
<dt><a name="28"><b class="cmd">::page::pluginmgr::tgettime</b> <i class="arg">id</i></a></dt>
<dd><p>This command retrieves the collected timing statistics of the
identified transformation plugin after it was executed.</p></dd>
<dt><a name="29"><b class="cmd">::page::pluginmgr::thelp</b> <i class="arg">id</i></a></dt>
<dd><p>This command retrieves the help string of the identified
transformation plugin. This is expected to be in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>
format.</p></dd>
<dt><a name="30"><b class="cmd">::page::pluginmgr::tlabel</b> <i class="arg">id</i></a></dt>
<dd><p>This command retrieves the human-readable name of the identified
transformation plugin.</p></dd>
<dt><a name="31"><b class="cmd">::page::pluginmgr::transform_do</b> <i class="arg">id</i> <i class="arg">data</i></a></dt>
<dd><p>The identified transformation plugin is invoked to process the
specified <i class="arg">data</i>. The result of the plugin is returned as the
result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CONFIG PLUGIN API</a></h2>
<p>Configuration plugins are expected to provide a single command,
described below.</p>
<dl class="doctools_definitions">
<dt><a name="32"><b class="cmd">page_cdefinition</b></a></dt>
<dd><p>This command of a configuration plugin is called by the plugin manager
to execute it. Its result has to be a list of options and values to
process.</p></dd>
</dl>
<p>Configuration plugins do not expect the environment to provide any
special commands.</p>
<p>It is expected that a configuration plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::config::<b class="const">FOO</b></b>.</p>
<p>Configuration plugins are loaded, executed, and unloaded in one step,
they are not kept in memory. The command for doing this is
<b class="cmd">::page::pluginmgr::configuration</b>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">READER PLUGIN API</a></h2>
<p>Reader plugins are expected to provide the following commands,
described below.</p>
<dl class="doctools_definitions">
<dt><a name="33"><b class="cmd">page_rfeature</b> <i class="arg">name</i></a></dt>
<dd><p>This command takes a feature <i class="arg">name</i> and returns a boolean flag
indicating whether the feature is supported by the plugin, or not.
The result has to be <b class="const">true</b> if the feature is supported, and
<b class="const">false</b> otherwise.</p>
<p>See section <span class="sectref"><a href="#section8">FEATURES</a></span> for the possible features the plugin
manager will ask for.</p></dd>
<dt><a name="34"><b class="cmd">page_rtime</b></a></dt>
<dd><p>This command is invoked to activate the collection of timing
statistics.</p></dd>
<dt><a name="35"><b class="cmd">page_rgettime</b></a></dt>
<dd><p>This command is invoked to retrieve the collected timing statistics.</p></dd>
<dt><a name="36"><b class="cmd">page_rlabel</b></a></dt>
<dd><p>This command is invoked to retrieve a human-readable label for the
plugin.</p></dd>
<dt><a name="37"><b class="cmd">page_rhelp</b></a></dt>
<dd><p>This command is invoked to retrieve a help text for plugin. The text
is expected to be in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="38"><b class="cmd">page_roptions</b></a></dt>
<dd><p>This command is invoked to retrieve the options understood by the
plugin.</p></dd>
<dt><a name="39"><b class="cmd">page_rconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></dt>
<dd><p>This command is invoked to reconfigure the plugin, specifically the
given <i class="arg">option</i> is set to the new <i class="arg">value</i>.</p></dd>
<dt><a name="40"><b class="cmd">page_rrun</b></a></dt>
<dd><p>This command is invoked to process the input stream per the current
plugin configuration. The result of the command is the result of the
processing.</p></dd>
</dl>
<p>Reader plugins expect the environment to provide the following special
commands.</p>
<dl class="doctools_definitions">
<dt><a name="41"><b class="cmd">page_read</b> <i class="arg">num</i></a></dt>
<dd><p>This command is invoked to read <i class="arg">num</i> characters/bytes from the
input. Its result has to be read characters/bytes.</p></dd>
<dt><a name="42"><b class="cmd">page_read_done</b></a></dt>
<dd><p>This command is invoked to signal that the plugin has completed the
processing of the input.</p></dd>
<dt><a name="43"><b class="cmd">page_eof</b></a></dt>
<dd><p>This command is invoked to check if the input stream has reached its
end. Its result has to be a boolean flag, <b class="const">true</b> when the input
has reached the end, <b class="const">false</b> otherwise.</p></dd>
<dt><a name="44"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report some information to the user. May indicate a
location or range in the input. Each piece of location data, if
provided, is a 2-element list containing line and column numbers.</p></dd>
<dt><a name="45"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report a warning to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a
2-element list containing line and column numbers.</p></dd>
<dt><a name="46"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report an error to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a
2-element list containing line and column numbers.</p></dd>
<dt><a name="47"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report some internal information.</p></dd>
<dt><a name="48"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal warning.</p></dd>
<dt><a name="49"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal error.</p></dd>
</dl>
<p>It is expected that a reader plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::reader::<b class="const">FOO</b></b>.</p>
<p>Reader plugins are loaded by the command
<b class="cmd">::page::pluginmgr::reader</b>. At most one reader plugin can be kept
in memory.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">WRITER PLUGIN API</a></h2>
<p>Writer plugins are expected to provide the following commands,
described below.</p>
<dl class="doctools_definitions">
<dt><a name="50"><b class="cmd">page_wfeature</b></a></dt>
<dd><p>This command takes a feature <i class="arg">name</i> and returns a boolean flag
indicating whether the feature is supported by the plugin, or not.
The result has to be <b class="const">true</b> if the feature is supported, and
<b class="const">false</b> otherwise.</p>
<p>See section <span class="sectref"><a href="#section8">FEATURES</a></span> for the possible features the plugin
manager will ask for.</p></dd>
<dt><a name="51"><b class="cmd">page_wtime</b></a></dt>
<dd><p>This command is invoked to activate the collection of timing
statistics.</p></dd>
<dt><a name="52"><b class="cmd">page_wgettime</b></a></dt>
<dd><p>This command is invoked to retrieve the collected timing statistics.</p></dd>
<dt><a name="53"><b class="cmd">page_wlabel</b></a></dt>
<dd><p>This command is invoked to retrieve a human-readable label for the
plugin.</p></dd>
<dt><a name="54"><b class="cmd">page_whelp</b></a></dt>
<dd><p>This command is invoked to retrieve a help text for plugin. The text
is expected to be in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="55"><b class="cmd">page_woptions</b></a></dt>
<dd><p>This command is invoked to retrieve the options understood by the
plugin.</p></dd>
<dt><a name="56"><b class="cmd">page_wconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></dt>
<dd><p>This command is invoked to reconfigure the plugin, specifically the
given <i class="arg">option</i> is set to the new <i class="arg">value</i>.</p></dd>
<dt><a name="57"><b class="cmd">page_wrun</b> <i class="arg">chan</i> <i class="arg">data</i></a></dt>
<dd><p>This command is invoked to process the specified <i class="arg">data</i> and write
it to the output stream <i class="arg">chan</i>. The latter is a Tcl channel handle
opened for writing. The result of the command is the empty string.</p></dd>
</dl>
<p>Writer plugins expect the environment to provide the following special
commands.</p>
<dl class="doctools_definitions">
<dt><a name="58"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report some information to the user. May indicate a
location or range in the input. Each piece of location data, if
provided, is a 2-element list containing line and column numbers.</p></dd>
<dt><a name="59"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report a warning to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a
2-element list containing line and column numbers.</p></dd>
<dt><a name="60"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report an error to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a
2-element list containing line and column numbers.</p></dd>
<dt><a name="61"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report some internal information.</p></dd>
<dt><a name="62"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal warning.</p></dd>
<dt><a name="63"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal error.</p></dd>
</dl>
<p>It is expected that a writer plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::writer::<b class="const">FOO</b></b>.</p>
<p>Writer plugins are loaded by the command
<b class="cmd">::page::pluginmgr::writer</b>. At most one writer plugin can be kept
in memory.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">TRANSFORM PLUGIN API</a></h2>
<p>page::transform::*
Transformation plugins are expected to provide the following commands,
described below.</p>
<dl class="doctools_definitions">
<dt><a name="64"><b class="cmd">page_tfeature</b></a></dt>
<dd><p>This command takes a feature <i class="arg">name</i> and returns a boolean flag
indicating whether the feature is supported by the plugin, or not.
The result has to be <b class="const">true</b> if the feature is supported, and
<b class="const">false</b> otherwise.</p>
<p>See section <span class="sectref"><a href="#section8">FEATURES</a></span> for the possible features the plugin
manager will ask for.</p></dd>
<dt><a name="65"><b class="cmd">page_ttime</b></a></dt>
<dd><p>This command is invoked to activate the collection of timing
statistics.</p></dd>
<dt><a name="66"><b class="cmd">page_tgettime</b></a></dt>
<dd><p>This command is invoked to retrieve the collected timing statistics.</p></dd>
<dt><a name="67"><b class="cmd">page_tlabel</b></a></dt>
<dd><p>This command is invoked to retrieve a human-readable label for the
plugin.</p></dd>
<dt><a name="68"><b class="cmd">page_thelp</b></a></dt>
<dd><p>This command is invoked to retrieve a help text for plugin. The text
is expected to be in <i class="term"><a href="../../../../index.html#doctools">doctools</a></i> format.</p></dd>
<dt><a name="69"><b class="cmd">page_toptions</b></a></dt>
<dd><p>This command is invoked to retrieve the options understood by the
plugin.</p></dd>
<dt><a name="70"><b class="cmd">page_tconfigure</b> <i class="arg">option</i> <i class="arg">value</i></a></dt>
<dd><p>This command is invoked to reconfigure the plugin, specifically the
given <i class="arg">option</i> is set to the new <i class="arg">value</i>.</p></dd>
<dt><a name="71"><b class="cmd">page_trun</b> <i class="arg">chan</i> <i class="arg">data</i></a></dt>
<dd><p>This command is invoked to process the specified <i class="arg">data</i> and write
it to the output stream <i class="arg">chan</i>. The latter is a Tcl channel handle
opened for writing. The result of the command is the empty string.</p></dd>
</dl>
<p>Transformation plugins expect the environment to provide the following
special commands.</p>
<dl class="doctools_definitions">
<dt><a name="72"><b class="cmd">page_info</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report some information to the user. May indicate a
location or range in the input. Each piece of location data, if
provided, is a 2-element list containing line and column numbers.</p></dd>
<dt><a name="73"><b class="cmd">page_warning</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report a warning to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a
2-element list containing line and column numbers.</p></dd>
<dt><a name="74"><b class="cmd">page_error</b> <i class="arg">text</i> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>Invoked to report an error to the user. May indicate a location or
range in the input. Each piece of location data, if provided, is a
2-element list containing line and column numbers.</p></dd>
<dt><a name="75"><b class="cmd">page_log_info</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report some internal information.</p></dd>
<dt><a name="76"><b class="cmd">page_log_warning</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal warning.</p></dd>
<dt><a name="77"><b class="cmd">page_log_error</b> <i class="arg">text</i></a></dt>
<dd><p>Invoked to report an internal error.</p></dd>
</dl>
<p>It is expected that a transformation plugin <b class="const">FOO</b> is implemented
by the package <b class="package">page::transform::<b class="const">FOO</b></b>.</p>
<p>Transformation plugins are loaded by the command
<b class="cmd">::page::pluginmgr::transform</b>. More than one transformation
plugin can be kept in memory.</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">PREDEFINED PLUGINS</a></h2>
<p>The following predefined plugins are known, i.e. provided by the page
module.</p>
<dl class="doctools_definitions">
<dt>Configuration</dt>
<dd><dl class="doctools_definitions">
<dt>peg</dt>
<dd><p>Returns a set of options to configure the <b class="syscmd"><a href="../../apps/page.html">page</a></b> application
for the processing of a PEG grammar and the generation of ME code. See
the packages <b class="package">grammar_peg</b>, <b class="package">grammar_me</b> and relations
for more details.</p></dd>
</dl></dd>
<dt>Reader</dt>
<dd><dl class="doctools_definitions">
<dt>hb</dt>
<dd><p>Expects a so-called <i class="term">half-baked PEG container</i> as input and
returns the equivalent abstract syntax tree. See the writer plugin
<i class="term">hb</i> for the plugin generating this type of input.</p></dd>
<dt>lemon</dt>
<dd><p>Expects a grammar specification as understood by Richar Hipp's LEMON
parser generator and returns an abstract syntax tree for it.</p></dd>
<dt>peg</dt>
<dd><p>Expects a grammar specification in the form of a parsing expression
grammar (PEG) and returns an abstract syntax tree for it.</p></dd>
<dt>ser</dt>
<dd><p>Expect the serialized form of a parsing expression grammar as
generated by the package <b class="package"><a href="../grammar_peg/peg.html">grammar::peg</a></b> as input, converts it
into an equivalent abstract syntax tree and returns that.</p></dd>
<dt>treeser</dt>
<dd><p>Expects the serialized form of a tree as generated by the package
<b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b> as input and returns it, after validation.</p></dd>
</dl></dd>
<dt>Writer</dt>
<dd><dl class="doctools_definitions">
<dt>hb</dt>
<dd><p>Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out in the form of a so-called
<i class="term">half-baked PEG container</i>.</p></dd>
<dt>identity</dt>
<dd><p>Takes any input and writes it as is.</p></dd>
<dt>mecpu</dt>
<dd><p>Expects symbolic assembler code for the MatchEngine CPU (See the
package <b class="package"><a href="../grammar_me/me_cpu.html">grammar::me::cpu</a></b> and relatives) and writes it out as
Tcl code for a parser.</p></dd>
<dt>me</dt>
<dd><p>Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out as Tcl code for the MatchEngine (See the
package <b class="package">grammar::me</b> and relatives) which parses input in
that grammar.</p></dd>
<dt>null</dt>
<dd><p>Takes any input and writes nothing. The logical equivalent of
/dev/null.</p></dd>
<dt>peg</dt>
<dd><p>Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out in the form of a canonical PEG which can be
read by the reader plugin <i class="term">peg</i>.</p></dd>
<dt>ser</dt>
<dd><p>Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out as a serialized PEG container which can be
read by the reader plugin <i class="term">ser</i>.</p></dd>
<dt>tpc</dt>
<dd><p>Expects an abstract syntax tree for a parsing expression grammar as
input and writes it out as Tcl code initializing a PEG container as
provided by the package <b class="package"><a href="../grammar_peg/peg.html">grammar::peg</a></b>.</p></dd>
<dt>tree</dt>
<dd><p>Takes any serialized tree (per package <b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>) as
input and writes it out in a generic indented format.</p></dd>
</dl></dd>
<dt>Transformation</dt>
<dd><dl class="doctools_definitions">
<dt>mecpu</dt>
<dd><p>Takes an abstract syntax tree for a parsing expression grammer as
input, generates symbolic assembler code for the MatchEngine CPU, and
returns that as its result (See the package <b class="package"><a href="../grammar_me/me_cpu.html">grammar::me::cpu</a></b>
and relatives).</p></dd>
<dt>reachable</dt>
<dd><p>Takes an abstract syntax tree for a parsing expression grammer as
input, performs a reachability analysis, and returns the modified and
annotated tree.</p></dd>
<dt>realizable</dt>
<dd><p>Takes an abstract syntax tree for a parsing expression grammer as
input, performs an analysis of realizability, and returns the modified
and annotated tree.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">FEATURES</a></h2>
<p>The plugin manager currently checks the plugins for only one feature,
<b class="const">timeable</b>. A plugin supporting this feature is assumed to be
able to collect timing statistics on request.</p>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#text_processing">text processing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_util_flow.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<div class='fossil-doc' data-title='page_util_flow - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_util_flow(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_util_flow - page dataflow/treewalker utility</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">FLOW API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">page::util::flow <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::page::util::flow</b> <i class="arg">start</i> <i class="arg">flowvar</i> <i class="arg">nodevar</i> <i class="arg">script</i></a></li>
<li><a href="#2"><i class="arg">flow</i> <b class="method">visit</b> <i class="arg">node</i></a></li>
<li><a href="#3"><i class="arg">flow</i> <b class="method">visitl</b> <i class="arg">nodelist</i></a></li>
<li><a href="#4"><i class="arg">flow</i> <b class="method">visita</b> <i class="arg">node</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single utility command for easy dataflow based
manipulation of arbitrary data structures, especially abstract syntax
trees.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::page::util::flow</b> <i class="arg">start</i> <i class="arg">flowvar</i> <i class="arg">nodevar</i> <i class="arg">script</i></a></dt>
<dd><p>This command contains the core logic to drive the walking of an
arbitrary data structure which can partitioned into separate
parts. Examples of such structures are trees and graphs.</p>
<p>The command makes no assumptions at all about the API of the structure
to be walked, except that that its parts, here called <i class="term">nodes</i>,
are identified by strings. These strings are taken as is, from the
arguments, and the body, and handed back to the body, without
modification.</p>
<p>Access to the actual data structure, and all decisions regarding which
nodes to visit in what order are delegated to the body of the loop,
i.e. the <i class="arg">script</i>.</p>
<p>The body is invoked first for the nodes in the start-set specified via
<i class="arg">start</i>), and from then on for the nodes the body has requested to
be visited. The command stops when the set of nodes to visit becomes
empty. Note that a node can be visited more than once. The body has
complete control about this.</p>
<p>The body is invoked in the context of the caller. The variable named
by <i class="arg">nodevar</i> will be set to the current node, and the variable
named by <i class="arg">flowvar</i> will be set to the command of the flow object
through which the body can request the nodes to visit next. The API
provided by this object is described in the next section,
<span class="sectref"><a href="#section3">FLOW API</a></span>.</p>
<p>Note that the command makes no promises regarding the order in which
nodes are visited, excpt that the nodes requested to be visited by the
current iteration will be visited afterward, in some order.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">FLOW API</a></h2>
<p>This section describes the API provided by the flow object made
accessible to the body script of <b class="cmd">::page::util::flow</b>.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">flow</i> <b class="method">visit</b> <i class="arg">node</i></a></dt>
<dd><p>Invoking this method requests that the node <i class="arg">n</i> is visited after
the current iteration.</p></dd>
<dt><a name="3"><i class="arg">flow</i> <b class="method">visitl</b> <i class="arg">nodelist</i></a></dt>
<dd><p>Invoking this method requests that all the nodes found in the list
<i class="arg">nodelist</i> are visited after the current iteration.</p></dd>
<dt><a name="4"><i class="arg">flow</i> <b class="method">visita</b> <i class="arg">node</i>...</a></dt>
<dd><p>This is the variadic arguments form of the method <b class="method">visitl</b>, see
above.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#dataflow">dataflow</a>, <a href="../../../../index.html#graph_walking">graph walking</a>, <a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#text_processing">text processing</a>, <a href="../../../../index.html#tree_walking">tree walking</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<div class='fossil-doc' data-title='page_util_norm_lemon - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_util_norm_lemon(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_util_norm_lemon - page AST normalization, LEMON</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">page::util::norm_lemon <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::page::util::norm::lemon</b> <i class="arg">tree</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single utility command which takes an AST for a
lemon grammar and normalizes it in various ways. The result
is called a <i class="term">Normalized Lemon Grammar Tree</i>.</p>
<p><em>Note</em> that this package can only be used from within a plugin
managed by the package <b class="package">page::pluginmgr</b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::page::util::norm::lemon</b> <i class="arg">tree</i></a></dt>
<dd><p>This command assumes the <i class="arg">tree</i> object contains for a lemon
grammar. It normalizes this tree in place. The result is called a
<i class="term">Normalized Lemon Grammar Tree</i>.</p>
<p>The exact operations performed are left undocumented for the moment.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#graph_walking">graph walking</a>, <a href="../../../../index.html#lemon">lemon</a>, <a href="../../../../index.html#normalization">normalization</a>, <a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#text_processing">text processing</a>, <a href="../../../../index.html#tree_walking">tree walking</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_util_norm_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<div class='fossil-doc' data-title='page_util_norm_peg - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_util_norm_peg(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_util_norm_peg - page AST normalization, PEG</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">page::util::norm_peg <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::page::util::norm::peg</b> <i class="arg">tree</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a single utility command which takes an AST for a
parsing expression grammar and normalizes it in various ways. The result
is called a <i class="term">Normalized PE Grammar Tree</i>.</p>
<p><em>Note</em> that this package can only be used from within a plugin
managed by the package <b class="package">page::pluginmgr</b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::page::util::norm::peg</b> <i class="arg">tree</i></a></dt>
<dd><p>This command assumes the <i class="arg">tree</i> object contains for a
parsing expression grammar. It normalizes this tree in place.
The result is called a <i class="term">Normalized PE Grammar Tree</i>.</p>
<p>The following operations are performd</p>
<ol class="doctools_enumerated">
<li><p>The data for all terminals is stored in their grandparental
nodes. The terminal nodes and their parents are removed. Type
information is dropped.</p></li>
<li><p>All nodes which have exactly one child are irrelevant and are
removed, with the exception of the root node. The immediate
child of the root is irrelevant as well, and removed as well.</p></li>
<li><p>The name of the grammar is moved from the tree node it is stored
in to an attribute of the root node, and the tree node removed.</p>
<p>The node keeping the start expression separate is removed as
irrelevant and the root node of the start expression tagged with
a marker attribute, and its handle saved in an attribute of the
root node for quick access.</p></li>
<li><p>Nonterminal hint information is moved from nodes into attributes,
and the now irrelevant nodes are deleted.</p>
<p><em>Note:</em> This transformation is dependent on the removal of all
nodes with exactly one child, as it removes the all 'Attribute'
nodes already. Otherwise this transformation would have to put
the information into the grandparental node.</p>
<p>The default mode given to the nonterminals is <b class="const">value</b>.</p>
<p>Like with the global metadata definition specific information
is moved out out of nodes into attributes, the now irrelevant
nodes are deleted, and the root nodes of all definitions are
tagged with marker attributes. This provides us with a mapping
from nonterminal names to their defining nodes as well, which
is saved in an attribute of the root node for quick reference.</p>
<p>At last the range in the input covered by a definition is
computed. The left extent comes from the terminal for the
nonterminal symbol it defines. The right extent comes from
the rightmost child under the definition. While this not an
expression tree yet the location data is sound already.</p></li>
<li><p>The remaining nodes under all definitions are transformed
into proper expression trees. First character ranges, followed
by unary operations, characters, and nonterminals. At last the
tree is flattened by the removal of superfluous inner nodes.</p>
<p>The order matters, to shed as much nodes as possible early, and
to avoid unnecessary work later.</p></li>
</ol></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#graph_walking">graph walking</a>, <a href="../../../../index.html#normalization">normalization</a>, <a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#text_processing">text processing</a>, <a href="../../../../index.html#tree_walking">tree walking</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_util_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
<div class='fossil-doc' data-title='page_util_peg - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_util_peg(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_util_peg - page PEG transformation utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">page::util::peg <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::page::util::peg::symbolNodeOf</b> <i class="arg">tree</i> <i class="arg">node</i></a></li>
<li><a href="#2"><b class="cmd">::page::util::peg::symbolOf</b> <i class="arg">tree</i> <i class="arg">node</i></a></li>
<li><a href="#3"><b class="cmd">::page::util::peg::updateUndefinedDueRemoval</b> <i class="arg">tree</i></a></li>
<li><a href="#4"><b class="cmd">::page::util::peg::flatten</b> <i class="arg">treequery</i> <i class="arg">tree</i></a></li>
<li><a href="#5"><b class="cmd">::page::util::peg::getWarnings</b> <i class="arg">tree</i></a></li>
<li><a href="#6"><b class="cmd">::page::util::peg::printWarnings</b> <i class="arg">msg</i></a></li>
<li><a href="#7"><b class="cmd">::page::util::peg::peOf</b> <i class="arg">tree</i> <i class="arg">eroot</i></a></li>
<li><a href="#8"><b class="cmd">::page::util::peg::printTclExpr</b> <i class="arg">pe</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a few common operations to PEG transformations.
They assume a <i class="term">Normalized PE Grammar Tree</i> as input, see the
package <b class="package">page::util::norm::peg</b>, possibly augmented with
attributes coming from transformations not in conflict with the base
definition.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::page::util::peg::symbolNodeOf</b> <i class="arg">tree</i> <i class="arg">node</i></a></dt>
<dd><p>Given an arbitrary expression <i class="arg">node</i> in the AST <i class="arg">tree</i> it
determines the node (itself or an ancestor) containing the name of the
nonterminal symbol the node belongs to, and returns its id. The result
is either the root of the tree (for the start expression), or a
definition node.</p></dd>
<dt><a name="2"><b class="cmd">::page::util::peg::symbolOf</b> <i class="arg">tree</i> <i class="arg">node</i></a></dt>
<dd><p>As <b class="cmd">::page::util::peg::symbolNodeOf</b>, but returns the symbol name
instead of the node.</p></dd>
<dt><a name="3"><b class="cmd">::page::util::peg::updateUndefinedDueRemoval</b> <i class="arg">tree</i></a></dt>
<dd><p>The removal of nodes in the AST <i class="arg">tree</i> can cause symbols to lose
one or more users.</p>
<pre class="doctools_example">
A used by B and C,
B is reachable,
C is not,
so A now loses the node in the expression for C calling it,
or rather, not calling it anymore.
</pre>
<p>This command updates the cross-references and which nonterminals are
now undefined.</p></dd>
<dt><a name="4"><b class="cmd">::page::util::peg::flatten</b> <i class="arg">treequery</i> <i class="arg">tree</i></a></dt>
<dd><p>This commands flattens nested sequence and choice operators in the AST
<i class="arg">tree</i>, re-using the <b class="package"><a href="../treeql/treeql.html">treeql</a></b> object <i class="arg">treequery</i> to
run the query determining which nodes to cut.</p></dd>
<dt><a name="5"><b class="cmd">::page::util::peg::getWarnings</b> <i class="arg">tree</i></a></dt>
<dd><p>This command looks at the attributes of the AST <i class="arg">tree</i> for
problems with the grammar and issues warnings. They do not prevent us
from writing the grammar, but still represent problems with it the
user should be made aware of.</p>
<p>The result of the command is a dictionary mapping nonterminal names to
their associated warnings.</p></dd>
<dt><a name="6"><b class="cmd">::page::util::peg::printWarnings</b> <i class="arg">msg</i></a></dt>
<dd><p>The argument of the command is a dictionary mapping nonterminal names
to their associated warnings, as generated by, for example, the
command <b class="cmd">::page::util::peg::getWarnings</b>.</p>
<p>The warnings contained therein are formatted and then printed via the
log command <b class="cmd">page_info</b>. This means that this command can be used
only from within a plugin managed by the package
<b class="package">page::pluginmgr</b>.</p></dd>
<dt><a name="7"><b class="cmd">::page::util::peg::peOf</b> <i class="arg">tree</i> <i class="arg">eroot</i></a></dt>
<dd><p>This command converts the parsing expression starting at the node
<i class="arg">eroot</i> in the AST <i class="arg">tree</i> into a nested list. The exact syntax
of this list specified by the package <b class="package"><a href="../grammar_peg/peg.html">grammar::peg</a></b>.</p></dd>
<dt><a name="8"><b class="cmd">::page::util::peg::printTclExpr</b> <i class="arg">pe</i></a></dt>
<dd><p>This command converts the parsing expression contained in the nested
list <i class="arg">pe</i> into a Tcl string which can be placed into a Tcl script.
See the package <b class="package"><a href="../grammar_peg/peg.html">grammar::peg</a></b> for the exact syntax of
<i class="arg">pe</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#text_processing">text processing</a>, <a href="../../../../index.html#transformation">transformation</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/page/page_util_quote.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
<div class='fossil-doc' data-title='page_util_quote - Parser generator tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">page_util_quote(n) 1.0 tcllib "Parser generator tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>page_util_quote - page character quoting utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">page::util::quote <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::page::util::quote::unquote</b> <i class="arg">char</i></a></li>
<li><a href="#2"><b class="cmd">::page::util::quote::quote'tcl</b> <i class="arg">char</i></a></li>
<li><a href="#3"><b class="cmd">::page::util::quote::quote'tclstr</b> <i class="arg">char</i></a></li>
<li><a href="#4"><b class="cmd">::page::util::quote::quote'tclcom</b> <i class="arg">char</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a few utility commands to convert characters
into various forms.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::page::util::quote::unquote</b> <i class="arg">char</i></a></dt>
<dd><p>A character, as stored in an abstract syntax tree by a PEG processor
(See the packages <b class="package">grammar::peg::interpreter</b>,
<b class="package">grammar::me</b>, and their relations), i.e. in some quoted form,
is converted into the equivalent Tcl character. The character is returned
as the result of the command.</p></dd>
<dt><a name="2"><b class="cmd">::page::util::quote::quote'tcl</b> <i class="arg">char</i></a></dt>
<dd><p>This command takes a Tcl character (internal representation) and
converts it into a string which is accepted by the Tcl parser, will
regenerate the character in question and is 7bit ASCII. The string is
returned as the result of this command.</p></dd>
<dt><a name="3"><b class="cmd">::page::util::quote::quote'tclstr</b> <i class="arg">char</i></a></dt>
<dd><p>This command takes a Tcl character (internal representation) and
converts it into a string which is accepted by the Tcl parser and will
generate a human readable representation of the character in question.
The string is returned as the result of this command.</p>
<p>The string does not use any unprintable characters. It may use
backslash-quoting. High UTF characters are quoted to avoid problems
with the still prevalent ascii terminals. It is assumed that the
string will be used in a double-quoted environment.</p></dd>
<dt><a name="4"><b class="cmd">::page::util::quote::quote'tclcom</b> <i class="arg">char</i></a></dt>
<dd><p>This command takes a Tcl character (internal representation) and
converts it into a string which is accepted by the Tcl parser when
used within a Tcl comment. The string is returned as the result of
this command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>page</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#page">page</a>, <a href="../../../../index.html#parser_generator">parser generator</a>, <a href="../../../../index.html#quoting">quoting</a>, <a href="../../../../index.html#text_processing">text processing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Page Parser Generator</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pki/pki.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
|
<div class='fossil-doc' data-title='pki - public key encryption'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pki(n) 0.10 tcllib "public key encryption"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pki - Implementation of the public key cipher</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pki <span class="opt">?0.10?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pki::encrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-pad</i>?</span> <span class="opt">?<i class="arg">-nopad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></li>
<li><a href="#2"><b class="cmd">::pki::decrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-unpad</i>?</span> <span class="opt">?<i class="arg">-nounpad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></li>
<li><a href="#3"><b class="cmd">::pki::sign</b> <i class="arg">input</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::pki::verify</b> <i class="arg">signedmessage</i> <i class="arg">plaintext</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::pki::key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span> <span class="opt">?<i class="arg">encodePem</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::pki::pkcs::parse_key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::pki::x509::parse_cert</b> <i class="arg">cert</i></a></li>
<li><a href="#8"><b class="cmd">::pki::rsa::generate</b> <i class="arg">bitlength</i> <span class="opt">?<i class="arg">exponent</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::pki::x509::verify_cert</b> <i class="arg">cert</i> <i class="arg">trustedcerts</i> <span class="opt">?<i class="arg">intermediatecerts</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::pki::x509::validate_cert</b> <i class="arg">cert</i> <span class="opt">?<b class="option">-sign_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-encrypt_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-sign_cert</b> <i class="arg">dn_to_be_signed</i> <i class="arg">ca_depth</i>?</span> <span class="opt">?<b class="option">-ssl</b> <i class="arg">dn</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::pki::pkcs::create_csr</b> <i class="arg">keylist</i> <i class="arg">namelist</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::pki::pkcs::parse_csr</b> <i class="arg">csr</i></a></li>
<li><a href="#13"><b class="cmd">::pki::x509::create_cert</b> <i class="arg">signreqlist</i> <i class="arg">cakeylist</i> <i class="arg">serial_number</i> <i class="arg">notBefore</i> <i class="arg">notAfter</i> <i class="arg">isCA</i> <i class="arg">extensions</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pki::encrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-pad</i>?</span> <span class="opt">?<i class="arg">-nopad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></dt>
<dd><p>Encrypt a message using PKI (probably RSA).
Requires the caller to specify either <b class="option">-priv</b> to encrypt with
the private key or <b class="option">-pub</b> to encrypt with the public key. The
default option is to pad and return in hex. One of <b class="option">-pub</b> or
<b class="option">-priv</b> must be specified.
The <b class="option">-hex</b> option causes the data to be returned in encoded as
a hexidecimal string, while the <b class="option">-binary</b> option causes the data
to be returned as a binary string. If they are specified multiple
times, the last one specified is used.
The <b class="option">-pad</b> option causes the data to be padded per PKCS#1 prior
to being encrypted. The <b class="option">-nopad</b> inhibits this behaviour. If
they are specified multiple times, the last one specified is used.
The input to encrypt is specified as <i class="arg">input</i>.
The <i class="arg">key</i> parameter, holding the key to use, is a return value
from either
<b class="cmd">::pki::pkcs::parse_key</b>,
<b class="cmd">::pki::x509::parse_cert</b>, or
<b class="cmd">::pki::rsa::generate</b>.</p>
<p>Mapping to OpenSSL's <b class="syscmd">openssl</b> application:</p>
<ol class="doctools_enumerated">
<li><p>"openssl rsautl -encrypt" == "::pki::encrypt -binary -pub"</p></li>
<li><p>"openssl rsautl -sign" == "::pki::encrypt -binary -priv"</p></li>
</ol></dd>
<dt><a name="2"><b class="cmd">::pki::decrypt</b> <span class="opt">?<i class="arg">-binary</i>?</span> <span class="opt">?<i class="arg">-hex</i>?</span> <span class="opt">?<i class="arg">-unpad</i>?</span> <span class="opt">?<i class="arg">-nounpad</i>?</span> <span class="opt">?<i class="arg">-priv</i>?</span> <span class="opt">?<i class="arg">-pub</i>?</span> <span class="opt">?<i class="arg">--</i>?</span> <i class="arg">input</i> <i class="arg">key</i></a></dt>
<dd><p>Decrypt a message using PKI (probably RSA). See <b class="cmd">::pki::encrypt</b> for option handling.</p>
<p>Mapping to OpenSSL's <b class="syscmd">openssl</b> application:</p>
<ol class="doctools_enumerated">
<li><p>"openssl rsautl -decrypt" == "::pki::decrypt -binary -priv"</p></li>
<li><p>"openssl rsautl -verify" == "::pki::decrypt -binary -pub"</p></li>
</ol></dd>
<dt><a name="3"><b class="cmd">::pki::sign</b> <i class="arg">input</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Digitally sign message <i class="arg">input</i> using the private <i class="arg">key</i>. If <i class="arg">algo</i>
is ommited "sha1" is assumed. Possible values for <i class="arg">algo</i> include
"md5", "sha1", "sha256", and "raw". Specifyin "raw" for <i class="arg">algo</i> will
inhibit the building of an ASN.1 structure to encode which hashing
algorithm was chosen.
The <i class="arg">input</i> should be the plain text, hashing will be performed on it.
The <i class="arg">key</i> should include the private key.</p></dd>
<dt><a name="4"><b class="cmd">::pki::verify</b> <i class="arg">signedmessage</i> <i class="arg">plaintext</i> <i class="arg">key</i> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Verify a digital signature using a public <i class="arg">key</i>. Returns true or false.</p></dd>
<dt><a name="5"><b class="cmd">::pki::key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span> <span class="opt">?<i class="arg">encodePem</i>?</span></a></dt>
<dd><p>Convert a key structure into a serialized PEM (default) or DER encoded private key suitable for other applications. For RSA keys this means PKCS#1.</p></dd>
<dt><a name="6"><b class="cmd">::pki::pkcs::parse_key</b> <i class="arg">key</i> <span class="opt">?<i class="arg">password</i>?</span></a></dt>
<dd><p>Convert a PKCS#1 private <i class="arg">key</i> into a usable key, i.e. one which
can be used as argument for
<b class="cmd">::pki::encrypt</b>,
<b class="cmd">::pki::decrypt</b>,
<b class="cmd">::pki::sign</b>, and
<b class="cmd">::pki::verify</b>.</p></dd>
<dt><a name="7"><b class="cmd">::pki::x509::parse_cert</b> <i class="arg">cert</i></a></dt>
<dd><p>Convert an X.509 certificate to a usable (public) key, i.e. one which
can be used as argument for
<b class="cmd">::pki:encrypt</b>,
<b class="cmd">::pki::decrypt</b>, and
<b class="cmd">::pki::verify</b>.
The <i class="arg">cert</i> argument can be either PEM or DER encoded.</p></dd>
<dt><a name="8"><b class="cmd">::pki::rsa::generate</b> <i class="arg">bitlength</i> <span class="opt">?<i class="arg">exponent</i>?</span></a></dt>
<dd><p>Generate a new RSA key pair, the parts of which can be used as
argument for
<b class="cmd">::pki::encrypt</b>,
<b class="cmd">::pki::decrypt</b>,
<b class="cmd">::pki::sign</b>, and
<b class="cmd">::pki::verify</b>.
The <i class="arg">bitlength</i> argument is the length of the public key modulus.
The <i class="arg">exponent</i> argument should generally not be specified unless
you really know what you are doing.</p></dd>
<dt><a name="9"><b class="cmd">::pki::x509::verify_cert</b> <i class="arg">cert</i> <i class="arg">trustedcerts</i> <span class="opt">?<i class="arg">intermediatecerts</i>?</span></a></dt>
<dd><p>Verify that a trust can be found between the certificate specified in the
<i class="arg">cert</i> argument and one of the certificates specified in the list
of certificates in the <i class="arg">trustedcerts</i> argument. (Eventually the
chain can be through untrusted certificates listed in the <i class="arg">intermediatecerts</i>
argument, but this is currently unimplemented).
The certificates specified in the <i class="arg">cert</i> and <i class="arg">trustedcerts</i> option
should be parsed (from <b class="cmd">::pki::x509::parse_cert</b>).</p></dd>
<dt><a name="10"><b class="cmd">::pki::x509::validate_cert</b> <i class="arg">cert</i> <span class="opt">?<b class="option">-sign_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-encrypt_message</b> <i class="arg">dn_of_signer</i>?</span> <span class="opt">?<b class="option">-sign_cert</b> <i class="arg">dn_to_be_signed</i> <i class="arg">ca_depth</i>?</span> <span class="opt">?<b class="option">-ssl</b> <i class="arg">dn</i>?</span></a></dt>
<dd><p>Validate that a certificate is valid to be used in some capacity. If
multiple options are specified they must all be met for this procedure
to return "true".
Currently, only the <b class="option">-sign_cert</b> option is functional.
Arguments for the <b class="option">-sign_cert</b> option are <i class="arg">dn_to_be_signed</i>
and <i class="arg">ca_depth</i>. The <i class="arg">dn_to_be_signed</i> is the distinguished from
the subject of a certificate to verify that the certificate specified in
the <i class="arg">cert</i> argument can sign. The <i class="arg">ca_depth</i> argument is used to
indicate at which depth the verification should be done at. Some
certificates are limited to how far down the chain they can be used to
verify a given certificate.</p></dd>
<dt><a name="11"><b class="cmd">::pki::pkcs::create_csr</b> <i class="arg">keylist</i> <i class="arg">namelist</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Generate a certificate signing request from a key pair specified in
the <i class="arg">keylist</i> argument.
The <i class="arg">namelist</i> argument is a list of "name" followed by "value"
pairs to encoding as the requested distinguished name in the CSR.
The <i class="arg">encodePem</i> option specifies whether or not the result should
be PEM encoded or DER encoded. A "true" value results in the result
being PEM encoded, while any other value 9results in the the result
being DER encoded. DER encoding is the default.
The <i class="arg">algo</i> argument specifies the hashing algorithm we should use
to sign this certificate signing request with. The default is "sha1".
Other possible values include "md5" and "sha256".</p></dd>
<dt><a name="12"><b class="cmd">::pki::pkcs::parse_csr</b> <i class="arg">csr</i></a></dt>
<dd><p>Parse a Certificate Signing Request. The <i class="arg">csr</i> argument can be
either PEM or DER encoded.</p></dd>
<dt><a name="13"><b class="cmd">::pki::x509::create_cert</b> <i class="arg">signreqlist</i> <i class="arg">cakeylist</i> <i class="arg">serial_number</i> <i class="arg">notBefore</i> <i class="arg">notAfter</i> <i class="arg">isCA</i> <i class="arg">extensions</i> <span class="opt">?<i class="arg">encodePem</i>?</span> <span class="opt">?<i class="arg">algo</i>?</span></a></dt>
<dd><p>Sign a signing request (usually from <b class="cmd">::pki::pkcs::create_csr</b> or
<b class="cmd">::pki::pkcs::parse_csr</b>) with a Certificate Authority (CA) certificate.
The <i class="arg">signreqlist</i> argument should be the parsed signing request.
The <i class="arg">cakeylist</i> argument should be the parsed CA certificate.
The <i class="arg">serial_number</i> argument should be a serial number unique to
this certificate from this certificate authority.
The <i class="arg">notBefore</i> and <i class="arg">notAfter</i> arguments should contain the
time before and after which (respectively) the certificate should
be considered invalid. The time should be encoded as something
<b class="cmd">clock format</b> will accept (i.e., the results of <b class="cmd">clock seconds</b>
and <b class="cmd">clock add</b>).
The <i class="arg">isCA</i> argument is a boolean argumen describing whether or not
the signed certificate should be a a CA certificate. If specified as
true the "id-ce-basicConstraints" extension is added with the arguments
of "critical" being true, "allowCA" being true, and caDepth being
-1 (infinite).
The <i class="arg">extensions</i> argument is a list of extensions and their parameters
that should be encoded into the created certificate. Currently only one
extension is understood ("id-ce-basicConstraints"). It accepts three
arguments <i class="arg">critical</i> <i class="arg">allowCA</i> <i class="arg">caDepth</i>. The <i class="arg">critical</i>
argument to this extension (and any extension) whether or not the
validator should reject the certificate as invalid if it does not
understand the extension (if set to "true") or should ignore the extension
(if set to "false"). The <i class="arg">allowCA</i> argument is used to specify
as a boolean value whether or not we can be used a certificate
authority (CA). The <i class="arg">caDepth</i> argument indicates how many children
CAs can be children of this CA in a depth-wise fashion. A value of "0"
for the <i class="arg">caDepth</i> argument means that this CA cannot sign a CA
certificate and have the result be valid. A value of "-1" indicates
infinite depth.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
</pre>
<pre class="doctools_example">
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Roy Keene</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>rsa</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../aes/aes.html">aes(n)</a>, <a href="../blowfish/blowfish.html">blowfish(n)</a>, <a href="../des/des.html">des(n)</a>, <a href="../md5/md5.html">md5(n)</a>, <a href="../sha1/sha1.html">sha1(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cipher">cipher</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#public_key_cipher">public key cipher</a>, <a href="../../../../index.html#rsa">rsa</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
|
<div class='fossil-doc' data-title='pluginmgr - Plugin management'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pluginmgr(n) 0.3 tcllib "Plugin management"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pluginmgr - Manage a plugin</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PUBLIC API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">PACKAGE COMMANDS</a></li>
<li class="doctools_subsection"><a href="#subsection2">OBJECT COMMAND</a></li>
<li class="doctools_subsection"><a href="#subsection3">OBJECT METHODS</a></li>
<li class="doctools_subsection"><a href="#subsection4">OBJECT CONFIGURATION</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">pluginmgr <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pluginmgr</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::pluginmgr::paths</b> <i class="arg">objectName</i> <i class="arg">name</i>...</a></li>
<li><a href="#3"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">clone</b></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">configure</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">do</b> <i class="arg">arg</i>...</a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">interpreter</b></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">plugin</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">load</b> <i class="arg">string</i></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">unload</b></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">list</b></a></li>
<li><a href="#16"><i class="arg">objectName</i> <b class="method">path</b> <i class="arg">path</i></a></li>
<li><a href="#17"><i class="arg">objectName</i> <b class="method">paths</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands and objects for the generic management
of plugins which can be loaded into an application.</p>
<p>To avoid the implementation of yet another system to locate Tcl code
the system provides by this package is built on top of the regular
package management system. Each plugin is considered as a package and
a simple invokation of <b class="cmd">package require</b> is enough to locate and
load it, if it exists. The only time we will need additional paths is
when a plugin manager is part of a wrapped application and has to be
able to search for plugins existing outside of that application. For
this situation the package provides a command to create a general set
of such paths based on names for the plugin manager and/or application
in question.</p>
<p>The main contribution of this package is a generic framework which
allows the easy declaration of</p>
<ol class="doctools_enumerated">
<li><p>How to translate a plugin name to the name of the package implementing
it, and vice versa.</p></li>
<li><p>The list of commands a plugin has to provide as API, and also of more
complex checks as code.</p></li>
<li><p>The list of commands expected by the plugin from the environment.</p></li>
</ol>
<p>This then allows the easy generation of plugin managers customized to
particular types of plugins for an application.</p>
<p>It should be noted that all plugin code is considered untrusted and
will always be executed within a safe interpreter. The interpreter is
enabled enough to allow plugins the loading of all additional packages
they may need.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PUBLIC API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">PACKAGE COMMANDS</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pluginmgr</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">option value</i>...?</span></a></dt>
<dd><p>This command creates a new plugin manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">OBJECT COMMAND</a></span>
and <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p>
<p>The options and their values coming after the name of the object are
used to set the initial configuration of the mamager object,
specifying the applicable plugins and their API.</p></dd>
<dt><a name="2"><b class="cmd">::pluginmgr::paths</b> <i class="arg">objectName</i> <i class="arg">name</i>...</a></dt>
<dd><p>This utility command adds a set of paths to the specified object,
based on the given <i class="arg">name</i>s.
It will search for:</p>
<ol class="doctools_enumerated">
<li><p>The environment variable <b class="variable"><i class="arg">name</i>_PLUGINS</b>. Its contents will
be interpreted as a list of package paths. The entries have to be
separated by either <b class="const">:</b> (unix) or <b class="const">;</b> (windows).</p>
<p>The name will be converted to upper-case letters.</p></li>
<li><p>The registry entry "HKEY_LOCAL_MACHINE\SOFTWARE\<i class="arg">name</i>\PLUGINS".
Its contents will be interpreted as a list of package paths. The
entries have to be separated by <b class="const">;</b>. This item is considered
only when on Windows (tm).</p>
<p>The casing of letters is not changed.</p></li>
<li><p>The registry entry "HKEY_CURRENT_USER\SOFTWARE\<i class="arg">name</i>\PLUGINS".
Its contents will be interpreted as a list of package paths. The
entries have to be separated by <b class="const">;</b>. This item is considered
only when on Windows (tm).</p>
<p>The casing of letters is not changed.</p></li>
<li><p>The directory "<b class="file">~/.<i class="arg">name</i>/plugin</b>".</p></li>
<li><p>The directory "<b class="file">~/.<i class="arg">name</i>/plugins</b>".</p>
<p>The casing of letters is not changed.</p></li>
</ol>
<p>and add all the paths found that way to the list of package paths
maintained by the object.</p>
<p>If <i class="arg">name</i> is namespaced each item in the list will be repeated per
prefix of <i class="arg">name</i>, with conversion of :-sequences into the proper
separator (underscore for environment variables, backslash for
registry entries, and / for directories).</p>
<p>Examples:</p>
<pre class="doctools_example">
::pluginmgr::paths ::obj docidx
=> env DOCIDX_PLUGINS
reg HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS
reg HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS
path ~/.docidx/plugins
::pluginmgr::paths ::obj doctools::idx
=> env DOCTOOLS_PLUGINS
env DOCTOOLS_IDX_PLUGINS
reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS
reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS
reg HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS
reg HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS
path ~/.doctools/plugin
path ~/.doctools/idx/plugin
</pre>
</dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">OBJECT COMMAND</a></h3>
<p>All commands created by the command <b class="cmd">::pluginmgr</b> (See section
<span class="sectref"><a href="#subsection1">PACKAGE COMMANDS</a></span>) have the following general form and may
be used to invoke various operations on their plugin manager object.</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the exact
behavior of the command. See section <span class="sectref"><a href="#subsection3">OBJECT METHODS</a></span> for
the detailed specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">OBJECT METHODS</a></h3>
<dl class="doctools_definitions">
<dt><a name="4"><i class="arg">objectName</i> <b class="method">clone</b></a></dt>
<dd><p>This method creates a new plugin management object and returns the
associated object command. The generated object is a clone of the
object the method was invoked on. I.e. the new object will have the
same configuration as the current object. With regard to state, if the
current object has a plugin loaded then this plugin and all associated
state is moved to the generated clone and the current object is reset
into the base state (no plugin loaded). In this manner a configured
plugin manager is also a factory for loaded plugins.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">configure</b></a></dt>
<dd><p>The method returns a list of all known options and their current
values when called without any arguments.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>The method behaves like the method <b class="method">cget</b> when called with a
single argument and returns the value of the option specified by said
argument.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">configure</b> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>The method reconfigures the specified <b class="option">option</b>s of the object,
setting them to the associated <i class="arg">value</i>s, when called with an even
number of arguments, at least two.</p>
<p>The legal options are described in the section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">cget</b> <b class="option">-option</b></a></dt>
<dd><p>This method expects a legal configuration option as argument and will
return the current value of that option for the object the method was
invoked for.</p>
<p>The legal configuration options are described in section
<span class="sectref"><a href="#subsection4">OBJECT CONFIGURATION</a></span>.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">do</b> <i class="arg">arg</i>...</a></dt>
<dd><p>This method interprets its list of arguments as the words of a command
and invokes this command in the execution context of the plugin.
The result of the invoked command is made the result of the method.
The call will fail with an error if no valid plugin has been loaded
into the manager object.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">interpreter</b></a></dt>
<dd><p>This method returns the handle of the safe interpreter the current
plugin is loaded into. An empty string as return value signals that
the manager currently has no valid plugin loaded.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">plugin</b></a></dt>
<dd><p>This method returns the name of the plugin currently loaded. An empty
string as return value signals that the manager currently has no valid
plugin loaded.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">load</b> <i class="arg">string</i></a></dt>
<dd><p>This method loads, validates, and initializes a named plugin into the
manager object.</p>
<p>The algorithm to locate and load the plugin employed is:</p>
<ol class="doctools_enumerated">
<li><p>If the <i class="arg">string</i> contains the path to an existing file then this
file is taken as the implementation of the plugin.</p></li>
<li><p>Otherwise the plugin name is translated into a package name via the value
of the option <b class="option">-pattern</b> and then loaded through the
regular package management.</p></li>
<li><p>The load fails.</p></li>
</ol>
<p>The algorithm to validate and initialize the loaded code is:</p>
<ol class="doctools_enumerated">
<li><p>If the option <b class="option">-api</b> is non-empty introspection commands are
used to ascertain that the plugin provides the listed commands.</p></li>
<li><p>If the option <b class="option">-check</b> is non-empty the specified command
prefix is called.</p></li>
<li><p>If either of the above fails the candidate plugin is unloaded again</p></li>
<li><p>Otherwise all the commands specified via the option
<b class="option">-cmds</b> are installed in the plugin.</p></li>
</ol>
<p>A previously loaded plugin is discarded, but only if the new plugin
was found and sucessfully validated and initialized. Note that there
will be no intereference between old and new plugin as both will be
put into separate safe interpreters.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">unload</b></a></dt>
<dd><p>This method unloads the currently loaded plugin. It returns the empty
string. The call will be silently ignored if no plugin is loaded at
all.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">list</b></a></dt>
<dd><p>This method uses the contents of the option <b class="option">-pattern</b> to find
all packages which can be plugins under the purview of this manager
object. It translates their names into plugin names and returns a list
containing them.</p></dd>
<dt><a name="16"><i class="arg">objectName</i> <b class="method">path</b> <i class="arg">path</i></a></dt>
<dd><p>This methods adds the specified <i class="arg">path</i> to the list of additional
package paths to look at when searching for a plugin. It returns the
empty string. Duplicate paths are ignored, i.e. each path is added
only once. Paths are made absolute, but are not normalized.</p></dd>
<dt><a name="17"><i class="arg">objectName</i> <b class="method">paths</b></a></dt>
<dd><p>This method returns a list containing all additional paths which have
been added to the plugin manager object since its creation.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">OBJECT CONFIGURATION</a></h3>
<p>All plugin manager objects understand the following configuration options:</p>
<dl class="doctools_options">
<dt><b class="option">-pattern</b> <i class="arg">string</i></dt>
<dd><p>The value of this option is a glob pattern which has to contain
exactly one '*'-operator. All packages whose names match this pattern
are the plugins recognized by the manager object. And vice versa, the
replacement of the '*'-operator with a plugin name will yield the name
of the package implementing that plugin.</p>
<p>This option has no default, except if option <b class="option">-name</b> was set.
It has to be set before attempting to load a plugin, either directly,
or through option <b class="option">-name</b>.</p></dd>
<dt><b class="option">-api</b> <i class="arg">list</i></dt>
<dd><p>The value of this option is a list of command names, and any plugin
loaded has to provide these commands. Names which are not fully
qualified are considered to be rooted in the global namespace.
If empty no expectations are made on the plugin. The default value is
the empty list.</p></dd>
<dt><b class="option">-check</b> <i class="arg">cmdprefix</i></dt>
<dd><p>The value of this option is interpreted as a command prefix.
Its purpose is to perform complex checks on a loaded plugin package to
validate it, which go beyond a simple list of provided commands.</p>
<p>It is called with the manager object command as the only argument and
has to return a boolean value. A value of <b class="const">true</b> will be
interpreted to mean that the candidate plugin passed the test.
The call will happen if and only if the candidate plugin already
passed the basic API check specified through the option <b class="option">-api</b>.</p>
<p>The default value is the empty list, which causes the manager object
to suppress the call and to assume the candidate plugin passes.</p></dd>
<dt><b class="option">-cmds</b> <i class="arg">dict</i></dt>
<dd><p>The value of this option is a dictionary. It specifies the commands
which will be made available to the plugin (as keys), and the trusted
commands in the environment which implement them (as values).
The trusted commands will be executed in the interpreter specified by
the option <b class="option">-cmdip</b>.
The default value is the empty dictionary.</p></dd>
<dt><b class="option">-cmdip</b> <i class="arg">ipspec</i></dt>
<dd><p>The value of this option is the path of the interpreter where the
trusted commands given to the plugin will be executed in.
The default is the empty string, referring to the current interpreter.</p></dd>
<dt><b class="option">-setup</b> <i class="arg">cmdprefix</i></dt>
<dd><p>The value of this option is interpreted as a command prefix.</p>
<p>It is called whenever a new safe interpreter for a plugin has been
created, but before a plugin is loaded. It is provided with the
manager object command and the interpreter handle as its only
arguments. Any return value will be ignored.</p>
<p>Its purpose is give a user of the plugin management the ability to
define commands, packages, etc. a chosen plugin may need while being
loaded.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pluginmgr</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#plugin_management">plugin management</a>, <a href="../../../../index.html#plugin_search">plugin search</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/png/png.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
<div class='fossil-doc' data-title='png - Image manipulation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">png(n) 0.3 tcllib "Image manipulation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>png - PNG querying and manipulation of meta data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">crc32</b></li>
<li>package require <b class="pkgname">png <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::png::validate</b> <i class="arg">file</i></a></li>
<li><a href="#2"><b class="cmd">::png::isPNG</b> <i class="arg">file</i></a></li>
<li><a href="#3"><b class="cmd">::png::imageInfo</b> <i class="arg">file</i></a></li>
<li><a href="#4"><b class="cmd">::png::getTimestamp</b> <i class="arg">file</i></a></li>
<li><a href="#5"><b class="cmd">::png::setTimestamp</b> <i class="arg">file</i> <i class="arg">time</i></a></li>
<li><a href="#6"><b class="cmd">::png::getComments</b> <i class="arg">file</i></a></li>
<li><a href="#7"><b class="cmd">::png::removeComments</b> <i class="arg">file</i></a></li>
<li><a href="#8"><b class="cmd">::png::addComment</b> <i class="arg">file</i> <i class="arg">keyword</i> <i class="arg">text</i></a></li>
<li><a href="#9"><b class="cmd">::png::addComment</b> <i class="arg">file</i> <i class="arg">keyword</i> <i class="arg">lang</i> <i class="arg">keyword2</i> <i class="arg">text</i></a></li>
<li><a href="#10"><b class="cmd">::png::getPixelDimension</b> <i class="arg">file</i></a></li>
<li><a href="#11"><b class="cmd">::png::image</b> <i class="arg">file</i></a></li>
<li><a href="#12"><b class="cmd">::png::write</b> <i class="arg">file</i> <i class="arg">data</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to query and modify PNG images. PNG
stands for <i class="term">Portable Network Graphics</i> and is specified at
<a href="http://www.libpng.org/pub/png/spec/1.2">http://www.libpng.org/pub/png/spec/1.2</a>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::png::validate</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a value indicating if <i class="arg">file</i> is a valid PNG file. The file
is checked for PNG signature, each chunks checksum is verified,
existence of a data chunk is verified, first chunk is checked for
header, last chunk is checked for ending. Things <em>not</em> checked
for are: validity of values within a chunk, multiple header chunks,
noncontiguous data chunks, end chunk before actual eof. This procedure
can take lots of time.</p>
<p>Possible return values:</p>
<dl class="doctools_definitions">
<dt>OK</dt>
<dd><p>File is a valid PNG file.</p></dd>
<dt>SIG</dt>
<dd><p>no/broken PNG signature.</p></dd>
<dt>BADLEN</dt>
<dd><p>corrupt chunk length.</p></dd>
<dt>EOF</dt>
<dd><p>premature end of file.</p></dd>
<dt>NOHDR</dt>
<dd><p>missing header chunk.</p></dd>
<dt>CKSUM</dt>
<dd><p>crc mismatch.</p></dd>
<dt>NODATA</dt>
<dd><p>missing data chunk(s).</p></dd>
<dt>NOEND</dt>
<dd><p>missing end marker.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::png::isPNG</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a boolean value indicating if the file <i class="arg">file</i> starts with
a PNG signature. This is a much faster and less intensive check than
<b class="cmd">::png::validate</b> as it does not check if the PNG data is valid.</p></dd>
<dt><a name="3"><b class="cmd">::png::imageInfo</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a dictionary with keys <b class="const">width</b>, <b class="const">height</b>,
<b class="const">depth</b>, <b class="const">color</b>, <b class="const">compression</b>, <b class="const">filter</b>, and
<b class="const">interlace</b>. The values are the associated properties of the PNG
image in <i class="arg">file</i>.
Throws an error if file is not a PNG image, or if the checksum of the
header is invalid. For information on interpreting the values for the
returned properties see
<a href="http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html">http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html</a>.</p></dd>
<dt><a name="4"><b class="cmd">::png::getTimestamp</b> <i class="arg">file</i></a></dt>
<dd><p>Returns the epoch time if a timestamp chunk is found in the PNG image
contained in the <i class="arg">file</i>, otherwise returns the empty string. Does
not attempt to verify the checksum of the timestamp chunk.
Throws an error if the <i class="arg">file</i> is not a valid PNG image.</p></dd>
<dt><a name="5"><b class="cmd">::png::setTimestamp</b> <i class="arg">file</i> <i class="arg">time</i></a></dt>
<dd><p>Writes a new timestamp to the <i class="arg">file</i>, either replacing the old
timestamp, or adding one just before the data chunks if there was no
previous timestamp. <i class="arg">time</i> is the new time in the gmt epoch
format.
Throws an error if <i class="arg">file</i> is not a valid PNG image.</p></dd>
<dt><a name="6"><b class="cmd">::png::getComments</b> <i class="arg">file</i></a></dt>
<dd><p>Currently supports only uncompressed comments. Does not attempt to
verify the checksums of the comment chunks. Returns a list where each
element is a comment. Each comment is itself a list. The list for a
plain text comment consists of 2 elements: the human readable keyword,
and the text data. A unicode (international) comment consists of 4
elements: the human readable keyword, the language identifier, the
translated keyword, and the unicode text data.
Throws an error if <i class="arg">file</i> is not a valid PNG image.</p></dd>
<dt><a name="7"><b class="cmd">::png::removeComments</b> <i class="arg">file</i></a></dt>
<dd><p>Removes all comments from the PNG image in <i class="arg">file</i>. Beware - This
uses memory equal to the file size minus comments, to hold the
intermediate result.
Throws an error if <i class="arg">file</i> is not a valid PNG image.</p></dd>
<dt><a name="8"><b class="cmd">::png::addComment</b> <i class="arg">file</i> <i class="arg">keyword</i> <i class="arg">text</i></a></dt>
<dd><p>Adds a plain <i class="arg">text</i> comment to the PNG image in <i class="arg">file</i>, just
before the first data chunk. Will throw an error if no data chunk is
found. <i class="arg">keyword</i> has to be less than 80 characters long to conform
to the PNG specification.</p></dd>
<dt><a name="9"><b class="cmd">::png::addComment</b> <i class="arg">file</i> <i class="arg">keyword</i> <i class="arg">lang</i> <i class="arg">keyword2</i> <i class="arg">text</i></a></dt>
<dd><p>Adds a unicode (international) comment to the PNG image in <i class="arg">file</i>,
just before the first data chunk. Will throw an error if no data chunk
is found. <i class="arg">keyword</i> has to be less than 80 characters long to
conform to the PNG specification. <i class="arg">keyword2</i> is the translated
<i class="arg">keyword</i>, in the language specified by the language identifier
<i class="arg">lang</i>.</p></dd>
<dt><a name="10"><b class="cmd">::png::getPixelDimension</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a dictionary with keys <b class="const">ppux</b>, <b class="const">ppuy</b> and
<b class="const">unit</b> if the information is present. Otherwise, it returns the empty
string.</p>
<p>The values of <b class="const">ppux</b> and <b class="const">ppuy</b> return the pixel
per unit value in X or Y direction.</p>
<p>The allowed values for key <b class="const">unit</b> are <b class="const">meter</b> and
<b class="const">unknown</b>. In the case of meter, the dpi value can be calculated
by multiplying with the conversion factor <b class="const">0.0254</b>.</p></dd>
<dt><a name="11"><b class="cmd">::png::image</b> <i class="arg">file</i></a></dt>
<dd><p>Given a PNG file returns the image in the list of scanlines format used by Tk_GetColor.</p></dd>
<dt><a name="12"><b class="cmd">::png::write</b> <i class="arg">file</i> <i class="arg">data</i></a></dt>
<dd><p>Takes a list of scanlines in the Tk_GetColor format and writes the represented image
to <i class="arg">file</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>png</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#comment">comment</a>, <a href="../../../../index.html#image">image</a>, <a href="../../../../index.html#png">png</a>, <a href="../../../../index.html#timestamp">timestamp</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File formats</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004, Code: Aaron Faupell <[email protected]><br>
Copyright © 2004, Doc: Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pop3/pop3.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
|
<div class='fossil-doc' data-title='pop3 - Tcl POP3 Client Library'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pop3(n) 1.9 tcllib "Tcl POP3 Client Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pop3 - Tcl client for POP3 email protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section3">API</a></li>
<li class="doctools_section"><a href="#section4">Secure mail transfer</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">pop3 <span class="opt">?1.9?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pop3::open</b> <span class="opt">?<b class="option">-msex</b> 0|1?</span> <span class="opt">?<b class="option">-retr-mode</b> retr|list|slow?</span> <span class="opt">?<b class="option">-socketcmd</b> cmdprefix?</span> <span class="opt">?<b class="option">-stls</b> 0|1?</span> <span class="opt">?<b class="option">-tls-callback</b> stls-callback-command?</span> <i class="arg">host username password</i> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::pop3::config</b> <i class="arg">chan</i></a></li>
<li><a href="#3"><b class="cmd">::pop3::status</b> <i class="arg">chan</i></a></li>
<li><a href="#4"><b class="cmd">::pop3::last</b> <i class="arg">chan</i></a></li>
<li><a href="#5"><b class="cmd">::pop3::retrieve</b> <i class="arg">chan startIndex</i> <span class="opt">?<i class="arg">endIndex</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::pop3::delete</b> <i class="arg">chan startIndex</i> <span class="opt">?<i class="arg">endIndex</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::pop3::list</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">msg</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::pop3::top</b> <i class="arg">chan</i> <i class="arg">msg</i> <i class="arg">n</i></a></li>
<li><a href="#9"><b class="cmd">::pop3::uidl</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">msg</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::pop3::capa</b> <i class="arg">chan</i></a></li>
<li><a href="#11"><b class="cmd">::pop3::close</b> <i class="arg">chan</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">pop3</b> package provides a simple Tcl-only client library
for the POP3 email protocol as specified in
<a href="http://www.rfc-editor.org/rfc/rfc1939.txt">RFC 1939</a>.
It works by opening the standard POP3 socket on the server,
transmitting the username and password, then providing a Tcl API to
access the POP3 protocol commands. All server errors are returned as
Tcl errors (thrown) which must be caught with the Tcl <b class="cmd">catch</b>
command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pop3::open</b> <span class="opt">?<b class="option">-msex</b> 0|1?</span> <span class="opt">?<b class="option">-retr-mode</b> retr|list|slow?</span> <span class="opt">?<b class="option">-socketcmd</b> cmdprefix?</span> <span class="opt">?<b class="option">-stls</b> 0|1?</span> <span class="opt">?<b class="option">-tls-callback</b> stls-callback-command?</span> <i class="arg">host username password</i> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Open a socket connection to the server specified by <i class="arg">host</i>,
transmit the <i class="arg">username</i> and <i class="arg">password</i> as login information to
the server. The default port number is <b class="const">110</b>, which can be
overridden using the optional <i class="arg">port</i> argument. The return value
is a channel used by all of the other ::pop3 functions.</p>
<p>The command recognizes three options</p>
<dl class="doctools_options">
<dt><b class="option">-msex</b> boolean</dt>
<dd><p>Setting this option tells the package that the server we are talking
to is an MS Exchange server (which has some oddities we have to work
around). The default is <b class="const">False</b>.</p></dd>
<dt><b class="option">-retr-mode</b> retr|list|slow</dt>
<dd><p>The retrieval mode determines how exactly messages are read from the
server.
The allowed values are <b class="const">retr</b>, <b class="const">list</b> and <b class="const">slow</b>.
The default is <b class="const">retr</b>. See <b class="cmd">::pop3::retrieve</b> for more
information.</p></dd>
<dt><b class="option">-socketcmd</b> cmdprefix</dt>
<dd><p>This option allows the user to overide the use of the builtin
<b class="cmd"><a href="../../../../index.html#socket">socket</a></b> command with any API-compatible command. The envisioned
main use is the securing of the new connection via SSL, through the
specification of the command <b class="cmd">tls::socket</b>. This command is
specially recognized as well, changing the default port of the
connection to <b class="const">995</b>.</p></dd>
<dt><b class="option">-stls</b> boolean</dt>
<dd><p>Setting this option tells the package to secure the connection using
SSL or TLS. It performs STARTTLS as described in IETF RFC 2595, it
first opens a normal, unencrypted connection and then negotiates a
SSLv3 or TLSv1 connection. If the connection cannot be secured, the
connection will be closed and an error will be returned</p></dd>
<dt><b class="option">-tls-callback</b> stls-callback-command</dt>
<dd><p>This option allows the user to overide the <b class="cmd">tls::callback</b> used during
the <b class="const">-stls</b> SSL/TLS handshake. See the TLS manual for details on how
to implement this callback.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::pop3::config</b> <i class="arg">chan</i></a></dt>
<dd><p>Returns the configuration of the pop3 connection identified by the
channel handle <i class="arg">chan</i> as a serialized array.</p></dd>
<dt><a name="3"><b class="cmd">::pop3::status</b> <i class="arg">chan</i></a></dt>
<dd><p>Query the server for the status of the mail spool. The status is
returned as a list containing two elements, the first is the number of
email messages on the server and the second is the size (in octets, 8
bit blocks) of the entire mail spool.</p></dd>
<dt><a name="4"><b class="cmd">::pop3::last</b> <i class="arg">chan</i></a></dt>
<dd><p>Query the server for the last email message read from the spool. This
value includes all messages read from all clients connecting to the
login account. This command may not be supported by the email server,
in which case the server may return 0 or an error.</p></dd>
<dt><a name="5"><b class="cmd">::pop3::retrieve</b> <i class="arg">chan startIndex</i> <span class="opt">?<i class="arg">endIndex</i>?</span></a></dt>
<dd><p>Retrieve a range of messages from the server. If the <i class="arg">endIndex</i>
is not specified, only one message will be retrieved. The return
value is a list containing each message as a separate element. See
the <i class="arg">startIndex</i> and <i class="arg">endIndex</i> descriptions below.</p>
<p>The retrieval mode determines how exactly messages are read from the
server. The mode <b class="const">retr</b> assumes that the RETR command delivers
the size of the message as part of the command status and uses this to
read the message efficiently. In mode <b class="const">list</b> RETR does not
deliver the size, but the LIST command does and we use this to
retrieve the message size before the actual retrieval, which can then
be done efficiently. In the last mode, <b class="const">slow</b>, the system is
unable to obtain the size of the message to retrieve in any manner and
falls back to reading the message from the server line by line.</p>
<p>It should also be noted that the system checks upon the configured
mode and falls back to the slower modes if the above assumptions are
not true.</p></dd>
<dt><a name="6"><b class="cmd">::pop3::delete</b> <i class="arg">chan startIndex</i> <span class="opt">?<i class="arg">endIndex</i>?</span></a></dt>
<dd><p>Delete a range of messages from the server. If the <i class="arg">endIndex</i> is
not specified, only one message will be deleted. Note, the indices
are not reordered on the server, so if you delete message 1, then the
first message in the queue is message 2 (message index 1 is no longer
valid). See the <i class="arg">startIndex</i> and <i class="arg">endIndex</i> descriptions
below.</p>
<dl class="doctools_definitions">
<dt><i class="arg">startIndex</i></dt>
<dd><p>The <i class="arg">startIndex</i> may be an index of a specific message starting
with the index 1, or it have any of the following values:</p>
<dl class="doctools_definitions">
<dt><b class="const">start</b></dt>
<dd><p>This is a logical value for the first message in the spool, equivalent
to the value 1.</p></dd>
<dt><b class="const">next</b></dt>
<dd><p>The message immediately following the last message read, see
<b class="cmd">::pop3::last</b>.</p></dd>
<dt><b class="const">end</b></dt>
<dd><p>The most recent message in the spool (the end of the spool). This is
useful to retrieve only the most recent message.</p></dd>
</dl></dd>
<dt><i class="arg">endIndex</i></dt>
<dd><p>The <i class="arg">endIndex</i> is an optional parameter and defaults to the value
"-1", which indicates to only retrieve the one message specified by
<i class="arg">startIndex</i>. If specified, it may be an index of a specific
message starting with the index "1", or it may have any of the
following values:</p>
<dl class="doctools_definitions">
<dt><b class="const">last</b></dt>
<dd><p>The message is the last message read by a POP3 client, see
<b class="cmd">::pop3::last</b>.</p></dd>
<dt><b class="const">end</b></dt>
<dd><p>The most recent message in the spool (the end of the spool).</p></dd>
</dl></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::pop3::list</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">msg</i>?</span></a></dt>
<dd><p>Returns the scan listing of the mailbox. If parameter <i class="arg">msg</i> is
given, then the listing only for that message is returned.</p></dd>
<dt><a name="8"><b class="cmd">::pop3::top</b> <i class="arg">chan</i> <i class="arg">msg</i> <i class="arg">n</i></a></dt>
<dd><p>Optional POP3 command, not all servers may support this.
<b class="cmd">::pop3::top</b> retrieves headers of a message, specified by
parameter <i class="arg">msg</i>, and number of <i class="arg">n</i> lines from the message
body.</p></dd>
<dt><a name="9"><b class="cmd">::pop3::uidl</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">msg</i>?</span></a></dt>
<dd><p>Optional POP3 command, not all servers may support this.
<b class="cmd">::pop3::uidl</b> returns the uid listing of the mailbox. If the
parameter <i class="arg">msg</i> is specified, then the listing only for that
message is returned.</p></dd>
<dt><a name="10"><b class="cmd">::pop3::capa</b> <i class="arg">chan</i></a></dt>
<dd><p>Optional POP3 command, not all servers may support this.
<b class="cmd">::pop3::capa</b> returns a list of the capabilities of the server.
TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities.
See IETF RFC 2449.</p></dd>
<dt><a name="11"><b class="cmd">::pop3::close</b> <i class="arg">chan</i></a></dt>
<dd><p>Gracefully close the connect after sending a POP3 QUIT command down
the socket.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Secure mail transfer</a></h2>
<p>A pop3 connection can be secured with SSL/TLS by requiring the package
<b class="package"><a href="../../../../index.html#tls">TLS</a></b> and then using either the option <b class="option">-socketcmd</b> or
the option <b class="option">-stls</b> of the command <b class="cmd">pop3::open</b>.
The first method, option <b class="option">-socketcmd</b>, will force the use
of the <b class="cmd">tls::socket</b> command when opening the connection. This is
suitable for POP3 servers which expect SSL connections only. These will
generally be listening on port 995.</p>
<pre class="doctools_example">
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured pop3 channel
pop3::open -socketcmd tls::socket \\
$thehost $theuser $thepassword
...
</pre>
<p>The second method, option <b class="option">-stls</b>, will connect to the standard POP3
port and then perform an STARTTLS handshake. This will only work for POP3
servers which have this capability. The package will confirm that the
server supports STARTTLS and the handshake was performed correctly before
proceeding with authentication.</p>
<pre class="doctools_example">
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create secured pop3 channel
pop3::open -stls 1 \\
$thehost $theuser $thepassword
...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pop3</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#email">email</a>, <a href="../../../../index.html#mail">mail</a>, <a href="../../../../index.html#pop">pop</a>, <a href="../../../../index.html#pop3">pop3</a>, <a href="../../../../index.html#rfc_1939">rfc 1939</a>, <a href="../../../../index.html#secure">secure</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pop3d/pop3d.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
|
<div class='fossil-doc' data-title='pop3d - Tcl POP3 Server Package'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pop3d(n) 1.1.0 tcllib "Tcl POP3 Server Package"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pop3d - Tcl POP3 server implementation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Options</a></li>
<li class="doctools_section"><a href="#section3">Authentication</a></li>
<li class="doctools_section"><a href="#section4">Mailboxes</a></li>
<li class="doctools_section"><a href="#section5">Secure mail transfer</a></li>
<li class="doctools_section"><a href="#section6">References</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">pop3d <span class="opt">?1.1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pop3d::new</b> <span class="opt">?<i class="arg">serverName</i>?</span></a></li>
<li><a href="#2"><b class="cmd">serverName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">serverName</i> <b class="method">up</b></a></li>
<li><a href="#4"><i class="arg">serverName</i> <b class="method">down</b></a></li>
<li><a href="#5"><i class="arg">serverName</i> <b class="method">destroy</b> <span class="opt">?<i class="arg">mode</i>?</span></a></li>
<li><a href="#6"><i class="arg">serverName</i> <b class="method">configure</b></a></li>
<li><a href="#7"><i class="arg">serverName</i> <b class="method">configure</b> <i class="arg">-option</i></a></li>
<li><a href="#8"><i class="arg">serverName</i> <b class="method">configure</b> <i class="arg">-option value</i>...</a></li>
<li><a href="#9"><i class="arg">serverName</i> <b class="method">cget</b> <i class="arg">-option</i></a></li>
<li><a href="#10"><i class="arg">serverName</i> <b class="method">conn</b> list</a></li>
<li><a href="#11"><i class="arg">serverName</i> <b class="method">conn</b> state <i class="arg">id</i></a></li>
<li><a href="#12"><i class="arg">authCmd</i> <b class="method">exists</b> <i class="arg">name</i></a></li>
<li><a href="#13"><i class="arg">authCmd</i> <b class="method">lookup</b> <i class="arg">name</i></a></li>
<li><a href="#14"><i class="arg">storageCmd</i> <b class="method">dele</b> <i class="arg">mbox</i> <i class="arg">msgList</i></a></li>
<li><a href="#15"><i class="arg">storageCmd</i> <b class="method">lock</b> <i class="arg">mbox</i></a></li>
<li><a href="#16"><i class="arg">storageCmd</i> <b class="method">unlock</b> <i class="arg">mbox</i></a></li>
<li><a href="#17"><i class="arg">storageCmd</i> <b class="method">size</b> <i class="arg">mbox</i> <span class="opt">?<i class="arg">msgId</i>?</span></a></li>
<li><a href="#18"><i class="arg">storageCmd</i> <b class="method">stat</b> <i class="arg">mbox</i></a></li>
<li><a href="#19"><i class="arg">storageCmd</i> <b class="method">get</b> <i class="arg">mbox</i> <i class="arg">msgId</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pop3d::new</b> <span class="opt">?<i class="arg">serverName</i>?</span></a></dt>
<dd><p>This command creates a new server object with an associated global Tcl
command whose name is <i class="arg">serverName</i>.</p></dd>
</dl>
<p>The command <b class="cmd">serverName</b> may be used to invoke various operations
on the server. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">serverName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>A pop3 server can be started on any port the caller has permission for
from the operating system. The default port will be 110, which is the
port defined by the standard specified in
RFC 1939 (<a href="http://www.rfc-editor.org/rfc/rfc1939.txt">http://www.rfc-editor.org/rfc/rfc1939.txt</a>).
After creating, configuring and starting a the server object will
listen for and accept connections on that port and handle them
according to the POP3 protocol.</p>
<p><em>Note:</em> The server provided by this module will handle only the
basic protocol by itself. For the higher levels of user authentication
and handling of the actual mailbox contents callbacks will be invoked.</p>
<p>The following commands are possible for server objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">serverName</i> <b class="method">up</b></a></dt>
<dd><p>After this call the server will listen for connections on its configured port.</p></dd>
<dt><a name="4"><i class="arg">serverName</i> <b class="method">down</b></a></dt>
<dd><p>After this call the server will stop listening for connections. This
does not affect existing connections.</p></dd>
<dt><a name="5"><i class="arg">serverName</i> <b class="method">destroy</b> <span class="opt">?<i class="arg">mode</i>?</span></a></dt>
<dd><p>Destroys the server object. Currently open connections are handled
depending on the chosen mode.
The provided <i class="arg">mode</i>s are:</p>
<dl class="doctools_definitions">
<dt><b class="const">kill</b></dt>
<dd><p>Destroys the server immediately, and forcefully closes all currently
open connections. This is the default mode.</p></dd>
<dt><b class="const">defer</b></dt>
<dd><p>Stops the server from accepting new connections and will actually
destroy it only after the last of the currently open connections for
the server is closed.</p></dd>
</dl></dd>
<dt><a name="6"><i class="arg">serverName</i> <b class="method">configure</b></a></dt>
<dd><p>Returns a list containing all options and their current values in a
format suitable for use by the command <b class="cmd">array set</b>. The options
themselves are described in section <span class="sectref"><a href="#section2">Options</a></span>.</p></dd>
<dt><a name="7"><i class="arg">serverName</i> <b class="method">configure</b> <i class="arg">-option</i></a></dt>
<dd><p>Returns the current value of the specified option. This is an alias
for the method <b class="method">cget</b>. The options themselves are described in
section <span class="sectref"><a href="#section2">Options</a></span>.</p></dd>
<dt><a name="8"><i class="arg">serverName</i> <b class="method">configure</b> <i class="arg">-option value</i>...</a></dt>
<dd><p>Sets the specified option to the provided value. The options
themselves are described in section <span class="sectref"><a href="#section2">Options</a></span>.</p></dd>
<dt><a name="9"><i class="arg">serverName</i> <b class="method">cget</b> <i class="arg">-option</i></a></dt>
<dd><p>Returns the current value of the specified option. The options
themselves are described in section <span class="sectref"><a href="#section2">Options</a></span>.</p></dd>
<dt><a name="10"><i class="arg">serverName</i> <b class="method">conn</b> list</a></dt>
<dd><p>Returns a list containing the ids of all connections currently open.</p></dd>
<dt><a name="11"><i class="arg">serverName</i> <b class="method">conn</b> state <i class="arg">id</i></a></dt>
<dd><p>Returns a list suitable for [<b class="cmd">array set</b>] containing the
state of the connection referenced by <i class="arg">id</i>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Options</a></h2>
<p>The following options are available to pop3 server objects.</p>
<dl class="doctools_definitions">
<dt><b class="option">-port</b> <i class="arg">port</i></dt>
<dd><p>Defines the <i class="arg">port</i> to listen on for new connections. Default is
110. This option is a bit special. If <i class="arg">port</i> is set to "0" the
server, or rather the operating system, will select a free port on its
own. When querying <b class="option">-port</b> the id of this chosen port will be
returned. Changing the port while the server is up will neither change
the returned value, nor will it change on which port the server is
listening on. Only after resetting the server via a call to
<b class="method">down</b> followed by a call to <b class="method">up</b> will the new port take
effect. It is at that time that the value returned when querying
<b class="option">-port</b> will change too.</p></dd>
<dt><b class="option">-auth</b> <i class="arg">command</i></dt>
<dd><p>Defines a <i class="arg">command</i> prefix to call whenever the authentication of
a user is required. If no such command is specified the server will
reject all users. The interface which has to be provided by the
command prefix is described in section <span class="sectref"><a href="#section3">Authentication</a></span>.</p></dd>
<dt><b class="option">-storage</b> <i class="arg">command</i></dt>
<dd><p>Defines a <i class="arg">command</i> prefix to call whenever the handling of
mailbox contents is required. If no such command is specified the
server will claim that all mailboxes are empty. The interface which
has to be provided by the command prefix is described in section
<span class="sectref"><a href="#section4">Mailboxes</a></span>.</p></dd>
<dt><b class="option">-socket</b> <i class="arg">command</i></dt>
<dd><p>Defines a <i class="arg">command</i> prefix to call for opening the listening socket.
This can be used to make the pop3 server listen on a SSL socket
as provided by the <b class="package"><a href="../../../../index.html#tls">tls</a></b> package, see the command <b class="cmd">tls::socket</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Authentication</a></h2>
<p>Here we describe the interface which has to be provided by the
authentication callback so that pop3 servers following the interface
of this module are able to use it.</p>
<dl class="doctools_definitions">
<dt><a name="12"><i class="arg">authCmd</i> <b class="method">exists</b> <i class="arg">name</i></a></dt>
<dd><p>This method is given a user<i class="arg">name</i> and has to return a boolean
value telling whether or not the specified user exists.</p></dd>
<dt><a name="13"><i class="arg">authCmd</i> <b class="method">lookup</b> <i class="arg">name</i></a></dt>
<dd><p>This method is given a user<i class="arg">name</i> and has to return a two-element
list containing the password for this user and a storage reference, in
this order.</p>
<p>The storage reference is passed unchanged to the storage callback, see
sections <span class="sectref"><a href="#section2">Options</a></span> and <span class="sectref"><a href="#section4">Mailboxes</a></span> for either the
option defining it and or the interface to provide, respectively.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Mailboxes</a></h2>
<p>Here we describe the interface which has to be provided by the storage
callback so that pop3 servers following the interface of this module
are able to use it. The <i class="arg">mbox</i> argument is the storage reference
as returned by the <b class="method">lookup</b> method of the authentication
command, see section <span class="sectref"><a href="#section3">Authentication</a></span>.</p>
<dl class="doctools_definitions">
<dt><a name="14"><i class="arg">storageCmd</i> <b class="method">dele</b> <i class="arg">mbox</i> <i class="arg">msgList</i></a></dt>
<dd><p>Deletes the messages whose numeric ids are contained in the
<i class="arg">msgList</i> from the mailbox specified via <i class="arg">mbox</i>.</p></dd>
<dt><a name="15"><i class="arg">storageCmd</i> <b class="method">lock</b> <i class="arg">mbox</i></a></dt>
<dd><p>This method locks the specified mailbox for use by a single connection
to the server. This is necessary to prevent havoc if several
connections to the same mailbox are open. The complementary method is
<b class="method">unlock</b>. The command will return true if the lock could be set
successfully or false if not.</p></dd>
<dt><a name="16"><i class="arg">storageCmd</i> <b class="method">unlock</b> <i class="arg">mbox</i></a></dt>
<dd><p>This is the complementary method to <b class="method">lock</b>, it revokes the lock
on the specified mailbox.</p></dd>
<dt><a name="17"><i class="arg">storageCmd</i> <b class="method">size</b> <i class="arg">mbox</i> <span class="opt">?<i class="arg">msgId</i>?</span></a></dt>
<dd><p>Determines the size of the message specified through its id in
<i class="arg">msgId</i>, in bytes, and returns this number. The command will
return the size of the whole maildrop if no message id was specified.</p></dd>
<dt><a name="18"><i class="arg">storageCmd</i> <b class="method">stat</b> <i class="arg">mbox</i></a></dt>
<dd><p>Determines the number of messages in the specified mailbox and returns
this number.</p></dd>
<dt><a name="19"><i class="arg">storageCmd</i> <b class="method">get</b> <i class="arg">mbox</i> <i class="arg">msgId</i></a></dt>
<dd><p>Returns a handle for the specified message. This handle is a mime
token following the interface described in the documentation of
package <b class="package"><a href="../mime/mime.html">mime</a></b>. The pop3 server will use the functionality of
the mime token to send the mail to the requestor at the other end of a
pop3 connection.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Secure mail transfer</a></h2>
<p>The option <b class="option">-socket</b> (see <span class="sectref"><a href="#section2">Options</a></span>) enables users of
the package to override how the server opens its listening socket.
The envisioned main use is the specification of the <b class="cmd">tls::socket</b>
command, see package <b class="package"><a href="../../../../index.html#tls">tls</a></b>, to secure the communication.</p>
<pre class="doctools_example">
package require tls
tls::init \\
...
pop3d::new S -socket tls::socket
...
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://www.rfc-editor.org/rfc/rfc1939.txt">RFC 1939</a></p></li>
<li><p><a href="http://www.rfc-editor.org/rfc/rfc2449.txt">RFC 2449</a></p></li>
</ol>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pop3d</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#network">network</a>, <a href="../../../../index.html#pop3">pop3</a>, <a href="../../../../index.html#protocol">protocol</a>, <a href="../../../../index.html#rfc_1939">rfc 1939</a>, <a href="../../../../index.html#secure">secure</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002-2009 Andreas Kupries <[email protected]><br>
Copyright © 2005 Reinhard Max <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
<div class='fossil-doc' data-title='pop3d::dbox - Tcl POP3 Server Package'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pop3d::dbox(n) 1.0.2 tcllib "Tcl POP3 Server Package"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pop3d::dbox - Simple mailbox database for pop3d</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">pop3d::dbox <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pop3d::dbox::new</b> <span class="opt">?<i class="arg">dbName</i>?</span></a></li>
<li><a href="#2"><b class="cmd">dbName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">dbName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">dbName</i> <b class="method">base</b> <i class="arg">base</i></a></li>
<li><a href="#5"><i class="arg">dbName</i> <b class="method">add</b> <i class="arg">mbox</i></a></li>
<li><a href="#6"><i class="arg">dbName</i> <b class="method">remove</b> <i class="arg">mbox</i></a></li>
<li><a href="#7"><i class="arg">dbName</i> <b class="method">move</b> <i class="arg">old new</i></a></li>
<li><a href="#8"><i class="arg">dbName</i> <b class="method">list</b></a></li>
<li><a href="#9"><i class="arg">dbName</i> <b class="method">exists</b> <i class="arg">mbox</i></a></li>
<li><a href="#10"><i class="arg">dbName</i> <b class="method">locked</b> <i class="arg">mbox</i></a></li>
<li><a href="#11"><i class="arg">dbName</i> <b class="method">lock</b> <i class="arg">mbox</i></a></li>
<li><a href="#12"><i class="arg">dbName</i> <b class="method">unlock</b> <i class="arg">mbox</i></a></li>
<li><a href="#13"><i class="arg">dbName</i> <b class="method">stat</b> <i class="arg">mbox</i></a></li>
<li><a href="#14"><i class="arg">dbName</i> <b class="method">size</b> <i class="arg">mbox</i> <span class="opt">?<i class="arg">msgId</i>?</span></a></li>
<li><a href="#15"><i class="arg">dbName</i> <b class="method">dele</b> <i class="arg">mbox msgList</i></a></li>
<li><a href="#16"><i class="arg">storageCmd</i> <b class="method">get</b> <i class="arg">mbox</i> <i class="arg">msgId</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">pop3d::dbox</b> provides simple/basic mailbox
management facilities. Each mailbox object manages a single base
directory whose subdirectories represent the managed mailboxes. Mails
in a mailbox are represented by files in a mailbox directory, where
each of these files contains a single mail, both headers and body, in
RFC 822 (<a href="http://www.rfc-editor.org/rfc/rfc822.txt">http://www.rfc-editor.org/rfc/rfc822.txt</a>) conformant
format.</p>
<p>Any mailbox object following the interface described below can be used
in conjunction with the pop3 server core provided by the package
<b class="package"><a href="pop3d.html">pop3d</a></b>. It is especially possible to directly use the objects
created by this package in the storage callback of pop3 servers
following the same interface as servers created by the package
<b class="package"><a href="pop3d.html">pop3d</a></b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pop3d::dbox::new</b> <span class="opt">?<i class="arg">dbName</i>?</span></a></dt>
<dd><p>This command creates a new database object with an associated global
Tcl command whose name is <i class="arg">dbName</i>.</p></dd>
</dl>
<p>The command <b class="cmd">dbName</b> may be used to invoke various operations on
the database. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">dbName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>The following commands are possible for database objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">dbName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the mailbox database and all transient data. The directory
associated with the object is not destroyed.</p></dd>
<dt><a name="4"><i class="arg">dbName</i> <b class="method">base</b> <i class="arg">base</i></a></dt>
<dd><p>Defines the base directory containing the mailboxes to manage. If this
method is not called none of the following methods will work.</p></dd>
<dt><a name="5"><i class="arg">dbName</i> <b class="method">add</b> <i class="arg">mbox</i></a></dt>
<dd><p>Adds a mailbox of name <i class="arg">mbox</i> to the database. The name must be a
valid path component.</p></dd>
<dt><a name="6"><i class="arg">dbName</i> <b class="method">remove</b> <i class="arg">mbox</i></a></dt>
<dd><p>Removes the mailbox specified through <i class="arg">mbox</i>, and the mails
contained therein, from the database. This method will fail if the
specified mailbox is locked.</p></dd>
<dt><a name="7"><i class="arg">dbName</i> <b class="method">move</b> <i class="arg">old new</i></a></dt>
<dd><p>Changes the name of the mailbox <i class="arg">old</i> to <i class="arg">new</i>.</p></dd>
<dt><a name="8"><i class="arg">dbName</i> <b class="method">list</b></a></dt>
<dd><p>Returns a list containing the names of all mailboxes in the directory
associated with the database.</p></dd>
<dt><a name="9"><i class="arg">dbName</i> <b class="method">exists</b> <i class="arg">mbox</i></a></dt>
<dd><p>Returns true if the mailbox with name <i class="arg">mbox</i> exists in the
database, or false if not.</p></dd>
<dt><a name="10"><i class="arg">dbName</i> <b class="method">locked</b> <i class="arg">mbox</i></a></dt>
<dd><p>Checks if the mailbox specified through <i class="arg">mbox</i> is currently locked.</p></dd>
<dt><a name="11"><i class="arg">dbName</i> <b class="method">lock</b> <i class="arg">mbox</i></a></dt>
<dd><p>This method locks the specified mailbox for use by a single connection
to the server. This is necessary to prevent havoc if several
connections to the same mailbox are open. The complementary method is
<b class="method">unlock</b>. The command will return true if the lock could be set
successfully or false if not.</p></dd>
<dt><a name="12"><i class="arg">dbName</i> <b class="method">unlock</b> <i class="arg">mbox</i></a></dt>
<dd><p>This is the complementary method to <b class="method">lock</b>, it revokes the lock
on the specified mailbox.</p></dd>
<dt><a name="13"><i class="arg">dbName</i> <b class="method">stat</b> <i class="arg">mbox</i></a></dt>
<dd><p>Determines the number of messages in the specified mailbox and returns
this number. This method fails if the mailbox <i class="arg">mbox</i> is not
locked.</p></dd>
<dt><a name="14"><i class="arg">dbName</i> <b class="method">size</b> <i class="arg">mbox</i> <span class="opt">?<i class="arg">msgId</i>?</span></a></dt>
<dd><p>Determines the size of the message specified through its id in
<i class="arg">msgId</i>, in bytes, and returns this number. The command will
return the size of the whole maildrop if no message id was specified.
If specified the <i class="arg">msgId</i> has to be in the range "1 ... [<i class="arg">dbName</i> <b class="method">stat</b>]"
or this call will fail. If <b class="method">stat</b> was not called before this
call, <b class="method">size</b> will assume that there are zero messages in the
mailbox.</p></dd>
<dt><a name="15"><i class="arg">dbName</i> <b class="method">dele</b> <i class="arg">mbox msgList</i></a></dt>
<dd><p>Deletes the messages whose numeric ids are contained in the
<i class="arg">msgList</i> from the mailbox specified via <i class="arg">mbox</i>.
The <i class="arg">msgList</i> must not be empty or this call will fail.
The numeric ids in <i class="arg">msgList</i> have to be in the range "1 ...
[<i class="arg">dbName</i> <b class="method">stat</b>]" or this
call will fail. If <b class="method">stat</b> was not called
before this call, <b class="method">dele</b> will assume
that there are zero messages in the mailbox.</p></dd>
<dt><a name="16"><i class="arg">storageCmd</i> <b class="method">get</b> <i class="arg">mbox</i> <i class="arg">msgId</i></a></dt>
<dd><p>Returns a handle for the specified message. This handle is a mime
token following the interface described in the documentation of
package <b class="package"><a href="../mime/mime.html">mime</a></b>. The token is <em>read-only</em>. In other
words, the caller is allowed to do anything with the token except to
modify it.
The <i class="arg">msgId</i> has to be in the range "1 ...
[<i class="arg">dbName</i> <b class="method">stat</b>]" or this
call will fail. If <b class="method">stat</b> was not called
before this call, <b class="method">get</b> will assume
that there are zero messages in the mailbox.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pop3d</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#network">network</a>, <a href="../../../../index.html#pop3">pop3</a>, <a href="../../../../index.html#protocol">protocol</a>, <a href="../../../../index.html#rfc_822">rfc 822</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
<div class='fossil-doc' data-title='pop3d::udb - Tcl POP3 Server Package'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pop3d::udb(n) 1.0.1 tcllib "Tcl POP3 Server Package"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pop3d::udb - Simple user database for pop3d</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">pop3d::udb <span class="opt">?1.0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pop3d::udb::new</b> <span class="opt">?<i class="arg">dbName</i>?</span></a></li>
<li><a href="#2"><b class="cmd">dbName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">dbName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">dbName</i> <b class="method">add</b> <i class="arg">user pwd storage</i></a></li>
<li><a href="#5"><i class="arg">dbName</i> <b class="method">remove</b> <i class="arg">user</i></a></li>
<li><a href="#6"><i class="arg">dbName</i> <b class="method">rename</b> <i class="arg">user newName</i></a></li>
<li><a href="#7"><i class="arg">dbName</i> <b class="method">lookup</b> <i class="arg">user</i></a></li>
<li><a href="#8"><i class="arg">dbName</i> <b class="method">exists</b> <i class="arg">user</i></a></li>
<li><a href="#9"><i class="arg">dbName</i> <b class="method">who</b></a></li>
<li><a href="#10"><i class="arg">dbName</i> <b class="method">save</b> <span class="opt">?<i class="arg">file</i>?</span></a></li>
<li><a href="#11"><i class="arg">dbName</i> <b class="method">read</b> <i class="arg">file</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">pop3d::udb</b> provides simple in memory databases
which can be used in conjunction with the pop3 server core provided by
the package <b class="package"><a href="pop3d.html">pop3d</a></b>. The databases will use the names of users
as keys and associates passwords and storage references with them.</p>
<p>Objects created by this package can be directly used in the
authentication callback of pop3 servers following the same interface
as servers created by the package <b class="package"><a href="pop3d.html">pop3d</a></b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pop3d::udb::new</b> <span class="opt">?<i class="arg">dbName</i>?</span></a></dt>
<dd><p>This command creates a new database object with an associated global
Tcl command whose name is <i class="arg">dbName</i>.</p></dd>
</dl>
<p>The command <b class="cmd">dbName</b> may be used to invoke various operations on
the database. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">dbName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>The following commands are possible for database objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">dbName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the database object.</p></dd>
<dt><a name="4"><i class="arg">dbName</i> <b class="method">add</b> <i class="arg">user pwd storage</i></a></dt>
<dd><p>Add a new user or changes the data of an existing user. Stores
<i class="arg">password</i> and <i class="arg">storage</i> reference for the given <i class="arg">user</i>.</p></dd>
<dt><a name="5"><i class="arg">dbName</i> <b class="method">remove</b> <i class="arg">user</i></a></dt>
<dd><p>Removes the specified <i class="arg">user</i> from the database.</p></dd>
<dt><a name="6"><i class="arg">dbName</i> <b class="method">rename</b> <i class="arg">user newName</i></a></dt>
<dd><p>Changes the name of the specified <i class="arg">user</i> to <i class="arg">newName</i>.</p></dd>
<dt><a name="7"><i class="arg">dbName</i> <b class="method">lookup</b> <i class="arg">user</i></a></dt>
<dd><p>Searches the database for the specified <i class="arg">user</i> and returns a
two-element list containing the associated password and storage
reference, in this order. Throws an error if the user could not be
found. This is the interface as expected by the authentication
callback of package <b class="package"><a href="pop3d.html">pop3d</a></b>.</p></dd>
<dt><a name="8"><i class="arg">dbName</i> <b class="method">exists</b> <i class="arg">user</i></a></dt>
<dd><p>Returns true if the specified <i class="arg">user</i> is known to the database,
else false.</p></dd>
<dt><a name="9"><i class="arg">dbName</i> <b class="method">who</b></a></dt>
<dd><p>Returns a list of users known to the database.</p></dd>
<dt><a name="10"><i class="arg">dbName</i> <b class="method">save</b> <span class="opt">?<i class="arg">file</i>?</span></a></dt>
<dd><p>Saves the contents of the database into the given <i class="arg">file</i>. If the
file is not specified the system will use the path last used in a call
to <i class="arg">dbName</i> <b class="method">read</b>. The generated file can be read by the
<b class="method">read</b> method.</p></dd>
<dt><a name="11"><i class="arg">dbName</i> <b class="method">read</b> <i class="arg">file</i></a></dt>
<dd><p>Reads the specified <i class="arg">file</i> and adds the contained user definitions
to the database. As the file is actually <b class="cmd"><a href="../../../../index.html#source">source</a></b>'d a safe
interpreter is employed to safeguard against malicious code. This
interpreter knows the <b class="cmd">add</b> command for adding users and their
associated data to this database. This command has the same argument
signature as the method <b class="method">add</b>. The path of the <i class="arg">file</i> is
remembered internally so that it can be used in the next call of
<i class="arg">dbName</i> <b class="method">save</b> without an argument.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pop3d</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#network">network</a>, <a href="../../../../index.html#pop3">pop3</a>, <a href="../../../../index.html#protocol">protocol</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/practcl/practcl.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
<div class='fossil-doc' data-title='practcl - The The Proper Rational API for C to Tool Command Language Module'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">practcl(n) 0.11 tcllib "The The Proper Rational API for C to Tool Command Language Module"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>practcl - The Practcl Module</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">TclOO 1.0</b></li>
<li>package require <b class="pkgname">practcl 0.11</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">CPUTS</b> <i class="arg">varname</i> <i class="arg">body</i> <span class="opt">?<i class="arg">body</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">practcl::_isdirectory</b> <i class="arg">path</i></a></li>
<li><a href="#3"><b class="cmd">practcl::object</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#4"><b class="cmd">practcl::library</b> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#5"><b class="cmd">practcl::exe</b> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#6"><b class="cmd">practcl::product</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#7"><b class="cmd">practcl::cheader</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#8"><b class="cmd">practcl::csource</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#9"><b class="cmd">practcl::module</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
<li><a href="#10"><b class="cmd">practcl::submodule</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The Practcl module is a tool for integrating large modules for C API
Tcl code that requires custom Tcl types and TclOO objects.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">CPUTS</b> <i class="arg">varname</i> <i class="arg">body</i> <span class="opt">?<i class="arg">body</i>...?</span></a></dt>
<dd><p>Appends blocks of text to a buffer. This command tries to reduce the number
of line breaks between bodies.</p></dd>
<dt><a name="2"><b class="cmd">practcl::_isdirectory</b> <i class="arg">path</i></a></dt>
<dd><p>Returns true if <i class="arg">path</i> is a directory, using the test</p></dd>
</dl>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">practcl::object</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A generic Practcl object</p></dd>
<dt><a name="4"><b class="cmd">practcl::library</b> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing a library container</p></dd>
<dt><a name="5"><b class="cmd">practcl::exe</b> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing a wrapped executable</p></dd>
<dt><a name="6"><b class="cmd">practcl::product</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing a compiled product</p></dd>
<dt><a name="7"><b class="cmd">practcl::cheader</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing an externally generated c header</p></dd>
<dt><a name="8"><b class="cmd">practcl::csource</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing an externally generated c source file</p></dd>
<dt><a name="9"><b class="cmd">practcl::module</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing a dynamically generated C/H/Tcl suite</p></dd>
<dt><a name="10"><b class="cmd">practcl::submodule</b> <i class="arg">parent</i> <span class="opt">?<i class="arg">keyvaluelist</i>?</span></a></dt>
<dd><p>A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>practcl</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#practcl">practcl</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>TclOO</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2016-2018 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/processman/processman.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
<div class='fossil-doc' data-title='processman - processman'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">processman(n) 0.1 tcllib "processman"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>processman - Tool for automating the period callback of commands</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">twapi 3.1</b></li>
<li>package require <b class="pkgname">cron 1.1</b></li>
<li>package require <b class="pkgname">processman <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::processman::find_exe</b> <i class="arg">name</i></a></li>
<li><a href="#2"><b class="cmd">::processman::kill</b> <i class="arg">id</i></a></li>
<li><a href="#3"><b class="cmd">::processman::kill_all</b></a></li>
<li><a href="#4"><b class="cmd">::processman::killexe</b> <i class="arg">name</i></a></li>
<li><a href="#5"><b class="cmd">::processman::onexit</b> <i class="arg">id</i> <i class="arg">cmd</i></a></li>
<li><a href="#6"><b class="cmd">::processman::priority</b> <i class="arg">id</i> <i class="arg">level</i></a></li>
<li><a href="#7"><b class="cmd">::processman::process_list</b></a></li>
<li><a href="#8"><b class="cmd">::processman::process_list</b> <i class="arg">id</i></a></li>
<li><a href="#9"><b class="cmd">::processman::spawn</b> <i class="arg">id</i> <i class="arg">cmd</i> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">processman</b> package provides a Pure-tcl set of utilities
to manage child processes in a platform-generic nature.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::processman::find_exe</b> <i class="arg">name</i></a></dt>
<dd><p>Locate an executable by the name of <i class="arg">name</i> in the system path. On windows,
also add the .exe extention if not given.</p></dd>
<dt><a name="2"><b class="cmd">::processman::kill</b> <i class="arg">id</i></a></dt>
<dd><p>Kill a child process <i class="arg">id</i>.</p></dd>
<dt><a name="3"><b class="cmd">::processman::kill_all</b></a></dt>
<dd><p>Kill all processes spawned by this program</p></dd>
<dt><a name="4"><b class="cmd">::processman::killexe</b> <i class="arg">name</i></a></dt>
<dd><p>Kill a process identified by the executable. On Unix, this triggers a killall.
On windows, <b class="cmd">twapi::get_process_ids</b> is used to map a name one or more IDs,
which are then killed.</p></dd>
<dt><a name="5"><b class="cmd">::processman::onexit</b> <i class="arg">id</i> <i class="arg">cmd</i></a></dt>
<dd><p>Arrange to execute the script <i class="arg">cmd</i> when this programe detects that
process <i class="arg">id</i> as terminated.</p></dd>
<dt><a name="6"><b class="cmd">::processman::priority</b> <i class="arg">id</i> <i class="arg">level</i></a></dt>
<dd><p>Mark process <i class="arg">id</i> with the priorty <i class="arg">level</i>. Valid levels: low, high, default.</p>
<p>On Unix, the process is tagged using the <b class="cmd">nice</b> command.</p>
<p>On Windows, the process is modifed via the <b class="cmd">twapi::set_priority_class</b></p></dd>
<dt><a name="7"><b class="cmd">::processman::process_list</b></a></dt>
<dd><p>Return a list of processes that have been triggered by this program, as
well as a boolean flag to indicate if the process is still running.</p></dd>
<dt><a name="8"><b class="cmd">::processman::process_list</b> <i class="arg">id</i></a></dt>
<dd><p>Return true if process <i class="arg">id</i> is still running, false otherwise.</p></dd>
<dt><a name="9"><b class="cmd">::processman::spawn</b> <i class="arg">id</i> <i class="arg">cmd</i> <i class="arg">args</i></a></dt>
<dd><p>Start a child process, identified by <i class="arg">id</i>. <i class="arg">cmd</i> is the name
of the command to execute. <i class="arg">args</i> are arguments to pass to that command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>odie</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#odie">odie</a>, <a href="../../../../index.html#processman">processman</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>System</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/profiler/profiler.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<div class='fossil-doc' data-title='profiler - Tcl Profiler'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">profiler(n) 0.3 tcllib "Tcl Profiler"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>profiler - Tcl source code profiler</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">profiler <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::profiler::init</b></a></li>
<li><a href="#2"><b class="cmd">::profiler::dump</b> <i class="arg">pattern</i></a></li>
<li><a href="#3"><b class="cmd">::profiler::print</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::profiler::reset</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::profiler::suspend</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::profiler::resume</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::profiler::sortFunctions</b> <i class="arg">key</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">profiler</b> package provides a simple Tcl source code
profiler. It is a function-level profiler; that is, it collects only
function-level information, not the more detailed line-level
information. It operates by redefining the Tcl <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> command.
Profiling is initiated via the <b class="cmd">::profiler::init</b> command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::profiler::init</b></a></dt>
<dd><p>Initiate profiling. All procedures created after this command is
called will be profiled. To profile an entire application, this
command must be called before any other commands.</p></dd>
<dt><a name="2"><b class="cmd">::profiler::dump</b> <i class="arg">pattern</i></a></dt>
<dd><p>Dump profiling information for the all functions matching
<i class="arg">pattern</i>. If no pattern is specified, information for all
functions will be returned. The result is a list of key/value pairs
that maps function names to information about that function. The
information about each function is in turn a list of key/value pairs.
The keys used and their values are:</p>
<dl class="doctools_definitions">
<dt><b class="const">totalCalls</b></dt>
<dd><p>The total number of times <i class="arg">functionName</i> was called.</p></dd>
<dt><b class="const">callerDist</b></dt>
<dd><p>A list of key/value pairs mapping each calling function that called
<i class="arg">functionName</i> to the number of times it called
<i class="arg">functionName</i>.</p></dd>
<dt><b class="const">compileTime</b></dt>
<dd><p>The runtime, in clock clicks, of <i class="arg">functionName</i> the first time
that it was called.</p></dd>
<dt><b class="const">totalRuntime</b></dt>
<dd><p>The sum of the runtimes of all calls of <i class="arg">functionName</i>.</p></dd>
<dt><b class="const">averageRuntime</b></dt>
<dd><p>Average runtime of <i class="arg">functionName</i>.</p></dd>
<dt><b class="const">descendantTime</b></dt>
<dd><p>Sum of the time spent in descendants of <i class="arg">functionName</i>.</p></dd>
<dt><b class="const">averageDescendantTime</b></dt>
<dd><p>Average time spent in descendants of <i class="arg">functionName</i>.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::profiler::print</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Print profiling information for all functions matching <i class="arg">pattern</i>.
If no pattern is specified, information about all functions will be
displayed. The return result is a human readable display of the
profiling information.</p></dd>
<dt><a name="4"><b class="cmd">::profiler::reset</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Reset profiling information for all functions matching <i class="arg">pattern</i>.
If no pattern is specified, information will be reset for all
functions.</p></dd>
<dt><a name="5"><b class="cmd">::profiler::suspend</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Suspend profiling for all functions matching <i class="arg">pattern</i>. If no
pattern is specified, profiling will be suspended for all
functions. It stops gathering profiling information after this command
is issued. However, it does not erase any profiling information that
has been gathered previously. Use resume command to re-enable
profiling.</p></dd>
<dt><a name="6"><b class="cmd">::profiler::resume</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Resume profiling for all functions matching <i class="arg">pattern</i>. If no
pattern is specified, profiling will be resumed for all functions.
This command should be invoked after suspending the profiler in the
code.</p></dd>
<dt><a name="7"><b class="cmd">::profiler::sortFunctions</b> <i class="arg">key</i></a></dt>
<dd><p>Return a list of functions sorted by a particular profiling statistic.
Supported values for <i class="arg">key</i> are: <b class="const">calls</b>,
<b class="const">exclusiveTime</b>, <b class="const">compileTime</b>, <b class="const">nonCompileTime</b>,
<b class="const">totalRuntime</b>, <b class="const">avgExclusiveTime</b>, and
<b class="const">avgRuntime</b>. The return result is a list of lists, where each
sublist consists of a function name and the value of <i class="arg">key</i> for
that function.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>profiler</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#performance">performance</a>, <a href="../../../../index.html#profile">profile</a>, <a href="../../../../index.html#speed">speed</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_astree.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
|
<div class='fossil-doc' data-title='pt::ast - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::ast(n) 1.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::ast - Abstract Syntax Tree Serialization</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">AST serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::ast <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::ast</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::pt::ast</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></li>
<li><a href="#3"><b class="cmd">::pt::ast</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></li>
<li><a href="#4"><b class="cmd">::pt::ast</b> <b class="method">print</b> <i class="arg">serial</i></a></li>
<li><a href="#5"><b class="cmd">::pt::ast</b> <b class="method">bottomup</b> <i class="arg">cmdprefix</i> <i class="arg">ast</i></a></li>
<li><a href="#6"><b class="cmd">cmdprefix</b> <i class="arg">ast</i></a></li>
<li><a href="#7"><b class="cmd">::pt::ast</b> <b class="method">topdown</b> <i class="arg">cmdprefix</i> <i class="arg">pe</i></a></li>
<li><a href="#8"><b class="cmd">::pt::ast</b> <b class="method">equal</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></li>
<li><a href="#9"><b class="cmd">::pt::ast</b> <b class="method">new0</b> <i class="arg">s</i> <i class="arg">loc</i> <span class="opt">?<i class="arg">child</i>...?</span></a></li>
<li><a href="#10"><b class="cmd">::pt::ast</b> <b class="method">new</b> <i class="arg">s</i> <i class="arg">start</i> <i class="arg">end</i> <span class="opt">?<i class="arg">child</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides commands to work with the serializations of
abstract syntax trees as managed by the Parser Tools, and specified in
section <span class="sectref"><a href="#section3">AST serialization format</a></span>.</p>
<p>This is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::ast</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
serialization of an abstract syntax tree and will throw an error if
that is not the case. The result of the command is the empty string.</p>
<p>If the argument <i class="arg">canonvar</i> is specified it is interpreted as the
name of a variable in the calling context. This variable will be
written to if and only if <i class="arg">serial</i> is a valid regular
serialization. Its value will be a boolean, with <b class="const">True</b>
indicating that the serialization is not only valid, but also
<i class="term">canonical</i>. <b class="const">False</b> will be written for a valid, but
non-canonical serialization.</p>
<p>For the specification of serializations see the section
<span class="sectref"><a href="#section3">AST serialization format</a></span>.</p></dd>
<dt><a name="2"><b class="cmd">::pt::ast</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">canonical</i> serialization of an abstract syntax tree and will
throw an error if that is not the case. The result of the command is
the empty string.</p>
<p>For the specification of canonical serializations see the section
<span class="sectref"><a href="#section3">AST serialization format</a></span>.</p></dd>
<dt><a name="3"><b class="cmd">::pt::ast</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of an abstract syntax and will throw an
error if that is not the case.</p>
<p>It will then convert the input into the <i class="term">canonical</i> serialization
of the contained tree and return it as its result. If the input is
already canonical it will be returned unchanged.</p>
<p>For the specification of regular and canonical serializations see the
section <span class="sectref"><a href="#section3">AST serialization format</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::pt::ast</b> <b class="method">print</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the argument <i class="arg">serial</i> contains a valid
serialization of an abstract syntax tree and returns a string
containing that tree in a human readable form.</p>
<p>The exact format of this form is not specified and cannot be relied on
for parsing or other machine-based activities.</p>
<p>For the specification of serializations see the section
<span class="sectref"><a href="#section3">AST serialization format</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::pt::ast</b> <b class="method">bottomup</b> <i class="arg">cmdprefix</i> <i class="arg">ast</i></a></dt>
<dd><p>This command walks the abstract syntax tree <i class="arg">ast</i> from the bottom
up to the root, invoking the command prefix <i class="arg">cmdprefix</i> for each
node. This implies that the children of a node N are handled before N.</p>
<p>The command prefix has the signature</p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="cmd">cmdprefix</b> <i class="arg">ast</i></a></dt>
<dd><p>I.e. it is invoked with the ast node the walk is currently at.</p>
<p>The result returned by the command prefix replaces <i class="arg">ast</i> in the
node it was a child of, allowing transformations of the tree.</p>
<p>This also means that for all inner node the contents of the children
elements are the results of the command prefix invoked for the
children of this node.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::pt::ast</b> <b class="method">topdown</b> <i class="arg">cmdprefix</i> <i class="arg">pe</i></a></dt>
<dd><p>This command walks the abstract syntax tree <i class="arg">ast</i> from the root
down to the leaves, invoking the command prefix <i class="arg">cmdprefix</i> for
each node. This implies that the children of a node N are handled
after N.</p>
<p>The command prefix has the same signature as for <b class="method">bottomup</b>,
see above.</p>
<p>The result returned by the command prefix is <em>ignored</em>.</p></dd>
<dt><a name="8"><b class="cmd">::pt::ast</b> <b class="method">equal</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></dt>
<dd><p>This command tests the two sbstract syntax trees <i class="arg">seriala</i> and
<i class="arg">serialb</i> for structural equality. The result of the command is a
boolean value. It will be set to <b class="const">true</b> if the trees are
identical, and <b class="const">false</b> otherwise.</p>
<p>String equality is usable only if we can assume that the two trees are
pure Tcl lists.</p></dd>
<dt><a name="9"><b class="cmd">::pt::ast</b> <b class="method">new0</b> <i class="arg">s</i> <i class="arg">loc</i> <span class="opt">?<i class="arg">child</i>...?</span></a></dt>
<dd><p>This command command constructs the ast for a nonterminal node
refering refering to the symbol <i class="arg">s</i> at position <i class="arg">loc</i> in the
input, and the set of child nodes <i class="arg">child</i> ..., from left
right. The latter may be empty. The constructed node is returned as
the result of the command. The end position is <i class="arg">loc</i>-1, i.e. one
character before the start. This type of node is possible for rules
containing optional parts.</p></dd>
<dt><a name="10"><b class="cmd">::pt::ast</b> <b class="method">new</b> <i class="arg">s</i> <i class="arg">start</i> <i class="arg">end</i> <span class="opt">?<i class="arg">child</i>...?</span></a></dt>
<dd><p>This command command constructs the ast for a nonterminal node
refering to the symbol <i class="arg">s</i> covering the range of positions
<i class="arg">start</i> to <i class="arg">end</i> in the input, and the set of child nodes
<i class="arg">child</i> ..., from left right. The latter may be empty. The
constructed node is returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AST serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Abstract Syntax Trees (ASTs) as immutable values for transport,
comparison, etc.</p>
<p>Each node in an AST represents a nonterminal symbol of a grammar, and
the range of tokens/characters in the input covered by it. ASTs do not
contain terminal symbols, i.e. tokens/characters. These can be
recovered from the input given a symbol's location.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a tree may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any AST is the serialization of its root node.</p></li>
<li><p>The serialization of any node is a Tcl list containing at least three
elements.</p>
<ol class="doctools_enumerated">
<li><p>The first element is the name of the nonterminal symbol stored in the
node.</p></li>
<li><p>The second and third element are the locations of the first and last
token in the token stream the node represents (covers).</p>
<ol class="doctools_enumerated">
<li><p>Locations are provided as non-negative integer offsets from the
beginning of the token stream, with the first token found in the
stream located at offset 0 (zero).</p></li>
<li><p>The end location has to be equal to or larger than the start location.</p></li>
</ol>
</li>
<li><p>All elements after the first three represent the children of the node,
which are themselves nodes. This means that the serializations of
nodes without children, i.e. leaf nodes, have exactly three elements.
The children are stored in the list with the leftmost child first, and
the rightmost child last.</p></li>
</ol>
</li>
</ol></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of an abstract syntax tree has the format
as specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this tree.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the parsing expression grammar below</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>and the input string</p>
<pre class="doctools_example"> 120+5 </pre>
<p>then a parser should deliver the abstract syntax tree below (except for whitespace)</p>
<pre class="doctools_example">
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
</pre>
<p>Or, more graphical</p>
<p><img alt="expr_ast" src="../../../../image/expr_ast.png"></p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<div class='fossil-doc' data-title='pt::cparam::configuration::critcl - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::cparam::configuration::critcl(n) 1.0.2 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::cparam::configuration::critcl - C/PARAM, Canned configuration, Critcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::cparam::configuration::critcl <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::cparam::configuration::critcl</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package is an adjunct to <b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b>, to make
the use of this highly configurable package easier by providing a
canned configuration. When applied this configuration causes the
package <b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b> to generate
<b class="package">critcl</b>-based parser packages.</p>
<p>It is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::cparam::configuration::critcl</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The command applies the configuration provided by this package to the
<i class="arg">cmdprefix</i>, causing the creation of <b class="package">critcl</b>-based parsers
whose class is <i class="arg">name</i>, in package <i class="arg">pkg</i> with <i class="arg">version</i>.</p>
<p>The use of a command prefix as API allows application of the
configuration to not only <b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b>
(<b class="cmd">pt::peg::to::cparam configure</b>), but also export manager
instances and PEG containers (<b class="cmd">$export configuration set</b> and
<b class="cmd">[$container exporter] configuration set</b> respectively).</p>
<p>Or anything other command prefix accepting two arguments, option and
value.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_cparam_config_tea.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<div class='fossil-doc' data-title='pt::cparam::configuration::tea - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::cparam::configuration::tea(n) 0.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::cparam::configuration::tea - C/PARAM, Canned configuration, TEA</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::cparam::configuration::tea <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::cparam::configuration::tea</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package is an adjunct to <b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b>, to make
the use of this highly configurable package easier by providing a
canned configuration. When applied this configuration causes the
package <b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b> to generate plain parser code
ready for inclusion into a <i class="term">TEA</i>-based C extension.</p>
<p>It is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::cparam::configuration::tea</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The command applies the configuration provided by this package to the
<i class="arg">cmdprefix</i>, causing the creation of <b class="package">tea</b>-based parsers
whose class is <i class="arg">name</i>, in package <i class="arg">pkg</i> with <i class="arg">version</i>.</p>
<p>The use of a command prefix as API allows application of the
configuration to not only <b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b>
(<b class="cmd">pt::peg::to::cparam configure</b>), but also export manager
instances and PEG containers (<b class="cmd">$export configuration set</b> and
<b class="cmd">[$container exporter] configuration set</b> respectively).</p>
<p>Or anything other command prefix accepting two arguments, option and
value.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_from_api.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
|
<div class='fossil-doc' data-title='pt_import_api - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt_import_api(i) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt_import_api - Parser Tools Import API</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Converter API</a></li>
<li class="doctools_section"><a href="#section3">Plugin API</a></li>
<li class="doctools_section"><a href="#section4">Usage</a></li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">CONVERTER</b> <b class="method">convert</b> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></li>
<li><a href="#3"><b class="cmd">::import</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This document describes two APIs. First the API shared by all packages
for the conversion of some other format into Parsing Expression
Grammars , and then the API shared by the packages which implement the
import plugins sitting on top of the conversion packages.</p>
<p>Its intended audience are people who wish to create their own
converter for some type of input, and/or an import plugin for their or
some other converter.</p>
<p>It resides in the Import section of the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_import" src="../../../../image/arch_core_import.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Converter API</a></h2>
<p>Any (grammar) import converter has to follow the rules set out below:</p>
<ol class="doctools_enumerated">
<li><p>A converter is a package. Its name is arbitrary, however it is
recommended to put it under the <b class="namespace">::pt::peg::from</b>
namespace.</p></li>
<li><p>The package provides either a single Tcl command following the
API outlined below, or a class command whose instances follow
the same API. The commands which follow the API are called
<i class="term">converter commands</i>.</p></li>
<li><p>A converter command has to provide the following single method
with the given signature and semantic. Converter commands
are allowed to provide more methods of their own, but not
less, and they may not provide different semantics for the
standardized method.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">CONVERTER</b> <b class="method">convert</b> <i class="arg">text</i></a></dt>
<dd><p>This method has to accept some <i class="arg">text</i>, a parsing expression
grammar in some format.
The result of the method has to be the canonical serialization of a
parsing expression grammar, as specified in section
<span class="sectref"><a href="#section5">PEG serialization format</a></span>, the result of reading and
converting the input text.</p></dd>
</dl>
</li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Plugin API</a></h2>
<p>Any (grammar) import plugin has to follow the rules set out below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
pt::peg::import::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
accept input for.</p></li>
<li><p>The plugin can expect that the package
<b class="package">pt::peg::import::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p>
<p>It is recommended that a plugin does check for the presence of
this package.</p></li>
<li><p>The plugin can expect that a command named <b class="cmd">IncludeFile</b>
is present, with the signature</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">IncludeFile</b> <i class="arg">currentfile</i> <i class="arg">path</i></a></dt>
<dd><p>This command has to be invoked by the plugin when it has to process an
included file, if the format has the concept of such.</p>
<p>The plugin has to supply the following arguments</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">currentfile</i></dt>
<dd><p>The path of the file it is currently processing. This may be the empty
string if no such is known.</p></dd>
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of the include file as specified in the include directive
being processed.</p></dd>
</dl>
<p>The result of the command will be a 5-element list containing</p>
<ol class="doctools_enumerated">
<li><p>A boolean flag indicating the success (<b class="const">True</b>) or failure
(<b class="const">False</b>) of the operation.</p></li>
<li><p>In case of success the contents of the included file, and the
empty string otherwise.</p></li>
<li><p>The resolved, i.e. absolute path of the included file, if
possible, or the unchanged <i class="arg">path</i> argument. This is for
display in an error message, or as the <i class="arg">currentfile</i>
argument of another call to <b class="cmd">IncludeFile</b> should this file
contain more files.</p></li>
<li><p>In case of success an empty string, and for failure a code
indicating the reason for it, one of</p>
<dl class="doctools_definitions">
<dt>notfound</dt>
<dd><p>The specified file could not be found.</p></dd>
<dt>notread</dt>
<dd><p>The specified file was found, but not be read into memory.</p></dd>
</dl>
</li>
<li><p>An empty string in case of success of a <b class="const">notfound</b>
failure, and an additional error message describing the reason
for a <b class="const">notread</b> error in more detail.</p></li>
</ol></dd>
</dl>
</li>
<li><p>A plugin has to provide a single command, in the global
namespace, with the signature shown below. Plugins are allowed
to provide more commands of their own, but not less, and they
may not provide different semantics for the standardized
command.</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::import</b> <i class="arg">text</i></a></dt>
<dd><p>This command has to accept the a text containing a parsing expression
grammar in some format. The result of the command has to be the result
of the converter invoked by the plugin for the input grammar, the
canonical serialization of the parsing expression grammar contained in
the input.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">text</i></dt>
<dd><p>This argument will contain the parsing expression grammar for which to
generate the serialization.
The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section5">PEG serialization format</a></span>.</p></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of an invokation of
the command <b class="cmd"><a href="../../../../index.html#import">import</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Usage</a></h2>
<p>To use a converter do</p>
<pre class="doctools_example">
# Get the converter (single command here, not class)
package require the-converter-package
# Perform the conversion
set serial [theconverter convert $thegrammartext]
... process the result ...
</pre>
<p>To use a plugin <b class="variable">FOO</b> do</p>
<pre class="doctools_example">
# Get an import plugin manager
package require pt::peg::import
pt::peg::import I
# Run the plugin, and the converter inside.
set serial [I import serial $thegrammartext FOO]
... process the result ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_introduction.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<div class='fossil-doc' data-title='pt_introduction - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt_introduction(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt_introduction - Introduction to Parser Tools</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Parser Tools Architecture</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">User Packages</a></li>
<li class="doctools_subsection"><a href="#subsection2">Core Packages</a></li>
<li class="doctools_subsection"><a href="#subsection3">Support Packages</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to the Parser Tools, a system for the creation and
manipulation of parsers and the grammars driving them.</p>
<p>What are your goals which drove you here ?</p>
<ol class="doctools_enumerated">
<li><p>Do you simply wish to create a parser for some language ?</p>
<p>In that case have a look at our parser generator application,
<b class="cmd"><a href="../../apps/pt.html">pt</a></b>, or, for a slightly deeper access, the package underneath it,
<b class="package"><a href="pt_pgen.html">pt::pgen</a></b>.</p></li>
<li><p>Do you wish to know more about the architecture of the system ?</p>
<p>This is described in the section
<span class="sectref"><a href="#section2">Parser Tools Architecture</a></span>, below</p></li>
<li><p>Is your interest in the theoretical background upon which the packages
and tools are build ?</p>
<p>See the <i class="term"><a href="pt_peg_introduction.html">Introduction to Parsing Expression Grammars</a></i>.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Parser Tools Architecture</a></h2>
<p>The system can be split into roughly three layers, as seen in the
figure below</p>
<p><img alt="architecture" src="../../../../image/architecture.png"></p>
<p>These layers are, from high to low:</p>
<ol class="doctools_enumerated">
<li><p>At the top we have the application and the packages using the packages
of the layer below to implement common usecases. One example is the
aforementioned <b class="package"><a href="pt_pgen.html">pt::pgen</a></b> which provides a parser generator.</p>
<p>The list of packages belonging to this layer can be found in section
<span class="sectref"><a href="#subsection1">User Packages</a></span></p></li>
<li><p>In this layer we have the packages which provide the core of the
functionality for the whole system. They are, in essence, a set of
blocks which can be combined in myriad ways, like Lego (tm). The
packages in the previous level are 'just' pre-fabricated combinations
to cover the most important use cases.</p>
<p>The list of packages belonging to this layer can be found in section
<span class="sectref"><a href="#subsection2">Core Packages</a></span></p></li>
<li><p>Last, but not least is the layer containing support packages providing
generic functionality which not necessarily belong into the module.</p>
<p>The list of packages belonging to this layer can be found in section
<span class="sectref"><a href="#subsection3">Support Packages</a></span></p></li>
</ol>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">User Packages</a></h3>
<dl class="doctools_definitions">
<dt><b class="package"><a href="pt_pgen.html">pt::pgen</a></b></dt>
<dd></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Core Packages</a></h3>
<p>This layer is further split into six sections handling the storage,
import, export, transformation, and execution of grammars, plus
grammar specific support packages.</p>
<dl class="doctools_definitions">
<dt>Storage</dt>
<dd><dl class="doctools_definitions">
<dt><b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b></dt>
<dd></dd>
</dl></dd>
<dt>Export</dt>
<dd><dl class="doctools_definitions">
<dt><b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_export_container.html">pt::peg::export::container</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_export_json.html">pt::peg::export::json</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_export_peg.html">pt::peg::export::peg</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_to_container.html">pt::peg::to::container</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_to_json.html">pt::peg::to::json</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_to_peg.html">pt::peg::to::peg</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_to_param.html">pt::peg::to::param</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b></dt>
<dd></dd>
</dl></dd>
<dt>Import</dt>
<dd><dl class="doctools_definitions">
<dt><b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_import_container.html">pt::peg::import::container</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_import_json.html">pt::peg::import::json</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_import_peg.html">pt::peg::import::peg</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_from_container.html">pt::peg::from::container</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_from_json.html">pt::peg::from::json</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_peg_from_peg.html">pt::peg::from::peg</a></b></dt>
<dd></dd>
</dl></dd>
<dt>Transformation</dt>
<dd></dd>
<dt>Execution</dt>
<dd><dl class="doctools_definitions">
<dt><b class="package"><a href="pt_peg_interp.html">pt::peg::interp</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_rdengine.html">pt::rde</a></b></dt>
<dd></dd>
</dl></dd>
<dt>Support</dt>
<dd><dl class="doctools_definitions">
<dt><b class="package"><a href="pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_astree.html">pt::ast</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_pexpression.html">pt::pe</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="pt_pegrammar.html">pt::peg</a></b></dt>
<dd></dd>
</dl></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Support Packages</a></h3>
<dl class="doctools_definitions">
<dt><b class="package"><a href="pt_peg_container_peg.html">pt::peg::container::peg</a></b></dt>
<dd></dd>
<dt><b class="package">text::write</b></dt>
<dd></dd>
<dt><b class="package">configuration</b></dt>
<dd></dd>
<dt><b class="package">paths</b></dt>
<dd></dd>
<dt><b class="package">char</b></dt>
<dd></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_json_language.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
|
<div class='fossil-doc' data-title='pt::json_language - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::json_language(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::json_language - The JSON Grammar Exchange Format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>The <b class="const">json</b> format for parsing expression grammars was written as
a data exchange format not bound to Tcl. It was defined to allow the
exchange of grammars with PackRat/PEG based parser generators for
other languages.</p>
<p>It is formally specified by the rules below:</p>
<ol class="doctools_enumerated">
<li><p>The JSON of any PEG is a JSON object.</p></li>
<li><p>This object holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a JSON object itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the
parsing expression describing the symbols sentennial structure, as
specified in the section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value is a JSON holding holding one of three values specifying how
a parser should handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol>
<p>As an aside to the advanced reader, this is pretty much the same as
the Tcl serialization of PE grammars, as specified in section
<span class="sectref"><a href="#section2">PEG serialization format</a></span>, except that the Tcl dictionaries
and lists of that format are mapped to JSON objects and arrays. Only
the parsing expressions themselves are not translated further, but
kept as JSON strings containing a nested Tcl list, and there is no
concept of canonicity for the JSON either.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>a JSON serialization for it is</p>
<pre class="doctools_example">
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
</pre>
<p>and a Tcl serialization of the same is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
<p>The similarity of the latter to the JSON should be quite obvious.</p>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_param.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
|
<div class='fossil-doc' data-title='pt::param - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::param(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::param - PackRat Machine Specification</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Architectural State</a></li>
<li class="doctools_section"><a href="#section3">Instruction Set</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Input Handling</a></li>
<li class="doctools_subsection"><a href="#subsection2">Character Processing</a></li>
<li class="doctools_subsection"><a href="#subsection3">Error Handling</a></li>
<li class="doctools_subsection"><a href="#subsection4">Status Control</a></li>
<li class="doctools_subsection"><a href="#subsection5">Location Handling</a></li>
<li class="doctools_subsection"><a href="#subsection6">Nonterminal Execution</a></li>
<li class="doctools_subsection"><a href="#subsection7">Value Construction</a></li>
<li class="doctools_subsection"><a href="#subsection8">AST Construction</a></li>
<li class="doctools_subsection"><a href="#subsection9">Control Flow</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Interaction of the Instructions with the Architectural State</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>Welcome to the PackRat Machine (short: <i class="term"><a href="../../../../index.html#param">PARAM</a></i>), a virtual
machine geared towards the support of recursive descent parsers,
especially packrat parsers. Towards this end it has features like the
caching and reuse of partial results, the caching of the encountered
input, and the ability to backtrack in both input and AST creation.</p>
<p>This document specifies the machine in terms of its architectural
state and instruction set.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Architectural State</a></h2>
<p>Any PARAM implementation has to manage at least the following state:</p>
<dl class="doctools_definitions">
<dt><i class="term">Input</i> (IN)</dt>
<dd><p>This is the channel the characters to process are read from.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the section <span class="sectref"><a href="#subsection1">Input Handling</a></span>.</p></dd>
<dt><i class="term">Current Character</i> (CC)</dt>
<dd><p>The character from the <i class="term">input</i> currently tested against its
possible alternatives.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the section <span class="sectref"><a href="#subsection2">Character Processing</a></span>.</p></dd>
<dt><i class="term">Current Location</i> (CL)</dt>
<dd><p>The location of the <i class="term">current character</i> in the <i class="term">input</i>, as
offset relative to the beginning of the input. Character offsets are
counted from <b class="const">0</b>.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection2">Character Processing</a></span>,
<span class="sectref"><a href="#subsection5">Location Handling</a></span>, and <span class="sectref"><a href="#subsection6">Nonterminal Execution</a></span>.</p></dd>
<dt><i class="term">Location Stack</i> (LS)</dt>
<dd><p>A stack of locations in the <i class="term">input</i>, saved for possible
backtracking.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection2">Character Processing</a></span>,
<span class="sectref"><a href="#subsection5">Location Handling</a></span>, and <span class="sectref"><a href="#subsection6">Nonterminal Execution</a></span>.</p></dd>
<dt><i class="term">Status</i> (ST)</dt>
<dd><p>The status of the last attempt of testing the <i class="term">input</i>, indicating
either success or failure.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection4">Status Control</a></span>,
<span class="sectref"><a href="#subsection2">Character Processing</a></span>, and <span class="sectref"><a href="#subsection6">Nonterminal Execution</a></span>.</p></dd>
<dt><i class="term">Semantic Value</i> (SV)</dt>
<dd><p>The current semantic value, either empty, or a node for AST
constructed from the input.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection7">Value Construction</a></span>, and
<span class="sectref"><a href="#subsection8">AST Construction</a></span>.</p></dd>
<dt><i class="term">AST Reduction Stack</i> (ARS)</dt>
<dd><p>The stack of partial ASTs constructed during the processing of
nonterminal symbols.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection7">Value Construction</a></span>, and
<span class="sectref"><a href="#subsection8">AST Construction</a></span>.</p></dd>
<dt><i class="term">AST Stack</i> (AS)</dt>
<dd><p>The stack of reduction stacks, saved for possible backtracking.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection7">Value Construction</a></span>, and
<span class="sectref"><a href="#subsection8">AST Construction</a></span>.</p></dd>
<dt><i class="term">Error Status</i> (ER)</dt>
<dd><p>The machine's current knowledge of errors. This is either empty, or
set to a pair of location in the input and the set of messages for
that location.</p>
<p><em>Note</em> that this part of the machine's state can be set even if
the last test of the <i class="term">current character</i> was successful. For
example, the *-operator (matching a sub-expression zero or more times)
in a PEG is always successful, even if it encounters a problem further
in the input and has to backtrack. Such problems must not be forgotten
when continuing the parsing.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection3">Error Handling</a></span>,
<span class="sectref"><a href="#subsection2">Character Processing</a></span>, and <span class="sectref"><a href="#subsection6">Nonterminal Execution</a></span>.</p></dd>
<dt><i class="term">Error Stack</i> (ES)</dt>
<dd><p>The stack of error stati, saved for backtracking. This enables the
machine to merge current and older error stati when performing
backtracking in choices after an failed match.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the sections <span class="sectref"><a href="#subsection3">Error Handling</a></span>,
<span class="sectref"><a href="#subsection2">Character Processing</a></span>, and <span class="sectref"><a href="#subsection6">Nonterminal Execution</a></span>.</p></dd>
<dt><i class="term">Nonterminal Cache</i> (NC)</dt>
<dd><p>A cache of machine states keyed by pairs name of nonterminal symbol
and location in the input. Each pair (N, L) is associated with a
4-tuple holding the values to use for CL, ST, SV, and ER after the
nonterminal N was parsed starting from the location L.
It is a performance aid for backtracking parsers, allowing them to
avoid an expensive reparsing of complex nonterminal symbols if they
have been encountered before at a given location.</p>
<p>The key location is where machine started the attempt to match the
named nonterminal symbol, and the location in the saved 4-tuple is
where machine ended up after the attempt completed, independent of the
success of the attempt.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the section <span class="sectref"><a href="#subsection6">Nonterminal Execution</a></span>.</p></dd>
<dt><i class="term">Terminal Cache</i> (TC)</dt>
<dd><p>A cache of characters read from IN, with their location in IN as pair
of line and column, keyed by the location in IN, this time as
character offset from the beginning of IN.
It is a performance aid for backtracking parsers, allowing them to
avoid a possibly expensive rereading of characters from IN, or even
enabling backtracking at, i.e. in the case of IN not randomly
seekable.</p>
<p>This part of the machine's state is used and modified by the
instructions defined in the section <span class="sectref"><a href="#subsection1">Input Handling</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instruction Set</a></h2>
<p>With the machine's architectural state specified it is now possible to
specify the instruction set operating on that state and to be
implemented by any realization of the PARAM. The 37 instructions are
grouped roughly by the state they influence and/or query during their
execution.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Input Handling</a></h3>
<p>The instructions in this section mainly access IN, pulling the
characters to process into the machine.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">input_next</b> <i class="arg">msg</i></dt>
<dd><p>This method reads the next character, i.e. the character after CL,
from IN. If successful this character becomes CC, CL is advanced by
one, ES is cleared, and the operation is recorded as a success in ST.</p>
<p>The operation may read the character from IN if the next character
is not yet known to TC. If successful the new character is stored in
TC, with its location (line, column), and the operation otherwise
behaves as specified above. Future reads from the same location,
possible due to backtracking, will then be satisfied from TC instead
of IN.</p>
<p>If, on the other hand, the end of IN was reached, the operation is
recorded as failed in ST, CL is left unchanged, and the pair of CL and
<i class="arg">msg</i> becomes the new ES.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Character Processing</a></h3>
<p>The instructions in this section mainly access CC, testing it against
character classes, ranges, and individual characters.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">test_alnum</b></dt>
<dd><p>This instruction implements the special PE operator "alnum", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_alpha</b></dt>
<dd><p>This instruction implements the special PE operator "alpha", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_ascii</b></dt>
<dd><p>This instruction implements the special PE operator "ascii", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_char</b> <i class="arg">char</i></dt>
<dd><p>This instruction implements the character matching operator, i.e. it
checks if CC is <i class="arg">char</i>.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_ddigit</b></dt>
<dd><p>This instruction implements the special PE operator "ddigit", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_digit</b></dt>
<dd><p>This instruction implements the special PE operator "digit", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_graph</b></dt>
<dd><p>This instruction implements the special PE operator "graph", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_lower</b></dt>
<dd><p>This instruction implements the special PE operator "lower", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_print</b></dt>
<dd><p>This instruction implements the special PE operator "print", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_punct</b></dt>
<dd><p>This instruction implements the special PE operator "punct", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_range</b> <i class="arg">chars</i> <i class="arg">chare</i></dt>
<dd><p>This instruction implements the range matching operator, i.e. it
checks if CC falls into the interval of characters spanned up by the
two characters from <i class="arg">chars</i> to <i class="arg">chare</i>, both inclusive.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_space</b></dt>
<dd><p>This instruction implements the special PE operator "space", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_upper</b></dt>
<dd><p>This instruction implements the special PE operator "upper", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_wordchar</b></dt>
<dd><p>This instruction implements the special PE operator "wordchar", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
<dt><b class="cmd">test_xdigit</b></dt>
<dd><p>This instruction implements the special PE operator "xdigit", which
checks if CC falls into the character class of the same name, or not.</p>
<p>Success and failure of the test are both recorded directly in ST.
Success further clears ES, wheras failure sets the pair of CL and
expected input (encoded as a leaf parsing expression) as the new ES
and then rewinds CL by one character, preparing the machine for
another parse attempt by a possible alternative.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Error Handling</a></h3>
<p>The instructions in this section mainly access ER and ES.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">error_clear</b></dt>
<dd><p>This instruction clears ER.</p></dd>
<dt><b class="cmd">error_push</b></dt>
<dd><p>This instruction makes a copy of ER and pushes it on ES.</p></dd>
<dt><b class="cmd">error_pop_merge</b></dt>
<dd><p>This instruction takes the topmost entry of ES and merges the error
status it contains with ES, making the result the new ES.</p>
<p>The merge is governed by four rules, with the merge result</p>
<ol class="doctools_enumerated">
<li><p>Empty if both states are empty.</p></li>
<li><p>The non-empty state if only one of the two states is non-empty.</p></li>
<li><p>The state with the larger location, if the two states specify
different locations.</p></li>
<li><p>The pair of the location shared by the two states, and the set-union
of their messages for states at the same location.</p></li>
</ol></dd>
<dt><b class="cmd">error_nonterminal</b> <i class="arg">symbol</i></dt>
<dd><p>This is a guarded instruction. It does nothing if either ES is empty,
or if the location in ES is not just past the last location saved in
LS. Otherwise it sets the pair of that location and the nonterminal
<i class="arg">symbol</i> as the new ES.</p>
<p><em>Note</em>: In the above "just past" means "that location plus one",
or also "the location of the next character after that location".</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Status Control</a></h3>
<p>The instructions in this section directly manipulate ST.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">status_ok</b></dt>
<dd><p>This instruction sets ST to <b class="const">true</b>, recording a success.</p></dd>
<dt><b class="cmd">status_fail</b></dt>
<dd><p>This instruction sets ST to <b class="const">false</b>, recording a failure.</p></dd>
<dt><b class="cmd">status_negate</b></dt>
<dd><p>This instruction negates ST, turning a failure into a success and vice
versa.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Location Handling</a></h3>
<p>The instructions in this section access CL and LS.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">loc_push</b></dt>
<dd><p>This instruction makes a copy of CL and pushes it on LS.</p></dd>
<dt><b class="cmd">loc_pop_discard</b></dt>
<dd><p>This instructions pops the last saved location from LS.</p></dd>
<dt><b class="cmd">loc_pop_rewind</b></dt>
<dd><p>This instruction pops the last saved location from LS and restores it
as CL.</p></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Nonterminal Execution</a></h3>
<p>The instructions in this section access and manipulate NC.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">symbol_restore</b> <i class="arg">symbol</i></dt>
<dd><p>This instruction checks if NC contains data for the nonterminal
<i class="arg">symbol</i> at CL, or not. The result of the instruction is a boolean
flag, with <b class="const">True</b> indicating that data was found in the
cache. In that case the instruction has further updated the
architectural state of the machine with the cached information, namely
CL, ST, ER, and SV.</p>
<p>The method with which the instruction's result is transformed into
control flow is left undefined and the responsibility of the
implementation.</p></dd>
<dt><b class="cmd">symbol_save</b> <i class="arg">symbol</i></dt>
<dd><p>This instructions saves the current settings of CL, ST, ER, and SV in
NC, using the pair of nonterminal <i class="arg">symbol</i> and the last location
saved in LS as key.</p></dd>
</dl>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Value Construction</a></h3>
<p>The instructions in this section manipulate SV.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">value_clear</b></dt>
<dd><p>This instruction clears SV.</p></dd>
<dt><b class="cmd">value_leaf</b> <i class="arg">symbol</i></dt>
<dd><p>This instruction constructs an AST node for <i class="arg">symbol</i> covering the
range of IN from one character after the last location saved on LS to
CL and stores it in SV. ...</p></dd>
<dt><b class="cmd">value_reduce</b> <i class="arg">symbol</i></dt>
<dd><p>This instruction generally behaves like <b class="cmd">value_nonterminal_leaf</b>,
except that it takes all AST nodes on ARS, if any, and makes them the
children of the new node, with the last node saved on ARS becoming the
right-most / last child. Note that ARS is not modfied by this
operation.</p></dd>
</dl>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">AST Construction</a></h3>
<p>The instructions in this section manipulate ARS and AS.</p>
<dl class="doctools_definitions">
<dt><b class="cmd">ast_value_push</b></dt>
<dd><p>This instruction makes a copy of SV and pushes it on ARS.</p></dd>
<dt><b class="cmd">ast_push</b></dt>
<dd><p>This instruction pushes the current state of ARS on AS and then clears
ARS.</p></dd>
<dt><b class="cmd">ast_pop_rewind</b></dt>
<dd><p>This instruction pops the last entry saved on AS and restores it as
the new state of ARS.</p></dd>
<dt><b class="cmd">ast_pop_discard</b></dt>
<dd><p>This instruction pops the last entry saved on AS.</p></dd>
</dl>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Control Flow</a></h3>
<p>Normally this section would contain the specifications of the control
flow instructions of the PARAM, i.e. (un)conditional jumps and the
like. However, this part of the PARAM is intentionally left
unspecified. This allows the implementations to freely choose how to
implement control flow.</p>
<p>The implementation of this machine in Parser Tools, i.e the package
<b class="package"><a href="pt_rdengine.html">pt::rde</a></b>, is not only coded in Tcl, but also relies on Tcl
commands to provide it with control flow (instructions).</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Interaction of the Instructions with the Architectural State</a></h2>
<pre class="doctools_example">
Instruction Inputs Outputs
======================= ======================= ====================
ast_pop_discard AS -> AS
ast_pop_rewind AS -> AS, ARS
ast_push ARS, AS -> AS
ast_value_push SV, ARS -> ARS
======================= ======================= ====================
error_clear - -> ER
error_nonterminal sym ER, LS -> ER
error_pop_merge ES, ER -> ER
error_push ES, ER -> ES
======================= ======================= ====================
input_next msg IN -> TC, CL, CC, ST, ER
======================= ======================= ====================
loc_pop_discard LS -> LS
loc_pop_rewind LS -> LS, CL
loc_push CL, LS -> LS
======================= ======================= ====================
status_fail - -> ST
status_negate ST -> ST
status_ok - -> ST
======================= ======================= ====================
symbol_restore sym NC -> CL, ST, ER, SV
symbol_save sym CL, ST, ER, SV LS -> NC
======================= ======================= ====================
test_alnum CC -> ST, ER
test_alpha CC -> ST, ER
test_ascii CC -> ST, ER
test_char char CC -> ST, ER
test_ddigit CC -> ST, ER
test_digit CC -> ST, ER
test_graph CC -> ST, ER
test_lower CC -> ST, ER
test_print CC -> ST, ER
test_punct CC -> ST, ER
test_range chars chare CC -> ST, ER
test_space CC -> ST, ER
test_upper CC -> ST, ER
test_wordchar CC -> ST, ER
test_xdigit CC -> ST, ER
======================= ======================= ====================
value_clear - -> SV
value_leaf symbol LS, CL -> SV
value_reduce symbol ARS, LS, CL -> SV
======================= ======================= ====================
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a>, <a href="../../../../index.html#virtual_machine">virtual machine</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_parse_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
<div class='fossil-doc' data-title='pt_parse_peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt_parse_peg(i) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt_parse_peg - Parser Tools PEG Parser</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Instances API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::parse::peg 1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::parse::peg</b> <span class="opt">?<i class="arg">objectName</i>?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">parse</b> <i class="arg">chan</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">parset</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a class whose instances are parsers for parsing
expression grammars in textual form.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::parse::peg</b> <span class="opt">?<i class="arg">objectName</i>?</span></a></dt>
<dd><p>The class command constructs parser instances, i.e. objects. The
result of the command is the fully-qualified name of the instance
command.</p>
<p>If no <i class="arg">objectName</i> is specified the class will generate and use an
automatic name. If the <i class="arg">objectName</i> was specified, but is not
fully qualified the command will be created in the current namespace.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instances API</a></h2>
<p>All parser instances provide at least the methods shown below:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the parser instance, releasing all claimed memory
and other resources, and deleting the instance command.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">parse</b> <i class="arg">chan</i></a></dt>
<dd><p>This method runs the parser using the contents of <i class="arg">chan</i> as input
(starting at the current location in the channel), until parsing is
not possible anymore, either because parsing has completed, or run
into a syntax error.</p>
<p>Note here that the Parser Tools are based on Tcl 8.5+. In other words,
the channel argument is not restricted to files, sockets, etc. We have
the full power of <i class="term">reflected channels</i> available.</p>
<p>It should also be noted that the parser pulls the characters from the
input stream as it needs them. If a parser created by this package has
to be operated in a push aka event-driven manner it will be necessary
to go to Tcl 8.6+ and use the <b class="package"><a href="../coroutine/coro_auto.html">coroutine::auto</a></b> to wrap it
into a coroutine where <b class="cmd"><a href="../../../../index.html#read">read</a></b> is properly changed for
push-operation.</p>
<p>Upon successful completion the command returns an abstract syntax tree
as its result.
This AST is in the form specified in section
<b class="sectref">AST serialization format</b>.
As a plain nested Tcl-list it can then be processed with any Tcl
commands the user likes, doing transformations, semantic checks, etc.
To help in this the package <b class="package"><a href="pt_astree.html">pt::ast</a></b> provides a set of
convenience commands for validation of the tree's basic structure,
printing it for debugging, and walking it either from the bottom up,
or top down.</p>
<p>When encountering a syntax error the command will throw an error instead.
This error will be a 4-element Tcl-list, containing, in the order
listed below:</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">pt::rde</b> identifying it as parser runtime error.</p></li>
<li><p>The location of the parse error, as character offset from the
beginning of the parsed input.</p></li>
<li><p>The location of parse error, now as a 2-element list containing
line-number and column in the line.</p></li>
<li><p>A set of atomic parsing expressions indicating encoding the characters
and/or nonterminal symbols the parser expected to see at the location
of the parse error, but did not get.
For the specification of atomic parsing expressions please see the
section <b class="sectref">PE serialization format</b>.</p></li>
</ol></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">parset</b> <i class="arg">text</i></a></dt>
<dd><p>This method runs the parser using the string in <i class="arg">text</i> as input.
In all other ways it behaves like the method <b class="method">parse</b>, shown
above.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_parser_api.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
|
<div class='fossil-doc' data-title='pt_parser_api - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt_parser_api(i) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt_parser_api - Parser API</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Instance API</a></li>
<li class="doctools_section"><a href="#section4">Usage</a></li>
<li class="doctools_section"><a href="#section5">AST serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">className</b> <span class="opt">?<i class="arg">objectName</i>?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">parse</b> <i class="arg">chan</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">parset</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This document describes the API shared by the grammar interpreter
provided by the package <b class="package"><a href="pt_peg_interp.html">pt::peg::interp</a></b> and the parsers
generated by the <b class="cmd"><a href="../../apps/pt.html">pt</a></b> application for the result formats
<b class="const">critcl</b>, <b class="const">snit</b>, and <b class="const">oo</b> regarding access
to the actual parsing functionality.</p>
<p>Its intended audience are people who wish to create a parser for some
language of theirs and then use that parser within a Tcl-based package
or application.</p>
<p>It resides in the User Layer of Parser Tools.</p>
<p><img alt="arch_user_pkg" src="../../../../image/arch_user_pkg.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">className</b> <span class="opt">?<i class="arg">objectName</i>?</span></a></dt>
<dd><p>The class command constructs parser instances, i.e. objects. The
result of the command is the fully-qualified name of the instance
command.</p>
<p>If no <i class="arg">objectName</i> is specified the class will generate and use an
automatic name. If the <i class="arg">objectName</i> was specified, but is not
fully qualified the command will be created in the current namespace.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instance API</a></h2>
<p>All parser instances provide at least the methods shown below:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the parser instance, releasing all claimed memory
and other resources, and deleting the instance command.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">parse</b> <i class="arg">chan</i></a></dt>
<dd><p>This method runs the parser using the contents of <i class="arg">chan</i> as input
(starting at the current location in the channel), until parsing is
not possible anymore, either because parsing has completed, or run
into a syntax error.</p>
<p>Note here that the Parser Tools are based on Tcl 8.5+. In other words,
the channel argument is not restricted to files, sockets, etc. We have
the full power of <i class="term">reflected channels</i> available.</p>
<p>It should also be noted that the parser pulls the characters from the
input stream as it needs them. If a parser created by this package has
to be operated in a push aka event-driven manner it will be necessary
to go to Tcl 8.6+ and use the <b class="package"><a href="../coroutine/coro_auto.html">coroutine::auto</a></b> to wrap it
into a coroutine where <b class="cmd"><a href="../../../../index.html#read">read</a></b> is properly changed for
push-operation.</p>
<p>Upon successful completion the command returns an abstract syntax tree
as its result.
This AST is in the form specified in section
<span class="sectref"><a href="#section5">AST serialization format</a></span>.
As a plain nested Tcl-list it can then be processed with any Tcl
commands the user likes, doing transformations, semantic checks, etc.
To help in this the package <b class="package"><a href="pt_astree.html">pt::ast</a></b> provides a set of
convenience commands for validation of the tree's basic structure,
printing it for debugging, and walking it either from the bottom up,
or top down.</p>
<p>When encountering a syntax error the command will throw an error instead.
This error will be a 4-element Tcl-list, containing, in the order
listed below:</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">pt::rde</b> identifying it as parser runtime error.</p></li>
<li><p>The location of the parse error, as character offset from the
beginning of the parsed input.</p></li>
<li><p>The location of parse error, now as a 2-element list containing
line-number and column in the line.</p></li>
<li><p>A set of atomic parsing expressions indicating encoding the characters
and/or nonterminal symbols the parser expected to see at the location
of the parse error, but did not get.
For the specification of atomic parsing expressions please see the
section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></li>
</ol></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">parset</b> <i class="arg">text</i></a></dt>
<dd><p>This method runs the parser using the string in <i class="arg">text</i> as input.
In all other ways it behaves like the method <b class="method">parse</b>, shown
above.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Usage</a></h2>
<p>A generated parser is used like this</p>
<pre class="doctools_example">
package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'.
set parser [the-parser-class]
set ast [$parser parse $channel]
... process the abstract syntax tree ...
</pre>
<p>When using a grammar interpreter for parsing some differences creep in</p>
<pre class="doctools_example">
package require the-grammar-package ;# Generated by result-format 'container' of 'pt'.
set grammar [the-grammar-class]
package require pt::peg::interp
set parser [pt::peg::interp]
$parser use $grammar
set ast [$parser parse $channel]
$parser destroy
... process the abstract syntax tree ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AST serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Abstract Syntax Trees (ASTs) as immutable values for transport,
comparison, etc.</p>
<p>Each node in an AST represents a nonterminal symbol of a grammar, and
the range of tokens/characters in the input covered by it. ASTs do not
contain terminal symbols, i.e. tokens/characters. These can be
recovered from the input given a symbol's location.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a tree may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any AST is the serialization of its root node.</p></li>
<li><p>The serialization of any node is a Tcl list containing at least three
elements.</p>
<ol class="doctools_enumerated">
<li><p>The first element is the name of the nonterminal symbol stored in the
node.</p></li>
<li><p>The second and third element are the locations of the first and last
token in the token stream the node represents (covers).</p>
<ol class="doctools_enumerated">
<li><p>Locations are provided as non-negative integer offsets from the
beginning of the token stream, with the first token found in the
stream located at offset 0 (zero).</p></li>
<li><p>The end location has to be equal to or larger than the start location.</p></li>
</ol>
</li>
<li><p>All elements after the first three represent the children of the node,
which are themselves nodes. This means that the serializations of
nodes without children, i.e. leaf nodes, have exactly three elements.
The children are stored in the list with the leftmost child first, and
the rightmost child last.</p></li>
</ol>
</li>
</ol></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of an abstract syntax tree has the format
as specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this tree.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the parsing expression grammar below</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>and the input string</p>
<pre class="doctools_example"> 120+5 </pre>
<p>then a parser should deliver the abstract syntax tree below (except for whitespace)</p>
<pre class="doctools_example">
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
</pre>
<p>Or, more graphical</p>
<p><img alt="expr_ast" src="../../../../image/expr_ast.png"></p>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
|
<div class='fossil-doc' data-title='pt::peg::container - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::container(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::container - PEG Storage</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Class API</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object API</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection4">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pt::peg::container <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::peg</b> <i class="arg">objectName</i> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const"><--</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">src</i>?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">clear</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">importer</b></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">importer</b> <i class="arg">object</i></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">exporter</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">exporter</b> <i class="arg">object</i></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">=</b> <i class="arg">source</i></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">--></b> <i class="arg">destination</i></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">deserialize =</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">deserialize +=</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">start</b></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">start</b> <i class="arg">pe</i></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">nonterminals</b></a></li>
<li><a href="#16"><i class="arg">objectName</i> <b class="method">modes</b></a></li>
<li><a href="#17"><i class="arg">objectName</i> <b class="method">modes</b> <i class="arg">dict</i></a></li>
<li><a href="#18"><i class="arg">objectName</i> <b class="method">rules</b></a></li>
<li><a href="#19"><i class="arg">objectName</i> <b class="method">rules</b> <i class="arg">dict</i></a></li>
<li><a href="#20"><i class="arg">objectName</i> <b class="method">add</b> <span class="opt">?<i class="arg">nt</i>...?</span></a></li>
<li><a href="#21"><i class="arg">objectName</i> <b class="method">remove</b> <span class="opt">?<i class="arg">nt</i>...?</span></a></li>
<li><a href="#22"><i class="arg">objectName</i> <b class="method">exists</b> <i class="arg">nt</i></a></li>
<li><a href="#23"><i class="arg">objectName</i> <b class="method">rename</b> <i class="arg">ntold</i> <i class="arg">ntnew</i></a></li>
<li><a href="#24"><i class="arg">objectName</i> <b class="method">mode</b> <i class="arg">nt</i></a></li>
<li><a href="#25"><i class="arg">objectName</i> <b class="method">mode</b> <i class="arg">nt</i> <i class="arg">mode</i></a></li>
<li><a href="#26"><i class="arg">objectName</i> <b class="method">rule</b> <i class="arg">nt</i></a></li>
<li><a href="#27"><i class="arg">objectName</i> <b class="method">rule</b> <i class="arg">nt</i> <i class="arg">pe</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a container class for parsing expression
grammars, with each instance storing a single grammar and allowing the
user to manipulate and query its definition.</p>
<p>It resides in the Storage section of the Core Layer of Parser Tools,
and is one of the three pillars the management of parsing expression
grammars resides on.</p>
<p><img alt="arch_core_container" src="../../../../image/arch_core_container.png"></p>
<p>The other two pillars are, as shown above</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="pt_peg_import.html">PEG Import</a></i>, and</p></li>
<li><p><i class="term"><a href="pt_peg_export.html">PEG Export</a></i></p></li>
</ol>
<p>Packages related to this are:</p>
<dl class="doctools_definitions">
<dt><b class="package"><a href="pt_rdengine.html">pt::rde</a></b></dt>
<dd><p>This package provides an implementation of PARAM, a virtual machine
for the parsing of a channel, geared towards the needs of handling
PEGs.</p></dd>
<dt><b class="package"><a href="pt_peg_interp.html">pt::peg::interp</a></b></dt>
<dd><p>This package implements an interpreter for PEGs on top of the virtual
machine provided by <b class="package">pt::peg::rde</b></p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Class API</a></h3>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::peg</b> <i class="arg">objectName</i> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const"><--</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">src</i>?</span></a></dt>
<dd><p>The command creates a new container object for a parsing expression
grammar and returns the fully qualified name of the object command as
its result. The API of this object command is described in the section
<span class="sectref"><a href="#subsection2">Object API</a></span>. It may be used to invoke various operations on
the object.</p>
<p>The new container will be empty if no <i class="arg">src</i> is specified. Otherwise
it will contain a copy of the grammar contained in the <i class="arg">src</i>.
All operators except <b class="const">deserialize</b> interpret <i class="arg">src</i> as a
container object command. The <b class="const">deserialize</b> operator interprets
<i class="arg">src</i> as the serialization of a parsing expression grammar
instead, as specified in section <span class="sectref"><a href="#section2">PEG serialization format</a></span>.</p>
<p>An empty grammar has no nonterminal symbols, and the start expression
is the empty expression, i.e. epsilon. It is <i class="term">valid</i>, but not
<i class="term">useful</i>.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object API</a></h3>
<p>All objects created by this package provide the following methods for
the manipulation and querying of their contents:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object, releasing all claimed memory, and
deleting the associated object command.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">clear</b></a></dt>
<dd><p>This method resets the object to contain the empty grammar. It does
<em>not</em> destroy the object itself.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">importer</b></a></dt>
<dd><p>This method returns the import manager object currently attached to
the container, if any.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">importer</b> <i class="arg">object</i></a></dt>
<dd><p>This method attaches the <i class="arg">object</i> as import manager to the
container, and returns it as the result of the command.
Note that the <i class="arg">object</i> is <em>not</em> put into ownership of the
container. I.e., destruction of the container will <em>not</em> destroy
the <i class="arg">object</i>.</p>
<p>It is expected that <i class="arg">object</i> provides a method named
<b class="method">import text</b> which takes a text and a format name, and
returns the canonical serialization of the table of contents contained in
the text, assuming the given format.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">exporter</b></a></dt>
<dd><p>This method returns the export manager object currently attached to
the container, if any.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">exporter</b> <i class="arg">object</i></a></dt>
<dd><p>This method attaches the <i class="arg">object</i> as export manager to the
container, and returns it as the result of the command.
Note that the <i class="arg">object</i> is <em>not</em> put into ownership of the
container. I.e., destruction of the container will <em>not</em> destroy
the <i class="arg">object</i>.</p>
<p>It is expected that <i class="arg">object</i> provides a method named
<b class="method">export object</b> which takes the container and a format name,
and returns a text encoding table of contents stored in the container, in
the given format. It is further expected that the <i class="arg">object</i> will
use the container's method <b class="method">serialize</b> to obtain the
serialization of the table of contents from which to generate the text.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">=</b> <i class="arg">source</i></a></dt>
<dd><p>This method assigns the contents of the PEG object <i class="arg">source</i> to
ourselves, overwriting the existing definition. This is the assignment
operator for grammars.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">objectName</i> <b class="method">deserialize =</b> [<i class="arg">source</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">--></b> <i class="arg">destination</i></a></dt>
<dd><p>This method assigns our contents to the PEG object <i class="arg">destination</i>,
overwriting the existing definition. This is the reverse assignment
operator for grammars.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">destination</i> <b class="method">deserialize =</b> [<i class="arg">objectName</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method returns our grammar in some textual form usable for
transfer, persistent storage, etc. If no <i class="arg">format</i> is not specified
the returned result is the canonical serialization of the grammar, as
specified in the section <span class="sectref"><a href="#section2">PEG serialization format</a></span>.</p>
<p>Otherwise the object will use the attached export manager to convert
the data to the specified format. In that case the method will fail
with an error if the container has no export manager attached to it.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">deserialize =</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This is the complementary method to <b class="method">serialize</b>.
It replaces the current definition with the grammar contained in the
<i class="arg">data</i>. If no <i class="arg">format</i> was specified it is assumed to be the
regular serialization of a grammar, as specified in the section
<span class="sectref"><a href="#section2">PEG serialization format</a></span></p>
<p>Otherwise the object will use the attached import manager to convert
the data from the specified format to a serialization it can handle.
In that case the method will fail with an error if the container has
no import manager attached to it.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">deserialize +=</b> <i class="arg">data</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">deserialize =</b> in its essentials,
except that it merges the grammar in the <i class="arg">data</i> to its
contents instead of replacing it.
The method will fail with an error and leave the grammar unchanged if
merging is not possible, i.e. would produce an invalid grammar.</p>
<p>The result of the method is the empty string.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">start</b></a></dt>
<dd><p>This method returns the current start expression of the grammar.</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">start</b> <i class="arg">pe</i></a></dt>
<dd><p>This method defines the <i class="term">start expression</i> of the grammar. It
replaces the current start expression with the parsing expression
<i class="arg">pe</i>, and returns the new start expression.</p>
<p>The method will fail with an error and leave the grammar unchanged if
<i class="arg">pe</i> does not contain a valid parsing expression as specified in
the section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">nonterminals</b></a></dt>
<dd><p>This method returns the set of all nonterminal symbols known to the
grammar.</p></dd>
<dt><a name="16"><i class="arg">objectName</i> <b class="method">modes</b></a></dt>
<dd><p>This method returns a dictionary mapping the set of all nonterminal
symbols known to the grammar to their semantic modes.</p></dd>
<dt><a name="17"><i class="arg">objectName</i> <b class="method">modes</b> <i class="arg">dict</i></a></dt>
<dd><p>This method takes a dictionary mapping a set of nonterminal symbols
known to the grammar to their semantic modes, and returns the new full
mapping of nonterminal symbols to semantic modes.</p>
<p>The method will fail with an error if any of the nonterminal symbols
in the dictionary is not known to the grammar, or the empty string,
i.e. an invalid nonterminal symbol, or if any the chosen <i class="arg">mode</i>s
is not one of the legal values.</p></dd>
<dt><a name="18"><i class="arg">objectName</i> <b class="method">rules</b></a></dt>
<dd><p>This method returns a dictionary mapping the set of all nonterminal
symbols known to the grammar to their parsing expressions (right-hand
sides).</p></dd>
<dt><a name="19"><i class="arg">objectName</i> <b class="method">rules</b> <i class="arg">dict</i></a></dt>
<dd><p>This method takes a dictionary mapping a set of nonterminal symbols
known to the grammar to their parsing expressions (right-hand sides),
and returns the new full mapping of nonterminal symbols to parsing
expressions.</p>
<p>The method will fail with an error any of the nonterminal symbols in
the dictionary is not known to the grammar, or the empty string,
i.e. an invalid nonterminal symbol, or any of the chosen parsing
expressions is not a valid parsing expression as specified in the
section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><a name="20"><i class="arg">objectName</i> <b class="method">add</b> <span class="opt">?<i class="arg">nt</i>...?</span></a></dt>
<dd><p>This method adds the nonterminal symbols <i class="arg">nt</i>, etc. to the
grammar, and defines default semantic mode and expression for it
(<b class="const">value</b> and <b class="const">epsilon</b> respectively).
The method returns the empty string as its result.</p>
<p>The method will fail with an error and leaves the grammar unchanged if
any of the nonterminal symbols are either already defined in our
grammar, or are the empty string (an invalid nonterminal symbol).</p>
<p>The method does nothing if no symbol was specified as argument.</p></dd>
<dt><a name="21"><i class="arg">objectName</i> <b class="method">remove</b> <span class="opt">?<i class="arg">nt</i>...?</span></a></dt>
<dd><p>This method removes the named nonterminal symbols <i class="arg">nt</i>, etc. from
the set of nonterminal symbols known to our grammar.
The method returns the empty string as its result.</p>
<p>The method will fail with an error and leave the grammar unchanged if
any of the nonterminal symbols is not known to the grammar, or is the
empty string, i.e. an invalid nonterminal symbol.</p></dd>
<dt><a name="22"><i class="arg">objectName</i> <b class="method">exists</b> <i class="arg">nt</i></a></dt>
<dd><p>This method tests whether the nonterminal symbol <i class="arg">nt</i> is known
to our grammar or not.
The result is a boolean value. It will be set to <b class="const">true</b> if
<i class="arg">nt</i> is known, and <b class="const">false</b> otherwise.</p>
<p>The method will fail with an error if <i class="arg">nt</i> is the empty string,
i.e. an invalid nonterminal symbol.</p></dd>
<dt><a name="23"><i class="arg">objectName</i> <b class="method">rename</b> <i class="arg">ntold</i> <i class="arg">ntnew</i></a></dt>
<dd><p>This method renames the nonterminal symbol <i class="arg">ntold</i> to <i class="arg">ntnew</i>.
The method returns the empty string as its result.</p>
<p>The method will fail with an error and leave the grammar unchanged if
either <i class="arg">ntold</i> is not known to the grammar, or <i class="arg">ntnew</i> is
already known, or any of them is the empty string, i.e. an invalid
nonterminal symbol.</p></dd>
<dt><a name="24"><i class="arg">objectName</i> <b class="method">mode</b> <i class="arg">nt</i></a></dt>
<dd><p>This method returns the current semantic mode for the nonterminal
symbol <i class="arg">nt</i>.</p>
<p>The method will fail with an error if <i class="arg">nt</i> is not known to the
grammar, or the empty string, i.e. an invalid nonterminal symbol.</p></dd>
<dt><a name="25"><i class="arg">objectName</i> <b class="method">mode</b> <i class="arg">nt</i> <i class="arg">mode</i></a></dt>
<dd><p>This mode sets the semantic mode for the nonterminal symbol <i class="arg">nt</i>,
and returns the new mode.
The method will fail with an error if <i class="arg">nt</i> is not known to the
grammar, or the empty string, i.e. an invalid nonterminal symbol, or
the chosen <i class="arg">mode</i> is not one of the legal values.</p>
<p>The following modes are legal:</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
<dt><a name="26"><i class="arg">objectName</i> <b class="method">rule</b> <i class="arg">nt</i></a></dt>
<dd><p>This method returns the current parsing expression (right-hand side)
for the nonterminal symbol <i class="arg">nt</i>.</p>
<p>The method will fail with an error if <i class="arg">nt</i> is not known to the
grammar, or the empty string, i.e. an invalid nonterminal symbol.</p></dd>
<dt><a name="27"><i class="arg">objectName</i> <b class="method">rule</b> <i class="arg">nt</i> <i class="arg">pe</i></a></dt>
<dd><p>This method set the parsing expression (right-hand side) of the
nonterminal <i class="arg">nt</i> to <i class="arg">pe</i>, and returns the new parsing
expression.</p>
<p>The method will fail with an error if <i class="arg">nt</i> is not known to the
grammar, or the empty string, i.e. an invalid nonterminal symbol, or
<i class="arg">pe</i> does not contain a valid parsing expression as specified in
the section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
<div class='fossil-doc' data-title='pt::peg::container::peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::container::peg(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::container::peg - PEG Storage. Canned PEG grammar specification</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">pt::peg::container::peg <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg::container</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a sub-type of <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b> which
is preloaded with a parsing expression grammar describing a textual
format for parsing expression grammars.</p>
<p>The sub-type provides the exact same API as
<b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>. Instead of duplicating its contents the
reader is asked to read the referenced document.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_export.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
|
<div class='fossil-doc' data-title='pt::peg::export - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::export(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::export - PEG Export</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection4">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection5">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">configuration</b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
<li>package require <b class="pkgname">pt::peg::export <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::peg::export</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">export serial</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">export object</b> <i class="arg">object</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">configuration names</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">configuration get</b></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">configuration set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">configuration unset</b> <i class="arg">pattern</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a manager for parsing expression grammars, with
each instance handling a set of plugins for the export of them to
other formats, i.e. their conversion to, for example <i class="term"><a href="../../../../index.html#nroff">nroff</a></i>,
<i class="term"><a href="../../../../index.html#html">HTML</a></i>, etc.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and is one of the three pillars the management of parsing expression
grammars resides on.</p>
<p><img alt="arch_core_export" src="../../../../image/arch_core_export.png"></p>
<p>The other two pillars are, as shown above</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="pt_peg_import.html">PEG Import</a></i>, and</p></li>
<li><p><i class="term"><a href="pt_peg_container.html">PEG Storage</a></i></p></li>
</ol>
<p>For information about the data structure which is the major input to
the manager objects provided by this package see the section
<span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p>
<p>The plugin system of this class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">GRAMMAR_PEG_EXPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">GRAMMAR_PEG_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">GRAMMAR_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/export/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/export/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\EXPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using the Windows(tm) operating system.</p>
<p>The whole system is delivered with three predefined export plugins,
namely</p>
<dl class="doctools_definitions">
<dt>container</dt>
<dd><p>See <i class="term">PEG Export Plugin. To CONTAINER format</i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">PEG Export Plugin. To JSON format</i> for details.</p></dd>
<dt>peg</dt>
<dd><p>See <i class="term">PEG Export Plugin. To PEG format</i> for details.</p></dd>
</dl>
<p>For readers wishing to write their own export plugin for some format,
i.e. <i class="term">plugin writer</i>s, reading and understanding the
<i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i> specification is an absolute
necessity, as it documents the interaction between this package and
its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::peg::export</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new export manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::pt::peg::export</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">export serial</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the canonical serialization of a parsing expression
grammar stored in <i class="arg">serial</i> and converts it to the specified
<i class="arg">format</i>, using the export plugin for the format. This will fail
with an error if no plugin could be found for the format.
The string generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">text</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p>
<p>The plugin has to conform to the interface documented in the
<i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i> specification.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">export object</b> <i class="arg">object</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">export serial</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">serialize</b> method returning the canonical serialization of a
parsing expression grammar. It invokes that method, feeds the result
into <b class="method">export serial</b> and returns the resulting string as its
own result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">configuration names</b></a></dt>
<dd><p>This method returns a list containing the names of all configuration
options currently known to the object.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">configuration get</b></a></dt>
<dd><p>This method returns a dictionary containing the names and values of
all configuration options currently known to the object.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">configuration set</b> <i class="arg">name</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>This method sets the configuration option <i class="arg">name</i> to the
specified <i class="arg">value</i> and returns the new value of the option.</p>
<p>If no value is specified it simply returns the current value, without
changing it.</p>
<p>Note that these configuration options and their values are simply
passed to a plugin when the actual export is performed. It is the
plugin which checks the validity, not the manager.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">configuration unset</b> <i class="arg">pattern</i>...</a></dt>
<dd><p>This method unsets all configuration options matching the specified
glob <i class="arg">pattern</i>s. If no pattern is specified it will unset all
currently defined configuration options.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
|
<div class='fossil-doc' data-title='pt::peg::export::container - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::export::container(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::export::container - PEG Export Plugin. Write CONTAINER format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">Grammar Container</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::export::container <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg::to::container</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the parsing expression grammar export plugin
for the generation of CONTAINER markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools and
is intended to be used by <b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>, the export
manager, sitting between it and the corresponding core conversion
functionality provided by <b class="package"><a href="pt_peg_to_container.html">pt::peg::to::container</a></b>.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
<p>While the direct use of this package with a regular interpreter is
possible, this is strongly disrecommended and requires a number of
contortions to provide the expected environment.
The proper way to use this functionality depends on the situation:</p>
<ol class="doctools_enumerated">
<li><p>In an untrusted environment the proper access is through the package
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b> and the export manager objects it
provides.</p></li>
<li><p>In a trusted environment however simply use the package
<b class="package"><a href="pt_peg_to_container.html">pt::peg::to::container</a></b> and access the core
conversion functionality directly.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Plugin API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates CONTAINER markup encoding the grammar.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The CONTAINER export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>enum <i class="arg">mode</i></dt>
<dd><p>The value of this configuration variable controls which methods of
<b class="package"><a href="pt_pegrammar.html">pt::peg</a></b> instances the plugin will use to specify the
grammar. There are two legal values</p>
<dl class="doctools_definitions">
<dt><b class="const">bulk</b></dt>
<dd><p>In this mode the methods <b class="method">start</b>, <b class="method">add</b>, <b class="method">modes</b>,
and <b class="method">rules</b> are used to specify the grammar in a bulk manner,
i.e. as a set of nonterminal symbols, and two dictionaries mapping
from the symbols to their semantic modes and parsing expressions.</p>
<p>This mode is the default.</p></dd>
<dt><b class="const">incremental</b></dt>
<dd><p>In this mode the methods <b class="method">start</b>, <b class="method">add</b>, <b class="method">mode</b>,
and <b class="method">rule</b> are used to specify the grammar piecemal, with each
nonterminal having its own block of defining commands.</p></dd>
</dl></dd>
<dt>string <i class="arg">template</i></dt>
<dd><p>If this configuration variable is set it is assumed to contain a
string into which to put the generated code and other configuration
data. The various locations are expected to be specified with the
following placeholders:</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">CONTAINER</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">name</b>.</p></dd>
<dt><b class="const">@mode@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">mode</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated code.</p></dd>
</dl>
<p>If this configuration variable is not set, or empty, then the plugin
falls back to a standard template, which is defined as "<b class="const">@code@</b>".</p></dd>
</dl>
<p><em>Note</em> that this plugin may ignore the standard configuration
variables <b class="variable">user</b>, <b class="variable">format</b>, <b class="variable">file</b>, and their values,
depending on the chosen template.</p>
<p>The content of the standard configuration variable <b class="variable">name</b>, if set,
is used as name of the grammar in the output. Otherwise the plugin
falls back to the default name <b class="const">a_pe_grammar</b>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Grammar Container</a></h2>
<p>The <b class="const">container</b> format is another form of describing parsing
expression grammars. While data in this format is executable it does
not constitute a parser for the grammar. It always has to be used in
conjunction with the package <b class="package"><a href="pt_peg_interp.html">pt::peg::interp</a></b>, a grammar
interpreter.</p>
<p>The format represents grammars by a <b class="cmd">snit::type</b>, i.e. class,
whose instances are API-compatible to the instances of the
<b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b> package, and which are preloaded with the
grammar in question.</p>
<p>It has no direct formal specification beyond what was said above.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>one possible CONTAINER serialization for it is</p>
<pre class="doctools_example">
snit::type a_pe_grammar {
constructor {} {
install myg using pt::peg::container ${selfns}::G
$myg start {n Expression}
$myg add AddOp Digit Expression Factor MulOp Number Sign Term
$myg modes {
AddOp value
Digit value
Expression value
Factor value
MulOp value
Number value
Sign value
Term value
}
$myg rules {
AddOp {/ {t -} {t +}}
Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
Factor {x {n Term} {* {x {n AddOp} {n Term}}}}
MulOp {/ {t *} {t /}}
Number {x {? {n Sign}} {+ {n Digit}}}
Sign {/ {t -} {t +}}
Term {n Number}
}
return
}
component myg
delegate method * to myg
}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#container">CONTAINER</a>, <a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
|
<div class='fossil-doc' data-title='pt::peg::export::json - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::export::json(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::export::json - PEG Export Plugin. Write JSON format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">JSON Grammar Exchange Format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::export::json <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg::to::json</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the parsing expression grammar export plugin
for the generation of JSON markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools and
is intended to be used by <b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>, the export
manager, sitting between it and the corresponding core conversion
functionality provided by <b class="package"><a href="pt_peg_to_json.html">pt::peg::to::json</a></b>.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
<p>While the direct use of this package with a regular interpreter is
possible, this is strongly disrecommended and requires a number of
contortions to provide the expected environment.
The proper way to use this functionality depends on the situation:</p>
<ol class="doctools_enumerated">
<li><p>In an untrusted environment the proper access is through the package
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b> and the export manager objects it
provides.</p></li>
<li><p>In a trusted environment however simply use the package
<b class="package"><a href="pt_peg_to_json.html">pt::peg::to::json</a></b> and access the core
conversion functionality directly.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Plugin API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates JSON markup encoding the grammar.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The JSON export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>boolean <i class="arg">indented</i></dt>
<dd><p>If this flag is set the plugin will break the generated JSON code
across lines and indent it according to its inner structure, with each
key of a dictionary on a separate line.</p>
<p>If this flag is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt>boolean <i class="arg">aligned</i></dt>
<dd><p>If this flag is set the generator ensures that the values for the keys
in a dictionary are vertically aligned with each other, for a nice
table effect. To make this work this also implies that <b class="variable">indented</b>
is set.</p>
<p>If this flag is not set (the default), the output is formatted as per
the value of <b class="variable">indented</b>, without trying to align the values for
dictionary keys.</p></dd>
</dl>
<p><em>Note</em> that this plugin ignores the standard configuration
variables <b class="variable">user</b>, <b class="variable">format</b>, <b class="variable">file</b>, and <b class="variable">name</b>, and
their values.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">JSON Grammar Exchange Format</a></h2>
<p>The <b class="const">json</b> format for parsing expression grammars was written as
a data exchange format not bound to Tcl. It was defined to allow the
exchange of grammars with PackRat/PEG based parser generators for
other languages.</p>
<p>It is formally specified by the rules below:</p>
<ol class="doctools_enumerated">
<li><p>The JSON of any PEG is a JSON object.</p></li>
<li><p>This object holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a JSON object itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the
parsing expression describing the symbols sentennial structure, as
specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value is a JSON holding holding one of three values specifying how
a parser should handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol>
<p>As an aside to the advanced reader, this is pretty much the same as
the Tcl serialization of PE grammars, as specified in section
<span class="sectref"><a href="#section5">PEG serialization format</a></span>, except that the Tcl dictionaries
and lists of that format are mapped to JSON objects and arrays. Only
the parsing expressions themselves are not translated further, but
kept as JSON strings containing a nested Tcl list, and there is no
concept of canonicity for the JSON either.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>a JSON serialization for it is</p>
<pre class="doctools_example">
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
</pre>
<p>and a Tcl serialization of the same is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
<p>The similarity of the latter to the JSON should be quite obvious.</p>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
|
<div class='fossil-doc' data-title='pt::peg::export::peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::export::peg(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::export::peg - PEG Export Plugin. Write PEG format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Configuration</a></li>
<li class="doctools_section"><a href="#section4">PEG Specification Language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::export::peg <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg::to::peg</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the parsing expression grammar export plugin
for the generation of PEG markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools and
is intended to be used by <b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>, the export
manager, sitting between it and the corresponding core conversion
functionality provided by <b class="package"><a href="pt_peg_to_peg.html">pt::peg::to::peg</a></b>.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
<p>While the direct use of this package with a regular interpreter is
possible, this is strongly disrecommended and requires a number of
contortions to provide the expected environment.
The proper way to use this functionality depends on the situation:</p>
<ol class="doctools_enumerated">
<li><p>In an untrusted environment the proper access is through the package
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b> and the export manager objects it
provides.</p></li>
<li><p>In a trusted environment however simply use the package
<b class="package"><a href="pt_peg_to_peg.html">pt::peg::to::peg</a></b> and access the core
conversion functionality directly.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Plugin API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#export">export</a></b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, the <i class="arg">configuration</i>, a dictionary,
and generates PEG markup encoding the grammar.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Configuration</a></h2>
<p>The PEG export plugin recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">template</i></dt>
<dd><p>If this configuration variable is set it is assumed to contain a
string into which to put the generated text and other configuration
data. The various locations are expected to be specified with the
following placeholders:</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">PEG</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated text.</p></dd>
</dl>
<p>If this configuration variable is not set, or empty, then the plugin
falls back to a standard template, which is defined as "<b class="const">@code@</b>".</p></dd>
</dl>
<p><em>Note</em> that this plugin may ignore the standard configuration
variables <b class="variable">user</b>, <b class="variable">format</b>, <b class="variable">file</b>, and their values,
depending on the chosen template.</p>
<p>The content of the standard configuration variable <b class="variable">name</b>, if set,
is used as name of the grammar in the output. Otherwise the plugin
falls back to the default name <b class="const">a_pe_grammar</b>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG Specification Language</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
<p>It is formally specified by the grammar shown below, written in
itself. For a tutorial / introduction to the language please go and
read the <i class="term"><a href="pt_peg_language.html">PEG Language Tutorial</a></i>.</p>
<pre class="doctools_example">
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
</pre>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Our example specifies the grammar for a basic 4-operation calculator.</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>Using higher-level features of the notation, i.e. the character
classes (predefined and custom), this example can be rewritten as</p>
<pre class="doctools_example">
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#export">export</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<div class='fossil-doc' data-title='pt::peg::from::container - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::from::container(n) 0 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::from::container - PEG Conversion. From CONTAINER format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package does not exist.
There is no need for it.
The CONTAINER format for parsing expression grammars is a piece of Tcl
code which, then sourced, provides a class whose instances have the
grammar we wish to import loaded.
Another way of looking at this is, the CONTAINER output is its own
import package.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
|
<div class='fossil-doc' data-title='pt::peg::from::json - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::from::json(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::from::json - PEG Conversion. Read JSON format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">JSON Grammar Exchange Format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::from::json <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">json</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::from::json</b> <b class="method">convert</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from JSON markup to
parsing expression grammars.</p>
<p>It resides in the Import section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the import manager provided by
<b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding import plugin
<b class="package"><a href="pt_peg_import_json.html">pt::peg::import::json</a></b> sitting between converter
and import manager.</p>
<p><img alt="arch_core_iplugins" src="../../../../image/arch_core_iplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_from_api.html">Parser Tools Import API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::from::json</b> <b class="method">convert</b> <i class="arg">text</i></a></dt>
<dd><p>This command takes the JSON markup encoding a parsing
expression grammar and contained in <i class="arg">text</i>, and generates the
canonical serialization of said grammar, as specified in section
<span class="sectref"><a href="#section4">PEG serialization format</a></span>.
The created value is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">JSON Grammar Exchange Format</a></h2>
<p>The <b class="const">json</b> format for parsing expression grammars was written as
a data exchange format not bound to Tcl. It was defined to allow the
exchange of grammars with PackRat/PEG based parser generators for
other languages.</p>
<p>It is formally specified by the rules below:</p>
<ol class="doctools_enumerated">
<li><p>The JSON of any PEG is a JSON object.</p></li>
<li><p>This object holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a JSON object itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the
parsing expression describing the symbols sentennial structure, as
specified in the section <span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value is a JSON holding holding one of three values specifying how
a parser should handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section
<span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol>
<p>As an aside to the advanced reader, this is pretty much the same as
the Tcl serialization of PE grammars, as specified in section
<span class="sectref"><a href="#section4">PEG serialization format</a></span>, except that the Tcl dictionaries
and lists of that format are mapped to JSON objects and arrays. Only
the parsing expressions themselves are not translated further, but
kept as JSON strings containing a nested Tcl list, and there is no
concept of canonicity for the JSON either.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>a JSON serialization for it is</p>
<pre class="doctools_example">
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
</pre>
<p>and a Tcl serialization of the same is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
<p>The similarity of the latter to the JSON should be quite obvious.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
|
<div class='fossil-doc' data-title='pt::peg::from::peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::from::peg(n) 1.0.3 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::from::peg - PEG Conversion. Read PEG format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">PEG Specification Language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::from::peg <span class="opt">?1.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::from::peg</b> <b class="method">convert</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from PEG markup to
parsing expression grammars.</p>
<p>It resides in the Import section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the import manager provided by
<b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding import plugin
<b class="package"><a href="pt_peg_import_peg.html">pt::peg::import::peg</a></b> sitting between converter
and import manager.</p>
<p><img alt="arch_core_iplugins" src="../../../../image/arch_core_iplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_from_api.html">Parser Tools Import API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::from::peg</b> <b class="method">convert</b> <i class="arg">text</i></a></dt>
<dd><p>This command takes the PEG markup encoding a parsing
expression grammar and contained in <i class="arg">text</i>, and generates the
canonical serialization of said grammar, as specified in section
<span class="sectref"><a href="#section4">PEG serialization format</a></span>.
The created value is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PEG Specification Language</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
<p>It is formally specified by the grammar shown below, written in
itself. For a tutorial / introduction to the language please go and
read the <i class="term"><a href="pt_peg_language.html">PEG Language Tutorial</a></i>.</p>
<pre class="doctools_example">
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
</pre>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Our example specifies the grammar for a basic 4-operation calculator.</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>Using higher-level features of the notation, i.e. the character
classes (predefined and custom), this example can be rewritten as</p>
<pre class="doctools_example">
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_import.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
|
<div class='fossil-doc' data-title='pt::peg::import - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::import(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::import - PEG Import</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection4">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection5">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">configuration</b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">pluginmgr</b></li>
<li>package require <b class="pkgname">pt::peg::import <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::peg::import</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">includes</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">include clear</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a manager for parsing expression grammars, with
each instance handling a set of plugins for the import of them from
other formats, i.e. their conversion from, for example <i class="term">peg</i>,
<i class="term">container</i>, <i class="term"><a href="../../../../index.html#json">json</a></i>, etc.</p>
<p>It resides in the Import section of the Core Layer of Parser Tools,
and is one of the three pillars the management of parsing expression
grammars resides on.</p>
<p><img alt="arch_core_import" src="../../../../image/arch_core_import.png"></p>
<p>The other two pillars are, as shown above</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="pt_peg_export.html">PEG Export</a></i>, and</p></li>
<li><p><i class="term"><a href="pt_peg_container.html">PEG Storage</a></i></p></li>
</ol>
<p>For information about the data structure which is the major output of
the manager objects provided by this package see the section
<span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p>
<p>The plugin system of our class is based on the package
<b class="package"><a href="../pluginmgr/pluginmgr.html">pluginmgr</a></b>, and configured to look for plugins using</p>
<ol class="doctools_enumerated">
<li><p>the environment variable <b class="variable">GRAMMAR_PEG_IMPORT_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">GRAMMAR_PEG_PLUGINS</b>,</p></li>
<li><p>the environment variable <b class="variable">GRAMMAR_PLUGINS</b>,</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/import/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/plugin</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/import/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/peg/plugins</b>"</p></li>
<li><p>the path "<b class="file">~/.grammar/plugins</b>"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\IMPORT\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"</p></li>
<li><p>the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"</p></li>
</ol>
<p>The last three are used only when the package is run on a machine
using the Windows(tm) operating system.</p>
<p>The whole system is delivered with three predefined import plugins,
namely</p>
<dl class="doctools_definitions">
<dt>container</dt>
<dd><p>See <i class="term"><a href="pt_peg_import_container.html">PEG Import Plugin. From CONTAINER format</a></i> for details.</p></dd>
<dt>json</dt>
<dd><p>See <i class="term">PEG Import Plugin. From JSON format</i> for details.</p></dd>
<dt>peg</dt>
<dd><p>See <i class="term">PEG Import Plugin. From PEG format</i> for details.</p></dd>
</dl>
<p>For readers wishing to write their own import plugin for some format,
i.e. <i class="term">plugin writer</i>s, reading and understanding the
<i class="term">Parser Tools Impport API</i> specification is an absolute
necessity, as it documents the interaction between this package and
its plugins in detail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::peg::import</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new import manager object with an associated
Tcl command whose name is <i class="arg">objectName</i>. This <i class="term"><a href="../../../../index.html#object">object</a></i> command
is explained in full detail in the sections <span class="sectref"><a href="#subsection2">Object command</a></span>
and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The object command will be created
under the current namespace if the <i class="arg">objectName</i> is not fully
qualified, and in the specified namespace otherwise.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::pt::peg::import</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">objectName</b> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object it is invoked for.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">import text</b> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method takes the <i class="arg">text</i> and converts it from the specified
<i class="arg">format</i> to the canonical serialization of a parsing expression
grammar using the import plugin for the format. An error is thrown if
no plugin could be found for the format.
The serialization generated by the conversion process is returned as
the result of this method.</p>
<p>If no format is specified the method defaults to <b class="const">text</b>.</p>
<p>The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p>
<p>The plugin has to conform to the interface documented in the
<i class="term"><a href="pt_from_api.html">Parser Tools Import API</a></i> specification.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">import file</b> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It reads the contents of the specified file into memory, feeds the
result into <b class="method">import text</b> and returns the resulting
serialization as its own result.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">import object text</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method is a convenient wrapper around the <b class="method">import text</b>
method described by the previous item.
It expects that <i class="arg">object</i> is an object command supporting a
<b class="method">deserialize</b> method expecting the canonical serialization of a
parsing expression grammar.
It imports the text using <b class="method">import text</b> and then feeds the
resulting serialization into the <i class="arg">object</i> via <b class="method">deserialize</b>.
This method returns the empty string as it result.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">import object file</b> <i class="arg">object</i> <i class="arg">path</i> <span class="opt">?<i class="arg">format</i>?</span></a></dt>
<dd><p>This method behaves like <b class="method">import object text</b>, except that it
reads the text to convert from the specified file instead of being
given it as argument.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">includes</b></a></dt>
<dd><p>This method returns a list containing the currently specified paths to
use to search for include files when processing input.
The order of paths in the list corresponds to the order in which they
are used, from first to last, and also corresponds to the order in
which they were added to the object.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">include add</b> <i class="arg">path</i></a></dt>
<dd><p>This methods adds the specified <i class="arg">path</i> to the list of paths to use
to search for include files when processing input. The path is added
to the end of the list, causing it to be searched after all previously
added paths. The result of the command is the empty string.</p>
<p>The method does nothing if the path is already known.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">include remove</b> <i class="arg">path</i></a></dt>
<dd><p>This methods removes the specified <i class="arg">path</i> from the list of paths
to use to search for include files when processing input. The result
of the command is the empty string.</p>
<p>The method does nothing if the path is not known.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">include clear</b></a></dt>
<dd><p>This method clears the list of paths to use to search for include
files when processing input. The result of the command is the empty
string.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<div class='fossil-doc' data-title='pt::peg::import::container - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::import::container(n) 0 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::import::container - PEG Import Plugin. From CONTAINER format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package does not exist.
There is no need for it.
The CONTAINER format for parsing expression grammars is a piece of Tcl
code which, then sourced, provides a class whose instances have the
grammar we wish to import loaded.
Another way of looking at this is, the CONTAINER output is its own
import package.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
|
<div class='fossil-doc' data-title='pt::peg::import::json - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::import::json(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::import::json - PEG Import Plugin. Read JSON format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">JSON Grammar Exchange Format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::import::json <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg::to::json</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the parsing expression grammar import plugin
processing JSON markup.</p>
<p>It resides in the Import section of the Core Layer of Parser Tools and
is intended to be used by <b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b>, the import
manager, sitting between it and the corresponding core conversion
functionality provided by <b class="package"><a href="pt_peg_from_json.html">pt::peg::from::json</a></b>.</p>
<p><img alt="arch_core_iplugins" src="../../../../image/arch_core_iplugins.png"></p>
<p>While the direct use of this package with a regular interpreter is
possible, this is strongly disrecommended and requires a number of
contortions to provide the expected environment.
The proper way to use this functionality depends on the situation:</p>
<ol class="doctools_enumerated">
<li><p>In an untrusted environment the proper access is through the package
<b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b> and the import manager objects it
provides.</p></li>
<li><p>In a trusted environment however simply use the package
<b class="package"><a href="pt_peg_from_json.html">pt::peg::from::json</a></b> and access the core
conversion functionality directly.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Plugin API found in the <i class="term"><a href="pt_from_api.html">Parser Tools Import API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i></a></dt>
<dd><p>This command takes the JSON markup encoding a parsing
expression grammar and contained in <i class="arg">text</i>, and generates the
canonical serialization of said grammar, as specified in section
<span class="sectref"><a href="#section4">PEG serialization format</a></span>.
The created value is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">JSON Grammar Exchange Format</a></h2>
<p>The <b class="const">json</b> format for parsing expression grammars was written as
a data exchange format not bound to Tcl. It was defined to allow the
exchange of grammars with PackRat/PEG based parser generators for
other languages.</p>
<p>It is formally specified by the rules below:</p>
<ol class="doctools_enumerated">
<li><p>The JSON of any PEG is a JSON object.</p></li>
<li><p>This object holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a JSON object itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the
parsing expression describing the symbols sentennial structure, as
specified in the section <span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value is a JSON holding holding one of three values specifying how
a parser should handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section
<span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol>
<p>As an aside to the advanced reader, this is pretty much the same as
the Tcl serialization of PE grammars, as specified in section
<span class="sectref"><a href="#section4">PEG serialization format</a></span>, except that the Tcl dictionaries
and lists of that format are mapped to JSON objects and arrays. Only
the parsing expressions themselves are not translated further, but
kept as JSON strings containing a nested Tcl list, and there is no
concept of canonicity for the JSON either.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>a JSON serialization for it is</p>
<pre class="doctools_example">
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
</pre>
<p>and a Tcl serialization of the same is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
<p>The similarity of the latter to the JSON should be quite obvious.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
|
<div class='fossil-doc' data-title='pt::peg::import::peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::import::peg(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::import::peg - PEG Import Plugin. Read PEG format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">PEG Specification Language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::import::peg <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg::to::peg</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the parsing expression grammar import plugin
processing PEG markup.</p>
<p>It resides in the Import section of the Core Layer of Parser Tools and
is intended to be used by <b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b>, the import
manager, sitting between it and the corresponding core conversion
functionality provided by <b class="package"><a href="pt_peg_from_peg.html">pt::peg::from::peg</a></b>.</p>
<p><img alt="arch_core_iplugins" src="../../../../image/arch_core_iplugins.png"></p>
<p>While the direct use of this package with a regular interpreter is
possible, this is strongly disrecommended and requires a number of
contortions to provide the expected environment.
The proper way to use this functionality depends on the situation:</p>
<ol class="doctools_enumerated">
<li><p>In an untrusted environment the proper access is through the package
<b class="package"><a href="pt_peg_import.html">pt::peg::import</a></b> and the import manager objects it
provides.</p></li>
<li><p>In a trusted environment however simply use the package
<b class="package"><a href="pt_peg_from_peg.html">pt::peg::from::peg</a></b> and access the core
conversion functionality directly.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Plugin API found in the <i class="term"><a href="pt_from_api.html">Parser Tools Import API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../../index.html#import">import</a></b> <i class="arg">text</i></a></dt>
<dd><p>This command takes the PEG markup encoding a parsing
expression grammar and contained in <i class="arg">text</i>, and generates the
canonical serialization of said grammar, as specified in section
<span class="sectref"><a href="#section4">PEG serialization format</a></span>.
The created value is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PEG Specification Language</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
<p>It is formally specified by the grammar shown below, written in
itself. For a tutorial / introduction to the language please go and
read the <i class="term"><a href="pt_peg_language.html">PEG Language Tutorial</a></i>.</p>
<pre class="doctools_example">
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
</pre>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Our example specifies the grammar for a basic 4-operation calculator.</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>Using higher-level features of the notation, i.e. the character
classes (predefined and custom), this example can be rewritten as</p>
<pre class="doctools_example">
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section5">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#import">import</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#plugin">plugin</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_interp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
|
<div class='fossil-doc' data-title='pt::peg::interp - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::interp(n) 1.0.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::interp - Interpreter for parsing expression grammars</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Class API</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object API</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">AST serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection4">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::interp <span class="opt">?1.0.1?</span></b></li>
<li>package require <b class="pkgname">pt::rde <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::peg::interp</b> <i class="arg">objectName</i> <i class="arg">grammar</i></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">use</b> <i class="arg">grammar</i></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">parse</b> <i class="arg">chan</i></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">parset</b> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a class whose instances are Packrat parsers
configurable with a parsing expression grammar. The grammar is
executed directly, i.e. interpreted, with the underlying runtime
provided by the package <b class="package"><a href="pt_rdengine.html">pt::rde</a></b>, basing everything on the
PARAM.</p>
<p>Like the supporting runtime this package resides in the Execution
section of the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_transform" src="../../../../image/arch_core_transform.png"></p>
<p>The interpreted grammar is copied from an instance of <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>, or anything providing the same API, like the
container classes created by <b class="package"><a href="pt_peg_to_container.html">pt::peg::to::container</a></b> or the
associated export plugin <b class="package"><a href="pt_peg_export_container.html">pt::peg::export::container</a></b>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Class API</a></h3>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::peg::interp</b> <i class="arg">objectName</i> <i class="arg">grammar</i></a></dt>
<dd><p>The command creates a new parser object and returns the fully
qualified name of the object command as its result. The API of this
object command is described in the section <span class="sectref"><a href="#subsection2">Object API</a></span>. It
may be used to invoke various operations on the object.</p>
<p>This new parser is configured for the execution of an empty PEG. To
configure the object for any other PEG use the method <b class="method">use</b> of
the <span class="sectref"><a href="#subsection2">Object API</a></span>.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object API</a></h3>
<p>All objects created by this package provide the following methods.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">use</b> <i class="arg">grammar</i></a></dt>
<dd><p>This method configures the grammar interpreter / parser for the
execution of the PEG stored in <i class="arg">grammar</i>, an object which is
API-compatible to instances of <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>. The
parser copies the relevant information of the grammar, and does
<em>not</em> take ownership of the object.</p>
<p>The information of any previously used grammar is overwritten.</p>
<p>The result of the method the empty string.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the parser instance, releasing all claimed memory
and other resources, and deleting the instance command.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">parse</b> <i class="arg">chan</i></a></dt>
<dd><p>This method runs the parser using the contents of <i class="arg">chan</i> as input
(starting at the current location in the channel), until parsing is
not possible anymore, either because parsing has completed, or run
into a syntax error.</p>
<p>Note here that the Parser Tools are based on Tcl 8.5+. In other words,
the channel argument is not restricted to files, sockets, etc. We have
the full power of <i class="term">reflected channels</i> available.</p>
<p>It should also be noted that the parser pulls the characters from the
input stream as it needs them. If a parser created by this package has
to be operated in a push aka event-driven manner it will be necessary
to go to Tcl 8.6+ and use the <b class="package"><a href="../coroutine/coro_auto.html">coroutine::auto</a></b> to wrap it
into a coroutine where <b class="cmd"><a href="../../../../index.html#read">read</a></b> is properly changed for
push-operation.</p>
<p>Upon successful completion the command returns an abstract syntax tree
as its result.
This AST is in the form specified in section
<span class="sectref"><a href="#section2">AST serialization format</a></span>.
As a plain nested Tcl-list it can then be processed with any Tcl
commands the user likes, doing transformations, semantic checks, etc.
To help in this the package <b class="package"><a href="pt_astree.html">pt::ast</a></b> provides a set of
convenience commands for validation of the tree's basic structure,
printing it for debugging, and walking it either from the bottom up,
or top down.</p>
<p>When encountering a syntax error the command will throw an error instead.
This error will be a 4-element Tcl-list, containing, in the order
listed below:</p>
<ol class="doctools_enumerated">
<li><p>The string <b class="const">pt::rde</b> identifying it as parser runtime error.</p></li>
<li><p>The location of the parse error, as character offset from the
beginning of the parsed input.</p></li>
<li><p>The location of parse error, now as a 2-element list containing
line-number and column in the line.</p></li>
<li><p>A set of atomic parsing expressions indicating encoding the characters
and/or nonterminal symbols the parser expected to see at the location
of the parse error, but did not get.
For the specification of atomic parsing expressions please see the
section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></li>
</ol></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">parset</b> <i class="arg">text</i></a></dt>
<dd><p>This method runs the parser using the string in <i class="arg">text</i> as input.
In all other ways it behaves like the method <b class="method">parse</b>, shown
above.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">AST serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Abstract Syntax Trees (ASTs) as immutable values for transport,
comparison, etc.</p>
<p>Each node in an AST represents a nonterminal symbol of a grammar, and
the range of tokens/characters in the input covered by it. ASTs do not
contain terminal symbols, i.e. tokens/characters. These can be
recovered from the input given a symbol's location.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a tree may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any AST is the serialization of its root node.</p></li>
<li><p>The serialization of any node is a Tcl list containing at least three
elements.</p>
<ol class="doctools_enumerated">
<li><p>The first element is the name of the nonterminal symbol stored in the
node.</p></li>
<li><p>The second and third element are the locations of the first and last
token in the token stream the node represents (covers).</p>
<ol class="doctools_enumerated">
<li><p>Locations are provided as non-negative integer offsets from the
beginning of the token stream, with the first token found in the
stream located at offset 0 (zero).</p></li>
<li><p>The end location has to be equal to or larger than the start location.</p></li>
</ol>
</li>
<li><p>All elements after the first three represent the children of the node,
which are themselves nodes. This means that the serializations of
nodes without children, i.e. leaf nodes, have exactly three elements.
The children are stored in the list with the leftmost child first, and
the rightmost child last.</p></li>
</ol>
</li>
</ol></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of an abstract syntax tree has the format
as specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this tree.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression grammar below</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>and the input string</p>
<pre class="doctools_example"> 120+5 </pre>
<p>then a parser should deliver the abstract syntax tree below (except for whitespace)</p>
<pre class="doctools_example">
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
</pre>
<p>Or, more graphical</p>
<p><img alt="expr_ast" src="../../../../image/expr_ast.png"></p>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
<div class='fossil-doc' data-title='pt::pegrammar - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::pegrammar(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::pegrammar - Introduction to Parsing Expression Grammars</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Formal definition</a></li>
<li class="doctools_section"><a href="#section3">References</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>Welcome to the introduction to <i class="term"><a href="../../../../index.html#parsing_expression_grammar">Parsing Expression Grammar</a></i>s
(short: <i class="term"><a href="../../../../index.html#peg">PEG</a></i>), the formalism used by the Parser Tools.
It is assumed that the reader has a basic knowledge of parsing theory,
i.e. <i class="term">Context-Free Grammars</i> (short: <i class="term"><a href="../../../../index.html#cfg">CFG</a></i>),
<i class="term">languages</i>, and associated terms like <i class="term"><a href="../../../../index.html#ll_k_">LL(k)</a></i>,
<i class="term">LR(k)</i>, <i class="term"><a href="../../../../index.html#terminal">terminal</a></i> and <i class="term">nonterminal</i> <i class="term">symbols</i>,
etc.
We do not intend to recapitulate such basic definitions or terms like
<i class="term">useful</i>, <i class="term">reachable</i>, (left/right) <i class="term">recursive</i>,
<i class="term">nullable</i>, first/last/follow sets, etc.
Please see the <span class="sectref"><a href="#section3">References</a></span> at the end instead if you are in
need of places and books which provide such background information.</p>
<p>PEGs are formally very similar to CFGs, with terminal and nonterminal
symbols, start symbol, and rules defining the structure of each
nonterminal symbol.
The main difference lies in the choice(sic!) of <i class="term">choice</i>
operators. Where CFGs use an <i class="term">unordered choice</i> to represent
alternatives PEGs use <i class="term">prioritized choice</i>. Which is fancy way
of saying that a parser has to try the first alternative first and can
try the other alternatives if only if it fails for the first, and so
on.</p>
<p>On the CFG side this gives rise to LL(k) and LR(k) for making the
choice <i class="term">deterministic</i> with a bounded <i class="term">lookahead</i> of k
terminal symbols, where LL is in essence <i class="term">topdown</i> aka
<i class="term"><a href="../../../../index.html#recursive_descent">recursive descent</a></i> parsing, and LR <i class="term">bottomup</i> aka
<i class="term">shift reduce</i> parsing.</p>
<p>On the PEG side we can parse input with recursive descent and
<i class="term">backtracking</i> of failed choices, the latter of which amounts to
unlimited lookahead.
By additionally recording the success or failure of nonterminals at
the specific locations they were tried at and reusing this information
after backtracking we can avoid the exponential blowup of running time
usually associated with backtracking and keep the parsing linear. The
memory requirements are of course higher due to this cache, as we are
trading space for time.</p>
<p>This is the basic concept behind <i class="term">packrat parsers</i>.</p>
<p>A limitation pure PEGs share with LL(k) CFGs is that
<i class="term">left-recursive</i> grammars cannot be parsed, with the associated
recursive descent parser entering an infinite recursion.
This limitation is usually overcome by extending pure PEGs with
explicit operators to specify repetition, zero or more, and one or
more, or, formally spoken, for the <i class="term">kleene closure</i> and
<i class="term">positive kleene closure</i>.
This is what the Parser Tools are doing.</p>
<p>Another extension, specific to Parser Tools, is a set of operators
which map more or less directly to various character classes built
into Tcl, i.e. the classes reachable via <b class="cmd">string is</b>.</p>
<p>The remainder of this document consists of the formal definition of
PEGs for the mathematically inclined, and an appendix listing
references to places with more information on PEGs specifically, and
parsing in general.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Formal definition</a></h2>
<p>For the mathematically inclined, a Parsing Expression Grammar is a
4-tuple (VN,VT,R,eS) where</p>
<ul class="doctools_itemized">
<li><p>VN is a set of <i class="term">nonterminal symbols</i>,</p></li>
<li><p>VT is a set of <i class="term">terminal symbols</i>,</p></li>
<li><p>R is a finite set of rules, where each rule is a pair (A,e), A in VN,
and <i class="term"><a href="../../../../index.html#e">e</a></i> a <i class="term"><a href="../../../../index.html#parsing_expression">parsing expression</a></i>.</p></li>
<li><p>eS is a parsing expression, the <i class="term">start expression</i>.</p></li>
</ul>
<p>Further constraints are</p>
<ul class="doctools_itemized">
<li><p>The intersection of VN and VT is empty.</p></li>
<li><p>For all A in VT exists exactly one pair (A,e) in R. In other words, R
is a function from nonterminal symbols to parsing expressions.</p></li>
</ul>
<p>Parsing expressions are inductively defined via</p>
<ul class="doctools_itemized">
<li><p>The empty string (epsilon) is a parsing expression.</p></li>
<li><p>A terminal symbol <i class="term">a</i> is a parsing expression.</p></li>
<li><p>A nonterminal symbol <i class="term">A</i> is a parsing expression.</p></li>
<li><p><i class="term">e1</i><i class="term">e2</i> is a parsing expression for parsing expressions
<i class="term">e1</i> and <i class="term">2</i>. This is called <i class="term">sequence</i>.</p></li>
<li><p><i class="term">e1</i>/<i class="term">e2</i> is a parsing expression for parsing expressions
<i class="term">e1</i> and <i class="term">2</i>. This is called <i class="term">ordered choice</i>.</p></li>
<li><p><i class="term"><a href="../../../../index.html#e">e</a></i>* is a parsing expression for parsing expression
<i class="term"><a href="../../../../index.html#e">e</a></i>. This is called <i class="term">zero-or-more repetitions</i>, also known
as <i class="term">kleene closure</i>.</p></li>
<li><p><i class="term"><a href="../../../../index.html#e">e</a></i>+ is a parsing expression for parsing expression
<i class="term"><a href="../../../../index.html#e">e</a></i>. This is called <i class="term">one-or-more repetitions</i>, also known
as <i class="term">positive kleene closure</i>.</p></li>
<li><p>!<i class="term"><a href="../../../../index.html#e">e</a></i> is a parsing expression for parsing expression
<i class="term">e1</i>. This is called a <i class="term">not lookahead predicate</i>.</p></li>
<li><p>&<i class="term"><a href="../../../../index.html#e">e</a></i> is a parsing expression for parsing expression
<i class="term">e1</i>. This is called an <i class="term">and lookahead predicate</i>.</p></li>
</ul>
<p>PEGs are used to define a grammatical structure for streams of symbols
over VT. They are a modern phrasing of older formalisms invented by
Alexander Birham. These formalisms were called TS (TMG recognition
scheme), and gTS (generalized TS). Later they were renamed to TPDL
(Top-Down Parsing Languages) and gTPDL (generalized TPDL).</p>
<p>They can be easily implemented by recursive descent parsers with
backtracking. This makes them relatives of LL(k) Context-Free
Grammars.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://www.pdos.lcs.mit.edu/~baford/packrat/">The Packrat Parsing and Parsing Expression Grammars Page</a>,
by Bryan Ford, Massachusetts Institute of Technology. This is the main
entry page to PEGs, and their realization through Packrat Parsers.</p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Parsing_expression_grammar">http://en.wikipedia.org/wiki/Parsing_expression_grammar</a>
Wikipedia's entry about Parsing Expression Grammars.</p></li>
<li><p><a href="http://www.cs.vu.nl/~dick/PTAPG.html">Parsing Techniques - A Practical Guide </a>, an online book
offering a clear, accessible, and thorough discussion of many
different parsing techniques with their interrelations and
applicabilities, including error recovery techniques.</p></li>
<li><p><a href="http://scifac.ru.ac.za/compilers/">Compilers and Compiler Generators</a>, an online book using
CoCo/R, a generator for recursive descent parsers.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_language.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
|
<div class='fossil-doc' data-title='pt::peg_language - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg_language(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg_language - PEG Language Tutorial</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">What is it?</a></li>
<li class="doctools_section"><a href="#section3">The elements of the language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Basic structure</a></li>
<li class="doctools_subsection"><a href="#subsection2">Names</a></li>
<li class="doctools_subsection"><a href="#subsection3">Rules</a></li>
<li class="doctools_subsection"><a href="#subsection4">Expressions</a></li>
<li class="doctools_subsection"><a href="#subsection5">Whitespace and comments</a></li>
<li class="doctools_subsection"><a href="#subsection6">Nonterminal attributes</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PEG Specification Language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection7">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>Welcome to the tutorial / introduction for the
<span class="sectref"><a href="#section4">PEG Specification Language</a></span>.
If you are already familiar with the language we are about to discuss,
and only wish to refresh your memory you can, of course, skip ahead to
the aforementioned section and just read the full formal specification.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">What is it?</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">The elements of the language</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Basic structure</a></h3>
<p>The general outline of a textual PEG is</p>
<pre class="doctools_example">
PEG <<name>> (<<start-expression>>)
<<rules>>
END;
</pre>
<p><em>Note</em>: We are using text in double angle-brackets as
place-holders for things not yet explained.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Names</a></h3>
<p>Names are mostly used to identify the nonterminal symbols of the
grammar, i.e. that which occurs on the left-hand side of a <rule>.
The exception to that is the name given after the keyword <b class="const">PEG</b>
(see previous section), which is the name of the whole grammar itself.</p>
<p>The structure of a name is simple:</p>
<ol class="doctools_enumerated">
<li><p>It begins with a letter, underscore, or colon, followed by</p></li>
<li><p>zero or more letters, digits, underscores, or colons.</p></li>
</ol>
<p>Or, in formal textual notation:</p>
<pre class="doctools_example">
([_:] / <alpha>) ([_:] / <alnum>)*
</pre>
<p>Examples of names:</p>
<pre class="doctools_example">
Hello
::world
_:submarine55_
</pre>
<p>Examples of text which are <em>not</em> names:</p>
<pre class="doctools_example">
12
.bogus
0wrong
@location
</pre>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Rules</a></h3>
<p>The main body of the text of a grammar specification is taken up by
the rules. Each rule defines the sentence structure of one nonterminal
symbol. Their basic structure is</p>
<pre class="doctools_example">
<<name>> <- <<expression>> ;
</pre>
<p>The <name> specifies the nonterminal symbol to be defined, the
<expression> after the arrow (<-) then declares its structure.</p>
<p>Note that each rule ends in a single semicolon, even the last.
I.e. the semicolon is a rule <em>terminator</em>, not a separator.</p>
<p>We can have as many rules as we like, as long as we define each
nonterminal symbol at most once, and have at least one rule for each
nonterminal symbol which occured in an expression, i.e. in either the
start expression of the grammar, or the right-hande side of a rule.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Expressions</a></h3>
<p>The <em>parsing</em> expressions are the meat of any specification. They
declare the structure of the whole document (<<start-expression>>),
and of all nonterminal symbols.</p>
<p>All expressions are made up out of <i class="term">atomic expressions</i> and
<i class="term">operators</i> combining them. We have operators for choosing
between alternatives, repetition of parts, and for look-ahead
constraints. There is no explicit operator for the sequencing (also
known as <i class="term">concatenation</i>) of parts however. This is specified by
simply placing the parts adjacent to each other.</p>
<p>Here are the operators, from highest to lowest priority (i.e. strength
of binding):</p>
<pre class="doctools_example">
# Binary operators.
<<expression-1>> <<expression-2>> # sequence. parse 1, then 2.
<<expression-1>> / <<expression-2>> # alternative. try to parse 1, and parse 2 if 1 failed to parse.
# Prefix operators. Lookahead constraints. Same priority.
& <<expression>> # Parse expression, ok on successful parse.
! <<expression>> # Ditto, except ok on failure to parse.
# Suffix operators. Repetition. Same priority.
<<expression>> ? # Parse expression none, or once (repeat 0 or 1).
<<expression>> * # Parse expression zero or more times.
<<expression>> + # Parse expression one or more times.
# Expression nesting
( <<expression>> ) # Put an expression in parens to change its priority.
</pre>
<p>With this we can now deconstruct the formal expression for names given
in section <span class="sectref"><a href="#subsection2">Names</a></span>:</p>
<pre class="doctools_example">
([_:] / <alpha>) ([_:] / <alnum>)*
</pre>
<p>It is a sequence of two parts,</p>
<pre class="doctools_example"> [_:] / <alpha> </pre>
<p>and</p>
<pre class="doctools_example"> ([_:] / <alnum>)* </pre>
<p>The parentheses around the parts kept their inner alternatives bound
together against the normally higher priority of the sequence. Each of
the two parts is an alternative, with the second part additionally
repeated zero or more times, leaving us with the three atomic
expressions</p>
<pre class="doctools_example">
[_:]
<alpha>
<alnum>
</pre>
<p>And <i class="term">atomic expressions</i> are our next topic. They
fall into three classes:</p>
<ol class="doctools_enumerated">
<li><p>names, i.e. nonterminal symbols,</p></li>
<li><p>string literals, and</p></li>
<li><p>character classes.</p></li>
</ol>
<p>Names we know about already, or see section <span class="sectref"><a href="#subsection2">Names</a></span> for a
refresher.</p>
<p>String literals are simple. They are delimited by (i.e. start and end
with) either a single or double-apostroph, and in between the
delimiters we can have any character but the delimiter itself. They
can be empty as well. Examples of strings are</p>
<pre class="doctools_example">
''
""
'hello'
"umbra"
"'"
'"'
</pre>
<p>The last two examples show how to place any of the delimiters into a
string.</p>
<p>For the last, but not least of our atomic expressions, character
classes, we have a number of predefined classes, shown below, and the
ability to construct or own. The predefined classes are:</p>
<pre class="doctools_example">
<alnum> # Any unicode alphabet or digit character (string is alnum).
<alpha> # Any unicode alphabet character (string is alpha).
<ascii> # Any unicode character below codepoint 0x80 (string is ascii).
<control> # Any unicode control character (string is control).
<ddigit> # The digit characters [0-9].
<digit> # Any unicode digit character (string is digit).
<graph> # Any unicode printing character, except space (string is graph).
<lower> # Any unicode lower-case alphabet character (string is lower).
<print> # Any unicode printing character, incl. space (string is print).
<punct> # Any unicode punctuation character (string is punct).
<space> # Any unicode space character (string is space).
<upper> # Any unicode upper-case alphabet character (string is upper).
<wordchar> # Any unicode word character (string is wordchar).
<xdigit> # The hexadecimal digit characters [0-9a-fA-F].
. # Any character, except end of input.
</pre>
<p>And the syntax of custom-defined character classes is</p>
<pre class="doctools_example">
[ <<range>>* ]
</pre>
<p>where each range is either a single character, or of the form</p>
<pre class="doctools_example">
<<character>> - <character>>
</pre>
<p>Examples for character classes we have seen already in the course of
this introduction are</p>
<pre class="doctools_example">
[_:]
[0-9]
[0-9a-fA-F]
</pre>
<p>We are nearly done with expressions. The only piece left is to tell
how the characters in character classes and string literals are
specified.</p>
<p>Basically characters in the input stand for themselves, and in
addition to that we several types of escape syntax to to repesent
control characters, or characters outside of the encoding the text is
in.</p>
<p>All the escaped forms are started with a backslash character ('\',
unicode codepoint 0x5C). This is then followed by a series of octal
digits, or 'u' and hexedecimal digits, or a regular character from a
fixed set for various control characters. Some examples:</p>
<pre class="doctools_example">
\n \r \t \' \" \[ \] \\ #
\000 up to \277 # octal escape, all ascii character, leading 0's can be removed.
\u2CA7 # hexadecimal escape, all unicode characters.
# # Here 2ca7 <=> Koptic Small Letter Tau
</pre>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Whitespace and comments</a></h3>
<p>One issue not touched upon so far is whitespace and comments.</p>
<p>Whitespace is any unicode space character, i.e. anything in the
character class <space>, and comments. The latter are sequences of
characters starting with a '#' (hash, unicode codepoint 0x23) and
ending at the next end-of-line.</p>
<p>Whitespace can be freely used between all syntactical elements of a
grammar specification. It cannot be used inside of syntactical
elements, like names, string literals, predefined character classes,
etc.</p>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Nonterminal attributes</a></h3>
<p>Lastly, a more advanced topic. In the section <span class="sectref"><a href="#subsection3">Rules</a></span> we gave
the structure of a rule as</p>
<pre class="doctools_example">
<<name>> <- <<expression>> ;
</pre>
<p>This is not quite true. It is possible to associate a semantic mode
with the nonterminal in the rule, by writing it before the name,
separated from it by a colon, i.e. writing</p>
<pre class="doctools_example">
<<mode>> : <<name>> <- <<expression>> ;
</pre>
<p>is also allowed. This mode is optional. The known modes and their
meanings are:</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl>
<p>Of these three modes only <b class="const">leaf</b> and <b class="const">void</b> can be
specified directly. <b class="const">value</b> is implicitly specified by the
absence of a mode before the nonterminal.</p>
<p>Now, with all the above under our belt it should be possible to not
only read, but understand the formal specification of the text
representation shown in the next section, written in itself.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG Specification Language</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
<p>It is formally specified by the grammar shown below, written in
itself. For a tutorial / introduction to the language please go and
read the <i class="term">PEG Language Tutorial</i>.</p>
<pre class="doctools_example">
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
</pre>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Example</a></h3>
<p>Our example specifies the grammar for a basic 4-operation calculator.</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>Using higher-level features of the notation, i.e. the character
classes (predefined and custom), this example can be rewritten as</p>
<pre class="doctools_example">
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_op.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
<div class='fossil-doc' data-title='pt_peg_op - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt_peg_op(i) 1.1.0 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt_peg_op - Parser Tools PE Grammar Utility Operations</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::op <span class="opt">?1.1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::peg::peg::op</b> <b class="method">called</b> <i class="arg">container</i></a></li>
<li><a href="#2"><b class="cmd">::peg::peg::op</b> <b class="method">dechain</b> <i class="arg">container</i></a></li>
<li><a href="#3"><b class="cmd">::peg::peg::op</b> <b class="method">drop unreachable</b> <i class="arg">container</i></a></li>
<li><a href="#4"><b class="cmd">::peg::peg::op</b> <b class="method">drop unrealizable</b> <i class="arg">container</i></a></li>
<li><a href="#5"><b class="cmd">::peg::peg::op</b> <b class="method">flatten</b> <i class="arg">container</i></a></li>
<li><a href="#6"><b class="cmd">::peg::peg::op</b> <b class="method">minimize</b> <i class="arg">container</i></a></li>
<li><a href="#7"><b class="cmd">::peg::peg::op</b> <b class="method">modeopt</b> <i class="arg">container</i></a></li>
<li><a href="#8"><b class="cmd">::peg::peg::op</b> <b class="method">reachable</b> <i class="arg">container</i></a></li>
<li><a href="#9"><b class="cmd">::peg::peg::op</b> <b class="method">realizable</b> <i class="arg">container</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a number of utility commands manipulating a PE
grammar (container) in various ways.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::peg::peg::op</b> <b class="method">called</b> <i class="arg">container</i></a></dt>
<dd><p>This command determines the static call structure for the nonterminal
symbols of the grammar stored in the <i class="arg">container</i>.</p>
<p>The result of the command is a dictionary mapping from each
symbol to the symbols it calls. The empty string is the key used to
represent the start expression of the grammar.</p>
<p>The grammar in the container is not modified.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="2"><b class="cmd">::peg::peg::op</b> <b class="method">dechain</b> <i class="arg">container</i></a></dt>
<dd><p>This command simplifies all symbols which just chain to a different
symbol by inlining the right hand side of the called symbol in its
callers. This works if and only the modes match properly, per the
decision table below.</p>
<pre class="doctools_example">
caller called | dechain | notes
--------------+---------+-----------------------
value value | yes | value is passed
value leaf | yes | value is passed
value void | yes | caller is implied void
leaf value | no | generated value was discarded, inlined would not. called may be implied void.
leaf leaf | no | s.a.
leaf void | no | s.a.
void value | no | caller drops value, inlined would not.
void leaf | no | s.a.
void void | yes |
</pre>
<p>The result of the command is the empty string.</p>
<p>The grammar in the container is directly modified. If that is
not wanted, a copy of the original container has to be used.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="3"><b class="cmd">::peg::peg::op</b> <b class="method">drop unreachable</b> <i class="arg">container</i></a></dt>
<dd><p>This command removes all symbols from the grammar which are not
<b class="method">reachable</b>.</p>
<p>The result of the command is the empty string.</p>
<p>The grammar in the container is directly modified. If that is
not wanted, a copy of the original container has to be used.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="4"><b class="cmd">::peg::peg::op</b> <b class="method">drop unrealizable</b> <i class="arg">container</i></a></dt>
<dd><p>This command removes all symbols from the grammar which are not
<b class="method">realizable</b>.</p>
<p>The result of the command is the empty string.</p>
<p>The grammar in the container is directly modified. If that is
not wanted, a copy of the original container has to be used.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="5"><b class="cmd">::peg::peg::op</b> <b class="method">flatten</b> <i class="arg">container</i></a></dt>
<dd><p>This command flattens (see <b class="package"><a href="pt_pexpr_op.html">pt::pe::op</a></b>) all expressions in
the grammar, i.e. the start expression and the right hand sides of all
nonterminal symbols.</p>
<p>The result of the command is the empty string.</p>
<p>The grammar in the container is directly modified. If that is
not wanted, a copy of the original container has to be used.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="6"><b class="cmd">::peg::peg::op</b> <b class="method">minimize</b> <i class="arg">container</i></a></dt>
<dd><p>This command reduces the provided grammar by applying most of the other methods of this package.</p>
<p>After flattening the expressions it removes unreachable and
unrealizable symbols, flattens the expressions again, then optimizes
the symbol modes before collapsing symbol chains as much as possible.</p>
<p>The result of the command is the empty string.</p>
<p>The grammar in the container is directly modified. If that is
not wanted, a copy of the original container has to be used.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="7"><b class="cmd">::peg::peg::op</b> <b class="method">modeopt</b> <i class="arg">container</i></a></dt>
<dd><p>This command optimizes the semantic modes of non-terminal symbols
according to the two rules below.</p>
<ol class="doctools_enumerated">
<li><p>If a symbol X with mode <b class="const">value</b> calls no other symbols,
i.e. uses only terminal symbols in whatever combination, then
this can be represented simpler by using mode <b class="const">leaf</b>.</p></li>
<li><p>If a symbol X is only called from symbols with modes
<b class="const">leaf</b> or <b class="const">void</b> then this symbol should have mode
<b class="const">void</b> also, as any AST it could generate will be
discarded anyway.</p></li>
</ol>
<p>The result of the command is the empty string.</p>
<p>The grammar in the container is directly modified. If that is
not wanted, a copy of the original container has to be used.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="8"><b class="cmd">::peg::peg::op</b> <b class="method">reachable</b> <i class="arg">container</i></a></dt>
<dd><p>This command computes the set of all nonterminal symbols which are
reachable from the start expression of the grammar. This is
essentially the transitive closure over <b class="method">called</b> and the
symbol's right hand sides, beginning with the start expression.</p>
<p>The result of the command is the list of reachable symbols.</p>
<p>The grammar in the container is not modified.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
<dt><a name="9"><b class="cmd">::peg::peg::op</b> <b class="method">realizable</b> <i class="arg">container</i></a></dt>
<dd><p>This command computes the set of all nonterminal symbols which are
realizable, i.e. can derive pure terminal phrases. This is done
iteratively, starting with state unrealizable for all and any, and
then updating all symbols which are realizable, propagating changes,
until nothing changes any more.</p>
<p>The result of the command is the list of realizable symbols.</p>
<p>The grammar in the container is not modified.</p>
<p>The <i class="arg">container</i> instance has to expose a method API as is
provided by the package <b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
|
<div class='fossil-doc' data-title='pt::peg::to::container - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::to::container(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::to::container - PEG Conversion. Write CONTAINER format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">Grammar Container</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::to::container <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">text::write</b></li>
<li>package require <b class="pkgname">char</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::to::container</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">pt::peg::to::container</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">pt::peg::to::container</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">pt::peg::to::container</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">pt::peg::to::container</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from parsing expression grammars
to CONTAINER markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the export manager provided by
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding export plugin
<b class="package"><a href="pt_peg_export_container.html">pt::peg::export::container</a></b> sitting between converter
and export manager.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::to::container</b> <b class="method">reset</b></a></dt>
<dd><p>This command resets the configuration of the package to its default
settings.</p></dd>
<dt><a name="2"><b class="cmd">pt::peg::to::container</b> <b class="method">configure</b></a></dt>
<dd><p>This command returns a dictionary containing the current configuration
of the package.</p></dd>
<dt><a name="3"><b class="cmd">pt::peg::to::container</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the current value of the specified configuration
<i class="arg">option</i> of the package. For the set of legal options, please read
the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">pt::peg::to::container</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command sets the given configuration <i class="arg">option</i>s of the
package, to the specified <i class="arg">value</i>s. For the set of legal options,
please read the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">pt::peg::to::container</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, and generates CONTAINER markup
encoding the grammar, per the current package configuration.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The converter to the CONTAINER format recognizes the following options
and changes its behaviour as they specify.</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-mode</b> <b class="const">bulk</b>|<b class="const">incremental</b></dt>
<dd><p>The value of this option controls which methods of
<b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b> instances are used to specify the
grammar, i.e. preload it into the container. There are two legal
values, as listed below. The default is <b class="const">bulk</b>.</p>
<dl class="doctools_definitions">
<dt><b class="const">bulk</b></dt>
<dd><p>In this mode the methods <b class="method">start</b>, <b class="method">add</b>, <b class="method">modes</b>,
and <b class="method">rules</b> are used to specify the grammar in a bulk manner,
i.e. as a set of nonterminal symbols, and two dictionaries mapping
from the symbols to their semantic modes and parsing expressions.</p>
<p>This mode is the default.</p></dd>
<dt><b class="const">incremental</b></dt>
<dd><p>In this mode the methods <b class="method">start</b>, <b class="method">add</b>, <b class="method">mode</b>,
and <b class="method">rule</b> are used to specify the grammar piecemal, with each
nonterminal having its own block of defining commands.</p></dd>
</dl></dd>
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this option is a string into which to put the generated
code and the other configuration settings. The various locations for
user-data are expected to be specified with the placeholders listed
below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">CONTAINER</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-name</b>.</p></dd>
<dt><b class="const">@mode@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-mode</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated code.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Grammar Container</a></h2>
<p>The <b class="const">container</b> format is another form of describing parsing
expression grammars. While data in this format is executable it does
not constitute a parser for the grammar. It always has to be used in
conjunction with the package <b class="package"><a href="pt_peg_interp.html">pt::peg::interp</a></b>, a grammar
interpreter.</p>
<p>The format represents grammars by a <b class="cmd">snit::type</b>, i.e. class,
whose instances are API-compatible to the instances of the
<b class="package"><a href="pt_peg_container.html">pt::peg::container</a></b> package, and which are preloaded with the
grammar in question.</p>
<p>It has no direct formal specification beyond what was said above.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>one possible CONTAINER serialization for it is</p>
<pre class="doctools_example">
snit::type a_pe_grammar {
constructor {} {
install myg using pt::peg::container ${selfns}::G
$myg start {n Expression}
$myg add AddOp Digit Expression Factor MulOp Number Sign Term
$myg modes {
AddOp value
Digit value
Expression value
Factor value
MulOp value
Number value
Sign value
Term value
}
$myg rules {
AddOp {/ {t -} {t +}}
Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
Factor {x {n Term} {* {x {n AddOp} {n Term}}}}
MulOp {/ {t *} {t /}}
Number {x {? {n Sign}} {+ {n Digit}}}
Sign {/ {t -} {t +}}
Term {n Number}
}
return
}
component myg
delegate method * to myg
}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#container">CONTAINER</a>, <a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
|
<div class='fossil-doc' data-title='pt::peg::to::cparam - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::to::cparam(n) 1.1.2 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::to::cparam - PEG Conversion. Write CPARAM format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">C/PARAM code representation of parsing expression grammars</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::to::cparam <span class="opt">?1.1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::to::cparam</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">pt::peg::to::cparam</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">pt::peg::to::cparam</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">pt::peg::to::cparam</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">pt::peg::to::cparam</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from parsing expression grammars
to CPARAM markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the export manager provided by
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding export plugin
<b class="package">pt::peg::export::cparam</b> sitting between converter
and export manager.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::to::cparam</b> <b class="method">reset</b></a></dt>
<dd><p>This command resets the configuration of the package to its default
settings.</p></dd>
<dt><a name="2"><b class="cmd">pt::peg::to::cparam</b> <b class="method">configure</b></a></dt>
<dd><p>This command returns a dictionary containing the current configuration
of the package.</p></dd>
<dt><a name="3"><b class="cmd">pt::peg::to::cparam</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the current value of the specified configuration
<i class="arg">option</i> of the package. For the set of legal options, please read
the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">pt::peg::to::cparam</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command sets the given configuration <i class="arg">option</i>s of the
package, to the specified <i class="arg">value</i>s. For the set of legal options,
please read the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">pt::peg::to::cparam</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, and generates CPARAM markup
encoding the grammar, per the current package configuration.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The converter to C code recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this option is a string into which to put
the generated text and the other configuration settings. The various
locations for user-data are expected to be specified with the
placeholders listed below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">C/PARAM</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated Tcl code.</p></dd>
</dl>
<p>The following options are special, in that they will
occur within the generated code, and are replaced there as well.</p>
<dl class="doctools_definitions">
<dt><b class="const">@statedecl@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">state-decl</b>.</p></dd>
<dt><b class="const">@stateref@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">state-ref</b>.</p></dd>
<dt><b class="const">@strings@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">string-varname</b>.</p></dd>
<dt><b class="const">@self@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">self-command</b>.</p></dd>
<dt><b class="const">@def@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">fun-qualifier</b>.</p></dd>
<dt><b class="const">@ns@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">namespace</b>.</p></dd>
<dt><b class="const">@main@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">main</b>.</p></dd>
<dt><b class="const">@prelude@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">prelude</b>.</p></dd>
</dl></dd>
<dt><b class="option">-state-decl</b> string</dt>
<dd><p>A C string representing the argument declaration to use in the
generated parsing functions to refer to the parsing state. In essence
type and argument name.
The default value is the string <b class="const">RDE_PARAM p</b>.</p></dd>
<dt><b class="option">-state-ref</b> string</dt>
<dd><p>A C string representing the argument named used in the generated
parsing functions to refer to the parsing state.
The default value is the string <b class="const">p</b>.</p></dd>
<dt><b class="option">-self-command</b> string</dt>
<dd><p>A C string representing the reference needed to call the generated
parser function (methods ...) from another parser fonction, per the
chosen framework (template).
The default value is the empty string.</p></dd>
<dt><b class="option">-fun-qualifier</b> string</dt>
<dd><p>A C string containing the attributes to give to the generated
functions (methods ...), per the chosen framework (template).
The default value is <b class="const">static</b>.</p></dd>
<dt><b class="option">-namespace</b> string</dt>
<dd><p>The name of the C namespace the parser functions (methods, ...) shall
reside in, or a general prefix to add to the function names.
The default value is the empty string.</p></dd>
<dt><b class="option">-main</b> string</dt>
<dd><p>The name of the main function (method, ...) to be called by the chosen
framework (template) to start parsing input.
The default value is <b class="const">__main</b>.</p></dd>
<dt><b class="option">-string-varname</b> string</dt>
<dd><p>The name of the variable used for the table of strings used by the
generated parser, i.e. error messages, symbol names, etc.
The default value is <b class="const">p_string</b>.</p></dd>
<dt><b class="option">-prelude</b> string</dt>
<dd><p>A snippet of code to be inserted at the head of each generated parsing
function.
The default value is the empty string.</p></dd>
<dt><b class="option">-indent</b> integer</dt>
<dd><p>The number of characters to indent each line of the generated code by.
The default value is <b class="const">0</b>.</p></dd>
<dt><b class="option">-comments</b> boolean</dt>
<dd><p>A flag controlling the generation of code comments containing the
original parsing expression a parsing function is for.
The default value is <b class="const">on</b>.</p></dd>
</dl>
<p>While the high parameterizability of this converter, as shown by the
multitude of options it supports, is an advantage to the advanced
user, allowing her to customize the output of the converter as needed,
a novice user will likely not see the forest for the trees.</p>
<p>To help these latter users an adjunct package is provided, containing
a canned configuration which will generate immediately useful full
parsers. It is</p>
<dl class="doctools_definitions">
<dt><b class="package"><a href="pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></b></dt>
<dd><p>Generated parsers are embedded into a <b class="package">Critcl</b>-based framework.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">C/PARAM code representation of parsing expression grammars</a></h2>
<p>The <b class="const">c</b> format is executable code, a parser for the grammar. The
parser implementation is written in C and can be tweaked to the users'
needs through a multitude of options.</p>
<p>The <b class="cmd">critcl</b> format, for example, is implemented as a canned
configuration of these options on top of the generator for <b class="const">c</b>.</p>
<p>The bulk of such a framework has to be specified through the option
<b class="option">-template</b>. The additional options</p>
<dl class="doctools_options">
<dt><b class="option">-fun-qualifier</b> string</dt>
<dd></dd>
<dt><b class="option">-main</b> string</dt>
<dd></dd>
<dt><b class="option">-namespace</b> string</dt>
<dd></dd>
<dt><b class="option">-prelude</b> string</dt>
<dd></dd>
<dt><b class="option">-self-command</b> string</dt>
<dd></dd>
<dt><b class="option">-state-decl</b> string</dt>
<dd></dd>
<dt><b class="option">-state-ref</b> string</dt>
<dd></dd>
<dt><b class="option">-string-varname</b> string</dt>
<dd></dd>
</dl>
<p>provide code snippets which help to glue framework and generated code
together. Their placeholders are in the <em>generated</em> code.
Further the options</p>
<dl class="doctools_options">
<dt><b class="option">-indent</b> integer</dt>
<dd></dd>
<dt><b class="option">-comments</b> boolean</dt>
<dd></dd>
</dl>
<p>allow for the customization of the code indent (default none), and
whether to generate comments showing the parsing expressions a
function is for (default on).</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>We are forgoing an example of this representation, with apologies.
It would be way to large for this document.</p>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cparam">CPARAM</a>, <a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
|
<div class='fossil-doc' data-title='pt::peg::to::json - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::to::json(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::to::json - PEG Conversion. Write JSON format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">JSON Grammar Exchange Format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::to::json <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">json::write</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::to::json</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">pt::peg::to::json</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">pt::peg::to::json</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">pt::peg::to::json</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">pt::peg::to::json</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from parsing expression grammars
to JSON markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the export manager provided by
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding export plugin
<b class="package"><a href="pt_peg_export_json.html">pt::peg::export::json</a></b> sitting between converter
and export manager.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::to::json</b> <b class="method">reset</b></a></dt>
<dd><p>This command resets the configuration of the package to its default
settings.</p></dd>
<dt><a name="2"><b class="cmd">pt::peg::to::json</b> <b class="method">configure</b></a></dt>
<dd><p>This command returns a dictionary containing the current configuration
of the package.</p></dd>
<dt><a name="3"><b class="cmd">pt::peg::to::json</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the current value of the specified configuration
<i class="arg">option</i> of the package. For the set of legal options, please read
the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">pt::peg::to::json</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command sets the given configuration <i class="arg">option</i>s of the
package, to the specified <i class="arg">value</i>s. For the set of legal options,
please read the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">pt::peg::to::json</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, and generates JSON markup
encoding the grammar, per the current package configuration.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The converter to the JSON grammar exchange format recognizes the
following configuration variables and changes its behaviour as they
specify.</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-indented</b> boolean</dt>
<dd><p>If this option is set the system will break the generated JSON across
lines and indent it according to its inner structure, with each key of
a dictionary on a separate line.</p>
<p>If the option is not set (the default), the whole JSON object will be
written on a single line, with minimum spacing between all elements.</p></dd>
<dt><b class="option">-aligned</b> boolean</dt>
<dd><p>If this option is set the system will ensure that the values for the
keys in a dictionary are vertically aligned with each other, for a
nice table effect.
To make this work this also implies that <b class="option">-indented</b> is set.</p>
<p>If the option is not set (the default), the output is formatted as per
the value of <b class="variable">indented</b>, without trying to align the values for
dictionary keys.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">JSON Grammar Exchange Format</a></h2>
<p>The <b class="const">json</b> format for parsing expression grammars was written as
a data exchange format not bound to Tcl. It was defined to allow the
exchange of grammars with PackRat/PEG based parser generators for
other languages.</p>
<p>It is formally specified by the rules below:</p>
<ol class="doctools_enumerated">
<li><p>The JSON of any PEG is a JSON object.</p></li>
<li><p>This object holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a JSON object holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a JSON object whose keys are the names of the nonterminal
symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a JSON object itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the
parsing expression describing the symbols sentennial structure, as
specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value is a JSON holding holding one of three values specifying how
a parser should handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is a JSON string holding the Tcl serialization of the start
parsing expression of the grammar, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol>
<p>As an aside to the advanced reader, this is pretty much the same as
the Tcl serialization of PE grammars, as specified in section
<span class="sectref"><a href="#section5">PEG serialization format</a></span>, except that the Tcl dictionaries
and lists of that format are mapped to JSON objects and arrays. Only
the parsing expressions themselves are not translated further, but
kept as JSON strings containing a nested Tcl list, and there is no
concept of canonicity for the JSON either.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>a JSON serialization for it is</p>
<pre class="doctools_example">
{
"pt::grammar::peg" : {
"rules" : {
"AddOp" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Digit" : {
"is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
"mode" : "value"
},
"Expression" : {
"is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
"mode" : "value"
},
"Factor" : {
"is" : "x {n Term} {* {x {n AddOp} {n Term}}}",
"mode" : "value"
},
"MulOp" : {
"is" : "\/ {t *} {t \/}",
"mode" : "value"
},
"Number" : {
"is" : "x {? {n Sign}} {+ {n Digit}}",
"mode" : "value"
},
"Sign" : {
"is" : "\/ {t -} {t +}",
"mode" : "value"
},
"Term" : {
"is" : "n Number",
"mode" : "value"
}
},
"start" : "n Expression"
}
}
</pre>
<p>and a Tcl serialization of the same is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
<p>The similarity of the latter to the JSON should be quite obvious.</p>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#json">JSON</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
|
<div class='fossil-doc' data-title='pt::peg::to::param - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::to::param(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::to::param - PEG Conversion. Write PARAM format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">PARAM code representation of parsing expression grammars</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::to::param <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">pt::pe</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::to::param</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">pt::peg::to::param</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">pt::peg::to::param</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">pt::peg::to::param</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">pt::peg::to::param</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from parsing expression grammars
to PARAM markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the export manager provided by
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding export plugin
<b class="package">pt::peg::export::param</b> sitting between converter
and export manager.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::to::param</b> <b class="method">reset</b></a></dt>
<dd><p>This command resets the configuration of the package to its default
settings.</p></dd>
<dt><a name="2"><b class="cmd">pt::peg::to::param</b> <b class="method">configure</b></a></dt>
<dd><p>This command returns a dictionary containing the current configuration
of the package.</p></dd>
<dt><a name="3"><b class="cmd">pt::peg::to::param</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the current value of the specified configuration
<i class="arg">option</i> of the package. For the set of legal options, please read
the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">pt::peg::to::param</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command sets the given configuration <i class="arg">option</i>s of the
package, to the specified <i class="arg">value</i>s. For the set of legal options,
please read the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">pt::peg::to::param</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, and generates PARAM markup
encoding the grammar, per the current package configuration.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The converter to PARAM markup recognizes the following configuration
variables and changes its behaviour as they specify.</p>
<dl class="doctools_options">
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this configuration variable is a string into which to put
the generated text and the other configuration settings. The various
locations for user-data are expected to be specified with the
placeholders listed below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">PARAM</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">-name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated text.</p></dd>
</dl></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this configuration variable is the name of the grammar
for which the conversion is run. The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this configuration variable is the name of the user for
which the conversion is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this configuration variable is the name of the file or
other entity from which the grammar came, for which the conversion is
run. The default value is <b class="const">unknown</b>.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PARAM code representation of parsing expression grammars</a></h2>
<p>The PARAM code representation of parsing expression grammars is
assembler-like text using the instructions of the virtual machine
documented in the <i class="term"><a href="pt_param.html">PackRat Machine Specification</a></i>, plus a
few more for control flow (jump ok, jump fail, call symbol, return).</p>
<p>It is not really useful, except possibly as a tool demonstrating how a
grammar is compiled in general, without getting distracted by the
incidentials of a framework, i.e. like the supporting C and Tcl code
generated by the other PARAM-derived formats.</p>
<p>It has no direct formal specification beyond what was said above.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>one possible PARAM serialization for it is</p>
<pre class="doctools_example">
# -*- text -*-
# Parsing Expression Grammar 'TEMPLATE'.
# Generated for unknown, from file 'TEST'
#
# Grammar Start Expression
#
<<MAIN>>:
call sym_Expression
halt
#
# value Symbol 'AddOp'
#
sym_AddOp:
# /
# '-'
# '+'
symbol_restore AddOp
found! jump found_7
loc_push
call choice_5
fail! value_clear
ok! value_leaf AddOp
symbol_save AddOp
error_nonterminal AddOp
loc_pop_discard
found_7:
ok! ast_value_push
return
choice_5:
# /
# '-'
# '+'
error_clear
loc_push
error_push
input_next "t -"
ok! test_char "-"
error_pop_merge
ok! jump oknoast_4
loc_pop_rewind
loc_push
error_push
input_next "t +"
ok! test_char "+"
error_pop_merge
ok! jump oknoast_4
loc_pop_rewind
status_fail
return
oknoast_4:
loc_pop_discard
return
#
# value Symbol 'Digit'
#
sym_Digit:
# /
# '0'
# '1'
# '2'
# '3'
# '4'
# '5'
# '6'
# '7'
# '8'
# '9'
symbol_restore Digit
found! jump found_22
loc_push
call choice_20
fail! value_clear
ok! value_leaf Digit
symbol_save Digit
error_nonterminal Digit
loc_pop_discard
found_22:
ok! ast_value_push
return
choice_20:
# /
# '0'
# '1'
# '2'
# '3'
# '4'
# '5'
# '6'
# '7'
# '8'
# '9'
error_clear
loc_push
error_push
input_next "t 0"
ok! test_char "0"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 1"
ok! test_char "1"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 2"
ok! test_char "2"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 3"
ok! test_char "3"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 4"
ok! test_char "4"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 5"
ok! test_char "5"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 6"
ok! test_char "6"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 7"
ok! test_char "7"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 8"
ok! test_char "8"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
loc_push
error_push
input_next "t 9"
ok! test_char "9"
error_pop_merge
ok! jump oknoast_19
loc_pop_rewind
status_fail
return
oknoast_19:
loc_pop_discard
return
#
# value Symbol 'Expression'
#
sym_Expression:
# /
# x
# '\('
# (Expression)
# '\)'
# x
# (Factor)
# *
# x
# (MulOp)
# (Factor)
symbol_restore Expression
found! jump found_46
loc_push
ast_push
call choice_44
fail! value_clear
ok! value_reduce Expression
symbol_save Expression
error_nonterminal Expression
ast_pop_rewind
loc_pop_discard
found_46:
ok! ast_value_push
return
choice_44:
# /
# x
# '\('
# (Expression)
# '\)'
# x
# (Factor)
# *
# x
# (MulOp)
# (Factor)
error_clear
ast_push
loc_push
error_push
call sequence_27
error_pop_merge
ok! jump ok_43
ast_pop_rewind
loc_pop_rewind
ast_push
loc_push
error_push
call sequence_40
error_pop_merge
ok! jump ok_43
ast_pop_rewind
loc_pop_rewind
status_fail
return
ok_43:
ast_pop_discard
loc_pop_discard
return
sequence_27:
# x
# '\('
# (Expression)
# '\)'
loc_push
error_clear
error_push
input_next "t ("
ok! test_char "("
error_pop_merge
fail! jump failednoast_29
ast_push
error_push
call sym_Expression
error_pop_merge
fail! jump failed_28
error_push
input_next "t )"
ok! test_char ")"
error_pop_merge
fail! jump failed_28
ast_pop_discard
loc_pop_discard
return
failed_28:
ast_pop_rewind
failednoast_29:
loc_pop_rewind
return
sequence_40:
# x
# (Factor)
# *
# x
# (MulOp)
# (Factor)
ast_push
loc_push
error_clear
error_push
call sym_Factor
error_pop_merge
fail! jump failed_41
error_push
call kleene_37
error_pop_merge
fail! jump failed_41
ast_pop_discard
loc_pop_discard
return
failed_41:
ast_pop_rewind
loc_pop_rewind
return
kleene_37:
# *
# x
# (MulOp)
# (Factor)
loc_push
error_push
call sequence_34
error_pop_merge
fail! jump failed_38
loc_pop_discard
jump kleene_37
failed_38:
loc_pop_rewind
status_ok
return
sequence_34:
# x
# (MulOp)
# (Factor)
ast_push
loc_push
error_clear
error_push
call sym_MulOp
error_pop_merge
fail! jump failed_35
error_push
call sym_Factor
error_pop_merge
fail! jump failed_35
ast_pop_discard
loc_pop_discard
return
failed_35:
ast_pop_rewind
loc_pop_rewind
return
#
# value Symbol 'Factor'
#
sym_Factor:
# x
# (Term)
# *
# x
# (AddOp)
# (Term)
symbol_restore Factor
found! jump found_60
loc_push
ast_push
call sequence_57
fail! value_clear
ok! value_reduce Factor
symbol_save Factor
error_nonterminal Factor
ast_pop_rewind
loc_pop_discard
found_60:
ok! ast_value_push
return
sequence_57:
# x
# (Term)
# *
# x
# (AddOp)
# (Term)
ast_push
loc_push
error_clear
error_push
call sym_Term
error_pop_merge
fail! jump failed_58
error_push
call kleene_54
error_pop_merge
fail! jump failed_58
ast_pop_discard
loc_pop_discard
return
failed_58:
ast_pop_rewind
loc_pop_rewind
return
kleene_54:
# *
# x
# (AddOp)
# (Term)
loc_push
error_push
call sequence_51
error_pop_merge
fail! jump failed_55
loc_pop_discard
jump kleene_54
failed_55:
loc_pop_rewind
status_ok
return
sequence_51:
# x
# (AddOp)
# (Term)
ast_push
loc_push
error_clear
error_push
call sym_AddOp
error_pop_merge
fail! jump failed_52
error_push
call sym_Term
error_pop_merge
fail! jump failed_52
ast_pop_discard
loc_pop_discard
return
failed_52:
ast_pop_rewind
loc_pop_rewind
return
#
# value Symbol 'MulOp'
#
sym_MulOp:
# /
# '*'
# '/'
symbol_restore MulOp
found! jump found_67
loc_push
call choice_65
fail! value_clear
ok! value_leaf MulOp
symbol_save MulOp
error_nonterminal MulOp
loc_pop_discard
found_67:
ok! ast_value_push
return
choice_65:
# /
# '*'
# '/'
error_clear
loc_push
error_push
input_next "t *"
ok! test_char "*"
error_pop_merge
ok! jump oknoast_64
loc_pop_rewind
loc_push
error_push
input_next "t /"
ok! test_char "/"
error_pop_merge
ok! jump oknoast_64
loc_pop_rewind
status_fail
return
oknoast_64:
loc_pop_discard
return
#
# value Symbol 'Number'
#
sym_Number:
# x
# ?
# (Sign)
# +
# (Digit)
symbol_restore Number
found! jump found_80
loc_push
ast_push
call sequence_77
fail! value_clear
ok! value_reduce Number
symbol_save Number
error_nonterminal Number
ast_pop_rewind
loc_pop_discard
found_80:
ok! ast_value_push
return
sequence_77:
# x
# ?
# (Sign)
# +
# (Digit)
ast_push
loc_push
error_clear
error_push
call optional_70
error_pop_merge
fail! jump failed_78
error_push
call poskleene_73
error_pop_merge
fail! jump failed_78
ast_pop_discard
loc_pop_discard
return
failed_78:
ast_pop_rewind
loc_pop_rewind
return
optional_70:
# ?
# (Sign)
loc_push
error_push
call sym_Sign
error_pop_merge
fail! loc_pop_rewind
ok! loc_pop_discard
status_ok
return
poskleene_73:
# +
# (Digit)
loc_push
call sym_Digit
fail! jump failed_74
loop_75:
loc_pop_discard
loc_push
error_push
call sym_Digit
error_pop_merge
ok! jump loop_75
status_ok
failed_74:
loc_pop_rewind
return
#
# value Symbol 'Sign'
#
sym_Sign:
# /
# '-'
# '+'
symbol_restore Sign
found! jump found_86
loc_push
call choice_5
fail! value_clear
ok! value_leaf Sign
symbol_save Sign
error_nonterminal Sign
loc_pop_discard
found_86:
ok! ast_value_push
return
#
# value Symbol 'Term'
#
sym_Term:
# (Number)
symbol_restore Term
found! jump found_89
loc_push
ast_push
call sym_Number
fail! value_clear
ok! value_reduce Term
symbol_save Term
error_nonterminal Term
ast_pop_rewind
loc_pop_discard
found_89:
ok! ast_value_push
return
#
#
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#param">PARAM</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
|
<div class='fossil-doc' data-title='pt::peg::to::peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::to::peg(n) 1.0.2 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::to::peg - PEG Conversion. Write PEG format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">PEG Specification Language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::to::peg <span class="opt">?1.0.2?</span></b></li>
<li>package require <b class="pkgname">pt::peg</b></li>
<li>package require <b class="pkgname">pt::pe</b></li>
<li>package require <b class="pkgname">text::write</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::to::peg</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">pt::peg::to::peg</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">pt::peg::to::peg</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">pt::peg::to::peg</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">pt::peg::to::peg</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from parsing expression grammars
to PEG markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the export manager provided by
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding export plugin
<b class="package"><a href="pt_peg_export_peg.html">pt::peg::export::peg</a></b> sitting between converter
and export manager.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::to::peg</b> <b class="method">reset</b></a></dt>
<dd><p>This command resets the configuration of the package to its default
settings.</p></dd>
<dt><a name="2"><b class="cmd">pt::peg::to::peg</b> <b class="method">configure</b></a></dt>
<dd><p>This command returns a dictionary containing the current configuration
of the package.</p></dd>
<dt><a name="3"><b class="cmd">pt::peg::to::peg</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the current value of the specified configuration
<i class="arg">option</i> of the package. For the set of legal options, please read
the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">pt::peg::to::peg</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command sets the given configuration <i class="arg">option</i>s of the
package, to the specified <i class="arg">value</i>s. For the set of legal options,
please read the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">pt::peg::to::peg</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, and generates PEG markup
encoding the grammar, per the current package configuration.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The converter to the PEG language recognizes the following options and
changes its behaviour as they specify.</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this option is a string into which to put the generated
text and the values of the other options. The various locations for
user-data are expected to be specified with the placeholders listed
below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">PEG</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the option <b class="option">-name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated text.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PEG Specification Language</a></h2>
<p><b class="const">peg</b>, a language for the specification of parsing expression
grammars is meant to be human readable, and writable as well, yet
strict enough to allow its processing by machine. Like any computer
language. It was defined to make writing the specification of a
grammar easy, something the other formats found in the Parser Tools do
not lend themselves too.</p>
<p>It is formally specified by the grammar shown below, written in
itself. For a tutorial / introduction to the language please go and
read the <i class="term"><a href="pt_peg_language.html">PEG Language Tutorial</a></i>.</p>
<pre class="doctools_example">
PEG pe-grammar-for-peg (Grammar)
# --------------------------------------------------------------------
# Syntactical constructs
Grammar <- WHITESPACE Header Definition* Final EOF ;
Header <- PEG Identifier StartExpr ;
Definition <- Attribute? Identifier IS Expression SEMICOLON ;
Attribute <- (VOID / LEAF) COLON ;
Expression <- Sequence (SLASH Sequence)* ;
Sequence <- Prefix+ ;
Prefix <- (AND / NOT)? Suffix ;
Suffix <- Primary (QUESTION / STAR / PLUS)? ;
Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
/ GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
/ WORDCHAR / XDIGIT
/ Identifier
/ OPEN Expression CLOSE
/ Literal
/ Class
/ DOT
;
Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE
/ DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
Range <- Char TO Char / Char ;
StartExpr <- OPEN Expression CLOSE ;
void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ;
# --------------------------------------------------------------------
# Lexing constructs
Identifier <- Ident WHITESPACE ;
leaf: Ident <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
Char <- CharSpecial / CharOctalFull / CharOctalPart
/ CharUnicode / CharUnescaped
;
leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ;
leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ;
leaf: CharOctalPart <- "\\" [0-7][0-7]? ;
leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
leaf: CharUnescaped <- !"\\" . ;
void: HexDigit <- [0-9a-fA-F] ;
void: TO <- '-' ;
void: OPENB <- "[" ;
void: CLOSEB <- "]" ;
void: APOSTROPH <- "'" ;
void: DAPOSTROPH <- '"' ;
void: PEG <- "PEG" !([_:] / <alnum>) WHITESPACE ;
void: IS <- "<-" WHITESPACE ;
leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value.
leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals.
void: SEMICOLON <- ";" WHITESPACE ;
void: COLON <- ":" WHITESPACE ;
void: SLASH <- "/" WHITESPACE ;
leaf: AND <- "&" WHITESPACE ;
leaf: NOT <- "!" WHITESPACE ;
leaf: QUESTION <- "?" WHITESPACE ;
leaf: STAR <- "*" WHITESPACE ;
leaf: PLUS <- "+" WHITESPACE ;
void: OPEN <- "(" WHITESPACE ;
void: CLOSE <- ")" WHITESPACE ;
leaf: DOT <- "." WHITESPACE ;
leaf: ALNUM <- "<alnum>" WHITESPACE ;
leaf: ALPHA <- "<alpha>" WHITESPACE ;
leaf: ASCII <- "<ascii>" WHITESPACE ;
leaf: CONTROL <- "<control>" WHITESPACE ;
leaf: DDIGIT <- "<ddigit>" WHITESPACE ;
leaf: DIGIT <- "<digit>" WHITESPACE ;
leaf: GRAPH <- "<graph>" WHITESPACE ;
leaf: LOWER <- "<lower>" WHITESPACE ;
leaf: PRINTABLE <- "<print>" WHITESPACE ;
leaf: PUNCT <- "<punct>" WHITESPACE ;
leaf: SPACE <- "<space>" WHITESPACE ;
leaf: UPPER <- "<upper>" WHITESPACE ;
leaf: WORDCHAR <- "<wordchar>" WHITESPACE ;
leaf: XDIGIT <- "<xdigit>" WHITESPACE ;
void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ;
void: COMMENT <- '#' (!EOL .)* EOL ;
void: EOL <- "\n\r" / "\n" / "\r" ;
void: EOF <- !. ;
# --------------------------------------------------------------------
END;
</pre>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Our example specifies the grammar for a basic 4-operation calculator.</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>Using higher-level features of the notation, i.e. the character
classes (predefined and custom), this example can be rewritten as</p>
<pre class="doctools_example">
PEG calculator (Expression)
Sign <- [-+] ;
Number <- Sign? <ddigit>+ ;
Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ;
MulOp <- [*/] ;
Factor <- Term (AddOp Term)* ;
AddOp <- [-+] ;
Term <- Number ;
END;
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
|
<div class='fossil-doc' data-title='pt::peg::to::tclparam - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg::to::tclparam(n) 1.0.3 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg::to::tclparam - PEG Conversion. Write TCLPARAM format</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">Tcl/PARAM code representation of parsing expression grammars</a></li>
<li class="doctools_section"><a href="#section5">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg::to::tclparam <span class="opt">?1.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package implements the converter from parsing expression grammars
to TCLPARAM markup.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools,
and can be used either directly with the other packages of this layer,
or indirectly through the export manager provided by
<b class="package"><a href="pt_peg_export.html">pt::peg::export</a></b>. The latter is intented for use in untrusted
environments and done through the corresponding export plugin
<b class="package">pt::peg::export::tclparam</b> sitting between converter
and export manager.</p>
<p><img alt="arch_core_eplugins" src="../../../../image/arch_core_eplugins.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification of the
Converter API found in the <i class="term"><a href="pt_to_api.html">Parser Tools Export API</a></i>
specification.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">reset</b></a></dt>
<dd><p>This command resets the configuration of the package to its default
settings.</p></dd>
<dt><a name="2"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">configure</b></a></dt>
<dd><p>This command returns a dictionary containing the current configuration
of the package.</p></dd>
<dt><a name="3"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This command returns the current value of the specified configuration
<i class="arg">option</i> of the package. For the set of legal options, please read
the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command sets the given configuration <i class="arg">option</i>s of the
package, to the specified <i class="arg">value</i>s. For the set of legal options,
please read the section <span class="sectref"><a href="#section3">Options</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">pt::peg::to::tclparam</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This command takes the canonical serialization of a parsing expression
grammar, as specified in section <span class="sectref"><a href="#section5">PEG serialization format</a></span>,
and contained in <i class="arg">serial</i>, and generates TCLPARAM markup
encoding the grammar, per the current package configuration.
The created string is then returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The converter to Tcl/PARAM markup recognizes the following
configuration variables and changes its behaviour as they specify.</p>
<dl class="doctools_options">
<dt><b class="option">-template</b> string</dt>
<dd><p>The value of this configuration variable is a string into which to put
the generated text and the other configuration settings. The various
locations for user-data are expected to be specified with the
placeholders listed below. The default value is "<b class="const">@code@</b>".</p>
<dl class="doctools_definitions">
<dt><b class="const">@user@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">-user</b>.</p></dd>
<dt><b class="const">@format@</b></dt>
<dd><p>To be replaced with the the constant <b class="const">Tcl/PARAM</b>.</p></dd>
<dt><b class="const">@file@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">-file</b>.</p></dd>
<dt><b class="const">@name@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">-name</b>.</p></dd>
<dt><b class="const">@code@</b></dt>
<dd><p>To be replaced with the generated Tcl code.</p></dd>
</dl>
<p>The following configuration variables are special, in that they will
occur within the generated code, and are replaced there as well.</p>
<dl class="doctools_definitions">
<dt><b class="const">@runtime@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">runtime-command</b>.</p></dd>
<dt><b class="const">@self@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">self-command</b>.</p></dd>
<dt><b class="const">@def@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">proc-command</b>.</p></dd>
<dt><b class="const">@ns@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">namespace</b>.</p></dd>
<dt><b class="const">@main@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">main</b>.</p></dd>
<dt><b class="const">@prelude@</b></dt>
<dd><p>To be replaced with the value of the configuration variable <b class="option">prelude</b>.</p></dd>
</dl></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this configuration variable is the name of the grammar
for which the conversion is run. The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this configuration variable is the name of the user for
which the conversion is run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this configuration variable is the name of the file or
other entity from which the grammar came, for which the conversion is
run. The default value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-runtime-command</b> string</dt>
<dd><p>A Tcl string representing the Tcl command or reference to it used to
call PARAM instruction from parser procedures, per the chosen
framework (template).
The default value is the empty string.</p></dd>
<dt><b class="option">-self-command</b> string</dt>
<dd><p>A Tcl string representing the Tcl command or reference to it used to
call the parser procedures (methods ...) from another parser
procedure, per the chosen framework (template).
The default value is the empty string.</p></dd>
<dt><b class="option">-proc-command</b> string</dt>
<dd><p>The name of the Tcl command used to define procedures (methods ...),
per the chosen framework (template).
The default value is <b class="const">proc</b>.</p></dd>
<dt><b class="option">-namespace</b> string</dt>
<dd><p>The name of the namespace the parser procedures (methods, ...) shall
reside in, including the trailing '::' needed to separate it from the
actual procedure name.
The default value is <b class="const">::</b>.</p></dd>
<dt><b class="option">-main</b> string</dt>
<dd><p>The name of the main procedure (method, ...) to be called by the
chosen framework (template) to start parsing input.
The default value is <b class="const">__main</b>.</p></dd>
<dt><b class="option">-prelude</b> string</dt>
<dd><p>A snippet of code to be insert at the head of each generated parsing
command.
The default value is the empty string.</p></dd>
<dt><b class="option">-indent</b> integer</dt>
<dd><p>The number of characters to indent each line of the generated code by.
The default value is <b class="const">0</b>.</p></dd>
</dl>
<p>While the high parameterizability of this converter, as shown by the
multitude of options it supports, is an advantage to the advanced
user, allowing her to customize the output of the converter as needed,
a novice user will likely not see the forest for the trees.</p>
<p>To help these latter users two adjunct packages are provided, each
containing a canned configuration which will generate immediately
useful full parsers. These are</p>
<dl class="doctools_definitions">
<dt><b class="package"><a href="pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></b></dt>
<dd><p>Generated parsers are classes based on the <b class="package"><a href="../snit/snit.html">snit</a></b> package,
i.e. snit::type's.</p></dd>
<dt><b class="package"><a href="pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></b></dt>
<dd><p>Generated parsers are classes based on the <b class="package">OO</b> package.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Tcl/PARAM code representation of parsing expression grammars</a></h2>
<p>The Tcl/PARAM representation of parsing expression grammars is Tcl
code whose execution will parse input per the grammar. The code is
based on the virtual machine documented in the
<i class="term"><a href="pt_param.html">PackRat Machine Specification</a></i>, using its instructions
and a few more to handle control flow.</p>
<p>Note that the generated code by itself is not functional. It expects
to be embedded into a framework which provides services like the PARAM
state, implementations for the PARAM instructions, etc.
The bulk of such a framework has to be specified through the option
<b class="option">-template</b>. The additional options</p>
<dl class="doctools_options">
<dt><b class="option">-indent</b> integer</dt>
<dd></dd>
<dt><b class="option">-main</b> string</dt>
<dd></dd>
<dt><b class="option">-namespace</b> string</dt>
<dd></dd>
<dt><b class="option">-prelude</b> string</dt>
<dd></dd>
<dt><b class="option">-proc-command</b> string</dt>
<dd></dd>
<dt><b class="option">-runtime-command</b> string</dt>
<dd></dd>
<dt><b class="option">-self-command</b> string</dt>
<dd></dd>
</dl>
<p>provide code snippets which help to glue framework and generated code
together. Their placeholders are in the <em>generated</em> code.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section6">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tclparam">TCLPARAM</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#format_conversion">format conversion</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_pegrammar.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
|
<div class='fossil-doc' data-title='pt::peg - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::peg(n) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::peg - Parsing Expression Grammar Serialization</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::peg <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">pt::pe</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::peg</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::pt::peg</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></li>
<li><a href="#3"><b class="cmd">::pt::peg</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></li>
<li><a href="#4"><b class="cmd">::pt::peg</b> <b class="method">print</b> <i class="arg">serial</i></a></li>
<li><a href="#5"><b class="cmd">::pt::peg</b> <b class="method">merge</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></li>
<li><a href="#6"><b class="cmd">::pt::peg</b> <b class="method">equal</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides commands to work with the serializations of
parsing expression grammars as managed by the Parser Tools, and
specified in section <span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p>
<p>This is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::peg</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
serialization of a parsing expression and will throw an error if that
is not the case. The result of the command is the empty string.</p>
<p>If the argument <i class="arg">canonvar</i> is specified it is interpreted as the
name of a variable in the calling context. This variable will be
written to if and only if <i class="arg">serial</i> is a valid regular
serialization. Its value will be a boolean, with <b class="const">True</b>
indicating that the serialization is not only valid, but also
<i class="term">canonical</i>. <b class="const">False</b> will be written for a valid, but
non-canonical serialization.</p>
<p>For the specification of serializations see the section
<span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
<dt><a name="2"><b class="cmd">::pt::peg</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">canonical</i> serialization of a PEG and will throw an error if
that is not the case. The result of the command is the empty string.</p>
<p>For the specification of canonical serializations see the section
<span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p></dd>
<dt><a name="3"><b class="cmd">::pt::peg</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of a PEG and will throw an error if that
is not the case.</p>
<p>It will then convert the input into the <i class="term">canonical</i> serialization
of the contained PEG and return it as its result. If the input is
already canonical it will be returned unchanged.</p>
<p>For the specification of regular and canonical serializations see the
section <span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::pt::peg</b> <b class="method">print</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the argument <i class="arg">serial</i> contains a valid
serialization of a parsing expression and returns a string containing
that PE in a human readable form.</p>
<p>The exact format of this form is not specified and cannot be relied on
for parsing or other machine-based activities.</p>
<p>For the specification of serializations see the section
<span class="sectref"><a href="#section3">PEG serialization format</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::pt::peg</b> <b class="method">merge</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></dt>
<dd><p>This command accepts the regular serializations of two grammars and
uses them to create their union. The result of the command is the
canonical serialization of this unified grammar.</p>
<p>A merge errors occurs if for any nonterminal symbol S occuring in both
input grammars the two input grammars specify different semantic
modes.</p>
<p>The semantic mode of each nonterminal symbol S is the semantic mode of
S in any of its input grammars. The previous rule made sure that for
symbols occuring in both grammars these values are identical.</p>
<p>The right-hand side of each nonterminal symbol S occuring in both
input grammars is the choice between the right-hand sides of S in the
input grammars, with the parsing expression of S in <i class="arg">seriala</i>
coming first, except if both expressions are identical. In that case
the first expression is taken.</p>
<p>The right-hand side of each nonterminal symbol S occuring in only one
of the input grammars is the right-hand side of S in its input
grammar.</p>
<p>The start expression of the unified grammar is the choice between the
start expressions of the input grammars, with the start expression of
<i class="arg">seriala</i> coming first, except if both expressions are identical.
In that case the first expression is taken</p></dd>
<dt><a name="6"><b class="cmd">::pt::peg</b> <b class="method">equal</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></dt>
<dd><p>This command tests the two grammars <i class="arg">seriala</i> and <i class="arg">serialb</i>
for structural equality. The result of the command is a boolean
value. It will be set to <b class="const">true</b> if the expressions are
identical, and <b class="const">false</b> otherwise.</p>
<p>String equality is usable only if we can assume that the two grammars
are pure Tcl lists and dictionaries.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section4">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
|
<div class='fossil-doc' data-title='pt::pe::op - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::pe::op(n) 1.0.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::pe::op - Parsing Expression Utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::pe::op <span class="opt">?1.0.1?</span></b></li>
<li>package require <b class="pkgname">pt::pe <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">struct::set</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::pe::op</b> <b class="method">drop</b> <i class="arg">dropset</i> <i class="arg">pe</i></a></li>
<li><a href="#2"><b class="cmd">::pt::pe::op</b> <b class="method">rename</b> <i class="arg">nt</i> <i class="arg">ntnew</i> <i class="arg">pe</i></a></li>
<li><a href="#3"><b class="cmd">::pt::pe::op</b> <b class="method">called</b> <i class="arg">pe</i></a></li>
<li><a href="#4"><b class="cmd">::pt::pe::op</b> <b class="method">flatten</b> <i class="arg">pe</i></a></li>
<li><a href="#5"><b class="cmd">::pt::pe::op</b> <b class="method">fusechars</b> <i class="arg">pe</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides additional commands to work with the
serializations of parsing expressions as managed by the PEG and
related packages, and specified in section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p>
<p>This is an internal package, for use by the higher level packages
handling PEGs, their conversion into and out of various other formats,
or other uses.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::pe::op</b> <b class="method">drop</b> <i class="arg">dropset</i> <i class="arg">pe</i></a></dt>
<dd><p>This command removes all occurences of any of the nonterminals symbols
in the set <i class="arg">dropset</i> from the parsing expression <i class="arg">pe</i>, and
simplifies it. This may result in the expression becoming "epsilon",
i.e. matching nothing.</p></dd>
<dt><a name="2"><b class="cmd">::pt::pe::op</b> <b class="method">rename</b> <i class="arg">nt</i> <i class="arg">ntnew</i> <i class="arg">pe</i></a></dt>
<dd><p>This command renames all occurences of the nonterminal <i class="arg">nt</i> in the
parsing expression <i class="arg">pe</i> into <i class="arg">ntnew</i>.</p></dd>
<dt><a name="3"><b class="cmd">::pt::pe::op</b> <b class="method">called</b> <i class="arg">pe</i></a></dt>
<dd><p>This command extracts the set of all nonterminal symbols used,
i.e. 'called', in the parsing expression <i class="arg">pe</i>.</p></dd>
<dt><a name="4"><b class="cmd">::pt::pe::op</b> <b class="method">flatten</b> <i class="arg">pe</i></a></dt>
<dd><p>This command transforms the parsing expression by eliminating
sequences nested in sequences, and choices in choices, lifting the
children of the nested expression into the parent. It further
eliminates all sequences and choices with only one child, as these are
redundant.</p>
<p>The resulting parsing expression is returned as the result of the
command.</p></dd>
<dt><a name="5"><b class="cmd">::pt::pe::op</b> <b class="method">fusechars</b> <i class="arg">pe</i></a></dt>
<dd><p>This command transforms the parsing expression by fusing adjacent
terminals in sequences and adjacent terminals and ranges in choices,
it (re)constructs highlevel <i class="term">strings</i> and
<i class="term">character classes</i>.</p>
<p>The resulting pseudo-parsing expression is returned as the result of
the command and may contain the pseudo-operators <b class="const">str</b> for
character sequences, aka strings, and <b class="const">cl</b> for character
choices, aka character classes.</p>
<p>The result is called a <i class="term">pseudo-parsing expression</i> because it
is not a true parsing expression anymore, and will fail a check with
<b class="cmd">::pt::peg verify</b> if the new pseudo-operators
are present in the result, but is otherwise of sound structure for a
parsing expression.
Notably, the commands <b class="cmd">::pt::peg bottomup</b> and
<b class="cmd">::pt::peg topdown</b> will process them without
trouble.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_pexpression.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
|
<div class='fossil-doc' data-title='pt::pe - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::pe(n) 1.0.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::pe - Parsing Expression Serialization</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::pe <span class="opt">?1.0.1?</span></b></li>
<li>package require <b class="pkgname">char</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::pe</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::pt::pe</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></li>
<li><a href="#3"><b class="cmd">::pt::pe</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></li>
<li><a href="#4"><b class="cmd">::pt::pe</b> <b class="method">print</b> <i class="arg">serial</i></a></li>
<li><a href="#5"><b class="cmd">::pt::pe</b> <b class="method">bottomup</b> <i class="arg">cmdprefix</i> <i class="arg">pe</i></a></li>
<li><a href="#6"><b class="cmd">cmdprefix</b> <i class="arg">pe</i> <i class="arg">op</i> <i class="arg">arguments</i></a></li>
<li><a href="#7"><b class="cmd">::pt::pe</b> <b class="method">topdown</b> <i class="arg">cmdprefix</i> <i class="arg">pe</i></a></li>
<li><a href="#8"><b class="cmd">::pt::pe</b> <b class="method">equal</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></li>
<li><a href="#9"><b class="cmd">::pt::pe</b> <b class="method">epsilon</b></a></li>
<li><a href="#10"><b class="cmd">::pt::pe</b> <b class="method">dot</b></a></li>
<li><a href="#11"><b class="cmd">::pt::pe</b> <b class="method">alnum</b></a></li>
<li><a href="#12"><b class="cmd">::pt::pe</b> <b class="method">alpha</b></a></li>
<li><a href="#13"><b class="cmd">::pt::pe</b> <b class="method">ascii</b></a></li>
<li><a href="#14"><b class="cmd">::pt::pe</b> <b class="method">control</b></a></li>
<li><a href="#15"><b class="cmd">::pt::pe</b> <b class="method">digit</b></a></li>
<li><a href="#16"><b class="cmd">::pt::pe</b> <b class="method">graph</b></a></li>
<li><a href="#17"><b class="cmd">::pt::pe</b> <b class="method">lower</b></a></li>
<li><a href="#18"><b class="cmd">::pt::pe</b> <b class="method">print</b></a></li>
<li><a href="#19"><b class="cmd">::pt::pe</b> <b class="method">punct</b></a></li>
<li><a href="#20"><b class="cmd">::pt::pe</b> <b class="method">space</b></a></li>
<li><a href="#21"><b class="cmd">::pt::pe</b> <b class="method">upper</b></a></li>
<li><a href="#22"><b class="cmd">::pt::pe</b> <b class="method">wordchar</b></a></li>
<li><a href="#23"><b class="cmd">::pt::pe</b> <b class="method">xdigit</b></a></li>
<li><a href="#24"><b class="cmd">::pt::pe</b> <b class="method">ddigit</b></a></li>
<li><a href="#25"><b class="cmd">::pt::pe</b> <b class="method">terminal</b> <i class="arg">t</i></a></li>
<li><a href="#26"><b class="cmd">::pt::pe</b> <b class="method">range</b> <i class="arg">ta</i> <i class="arg">tb</i></a></li>
<li><a href="#27"><b class="cmd">::pt::pe</b> <b class="method">nonterminal</b> <i class="arg">nt</i></a></li>
<li><a href="#28"><b class="cmd">::pt::pe</b> <b class="method">choice</b> <i class="arg">pe</i>...</a></li>
<li><a href="#29"><b class="cmd">::pt::pe</b> <b class="method">sequence</b> <i class="arg">pe</i>...</a></li>
<li><a href="#30"><b class="cmd">::pt::pe</b> <b class="method">repeat0</b> <i class="arg">pe</i></a></li>
<li><a href="#31"><b class="cmd">::pt::pe</b> <b class="method">repeat1</b> <i class="arg">pe</i></a></li>
<li><a href="#32"><b class="cmd">::pt::pe</b> <b class="method">optional</b> <i class="arg">pe</i></a></li>
<li><a href="#33"><b class="cmd">::pt::pe</b> <b class="method">ahead</b> <i class="arg">pe</i></a></li>
<li><a href="#34"><b class="cmd">::pt::pe</b> <b class="method">notahead</b> <i class="arg">pe</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides commands to work with the serializations of
parsing expressions as managed by the Parser Tools, and specified in
section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p>
<p>This is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::pe</b> <b class="method">verify</b> <i class="arg">serial</i> <span class="opt">?<i class="arg">canonvar</i>?</span></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
serialization of a parsing expression and will throw an error if that
is not the case. The result of the command is the empty string.</p>
<p>If the argument <i class="arg">canonvar</i> is specified it is interpreted as the
name of a variable in the calling context. This variable will be
written to if and only if <i class="arg">serial</i> is a valid regular
serialization. Its value will be a boolean, with <b class="const">True</b>
indicating that the serialization is not only valid, but also
<i class="term">canonical</i>. <b class="const">False</b> will be written for a valid, but
non-canonical serialization.</p>
<p>For the specification of serializations see the section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><a name="2"><b class="cmd">::pt::pe</b> <b class="method">verify-as-canonical</b> <i class="arg">serial</i></a></dt>
<dd><p>This command verifies that the content of <i class="arg">serial</i> is a valid
<i class="term">canonical</i> serialization of a parsing expression and will throw
an error if that is not the case. The result of the command is the
empty string.</p>
<p>For the specification of canonical serializations see the section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><a name="3"><b class="cmd">::pt::pe</b> <b class="method">canonicalize</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the content of <i class="arg">serial</i> is a valid
<i class="term">regular</i> serialization of a parsing expression and will throw an
error if that is not the case.</p>
<p>It will then convert the input into the <i class="term">canonical</i> serialization
of this parsing expression and return it as its result. If the input
is already canonical it will be returned unchanged.</p>
<p>For the specification of regular and canonical serializations see the
section <span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><a name="4"><b class="cmd">::pt::pe</b> <b class="method">print</b> <i class="arg">serial</i></a></dt>
<dd><p>This command assumes that the argument <i class="arg">serial</i> contains a valid
serialization of a parsing expression and returns a string containing
that PE in a human readable form.</p>
<p>The exact format of this form is not specified and cannot be relied on
for parsing or other machine-based activities.</p>
<p>For the specification of serializations see the section
<span class="sectref"><a href="#section3">PE serialization format</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::pt::pe</b> <b class="method">bottomup</b> <i class="arg">cmdprefix</i> <i class="arg">pe</i></a></dt>
<dd><p>This command walks the parsing expression <i class="arg">pe</i> from the bottom up
to the root, invoking the command prefix <i class="arg">cmdprefix</i> for each
partial expression. This implies that the children of a parsing
expression PE are handled before PE.</p>
<p>The command prefix has the signature</p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="cmd">cmdprefix</b> <i class="arg">pe</i> <i class="arg">op</i> <i class="arg">arguments</i></a></dt>
<dd><p>I.e. it is invoked with the parsing expression <i class="arg">pe</i> the walk is
currently at, the <i class="arg">op</i>'erator in the <i class="arg">pe</i>, and the operator's
<i class="arg">arguments</i>.</p>
<p>The result returned by the command prefix replaces <i class="arg">pe</i> in the
parsing expression it was a child of, allowing transformations of the
expression tree.</p>
<p>This also means that for all inner parsing expressions the contents of
<i class="arg">arguments</i> are the results of the command prefix invoked for the
children of this inner parsing expression.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::pt::pe</b> <b class="method">topdown</b> <i class="arg">cmdprefix</i> <i class="arg">pe</i></a></dt>
<dd><p>This command walks the parsing expression <i class="arg">pe</i> from the root down
to the leaves, invoking the command prefix <i class="arg">cmdprefix</i> for each
partial expression. This implies that the children of a parsing
expression PE are handled after PE.</p>
<p>The command prefix has the same signature as for <b class="method">bottomup</b>,
see above.</p>
<p>The result returned by the command prefix is <em>ignored</em>.</p></dd>
<dt><a name="8"><b class="cmd">::pt::pe</b> <b class="method">equal</b> <i class="arg">seriala</i> <i class="arg">serialb</i></a></dt>
<dd><p>This command tests the two parsing expressions <i class="arg">seriala</i> and
<i class="arg">serialb</i> for structural equality. The result of the command is a
boolean value. It will be set to <b class="const">true</b> if the expressions are
identical, and <b class="const">false</b> otherwise.</p>
<p>String equality is usable only if we can assume that the two parsing
expressions are pure Tcl lists.</p></dd>
<dt><a name="9"><b class="cmd">::pt::pe</b> <b class="method">epsilon</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for epsilon.</p></dd>
<dt><a name="10"><b class="cmd">::pt::pe</b> <b class="method">dot</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for dot.</p></dd>
<dt><a name="11"><b class="cmd">::pt::pe</b> <b class="method">alnum</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for alnum.</p></dd>
<dt><a name="12"><b class="cmd">::pt::pe</b> <b class="method">alpha</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for alpha.</p></dd>
<dt><a name="13"><b class="cmd">::pt::pe</b> <b class="method">ascii</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for ascii.</p></dd>
<dt><a name="14"><b class="cmd">::pt::pe</b> <b class="method">control</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for control.</p></dd>
<dt><a name="15"><b class="cmd">::pt::pe</b> <b class="method">digit</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for digit.</p></dd>
<dt><a name="16"><b class="cmd">::pt::pe</b> <b class="method">graph</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for graph.</p></dd>
<dt><a name="17"><b class="cmd">::pt::pe</b> <b class="method">lower</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for lower.</p></dd>
<dt><a name="18"><b class="cmd">::pt::pe</b> <b class="method">print</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for print.</p></dd>
<dt><a name="19"><b class="cmd">::pt::pe</b> <b class="method">punct</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for punct.</p></dd>
<dt><a name="20"><b class="cmd">::pt::pe</b> <b class="method">space</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for space.</p></dd>
<dt><a name="21"><b class="cmd">::pt::pe</b> <b class="method">upper</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for upper.</p></dd>
<dt><a name="22"><b class="cmd">::pt::pe</b> <b class="method">wordchar</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for wordchar.</p></dd>
<dt><a name="23"><b class="cmd">::pt::pe</b> <b class="method">xdigit</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for xdigit.</p></dd>
<dt><a name="24"><b class="cmd">::pt::pe</b> <b class="method">ddigit</b></a></dt>
<dd><p>This command constructs the atomic parsing expression for ddigit.</p></dd>
<dt><a name="25"><b class="cmd">::pt::pe</b> <b class="method">terminal</b> <i class="arg">t</i></a></dt>
<dd><p>This command constructs the atomic parsing expression for the terminal
symbol <i class="arg">t</i>.</p></dd>
<dt><a name="26"><b class="cmd">::pt::pe</b> <b class="method">range</b> <i class="arg">ta</i> <i class="arg">tb</i></a></dt>
<dd><p>This command constructs the atomic parsing expression for the range of
terminal symbols <i class="arg">ta</i> ... <i class="arg">tb</i>.</p></dd>
<dt><a name="27"><b class="cmd">::pt::pe</b> <b class="method">nonterminal</b> <i class="arg">nt</i></a></dt>
<dd><p>This command constructs the atomic parsing expression for the
nonterminal symbol <i class="arg">nt</i>.</p></dd>
<dt><a name="28"><b class="cmd">::pt::pe</b> <b class="method">choice</b> <i class="arg">pe</i>...</a></dt>
<dd><p>This command constructs the parsing expression representing the
ordered or prioritized choice between the argument parsing
expressions. The first argument has the highest priority.</p></dd>
<dt><a name="29"><b class="cmd">::pt::pe</b> <b class="method">sequence</b> <i class="arg">pe</i>...</a></dt>
<dd><p>This command constructs the parsing expression representing the
sequence of the argument parsing expression. The first argument is the
first element of the sequence.</p></dd>
<dt><a name="30"><b class="cmd">::pt::pe</b> <b class="method">repeat0</b> <i class="arg">pe</i></a></dt>
<dd><p>This command constructs the parsing expression representing the zero
or more repetition of the argument parsing expression <i class="arg">pe</i>, also
known as the kleene closure.</p></dd>
<dt><a name="31"><b class="cmd">::pt::pe</b> <b class="method">repeat1</b> <i class="arg">pe</i></a></dt>
<dd><p>This command constructs the parsing expression representing the one or
more repetition of the argument parsing expression <i class="arg">pe</i>, also
known as the positive kleene closure.</p></dd>
<dt><a name="32"><b class="cmd">::pt::pe</b> <b class="method">optional</b> <i class="arg">pe</i></a></dt>
<dd><p>This command constructs the parsing expression representing the
optionality of the argument parsing expression <i class="arg">pe</i>.</p></dd>
<dt><a name="33"><b class="cmd">::pt::pe</b> <b class="method">ahead</b> <i class="arg">pe</i></a></dt>
<dd><p>This command constructs the parsing expression representing the
positive lookahead of the argument parsing expression <i class="arg">pe</i>.</p></dd>
<dt><a name="34"><b class="cmd">::pt::pe</b> <b class="method">notahead</b> <i class="arg">pe</i></a></dt>
<dd><p>This command constructs the parsing expression representing the
negative lookahead of the argument parsing expression <i class="arg">pe</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_pgen.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
<div class='fossil-doc' data-title='pt::pgen - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::pgen(n) 1.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::pgen - Parser Generator</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Example</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::pgen <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::pgen</b> <i class="arg">inputformat</i> <i class="arg">text</i> <i class="arg">resultformat</i> <span class="opt">?<i class="arg">options...</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a command implementing a
<i class="term"><a href="../../../../index.html#parser_generator">parser generator</a></i>
taking parsing expression grammars as input.</p>
<p>It is the implementation of method <b class="method">generate</b> of <b class="cmd"><a href="../../apps/pt.html">pt</a></b>, the
<i class="term"><a href="../../apps/pt.html">Parser Tools Application</a></i>.</p>
<p>As such the intended audience of this document are people wishing to
modify and/or extend this part of <b class="cmd"><a href="../../apps/pt.html">pt</a></b>'s functionality. Users of
<b class="cmd"><a href="../../apps/pt.html">pt</a></b> on the other hand are hereby refered to the applications'
manpage, i.e. <i class="term"><a href="../../apps/pt.html">Parser Tools Application</a></i>.</p>
<p>It resides in the User Package Layer of Parser Tools.</p>
<p><img alt="arch_user_pkg" src="../../../../image/arch_user_pkg.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::pgen</b> <i class="arg">inputformat</i> <i class="arg">text</i> <i class="arg">resultformat</i> <span class="opt">?<i class="arg">options...</i>?</span></a></dt>
<dd><p>This command takes the parsing expression grammar in <i class="arg">text</i> (in
the format specified by <i class="arg">inputformat</i>), and returns the same
grammar in the format <i class="arg">resultformat</i> as the result of the command.</p>
<p>The two known input formats are <b class="const">peg</b> and <b class="const">json</b>.
Introductions to them, including their formal specifications, can be
found in the <i class="term"><a href="pt_peg_language.html">PEG Language Tutorial</a></i> and
<i class="term"><a href="pt_json_language.html">The JSON Grammar Exchange Format</a></i>. The packages used to
parse these formats are</p>
<dl class="doctools_definitions">
<dt><b class="const">peg</b></dt>
<dd><p><b class="package"><a href="pt_peg_from_peg.html">pt::peg::from::peg</a></b></p></dd>
<dt><b class="const">json</b></dt>
<dd><p><b class="package"><a href="pt_peg_from_json.html">pt::peg::from::json</a></b></p></dd>
</dl>
<p>On the output side the known formats, and the packages used to
generate them are</p>
<dl class="doctools_definitions">
<dt><b class="const">c</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b></p></dd>
<dt><b class="const">container</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_container.html">pt::peg::to::container</a></b></p></dd>
<dt><b class="const">critcl</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_cparam.html">pt::peg::to::cparam</a></b> +
<b class="package"><a href="pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></b></p></dd>
<dt><b class="const">json</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_json.html">pt::peg::to::json</a></b></p></dd>
<dt><b class="const">oo</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b> +
<b class="package"><a href="pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></b></p></dd>
<dt><b class="const">peg</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_peg.html">pt::peg::to::peg</a></b></p></dd>
<dt><b class="const">snit</b></dt>
<dd><p><b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b> +
<b class="package"><a href="pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></b></p></dd>
</dl>
<p>The options supported by each of these formats are documented
with their respective packages.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Example</a></h2>
<p>In this section we are working a complete example, starting with a PEG
grammar and ending with running the parser generated from it over some
input, following the outline shown in the figure below:</p>
<p><img alt="flow" src="../../../../image/flow.png"></p>
<p>Our grammar, assumed to the stored in the file "<b class="file">calculator.peg</b>"
is</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>From this we create a snit-based parser
using the script "<b class="file">gen</b>"</p>
<pre class="doctools_example">
package require Tcl 8.5
package require fileutil
package require pt::pgen
lassign $argv name
set grammar [fileutil::cat $name.peg]
set pclass [pt::pgen peg $gr snit -class $name -file $name.peg -name $name]
fileutil::writeFile $name.tcl $pclass
exit 0
</pre>
<p>calling it like</p>
<pre class="doctools_example"> tclsh8.5 gen calculator </pre>
<p>which leaves us with the parser package and class written to the file
"<b class="file">calculator.tcl</b>".
Assuming that this package is then properly installed in a place where
Tcl can find it we can now use this class via a script like</p>
<pre class="doctools_example">
package require calculator
lassign $argv input
set channel [open $input r]
set parser [calculator]
set ast [$parser parse $channel]
$parser destroy
close $channel
... now process the returned abstract syntax tree ...
</pre>
<p>where the abstract syntax tree stored in the variable will look like</p>
<pre class="doctools_example">
set ast {Expression 0 4
{Factor 0 4
{Term 0 2
{Number 0 2
{Digit 0 0}
{Digit 1 1}
{Digit 2 2}
}
}
{AddOp 3 3}
{Term 4 4
{Number 4 4
{Digit 4 4}
}
}
}
}
</pre>
<p>assuming that the input file and channel contained the text</p>
<pre class="doctools_example"> 120+5 </pre>
<p>A more graphical representation of the tree would be</p>
<p><img alt="expr_ast" src="../../../../image/expr_ast.png"></p>
<p>Regardless, at this point it is the user's responsibility to work with
the tree to reach whatever goal she desires. I.e. analyze it,
transform it, etc. The package <b class="package"><a href="pt_astree.html">pt::ast</a></b> should be of help
here, providing commands to walk such ASTs structures in various ways.</p>
<p>One important thing to note is that the parsers used here return a
data structure representing the structure of the input per the grammar
underlying the parser. There are <em>no</em> callbacks during the
parsing process, i.e. no <i class="term">parsing actions</i>, as most other
parsers will have.</p>
<p>Going back to the last snippet of code, the execution of the parser
for some input, note how the parser instance follows the specified
<i class="term"><a href="pt_parser_api.html">Parser API</a></i>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_rdengine.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
|
<div class='fossil-doc' data-title='pt::rde - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::rde(n) 1.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::rde - Parsing Runtime Support, PARAM based</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Class API</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object API</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::rde <span class="opt">?1.1?</span></b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::stack 1.5</b></li>
<li>package require <b class="pkgname">pt::ast 1.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::rde</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">reset</b> <i class="arg">chan</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">complete</b></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">chan</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">line</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">column</b></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">current</b></a></li>
<li><a href="#9"><i class="arg">objectName</i> <b class="method">location</b></a></li>
<li><a href="#10"><i class="arg">objectName</i> <b class="method">locations</b></a></li>
<li><a href="#11"><i class="arg">objectName</i> <b class="method">ok</b></a></li>
<li><a href="#12"><i class="arg">objectName</i> <b class="method">value</b></a></li>
<li><a href="#13"><i class="arg">objectName</i> <b class="method">error</b></a></li>
<li><a href="#14"><i class="arg">objectName</i> <b class="method">errors</b></a></li>
<li><a href="#15"><i class="arg">objectName</i> <b class="method">tokens</b> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></li>
<li><a href="#16"><i class="arg">objectName</i> <b class="method">symbols</b></a></li>
<li><a href="#17"><i class="arg">objectName</i> <b class="method">known</b></a></li>
<li><a href="#18"><i class="arg">objectName</i> <b class="method">reducible</b></a></li>
<li><a href="#19"><i class="arg">objectName</i> <b class="method">asts</b></a></li>
<li><a href="#20"><i class="arg">objectName</i> <b class="method">ast</b></a></li>
<li><a href="#21"><i class="arg">objectName</i> <b class="method">position</b> <i class="arg">loc</i></a></li>
<li><a href="#22"><i class="arg">objectName</i> <b class="method">i_input_next</b> <i class="arg">msg</i></a></li>
<li><a href="#23"><i class="arg">objectName</i> <b class="method">i_test_alnum</b></a></li>
<li><a href="#24"><i class="arg">objectName</i> <b class="method">i_test_alpha</b></a></li>
<li><a href="#25"><i class="arg">objectName</i> <b class="method">i_test_ascii</b></a></li>
<li><a href="#26"><i class="arg">objectName</i> <b class="method">i_test_char</b> <i class="arg">char</i></a></li>
<li><a href="#27"><i class="arg">objectName</i> <b class="method">i_test_ddigit</b></a></li>
<li><a href="#28"><i class="arg">objectName</i> <b class="method">i_test_digit</b></a></li>
<li><a href="#29"><i class="arg">objectName</i> <b class="method">i_test_graph</b></a></li>
<li><a href="#30"><i class="arg">objectName</i> <b class="method">i_test_lower</b></a></li>
<li><a href="#31"><i class="arg">objectName</i> <b class="method">i_test_print</b></a></li>
<li><a href="#32"><i class="arg">objectName</i> <b class="method">i_test_punct</b></a></li>
<li><a href="#33"><i class="arg">objectName</i> <b class="method">i_test_range</b> <i class="arg">chars</i> <i class="arg">chare</i></a></li>
<li><a href="#34"><i class="arg">objectName</i> <b class="method">i_test_space</b></a></li>
<li><a href="#35"><i class="arg">objectName</i> <b class="method">i_test_upper</b></a></li>
<li><a href="#36"><i class="arg">objectName</i> <b class="method">i_test_wordchar</b></a></li>
<li><a href="#37"><i class="arg">objectName</i> <b class="method">i_test_xdigit</b></a></li>
<li><a href="#38"><i class="arg">objectName</i> <b class="method">i_error_clear</b></a></li>
<li><a href="#39"><i class="arg">objectName</i> <b class="method">i_error_push</b></a></li>
<li><a href="#40"><i class="arg">objectName</i> <b class="method">i_error_pop_merge</b></a></li>
<li><a href="#41"><i class="arg">objectName</i> <b class="method">i_error_nonterminal</b> <i class="arg">symbol</i></a></li>
<li><a href="#42"><i class="arg">objectName</i> <b class="method">i_status_ok</b></a></li>
<li><a href="#43"><i class="arg">objectName</i> <b class="method">i_status_fail</b></a></li>
<li><a href="#44"><i class="arg">objectName</i> <b class="method">i_status_negate</b></a></li>
<li><a href="#45"><i class="arg">objectName</i> <b class="method">i_loc_push</b></a></li>
<li><a href="#46"><i class="arg">objectName</i> <b class="method">i_loc_pop_discard</b></a></li>
<li><a href="#47"><i class="arg">objectName</i> <b class="method">i_loc_pop_rewind</b></a></li>
<li><a href="#48"><i class="arg">objectName</i> <b class="method">i:ok_loc_pop_rewind</b></a></li>
<li><a href="#49"><i class="arg">objectName</i> <b class="method">i_loc_pop_rewind/discard</b></a></li>
<li><a href="#50"><i class="arg">objectName</i> <b class="method">i_symbol_restore</b> <i class="arg">symbol</i></a></li>
<li><a href="#51"><i class="arg">objectName</i> <b class="method">i_symbol_save</b> <i class="arg">symbol</i></a></li>
<li><a href="#52"><i class="arg">objectName</i> <b class="method">i_value_clear</b></a></li>
<li><a href="#53"><i class="arg">objectName</i> <b class="method">i_value_clear/leaf</b></a></li>
<li><a href="#54"><i class="arg">objectName</i> <b class="method">i_value_clear/reduce</b></a></li>
<li><a href="#55"><i class="arg">objectName</i> <b class="method">i:ok_ast_value_push</b></a></li>
<li><a href="#56"><i class="arg">objectName</i> <b class="method">i_ast_push</b></a></li>
<li><a href="#57"><i class="arg">objectName</i> <b class="method">i_ast_pop_rewind</b></a></li>
<li><a href="#58"><i class="arg">objectName</i> <b class="method">i:fail_ast_pop_rewind</b></a></li>
<li><a href="#59"><i class="arg">objectName</i> <b class="method">i_ast_pop_rewind/discard</b></a></li>
<li><a href="#60"><i class="arg">objectName</i> <b class="method">i_ast_pop_discard</b></a></li>
<li><a href="#61"><i class="arg">objectName</i> <b class="method">i_ast_pop_discard/rewind</b></a></li>
<li><a href="#62"><i class="arg">objectName</i> <b class="method">i:ok_continue</b></a></li>
<li><a href="#63"><i class="arg">objectName</i> <b class="method">i:fail_continue</b></a></li>
<li><a href="#64"><i class="arg">objectName</i> <b class="method">i:fail_return</b></a></li>
<li><a href="#65"><i class="arg">objectName</i> <b class="method">i:ok_return</b></a></li>
<li><a href="#66"><i class="arg">objectName</i> <b class="method">si:void_state_push</b></a></li>
<li><a href="#67"><i class="arg">objectName</i> <b class="method">si:void2_state_push</b></a></li>
<li><a href="#68"><i class="arg">objectName</i> <b class="method">si:value_state_push</b></a></li>
<li><a href="#69"><i class="arg">objectName</i> <b class="method">si:void_state_merge</b></a></li>
<li><a href="#70"><i class="arg">objectName</i> <b class="method">si:void_state_merge_ok</b></a></li>
<li><a href="#71"><i class="arg">objectName</i> <b class="method">si:value_state_merge</b></a></li>
<li><a href="#72"><i class="arg">objectName</i> <b class="method">si:value_notahead_start</b></a></li>
<li><a href="#73"><i class="arg">objectName</i> <b class="method">si:void_notahead_exit</b></a></li>
<li><a href="#74"><i class="arg">objectName</i> <b class="method">si:value_notahead_exit</b></a></li>
<li><a href="#75"><i class="arg">objectName</i> <b class="method">si:kleene_abort</b></a></li>
<li><a href="#76"><i class="arg">objectName</i> <b class="method">si:kleene_close</b></a></li>
<li><a href="#77"><i class="arg">objectName</i> <b class="method">si:voidvoid_branch</b></a></li>
<li><a href="#78"><i class="arg">objectName</i> <b class="method">si:voidvalue_branch</b></a></li>
<li><a href="#79"><i class="arg">objectName</i> <b class="method">si:valuevoid_branch</b></a></li>
<li><a href="#80"><i class="arg">objectName</i> <b class="method">si:valuevalue_branch</b></a></li>
<li><a href="#81"><i class="arg">objectName</i> <b class="method">si:voidvoid_part</b></a></li>
<li><a href="#82"><i class="arg">objectName</i> <b class="method">si:voidvalue_part</b></a></li>
<li><a href="#83"><i class="arg">objectName</i> <b class="method">si:valuevalue_part</b></a></li>
<li><a href="#84"><i class="arg">objectName</i> <b class="method">si:value_symbol_start</b> <i class="arg">symbol</i></a></li>
<li><a href="#85"><i class="arg">objectName</i> <b class="method">si:value_void_symbol_start</b> <i class="arg">symbol</i></a></li>
<li><a href="#86"><i class="arg">objectName</i> <b class="method">si:void_symbol_start</b> <i class="arg">symbol</i></a></li>
<li><a href="#87"><i class="arg">objectName</i> <b class="method">si:void_void_symbol_start</b> <i class="arg">symbol</i></a></li>
<li><a href="#88"><i class="arg">objectName</i> <b class="method">si:reduce_symbol_end</b> <i class="arg">symbol</i></a></li>
<li><a href="#89"><i class="arg">objectName</i> <b class="method">si:void_leaf_symbol_end</b> <i class="arg">symbol</i></a></li>
<li><a href="#90"><i class="arg">objectName</i> <b class="method">si:value_leaf_symbol_end</b> <i class="arg">symbol</i></a></li>
<li><a href="#91"><i class="arg">objectName</i> <b class="method">si:value_clear_symbol_end</b> <i class="arg">symbol</i></a></li>
<li><a href="#92"><i class="arg">objectName</i> <b class="method">si:void_clear_symbol_end</b> <i class="arg">symbol</i></a></li>
<li><a href="#93"><i class="arg">objectName</i> <b class="method">si:next_char</b> <i class="arg">tok</i></a></li>
<li><a href="#94"><i class="arg">objectName</i> <b class="method">si:next_range</b> <i class="arg">toks</i> <i class="arg">toke</i></a></li>
<li><a href="#95"><i class="arg">objectName</i> <b class="method">si:next_alnum</b></a></li>
<li><a href="#96"><i class="arg">objectName</i> <b class="method">si:next_alpha</b></a></li>
<li><a href="#97"><i class="arg">objectName</i> <b class="method">si:next_ascii</b></a></li>
<li><a href="#98"><i class="arg">objectName</i> <b class="method">si:next_ddigit</b></a></li>
<li><a href="#99"><i class="arg">objectName</i> <b class="method">si:next_digit</b></a></li>
<li><a href="#100"><i class="arg">objectName</i> <b class="method">si:next_graph</b></a></li>
<li><a href="#101"><i class="arg">objectName</i> <b class="method">si:next_lower</b></a></li>
<li><a href="#102"><i class="arg">objectName</i> <b class="method">si:next_print</b></a></li>
<li><a href="#103"><i class="arg">objectName</i> <b class="method">si:next_punct</b></a></li>
<li><a href="#104"><i class="arg">objectName</i> <b class="method">si:next_space</b></a></li>
<li><a href="#105"><i class="arg">objectName</i> <b class="method">si:next_upper</b></a></li>
<li><a href="#106"><i class="arg">objectName</i> <b class="method">si:next_wordchar</b></a></li>
<li><a href="#107"><i class="arg">objectName</i> <b class="method">si:next_xdigit</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides a class whose instances provide the runtime
support for recursive descent parsers with backtracking, as is needed
for the execution of, for example, parsing expression grammars. It
implements the <i class="term"><a href="pt_param.html">PackRat Machine Specification</a></i>, as such that
document is <em>required</em> reading to understand both this manpage,
and the package itself. The description below does make numerous
shorthand references to the PARAM's instructions and the various parts
of its architectural state.</p>
<p>The package resides in the Execution section of the Core Layer of
Parser Tools.</p>
<p><img alt="arch_core_transform" src="../../../../image/arch_core_transform.png"></p>
<p>Note: This package not only has the standard Tcl implementation, but
also an accelerator, i.e. a C implementation, based on Critcl.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Class API</a></h3>
<p>The package exports the API described here.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::rde</b> <i class="arg">objectName</i></a></dt>
<dd><p>The command creates a new runtime object for a recursive descent
parser with backtracking and returns the fully qualified name of the
object command as its result. The API of this object command is
described in the section <span class="sectref"><a href="#subsection2">Object API</a></span>. It may be used to
invoke various operations on the object.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object API</a></h3>
<p>All objects created by this package provide the following 63 methods
for the manipulation and querying of their state, which is, in essence
the architectural state of a PARAM.</p>
<p>First some general methods and the state accessors.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object, releasing all claimed memory, and
deleting the associated object command.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">reset</b> <i class="arg">chan</i></a></dt>
<dd><p>This method resets the state of the runtme to its defaults, preparing
it for the parsing of the character in the channel <i class="arg">chan</i>, which
becomes IN.</p>
<p>Note here that the Parser Tools are based on Tcl 8.5+. In other words,
the channel argument is not restricted to files, sockets, etc. We have
the full power of <i class="term">reflected channels</i> available.</p>
<p>It should also be noted that the parser pulls the characters from the
input stream as it needs them. If a parser created by this package has
to be operated in a push aka event-driven manner it will be necessary
to go to Tcl 8.6+ and use the <b class="package"><a href="../coroutine/coro_auto.html">coroutine::auto</a></b> to wrap it
into a coroutine where <b class="cmd"><a href="../../../../index.html#read">read</a></b> is properly changed for
push-operation.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">complete</b></a></dt>
<dd><p>This method completes parsing, either returning the AST made from the
elements of ARS, or throwing an error containing the current ER.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">chan</b></a></dt>
<dd><p>This method returns the handle of the channel which is IN.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">line</b></a></dt>
<dd><p>This method returns the line number for the position IN is currently
at. Note that this may not match with the line number for CL, due to
backtracking.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">column</b></a></dt>
<dd><p>This method returns the column for the position IN is currently
at. Note that this may not match with the column for CL, due to
backtracking.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">current</b></a></dt>
<dd><p>This method returns CC.</p></dd>
<dt><a name="9"><i class="arg">objectName</i> <b class="method">location</b></a></dt>
<dd><p>This method returns CL.</p></dd>
<dt><a name="10"><i class="arg">objectName</i> <b class="method">locations</b></a></dt>
<dd><p>This method returns the LS. The topmost entry of the stack will be the
first element of the returned list.</p></dd>
<dt><a name="11"><i class="arg">objectName</i> <b class="method">ok</b></a></dt>
<dd><p>This method returns ST.</p></dd>
<dt><a name="12"><i class="arg">objectName</i> <b class="method">value</b></a></dt>
<dd><p>This method returns SV.</p></dd>
<dt><a name="13"><i class="arg">objectName</i> <b class="method">error</b></a></dt>
<dd><p>This method returns ER. This is either the empty string for an empty
ER, or a list of 2 elements, the location the error is for, and a set
of messages which specify which symbols were expected at the
location. The messages are encoded as one of the possible atomic
parsing expressions (special operators, terminal, range, and
nonterminal operator).</p></dd>
<dt><a name="14"><i class="arg">objectName</i> <b class="method">errors</b></a></dt>
<dd><p>This method returns ES. The topmost entry of the stack will be the
first element of the returned list. Each entry is encoded as described
for <b class="method">error</b>.</p></dd>
<dt><a name="15"><i class="arg">objectName</i> <b class="method">tokens</b> <span class="opt">?<i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span>?</span></a></dt>
<dd><p>This method returns the part of TC for the range of locations of IN
starting at <i class="arg">from</i> and ending at <i class="arg">to</i>. If <i class="arg">to</i> is not
specified it is taken as identical to <i class="arg">from</i>. If neither argument
is specified the whole of TC is returned.</p>
<p>Each token in the returned list is a list of three elements itself,
containing the character at the location, and the associated line and
column numbers, in this order.</p></dd>
<dt><a name="16"><i class="arg">objectName</i> <b class="method">symbols</b></a></dt>
<dd><p>This method returns a dictionary containing NC. Keys are two-element
lists containing nonterminal symbol and location, in this order. The
values are 4-tuples containing CL, ST, ER, and SV, in this order. ER
is encoded as specified for the method <b class="method">error</b>.</p></dd>
<dt><a name="17"><i class="arg">objectName</i> <b class="method">known</b></a></dt>
<dd><p>This method returns a list containing the keys of SC. They are
encoded in the same manner as is done by method <b class="method">symbols</b>.</p></dd>
<dt><a name="18"><i class="arg">objectName</i> <b class="method">reducible</b></a></dt>
<dd><p>This method returns ARS. The topmost entry of the stack will be the
first element of the returned list</p></dd>
<dt><a name="19"><i class="arg">objectName</i> <b class="method">asts</b></a></dt>
<dd><p>This method returns AS. The topmost entry of the stack will be the
first element of the returned list</p></dd>
<dt><a name="20"><i class="arg">objectName</i> <b class="method">ast</b></a></dt>
<dd><p>This is a convenience method returning the topmost element of ARS.</p></dd>
<dt><a name="21"><i class="arg">objectName</i> <b class="method">position</b> <i class="arg">loc</i></a></dt>
<dd><p>This method returns the line and column numbers for the specified
location of IN, assuming that this location has already been reached
during the parsing process.</p></dd>
</dl>
<p>The following methods implement all PARAM instructions. They all have
the prefix "i_".</p>
<p>The control flow is mainly provided by Tcl's builtin commands, like
<b class="cmd">if</b>, <b class="cmd">while</b>, etc., plus a few guarded variants of PARAM
instructions and Tcl commands.. That means that these instruction
variants will do nothing if their guard condition is not
fulfilled. They can be recognized by the prefix "i:ok_" and "i:fail_",
which denote the value ST has to have for the instruction to execute.</p>
<p>The instructions are listed in the same order they occur in the
<i class="term"><a href="pt_param.html">PackRat Machine Specification</a></i>, with the guard variants
listed after their regular implementation, if any, or in their place.</p>
<dl class="doctools_definitions">
<dt><a name="22"><i class="arg">objectName</i> <b class="method">i_input_next</b> <i class="arg">msg</i></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">input_next</b>.</p></dd>
<dt><a name="23"><i class="arg">objectName</i> <b class="method">i_test_alnum</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_alnum</b>.</p></dd>
<dt><a name="24"><i class="arg">objectName</i> <b class="method">i_test_alpha</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_alpha</b>.</p></dd>
<dt><a name="25"><i class="arg">objectName</i> <b class="method">i_test_ascii</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_ascii</b>.</p></dd>
<dt><a name="26"><i class="arg">objectName</i> <b class="method">i_test_char</b> <i class="arg">char</i></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_char</b>.</p></dd>
<dt><a name="27"><i class="arg">objectName</i> <b class="method">i_test_ddigit</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_ddigit</b>.</p></dd>
<dt><a name="28"><i class="arg">objectName</i> <b class="method">i_test_digit</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_digit</b>.</p></dd>
<dt><a name="29"><i class="arg">objectName</i> <b class="method">i_test_graph</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_graph</b>.</p></dd>
<dt><a name="30"><i class="arg">objectName</i> <b class="method">i_test_lower</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_lower</b>.</p></dd>
<dt><a name="31"><i class="arg">objectName</i> <b class="method">i_test_print</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_print</b>.</p></dd>
<dt><a name="32"><i class="arg">objectName</i> <b class="method">i_test_punct</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_punct</b>.</p></dd>
<dt><a name="33"><i class="arg">objectName</i> <b class="method">i_test_range</b> <i class="arg">chars</i> <i class="arg">chare</i></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_range</b>.</p></dd>
<dt><a name="34"><i class="arg">objectName</i> <b class="method">i_test_space</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_space</b>.</p></dd>
<dt><a name="35"><i class="arg">objectName</i> <b class="method">i_test_upper</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_upper</b>.</p></dd>
<dt><a name="36"><i class="arg">objectName</i> <b class="method">i_test_wordchar</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_wordchar</b>.</p></dd>
<dt><a name="37"><i class="arg">objectName</i> <b class="method">i_test_xdigit</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">test_xdigit</b>.</p></dd>
<dt><a name="38"><i class="arg">objectName</i> <b class="method">i_error_clear</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">error_clear</b>.</p></dd>
<dt><a name="39"><i class="arg">objectName</i> <b class="method">i_error_push</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">error_push</b>.</p></dd>
<dt><a name="40"><i class="arg">objectName</i> <b class="method">i_error_pop_merge</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">error_pop_merge</b>.</p></dd>
<dt><a name="41"><i class="arg">objectName</i> <b class="method">i_error_nonterminal</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">error_nonterminal</b>.</p></dd>
<dt><a name="42"><i class="arg">objectName</i> <b class="method">i_status_ok</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">status_ok</b>.</p></dd>
<dt><a name="43"><i class="arg">objectName</i> <b class="method">i_status_fail</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">status_fail</b>.</p></dd>
<dt><a name="44"><i class="arg">objectName</i> <b class="method">i_status_negate</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">status_negate</b>.</p></dd>
<dt><a name="45"><i class="arg">objectName</i> <b class="method">i_loc_push</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">loc_push</b>.</p></dd>
<dt><a name="46"><i class="arg">objectName</i> <b class="method">i_loc_pop_discard</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">loc_pop_discard</b>.</p></dd>
<dt><a name="47"><i class="arg">objectName</i> <b class="method">i_loc_pop_rewind</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">loc_pop_rewind</b>.</p></dd>
<dt><a name="48"><i class="arg">objectName</i> <b class="method">i:ok_loc_pop_rewind</b></a></dt>
<dd><p>This guarded method, a variant of <b class="method">i_loc_pop_rewind</b>, executes only
for "ST == ok".</p></dd>
<dt><a name="49"><i class="arg">objectName</i> <b class="method">i_loc_pop_rewind/discard</b></a></dt>
<dd><p>This method is a convenient combination of control flow and the two
PARAM instructions <b class="cmd">loc_pop_rewind</b> and <b class="cmd">loc_pop_discard</b>. The former
is executed for "ST == fail", the latter for "ST == ok".</p></dd>
<dt><a name="50"><i class="arg">objectName</i> <b class="method">i_symbol_restore</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">symbol_restore</b>.</p>
<p>The boolean result of the check is returned as the result of
the method and can be used with standard Tcl control flow commands.</p></dd>
<dt><a name="51"><i class="arg">objectName</i> <b class="method">i_symbol_save</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">symbol_save</b>.</p></dd>
<dt><a name="52"><i class="arg">objectName</i> <b class="method">i_value_clear</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">value_clear</b>.</p></dd>
<dt><a name="53"><i class="arg">objectName</i> <b class="method">i_value_clear/leaf</b></a></dt>
<dd><p>This method is a convenient combination of control flow and the two
PARAM instructions <b class="cmd">value_clear</b> and <b class="cmd">value_leaf</b>. The former
is executed for "ST == fail", the latter for "ST == ok".</p></dd>
<dt><a name="54"><i class="arg">objectName</i> <b class="method">i_value_clear/reduce</b></a></dt>
<dd><p>This method is a convenient combination of control flow and the two
PARAM instructions <b class="cmd">value_clear</b> and <b class="cmd">value_reduce</b>. The former
is executed for "ST == fail", the latter for "ST == ok".</p></dd>
<dt><a name="55"><i class="arg">objectName</i> <b class="method">i:ok_ast_value_push</b></a></dt>
<dd><p>This method implements a guarded variant of the the PARAM instruction
<b class="cmd">ast_value_push</b>, which executes only for "ST == ok".</p></dd>
<dt><a name="56"><i class="arg">objectName</i> <b class="method">i_ast_push</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">ast_push</b>.</p></dd>
<dt><a name="57"><i class="arg">objectName</i> <b class="method">i_ast_pop_rewind</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">ast_pop_rewind</b>.</p></dd>
<dt><a name="58"><i class="arg">objectName</i> <b class="method">i:fail_ast_pop_rewind</b></a></dt>
<dd><p>This guarded method, a variant of <b class="method">i_ast_pop_rewind</b>, executes only
for "ST == fail".</p></dd>
<dt><a name="59"><i class="arg">objectName</i> <b class="method">i_ast_pop_rewind/discard</b></a></dt>
<dd><p>This method is a convenient combination of control flow and the two
PARAM instructions <b class="cmd">ast_pop_rewind</b> and <b class="cmd">ast_pop_discard</b>. The former
is executed for "ST == fail", the latter for "ST == ok".</p></dd>
<dt><a name="60"><i class="arg">objectName</i> <b class="method">i_ast_pop_discard</b></a></dt>
<dd><p>This method implements the PARAM instruction <b class="cmd">ast_pop_discard</b>.</p></dd>
<dt><a name="61"><i class="arg">objectName</i> <b class="method">i_ast_pop_discard/rewind</b></a></dt>
<dd><p>This method is a convenient combination of control flow and the two
PARAM instructions <b class="cmd">ast_pop_discard</b> and <b class="cmd">ast_pop_rewind</b>. The former
is executed for "ST == fail", the latter for "ST == ok".</p></dd>
<dt><a name="62"><i class="arg">objectName</i> <b class="method">i:ok_continue</b></a></dt>
<dd><p>This guarded method executes only for "ST == ok". Then it aborts the
current iteration of the innermost loop in the calling Tcl procedure.</p></dd>
<dt><a name="63"><i class="arg">objectName</i> <b class="method">i:fail_continue</b></a></dt>
<dd><p>This guarded method executes only for "ST == fail". Then it aborts the
current iteration of the innermost loop in the calling Tcl procedure.</p></dd>
<dt><a name="64"><i class="arg">objectName</i> <b class="method">i:fail_return</b></a></dt>
<dd><p>This guarded method executes only for "ST == fail". Then it aborts the
calling Tcl procedure.</p></dd>
<dt><a name="65"><i class="arg">objectName</i> <b class="method">i:ok_return</b></a></dt>
<dd><p>This guarded method executes only for "ST == ok". Then it aborts the
calling Tcl procedure.</p></dd>
</dl>
<p>The next set of methods are <i class="term">super instructions</i>, meaning that
each implements a longer sequence of instructions commonly used in
parsers. The combinated instructions of the previous set, i.e. those
with names matching the pattern "i_*/*", are actually super
instructions as well, albeit with limited scope, handling 2
instructions with their control flow. The upcoming set is much broader
in scope, folding as much as six or more PARAM instructions into a
single method call.</p>
<p>In this we can see the reasoning behind their use well:</p>
<ol class="doctools_enumerated">
<li><p>By using less instructions the generated parsers become smaller, as
the common parts are now truly part of the common runtime, and not
explicitly written in the parser's code over and over again.</p></li>
<li><p>Using less instructions additionally reduces the overhead associated
with calls into the runtime, i.e. the cost of method dispatch and of
setting up the variable context.</p></li>
<li><p>Another effect of the super instructions is that their internals can
be optimized as well, especially regarding control flow, and stack
use, as the runtime internals are accessible to all instructions
folded into the sequence.</p></li>
</ol>
<dl class="doctools_definitions">
<dt><a name="66"><i class="arg">objectName</i> <b class="method">si:void_state_push</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_loc_push
i_error_clear
i_error_push
</pre>
<p>Parsers use it at the beginning of <i class="term">void</i> sequences and choices
with a <i class="term">void</i> initial branch.</p></dd>
<dt><a name="67"><i class="arg">objectName</i> <b class="method">si:void2_state_push</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_loc_push
i_error_clear
i_error_push
</pre>
<p>Parsers use it at the beginning of optional and repeated expressions.</p></dd>
<dt><a name="68"><i class="arg">objectName</i> <b class="method">si:value_state_push</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_ast_push
i_loc_push
i_error_clear
i_error_push
</pre>
<p>Parsers use it at the beginning of sequences generating an AST and
choices with an initial branch generating an AST.</p></dd>
<dt><a name="69"><i class="arg">objectName</i> <b class="method">si:void_state_merge</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i_loc_pop_rewind/discard
</pre>
<p>Parsers use it at the end of void sequences and choices whose last
branch is void.</p></dd>
<dt><a name="70"><i class="arg">objectName</i> <b class="method">si:void_state_merge_ok</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i_loc_pop_rewind/discard
i_status_ok
</pre>
<p>Parsers use it at the end of optional expressions</p></dd>
<dt><a name="71"><i class="arg">objectName</i> <b class="method">si:value_state_merge</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i_ast_pop_rewind/discard
i_loc_pop_rewind/discard
</pre>
<p>Parsers use it at the end of sequences generating ASTs and choices
whose last branch generates an AST</p></dd>
<dt><a name="72"><i class="arg">objectName</i> <b class="method">si:value_notahead_start</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_loc_push
i_ast_push
</pre>
<p>Parsers use it at the beginning of negative lookahead predicates which
generate ASTs.</p></dd>
<dt><a name="73"><i class="arg">objectName</i> <b class="method">si:void_notahead_exit</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_loc_pop_rewind
i_status_negate
</pre>
<p>Parsers use it at the end of void negative lookahead predicates.</p></dd>
<dt><a name="74"><i class="arg">objectName</i> <b class="method">si:value_notahead_exit</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_ast_pop_discard/rewind
i_loc_pop_rewind
i_status_negate
</pre>
<p>Parsers use it at the end of negative lookahead predicates which
generate ASTs.</p></dd>
<dt><a name="75"><i class="arg">objectName</i> <b class="method">si:kleene_abort</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_loc_pop_rewind/discard
i:fail_return
</pre>
<p>Parsers use it to stop a positive repetition when its first, required, expression fails.</p></dd>
<dt><a name="76"><i class="arg">objectName</i> <b class="method">si:kleene_close</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i_loc_pop_rewind/discard
i:fail_status_ok
i:fail_return
</pre>
<p>Parsers use it at the end of repetitions.</p></dd>
<dt><a name="77"><i class="arg">objectName</i> <b class="method">si:voidvoid_branch</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i:ok_loc_pop_discard
i:ok_return
i_loc_rewind
i_error_push
</pre>
<p>Parsers use it when transiting between branches of a choice when both are void.</p></dd>
<dt><a name="78"><i class="arg">objectName</i> <b class="method">si:voidvalue_branch</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i:ok_loc_pop_discard
i:ok_return
i_ast_push
i_loc_rewind
i_error_push
</pre>
<p>Parsers use it when transiting between branches of a choice when the
failing branch is void, and the next to test generates an AST.</p></dd>
<dt><a name="79"><i class="arg">objectName</i> <b class="method">si:valuevoid_branch</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i_ast_pop_rewind/discard
i:ok_loc_pop_discard
i:ok_return
i_loc_rewind
i_error_push
</pre>
<p>Parsers use it when transiting between branches of a choice when the
failing branch generates an AST, and the next to test is void.</p></dd>
<dt><a name="80"><i class="arg">objectName</i> <b class="method">si:valuevalue_branch</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i_ast_pop_discard
i:ok_loc_pop_discard
i:ok_return
i_ast_rewind
i_loc_rewind
i_error_push
</pre>
<p>Parsers use it when transiting between branches of a choice when both
generate ASTs.</p></dd>
<dt><a name="81"><i class="arg">objectName</i> <b class="method">si:voidvoid_part</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i:fail_loc_pop_rewind
i:fail_return
i_error_push
</pre>
<p>Parsers use it when transiting between parts of a sequence and both
are void.</p></dd>
<dt><a name="82"><i class="arg">objectName</i> <b class="method">si:voidvalue_part</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i:fail_loc_pop_rewind
i:fail_return
i_ast_push
i_error_push
</pre>
<p>Parsers use it when transiting between parts of a sequence and the
sucessfully matched part is void, and after it an AST is generated.</p></dd>
<dt><a name="83"><i class="arg">objectName</i> <b class="method">si:valuevalue_part</b></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_error_pop_merge
i:fail_ast_pop_rewind
i:fail_loc_pop_rewind
i:fail_return
i_error_push
</pre>
<p>Parsers use it when transiting between parts of a sequence and both
parts generate ASTs.</p></dd>
<dt><a name="84"><i class="arg">objectName</i> <b class="method">si:value_symbol_start</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
if/found? i_symbol_restore $symbol
i:found:ok_ast_value_push
i:found_return
i_loc_push
i_ast_push
</pre>
<p>Parsers use it at the beginning of a nonterminal symbol generating an
AST, whose right-hand side may have generated an AST as well.</p></dd>
<dt><a name="85"><i class="arg">objectName</i> <b class="method">si:value_void_symbol_start</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
if/found? i_symbol_restore $symbol
i:found:ok_ast_value_push
i:found_return
i_loc_push
i_ast_push
</pre>
<p>Parsers use it at the beginning of a void nonterminal symbol whose
right-hand side may generate an AST.</p></dd>
<dt><a name="86"><i class="arg">objectName</i> <b class="method">si:void_symbol_start</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
if/found? i_symbol_restore $symbol
i:found_return
i_loc_push
i_ast_push
</pre>
<p>Parsers use it at the beginning of a nonterminal symbol generating an
AST whose right-hand side is void.</p></dd>
<dt><a name="87"><i class="arg">objectName</i> <b class="method">si:void_void_symbol_start</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
if/found? i_symbol_restore $symbol
i:found_return
i_loc_push
</pre>
<p>Parsers use it at the beginning of a void nonterminal symbol whose
right-hand side is void as well.</p></dd>
<dt><a name="88"><i class="arg">objectName</i> <b class="method">si:reduce_symbol_end</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_value_clear/reduce $symbol
i_symbol_save $symbol
i_error_nonterminal $symbol
i_ast_pop_rewind
i_loc_pop_discard
i:ok_ast_value_push
</pre>
<p>Parsers use it at the end of a non-terminal symbol generating an AST
using the AST generated by the right-hand side as child.</p></dd>
<dt><a name="89"><i class="arg">objectName</i> <b class="method">si:void_leaf_symbol_end</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_value_clear/leaf $symbol
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
i:ok_ast_value_push
</pre>
<p>Parsers use it at the end of a non-terminal symbol generating an AST
whose right-hand side is void.</p></dd>
<dt><a name="90"><i class="arg">objectName</i> <b class="method">si:value_leaf_symbol_end</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_value_clear/leaf $symbol
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
i_ast_pop_rewind
i:ok_ast_value_push
</pre>
<p>Parsers use it at the end of a non-terminal symbol generating an AST
discarding the AST generated by the right-hand side.</p></dd>
<dt><a name="91"><i class="arg">objectName</i> <b class="method">si:value_clear_symbol_end</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_value_clear
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
i_ast_pop_rewind
</pre>
<p>Parsers use it at the end of a void non-terminal symbol, discarding
the AST generated by the right-hand side.</p></dd>
<dt><a name="92"><i class="arg">objectName</i> <b class="method">si:void_clear_symbol_end</b> <i class="arg">symbol</i></a></dt>
<dd><p>This method combines</p>
<pre class="doctools_example">
i_value_clear
i_symbol_save $symbol
i_error_nonterminal $symbol
i_loc_pop_discard
</pre>
<p>Parsers use it at the end of a void non-terminal symbol with a void
right-hand side.</p></dd>
<dt><a name="93"><i class="arg">objectName</i> <b class="method">si:next_char</b> <i class="arg">tok</i></a></dt>
<dd></dd>
<dt><a name="94"><i class="arg">objectName</i> <b class="method">si:next_range</b> <i class="arg">toks</i> <i class="arg">toke</i></a></dt>
<dd></dd>
<dt><a name="95"><i class="arg">objectName</i> <b class="method">si:next_alnum</b></a></dt>
<dd></dd>
<dt><a name="96"><i class="arg">objectName</i> <b class="method">si:next_alpha</b></a></dt>
<dd></dd>
<dt><a name="97"><i class="arg">objectName</i> <b class="method">si:next_ascii</b></a></dt>
<dd></dd>
<dt><a name="98"><i class="arg">objectName</i> <b class="method">si:next_ddigit</b></a></dt>
<dd></dd>
<dt><a name="99"><i class="arg">objectName</i> <b class="method">si:next_digit</b></a></dt>
<dd></dd>
<dt><a name="100"><i class="arg">objectName</i> <b class="method">si:next_graph</b></a></dt>
<dd></dd>
<dt><a name="101"><i class="arg">objectName</i> <b class="method">si:next_lower</b></a></dt>
<dd></dd>
<dt><a name="102"><i class="arg">objectName</i> <b class="method">si:next_print</b></a></dt>
<dd></dd>
<dt><a name="103"><i class="arg">objectName</i> <b class="method">si:next_punct</b></a></dt>
<dd></dd>
<dt><a name="104"><i class="arg">objectName</i> <b class="method">si:next_space</b></a></dt>
<dd></dd>
<dt><a name="105"><i class="arg">objectName</i> <b class="method">si:next_upper</b></a></dt>
<dd></dd>
<dt><a name="106"><i class="arg">objectName</i> <b class="method">si:next_wordchar</b></a></dt>
<dd></dd>
<dt><a name="107"><i class="arg">objectName</i> <b class="method">si:next_xdigit</b></a></dt>
<dd><p>These methods all combine</p>
<pre class="doctools_example">
i_input_next $msg
i:fail_return
</pre>
<p>with the appropriate <b class="cmd">i_test_xxx</b> instruction. Parsers use them for
handling atomic expressions.</p></dd>
</dl>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_tclparam_config_nx.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<div class='fossil-doc' data-title='pt::tclparam::configuration::nx - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::tclparam::configuration::nx(n) 1.0.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::tclparam::configuration::nx - Tcl/PARAM, Canned configuration, NX</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::tclparam::configuration::nx <span class="opt">?1.0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::tclparam::configuration::nx</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package is an adjunct to <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b>, to make
the use of this highly configurable package easier by providing a
canned configuration. When applied this configuration causes the
package <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b> to generate
<b class="package">NX</b>-based parser packages.</p>
<p>It is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::tclparam::configuration::nx</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The command applies the configuration provided by this package to the
<i class="arg">cmdprefix</i>, causing the creation of <b class="package">NX</b>-based parsers
whose class is <i class="arg">name</i>, in package <i class="arg">pkg</i> with <i class="arg">version</i>.</p>
<p>The use of a command prefix as API allows application of the
configuration to not only <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b>
(<b class="cmd">pt::peg::to::tclparam configure</b>), but also export manager
instances and PEG containers (<b class="cmd">$export configuration set</b> and
<b class="cmd">[$container exporter] configuration set</b> respectively).</p>
<p>Or anything other command prefix accepting two arguments, option and
value.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<div class='fossil-doc' data-title='pt::tclparam::configuration::snit - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::tclparam::configuration::snit(n) 1.0.2 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::tclparam::configuration::snit - Tcl/PARAM, Canned configuration, Snit</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::tclparam::configuration::snit <span class="opt">?1.0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::tclparam::configuration::snit</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package is an adjunct to <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b>, to make
the use of this highly configurable package easier by providing a
canned configuration. When applied this configuration causes the
package <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b> to generate
<b class="package"><a href="../snit/snit.html">snit</a></b>-based parser packages.</p>
<p>It is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::tclparam::configuration::snit</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The command applies the configuration provided by this package to the
<i class="arg">cmdprefix</i>, causing the creation of <b class="package"><a href="../snit/snit.html">snit</a></b>-based parsers
whose class is <i class="arg">name</i>, in package <i class="arg">pkg</i> with <i class="arg">version</i>.</p>
<p>The use of a command prefix as API allows application of the
configuration to not only <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b>
(<b class="cmd">pt::peg::to::tclparam configure</b>), but also export manager
instances and PEG containers (<b class="cmd">$export configuration set</b> and
<b class="cmd">[$container exporter] configuration set</b> respectively).</p>
<p>Or anything other command prefix accepting two arguments, option and
value.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<div class='fossil-doc' data-title='pt::tclparam::configuration::tcloo - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::tclparam::configuration::tcloo(n) 1.0.4 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::tclparam::configuration::tcloo - Tcl/PARAM, Canned configuration, Tcloo</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::tclparam::configuration::tcloo <span class="opt">?1.0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::tclparam::configuration::tcloo</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package is an adjunct to <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b>, to make
the use of this highly configurable package easier by providing a
canned configuration. When applied this configuration causes the
package <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b> to generate
<b class="package">OO</b>-based parser packages.</p>
<p>It is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::tclparam::configuration::tcloo</b> <b class="method">def</b> <i class="arg">name</i> <i class="arg">pkg</i> <i class="arg">version</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The command applies the configuration provided by this package to the
<i class="arg">cmdprefix</i>, causing the creation of <b class="package">OO</b>-based parsers
whose class is <i class="arg">name</i>, in package <i class="arg">pkg</i> with <i class="arg">version</i>.</p>
<p>The use of a command prefix as API allows application of the
configuration to not only <b class="package"><a href="pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></b>
(<b class="cmd">pt::peg::to::tclparam configure</b>), but also export manager
instances and PEG containers (<b class="cmd">$export configuration set</b> and
<b class="cmd">[$container exporter] configuration set</b> respectively).</p>
<p>Or anything other command prefix accepting two arguments, option and
value.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_to_api.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
|
<div class='fossil-doc' data-title='pt_export_api - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt_export_api(i) 1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt_export_api - Parser Tools Export API</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Converter API</a></li>
<li class="doctools_section"><a href="#section3">Plugin API</a></li>
<li class="doctools_section"><a href="#section4">Options</a></li>
<li class="doctools_section"><a href="#section5">Usage</a></li>
<li class="doctools_section"><a href="#section6">PEG serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">PE serialization format</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">Example</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">CONVERTER</b> <b class="method">reset</b></a></li>
<li><a href="#2"><b class="cmd">CONVERTER</b> <b class="method">configure</b></a></li>
<li><a href="#3"><b class="cmd">CONVERTER</b> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#4"><b class="cmd">CONVERTER</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#5"><b class="cmd">CONVERTER</b> <b class="method">convert</b> <i class="arg">serial</i></a></li>
<li><a href="#6"><b class="cmd">::export</b> <i class="arg">serial</i> <i class="arg">configuration</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This document describes two APIs. First the API shared by all packages
for the conversion of Parsing Expression Grammars into some other
format, and then the API shared by the packages which implement the
export plugins sitting on top of the conversion packages.</p>
<p>Its intended audience are people who wish to create their own
converter for some type of output, and/or an export plugin for
their or some other converter.</p>
<p>It resides in the Export section of the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_export" src="../../../../image/arch_core_export.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Converter API</a></h2>
<p>Any (grammar) export converter has to follow the rules set out below:</p>
<ol class="doctools_enumerated">
<li><p>A converter is a package. Its name is arbitrary, however it is
recommended to put it under the <b class="namespace">::pt::peg::to</b>
namespace.</p></li>
<li><p>The package provides either a single Tcl command following the
API outlined below, or a class command whose instances follow
the same API. The commands which follow the API are called
<i class="term">converter commands</i>.</p></li>
<li><p>A converter command has to provide the following three methods
with the given signatures and semantics. Converter commands
are allowed to provide more methods of their own, but not
less, and they may not provide different semantics for the
standardized methods.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">CONVERTER</b> <b class="method">reset</b></a></dt>
<dd><p>This method has to reset the configuration of the converter to its
default settings. The result of the method has to be the empty
string.</p></dd>
<dt><a name="2"><b class="cmd">CONVERTER</b> <b class="method">configure</b></a></dt>
<dd><p>This method, in this form, has to return a dictionary containing the
current configuration of the converter.</p></dd>
<dt><a name="3"><b class="cmd">CONVERTER</b> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd><p>This method, in this form, has to return the current value of the
specified configuration <i class="arg">option</i> of the converter.</p>
<p>Please read the section <span class="sectref"><a href="#section4">Options</a></span> for the set of standard
options any converter has to accept.
Any other options accepted by a specific converter will be described
in its manpage.</p></dd>
<dt><a name="4"><b class="cmd">CONVERTER</b> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd><p>This command, in this form, sets the specified <i class="arg">option</i>s of the
converter to the given <i class="arg">value</i>s.</p>
<p>Please read the section <span class="sectref"><a href="#section4">Options</a></span> for the set of standard
options a converter has to accept.
Any other options accepted by a specific converter will be described
in its manpage.</p></dd>
<dt><a name="5"><b class="cmd">CONVERTER</b> <b class="method">convert</b> <i class="arg">serial</i></a></dt>
<dd><p>This method has to accept the canonical serialization of a parsing
expression grammar, as specified in section
<span class="sectref"><a href="#section6">PEG serialization format</a></span>, and contained in <i class="arg">serial</i>.
The result of the method has to be the result of converting the input
grammar into whatever the converter is for, per its configuration.</p></dd>
</dl>
</li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Plugin API</a></h2>
<p>Any (grammar) export plugin has to follow the rules set out below:</p>
<ol class="doctools_enumerated">
<li><p>A plugin is a package.</p></li>
<li><p>The name of a plugin package has the form
pt::peg::export::<b class="variable">FOO</b>,
where <b class="variable">FOO</b> is the name of the format the plugin will
generate output for.</p></li>
<li><p>The plugin can expect that the package
<b class="package">pt::peg::export::plugin</b> is present, as
indicator that it was invoked from a genuine plugin manager.</p>
<p>It is recommended that a plugin does check for the presence of
this package.</p></li>
<li><p>A plugin has to provide a single command, in the global
namespace, with the signature shown below. Plugins are allowed
to provide more command of their own, but not less, and they
may not provide different semantics for the standardized
command.</p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="cmd">::export</b> <i class="arg">serial</i> <i class="arg">configuration</i></a></dt>
<dd><p>This command has to accept the canonical serialization of a parsing
expression grammar and the configuration for the converter invoked by
the plugin. The result of the command has to be the result of the
converter invoked by the plugin for th input grammar and
configuration.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">serial</i></dt>
<dd><p>This argument will contain the <i class="term">canonical</i> serialization of the
parsing expression grammar for which to generate the output.
The specification of what a <i class="term">canonical</i> serialization is can be
found in the section <span class="sectref"><a href="#section6">PEG serialization format</a></span>.</p></dd>
<dt>dictionary <i class="arg">configuration</i></dt>
<dd><p>This argument will contain the configuration to configure the
converter with before invoking it, as a dictionary mapping from
options to values.</p>
<p>Please read the section <span class="sectref"><a href="#section4">Options</a></span> for the set of standard
options any converter has to accept, and thus any plugin as well.
Any other options accepted by a specific plugin will be described in
its manpage.</p></dd>
</dl></dd>
</dl>
</li>
<li><p>A single usage cycle of a plugin consists of an invokation of
the command <b class="cmd"><a href="../../../../index.html#export">export</a></b>. This call has to leave the plugin in
a state where another usage cycle can be run without problems.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Options</a></h2>
<p>Each export converter and plugin for an export converter has to accept
the options below in their <b class="method">configure</b> method. Converters are
allowed to ignore the contents of these options when performing a
conversion, but they must not reject them. Plugins are expected to
pass the options given to them to the converter they are invoking.</p>
<dl class="doctools_options">
<dt><b class="option">-file</b> string</dt>
<dd><p>The value of this option is the name of the file or other entity from
which the grammar came, for which the command is run. The default
value is <b class="const">unknown</b>.</p></dd>
<dt><b class="option">-name</b> string</dt>
<dd><p>The value of this option is the name of the grammar we are processing.
The default value is <b class="const">a_pe_grammar</b>.</p></dd>
<dt><b class="option">-user</b> string</dt>
<dd><p>The value of this option is the name of the user for which the command
is run. The default value is <b class="const">unknown</b>.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Usage</a></h2>
<p>To use a converter do</p>
<pre class="doctools_example">
# Get the converter (single command here, not class)
package require the-converter-package
# Provide a configuration
theconverter configure ...
# Perform the conversion
set result [theconverter convert $thegrammarserial]
... process the result ...
</pre>
<p>To use a plugin <b class="variable">FOO</b> do</p>
<pre class="doctools_example">
# Get an export plugin manager
package require pt::peg::export
pt::peg::export E
# Provide a configuration
E configuration set ...
# Run the plugin, and the converter inside.
set result [E export serial $grammarserial FOO]
... process the result ...
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PEG serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expression Grammars as immutable values for transport,
comparison, etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a PEG may have more than one regular serialization only exactly
one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>regular serialization</dt>
<dd><ol class="doctools_enumerated">
<li><p>The serialization of any PEG is a nested Tcl dictionary.</p></li>
<li><p>This dictionary holds a single key, <b class="const">pt::grammar::peg</b>, and its
value. This value holds the contents of the grammar.</p></li>
<li><p>The contents of the grammar are a Tcl dictionary holding the set of
nonterminal symbols and the starting expression. The relevant keys and
their values are</p>
<dl class="doctools_definitions">
<dt><b class="const">rules</b></dt>
<dd><p>The value is a Tcl dictionary whose keys are the names of the
nonterminal symbols known to the grammar.</p>
<ol class="doctools_enumerated">
<li><p>Each nonterminal symbol may occur only once.</p></li>
<li><p>The empty string is not a legal nonterminal symbol.</p></li>
<li><p>The value for each symbol is a Tcl dictionary itself. The relevant
keys and their values in this dictionary are</p>
<dl class="doctools_definitions">
<dt><b class="const">is</b></dt>
<dd><p>The value is the serialization of the parsing expression describing
the symbols sentennial structure, as specified in the section
<span class="sectref"><a href="#section7">PE serialization format</a></span>.</p></dd>
<dt><b class="const">mode</b></dt>
<dd><p>The value can be one of three values specifying how a parser should
handle the semantic value produced by the symbol.</p>
<dl class="doctools_definitions">
<dt><b class="const">value</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal itself,
which has the ASTs of the symbol's right hand side as its children.</p></dd>
<dt><b class="const">leaf</b></dt>
<dd><p>The semantic value of the nonterminal symbol is an abstract syntax
tree consisting of a single node node for the nonterminal, without any
children. Any ASTs generated by the symbol's right hand side are
discarded.</p></dd>
<dt><b class="const">void</b></dt>
<dd><p>The nonterminal has no semantic value. Any ASTs generated by the
symbol's right hand side are discarded (as well).</p></dd>
</dl></dd>
</dl>
</li>
</ol></dd>
<dt><b class="const">start</b></dt>
<dd><p>The value is the serialization of the start parsing expression of the
grammar, as specified in the section <span class="sectref"><a href="#section7">PE serialization format</a></span>.</p></dd>
</dl>
</li>
<li><p>The terminal symbols of the grammar are specified implicitly as the
set of all terminal symbols used in the start expression and on the
RHS of the grammar rules.</p></li>
</ol></dd>
<dt>canonical serialization</dt>
<dd><p>The canonical serialization of a grammar has the format as specified
in the previous item, and then additionally satisfies the constraints
below, which make it unique among all the possible serializations of
this grammar.</p>
<ol class="doctools_enumerated">
<li><p>The keys found in all the nested Tcl dictionaries are sorted in
ascending dictionary order, as generated by Tcl's builtin command
<b class="cmd">lsort -increasing -dict</b>.</p></li>
<li><p>The string representation of the value is the canonical representation
of a Tcl dictionary. I.e. it does not contain superfluous whitespace.</p></li>
</ol></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example</a></h3>
<p>Assuming the following PEG for simple mathematical expressions</p>
<pre class="doctools_example">
PEG calculator (Expression)
Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ;
Sign <- '-' / '+' ;
Number <- Sign? Digit+ ;
Expression <- Term (AddOp Term)* ;
MulOp <- '*' / '/' ;
Term <- Factor (MulOp Factor)* ;
AddOp <- '+'/'-' ;
Factor <- '(' Expression ')' / Number ;
END;
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
pt::grammar::peg {
rules {
AddOp {is {/ {t -} {t +}} mode value}
Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value}
Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value}
Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value}
MulOp {is {/ {t *} {t /}} mode value}
Number {is {x {? {n Sign}} {+ {n Digit}}} mode value}
Sign {is {/ {t -} {t +}} mode value}
Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value}
}
start {n Expression}
}
</pre>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">PE serialization format</a></h2>
<p>Here we specify the format used by the Parser Tools to serialize
Parsing Expressions as immutable values for transport, comparison,
etc.</p>
<p>We distinguish between <i class="term">regular</i> and <i class="term">canonical</i>
serializations.
While a parsing expression may have more than one regular
serialization only exactly one of them will be <i class="term">canonical</i>.</p>
<dl class="doctools_definitions">
<dt>Regular serialization</dt>
<dd><dl class="doctools_definitions">
<dt><b class="const">Atomic Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>The string <b class="const">epsilon</b> is an atomic parsing expression. It matches
the empty string.</p></li>
<li><p>The string <b class="const">dot</b> is an atomic parsing expression. It matches
any character.</p></li>
<li><p>The string <b class="const">alnum</b> is an atomic parsing expression. It matches
any Unicode alphabet or digit character. This is a custom extension of
PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">alpha</b> is an atomic parsing expression. It matches
any Unicode alphabet character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ascii</b> is an atomic parsing expression. It matches
any Unicode character below U0080. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">control</b> is an atomic parsing expression. It matches
any Unicode control character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">digit</b> is an atomic parsing expression. It matches
any Unicode digit character. Note that this includes characters
outside of the [0..9] range. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">graph</b> is an atomic parsing expression. It matches
any Unicode printing character, except for space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">lower</b> is an atomic parsing expression. It matches
any Unicode lower-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">print</b> is an atomic parsing expression. It matches
any Unicode printing character, including space. This is a custom
extension of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">punct</b> is an atomic parsing expression. It matches
any Unicode punctuation character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">space</b> is an atomic parsing expression. It matches
any Unicode space character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">upper</b> is an atomic parsing expression. It matches
any Unicode upper-case alphabet character. This is a custom extension
of PEs based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">wordchar</b> is an atomic parsing expression. It
matches any Unicode word character. This is any alphanumeric character
(see alnum), and any connector punctuation characters (e.g.
underscore). This is a custom extension of PEs based on Tcl's builtin
command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">xdigit</b> is an atomic parsing expression. It matches
any hexadecimal digit character. This is a custom extension of PEs
based on Tcl's builtin command <b class="cmd">string is</b>.</p></li>
<li><p>The string <b class="const">ddigit</b> is an atomic parsing expression. It matches
any decimal digit character. This is a custom extension of PEs based
on Tcl's builtin command <b class="cmd">regexp</b>.</p></li>
<li><p>The expression
[list t <b class="variable">x</b>]
is an atomic parsing expression. It matches the terminal string <b class="variable">x</b>.</p></li>
<li><p>The expression
[list n <b class="variable">A</b>]
is an atomic parsing expression. It matches the nonterminal <b class="variable">A</b>.</p></li>
</ol></dd>
<dt><b class="const">Combined Parsing Expressions</b></dt>
<dd><ol class="doctools_enumerated">
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list / <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">ordered choice</i>, aka <i class="term">prioritized choice</i>.</p></li>
<li><p>For parsing expressions <b class="variable">e1</b>, <b class="variable">e2</b>, ... the result of
[list x <b class="variable">e1</b> <b class="variable">e2</b> ... ]
is a parsing expression as well.
This is the <i class="term">sequence</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list * <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">kleene closure</i>, describing zero or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list + <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">positive kleene closure</i>, describing one or more
repetitions.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list & <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">and lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ! <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">not lookahead predicate</i>.</p></li>
<li><p>For a parsing expression <b class="variable">e</b> the result of
[list ? <b class="variable">e</b>]
is a parsing expression as well.
This is the <i class="term">optional input</i>.</p></li>
</ol></dd>
</dl></dd>
<dt>Canonical serialization</dt>
<dd><p>The canonical serialization of a parsing expression has the format as
specified in the previous item, and then additionally satisfies the
constraints below, which make it unique among all the possible
serializations of this parsing expression.</p>
<ol class="doctools_enumerated">
<li><p>The string representation of the value is the canonical representation
of a pure Tcl list. I.e. it does not contain superfluous whitespace.</p></li>
<li><p>Terminals are <em>not</em> encoded as ranges (where start and end of the
range are identical).</p></li>
</ol></dd>
</dl>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Example</a></h3>
<p>Assuming the parsing expression shown on the right-hand side of the
rule</p>
<pre class="doctools_example">
Expression <- Term (AddOp Term)*
</pre>
<p>then its canonical serialization (except for whitespace) is</p>
<pre class="doctools_example">
{x {n Term} {* {x {n AddOp} {n Term}}}}
</pre>
</div>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/pt/pt_util.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
<div class='fossil-doc' data-title='pt::util - Parser Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">pt::util(n) 1.1 tcllib "Parser Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>pt::util - General utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">pt::ast <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::pt::util</b> <b class="method">error2readable</b> <i class="arg">error</i> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">::pt::util</b> <b class="method">error2position</b> <i class="arg">error</i> <i class="arg">text</i></a></li>
<li><a href="#3"><b class="cmd">::pt::util</b> <b class="method">error2text</b> <i class="arg">error</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Are you lost ?
Do you have trouble understanding this document ?
In that case please read the overview provided by the
<i class="term"><a href="pt_introduction.html">Introduction to Parser Tools</a></i>. This document is the
entrypoint to the whole system the current package is a part of.</p>
<p>This package provides general utility commands.</p>
<p>This is a supporting package in the Core Layer of Parser Tools.</p>
<p><img alt="arch_core_support" src="../../../../image/arch_core_support.png"></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::pt::util</b> <b class="method">error2readable</b> <i class="arg">error</i> <i class="arg">text</i></a></dt>
<dd><p>This command takes the structured form of a syntax <i class="arg">error</i> as
thrown by parser runtimes and the input <i class="arg">text</i> to the parser which
caused that error and returns a string describing the error in a
human-readable form.</p>
<p>The input <i class="arg">text</i> is required to convert the character
position of the error into a more readable line/column format, and to
provide excerpts of the input around the error position.</p></dd>
<dt><a name="2"><b class="cmd">::pt::util</b> <b class="method">error2position</b> <i class="arg">error</i> <i class="arg">text</i></a></dt>
<dd><p>This command takes the structured form of a syntax <i class="arg">error</i> as
thrown by parser runtimes and the input <i class="arg">text</i> to the parser which
caused that error and returns a 2-element list containing the line
number and column index for the error's character position in the
input, in this order.</p></dd>
<dt><a name="3"><b class="cmd">::pt::util</b> <b class="method">error2text</b> <i class="arg">error</i></a></dt>
<dd><p>This command takes the structured form of a syntax <i class="arg">error</i> as
thrown by parser runtimes and returns a list of strings, each
describing a possible expected input in a human-readable form.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>pt</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ebnf">EBNF</a>, <a href="../../../../index.html#ll_k_">LL(k)</a>, <a href="../../../../index.html#peg">PEG</a>, <a href="../../../../index.html#tdpl">TDPL</a>, <a href="../../../../index.html#context_free_languages">context-free languages</a>, <a href="../../../../index.html#expression">expression</a>, <a href="../../../../index.html#grammar">grammar</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#parser">parser</a>, <a href="../../../../index.html#parsing_expression">parsing expression</a>, <a href="../../../../index.html#parsing_expression_grammar">parsing expression grammar</a>, <a href="../../../../index.html#push_down_automaton">push down automaton</a>, <a href="../../../../index.html#recursive_descent">recursive descent</a>, <a href="../../../../index.html#state">state</a>, <a href="../../../../index.html#top_down_parsing_languages">top-down parsing languages</a>, <a href="../../../../index.html#transducer">transducer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Parsing and Grammars</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/rc4/rc4.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<div class='fossil-doc' data-title='rc4 - RC4 Stream Cipher'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">rc4(n) 1.1.0 tcllib "RC4 Stream Cipher"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>rc4 - Implementation of the RC4 stream cipher</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">rc4 <span class="opt">?1.1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::rc4::rc4</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key keyvalue</i> <span class="opt">?<i class="arg">-command lst</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> [ <i class="arg">-in channel</i> | <i class="arg">-infile filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::rc4::RC4Init</b> <i class="arg">keydata</i></a></li>
<li><a href="#3"><b class="cmd">::rc4::RC4</b> <i class="arg">Key</i> <i class="arg">data</i></a></li>
<li><a href="#4"><b class="cmd">::rc4::RC4Final</b> <i class="arg">Key</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the RC4 stream cipher
developed by Ron Rivest of RSA Data Security Inc. The cipher was a
trade secret of RSA but was reverse-engineered and published to the
internet in 1994. It is used in a number of network protocols for
securing communications. To evade trademark restrictions this cipher
is sometimes known as ARCFOUR.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::rc4::rc4</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key keyvalue</i> <span class="opt">?<i class="arg">-command lst</i>?</span> <span class="opt">?<i class="arg">-out channel</i>?</span> [ <i class="arg">-in channel</i> | <i class="arg">-infile filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Perform the RC4 algorithm on either the data provided by the argument
or on the data read from the <i class="arg">-in</i> channel. If an <i class="arg">-out</i>
channel is given then the result will be written to this channel.
Giving the <i class="arg">-hex</i> option will return a hexadecimal encoded
version of the result if not using an <i class="arg">-out</i> channel.</p>
<p>The data to be processes can be specified either as a string argument to
the rc4 command, or as a filename or a pre-opened channel. If the
<i class="arg">-infile</i> argument is given then the file is opened, the data read
and processed and the file is closed. If the <i class="arg">-in</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed. If the <i class="arg">-out</i> argument is given then the
processing result is written to this channel.</p>
<p>If <i class="arg">-command</i> is provided then the rc4 command does not return
anything. Instead the command provided is called with the rc4 result data
appended as the final parameter. This is most useful when reading from Tcl
channels as a fileevent is setup on the channel and the data processed in
chunks</p>
<p>Only one of <i class="arg">-infile</i>, <i class="arg">-in</i> or <i class="arg">string</i> should be given.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::rc4::RC4Init</b> <i class="arg">keydata</i></a></dt>
<dd><p>Initialize a new RC4 key. The <i class="arg">keydata</i> is any amount of binary
data and is used to initialize the cipher internal state.</p></dd>
<dt><a name="3"><b class="cmd">::rc4::RC4</b> <i class="arg">Key</i> <i class="arg">data</i></a></dt>
<dd><p>Encrypt or decrypt the input data using the key obtained by calling
<b class="cmd">RC4Init</b>.</p></dd>
<dt><a name="4"><b class="cmd">::rc4::RC4Final</b> <i class="arg">Key</i></a></dt>
<dd><p>This should be called to clean up resources associated with
<i class="arg">Key</i>. Once this function has been called the key is destroyed.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% set keydata [binary format H* 0123456789abcdef]
% rc4::rc4 -hex -key $keydata HelloWorld
3cf1ae8b7f1c670b612f
% rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f]
HelloWorld
</pre>
<pre class="doctools_example">
set Key [rc4::RC4Init "key data"]
append ciphertext [rc4::RC4 $Key $plaintext]
append ciphertext [rc4::RC4 $Key $additional_plaintext]
rc4::RC4Final $Key
</pre>
<pre class="doctools_example">
proc ::Finish {myState data} {
DoStuffWith $myState $data
}
rc4::rc4 -in $socket -command [list ::Finish $ApplicationState]
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>rc4</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../aes/aes.html">aes(n)</a>, <a href="../blowfish/blowfish.html">blowfish(n)</a>, <a href="../des/des.html">des(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#arcfour">arcfour</a>, <a href="../../../../index.html#data_integrity">data integrity</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#rc4">rc4</a>, <a href="../../../../index.html#security">security</a>, <a href="../../../../index.html#stream_cipher">stream cipher</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/rcs/rcs.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
|
<div class='fossil-doc' data-title='rcs - RCS low level utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">rcs(n) 2.0.2 tcllib "RCS low level utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>rcs - RCS low level utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">TEXT DICT DATA STRUCTURE</a></li>
<li class="doctools_section"><a href="#section4">RCS PATCH FORMAT</a></li>
<li class="doctools_section"><a href="#section5">RCS PATCH COMMAND LIST</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">rcs <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::rcs::text2dict</b> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">::rcs::dict2text</b> <i class="arg">dict</i></a></li>
<li><a href="#3"><b class="cmd">::rcs::file2dict</b> <i class="arg">filename</i></a></li>
<li><a href="#4"><b class="cmd">::rcs::dict2file</b> <i class="arg">filename</i> <i class="arg">dict</i></a></li>
<li><a href="#5"><b class="cmd">::rcs::decodeRcsPatch</b> <i class="arg">text</i></a></li>
<li><a href="#6"><b class="cmd">::rcs::encodeRcsPatch</b> <i class="arg">pcmds</i></a></li>
<li><a href="#7"><b class="cmd">::rcs::applyRcsPatch</b> <i class="arg">text</i> <i class="arg">pcmds</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <i class="term">Revision Control System</i>, short <i class="term"><a href="../../../../index.html#rcs">RCS</a></i>, is a set of
applications and related data formats which allow a system to persist
the history of changes to a text. It, and its relative SCCS are the
basis for many other such systems, like <i class="term"><a href="../../../../index.html#cvs">CVS</a></i>, etc.</p>
<p>This package <em>does not</em> implement RCS.</p>
<p>It only provides a number of low level commands which should be useful
in the implementation of any revision management system, namely:</p>
<ol class="doctools_enumerated">
<li><p>The conversion of texts into and out of a data structures which allow
the easy modification of such text by <i class="term">patches</i>, i.e. sequences
of instructions for the transformation of one text into an other.</p></li>
<li><p>And the conversion of one particular format for patches, the so-called
<i class="term">RCS patches</i>, into and out of data structures which allow
their easy application to texts.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::rcs::text2dict</b> <i class="arg">text</i></a></dt>
<dd><p>Converts the argument <i class="arg">text</i> into a dictionary containing and
representing the same text in an indexed form and returns that
dictionary as its result.
More information about the format of the result can be found in
section <span class="sectref"><a href="#section3">TEXT DICT DATA STRUCTURE</a></span>. This command returns the
<i class="term">canonical</i> representation of the input.</p></dd>
<dt><a name="2"><b class="cmd">::rcs::dict2text</b> <i class="arg">dict</i></a></dt>
<dd><p>This command provides the complementary operation to
<b class="cmd">::rcs::text2dict</b>. It converts a dictionary in the form described
in section <span class="sectref"><a href="#section3">TEXT DICT DATA STRUCTURE</a></span> back into a text and
returns that text as its result. The command does accept non-canonical
representations of the text as its input.</p></dd>
<dt><a name="3"><b class="cmd">::rcs::file2dict</b> <i class="arg">filename</i></a></dt>
<dd><p>This command is identical to <b class="cmd">::rcs::text2dict</b>, except that it
reads the text to convert from the file with path <i class="arg">filename</i>. The
file has to exist and must be readable as well.</p></dd>
<dt><a name="4"><b class="cmd">::rcs::dict2file</b> <i class="arg">filename</i> <i class="arg">dict</i></a></dt>
<dd><p>This command is identical to <b class="cmd">::rcs::2dict2text</b>, except that it
stores the resulting text in the file with path <i class="arg">filename</i>. The
file is created if it did not exist, and must be writable. The result
of the command is the empty string.</p></dd>
<dt><a name="5"><b class="cmd">::rcs::decodeRcsPatch</b> <i class="arg">text</i></a></dt>
<dd><p>Converts the <i class="arg">text</i> argument into a patch command list (PCL) as
specified in the section <span class="sectref"><a href="#section5">RCS PATCH COMMAND LIST</a></span> and
returns this list as its result.
It is assumed that the input text is in <i class="term"><a href="../../../../index.html#diff_n_format">diff -n format</a></i>, also
known as <i class="term"><a href="../../../../index.html#rcs_patch">RCS patch</a></i> format, as specified in the section
<span class="sectref"><a href="#section4">RCS PATCH FORMAT</a></span>.
Please note that the command ignores no-ops in the input, in other
words the resulting PCL contains only instructions doing something.</p></dd>
<dt><a name="6"><b class="cmd">::rcs::encodeRcsPatch</b> <i class="arg">pcmds</i></a></dt>
<dd><p>This command provides the complementary operation to
<b class="cmd">::rcs::decodeRcsPatch</b>. It convert a patch comand list (PCL) list
as specified in the section <span class="sectref"><a href="#section5">RCS PATCH COMMAND LIST</a></span> back
into a text in <span class="sectref"><a href="#section4">RCS PATCH FORMAT</a></span> and returns that text as its result.</p>
<p>Note that this command and <b class="cmd">::rcs::decodeRcsPatch</b> are not exactly
complementary, as the latter strips no-ops from its input, which the
encoder cannot put back anymore into the generated RCS patch. In other
words, the result of a decode/encode step may not match the original
input at the character level, but it will match it at the functional
level.</p></dd>
<dt><a name="7"><b class="cmd">::rcs::applyRcsPatch</b> <i class="arg">text</i> <i class="arg">pcmds</i></a></dt>
<dd><p>This operation applies a patch in the form of a PCL to a text given in
the form of a dictionary and returns the modified text, again as
dictionary, as its result.</p>
<p>To handle actual text use the commands <b class="cmd">::rcs::text2dict</b> (or
equivalent) and <b class="cmd">::rcs::decodeRcsPatch</b> to transform the inputs
into data structures acceptable to this command. Analogously use the
command <b class="cmd">::rcs::dict2text</b> (or equivalent) to transform the
result of this command into actuall text as required.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TEXT DICT DATA STRUCTURE</a></h2>
<p>A text dictionary is a dictionary whose keys are integer numbers and
text strings as the associated values. The keys represent the line
numbers of a text and the values the text of that line. Note that one
text can have many representations as a dictionary, as the index
values only have to be properly ordered for reconstruction, their
exact values do not matter. Similarly the strings may actually span
multiple physical lines.</p>
<p>The text</p>
<pre class="doctools_example">Hello World,
how are you ?
Fine, and you ?</pre>
<p>for example can be represented by</p>
<pre class="doctools_example">{{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}}</pre>
<p>or</p>
<pre class="doctools_example">{{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}}</pre>
<p>or</p>
<pre class="doctools_example">{{-1 {Hello World,
how are you ?}} {4 {Fine, and you ?}}}</pre>
<p>The first dictionary is the <i class="term">canonical</i> representation of the
text, with line numbers starting at <b class="const">1</b>, increasing in steps of
<b class="const">1</b> and without gaps, and each value representing exactly one
physical line.</p>
<p>All the commands creating dictionaries from text will return the
canonical representation of their input text. The commands taking a
dictionary and returning text will generally accept all
representations, canonical or not.</p>
<p>The result of applying a patch to a text dictionary will in general
cause the dictionary to become non-canonical.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">RCS PATCH FORMAT</a></h2>
<p>A <i class="term"><a href="../../../../index.html#patch">patch</a></i> is in general a series of instructions how to transform
an input text T into a different text T', and also encoded in text
form as well.</p>
<p>The text format for patches understood by this package is a very
simple one, known under the names <i class="term"><a href="../../../../index.html#rcs_patch">RCS patch</a></i> or
<i class="term"><a href="../../../../index.html#diff_n_format">diff -n format</a></i>.</p>
<p>Patches in this format contain only two different commands, for the
deletion of old text, and addition of new text. The replacement of
some text by a different text is handled as combination of a deletion
following by an addition.</p>
<p>The format is line oriented, with each line containing either a
command or text data associated with the preceding command.
The first line of a <i class="term"><a href="../../../../index.html#rcs_patch">RCS patch</a></i> is always a command line.</p>
<p>The commands are:</p>
<dl class="doctools_definitions">
<dt>""</dt>
<dd><p>The empty line is a command which does nothing.</p></dd>
<dt>"a<b class="variable">start</b> <b class="variable">n</b>"</dt>
<dd><p>A line starting with the character <b class="const">a</b> is a command for the
addition of text to the output. It is followed by <b class="variable">n</b> lines of
text data. When applying the patch the data is added just between the
lines <b class="variable">start</b> and <b class="variable">start</b>+1. The same effect is had by
appending the data to the existing text on line <b class="variable">start</b>. A
non-existing line <b class="variable">start</b> is created.</p></dd>
<dt>"d<b class="variable">start</b> <b class="variable">n</b>"</dt>
<dd><p>A line starting with the character <b class="const">d</b> is a command for the
deletion of text from the output. When applied it deletes <b class="variable">n</b>
lines of text, and the first line deleted is at index <b class="variable">start</b>.</p></dd>
</dl>
<p>Note that the line indices <b class="variable">start</b> always refer to the text which
is transformed as it is in its original state, without taking the
precending changes into account.</p>
<p>Note also that the instruction have to be applied in the order they
occur in the patch, or in a manner which produces the same result as
in-order application.</p>
<p>This is the format of results returned by the command
<b class="cmd">::rcs::decodeRcsPatch</b> and accepted by the commands
<b class="cmd">::rcs::encodeRcsPatch</b> and <b class="cmd">::rcs::appplyRcsPatch</b>
resp.
Note however that the decoder will strip no-op commands, and the
encoder will not generate no-ops, making them not fully complementary
at the textual level, only at the functional level.</p>
<p>And example of a RCS patch is</p>
<pre class="doctools_example">d1 2
d4 1
a4 2
The named is the mother of all things.
a11 3
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">RCS PATCH COMMAND LIST</a></h2>
<p>Patch command lists (sort: PCL's) are the data structures generated by
patch decoder command and accepted by the patch encoder and applicator
commands. They represent RCS patches in the form of Tcl data
structures.</p>
<p>A PCL is a list where each element represents a single patch
instruction, either an addition, or a deletion. The elements are lists
themselves, where the first item specifies the command and the
remainder represent the arguments of the command.</p>
<dl class="doctools_definitions">
<dt>a</dt>
<dd><p>This is the instruction for the addition of text. It has two
arguments, the index of the line where to add the text, and the text
to add, in this order.</p></dd>
<dt>d</dt>
<dd><p>This is the instruction for the deletion of text. It has two
arguments, the index of the line where to start deleting text, and the
number of lines to delete, in this order.</p></dd>
</dl>
<p>This is the format returned by the patch decoder command and accepted
as input by the patch encoder and applicator commands.</p>
<p>An example for a patch command is shown below, it represents the
example RCS patch found in section <span class="sectref"><a href="#section4">RCS PATCH FORMAT</a></span>.</p>
<pre class="doctools_example">{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.
}} {a 11 {They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!}}}</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>rcs</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../../../../index.html#struct">struct</a>, <a href="../textutil/textutil.html">textutil</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cvs">CVS</a>, <a href="../../../../index.html#rcs">RCS</a>, <a href="../../../../index.html#rcs_patch">RCS patch</a>, <a href="../../../../index.html#sccs">SCCS</a>, <a href="../../../../index.html#diff_n_format">diff -n format</a>, <a href="../../../../index.html#patching">patching</a>, <a href="../../../../index.html#text_conversion">text conversion</a>, <a href="../../../../index.html#text_differences">text differences</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005, Andreas Kupries <[email protected]><br>
Copyright © 2005, Colin McCormack <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/report/report.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
|
<div class='fossil-doc' data-title='report - Matrix reports'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">report(n) 0.3.2 tcllib "Matrix reports"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>report - Create and manipulate report objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">REGIONS</a></li>
<li class="doctools_section"><a href="#section3">LINES</a></li>
<li class="doctools_section"><a href="#section4">TEMPLATES</a></li>
<li class="doctools_section"><a href="#section5">STYLES</a></li>
<li class="doctools_section"><a href="#section6">REPORT METHODS</a></li>
<li class="doctools_section"><a href="#section7">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">report <span class="opt">?0.3.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::report::report</b> <i class="arg">reportName</i> <i class="arg">columns</i> <span class="opt">?<b class="const">style</b> <i class="arg">style arg...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">reportName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::report::defstyle</b> <i class="arg">styleName arguments script</i></a></li>
<li><a href="#4"><b class="cmd">::report::rmstyle</b> <i class="arg">styleName</i></a></li>
<li><a href="#5"><b class="cmd">::report::stylearguments</b> <i class="arg">styleName</i></a></li>
<li><a href="#6"><b class="cmd">::report::stylebody</b> <i class="arg">styleName</i></a></li>
<li><a href="#7"><b class="cmd">::report::styles</b></a></li>
<li><a href="#8"><i class="arg">reportName</i> <b class="method">destroy</b></a></li>
<li><a href="#9"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">disable</b>|<b class="method">enable</b></a></li>
<li><a href="#10"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">enabled</b></a></li>
<li><a href="#11"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">get</b></a></li>
<li><a href="#12"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">set</b> <i class="arg">templatedata</i></a></li>
<li><a href="#13"><i class="arg">reportName</i> <b class="method">tcaption</b> <span class="opt">?<i class="arg">size</i>?</span></a></li>
<li><a href="#14"><i class="arg">reportName</i> <b class="method">bcaption</b> <i class="arg">size</i></a></li>
<li><a href="#15"><i class="arg">reportName</i> <b class="cmd">size</b> <i class="arg">column</i> <span class="opt">?<i class="arg">number</i>|<b class="const">dyn</b>?</span></a></li>
<li><a href="#16"><i class="arg">reportName</i> <b class="cmd">sizes</b> <span class="opt">?<i class="arg">size-list</i>?</span></a></li>
<li><a href="#17"><i class="arg">reportName</i> <b class="cmd">pad</b> <i class="arg">column</i> <span class="opt">?<b class="const">left</b>|<b class="const">right</b>|<b class="const">both</b> <span class="opt">?<i class="arg">padstring</i>?</span>?</span></a></li>
<li><a href="#18"><i class="arg">reportName</i> <b class="cmd">justify</b> <i class="arg">column</i> <span class="opt">?<b class="const">left</b>|<b class="const">right</b>|<b class="const">center</b>?</span></a></li>
<li><a href="#19"><i class="arg">reportName</i> <b class="cmd">printmatrix</b> <i class="arg">matrix</i></a></li>
<li><a href="#20"><i class="arg">reportName</i> <b class="cmd">printmatrix2channel</b> <i class="arg">matrix chan</i></a></li>
<li><a href="#21"><i class="arg">reportName</i> <b class="cmd"><a href="../../../../index.html#columns">columns</a></b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides report objects which can be used by the
formatting methods of matrix objects to generate tabular reports of
the matrix in various forms. The report objects defined here break
each report down into three <span class="sectref"><a href="#section2">REGIONS</a></span> and ten classes of
<i class="term"><a href="../../../../index.html#lines">lines</a></i> (various separator- and data-lines). See the following
section for more detailed explanations.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::report::report</b> <i class="arg">reportName</i> <i class="arg">columns</i> <span class="opt">?<b class="const">style</b> <i class="arg">style arg...</i>?</span></a></dt>
<dd><p>Creates a new report object for a report having <i class="arg">columns</i> columns
with an associated global Tcl command whose name is
<i class="arg">reportName</i>. This command may be used to invoke various
configuration operations on the report. It has the following general
form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">reportName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. See section <span class="sectref"><a href="#section6">REPORT METHODS</a></span> for more
explanations. If no <b class="const">style</b> is specified the report will use
the builtin style <b class="const">plain</b> as its default configuration.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::report::defstyle</b> <i class="arg">styleName arguments script</i></a></dt>
<dd><p>Defines the new style <i class="arg">styleName</i>. See section <span class="sectref"><a href="#section5">STYLES</a></span>
for more information.</p></dd>
<dt><a name="4"><b class="cmd">::report::rmstyle</b> <i class="arg">styleName</i></a></dt>
<dd><p>Deletes the style <i class="arg">styleName</i>. Trying to delete an unknown or
builtin style will result in an error. Beware, this command will not
check that there are no other styles depending on the deleted
one. Deleting a style which is still used by another style FOO will
result in a runtime error when FOO is applied to a newly instantiated
report.</p></dd>
<dt><a name="5"><b class="cmd">::report::stylearguments</b> <i class="arg">styleName</i></a></dt>
<dd><p>This introspection command returns the list of arguments associated
with the style <i class="arg">styleName</i>.</p></dd>
<dt><a name="6"><b class="cmd">::report::stylebody</b> <i class="arg">styleName</i></a></dt>
<dd><p>This introspection command returns the script associated with the
style <i class="arg">styleName</i>.</p></dd>
<dt><a name="7"><b class="cmd">::report::styles</b></a></dt>
<dd><p>This introspection command returns a list containing the names of all
styles known to the package at the time of the call. The order of the
names in the list reflects the order in which the styles were
created. In other words, the first item is the predefined style
<b class="const">plain</b>, followed by the first style defined by the user, and
so on.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">REGIONS</a></h2>
<p>The three regions are the <i class="term">top caption</i>,
<i class="term">data area</i> and <i class="term">bottom caption</i>. These are,
roughly speaking, the title, the values to report and a title at the
bottom. The size of the caption regions can be specified by the user
as the number of rows they occupy in the matrix to format. The size of
the data area is specified implicitly.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">LINES</a></h2>
<p><span class="sectref"><a href="#section4">TEMPLATES</a></span> are associated with each of the ten line classes,
defining the formatting for this kind of line. The user is able to
enable and disable the separator lines at will, but not the data
lines. Their usage is solely determined by the number of rows
contained in the three regions. Data lines and all enabled separators
must have a template associated with them.</p>
<p>Note that the data-lines in a report and the rows in the matrix the
report was generated from are <em>not</em> in a 1:1 relationship if
any row in the matrix has a height greater than one.</p>
<p>The different kinds of lines and the codes used by the report methods
to address them are:</p>
<dl class="doctools_definitions">
<dt><b class="const">top</b></dt>
<dd><p>The topmost line of a report. Separates the report from anything which
came before it. The user can enable the usage of this line at will.</p></dd>
<dt><b class="const">topdatasep</b></dt>
<dd><p>This line is used to separate the data rows in the top caption region,
if it contains more than one row and the user enabled its usage.</p></dd>
<dt><b class="const">topcapsep</b></dt>
<dd><p>This line is used to separate the top caption and data regions, if the
top caption is not empty and the user enabled its usage.</p></dd>
<dt><b class="const">datasep</b></dt>
<dd><p>This line is used to separate the data rows in the data region, if it
contains more than one row and the user enabled its usage.</p></dd>
<dt><b class="const">botcapsep</b></dt>
<dd><p>This line is used to separate the data and bottom caption regions, if
the bottom caption is not empty and the user enabled its usage.</p></dd>
<dt><b class="const">botdatasep</b></dt>
<dd><p>This line is used to separate the data rows in the bottom caption
region, if it contains more than one row and the user enabled its
usage.</p></dd>
<dt><b class="const">bottom</b></dt>
<dd><p>The bottommost line of a report. Separates the report from anything
which comes after it. The user can enable the usage of this line at
will.</p></dd>
<dt><b class="const">topdata</b></dt>
<dd><p>This line defines the format of data lines in the top caption region
of the report.</p></dd>
<dt><b class="const">data</b></dt>
<dd><p>This line defines the format of data lines in the data region of the
report.</p></dd>
<dt><b class="const">botdata</b></dt>
<dd><p>This line defines the format of data lines in the bottom caption
region of the report.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TEMPLATES</a></h2>
<p>Each template is a list of strings used to format the line it is
associated with. For a report containing <b class="variable">n</b> columns a template
for a data line has to contain "<b class="variable">n</b>+1" items and a template for a
separator line "2*<b class="variable">n</b>+1" items.</p>
<p>The items in a data template specify the strings used to separate the
column information. Together with the corresponding items in the
separator templates they form the vertical lines in the report.</p>
<p><em>Note</em> that the corresponding items in all defined templates
have to be of equal length. This will be checked by the report
object. The first item defines the leftmost vertical line and the last
item defines the rightmost vertical line. The item at index <b class="variable">k</b>
("1",...,"<b class="variable">n</b>-2") separates the information in the columns
"<b class="variable">k</b>-1" and "<b class="variable">k</b>".</p>
<p>The items in a separator template having an even-numbered index
("0","2",...) specify the column separators. The item at index
"2*<b class="variable">k</b>" ("0","2",...,"2*<b class="variable">n</b>") corresponds to the items at
index "<b class="variable">k</b>" in the data templates.</p>
<p>The items in a separator template having an odd-numbered index
("1","3",...) specify the strings used to form the horizontal lines in
the separator lines. The item at index "2*<b class="variable">k</b>+1"
("1","3",...,"2*<b class="variable">n</b>+1") corresponds to column "<b class="variable">k</b>". When
generating the horizontal lines the items are replicated to be at
least as long as the size of their column and then cut to the exact
size.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">STYLES</a></h2>
<p>Styles are a way for the user of this package to define common
configurations for report objects and then use them later during the
actual instantiation of report objects. They are defined as tcl
scripts which when executed configure the report object into the
requested configuration.</p>
<p>The command to define styles is <b class="cmd">::report::defstyle</b>. Its last
argument is the tcl <b class="type">script</b> performing the actual
reconfiguration of the report object to obtain the requested style.</p>
<p>In this script the names of all previously defined styles are
available as commands, as are all commands found in a safe interpreter
and the configuration methods of report objects. The latter implicitly
operate on the object currently executing the style script. The
<b class="variable">arguments</b> declared here are available in the <b class="type">script</b> as
variables. When calling the command of a previously declared style all
the arguments expected by it have to be defined in the call.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">REPORT METHODS</a></h2>
<p>The following commands are possible for report objects:</p>
<dl class="doctools_definitions">
<dt><a name="8"><i class="arg">reportName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the report, including its storage space and associated
command.</p></dd>
<dt><a name="9"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">disable</b>|<b class="method">enable</b></a></dt>
<dd><p>Enables or disables the usage of the template addressed by the
<i class="arg">templatecode</i>. Only the codes for separator lines are allowed
here. It is not possible to enable or disable data lines.</p>
<p>Enabling a template causes the report to check all used templates for
inconsistencies in the definition of the vertical lines (See section
<span class="sectref"><a href="#section4">TEMPLATES</a></span>).</p></dd>
<dt><a name="10"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">enabled</b></a></dt>
<dd><p>Returns the whether the template addressed by the <i class="arg">templatecode</i>
is currently enabled or not.</p></dd>
<dt><a name="11"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">get</b></a></dt>
<dd><p>Returns the template currently associated with the kind of line
addressed by the <i class="arg">templatecode</i>. All known templatecodes are
allowed here.</p></dd>
<dt><a name="12"><i class="arg">reportName</i> <i class="arg">templatecode</i> <b class="method">set</b> <i class="arg">templatedata</i></a></dt>
<dd><p>Sets the template associated with the kind of line addressed by the
<i class="arg">templatecode</i> to the new value in <i class="arg">templatedata</i>. See section
<span class="sectref"><a href="#section4">TEMPLATES</a></span> for constraints on the length of templates.</p></dd>
<dt><a name="13"><i class="arg">reportName</i> <b class="method">tcaption</b> <span class="opt">?<i class="arg">size</i>?</span></a></dt>
<dd><p>Specifies the <i class="arg">size</i> of the top caption region as the number rows
it occupies in the matrix to be formatted. Only numbers greater than
or equal to zero are allowed. If no <i class="arg">size</i> is specified the
command will return the current size instead.</p>
<p>Setting the size of the top caption to a value greater than zero
enables the corresponding data template and causes the report to check
all used templates for inconsistencies in the definition of the
vertical lines (See section <span class="sectref"><a href="#section4">TEMPLATES</a></span>).</p></dd>
<dt><a name="14"><i class="arg">reportName</i> <b class="method">bcaption</b> <i class="arg">size</i></a></dt>
<dd><p>Specifies the <i class="arg">size</i> of the bottom caption region as the number
rows it occupies in the matrix to be formatted. Only numbers greater
than or equal to zero are allowed. If no <i class="arg">size</i> is specified the
command will return the current size instead.</p>
<p>Setting the size of the bottom caption to a value greater than zero
enables the corresponding data template and causes the report to check
all used templates for inconsistencies in the definition of the
vertical lines (See section <span class="sectref"><a href="#section4">TEMPLATES</a></span>).</p></dd>
<dt><a name="15"><i class="arg">reportName</i> <b class="cmd">size</b> <i class="arg">column</i> <span class="opt">?<i class="arg">number</i>|<b class="const">dyn</b>?</span></a></dt>
<dd><p>Specifies the size of the <i class="arg">column</i> in the output. The value
<b class="const">dyn</b> means that the columnwidth returned by the matrix to be
formatted for the specified column shall be used. The formatting of
the column is dynamic. If a fixed <i class="arg">number</i> is used instead of
<b class="const">dyn</b> it means that the column has a width of that many
characters (padding excluded). Only numbers greater than zero are
allowed here.</p>
<p>If no size specification is given the command will return the current
size of the <i class="arg">column</i> instead.</p></dd>
<dt><a name="16"><i class="arg">reportName</i> <b class="cmd">sizes</b> <span class="opt">?<i class="arg">size-list</i>?</span></a></dt>
<dd><p>This method allows the user to specify the sizes of all columns in one
call. Its argument is a list containing the sizes to associate with
the columns. The first item is associated with column 0, the next with
column 1, and so on.</p>
<p>If no <i class="arg">size-list</i> is specified the command will return a list
containing the currently set sizes instead.</p></dd>
<dt><a name="17"><i class="arg">reportName</i> <b class="cmd">pad</b> <i class="arg">column</i> <span class="opt">?<b class="const">left</b>|<b class="const">right</b>|<b class="const">both</b> <span class="opt">?<i class="arg">padstring</i>?</span>?</span></a></dt>
<dd><p>This method allows the user to specify padding on the left, right or
both sides of a <i class="arg">column</i>. If the <i class="arg">padstring</i> is not specified
it defaults to a single space character. <em>Note</em>: An alternative
way of specifying the padding is to use vertical separator strings
longer than one character in the templates (See section
<span class="sectref"><a href="#section4">TEMPLATES</a></span>).</p>
<p>If no pad specification is given at all the command will return the
current state of padding for the column instead. This will be a list
containing two elements, the first element the left padding, the
second describing the right padding.</p></dd>
<dt><a name="18"><i class="arg">reportName</i> <b class="cmd">justify</b> <i class="arg">column</i> <span class="opt">?<b class="const">left</b>|<b class="const">right</b>|<b class="const">center</b>?</span></a></dt>
<dd><p>Declares how the cell values for a <i class="arg">column</i> are filled into the
report given the specified size of a column in the report.</p>
<p>For <b class="const">left</b> and <b class="const">right</b> justification a cell value
shorter than the width of the column is bound with its named edge to
the same edge of the column. The other side is filled with spaces. In
the case of <b class="const">center</b> the spaces are placed to both sides of the
value and the left number of spaces is at most one higher than the
right number of spaces.</p>
<p>For a value longer than the width of the column the value is cut at
the named edge. This means for <b class="const">left</b> justification that the
<em>tail</em> (i.e. the <b class="const">right</b> part) of the value is made
visible in the output. For <b class="const">center</b> the value is cut at both
sides to fit into the column and the number of characters cut at the
left side of the value is at most one less than the number of
characters cut from the right side.</p>
<p>If no justification was specified the command will return the current
justification for the column instead.</p></dd>
<dt><a name="19"><i class="arg">reportName</i> <b class="cmd">printmatrix</b> <i class="arg">matrix</i></a></dt>
<dd><p>Formats the <i class="arg">matrix</i> according to the configuration of the report
and returns the resulting string. The matrix has to have the same
number of columns as the report. The matrix also has to have enough
rows so that the top and bottom caption regions do not overlap. The
data region is allowed to be empty.</p></dd>
<dt><a name="20"><i class="arg">reportName</i> <b class="cmd">printmatrix2channel</b> <i class="arg">matrix chan</i></a></dt>
<dd><p>Formats the <i class="arg">matrix</i> according to the configuration of the report
and writes the result into the channel <i class="arg">chan</i>. The matrix has to
have the same number of columns as the report. The matrix also has to
have enough rows so that the top and bottom caption regions do not
overlap. The data region is allowed to be empty.</p></dd>
<dt><a name="21"><i class="arg">reportName</i> <b class="cmd"><a href="../../../../index.html#columns">columns</a></b></a></dt>
<dd><p>Returns the number of columns in the report.</p></dd>
</dl>
<p>The methods <b class="method">size</b>, <b class="method">pad</b> and <b class="method">justify</b> all take
a column index as their first argument. This index is allowed to use
all the forms of an index as accepted by the <b class="cmd">lindex</b> command. The
allowed range for indices is
"0,...,[<b class="variable">reportName</b> columns]-1".</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">EXAMPLES</a></h2>
<p>Our examples define some generally useful report styles.</p>
<p>A simple table with lines surrounding all information and vertical
separators, but without internal horizontal separators.</p>
<pre class="doctools_example">
::report::defstyle simpletable {} {
data set [split "[string repeat "| " [columns]]|"]
top set [split "[string repeat "+ - " [columns]]+"]
bottom set [top get]
top enable
bottom enable
}
</pre>
<p>An extension of a <b class="cmd">simpletable</b>, see above, with a title area.</p>
<pre class="doctools_example">
::report::defstyle captionedtable {{n 1}} {
simpletable
topdata set [data get]
topcapsep set [top get]
topcapsep enable
tcaption $n
}
</pre>
<p>Given the definitions above now an example which actually formats a
matrix into a tabular report. It assumes that the matrix actually
contains useful data.</p>
<pre class="doctools_example">
% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% r printmatrix m
+---+-------------------+-------+-------+--------+
|000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok |7 |13 |53.85 |
|002|CATCH return error |68 |91 |74.73 |
|003|CATCH no catch used|7 |14 |50.00 |
|004|IF if true numeric |12 |33 |36.36 |
|005|IF elseif |15 |47 |31.91 |
| |true numeric | | | |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% m format 2string r
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>report</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#matrix">matrix</a>, <a href="../../../../index.html#report">report</a>, <a href="../../../../index.html#table">table</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002-2014 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/rest/rest.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
|
<div class='fossil-doc' data-title='rest - A framework for RESTful web services'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">rest(n) 1.3.1 tcllib "A framework for RESTful web services"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>rest - define REST web APIs and call them inline or asychronously</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Simple usage</a></li>
<li class="doctools_section"><a href="#section3">Interface usage</a></li>
<li class="doctools_section"><a href="#section4">Examples</a></li>
<li class="doctools_section"><a href="#section5">INCLUDED</a></li>
<li class="doctools_section"><a href="#section6">TLS</a></li>
<li class="doctools_section"><a href="#section7">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">rest <span class="opt">?1.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::rest::simple</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::rest::get</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::rest::post</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::rest::patch</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::rest::head</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::rest::put</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#7"><b class="cmd">::rest::delete</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::rest::save</b> <i class="arg">name</i> <i class="arg">file</i></a></li>
<li><a href="#9"><b class="cmd">::rest::describe</b> <i class="arg">name</i></a></li>
<li><a href="#10"><b class="cmd">::rest::parameters</b> <i class="arg">url</i> <span class="opt">?<i class="arg">key</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::rest::parse_opts</b> <i class="arg">static</i> <i class="arg">required</i> <i class="arg">optional</i> <i class="arg">words</i></a></li>
<li><a href="#12"><b class="cmd">::rest::substitute</b> <i class="arg">string</i> <i class="arg">var</i></a></li>
<li><a href="#13"><b class="cmd">::rest::create_interface</b> <i class="arg">name</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>There are two types of usage this package supports: <i class="term">simple calls</i>,
and complete <i class="term">interfaces</i>.
In an <i class="term">interface</i> you specify a set of rules and then the package
builds the commands which correspond to the REST methods. These
commands can have many options such as input and output
transformations and data type specific formatting. This results in a
cleaner and simpler script.
On the other hand, while a <i class="term">simple call</i> is easier and quicker
to implement it is also less featureful. It takes the url and a few
options about the command and returns the result directly. Any
formatting or checking is up to rest of the script.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Simple usage</a></h2>
<p>In simple usage you make calls using the http method procedures and
then check or process the returned data yourself</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::rest::simple</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd></dd>
<dt><a name="2"><b class="cmd">::rest::get</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd></dd>
<dt><a name="3"><b class="cmd">::rest::post</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd></dd>
<dt><a name="4"><b class="cmd">::rest::patch</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">::rest::head</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd></dd>
<dt><a name="6"><b class="cmd">::rest::put</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd></dd>
<dt><a name="7"><b class="cmd">::rest::delete</b> <i class="arg">url</i> <i class="arg">query</i> <span class="opt">?<i class="arg">config</i>?</span> <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd><p>These commands are all equivalent except for the http method
used.
If you use <b class="cmd">simple</b> then the method should be specified as an
option in the <i class="arg">config</i> dictionary. If that is not done it defaults
to <b class="const">get</b>. If a <i class="arg">body</i> is needed then the <i class="arg">config</i>
dictionary must be present, however it is allowed to be empty.</p>
<p>The <i class="arg">config</i> dictionary supports the following keys</p>
<dl class="doctools_definitions">
<dt><b class="const">auth</b></dt>
<dd></dd>
<dt><b class="const">content-type</b></dt>
<dd></dd>
<dt><b class="const">cookie</b></dt>
<dd></dd>
<dt><b class="const">error-body</b></dt>
<dd></dd>
<dt><b class="const">format</b></dt>
<dd></dd>
<dt><b class="const">headers</b></dt>
<dd></dd>
<dt><b class="const">method</b></dt>
<dd></dd>
</dl>
<p>Two quick examples:</p>
<p>Example 1, Yahoo Boss:</p>
<pre class="doctools_example">
set appid APPID
set search tcl
set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]]
set res [rest::format_json $res]
</pre>
<p>Example 2, Twitter:</p>
<pre class="doctools_example">
set url http://twitter.com/statuses/update.json
set query [list status $text]
set res [rest::simple $url $query {
method post
auth {basic user password}
format json
}]
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Interface usage</a></h2>
<p>An interface to a REST API consists of a series of definitions of REST
calls contained in an array.
The name of that array becomes a namespace containing the defined
commands. Each key of the array specifies the name of the call, with
the associated configuration a dictionary, i.e. key/value pairs.
The acceptable keys, i.e. legal configuration options are described
below.
After creating the definitions in the array simply calling
<b class="cmd">rest::create_interface</b> with the array as argument will then
create the desired commands.</p>
<p>Example, Yahoo Weather:</p>
<pre class="doctools_example">
package require rest
set yweather(forecast) {
url http://weather.yahooapis.com/forecastrss
req_args { p: }
opt_args { u: }
}
rest::create_interface yweather
puts [yweather::forecast -p 94089]
</pre>
<dl class="doctools_definitions">
<dt><a name="8"><b class="cmd">::rest::save</b> <i class="arg">name</i> <i class="arg">file</i></a></dt>
<dd><p>This command saves a copy of the dynamically created procedures for
all the API calls specified in the array variable <i class="arg">name</i> to the
<i class="arg">file</i>, for later loading.</p>
<p>The result of the command is the empty string</p></dd>
<dt><a name="9"><b class="cmd">::rest::describe</b> <i class="arg">name</i></a></dt>
<dd><p>This command prints a description of all API calls specified in the array
variable <i class="arg">name</i> to the channel <b class="const">stdout</b>.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="10"><b class="cmd">::rest::parameters</b> <i class="arg">url</i> <span class="opt">?<i class="arg">key</i>?</span></a></dt>
<dd><p>This command parses an <i class="arg">url</i> query string into a dictionary and
returns said dictionary as its result.</p>
<p>If <i class="arg">key</i> is specified the command will not return the
entire dictionary, but only the value of that <i class="arg">key</i>.</p></dd>
<dt><a name="11"><b class="cmd">::rest::parse_opts</b> <i class="arg">static</i> <i class="arg">required</i> <i class="arg">optional</i> <i class="arg">words</i></a></dt>
<dd><p>This command implements a custom parserfor command options.</p>
<dl class="doctools_arguments">
<dt>dict <i class="arg">static</i></dt>
<dd><p>A dictionary of options and their values that are always present in
the output.</p></dd>
<dt>list <i class="arg">required</i></dt>
<dd><p>A list of options that must be supplied by <i class="arg">words</i></p></dd>
<dt>list <i class="arg">optional</i></dt>
<dd><p>A list of options that may appear in the <i class="arg">words</i>, but are not required.
The elements must be in one of three forms:</p>
<dl class="doctools_definitions">
<dt>name</dt>
<dd><p>The option may be present or not, no default.</p></dd>
<dt>name:</dt>
<dd><p>When present the option requires an argument.</p></dd>
<dt>name:value</dt>
<dd><p>When not present use <b class="const">value</b> as default.</p></dd>
</dl></dd>
<dt>list <i class="arg">words</i></dt>
<dd><p>The words to parse into options and values.</p></dd>
</dl>
<p>The result of the command is a list containing two elements.
The first element is a dictionary containing the parsed options and
their values. The second element is a list of the remaining words.</p></dd>
<dt><a name="12"><b class="cmd">::rest::substitute</b> <i class="arg">string</i> <i class="arg">var</i></a></dt>
<dd><p>This command takes a <i class="arg">string</i>, substitutes values for any option
identifiers found inside and returns the modified string as its
results.</p>
<p>The values to substitute are found in the variable <i class="arg">var</i>,
which is expected to contain a dictionary mapping from the option
identifiers to replace to their values.
<em>Note</em> that option identifiers which have no key in <i class="arg">var</i> are
replaced with the empty string.</p>
<p>The option identifiers in <i class="arg">string</i> have to follow the
syntax <b class="const">%...%</b> where <b class="variable">...</b> may contain any combination of
lower-case alphanumeric characters, plus underscore, colon and dash.</p></dd>
<dt><a name="13"><b class="cmd">::rest::create_interface</b> <i class="arg">name</i></a></dt>
<dd><p>This command creates procedures for all the API calls specified in the
array variable <i class="arg">name</i>.</p>
<p>The name of that array becomes a namespace containing the defined
commands. Each key of the array specifies the name of the call, with
the associated configuration a dictionary, i.e. key/value pairs.
The legal keys and their meanings are:</p>
<dl class="doctools_definitions">
<dt><b class="const">url</b></dt>
<dd><p>The value of this <em>required</em> option must be the target of the
http request.</p></dd>
<dt><b class="const">description</b></dt>
<dd><p>The value of this option must be a short string describing the call.
Default to the empty string, if not specified.
Used only by <b class="cmd">::rest::describe</b>.</p></dd>
<dt><b class="const">body</b></dt>
<dd><p>The value of this option indicates if arguments are required for the
call's request body or not. The acceptable values are listed below.
Defaults to <b class="const">optional</b> if not specified.</p>
<dl class="doctools_definitions">
<dt><b class="const">none</b></dt>
<dd><p>The call has no request body, none must be supplied.</p></dd>
<dt><b class="const">optional</b></dt>
<dd><p>A request body can be supplied, but is not required.</p></dd>
<dt><b class="const">required</b></dt>
<dd><p>A request body must be supplied.</p></dd>
<dt><b class="const">argument</b></dt>
<dd><p>This value must be followed by the name of an option, treating the
entire string as a list. The request body will be used as the value of
that option.</p></dd>
<dt><b class="const">mime_multipart</b></dt>
<dd><p>A request body must be supplied and will be interpreted as each
argument representing one part of a mime/multipart document.
Arguments must be lists containing 2 elements, a list of header keys
and values, and the mime part body, in this order.</p></dd>
</dl></dd>
<dt><b class="const">method</b></dt>
<dd><p>The value of this option must be the name of the HTTP method to call
on the url.
Defaults to GET, if not specified.
The acceptable values are <b class="const">GET</b>, <b class="const">POST</b>, and <b class="const">PUT</b>,
regardless of letter-case.</p></dd>
<dt><b class="const">copy</b></dt>
<dd><p>When present the value of this option specifies the name of a
previously defined call. The definition of that call is copied to the
current call, except for the options specified by the current call
itself.</p></dd>
<dt><b class="const">unset</b></dt>
<dd><p>When present the value of this option contains a list of options in
the current call. These options are removed from the definition. Use
this after <b class="const">copy</b>ing an existing definition to remove options,
instead of overriding their value.</p></dd>
<dt><b class="const">headers</b></dt>
<dd><p>Specification of additional header fields. The value of this option
must be a dictionary, interpreted to contain the new header fields and
their values. The default is to not add any additional headers.</p></dd>
<dt><b class="const">content-type</b></dt>
<dd><p>The value of this option specifies the content type for the request data.</p></dd>
<dt><b class="const">req_args</b></dt>
<dd><p>The value of this option is a list naming the required arguments of
the call. Names ending in a colon will require a value.</p></dd>
<dt><b class="const">opt_args</b></dt>
<dd><p>The value of this option a list naming the arguments that may be
present for a call but are not required.</p></dd>
<dt><b class="const">static_args</b></dt>
<dd><p>The value of this option a list naming the arguments that are always
the same. No sense in troubling the user with these. A leading dash
(<b class="const">-</b>) is allowed but not required to maintain consistency with
the command line.</p></dd>
<dt><b class="const">auth</b></dt>
<dd><p>The value of this option specifies how to authenticate the calls.
No authentication is done if the option is not specified.</p>
<dl class="doctools_definitions">
<dt><b class="const">basic</b></dt>
<dd><p>The user may configure the <i class="term">basic authentication</i> by overriding
the procedure <b class="cmd">basic_auth</b> in the namespace of interface. This
procedure takes two arguments, the username and password, in this
order.</p></dd>
<dt><b class="const">sign</b></dt>
<dd><p>The value must actually be a list with the second element the name of
a procedure which will be called to perform request signing.</p></dd>
</dl></dd>
<dt><b class="const">callback</b></dt>
<dd><p>If this option is present then the method will be created as an
<i class="term">async</i> call. Such calls will return immediately with the value
of the associated http token instead of the call's result. The event
loop must be active to use this option.</p>
<p>The value of this option is treated as a command prefix which
is invoked when the HTTP call is complete. The prefix will receive at
least two additional arguments, the name of the calling procedure and
the status of the result (one of <b class="const">OK</b> or <b class="const">ERROR</b>), in this
order.</p>
<p>In case of <b class="const">OK</b> a third argument is added, the data
associated with the result.</p>
<p>If and only if the <b class="const">ERROR</b> is a redirection, the location
redirected to will be added as argument.
Further, if the configuration key <b class="const">error-body</b> is set to
<b class="const">true</b> the data associated with the result will be added as
argument as well.</p>
<p>The http request header will be available in that procedure via
<b class="cmd">upvar token token</b>.</p></dd>
<dt><b class="const">cookie</b></dt>
<dd><p>The value of this option is a list of cookies to be passed in the http
header. This is a shortcut to the <b class="const">headers</b> option.</p></dd>
<dt><b class="const">input_transform</b></dt>
<dd><p>The value of this option is a command prefix or script to perform a
transformation on the query before invoking the call. A script
transform is wrapped into an automatically generated internal
procedure.</p>
<p>If not specified no transformation is done.</p>
<p>The command (prefix) must accept a single argument, the query
(a dictionary) to transform, and must return the modified query (again
as dictionary) as its result.
The request body is accessible in the transform command via
<b class="cmd">upvar body body</b>.</p></dd>
<dt><b class="const">format</b></dt>
<dd></dd>
<dt><b class="const">result</b></dt>
<dd><p>The value of this option specifies the format of the returned
data.
Defaults to <b class="const">auto</b> if not specified.
The acceptable values are:</p>
<dl class="doctools_definitions">
<dt><b class="const">auto</b></dt>
<dd><p>Auto detect between <b class="const">xml</b> and <b class="const">json</b>.</p></dd>
<dt><b class="const">discard</b></dt>
<dd></dd>
<dt><b class="const">json</b></dt>
<dd></dd>
<dt><b class="const">raw</b></dt>
<dd></dd>
<dt><b class="const">rss</b></dt>
<dd><p>This is formatted as a special case of <b class="const">xml</b>.</p></dd>
<dt><b class="const">tdom</b></dt>
<dd></dd>
<dt><b class="const">xml</b></dt>
<dd></dd>
</dl></dd>
<dt><b class="const">pre_transform</b></dt>
<dd><p>The value of this option is a command prefix or script to perform a
transformation on the result of a call (<em>before</em> the application
of the output transform as per <b class="const">format</b>). A script transform is
wrapped into an automatically generated internal procedure.</p>
<p>If not specified no transformation is done.</p>
<p>The command (prefix) must accept a single argument, the result
to transform, and must return the modified result as its result.</p>
<p>The http request header is accessible in the transform command
via <b class="cmd">upvar token token</b></p></dd>
<dt><b class="const">post_transform</b></dt>
<dd><p>The value of this option is a command prefix or script to perform a
transformation on the result of a call (<em>after</em> the application
of the output transform as per <b class="const">format</b>). A script transform is
wrapped into an automatically generated internal procedure.</p>
<p>If not specified no transformation is done.</p>
<p>The command (prefix) must accept a single argument, the result
to transform, and must return the modified result as its result.</p>
<p>The http request header is accessible in the transform command
via <b class="cmd">upvar token token</b></p></dd>
<dt><b class="const">check_result</b></dt>
<dd><p>The value of this option must be list of two expressions, either of
which may be empty.</p>
<p>The first expression is checks the OK condition, it must return
<b class="const">true</b> when the result is satisfactory, and <b class="const">false</b>
otherwise.</p>
<p>The second expression is the ERROR condition, it must return
<b class="const">false</b> unless there is an error, then it has to return
<b class="const">true</b>.</p></dd>
<dt><b class="const">error_body</b></dt>
<dd><p>The value of this option determines whether to return the response
when encountering an HTTP error, or not. The default is to not return
the response body on error.</p>
<p>See <b class="const">callback</b> above for more information.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Examples</a></h2>
<p>Yahoo Geo:</p>
<pre class="doctools_example">
set ygeo(parse) {
url http://wherein.yahooapis.com/v1/document
method post
body { arg documentContent }
}
ygeo::parse "san jose ca"
# "san jose ca" will be interpreted as if it were specified as the -documentContent option
</pre>
<p>Google Docs:</p>
<pre class="doctools_example">
set gdocs(upload) {
url http://docs.google.com/feeds/default/private/full
body mime_multipart
}
gdocs::upload [list {Content-Type application/atom+xml} $xml] [list {Content-Type image/jpeg} $filedata]
</pre>
<p>Delicious:</p>
<pre class="doctools_example">
set delicious(updated) {
url https://api.del.icio.us/v1/posts/update
auth basic
}
rest::create_interface flickr
flickr::basic_auth username password
</pre>
<p>Flickr:</p>
<pre class="doctools_example">
set flickr(auth.getToken) {
url http://api.flickr.com/services/rest/
req_args { api_key: secret: }
auth { sign do_signature }
}
rest::create_interface flickr
proc ::flickr::do_signature {query} {
# perform some operations on the query here
return $query
}
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">INCLUDED</a></h2>
<p>The package provides functional but incomplete implementations for the following services:</p>
<dl class="doctools_definitions">
<dt><b class="const">del.icio.us</b></dt>
<dd></dd>
<dt><b class="const">facebook</b></dt>
<dd></dd>
<dt><b class="const">flickr</b></dt>
<dd></dd>
<dt><b class="const">twitter</b></dt>
<dd></dd>
<dt><b class="const">google calendar</b></dt>
<dd></dd>
<dt><b class="const">yahoo boss</b></dt>
<dd></dd>
<dt><b class="const">yahoo weather</b></dt>
<dd></dd>
</dl>
<p>Please either read the package's implementation, or use
<b class="cmd">rest::describe</b> after loading it for their details.</p>
<p>Do not forget developers' documentation on the respective sites either.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">TLS</a></h2>
<p>The <b class="package">rest</b> package can be used with <i class="term"><a href="../../../../index.html#https">https</a></i>-secured
services, by requiring the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package and then registering
it with the <b class="package"><a href="../../../../index.html#http">http</a></b> package it is sitting on top of.
Example</p>
<pre class="doctools_example">
package require tls
http::register https 443 ::tls::socket
</pre>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>rest</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ripemd/ripemd128.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
<div class='fossil-doc' data-title='ripemd128 - RIPEMD Message-Digest Algorithm'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ripemd128(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ripemd128 - RIPEMD-128 Message-Digest Algorithm</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">ripemd128 <span class="opt">?1.0.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ripemd::ripemd128</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::ripemd::hmac128</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#3"><b class="cmd">::ripemd::RIPEMD128Init</b></a></li>
<li><a href="#4"><b class="cmd">::ripemd::RIPEMD128Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::ripemd::RIPEMD128Final</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::ripemd::RIPEHMAC128Init</b> <i class="arg">key</i></a></li>
<li><a href="#7"><b class="cmd">::ripemd::RIPEHMAC128Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::ripemd::RIPEHMAC128Final</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the RIPEMD-128 message-digest
algorithm (1). This algorithm takes an arbitrary quantity of data and
generates a 128-bit message digest from the input. The RIPEMD-128
algorithm is based upon the MD4 algorithm (2, 4) but has been
cryptographically strengthened against weaknesses that have been found
in MD4 (4). RIPEMD-128 has been designed to be a drop-in replacement
for MD4 and MD5 (5). If security is the major consideration, then
RIPEMD-160 or SHA1 should be considered.</p>
<p>This package will use <b class="package">Trf</b> to
accelerate the digest computation if available. In
the absence of an accelerator package the pure-Tcl implementation will
be used.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ripemd::ripemd128</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate the RIPEMD-128 digest of the data given in string. This is
returned as a binary string by default. Giving the <i class="arg">-hex</i> option
will return a hexadecimal encoded version of the digest.</p>
<p>The data to be hashed can be specified either as a string argument to
the ripemd128 command, or as a filename or a pre-opened channel. If the
<i class="arg">-filename</i> argument is given then the file is opened, the data read
and hashed and the file is closed. If the <i class="arg">-channel</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed.</p>
<p>Only one of <i class="arg">-file</i>, <i class="arg">-channel</i> or <i class="arg">string</i> should be given.</p></dd>
<dt><a name="2"><b class="cmd">::ripemd::hmac128</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate an Hashed Message Authentication digest (HMAC) using the
RIPEMD-128 digest algorithm. HMACs are described in RFC 2104 (6) and
provide a RIPEMD-128 digest that includes a key. All options other
than <i class="arg">-key</i> are as for the <b class="cmd">::ripemd::ripemd128</b> command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>For the programmer, hash functions can be viewed as a bucket into which
one pours data. When you have finished, you extract a value that is
uniquely derived from the data that was poured into the bucket. The
programming interface to the hash operates on a token (equivalent to the
bucket). You call <b class="cmd">RIPEMD128Init</b> to obtain a token and then call
<b class="cmd">RIPEMD128Update</b> as many times as required to add data to the hash. To
release any resources and obtain the hash value, you then call
<b class="cmd">RIPEMD128Final</b>. An equivalent set of functions gives you a keyed
digest (HMAC).</p>
<p>If you have <b class="package">critcl</b> and have built the <b class="package">tcllibc</b>
package then the implementation of the hashing function will be
performed by compiled code. Alternatively if both the Trf and Memchan
extensions are available then these will be used. Finally the package
will revert to a pure-Tcl implementation. The programming interface
remains the same, however.</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::ripemd::RIPEMD128Init</b></a></dt>
<dd><p>Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the
remaining functions.</p></dd>
<dt><a name="4"><b class="cmd">::ripemd::RIPEMD128Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the hash identified by token. Calling
<em>RIPEMD128Update $token "abcd"</em> is equivalent to calling
<em>RIPEMD128Update $token "ab"</em> followed by
<em>RIPEMD128Update $token "cb"</em>. See <span class="sectref"><a href="#section4">EXAMPLES</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::ripemd::RIPEMD128Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the hash value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a binary string of 16 bytes representing the 128 bit
RIPEMD-128 digest value.</p></dd>
<dt><a name="6"><b class="cmd">::ripemd::RIPEHMAC128Init</b> <i class="arg">key</i></a></dt>
<dd><p>This is equivalent to the <b class="cmd">::ripemd::RIPEMD128Init</b> command
except that it requires the key that will be included in the HMAC.</p></dd>
<dt><a name="7"><b class="cmd">::ripemd::RIPEHMAC128Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="8"><b class="cmd">::ripemd::RIPEHMAC128Final</b> <i class="arg">token</i></a></dt>
<dd><p>These commands are identical to the RIPEMD128 equivalent commands.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% ripemd::ripemd128 -hex "Tcl does RIPEMD-128"
3cab177bae65205d81e7978f63556c63
</pre>
<pre class="doctools_example">
% ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128"
b359dc5971a05beea0be7b106b30e389
</pre>
<pre class="doctools_example">
% set tok [ripemd::RIPEMD128Init]
::ripemd::1
% ripemd::RIPEMD128Update $tok "Tcl "
% ripemd::RIPEMD128Update $tok "does "
% ripemd::RIPEMD128Update $tok "RIPEMD-128"
% ripemd::Hex [ripemd::RIPEMD128Final $tok]
3cab177bae65205d81e7978f63556c63
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>H. Dobbertin, A. Bosselaers, B. Preneel,
"RIPEMD-160, a strengthened version of RIPEMD"
<a href="http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf">http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf</a></p></li>
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes
and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90
Proceedings, pages 303-311, Springer-Verlag, 1991.</p></li>
<li><p>Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology
vol 11 (4), pp. 253-271 (1998)</p></li>
<li><p>Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and
RSA Data Security, Inc, April 1992.
(<a href="http://www.rfc-editor.org/rfc/rfc1321.txt">http://www.rfc-editor.org/rfc/rfc1321.txt</a>)</p></li>
<li><p>Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
Message Authentication", RFC 2104, February 1997.
(<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">http://www.rfc-editor.org/rfc/rfc2104.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ripemd</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md4/md4.html">md4</a>, <a href="../md5/md5.html">md5</a>, <a href="ripemd160.html">ripemd160</a>, <a href="../sha1/sha1.html">sha1</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ripemd">RIPEMD</a>, <a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#md4">md4</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#rfc_1320">rfc 1320</a>, <a href="../../../../index.html#rfc_1321">rfc 1321</a>, <a href="../../../../index.html#rfc_2104">rfc 2104</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/ripemd/ripemd160.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
<div class='fossil-doc' data-title='ripemd160 - RIPEMD Message-Digest Algorithm'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">ripemd160(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>ripemd160 - RIPEMD-160 Message-Digest Algorithm</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">ripemd160 <span class="opt">?1.0.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::ripemd::ripemd160</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::ripemd::hmac160</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></li>
<li><a href="#3"><b class="cmd">::ripemd::RIPEMD160Init</b></a></li>
<li><a href="#4"><b class="cmd">::ripemd::RIPEMD160Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#5"><b class="cmd">::ripemd::RIPEMD160Final</b> <i class="arg">token</i></a></li>
<li><a href="#6"><b class="cmd">::ripemd::RIPEHMAC160Init</b> <i class="arg">key</i></a></li>
<li><a href="#7"><b class="cmd">::ripemd::RIPEHMAC160Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::ripemd::RIPEHMAC160Final</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is an implementation in Tcl of the RIPEMD-160 message-digest
algorithm (1). This algorithm takes an arbitrary quantity of data and
generates a 160-bit message digest from the input. The RIPEMD-160
algorithm is based upon the MD4 algorithm (2, 4) but has been
cryptographically strengthened against weaknesses that have been found
in MD4 (4).</p>
<p>This package will use <b class="package">cryptkit</b> or <b class="package">Trf</b> to
accelerate the digest computation if either package is available. In
the absence of an accelerator package the pure-Tcl implementation will
be used.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::ripemd::ripemd160</b> <span class="opt">?<i class="arg">-hex</i>?</span> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate the RIPEMD-160 digest of the data given in string. This is
returned as a binary string by default. Giving the <i class="arg">-hex</i> option
will return a hexadecimal encoded version of the digest.</p>
<p>The data to be hashed can be specified either as a string argument to
the ripemd160 command, or as a filename or a pre-opened channel. If the
<i class="arg">-filename</i> argument is given then the file is opened, the data read
and hashed and the file is closed. If the <i class="arg">-channel</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed.</p>
<p>Only one of <i class="arg">-file</i>, <i class="arg">-channel</i> or <i class="arg">string</i> should be given.</p></dd>
<dt><a name="2"><b class="cmd">::ripemd::hmac160</b> <span class="opt">?<i class="arg">-hex</i>?</span> <i class="arg">-key key</i> [ <i class="arg">-channel channel</i> | <i class="arg">-file filename</i> | <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate an Hashed Message Authentication digest (HMAC) using the
RIPEMD-160 digest algorithm. HMACs are described in RFC 2104 (5) and
provide a RIPEMD-160 digest that includes a key. All options other
than <i class="arg">-key</i> are as for the <b class="cmd">::ripemd::ripemd160</b> command.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>For the programmer, hash functions can be viewed as a bucket into which
one pours data. When you have finished, you extract a value that is
uniquely derived from the data that was poured into the bucket. The
programming interface to the hash operates on a token (equivalent to the
bucket). You call <b class="cmd">RIPEMD160Init</b> to obtain a token and then call
<b class="cmd">RIPEMD160Update</b> as many times as required to add data to the hash. To
release any resources and obtain the hash value, you then call
<b class="cmd">RIPEMD160Final</b>. An equivalent set of functions gives you a keyed
digest (HMAC).</p>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::ripemd::RIPEMD160Init</b></a></dt>
<dd><p>Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the
remaining functions.</p></dd>
<dt><a name="4"><b class="cmd">::ripemd::RIPEMD160Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the hash identified by token. Calling
<em>RIPEMD160Update $token "abcd"</em> is equivalent to calling
<em>RIPEMD160Update $token "ab"</em> followed by
<em>RIPEMD160Update $token "cb"</em>. See <span class="sectref"><a href="#section4">EXAMPLES</a></span>.</p></dd>
<dt><a name="5"><b class="cmd">::ripemd::RIPEMD160Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the hash value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a binary string of 16 bytes representing the 160 bit
RIPEMD-160 digest value.</p></dd>
<dt><a name="6"><b class="cmd">::ripemd::RIPEHMAC160Init</b> <i class="arg">key</i></a></dt>
<dd><p>This is equivalent to the <b class="cmd">::ripemd::RIPEMD160Init</b> command
except that it requires the key that will be included in the HMAC.</p></dd>
<dt><a name="7"><b class="cmd">::ripemd::RIPEHMAC160Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="8"><b class="cmd">::ripemd::RIPEHMAC160Final</b> <i class="arg">token</i></a></dt>
<dd><p>These commands are identical to the RIPEMD160 equivalent commands.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% ripemd::ripemd160 -hex "Tcl does RIPEMD-160"
0829dea75a1a7074c702896723fe37763481a0a7
</pre>
<pre class="doctools_example">
% ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160"
bf0c927231733686731dddb470b64a9c23f7f53b
</pre>
<pre class="doctools_example">
% set tok [ripemd::RIPEMD160Init]
::ripemd::1
% ripemd::RIPEMD160Update $tok "Tcl "
% ripemd::RIPEMD160Update $tok "does "
% ripemd::RIPEMD160Update $tok "RIPEMD-160"
% ripemd::Hex [ripemd::RIPEMD160Final $tok]
0829dea75a1a7074c702896723fe37763481a0a7
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>H. Dobbertin, A. Bosselaers, B. Preneel,
"RIPEMD-160, a strengthened version of RIPEMD"
<a href="http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf">http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf</a></p></li>
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes
and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90
Proceedings, pages 303-311, Springer-Verlag, 1991.</p></li>
<li><p>Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology
vol 11 (4), pp. 253-271 (1998)</p></li>
<li><p>Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
Message Authentication", RFC 2104, February 1997.
(<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">http://www.rfc-editor.org/rfc/rfc2104.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>ripemd</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md4/md4.html">md4</a>, <a href="../md5/md5.html">md5</a>, <a href="ripemd128.html">ripemd128</a>, <a href="../sha1/sha1.html">sha1</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ripemd">RIPEMD</a>, <a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#md4">md4</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#rfc_1320">rfc 1320</a>, <a href="../../../../index.html#rfc_1321">rfc 1321</a>, <a href="../../../../index.html#rfc_2104">rfc 2104</a>, <a href="../../../../index.html#security">security</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/sasl/gtoken.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<div class='fossil-doc' data-title='SASL::XGoogleToken - Simple Authentication and Security Layer (SASL)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">SASL::XGoogleToken(n) 1.0.1 tcllib "Simple Authentication and Security Layer (SASL)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>SASL::XGoogleToken - Implementation of SASL NTLM mechanism for Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">SASL::XGoogleToken <span class="opt">?1.0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the XGoogleToken authentication mechanism for
the Simple Authentication and Security Layer (SASL).</p>
<p>Please read the documentation for package <b class="package">sasl</b>
for details.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>sasl</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#sasl">SASL</a>, <a href="../../../../index.html#xgoogletoken">XGoogleToken</a>, <a href="../../../../index.html#authentication">authentication</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/sasl/ntlm.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
<div class='fossil-doc' data-title='SASL::NTLM - Simple Authentication and Security Layer (SASL)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">SASL::NTLM(n) 1.1.2 tcllib "Simple Authentication and Security Layer (SASL)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>SASL::NTLM - Implementation of SASL NTLM mechanism for Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">REFERENCES</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">SASL::NTLM <span class="opt">?1.1.2?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the NTLM authentication mechanism for
the Simple Authentication and Security Layer (SASL).</p>
<p>Please read the documentation for package <b class="package">sasl</b>
for details.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>No official specification is available. However,
<a href="http://davenport.sourceforge.net/ntlm.html">http://davenport.sourceforge.net/ntlm.html</a> provides a good
description.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>sasl</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ntlm">NTLM</a>, <a href="../../../../index.html#sasl">SASL</a>, <a href="../../../../index.html#authentication">authentication</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005-2006, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/sasl/sasl.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
|
<div class='fossil-doc' data-title='SASL - Simple Authentication and Security Layer (SASL)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">SASL(n) 1.3.3 tcllib "Simple Authentication and Security Layer (SASL)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>SASL - Implementation of SASL mechanisms for Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">OPTIONS</a></li>
<li class="doctools_section"><a href="#section4">CALLBACK PROCEDURE</a></li>
<li class="doctools_section"><a href="#section5">MECHANISMS</a></li>
<li class="doctools_section"><a href="#section6">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section7">REFERENCES</a></li>
<li class="doctools_section"><a href="#section8">AUTHORS</a></li>
<li class="doctools_section"><a href="#section9">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">SASL <span class="opt">?1.3.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::SASL::new</b> <i class="arg">option value <span class="opt">?...?</span></i></a></li>
<li><a href="#2"><b class="cmd">::SASL::configure</b> <i class="arg">option value</i> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::SASL::step</b> <i class="arg">context</i> <i class="arg">challenge</i> <span class="opt">?<i class="arg">...</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::SASL::response</b> <i class="arg">context</i></a></li>
<li><a href="#5"><b class="cmd">::SASL::reset</b> <i class="arg">context</i></a></li>
<li><a href="#6"><b class="cmd">::SASL::cleanup</b> <i class="arg">context</i></a></li>
<li><a href="#7"><b class="cmd">::SASL::mechanisms</b> <span class="opt">?<i class="arg">type</i>?</span> <span class="opt">?<i class="arg">minimum</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::SASL::register</b> <i class="arg">mechanism</i> <i class="arg">preference</i> <i class="arg">clientproc</i> <span class="opt">?<i class="arg">serverproc</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The Simple Authentication and Security Layer (SASL) is a framework
for providing authentication and authorization to comunications
protocols. The SASL framework is structured to permit negotiation
among a number of authentication mechanisms. SASL may be used in
SMTP, IMAP and HTTP authentication. It is also in use in XMPP, LDAP
and BEEP. See <span class="sectref"><a href="#section5">MECHANISMS</a></span> for the set of available SASL
mechanisms provided with tcllib.</p>
<p>The SASL framework operates using a simple multi-step challenge
response mechanism. All the mechanisms work the same way although the
number of steps may vary. In this implementation a callback procedure
must be provided from which the SASL framework will obtain users
details. See <span class="sectref"><a href="#section4">CALLBACK PROCEDURE</a></span> for details of this
procedure.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::SASL::new</b> <i class="arg">option value <span class="opt">?...?</span></i></a></dt>
<dd><p>Contruct a new SASL context. See <span class="sectref"><a href="#section3">OPTIONS</a></span> for details of the
possible options to this command. A context token is required for most
of the SASL procedures.</p></dd>
<dt><a name="2"><b class="cmd">::SASL::configure</b> <i class="arg">option value</i> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>Modify and inspect the SASL context option. See <span class="sectref"><a href="#section3">OPTIONS</a></span> for
further details.</p></dd>
<dt><a name="3"><b class="cmd">::SASL::step</b> <i class="arg">context</i> <i class="arg">challenge</i> <span class="opt">?<i class="arg">...</i>?</span></a></dt>
<dd><p>This is the core procedure for using the SASL framework. The
<b class="cmd">step</b> procedure should be called until it returns 0. Each step takes a
server challenge string and the response is calculated and stored in
the context. Each mechanism may require one or more steps. For some
steps there may be no server challenge required in which case an empty
string should be provided for this parameter. All mechanisms should accept
an initial empty challenge.</p></dd>
<dt><a name="4"><b class="cmd">::SASL::response</b> <i class="arg">context</i></a></dt>
<dd><p>Returns the next response string that should be sent to the server.</p></dd>
<dt><a name="5"><b class="cmd">::SASL::reset</b> <i class="arg">context</i></a></dt>
<dd><p>Re-initialize the SASL context. Discards any internal state and
permits the token to be reused.</p></dd>
<dt><a name="6"><b class="cmd">::SASL::cleanup</b> <i class="arg">context</i></a></dt>
<dd><p>Release all resources associated with the SASL context. The context
token may not be used again after this procedure has been called.</p></dd>
<dt><a name="7"><b class="cmd">::SASL::mechanisms</b> <span class="opt">?<i class="arg">type</i>?</span> <span class="opt">?<i class="arg">minimum</i>?</span></a></dt>
<dd><p>Returns a list of all the available SASL mechanisms. The list is
sorted by the mechanism preference value (see <b class="cmd">register</b>) with the
preferred mechanisms and the head of the list. Any mechanism with a
preference value less than the<i class="arg">minimum</i> (which defaults to 0) is removed
from the returned list. This permits a security threshold to be set. Mechanisms
with a preference less that 25 transmit authentication are particularly
susceptible to eavesdropping and should not be provided unless a secure
channel is in use (eg: tls).</p>
<p>The <i class="arg">type</i> parameter
may be one of <i class="arg">client</i> or <i class="arg">server</i> and defaults to <i class="arg">client</i>.
Only mechanisms that have an implementation matching the <i class="arg">type</i> are
returned (this permits servers to correctly declare support only for
mechanisms that actually provide a server implementation).</p></dd>
<dt><a name="8"><b class="cmd">::SASL::register</b> <i class="arg">mechanism</i> <i class="arg">preference</i> <i class="arg">clientproc</i> <span class="opt">?<i class="arg">serverproc</i>?</span></a></dt>
<dd><p>New mechanisms can be added to the package by registering the
mechanism name and the implementing procedures. The server procedure
is optional. The preference value is an integer that is used to order
the list returned by the <b class="cmd">mechanisms</b> command. Higher values
indicate a preferred mechanism. If the mechanism is already registered
then the recorded values are updated.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">OPTIONS</a></h2>
<dl class="doctools_definitions">
<dt><b class="option">-callback</b></dt>
<dd><p>Specify a command to be evaluated when the SASL mechanism requires
information about the user. The command is called with the current
SASL context and a name specifying the information desired. See
<span class="sectref"><a href="#section6">EXAMPLES</a></span>.</p></dd>
<dt><b class="option">-mechanism</b></dt>
<dd><p>Set the SASL mechanism to be used. See <b class="cmd">mechanisms</b> for a list of
supported authentication mechanisms.</p></dd>
<dt><b class="option">-service</b></dt>
<dd><p>Set the service type for this context. Some mechanisms may make use of
this parameter (eg DIGEST-MD5, GSSAPI and Kerberos). If not set it
defaults to an empty string. If the <b class="option">-type</b> is set to 'server'
then this option should be set to a valid service identity. Some
examples of valid service names are smtp, ldap, beep and xmpp.</p></dd>
<dt><b class="option">-server</b></dt>
<dd><p>This option is used to set the server name used in SASL challenges
when operating as a SASL server.</p></dd>
<dt><b class="option">-type</b></dt>
<dd><p>The context type may be one of 'client' or 'server'. The default is to
operate as a client application and respond to server
challenges. Mechanisms may be written to support server-side SASL and
setting this option will cause each <b class="cmd">step</b> to issue the next
challenge. A new context must be created for each incoming client
connection when in server mode.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">CALLBACK PROCEDURE</a></h2>
<p>When the SASL framework requires any user details it will call the
procedure provided when the context was created with an argument that
specfies the item of information required.</p>
<p>In all cases a single response string should be returned.</p>
<dl class="doctools_definitions">
<dt>login</dt>
<dd><p>The callback procedure should return the users authorization identity.
Return an empty string unless this is to be different to the authentication
identity. Read [1] for a discussion about the specific meaning of
authorization and authentication identities within SASL.</p></dd>
<dt>username</dt>
<dd><p>The callback procedure should return the users authentication identity.
Read [1] for a discussion about the specific meaning of
authorization and authentication identities within SASL.</p></dd>
<dt>password</dt>
<dd><p>The callback procedure should return the password that matches the
authentication identity as used within the current realm.</p>
<p>For server mechanisms the password callback should always be called with
the authentication identity and the realm as the first two parameters.</p></dd>
<dt>realm</dt>
<dd><p>Some SASL mechanisms use realms to partition authentication identities.
The realm string is protocol dependent and is often the current DNS
domain or in the case of the NTLM mechanism it is the Windows NT domain name.</p></dd>
<dt>hostname</dt>
<dd><p>Returns the client host name - typically [info host].</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">MECHANISMS</a></h2>
<dl class="doctools_definitions">
<dt>ANONYMOUS</dt>
<dd><p>As used in FTP this mechanism only passes an email address for
authentication. The ANONYMOUS mechanism is specified in [2].</p></dd>
<dt>PLAIN</dt>
<dd><p>This is the simplest mechanism. The users authentication details are
transmitted in plain text. This mechanism should not be provided
unless an encrypted link is in use - typically after SSL or TLS has
been negotiated.</p></dd>
<dt>LOGIN</dt>
<dd><p>The LOGIN [1] mechanism transmits the users details with base64
encoding. This is no more secure than PLAIN and likewise should not be
used without a secure link.</p></dd>
<dt>CRAM-MD5</dt>
<dd><p>This mechanism avoids sending the users password over the network in
plain text by hashing the password with a server provided random value
(known as a nonce). A disadvantage of this mechanism is that the
server must maintain a database of plaintext passwords for
comparison. CRAM-MD5 was defined in [4].</p></dd>
<dt>DIGEST-MD5</dt>
<dd><p>This mechanism improves upon the CRAM-MD5 mechanism by avoiding the
need for the server to store plaintext passwords. With digest
authentication the server needs to store the MD5 digest of the users
password which helps to make the system more secure. As in CRAM-MD5
the password is hashed with a server nonce and other data before being
transmitted across the network. Specified in [3].</p></dd>
<dt>OTP</dt>
<dd><p>OTP is the One-Time Password system described in RFC 2289 [6].
This mechanism is secure against replay attacks and also avoids storing
password or password equivalents on the server. Only a digest of a seed
and a passphrase is ever transmitted across the network. Requires the
<b class="package"><a href="../otp/otp.html">otp</a></b> package from tcllib and one or more of the cryptographic
digest packages (md5 or sha-1 are the most commonly used).</p></dd>
<dt>NTLM</dt>
<dd><p>This is a proprietary protocol developed by Microsoft [5] and is
in common use for authenticating users in a Windows network
environment. NTLM uses DES encryption and MD4 digests of the users
password to authenticate a connection. Certain weaknesses have been
found in NTLM and thus there are a number of versions of the protocol.
As this mechanism has additional dependencies it is made available as
a separate sub-package. To enable this mechanism your application must
load the <b class="package"><a href="ntlm.html">SASL::NTLM</a></b> package.</p></dd>
<dt>X-GOOGLE-TOKEN</dt>
<dd><p>This is a proprietary protocol developed by Google and used for
authenticating users for the Google Talk service. This mechanism makes
a pair of HTTP requests over an SSL channel and so this mechanism
depends upon the availability of the tls and http packages. To enable
this mechanism your application must load the <b class="package"><a href="gtoken.html">SASL::XGoogleToken</a></b> package.
In addition you are recommended to make use of the autoproxy package to
handle HTTP proxies reasonably transparently.</p></dd>
<dt>SCRAM</dt>
<dd><p>This is a protocol specified in RFC 5802 [7]. To enable this mechanism
your application must load the <b class="package"><a href="scram.html">SASL::SCRAM</a></b> package.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">EXAMPLES</a></h2>
<p>See the examples subdirectory for more complete samples using SASL
with network protocols. The following should give an idea how the SASL
commands are to be used. In reality this should be event
driven. Each time the <b class="cmd">step</b> command is called, the last server
response should be provided as the command argument so that the SASL
mechanism can take appropriate action.</p>
<pre class="doctools_example">
proc ClientCallback {context command args} {
switch -exact -- $command {
login { return "" }
username { return $::tcl_platform(user) }
password { return "SecRet" }
realm { return "" }
hostname { return [info host] }
default { return -code error unxpected }
}
}
proc Demo {{mech PLAIN}} {
set ctx [SASL::new -mechanism $mech -callback ClientCallback]
set challenge ""
while {1} {
set more_steps [SASL::step $ctx challenge]
puts "Send '[SASL::response $ctx]'"
puts "Read server response into challenge var"
if {!$more_steps} {break}
}
SASL::cleanup $ctx
}
</pre>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Myers, J. "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997.
(<a href="http://www.ietf.org/rfc/rfc2222.txt">http://www.ietf.org/rfc/rfc2222.txt</a>)</p></li>
<li><p>Newman, C. "Anonymous SASL Mechanism",
RFC 2245, November 1997.
(<a href="http://www.ietf.org/rfc/rfc2245.txt">http://www.ietf.org/rfc/rfc2245.txt</a>)</p></li>
<li><p>Leach, P., Newman, C. "Using Digest Authentication as a SASL
Mechanism", RFC 2831, May 2000,
(<a href="http://www.ietf.org/rfc/rfc2831.txt">http://www.ietf.org/rfc/rfc2831.txt</a>)</p></li>
<li><p>Klensin, J., Catoe, R. and Krumviede, P.,
"IMAP/POP AUTHorize Extension for Simple Challenge/Response"
RFC 2195, September 1997.
(<a href="http://www.ietf.org/rfc/rfc2195.txt">http://www.ietf.org/rfc/rfc2195.txt</a>)</p></li>
<li><p>No official specification is available. However,
<a href="http://davenport.sourceforge.net/ntlm.html">http://davenport.sourceforge.net/ntlm.html</a> provides a good
description.</p></li>
<li><p>Haller, N. et al., "A One-Time Password System",
RFC 2289, February 1998,
(<a href="http://www.ieft.org/rfc/rfc2289.txt">http://www.ieft.org/rfc/rfc2289.txt</a>)</p></li>
<li><p>Newman, C. et al., "Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms",
RFC 5802, July 2010,
(<a href="http://www.ieft.org/rfc/rfc5802.txt">http://www.ieft.org/rfc/rfc5802.txt</a>)</p></li>
</ol>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">AUTHORS</a></h2>
<p>Pat Thoyts</p>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>sasl</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#sasl">SASL</a>, <a href="../../../../index.html#authentication">authentication</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005-2006, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/sasl/scram.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
<div class='fossil-doc' data-title='SASL::SCRAM - Simple Authentication and Security Layer (SASL)'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">SASL::SCRAM(n) 0.1 tcllib "Simple Authentication and Security Layer (SASL)"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>SASL::SCRAM - Implementation of SASL SCRAM mechanism for Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">REFERENCES</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">SASL::SCRAM <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the SCRAM authentication mechanism for
the Simple Authentication and Security Layer (SASL).</p>
<p>Please read the documentation for package <b class="package">sasl</b>
for details.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Newman, C. et al., "Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms",
RFC 5802, July 2010,
(<a href="http://www.ieft.org/rfc/rfc5802.txt">http://www.ieft.org/rfc/rfc5802.txt</a>)</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Sergei Golovan</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>sasl</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#sasl">SASL</a>, <a href="../../../../index.html#scram">SCRAM</a>, <a href="../../../../index.html#authentication">authentication</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2013 Sergei Golovan <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/sha1/sha1.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
|
<div class='fossil-doc' data-title='sha1 - SHA-x Message-Digest Algorithm'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">sha1(n) 2.0.3 tcllib "SHA-x Message-Digest Algorithm"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>sha1 - SHA1 Message-Digest Algorithm</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">sha1 <span class="opt">?2.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::sha1::sha1</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::sha1::hmac</b> <i class="arg">key</i> <i class="arg">string</i></a></li>
<li><a href="#3"><b class="cmd">::sha1::hmac</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> <b class="option">-key key</b> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></li>
<li><a href="#4"><b class="cmd">::sha1::SHA1Init</b></a></li>
<li><a href="#5"><b class="cmd">::sha1::SHA1Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#6"><b class="cmd">::sha1::SHA1Final</b> <i class="arg">token</i></a></li>
<li><a href="#7"><b class="cmd">::sha1::HMACInit</b> <i class="arg">key</i></a></li>
<li><a href="#8"><b class="cmd">::sha1::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#9"><b class="cmd">::sha1::HMACFinal</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an implementation in Tcl of the SHA1
message-digest algorithm as specified by FIPS PUB 180-1 (1). This
algorithm takes a message and generates a 160-bit digest from the
input. The SHA1 algorithm is related to the MD4 algorithm (2) but has
been strengthend against certain types of cryptographic attack. SHA1
should be used in preference to MD4 or MD5 in new applications.</p>
<p>This package also includes support for creating keyed message-digests
using the HMAC algorithm from RFC 2104 (3) with SHA1 as the
message-digest.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::sha1::sha1</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></dt>
<dd><p>The command takes a message and returns the SHA1 digest of this message
as a hexadecimal string. You may request the result as binary data by
giving <i class="arg">-bin</i>.</p>
<p>The data to be hashed can be specified either as a string argument to
the <b class="cmd">sha1</b> command, or as a filename or a pre-opened channel. If the
<i class="arg">-filename</i> argument is given then the file is opened, the data read
and hashed and the file is closed. If the <i class="arg">-channel</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed. <em>NOTE</em> use of the channel or filename
options results in the internal use of <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>. To avoid nested
event loops in Tk or tclhttpd applications you should use the
incremental programming API (see below).</p>
<p>Only one of <i class="arg">-file</i>, <i class="arg">-channel</i> or <i class="arg">string</i> should be given.</p>
<p>If the <i class="arg">string</i> to hash can be mistaken for an option
(leading dash "-"), use the option <b class="option">--</b> before it to terminate
option processing and force interpretation as a string.</p></dd>
<dt><a name="2"><b class="cmd">::sha1::hmac</b> <i class="arg">key</i> <i class="arg">string</i></a></dt>
<dd></dd>
<dt><a name="3"><b class="cmd">::sha1::hmac</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> <b class="option">-key key</b> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate an Hashed Message Authentication digest (HMAC) using the SHA1
digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA1
digest that includes a key. All options other than <i class="arg">-key</i> are as
for the <b class="cmd">::sha1::sha1</b> command.</p>
<p>If the <i class="arg">string</i> to hash can be mistaken for an option
(leading dash "-"), use the option <b class="option">--</b> before it to terminate
option processing and force interpretation as a string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>For the programmer, the SHA1 hash can be viewed as a bucket into which
one pours data. When you have finished, you extract a value that is
derived from the data that was poured into the bucket. The programming
interface to the SHA1 hash operates on a token (equivalent to the
bucket). You call <b class="cmd">SHA1Init</b> to obtain a token and then call
<b class="cmd">SHA1Update</b> as many times as required to add data to the hash. To
release any resources and obtain the hash value, you then call
<b class="cmd">SHA1Final</b>. An equivalent set of functions gives you a keyed digest
(HMAC).</p>
<p>If you have <b class="package">critcl</b> and have built the <b class="package">tcllibc</b> package
then the implementation of the hashing function will be performed by compiled
code. Failing that if you have the <b class="package">Trf</b> package then this can
be used otherwise there is a pure-tcl equivalent. The programming
interface remains the same in all cases.</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">::sha1::SHA1Init</b></a></dt>
<dd><p>Begins a new SHA1 hash. Returns a token ID that must be used for the
remaining functions.</p></dd>
<dt><a name="5"><b class="cmd">::sha1::SHA1Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the hash identified by token. Calling
<em>SHA1Update $token "abcd"</em> is equivalent to calling
<em>SHA1Update $token "ab"</em> followed by
<em>SHA1Update $token "cb"</em>. See <span class="sectref"><a href="#section4">EXAMPLES</a></span>.</p></dd>
<dt><a name="6"><b class="cmd">::sha1::SHA1Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the hash value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a binary string of 20 bytes representing the 160 bit SHA1
digest value.</p></dd>
<dt><a name="7"><b class="cmd">::sha1::HMACInit</b> <i class="arg">key</i></a></dt>
<dd><p>This is equivalent to the <b class="cmd">::sha1::SHA1Init</b> command except that
it requires the key that will be included in the HMAC.</p></dd>
<dt><a name="8"><b class="cmd">::sha1::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="9"><b class="cmd">::sha1::HMACFinal</b> <i class="arg">token</i></a></dt>
<dd><p>These commands are identical to the SHA1 equivalent commands.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% sha1::sha1 "Tcl does SHA1"
285a6a91c45a9066bf39fcf24425796ef0b2a8bf
</pre>
<pre class="doctools_example">
% sha1::hmac Sekret "Tcl does SHA1"
ae6251fa51b95b18cba2be95eb031d07475ff03c
</pre>
<pre class="doctools_example">
% set tok [sha1::SHA1Init]
::sha1::1
% sha1::SHA1Update $tok "Tcl "
% sha1::SHA1Update $tok "does "
% sha1::SHA1Update $tok "SHA1"
% sha1::Hex [sha1::SHA1Final $tok]
285a6a91c45a9066bf39fcf24425796ef0b2a8bf
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>"Secure Hash Standard", National Institute of Standards
and Technology, U.S. Department Of Commerce, April 1995.
(<a href="http://www.itl.nist.gov/fipspubs/fip180-1.htm">http://www.itl.nist.gov/fipspubs/fip180-1.htm</a>)</p></li>
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
Message Authentication", RFC 2104, February 1997.
(<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">http://www.rfc-editor.org/rfc/rfc2104.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>sha1</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md4/md4.html">md4</a>, <a href="../md5/md5.html">md5</a>, <a href="../ripemd/ripemd128.html">ripemd128</a>, <a href="../ripemd/ripemd160.html">ripemd160</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fips_180_1">FIPS 180-1</a>, <a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#rfc_2104">rfc 2104</a>, <a href="../../../../index.html#security">security</a>, <a href="../../../../index.html#sha1">sha1</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/sha1/sha256.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
<div class='fossil-doc' data-title='sha256 - SHA-x Message-Digest Algorithm'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">sha256(n) 1.0.3 tcllib "SHA-x Message-Digest Algorithm"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>sha256 - SHA256 Message-Digest Algorithm</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">PROGRAMMING INTERFACE</a></li>
<li class="doctools_section"><a href="#section4">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">sha256 <span class="opt">?1.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::sha2::sha256</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></li>
<li><a href="#2"><b class="cmd">::sha2::sha224</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></li>
<li><a href="#3"><b class="cmd">::sha2::hmac</b> <i class="arg">key</i> <i class="arg">string</i></a></li>
<li><a href="#4"><b class="cmd">::sha2::hmac</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> <b class="option">-key key</b> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></li>
<li><a href="#5"><b class="cmd">::sha2::SHA256Init</b></a></li>
<li><a href="#6"><b class="cmd">::sha2::SHA224Init</b></a></li>
<li><a href="#7"><b class="cmd">::sha2::SHA256Update</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#8"><b class="cmd">::sha2::SHA256Final</b> <i class="arg">token</i></a></li>
<li><a href="#9"><b class="cmd">::sha2::SHA224Final</b> <i class="arg">token</i></a></li>
<li><a href="#10"><b class="cmd">::sha2::HMACInit</b> <i class="arg">key</i></a></li>
<li><a href="#11"><b class="cmd">::sha2::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></li>
<li><a href="#12"><b class="cmd">::sha2::HMACFinal</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an implementation in Tcl of the SHA256 and
SHA224 message-digest algorithms as specified by FIPS PUB 180-1
(1). These algorithms take a message and generates a 256-bit (224-bit)
digest from the input. The SHA2 algorithms are related to the SHA1
algorithm.</p>
<p>This package also includes support for creating keyed message-digests
using the HMAC algorithm from RFC 2104 (3) with SHA256 as the
message-digest.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::sha2::sha256</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></dt>
<dd><p>The command takes a message and returns the SHA256 digest of this
message as a hexadecimal string. You may request the result as binary
data by giving <i class="arg">-bin</i>.</p>
<p>The data to be hashed can be specified either as a string argument to
the <b class="cmd">sha256</b> command, or as a filename or a pre-opened channel. If the
<i class="arg">-filename</i> argument is given then the file is opened, the data read
and hashed and the file is closed. If the <i class="arg">-channel</i> argument is
given then data is read from the channel until the end of file. The
channel is not closed. <em>NOTE</em> use of the channel or filename
options results in the internal use of <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>. To avoid nested
event loops in Tk or tclhttpd applications you should use the
incremental programming API (see below).</p>
<p>Only one of <i class="arg">-file</i>, <i class="arg">-channel</i> or <i class="arg">string</i> should be given.</p>
<p>If the <i class="arg">string</i> to hash can be mistaken for an option
(leading dash "-"), use the option <b class="option">--</b> before it to terminate
option processing and force interpretation as a string.</p></dd>
<dt><a name="2"><b class="cmd">::sha2::sha224</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></dt>
<dd><p>Like <b class="cmd">::sha2::sha256</b>, except that the SHA224 digest is returned.</p></dd>
<dt><a name="3"><b class="cmd">::sha2::hmac</b> <i class="arg">key</i> <i class="arg">string</i></a></dt>
<dd></dd>
<dt><a name="4"><b class="cmd">::sha2::hmac</b> <span class="opt">?<b class="option">-hex|-bin</b>?</span> <b class="option">-key key</b> [ <b class="option">-channel channel</b> | <b class="option">-file filename</b> | <span class="opt">?<b class="option">--</b>?</span> <i class="arg">string</i> ]</a></dt>
<dd><p>Calculate an Hashed Message Authentication digest (HMAC) using the
SHA256 digest algorithm. HMACs are described in RFC 2104 (3) and
provide an SHA256 digest that includes a key. All options other than
<i class="arg">-key</i> are as for the <b class="cmd">::sha2::sha256</b> command.</p>
<p>If the <i class="arg">string</i> to hash can be mistaken for an option
(leading dash "-"), use the option <b class="option">--</b> before it to terminate
option processing and force interpretation as a string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROGRAMMING INTERFACE</a></h2>
<p>For the programmer, the SHA256 hash can be viewed as a bucket into
which one pours data. When you have finished, you extract a value that
is derived from the data that was poured into the bucket. The
programming interface to the SHA256 hash operates on a token
(equivalent to the bucket). You call <b class="cmd">SHA256Init</b> to obtain a
token and then call <b class="cmd">SHA256Update</b> as many times as required to
add data to the hash. To release any resources and obtain the hash
value, you then call <b class="cmd">SHA256Final</b>. An equivalent set of
functions gives you a keyed digest (HMAC).</p>
<p>If you have <b class="package">critcl</b> and have built the <b class="package">tcllibc</b>
package then the implementation of the hashing function will be
performed by compiled code. Failing that there is a pure-tcl
equivalent. The programming interface remains the same in all cases.</p>
<dl class="doctools_definitions">
<dt><a name="5"><b class="cmd">::sha2::SHA256Init</b></a></dt>
<dd></dd>
<dt><a name="6"><b class="cmd">::sha2::SHA224Init</b></a></dt>
<dd><p>Begins a new SHA256/SHA224 hash. Returns a token ID that must be used
for the remaining functions.</p></dd>
<dt><a name="7"><b class="cmd">::sha2::SHA256Update</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd><p>Add data to the hash identified by token. Calling
<em>SHA256Update $token "abcd"</em> is equivalent to calling
<em>SHA256Update $token "ab"</em> followed by
<em>SHA256Update $token "cb"</em>. See <span class="sectref"><a href="#section4">EXAMPLES</a></span>.
Note that this command is used for both SHA256 and SHA224. Only the
initialization and finalization commands of both hashes differ.</p></dd>
<dt><a name="8"><b class="cmd">::sha2::SHA256Final</b> <i class="arg">token</i></a></dt>
<dd></dd>
<dt><a name="9"><b class="cmd">::sha2::SHA224Final</b> <i class="arg">token</i></a></dt>
<dd><p>Returns the hash value and releases any resources held by this
token. Once this command completes the token will be invalid. The
result is a binary string of 32/28 bytes representing the 256/224 bit
SHA256 / SHA224 digest value.</p></dd>
<dt><a name="10"><b class="cmd">::sha2::HMACInit</b> <i class="arg">key</i></a></dt>
<dd><p>This is equivalent to the <b class="cmd">::sha2::SHA256Init</b> command except
that it requires the key that will be included in the HMAC.</p></dd>
<dt><a name="11"><b class="cmd">::sha2::HMACUpdate</b> <i class="arg">token</i> <i class="arg">data</i></a></dt>
<dd></dd>
<dt><a name="12"><b class="cmd">::sha2::HMACFinal</b> <i class="arg">token</i></a></dt>
<dd><p>These commands are identical to the SHA256 equivalent commands.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXAMPLES</a></h2>
<pre class="doctools_example">
% sha2::sha256 "Tcl does SHA256"
0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
</pre>
<pre class="doctools_example">
% sha2::hmac Sekret "Tcl does SHA256"
4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0
</pre>
<pre class="doctools_example">
% set tok [sha2::SHA256Init]
::sha2::1
% sha2::SHA256Update $tok "Tcl "
% sha2::SHA256Update $tok "does "
% sha2::SHA256Update $tok "SHA256"
% sha2::Hex [sha2::SHA256Final $tok]
0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>"Secure Hash Standard", National Institute of Standards
and Technology, U.S. Department Of Commerce, April 1995.
(<a href="http://www.itl.nist.gov/fipspubs/fip180-1.htm">http://www.itl.nist.gov/fipspubs/fip180-1.htm</a>)</p></li>
<li><p>Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT,
April 1992. (<a href="http://www.rfc-editor.org/rfc/rfc1320.txt">http://www.rfc-editor.org/rfc/rfc1320.txt</a>)</p></li>
<li><p>Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
Message Authentication", RFC 2104, February 1997.
(<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">http://www.rfc-editor.org/rfc/rfc2104.txt</a>)</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>sha1</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../md4/md4.html">md4</a>, <a href="../md5/md5.html">md5</a>, <a href="../ripemd/ripemd128.html">ripemd128</a>, <a href="../ripemd/ripemd160.html">ripemd160</a>, <a href="sha1.html">sha1</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fips_180_1">FIPS 180-1</a>, <a href="../../../../index.html#hashing">hashing</a>, <a href="../../../../index.html#message_digest">message-digest</a>, <a href="../../../../index.html#rfc_2104">rfc 2104</a>, <a href="../../../../index.html#security">security</a>, <a href="../../../../index.html#sha256">sha256</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008, Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/simulation/annealing.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
|
<div class='fossil-doc' data-title='simulation::annealing - Tcl Simulation Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">simulation::annealing(n) 0.2 tcllib "Tcl Simulation Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>simulation::annealing - Simulated annealing</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">TIPS</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">simulation::annealing 0.2</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::simulation::annealing::getOption</b> <i class="arg">keyword</i></a></li>
<li><a href="#2"><b class="cmd">::simulation::annealing::hasOption</b> <i class="arg">keyword</i></a></li>
<li><a href="#3"><b class="cmd">::simulation::annealing::setOption</b> <i class="arg">keyword</i> <i class="arg">value</i></a></li>
<li><a href="#4"><b class="cmd">::simulation::annealing::findMinimum</b> <i class="arg">args</i></a></li>
<li><a href="#5"><b class="cmd">::simulation::annealing::findCombinatorialMinimum</b> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The technique of <em>simulated annealing</em> provides methods to
estimate the global optimum of a function. It is described in some
detail on the Wiki <a href="http://wiki.tcl.tk/...">http://wiki.tcl.tk/...</a>. The idea is simple:</p>
<ul class="doctools_itemized">
<li><p>randomly select points within a given search space</p></li>
<li><p>evaluate the function to be optimised for each of these
points and select the point that has the lowest (or highest)
function value or - sometimes - accept a point that has a less optimal
value. The chance by which such a non-optimal point is accepted diminishes over
time.</p></li>
<li><p>Accepting less optimal points means the method does not necessarily get
stuck in a local optimum and theoretically it is capable of finding the
global optimum within the search space.</p></li>
</ul>
<p>The method resembles the cooling of material, hence the name.</p>
<p>The package <i class="term">simulation::annealing</i> offers the command <i class="term">findMinimum</i>:</p>
<pre class="doctools_example">
puts [::simulation::annealing::findMinimum -trials 300 -parameters {x -5.0 5.0 y -5.0 5.0} -function {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
</pre>
<p>prints the estimated minimum value of the function f(x,y) =
<em>x**2+y**2+sin(10*x)+4*cos(20*y)</em> and the values of x and y where
the minimum was attained:</p>
<pre class="doctools_example">
result -4.9112922923 x -0.181647676593 y 0.155743646974
</pre>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following auxiliary procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::simulation::annealing::getOption</b> <i class="arg">keyword</i></a></dt>
<dd><p>Get the value of an option given as part of the <i class="term">findMinimum</i>
command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">keyword</i></dt>
<dd><p>Given keyword (without leading minus)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::simulation::annealing::hasOption</b> <i class="arg">keyword</i></a></dt>
<dd><p>Returns 1 if the option is available, 0 if not.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">keyword</i></dt>
<dd><p>Given keyword (without leading minus)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::simulation::annealing::setOption</b> <i class="arg">keyword</i> <i class="arg">value</i></a></dt>
<dd><p>Set the value of the given option.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">keyword</i></dt>
<dd><p>Given keyword (without leading minus)</p></dd>
<dt>string <i class="arg">value</i></dt>
<dd><p>(New) value for the option</p></dd>
</dl></dd>
</dl>
<p>The main procedures are <i class="term">findMinimum</i> and <i class="term">findCombinatorialMinimum</i>:</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">::simulation::annealing::findMinimum</b> <i class="arg">args</i></a></dt>
<dd><p>Find the minimum of a function using simulated annealing. The function
and the method's parameters is given via a list of
keyword-value pairs.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>List of keyword-value pairs, all of which are available
during the execution via the <i class="term">getOption</i> command.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::simulation::annealing::findCombinatorialMinimum</b> <i class="arg">args</i></a></dt>
<dd><p>Find the minimum of a function of discrete variables using simulated
annealing. The function and the method's parameters is given via a list of
keyword-value pairs.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>List of keyword-value pairs, all of which are available
during the execution via the <i class="term">getOption</i> command.</p></dd>
</dl></dd>
</dl>
<p>The <i class="term">findMinimum</i> command predefines the following options:</p>
<ul class="doctools_itemized">
<li><p><i class="term">-parameters list</i>: triples defining parameters and ranges</p></li>
<li><p><i class="term">-function expr</i>: expression defining the function</p></li>
<li><p><i class="term">-code body</i>: body of code to define the function (takes
precedence over <i class="term">-function</i>). The code should set the variable
"result"</p></li>
<li><p><i class="term">-init code</i>: code to be run at start up
<i class="term">-final code</i>: code to be run at the end
<i class="term">-trials n</i>: number of trials before reducing the temperature
<i class="term">-reduce factor</i>: reduce the temperature by this factor (between 0 and 1)
<i class="term">-initial-temp t</i>: initial temperature
<i class="term">-scale s</i>: scale of the function (order of magnitude of the values)
<i class="term">-estimate-scale y/n</i>: estimate the scale (only if <i class="term">-scale</i>
is not present)
<i class="term">-verbose y/n</i>: print detailed information on progress to the
report file (1) or not (0)
<i class="term">-reportfile file</i>: opened file to print to (defaults to stdout)</p></li>
</ul>
<p>Any other options can be used via the getOption procedure
in the body.
The <i class="term">findCombinatorialMinimum</i> command predefines the following
options:</p>
<ul class="doctools_itemized">
<li><p><i class="term">-number-params n</i>: number of binary parameters (the solution
space consists of lists of 1s and 0s). This is a required option.</p></li>
<li><p><i class="term">-initial-values</i>: list of 1s and 0s constituting the start of
the search.</p></li>
</ul>
<p>The other predefined options are identical to those of <i class="term">findMinimum</i>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TIPS</a></h2>
<p>The procedure <i class="term">findMinimum</i> works by constructing a temporary
procedure that does the actual work. It loops until the point
representing the estimated optimum does not change anymore within the
given number of trials. As the temperature gets lower and lower the
chance of accepting a point with a higher value becomes lower too, so
the procedure will in practice terminate.</p>
<p>It is possible to optimise over a non-rectangular region, but some care
must be taken:</p>
<ul class="doctools_itemized">
<li><p>If the point is outside the region of interest, you can specify a very
high value.</p></li>
<li><p>This does mean that the automatic determination of a scale factor is
out of the question - the high function values that force the point
inside the region would distort the estimation.</p></li>
</ul>
<p>Here is an example of finding an optimum inside a circle:</p>
<pre class="doctools_example">
puts [::simulation::annealing::findMinimum -trials 3000 -reduce 0.98 -parameters {x -5.0 5.0 y -5.0 5.0} -code {
if { hypot($x-5.0,$y-5.0) < 4.0 } {
set result [expr {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
} else {
set result 1.0e100
}
}]
</pre>
<p>The method is theoretically capable of determining the global optimum,
but often you need to use a large number of trials and a slow reduction
of temperature to get reliable and repeatable estimates.</p>
<p>You can use the <i class="term">-final</i> option to use a deterministic optimization
method, once you are sure you are near the required optimum.</p>
<p>The <i class="term">findCombinatorialMinimum</i> procedure is suited for situations
where the parameters have the values 0 or 1 (and there can be many of
them). Here is an example:</p>
<ul class="doctools_itemized">
<li><p>We have a function that attains an absolute minimum if the first ten
numbers are 1 and the rest is 0:</p>
<pre class="doctools_example">
proc cost {params} {
set cost 0
foreach p [lrange $params 0 9] {
if { $p == 0 } {
incr cost
}
}
foreach p [lrange $params 10 end] {
if { $p == 1 } {
incr cost
}
}
return $cost
}
</pre>
</li>
<li><p>We want to find the solution that gives this minimum for various lengths
of the solution vector <i class="term">params</i>:</p>
<pre class="doctools_example">
foreach n {100 1000 10000} {
break
puts "Problem size: $n"
puts [::simulation::annealing::findCombinatorialMinimum -trials 300 -verbose 0 -number-params $n -code {set result [cost $params]}]
}
</pre>
</li>
<li><p>As the vector grows, the computation time increases, but the procedure
will stop if some kind of equilibrium is reached. To achieve a useful
solution you may want to try different values of the trials parameter
for instance. Also ensure that the function to be minimized depends on
all or most parameters - see the source code for a counter example and
run that.</p></li>
</ul>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#optimization">optimization</a>, <a href="../../../../index.html#simulated_annealing">simulated annealing</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/simulation/montecarlo.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
<div class='fossil-doc' data-title='simulation::montecarlo - Tcl Simulation Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">simulation::montecarlo(n) 0.1 tcllib "Tcl Simulation Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>simulation::montecarlo - Monte Carlo simulations</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#section3">TIPS</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">simulation::montecarlo 0.1</b></li>
<li>package require <b class="pkgname">simulation::random</b></li>
<li>package require <b class="pkgname">math::statistics</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::simulation::montecarlo::getOption</b> <i class="arg">keyword</i></a></li>
<li><a href="#2"><b class="cmd">::simulation::montecarlo::hasOption</b> <i class="arg">keyword</i></a></li>
<li><a href="#3"><b class="cmd">::simulation::montecarlo::setOption</b> <i class="arg">keyword</i> <i class="arg">value</i></a></li>
<li><a href="#4"><b class="cmd">::simulation::montecarlo::setTrialResult</b> <i class="arg">values</i></a></li>
<li><a href="#5"><b class="cmd">::simulation::montecarlo::setExpResult</b> <i class="arg">values</i></a></li>
<li><a href="#6"><b class="cmd">::simulation::montecarlo::getTrialResults</b></a></li>
<li><a href="#7"><b class="cmd">::simulation::montecarlo::getExpResult</b></a></li>
<li><a href="#8"><b class="cmd">::simulation::montecarlo::transposeData</b> <i class="arg">values</i></a></li>
<li><a href="#9"><b class="cmd">::simulation::montecarlo::integral2D</b> <i class="arg">...</i></a></li>
<li><a href="#10"><b class="cmd">::simulation::montecarlo::singleExperiment</b> <i class="arg">args</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The technique of <em>Monte Carlo simulations</em> is basically simple:</p>
<ul class="doctools_itemized">
<li><p>generate random values for one or more parameters.</p></li>
<li><p>evaluate the model of some system you are interested in and record the
interesting results for each realisation of these parameters.</p></li>
<li><p>after a suitable number of such trials, deduce an overall characteristic
of the model.</p></li>
</ul>
<p>You can think of a model of a network of computers, an ecosystem of some
kind or in fact anything that can be quantitatively described and has
some stochastic element in it.</p>
<p>The package <i class="term">simulation::montecarlo</i> offers a basic framework for
such a modelling technique:</p>
<pre class="doctools_example">
#
# MC experiments:
# Determine the mean and median of a set of points and compare them
#
::simulation::montecarlo::singleExperiment -init {
package require math::statistics
set prng [::simulation::random::prng_Normal 0.0 1.0]
} -loop {
set numbers {}
for { set i 0 } { $i < [getOption samples] } { incr i } {
lappend numbers [$prng]
}
set mean [::math::statistics::mean $numbers]
set median [::math::statistics::median $numbers] ;# ? Exists?
setTrialResult [list $mean $median]
} -final {
set result [getTrialResults]
set means {}
set medians {}
foreach r $result {
foreach {m M} $r break
lappend means $m
lappend medians $M
}
puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]"
} -trials 100 -samples 10 -verbose 1 -columns {Mean Median}
</pre>
<p>This example attemps to find out how well the median value and the mean
value of a random set of numbers correlate. Sometimes a median value is
a more robust characteristic than a mean value - especially if you have
a statistical distribution with "fat" tails.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following auxiliary procedures:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::simulation::montecarlo::getOption</b> <i class="arg">keyword</i></a></dt>
<dd><p>Get the value of an option given as part of the <i class="term">singeExperiment</i> command.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">keyword</i></dt>
<dd><p>Given keyword (without leading minus)</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::simulation::montecarlo::hasOption</b> <i class="arg">keyword</i></a></dt>
<dd><p>Returns 1 if the option is available, 0 if not.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">keyword</i></dt>
<dd><p>Given keyword (without leading minus)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::simulation::montecarlo::setOption</b> <i class="arg">keyword</i> <i class="arg">value</i></a></dt>
<dd><p>Set the value of the given option.</p>
<dl class="doctools_arguments">
<dt>string <i class="arg">keyword</i></dt>
<dd><p>Given keyword (without leading minus)</p></dd>
<dt>string <i class="arg">value</i></dt>
<dd><p>(New) value for the option</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::simulation::montecarlo::setTrialResult</b> <i class="arg">values</i></a></dt>
<dd><p>Store the results of the trial for later analysis</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">values</i></dt>
<dd><p>List of values to be stored</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::simulation::montecarlo::setExpResult</b> <i class="arg">values</i></a></dt>
<dd><p>Set the results of the entire experiment (typically used in the final
phase).</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">values</i></dt>
<dd><p>List of values to be stored</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::simulation::montecarlo::getTrialResults</b></a></dt>
<dd><p>Get the results of all individual trials for analysis (typically used in
the final phase or after completion of the command).</p></dd>
<dt><a name="7"><b class="cmd">::simulation::montecarlo::getExpResult</b></a></dt>
<dd><p>Get the results of the entire experiment (typically used in the final
phase or even after completion of the <i class="term">singleExperiment</i> command).</p></dd>
<dt><a name="8"><b class="cmd">::simulation::montecarlo::transposeData</b> <i class="arg">values</i></a></dt>
<dd><p>Interchange columns and rows of a list of lists and return the result.</p>
<dl class="doctools_arguments">
<dt>list <i class="arg">values</i></dt>
<dd><p>List of lists of values</p></dd>
</dl></dd>
</dl>
<p>There are two main procedures: <i class="term">integral2D</i> and <i class="term">singleExperiment</i>.</p>
<dl class="doctools_definitions">
<dt><a name="9"><b class="cmd">::simulation::montecarlo::integral2D</b> <i class="arg">...</i></a></dt>
<dd><p>Integrate a function over a two-dimensional region using a Monte Carlo
approach.</p>
<p>Arguments PM</p></dd>
<dt><a name="10"><b class="cmd">::simulation::montecarlo::singleExperiment</b> <i class="arg">args</i></a></dt>
<dd><p>Iterate code over a number of trials and store the results. The
iteration is gouverned by parameters given via a list of
keyword-value pairs.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>List of keyword-value pairs, all of which are available
during the execution via the <i class="term">getOption</i> command.</p></dd>
</dl></dd>
</dl>
<p>The <i class="term">singleExperiment</i> command predefines the following
options:</p>
<ul class="doctools_itemized">
<li><p><i class="term">-init code</i>: code to be run at start up</p></li>
<li><p><i class="term">-loop body</i>: body of code that defines the computation to
be run time and again. The code should use <i class="term">setTrialResult</i>
to store the results of each trial (typically a list of numbers,
but the interpretation is up to the implementation). Note: Required keyword.</p></li>
<li><p><i class="term">-final code</i>: code to be run at the end</p></li>
<li><p><i class="term">-trials n</i>: number of trials in the experiment (required)</p></li>
<li><p><i class="term">-reportfile file</i>: opened file to send the output to (default: stdout)</p></li>
<li><p><i class="term">-verbose</i>: write the intermediate results (1) or not (0) (default: 0)</p></li>
<li><p><i class="term">-analysis proc</i>: either "none" (no automatic analysis), standard
(basic statistics of the trial results and a correlation matrix) or the
name of a procedure that will take care of the analysis.</p></li>
<li><p><i class="term">-columns list</i>: list of column names, useful for verbose output
and the analysis</p></li>
</ul>
<p>Any other options can be used via the getOption procedure
in the body.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TIPS</a></h2>
<p>The procedure <i class="term">singleExperiment</i> works by constructing a
temporary procedure that does the actual work. It loops for the given
number of trials.</p>
<p>As it constructs a temporary procedure, local variables defined at the
start continue to exist in the loop.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#montecarlo_simulation">montecarlo simulation</a>, <a href="../../../../index.html#stochastic_modelling">stochastic modelling</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/simulation/simulation_random.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
<div class='fossil-doc' data-title='simulation::random - Tcl Simulation Tools'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">simulation::random(n) 0.1 tcllib "Tcl Simulation Tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>simulation::random - Pseudo-random number generators</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">PROCEDURES</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.4?</span></b></li>
<li>package require <b class="pkgname">simulation::random 0.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::simulation::random::prng_Bernoulli</b> <i class="arg">p</i></a></li>
<li><a href="#2"><b class="cmd">::simulation::random::prng_Discrete</b> <i class="arg">n</i></a></li>
<li><a href="#3"><b class="cmd">::simulation::random::prng_Poisson</b> <i class="arg">lambda</i></a></li>
<li><a href="#4"><b class="cmd">::simulation::random::prng_Uniform</b> <i class="arg">min</i> <i class="arg">max</i></a></li>
<li><a href="#5"><b class="cmd">::simulation::random::prng_Exponential</b> <i class="arg">min</i> <i class="arg">mean</i></a></li>
<li><a href="#6"><b class="cmd">::simulation::random::prng_Normal</b> <i class="arg">mean</i> <i class="arg">stdev</i></a></li>
<li><a href="#7"><b class="cmd">::simulation::random::prng_Pareto</b> <i class="arg">min</i> <i class="arg">steep</i></a></li>
<li><a href="#8"><b class="cmd">::simulation::random::prng_Gumbel</b> <i class="arg">min</i> <i class="arg">f</i></a></li>
<li><a href="#9"><b class="cmd">::simulation::random::prng_chiSquared</b> <i class="arg">df</i></a></li>
<li><a href="#10"><b class="cmd">::simulation::random::prng_Disk</b> <i class="arg">rad</i></a></li>
<li><a href="#11"><b class="cmd">::simulation::random::prng_Sphere</b> <i class="arg">rad</i></a></li>
<li><a href="#12"><b class="cmd">::simulation::random::prng_Ball</b> <i class="arg">rad</i></a></li>
<li><a href="#13"><b class="cmd">::simulation::random::prng_Rectangle</b> <i class="arg">length</i> <i class="arg">width</i></a></li>
<li><a href="#14"><b class="cmd">::simulation::random::prng_Block</b> <i class="arg">length</i> <i class="arg">width</i> <i class="arg">depth</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package consists of commands to generate pseudo-random number
generators. These new commands deliver</p>
<ul class="doctools_itemized">
<li><p>numbers that are distributed normally, uniformly, according to a
Pareto or Gumbel distribution and so on</p></li>
<li><p>coordinates of points uniformly spread inside a sphere or a rectangle</p></li>
</ul>
<p>For example:</p>
<pre class="doctools_example">
set p [::simulation::random::prng_Normal -1.0 10.0]
</pre>
<p>produces a new command (whose name is stored in the variable "p") that
generates normally distributed numbers with a mean of -1.0 and a
standard deviation of 10.0.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">PROCEDURES</a></h2>
<p>The package defines the following public procedures for <em>discrete</em>
distributions:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::simulation::random::prng_Bernoulli</b> <i class="arg">p</i></a></dt>
<dd><p>Create a command (PRNG) that generates numbers with a Bernoulli
distribution: the value is either 1 or 0, with a chance p to be 1</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">p</i></dt>
<dd><p>Chance the outcome is 1</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::simulation::random::prng_Discrete</b> <i class="arg">n</i></a></dt>
<dd><p>Create a command (PRNG) that generates numbers 0 to n-1 with equal
probability.</p>
<dl class="doctools_arguments">
<dt>int <i class="arg">n</i></dt>
<dd><p>Number of different values (ranging from 0 to n-1)</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::simulation::random::prng_Poisson</b> <i class="arg">lambda</i></a></dt>
<dd><p>Create a command (PRNG) that generates numbers according to the Poisson
distribution.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">lambda</i></dt>
<dd><p>Mean number per time interval</p></dd>
</dl></dd>
</dl>
<p>The package defines the following public procedures for <em>continuous</em> distributions:</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">::simulation::random::prng_Uniform</b> <i class="arg">min</i> <i class="arg">max</i></a></dt>
<dd><p>Create a command (PRNG) that generates uniformly distributed numbers
between "min" and "max".</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">min</i></dt>
<dd><p>Minimum number that will be generated</p></dd>
<dt>float <i class="arg">max</i></dt>
<dd><p>Maximum number that will be generated</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::simulation::random::prng_Exponential</b> <i class="arg">min</i> <i class="arg">mean</i></a></dt>
<dd><p>Create a command (PRNG) that generates exponentially distributed numbers
with a given minimum value and a given mean value.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">min</i></dt>
<dd><p>Minimum number that will be generated</p></dd>
<dt>float <i class="arg">mean</i></dt>
<dd><p>Mean value for the numbers</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">::simulation::random::prng_Normal</b> <i class="arg">mean</i> <i class="arg">stdev</i></a></dt>
<dd><p>Create a command (PRNG) that generates normally distributed numbers
with a given mean value and a given standard deviation.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">mean</i></dt>
<dd><p>Mean value for the numbers</p></dd>
<dt>float <i class="arg">stdev</i></dt>
<dd><p>Standard deviation</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::simulation::random::prng_Pareto</b> <i class="arg">min</i> <i class="arg">steep</i></a></dt>
<dd><p>Create a command (PRNG) that generates numbers distributed according to
Pareto with a given minimum value and a given distribution steepness.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">min</i></dt>
<dd><p>Minimum number that will be generated</p></dd>
<dt>float <i class="arg">steep</i></dt>
<dd><p>Steepness of the distribution</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">::simulation::random::prng_Gumbel</b> <i class="arg">min</i> <i class="arg">f</i></a></dt>
<dd><p>Create a command (PRNG) that generates numbers distributed according to
Gumbel with a given minimum value and a given scale factor. The
probability density function is:</p>
<pre class="doctools_example">
P(v) = exp( -exp(f*(v-min)))
</pre>
<dl class="doctools_arguments">
<dt>float <i class="arg">min</i></dt>
<dd><p>Minimum number that will be generated</p></dd>
<dt>float <i class="arg">f</i></dt>
<dd><p>Scale factor for the values</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::simulation::random::prng_chiSquared</b> <i class="arg">df</i></a></dt>
<dd><p>Create a command (PRNG) that generates numbers distributed according to
the chi-squared distribution with df degrees of freedom. The mean is 0
and the standard deviation is 1.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">df</i></dt>
<dd><p>Degrees of freedom</p></dd>
</dl></dd>
</dl>
<p>The package defines the following public procedures for random point sets:</p>
<dl class="doctools_definitions">
<dt><a name="10"><b class="cmd">::simulation::random::prng_Disk</b> <i class="arg">rad</i></a></dt>
<dd><p>Create a command (PRNG) that generates (x,y)-coordinates for points
uniformly spread over a disk of given radius.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">rad</i></dt>
<dd><p>Radius of the disk</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::simulation::random::prng_Sphere</b> <i class="arg">rad</i></a></dt>
<dd><p>Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread over the surface of a sphere of given radius.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">rad</i></dt>
<dd><p>Radius of the disk</p></dd>
</dl></dd>
<dt><a name="12"><b class="cmd">::simulation::random::prng_Ball</b> <i class="arg">rad</i></a></dt>
<dd><p>Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread within a ball of given radius.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">rad</i></dt>
<dd><p>Radius of the ball</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">::simulation::random::prng_Rectangle</b> <i class="arg">length</i> <i class="arg">width</i></a></dt>
<dd><p>Create a command (PRNG) that generates (x,y)-coordinates for points
uniformly spread over a rectangle.</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">length</i></dt>
<dd><p>Length of the rectangle (x-direction)</p></dd>
<dt>float <i class="arg">width</i></dt>
<dd><p>Width of the rectangle (y-direction)</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">::simulation::random::prng_Block</b> <i class="arg">length</i> <i class="arg">width</i> <i class="arg">depth</i></a></dt>
<dd><p>Create a command (PRNG) that generates (x,y,z)-coordinates for points
uniformly spread over a block</p>
<dl class="doctools_arguments">
<dt>float <i class="arg">length</i></dt>
<dd><p>Length of the block (x-direction)</p></dd>
<dt>float <i class="arg">width</i></dt>
<dd><p>Width of the block (y-direction)</p></dd>
<dt>float <i class="arg">depth</i></dt>
<dd><p>Depth of the block (z-direction)</p></dd>
</dl></dd>
</dl>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#math">math</a>, <a href="../../../../index.html#random_numbers">random numbers</a>, <a href="../../../../index.html#simulation">simulation</a>, <a href="../../../../index.html#statistical_distribution">statistical distribution</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Arjen Markus <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/smtpd/smtpd.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
<div class='fossil-doc' data-title='smtpd - Tcl SMTP Server Package'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">smtpd(n) 1.5 tcllib "Tcl SMTP Server Package"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>smtpd - Tcl SMTP server implementation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">SECURITY</a></li>
<li class="doctools_section"><a href="#section3">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section4">COMMANDS</a></li>
<li class="doctools_section"><a href="#section5">CALLBACKS</a></li>
<li class="doctools_section"><a href="#section6">VARIABLES</a></li>
<li class="doctools_section"><a href="#section7">AUTHOR</a></li>
<li class="doctools_section"><a href="#section8">LICENSE</a></li>
<li class="doctools_section"><a href="#section9">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">smtpd <span class="opt">?1.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::smtpd::start</b> <span class="opt">?<i class="arg">myaddr</i>?</span> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::smtpd::stop</b></a></li>
<li><a href="#3"><b class="cmd">::smptd::configure</b> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>?</span> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> <i class="arg">...</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::smtpd::cget</b> <span class="opt">?<i class="arg">option</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">smtpd</b> package provides a simple Tcl-only server library
for the Simple Mail Transfer Protocol as described in
RFC 821 (<a href="http://www.rfc-editor.org/rfc/rfc821.txt">http://www.rfc-editor.org/rfc/rfc821.txt</a>) and
RFC 2821 (<a href="http://www.rfc-editor.org/rfc/rfc2821.txt">http://www.rfc-editor.org/rfc/rfc2821.txt</a>).
By default the server will bind to the default network address and the
standard SMTP port (25).</p>
<p>This package was designed to permit testing of Mail User Agent code
from a developers workstation. <em>It does not attempt to deliver mail to your mailbox.</em> Instead users of this package are expected to
write a procedure that will be called when mail arrives. Once this
procedure returns, the server has nothing further to do with the mail.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">SECURITY</a></h2>
<p>On Unix platforms binding to the SMTP port requires root privileges. I
would not recommend running any script-based server as root unless
there is some method for dropping root privileges immediately after
the socket is bound. Under Windows platforms, it is not necessary to
have root or administrator privileges to bind low numbered
sockets. However, security on these platforms is weak anyway.</p>
<p>In short, this code should probably not be used as a permanently
running Mail Transfer Agent on an Internet connected server, even
though we are careful not to evaluate remote user input. There are
many other well tested and security audited programs that can be used
as mail servers for internet connected hosts.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::smtpd::start</b> <span class="opt">?<i class="arg">myaddr</i>?</span> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Start the service listening on <i class="arg">port</i> or the default port 25. If
<i class="arg">myaddr</i> is given as a domain-style name or numerical
dotted-quad IP address then the server socket will be bound to that
network interface. By default the server is bound to all network
interfaces. For example:</p>
<pre class="doctools_example">
set sock [::smtpd::start [info hostname] 0]
</pre>
<p>will bind to the hosts internet interface on the first available port.</p>
<p>At present the package only supports a single instance of a SMTP
server. This could be changed if required at the cost of making the
package a little more complicated to read. If there is a good reason
for running multiple SMTP services then it will only be necessary to
fix the <b class="variable">options</b> array and the <b class="variable">::smtpd::stopped</b> variable
usage.</p>
<p>As the server code uses <b class="cmd">fileevent</b>(n) handlers to process the
input on sockets you will need to run the event loop. This means
either you should be running from within <b class="syscmd">wish</b>(1) or you
should <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>(n) on the <b class="variable">::smtpd::stopped</b> variable which is
set when the server is stopped.</p></dd>
<dt><a name="2"><b class="cmd">::smtpd::stop</b></a></dt>
<dd><p>Halt the server and release the listening socket. If the server has
not been started then this command does nothing.
The <b class="variable">::smtpd::stopped</b> variable is set for use with
<b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>(n).</p>
<p>It should be noted that stopping the server does not disconnect any
currently active sessions as these are operating over an independent
channel. Only explicitly tracking and closing these sessions, or
exiting the server process will close down all the running
sessions. This is similar to the usual unix daemon practice where the
server performs a <b class="syscmd">fork</b>(2) and the client session continues on
the child process.</p></dd>
<dt><a name="3"><b class="cmd">::smptd::configure</b> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>?</span> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> <i class="arg">...</i>?</span></a></dt>
<dd><p>Set configuration options for the SMTP server. Most values are the
name of a callback procedure to be called at various points in the
SMTP protocol. See the <span class="sectref"><a href="#section5">CALLBACKS</a></span> section for details of the
procedures.</p>
<dl class="doctools_definitions">
<dt><b class="option">-banner</b> <i class="arg">text</i></dt>
<dd><p>Text of a custom banner message. The default banner is "tcllib smtpd 1.5".
Note that changing the banner does not affect the bracketing text
in the full greeting, printing status 220, server-address, and timestamp.</p></dd>
<dt><b class="option">-validate_host</b> <i class="arg">proc</i></dt>
<dd><p>Callback to authenticate new connections based on the ip-address of
the client.</p></dd>
<dt><b class="option">-validate_sender</b> <i class="arg">proc</i></dt>
<dd><p>Callback to authenticate new connections based on the senders email
address.</p></dd>
<dt><b class="option">-validate_recipient</b> <i class="arg">proc</i></dt>
<dd><p>Callback to validate and authorize a recipient email address</p></dd>
<dt><b class="option">-deliverMIME</b> <i class="arg">proc</i></dt>
<dd><p>Callback used to deliver mail as a mime token created by the tcllib
<b class="package"><a href="../mime/mime.html">mime</a></b> package.</p></dd>
<dt><b class="option">-deliver</b> <i class="arg">proc</i></dt>
<dd><p>Callback used to deliver email. This option has no effect if
the <b class="option">-deliverMIME</b> option has been set.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">::smtpd::cget</b> <span class="opt">?<i class="arg">option</i>?</span></a></dt>
<dd><p>If no <i class="arg">option</i> is specified the command will return a list of all
options and their current values. If an option is specified it will
return the value of that option.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">CALLBACKS</a></h2>
<dl class="doctools_definitions">
<dt><b class="cmd">validate_host</b> callback</dt>
<dd><p>This procedure is called with the clients ip address as soon as a
connection request has been accepted and before any protocol commands
are processed. If you wish to deny access to a specific host then an
error should be returned by this callback. For example:</p>
<pre class="doctools_example">
proc validate_host {ipnum} {
if {[string match "192.168.1.*" $ipnum]} {
error "go away!"
}
}
</pre>
<p>If access is denied the client will receive a standard message that
includes the text of your error, such as:</p>
<pre class="doctools_example">
550 Access denied: I hate you.
</pre>
<p>As per the SMTP protocol, the connection is not closed but we wait for
the client to send a QUIT command. Any other commands cause a
<b class="const">503 Bad Sequence</b> error.</p></dd>
<dt><b class="cmd">validate_sender</b> callback</dt>
<dd><p>The validate_sender callback is called with the senders mail address
during processing of a MAIL command to allow you to accept or reject
mail based upon the declared sender. To reject mail you should throw
an error. For example, to reject mail from user "denied":</p>
<pre class="doctools_example">
proc validate_sender {address} {
eval array set addr [mime::parseaddress $address]
if {[string match "denied" $addr(local)]} {
error "mailbox $addr(local) denied"
}
return
}
</pre>
<p>The content of any error message will not be passed back to the client.</p></dd>
<dt><b class="cmd">validate_recipient</b> callback</dt>
<dd><p>The validate_recipient callback is similar to the validate_sender
callback and permits you to verify a local mailbox and accept mail for
a local user address during RCPT command handling. To reject mail,
throw an error as above. The error message is ignored.</p></dd>
<dt><b class="cmd">deliverMIME</b> callback</dt>
<dd><p>The deliverMIME callback is called once a mail message has been
successfully passed to the server. A mime token is constructed from
the sender, recipients and data and the users procedure it called with
this single argument. When the call returns, the mime token is cleaned
up so if the user wishes to preserve the data she must make a copy.</p>
<pre class="doctools_example">
proc deliverMIME {token} {
set sender [lindex [mime::getheader $token From] 0]
set recipients [lindex [mime::getheader $token To] 0]
set mail "From $sender [clock format [clock seconds]]"
append mail "\n" [mime::buildmessage $token]
puts $mail
}
</pre>
</dd>
<dt><b class="cmd">deliver</b> callback</dt>
<dd><p>The deliver callback is called once a mail message has been
successfully passed to the server and there is no -deliverMIME option
set. The procedure is called with the sender, a list of recipients and
the text of the mail as a list of lines. For example:</p>
<pre class="doctools_example">
proc deliver {sender recipients data} {
set mail "From $sender [clock format [clock seconds]]"
append mail "\n" [join $data "\n"]
puts "$mail"
}
</pre>
<p>Note that the DATA command will return an error if no sender or
recipient has yet been defined.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">VARIABLES</a></h2>
<dl class="doctools_definitions">
<dt><b class="variable">::smtpd::stopped</b></dt>
<dd><p>This variable is set to <b class="const">true</b> during the <b class="cmd">::smtpd::stop</b>
command to permit the use of the <b class="cmd"><a href="../../../../index.html#vwait">vwait</a></b>(n) command.</p></dd>
</dl>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">AUTHOR</a></h2>
<p>Written by Pat Thoyts <a href="mailto:[email protected]">mailto:[email protected]</a>.</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">LICENSE</a></h2>
<p>This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file
"<b class="file">license.terms</b>" for more details.</p>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>smtpd</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#rfc_2821">rfc 2821</a>, <a href="../../../../index.html#rfc_821">rfc 821</a>, <a href="../../../../index.html#services">services</a>, <a href="../../../../index.html#smtp">smtp</a>, <a href="../../../../index.html#smtpd">smtpd</a>, <a href="../../../../index.html#socket">socket</a>, <a href="../../../../index.html#vwait">vwait</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/snit/snit.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
|
<div class='fossil-doc' data-title='snit - Snit's Not Incr Tcl, OO system'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">snit(n) 2.3.2 tcllib "Snit's Not Incr Tcl, OO system"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>snit - Snit's Not Incr Tcl</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">SNIT VERSIONS</a></li>
<li class="doctools_section"><a href="#section3">REFERENCE</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Type and Widget Definitions</a></li>
<li class="doctools_subsection"><a href="#subsection2">The Type Command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Standard Type Methods</a></li>
<li class="doctools_subsection"><a href="#subsection4">The Instance Command</a></li>
<li class="doctools_subsection"><a href="#subsection5">Standard Instance Methods</a></li>
<li class="doctools_subsection"><a href="#subsection6">Commands for use in Object Code</a></li>
<li class="doctools_subsection"><a href="#subsection7">Components and Delegation</a></li>
<li class="doctools_subsection"><a href="#subsection8">Type Components and Delegation</a></li>
<li class="doctools_subsection"><a href="#subsection9">The Tk Option Database</a></li>
<li class="doctools_subsection"><a href="#subsection10">Macros and Meta-programming</a></li>
<li class="doctools_subsection"><a href="#subsection11">Validation Types</a></li>
<li class="doctools_subsection"><a href="#subsection12">Defining Validation Types</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">CAVEATS</a></li>
<li class="doctools_section"><a href="#section5">KNOWN BUGS</a></li>
<li class="doctools_section"><a href="#section6">HISTORY</a></li>
<li class="doctools_section"><a href="#section7">CREDITS</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?2.3.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">snit::type</b> <i class="arg">name</i> <i class="arg">definition</i></a></li>
<li><a href="#2"><b class="cmd">typevariable</b> <i class="arg">name</i> <span class="opt">?<b class="const">-array</b>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#3"><b class="cmd">typemethod</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#4"><b class="cmd">typeconstructor</b> <i class="arg">body</i></a></li>
<li><a href="#5"><b class="cmd">variable</b> <i class="arg">name</i> <span class="opt">?<b class="const">-array</b>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#6"><b class="cmd"><a href="../../../../index.html#method">method</a></b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#7"><b class="cmd">option</b> <i class="arg">namespec</i> <span class="opt">?<i class="arg">defaultValue</i>?</span></a></li>
<li><a href="#8"><b class="cmd">option</b> <i class="arg">namespec</i> <span class="opt">?<i class="arg">options...</i>?</span></a></li>
<li><a href="#9"><b class="cmd">constructor</b> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#10"><b class="cmd">destructor</b> <i class="arg">body</i></a></li>
<li><a href="#11"><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> <i class="arg">name</i> <i class="arg">args</i> <i class="arg">body</i></a></li>
<li><a href="#12"><b class="cmd">delegate</b> <b class="const">method</b> <i class="arg">name</i> <b class="const">to</b> <i class="arg">comp</i> <span class="opt">?<b class="const">as</b> <i class="arg">target</i>?</span></a></li>
<li><a href="#13"><b class="cmd">delegate</b> <b class="const">method</b> <i class="arg">name</i> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <b class="const">using</b> <i class="arg">pattern</i></a></li>
<li><a href="#14"><b class="cmd">delegate</b> <b class="const">method</b> <b class="const">*</b> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <span class="opt">?<b class="const">using</b> <i class="arg">pattern</i>?</span> <span class="opt">?<b class="const">except</b> <i class="arg">exceptions</i>?</span></a></li>
<li><a href="#15"><b class="cmd">delegate</b> <b class="const">option</b> <i class="arg">namespec</i> <b class="const">to</b> <i class="arg">comp</i></a></li>
<li><a href="#16"><b class="cmd">delegate</b> <b class="const">option</b> <i class="arg">namespec</i> <b class="const">to</b> <i class="arg">comp</i> <b class="const">as</b> <i class="arg">target</i></a></li>
<li><a href="#17"><b class="cmd">delegate</b> <b class="const">option</b> <b class="const">*</b> <b class="const">to</b> <i class="arg">comp</i></a></li>
<li><a href="#18"><b class="cmd">delegate</b> <b class="const">option</b> <b class="const">*</b> <b class="const">to</b> <i class="arg">comp</i> <b class="const">except</b> <i class="arg">exceptions</i></a></li>
<li><a href="#19"><b class="cmd">component</b> <i class="arg">comp</i> <span class="opt">?<b class="const">-public</b> <i class="arg">method</i>?</span> <span class="opt">?<b class="const">-inherit</b> <i class="arg">flag</i>?</span></a></li>
<li><a href="#20"><b class="cmd">delegate</b> <b class="const">typemethod</b> <i class="arg">name</i> <b class="const">to</b> <i class="arg">comp</i> <span class="opt">?<b class="const">as</b> <i class="arg">target</i>?</span></a></li>
<li><a href="#21"><b class="cmd">delegate</b> <b class="const">typemethod</b> <i class="arg">name</i> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <b class="const">using</b> <i class="arg">pattern</i></a></li>
<li><a href="#22"><b class="cmd">delegate</b> <b class="const">typemethod</b> <b class="const">*</b> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <span class="opt">?<b class="const">using</b> <i class="arg">pattern</i>?</span> <span class="opt">?<b class="const">except</b> <i class="arg">exceptions</i>?</span></a></li>
<li><a href="#23"><b class="cmd">typecomponent</b> <i class="arg">comp</i> <span class="opt">?<b class="const">-public</b> <i class="arg">typemethod</i>?</span> <span class="opt">?<b class="const">-inherit</b> <i class="arg">flag</i>?</span></a></li>
<li><a href="#24"><b class="cmd">pragma</b> <span class="opt">?<i class="arg">options...</i>?</span></a></li>
<li><a href="#25"><b class="cmd">expose</b> <i class="arg">comp</i></a></li>
<li><a href="#26"><b class="cmd">expose</b> <i class="arg">comp</i> <b class="const">as</b> <i class="arg">method</i></a></li>
<li><a href="#27"><b class="cmd">onconfigure</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#28"><b class="cmd">oncget</b> <i class="arg">name</i> <i class="arg">body</i></a></li>
<li><a href="#29"><b class="cmd">snit::widget</b> <i class="arg">name</i> <i class="arg">definition</i></a></li>
<li><a href="#30"><b class="cmd">widgetclass</b> <i class="arg">name</i></a></li>
<li><a href="#31"><b class="cmd">hulltype</b> <i class="arg">type</i></a></li>
<li><a href="#32"><b class="cmd">snit::widgetadaptor</b> <i class="arg">name</i> <i class="arg">definition</i></a></li>
<li><a href="#33"><b class="cmd">snit::typemethod</b> <i class="arg">type</i> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#34"><b class="cmd">snit::method</b> <i class="arg">type</i> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#35"><b class="cmd">snit::macro</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#36"><b class="cmd">snit::compile</b> <i class="arg">which</i> <i class="arg">type</i> <i class="arg">body</i></a></li>
<li><a href="#37"><b class="cmd">$type</b> <i class="arg">typemethod</i> <i class="arg">args</i>...</a></li>
<li><a href="#38"><b class="cmd">$type</b> <b class="method">create</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></li>
<li><a href="#39"><b class="cmd">$type</b> <b class="method">info typevars</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#40"><b class="cmd">$type</b> <b class="method">info typemethods</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#41"><b class="cmd">$type</b> <b class="method">info args</b> <i class="arg">method</i></a></li>
<li><a href="#42"><b class="cmd">$type</b> <b class="method">info body</b> <i class="arg">method</i></a></li>
<li><a href="#43"><b class="cmd">$type</b> <b class="method">info default</b> <i class="arg">method</i> <i class="arg">aname</i> <i class="arg">varname</i></a></li>
<li><a href="#44"><b class="cmd">$type</b> <b class="method">info instances</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#45"><b class="cmd">$type</b> <b class="method">destroy</b></a></li>
<li><a href="#46"><b class="cmd">$object</b> <i class="arg">method</i> <i class="arg">args...</i></a></li>
<li><a href="#47"><b class="cmd">$object</b> <b class="method">configure</b> <span class="opt">?<i class="arg">option</i>?</span> <span class="opt">?<i class="arg">value</i>?</span> ...</a></li>
<li><a href="#48"><b class="cmd">$object</b> <b class="method">configurelist</b> <i class="arg">optionlist</i></a></li>
<li><a href="#49"><b class="cmd">$object</b> <b class="method">cget</b> <i class="arg">option</i></a></li>
<li><a href="#50"><b class="cmd">$object</b> <b class="method">destroy</b></a></li>
<li><a href="#51"><b class="cmd">$object</b> <b class="method">info type</b></a></li>
<li><a href="#52"><b class="cmd">$object</b> <b class="method">info vars</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#53"><b class="cmd">$object</b> <b class="method">info typevars</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#54"><b class="cmd">$object</b> <b class="method">info typemethods</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#55"><b class="cmd">$object</b> <b class="method">info options</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#56"><b class="cmd">$object</b> <b class="method">info methods</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#57"><b class="cmd">$object</b> <b class="method">info args</b> <i class="arg">method</i></a></li>
<li><a href="#58"><b class="cmd">$object</b> <b class="method">info body</b> <i class="arg">method</i></a></li>
<li><a href="#59"><b class="cmd">$object</b> <b class="method">info default</b> <i class="arg">method</i> <i class="arg">aname</i> <i class="arg">varname</i></a></li>
<li><a href="#60"><b class="cmd">mymethod</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args...</i>?</span></a></li>
<li><a href="#61"><b class="cmd">mytypemethod</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args...</i>?</span></a></li>
<li><a href="#62"><b class="cmd">myproc</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args...</i>?</span></a></li>
<li><a href="#63"><b class="cmd">myvar</b> <i class="arg">name</i></a></li>
<li><a href="#64"><b class="cmd">mytypevar</b> <i class="arg">name</i></a></li>
<li><a href="#65"><b class="cmd">from</b> <i class="arg">argvName</i> <i class="arg">option</i> <span class="opt">?<i class="arg">defvalue</i>?</span></a></li>
<li><a href="#66"><b class="cmd">install</b> <i class="arg">compName</i> <b class="const">using</b> <i class="arg">objType</i> <i class="arg">objName</i> <i class="arg">args...</i></a></li>
<li><a href="#67"><b class="cmd">installhull</b> <b class="const">using</b> <i class="arg">widgetType</i> <i class="arg">args...</i></a></li>
<li><a href="#68"><b class="cmd">installhull</b> <i class="arg">name</i></a></li>
<li><a href="#69"><b class="cmd">variable</b> <i class="arg">name</i></a></li>
<li><a href="#70"><b class="cmd">typevariable</b> <i class="arg">name</i></a></li>
<li><a href="#71"><b class="cmd">varname</b> <i class="arg">name</i></a></li>
<li><a href="#72"><b class="cmd">typevarname</b> <i class="arg">name</i></a></li>
<li><a href="#73"><b class="cmd">codename</b> <i class="arg">name</i></a></li>
<li><a href="#74"><b class="cmd">snit::boolean</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#75"><b class="cmd">snit::boolean</b> <i class="arg">name</i></a></li>
<li><a href="#76"><b class="cmd">snit::double</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#77"><b class="cmd">snit::double</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#78"><b class="cmd">snit::enum</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#79"><b class="cmd">snit::enum</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#80"><b class="cmd">snit::fpixels</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#81"><b class="cmd">snit::fpixels</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#82"><b class="cmd">snit::integer</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#83"><b class="cmd">snit::integer</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#84"><b class="cmd">snit::listtype</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#85"><b class="cmd">snit::listtype</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#86"><b class="cmd">snit::pixels</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#87"><b class="cmd">snit::pixels</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#88"><b class="cmd">snit::stringtype</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#89"><b class="cmd">snit::stringtype</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></li>
<li><a href="#90"><b class="cmd">snit::window</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#91"><b class="cmd">snit::window</b> <i class="arg">name</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Snit is a pure Tcl object and megawidget system. It's
unique among Tcl object systems in that it's based not on inheritance
but on delegation. Object systems based on inheritance only allow you
to inherit from classes defined using the same system, which is
limiting. In Tcl, an object is
anything that acts like an object; it shouldn't matter how the object
was implemented. Snit is intended to help you build applications out of
the materials at hand; thus, Snit is designed to be able to
incorporate and build on any object, whether it's a hand-coded object,
a <b class="package"><a href="../../../../index.html#tk">Tk</a></b> widget, an <b class="package"><a href="../../../../index.html#incr_tcl">Incr Tcl</a></b> object,
a <b class="package"><a href="../../../../index.html#bwidget">BWidget</a></b> or almost anything else.</p>
<p>This man page is intended to be a reference only; see the accompanying
<b class="cmd"><a href="snitfaq.html">snitfaq</a></b> for a gentler, more tutorial introduction to Snit
concepts.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">SNIT VERSIONS</a></h2>
<p>This man page covers both Snit 2.2 and Snit 1.3. The primary
difference between the two versions is simply that Snit 2.2 contains
speed optimizations based on new features of Tcl 8.5; Snit 1.3
supports all of Tcl 8.3, 8.4 and Tcl 8.5. There are a few minor
inconsistencies; they are flagged in the body of the man page with the
label "Snit 1.x Incompatibility"; they are also discussed in the <b class="cmd"><a href="snitfaq.html">snitfaq</a></b>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">REFERENCE</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Type and Widget Definitions</a></h3>
<p>Snit provides the following commands for defining new types:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">snit::type</b> <i class="arg">name</i> <i class="arg">definition</i></a></dt>
<dd><p>Defines a new abstract data type called <i class="arg">name</i>. If <i class="arg">name</i> is
not a fully qualified command name, it is assumed to be a name in the
namespace in which the <b class="cmd">snit::type</b> command was called (usually the
global namespace). It returns the fully qualified name of the new type.</p>
<p>The type name is then a command that is used to create objects of the
new type, along with other activities.</p>
<p>The <b class="cmd">snit::type</b> <i class="arg">definition</i> block is a script that may
contain the following definitions:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">typevariable</b> <i class="arg">name</i> <span class="opt">?<b class="const">-array</b>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Defines a type variable with the specified <i class="arg">name</i>, and optionally
the specified <i class="arg">value</i>. Type variables are shared by all instances
of the type. If the <b class="const">-array</b> option is included, then
<i class="arg">value</i> should be a dictionary; it will be
assigned to the variable using <b class="cmd">array set</b>.</p></dd>
<dt><a name="3"><b class="cmd">typemethod</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Defines a type method, a subcommand of the new type command,
with the specified name, argument list, and
body. The <i class="arg">arglist</i> is a normal Tcl argument list and may contain
default arguments and the <b class="variable">args</b> argument; however, it may not
contain the argument names <b class="variable">type</b>, <b class="variable">self</b>, <b class="variable">selfns</b>, or
<b class="variable">win</b>.</p>
<p>The variable <b class="variable">type</b> is automatically defined in the <i class="arg">body</i> to
the type's fully-qualified name. In addition,
type variables are automatically visible in the <i class="arg">body</i>
of every type method.</p>
<p>If the <i class="arg">name</i> consists of two or more tokens, Snit handles it specially:</p>
<pre class="doctools_example"> typemethod {a b} {arg} { puts "Got $arg" }
</pre>
<p>This statement implicitly defines a type method called <b class="const">a</b> which
has a subcommand <b class="const">b</b>. <b class="const">b</b> is called like this:</p>
<pre class="doctools_example"> $type a b "Hello, world!"
</pre>
<p><b class="const">a</b> may have any number of subcommands. This makes it possible
to define a hierarchical command structure; see <b class="cmd"><a href="../../../../index.html#method">method</a></b>, below,
for more examples.</p>
<p>Type methods can call commands from the namespace in which the type is
defined without importing them, e.g., if the type name is
<b class="cmd">::parentns::typename</b>, then the type's type methods can call
<b class="cmd">::parentns::someproc</b> just as <b class="cmd">someproc</b>.
<em>Snit 1.x Incompatibility:</em> This does not work in Snit 1.x, as
it depends on <b class="cmd">namespace path</b>, a new command in Tcl 8.5.</p>
<p><em>Snit 1.x Incompatibility:</em> In Snit 1.x, the following
following two calls to this type method are equivalent:</p>
<pre class="doctools_example"> $type a b "Hello, world!"
$type {a b} "Hello, world!"
</pre>
<p>In Snit 2.2, the second form is invalid.</p></dd>
<dt><a name="4"><b class="cmd">typeconstructor</b> <i class="arg">body</i></a></dt>
<dd><p>The type constructor's <i class="arg">body</i> is executed once when the
type is first defined; it is typically used to
initialize array-valued type variables and to add
entries to <span class="sectref"><a href="#subsection9">The Tk Option Database</a></span>.</p>
<p>The variable <b class="variable">type</b> is automatically defined in the <i class="arg">body</i>,
and contains the type's fully-qualified name. In addition,
type variables are automatically visible in the <i class="arg">body</i> of the type
constructor.</p>
<p>A type may define at most one type constructor.</p>
<p>The type constructor can call commands from the namespace in which the type is
defined without importing them, e.g., if the type name is
<b class="cmd">::parentns::typename</b>, then the type constructor can call
<b class="cmd">::parentns::someproc</b> just as <b class="cmd">someproc</b>.
<em>Snit 1.x Incompatibility:</em> This does not work in Snit 1.x, as
it depends on <b class="cmd">namespace path</b>, a new command in Tcl 8.5.</p></dd>
<dt><a name="5"><b class="cmd">variable</b> <i class="arg">name</i> <span class="opt">?<b class="const">-array</b>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Defines an instance variable, a private variable associated with each
instance of this type, and optionally its initial value.
If the <b class="const">-array</b> option is included, then
<i class="arg">value</i> should be a dictionary; it will be
assigned to the variable using <b class="cmd">array set</b>.</p></dd>
<dt><a name="6"><b class="cmd"><a href="../../../../index.html#method">method</a></b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Defines an instance method, a subcommand of each instance of this
type, with the specified name, argument list and body.
The <i class="arg">arglist</i> is a normal Tcl argument list and may contain
default arguments and the <b class="variable">args</b> argument.</p>
<p>The method is implicitly passed the following arguments as well:
<b class="variable">type</b>, which contains the fully-qualified type name; <b class="variable">self</b>,
which contains the current instance command name; <b class="variable">selfns</b>, which
contains the name of the instance's private namespace; and <b class="variable">win</b>,
which contains the original instance name.
Consequently, the <i class="arg">arglist</i> may not contain the argument names
<b class="const">type</b>, <b class="const">self</b>, <b class="const">selfns</b>, or <b class="const">win</b>.</p>
<p>An instance method defined in this way is said to be
<i class="term">locally defined</i>.</p>
<p>Type and instance variables are
automatically visible in all instance methods. If the type has
locally defined options, the <b class="variable">options</b> array is also visible.</p>
<p>If the <i class="arg">name</i> consists of two or more tokens, Snit handles it specially:</p>
<pre class="doctools_example"> method {a b} {} { ... }
</pre>
<p>This statement implicitly defines a method called <b class="const">a</b> which
has a subcommand <b class="const">b</b>. <b class="const">b</b> is called like this:</p>
<pre class="doctools_example"> $self a b "Hello, world!"
</pre>
<p><b class="const">a</b> may have any number of subcommands. This makes it possible
to define a hierarchical command structure:</p>
<pre class="doctools_example">% snit::type dog {
method {tail wag} {} {return "Wag, wag"}
method {tail droop} {} {return "Droop, droop"}
}
::dog
% dog spot
::spot
% spot tail wag
Wag, wag
% spot tail droop
Droop, droop
%
</pre>
<p>What we've done is implicitly defined a "tail" method with subcommands
"wag" and "droop". Consequently, it's an error to define "tail"
explicitly.</p>
<p>Methods can call commands from the namespace in which the type is
defined without importing them, e.g., if the type name is
<b class="cmd">::parentns::typename</b>, then the type's methods can call
<b class="cmd">::parentns::someproc</b> just as <b class="cmd">someproc</b>.
<em>Snit 1.x Incompatibility:</em> This does not work in Snit 1.x, as
it depends on <b class="cmd">namespace path</b>, a new command in Tcl 8.5.</p>
<p><em>Snit 1.x Incompatibility:</em> In Snit 1.x, the following
following two calls to this method are equivalent:</p>
<pre class="doctools_example"> $self a b "Hello, world!"
$self {a b} "Hello, world!"
</pre>
<p>In Snit 2.2, the second form is invalid.</p></dd>
<dt><a name="7"><b class="cmd">option</b> <i class="arg">namespec</i> <span class="opt">?<i class="arg">defaultValue</i>?</span></a></dt>
<dd></dd>
<dt><a name="8"><b class="cmd">option</b> <i class="arg">namespec</i> <span class="opt">?<i class="arg">options...</i>?</span></a></dt>
<dd><p>Defines an option for instances of this type, and optionally gives it
an initial value. The initial value defaults to the empty string if
no <i class="arg">defaultValue</i> is specified.</p>
<p>An option defined in this way is said to be <i class="term">locally defined</i>.</p>
<p>The <i class="arg">namespec</i> is a list defining the option's
name, resource name, and class name, e.g.:</p>
<pre class="doctools_example"> option {-font font Font} {Courier 12}
</pre>
<p>The option name must begin with a hyphen, and must not contain any
upper case letters. The resource name and class name are optional; if
not specified, the resource name defaults to the option name, minus
the hyphen, and the class name defaults to the resource name with the
first letter capitalized. Thus, the following statement is equivalent
to the previous example:</p>
<pre class="doctools_example"> option -font {Courier 12}
</pre>
<p>See <span class="sectref"><a href="#subsection9">The Tk Option Database</a></span> for more information about
resource and class names.</p>
<p>Options are normally set and retrieved using the standard
instance methods <b class="method">configure</b> and <b class="method">cget</b>; within instance code
(method bodies, etc.), option values are available through the
<b class="variable">options</b> array:</p>
<pre class="doctools_example"> set myfont $options(-font)
</pre>
<p>If the type defines any option handlers (e.g., <b class="const">-configuremethod</b>),
then it should probably use <b class="method">configure</b> and <b class="method">cget</b> to
access its options to avoid subtle errors.</p>
<p>The <b class="cmd">option</b> statement may include the following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-default</b> <i class="arg">defvalue</i></dt>
<dd><p>Defines the option's default value; the option's default value
will be "" otherwise.</p></dd>
<dt><b class="const">-readonly</b> <i class="arg">flag</i></dt>
<dd><p>The <i class="arg">flag</i> can be any Boolean value recognized by Tcl.
If <i class="arg">flag</i> is true, then the option is read-only--it can only
be set using <b class="method">configure</b> or <b class="method">configurelist</b>
at creation time, i.e., in the type's constructor.</p></dd>
<dt><b class="const">-type</b> <i class="arg">type</i></dt>
<dd><p>Every locally-defined option may define its validation type, which may
be either the name of a validation type or a specification for a
validation subtype</p>
<p>For example, an option may declare that its value must be an integer
by specifying <b class="cmd">snit::integer</b> as its validation type:</p>
<pre class="doctools_example"> option -number -type snit::integer
</pre>
<p>It may also declare that its value is an integer between 1 and 10
by specifying a validation subtype:</p>
<pre class="doctools_example"> option -number -type {snit::integer -min 1 -max 10}
</pre>
<p>If a validation type or subtype is defined for an option, then
it will be used to validate the option's value whenever it is
changed by the object's <b class="method">configure</b> or
<b class="method">configurelist</b> methods. In addition, all such options
will have their values validated automatically immediately
after the constructor executes.</p>
<p>Snit defines a family of validation types and subtypes, and it's
quite simple to define new ones. See
<span class="sectref"><a href="#subsection11">Validation Types</a></span> for the complete list, and
<span class="sectref"><a href="#subsection12">Defining Validation Types</a></span> for an explanation of how
to define your own.</p></dd>
<dt><b class="const">-cgetmethod</b> <i class="arg">methodName</i></dt>
<dd><p>Every locally-defined option may define a <b class="const">-cgetmethod</b>;
it is called when the option's value is retrieved using the
<b class="method">cget</b> method. Whatever the method's <i class="arg">body</i> returns will
be the return value of the call to <b class="method">cget</b>.</p>
<p>The named method must take one argument, the option name.
For example, this code is equivalent to (though slower than)
Snit's default handling of <b class="cmd">cget</b>:</p>
<pre class="doctools_example"> option -font -cgetmethod GetOption
method GetOption {option} {
return $options($option)
}
</pre>
<p>Note that it's possible for any number of options to share a
<b class="const">-cgetmethod</b>.</p></dd>
<dt><b class="const">-configuremethod</b> <i class="arg">methodName</i></dt>
<dd><p>Every locally-defined option may define a <b class="const">-configuremethod</b>;
it is called when the option's value is set using the
<b class="method">configure</b> or <b class="method">configurelist</b> methods. It is the
named method's responsibility to save the option's value; in other
words, the value will not be saved to the <b class="variable">options()</b> array unless
the method saves it there.</p>
<p>The named method must take two arguments, the option name and
its new value. For example, this code is equivalent to
(though slower than) Snit's default handling of <b class="cmd">configure</b>:</p>
<pre class="doctools_example"> option -font -configuremethod SetOption
method SetOption {option value} {
set options($option) $value
}
</pre>
<p>Note that it's possible for any number of options to share a
single <b class="const">-configuremethod</b>.</p></dd>
<dt><b class="const">-validatemethod</b> <i class="arg">methodName</i></dt>
<dd><p>Every locally-defined option may define a <b class="const">-validatemethod</b>;
it is called when the option's value is set using the
<b class="method">configure</b> or <b class="method">configurelist</b> methods, just before
the <b class="const">-configuremethod</b> (if any). It is the
named method's responsibility to validate the option's new value,
and to throw an error if the value is invalid.</p>
<p>The named method must take two arguments, the option name and
its new value. For example, this code verifies that
<b class="const">-flag</b>'s value is a valid Boolean value:</p>
<pre class="doctools_example"> option -font -validatemethod CheckBoolean
method CheckBoolean {option value} {
if {![string is boolean -strict $value]} {
error "option $option must have a boolean value."
}
}
</pre>
<p>Note that it's possible for any number of options to share a
single <b class="const">-validatemethod</b>.</p></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">constructor</b> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>The constructor definition specifies a <i class="arg">body</i> of code to be
executed when a new instance is created. The <i class="arg">arglist</i> is a
normal Tcl argument list and may contain default arguments and
the <b class="variable">args</b> argument.</p>
<p>As with methods, the arguments <b class="variable">type</b>, <b class="variable">self</b>, <b class="variable">selfns</b>,
and <b class="variable">win</b> are defined implicitly, and all type and instance
variables are automatically visible in its <i class="arg">body</i>.</p>
<p>If the <i class="arg">definition</i> doesn't explicitly define the constructor,
Snit defines one implicitly. If the type declares at least one option
(whether locally or by delegation), the default constructor will
be defined as follows:</p>
<pre class="doctools_example"> constructor {args} {
$self configurelist $args
}
</pre>
<p>For standard Tk widget behavior, the argument list should be
the single name <b class="const">args</b>, as shown.</p>
<p>If the <i class="arg">definition</i> defines neither a constructor nor
any options, the default constructor is defined as follows:</p>
<pre class="doctools_example"> constructor {} {}
</pre>
<p>As with methods, the constructor can call commands from the namespace
in which the type is
defined without importing them, e.g., if the type name is
<b class="cmd">::parentns::typename</b>, then the constructor can call
<b class="cmd">::parentns::someproc</b> just as <b class="cmd">someproc</b>.
<em>Snit 1.x Incompatibility:</em> This does not work in Snit 1.x, as
it depends on <b class="cmd">namespace path</b>, a new command in Tcl 8.5.</p></dd>
<dt><a name="10"><b class="cmd">destructor</b> <i class="arg">body</i></a></dt>
<dd><p>The destructor is used to code any actions that must take place when
an instance of the type is destroyed: typically, the destruction of
anything created in the constructor.</p>
<p>The destructor takes no explicit arguments; as with methods, the
arguments <b class="variable">type</b>, <b class="variable">self</b>, <b class="variable">selfns</b>, and <b class="variable">win</b>, are
defined implicitly, and all type and instance
variables are automatically visible in its <i class="arg">body</i>.
As with methods, the destructor can call commands from the namespace
in which the type is
defined without importing them, e.g., if the type name is
<b class="cmd">::parentns::typename</b>, then the destructor can call
<b class="cmd">::parentns::someproc</b> just as <b class="cmd">someproc</b>.
<em>Snit 1.x Incompatibility:</em> This does not work in Snit 1.x, as
it depends on <b class="cmd">namespace path</b>, a new command in Tcl 8.5.</p></dd>
<dt><a name="11"><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> <i class="arg">name</i> <i class="arg">args</i> <i class="arg">body</i></a></dt>
<dd><p>Defines a new Tcl procedure in the type's namespace.</p>
<p>The defined proc differs from a normal Tcl proc in that all type
variables are automatically visible. The proc can access
instance variables as well, provided that it is passed
<b class="variable">selfns</b> (with precisely that name) as one of its arguments.</p>
<p>Although they are not implicitly defined for procs, the argument names
<b class="const">type</b>, <b class="const">self</b>, and <b class="const">win</b> should be avoided.</p>
<p>As with methods and typemethods, procs can call commands from the namespace
in which the type is
defined without importing them, e.g., if the type name is
<b class="cmd">::parentns::typename</b>, then the proc can call
<b class="cmd">::parentns::someproc</b> just as <b class="cmd">someproc</b>.
<em>Snit 1.x Incompatibility:</em> This does not work in Snit 1.x, as
it depends on <b class="cmd">namespace path</b>, a new command in Tcl 8.5.</p></dd>
<dt><a name="12"><b class="cmd">delegate</b> <b class="const">method</b> <i class="arg">name</i> <b class="const">to</b> <i class="arg">comp</i> <span class="opt">?<b class="const">as</b> <i class="arg">target</i>?</span></a></dt>
<dd><p>Delegates method <i class="arg">name</i> to component <i class="arg">comp</i>. That is, when
method <i class="arg">name</i> is called on an instance of this type, the method
and its arguments will be passed to the named component's command
instead. That is, the following statement</p>
<pre class="doctools_example"> delegate method wag to tail
</pre>
<p>is roughly equivalent to this explicitly defined method:</p>
<pre class="doctools_example"> method wag {args} {
uplevel $tail wag $args
}
</pre>
<p>As with methods, the <i class="arg">name</i> may have multiple tokens; in this
case, the last token of the name is assumed to be the name of the
component's method.</p>
<p>The optional <b class="const">as</b> clause allows you to specify the delegated
method name and possibly add some arguments:</p>
<pre class="doctools_example"> delegate method wagtail to tail as "wag briskly"
</pre>
<p>A method cannot be both locally defined and delegated.</p>
<p><b class="const">Note:</b> All forms of <b class="cmd">delegate method</b> can delegate to
both instance components and type components.</p></dd>
<dt><a name="13"><b class="cmd">delegate</b> <b class="const">method</b> <i class="arg">name</i> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <b class="const">using</b> <i class="arg">pattern</i></a></dt>
<dd><p>In this form of the <b class="cmd">delegate</b> statement, the <b class="const">using</b> clause
is used to specify the precise form of the command to which method
<i class="arg">name</i> name is delegated. In this form, the <b class="const">to</b> clause is
optional, since the chosen command might not involve any particular
component.</p>
<p>The value of the <b class="const">using</b> clause is a list that may contain
any or all of the following substitution codes; these codes are
substituted with the described value to build the delegated command
prefix. Note that the following two statements are equivalent:</p>
<pre class="doctools_example"> delegate method wag to tail
delegate method wag to tail using "%c %m"
</pre>
<p>Each element of the list becomes a single element of the delegated
command--it is never reparsed as a string.</p>
<p>Substitutions:</p>
<dl class="doctools_definitions">
<dt><b class="const">%%</b></dt>
<dd><p>This is replaced with a single "%". Thus, to pass the string "%c"
to the command as an argument, you'd write "%%c".</p></dd>
<dt><b class="const">%c</b></dt>
<dd><p>This is replaced with the named component's command.</p></dd>
<dt><b class="const">%m</b></dt>
<dd><p>This is replaced with the final token of the method <i class="arg">name</i>; if
the method <i class="arg">name</i> has one token, this is identical to <b class="const">%M</b>.</p></dd>
<dt><b class="const">%M</b></dt>
<dd><p>This is replaced by the method <i class="arg">name</i>; if the <i class="arg">name</i> consists
of multiple tokens, they are joined by space characters.</p></dd>
<dt><b class="const">%j</b></dt>
<dd><p>This is replaced by the method <i class="arg">name</i>; if the <i class="arg">name</i> consists
of multiple tokens, they are joined by underscores ("_").</p></dd>
<dt><b class="const">%t</b></dt>
<dd><p>This is replaced with the fully qualified type name.</p></dd>
<dt><b class="const">%n</b></dt>
<dd><p>This is replaced with the name of the instance's private namespace.</p></dd>
<dt><b class="const">%s</b></dt>
<dd><p>This is replaced with the name of the instance command.</p></dd>
<dt><b class="const">%w</b></dt>
<dd><p>This is replaced with the original name of the instance command; for
Snit widgets and widget adaptors, it will be the Tk window name.
It remains constant, even if the instance command is renamed.</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">delegate</b> <b class="const">method</b> <b class="const">*</b> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <span class="opt">?<b class="const">using</b> <i class="arg">pattern</i>?</span> <span class="opt">?<b class="const">except</b> <i class="arg">exceptions</i>?</span></a></dt>
<dd><p>The form <b class="cmd">delegate method *</b> delegates all unknown method names to the
specified <i class="arg">comp</i>onent. The <b class="const">except</b> clause can be used to
specify a list of <i class="arg">exceptions</i>, i.e., method names that will not
be so delegated. The <b class="const">using</b> clause is defined as given above.
In this form, the statement must contain the <b class="const">to</b> clause, the
<b class="const">using</b> clause, or both.</p>
<p>In fact, the "*" can be a list of two or more tokens whose last
element is "*", as in the following example:</p>
<pre class="doctools_example"> delegate method {tail *} to tail
</pre>
<p>This implicitly defines the method <b class="cmd">tail</b> whose subcommands will
be delegated to the <b class="variable">tail</b> component.</p></dd>
<dt><a name="15"><b class="cmd">delegate</b> <b class="const">option</b> <i class="arg">namespec</i> <b class="const">to</b> <i class="arg">comp</i></a></dt>
<dd></dd>
<dt><a name="16"><b class="cmd">delegate</b> <b class="const">option</b> <i class="arg">namespec</i> <b class="const">to</b> <i class="arg">comp</i> <b class="const">as</b> <i class="arg">target</i></a></dt>
<dd></dd>
<dt><a name="17"><b class="cmd">delegate</b> <b class="const">option</b> <b class="const">*</b> <b class="const">to</b> <i class="arg">comp</i></a></dt>
<dd></dd>
<dt><a name="18"><b class="cmd">delegate</b> <b class="const">option</b> <b class="const">*</b> <b class="const">to</b> <i class="arg">comp</i> <b class="const">except</b> <i class="arg">exceptions</i></a></dt>
<dd><p>Defines a delegated option; the <i class="arg">namespec</i> is defined as for the
<b class="cmd">option</b> statement.
When the <b class="method">configure</b>, <b class="method">configurelist</b>, or <b class="method">cget</b>
instance method is used to set or retrieve the option's value, the
equivalent <b class="method">configure</b> or <b class="method">cget</b> command will be applied
to the component as though the option was defined with the following
<b class="const">-configuremethod</b> and <b class="const">-cgetmethod</b>:</p>
<pre class="doctools_example"> method ConfigureMethod {option value} {
$comp configure $option $value
}
method CgetMethod {option} {
return [$comp cget $option]
}
</pre>
<p>Note that delegated options never appear in the <b class="variable">options</b> array.</p>
<p>If the <b class="const">as</b> clause is specified, then the <i class="arg">target</i> option
name is used in place of <i class="arg">name</i>.</p>
<p>The form <b class="cmd">delegate option *</b> delegates all unknown options to the
specified <i class="arg">comp</i>onent. The <b class="const">except</b> clause can be used to
specify a list of <i class="arg">exceptions</i>, i.e., option names that will not
be so delegated.</p>
<p>Warning: options can only be delegated to a component if it supports
the <b class="method">configure</b> and <b class="method">cget</b> instance methods.</p>
<p>An option cannot be both locally defined and delegated.
TBD: Continue from here.</p></dd>
<dt><a name="19"><b class="cmd">component</b> <i class="arg">comp</i> <span class="opt">?<b class="const">-public</b> <i class="arg">method</i>?</span> <span class="opt">?<b class="const">-inherit</b> <i class="arg">flag</i>?</span></a></dt>
<dd><p>Explicitly declares a component called <i class="arg">comp</i>, and automatically
defines the component's instance variable.</p>
<p>If the <b class="const">-public</b> option is specified, then the option is made
public by defining a <i class="arg">method</i> whose subcommands are delegated
to the component e.g., specifying <b class="const">-public mycomp</b> is
equivalent to the following:</p>
<pre class="doctools_example"> component mycomp
delegate method {mymethod *} to mycomp
</pre>
<p>If the <b class="const">-inherit</b> option is specified, then <i class="arg">flag</i> must be a
Boolean value; if <i class="arg">flag</i> is true then all unknown methods and
options will be delegated to this component. The name <b class="const">-inherit</b>
implies that instances of this new type inherit, in a sense, the
methods and options of the component. That is, <b class="const">-inherit yes</b> is
equivalent to:</p>
<pre class="doctools_example"> component mycomp
delegate option * to mycomp
delegate method * to mycomp
</pre>
</dd>
<dt><a name="20"><b class="cmd">delegate</b> <b class="const">typemethod</b> <i class="arg">name</i> <b class="const">to</b> <i class="arg">comp</i> <span class="opt">?<b class="const">as</b> <i class="arg">target</i>?</span></a></dt>
<dd><p>Delegates type method <i class="arg">name</i> to type component <i class="arg">comp</i>. That is, when
type method <i class="arg">name</i> is called on this type, the type method
and its arguments will be passed to the named type component's command
instead. That is, the following statement</p>
<pre class="doctools_example"> delegate typemethod lostdogs to pound
</pre>
<p>is roughly equivalent to this explicitly defined method:</p>
<pre class="doctools_example"> typemethod lostdogs {args} {
uplevel $pound lostdogs $args
}
</pre>
<p>As with type methods, the <i class="arg">name</i> may have multiple tokens; in this
case, the last token of the name is assumed to be the name of the
component's method.</p>
<p>The optional <b class="const">as</b> clause allows you to specify the delegated
method name and possibly add some arguments:</p>
<pre class="doctools_example"> delegate typemethod lostdogs to pound as "get lostdogs"
</pre>
<p>A type method cannot be both locally defined and delegated.</p></dd>
<dt><a name="21"><b class="cmd">delegate</b> <b class="const">typemethod</b> <i class="arg">name</i> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <b class="const">using</b> <i class="arg">pattern</i></a></dt>
<dd><p>In this form of the <b class="cmd">delegate</b> statement, the <b class="const">using</b> clause
is used to specify the precise form of the command to which type method
<i class="arg">name</i> name is delegated. In this form, the <b class="const">to</b> clause is
optional, since the chosen command might not involve any particular
type component.</p>
<p>The value of the <b class="const">using</b> clause is a list that may contain
any or all of the following substitution codes; these codes are
substituted with the described value to build the delegated command
prefix. Note that the following two statements are equivalent:</p>
<pre class="doctools_example"> delegate typemethod lostdogs to pound
delegate typemethod lostdogs to pound using "%c %m"
</pre>
<p>Each element of the list becomes a single element of the delegated
command--it is never reparsed as a string.</p>
<p>Substitutions:</p>
<dl class="doctools_definitions">
<dt><b class="const">%%</b></dt>
<dd><p>This is replaced with a single "%". Thus, to pass the string "%c"
to the command as an argument, you'd write "%%c".</p></dd>
<dt><b class="const">%c</b></dt>
<dd><p>This is replaced with the named type component's command.</p></dd>
<dt><b class="const">%m</b></dt>
<dd><p>This is replaced with the final token of the type method <i class="arg">name</i>; if
the type method <i class="arg">name</i> has one token, this is identical to <b class="const">%M</b>.</p></dd>
<dt><b class="const">%M</b></dt>
<dd><p>This is replaced by the type method <i class="arg">name</i>; if the <i class="arg">name</i> consists
of multiple tokens, they are joined by space characters.</p></dd>
<dt><b class="const">%j</b></dt>
<dd><p>This is replaced by the type method <i class="arg">name</i>; if the <i class="arg">name</i> consists
of multiple tokens, they are joined by underscores ("_").</p></dd>
<dt><b class="const">%t</b></dt>
<dd><p>This is replaced with the fully qualified type name.</p></dd>
</dl></dd>
<dt><a name="22"><b class="cmd">delegate</b> <b class="const">typemethod</b> <b class="const">*</b> <span class="opt">?<b class="const">to</b> <i class="arg">comp</i>?</span> <span class="opt">?<b class="const">using</b> <i class="arg">pattern</i>?</span> <span class="opt">?<b class="const">except</b> <i class="arg">exceptions</i>?</span></a></dt>
<dd><p>The form <b class="cmd">delegate typemethod *</b> delegates all unknown type
method names to the
specified type component. The <b class="const">except</b> clause can be used to
specify a list of <i class="arg">exceptions</i>, i.e., type method names that will not
be so delegated. The <b class="const">using</b> clause is defined as given above.
In this form, the statement must contain the <b class="const">to</b> clause, the
<b class="const">using</b> clause, or both.</p>
<p><b class="const">Note:</b> By default, Snit interprets <b class="cmd">$type foo</b>, where
<b class="const">foo</b> is
not a defined type method, as equivalent to <b class="cmd">$type create foo</b>, where
<b class="const">foo</b> is the name of a new instance of the type. If you
use <b class="const">delegate typemethod *</b>, then the <b class="method">create</b> type
method must always be used explicitly.</p>
<p>The "*" can be a list of two or more tokens whose last
element is "*", as in the following example:</p>
<pre class="doctools_example"> delegate typemethod {tail *} to tail
</pre>
<p>This implicitly defines the type method <b class="cmd">tail</b> whose subcommands will
be delegated to the <b class="variable">tail</b> type component.</p></dd>
<dt><a name="23"><b class="cmd">typecomponent</b> <i class="arg">comp</i> <span class="opt">?<b class="const">-public</b> <i class="arg">typemethod</i>?</span> <span class="opt">?<b class="const">-inherit</b> <i class="arg">flag</i>?</span></a></dt>
<dd><p>Explicitly declares a type component called <i class="arg">comp</i>, and automatically
defines the component's type variable. A type component is an arbitrary
command to which type methods and instance methods can be delegated;
the command's name is stored in a type variable.</p>
<p>If the <b class="const">-public</b> option is specified, then the type component is made
public by defining a <i class="arg">typemethod</i> whose subcommands are delegated to
the type component, e.g., specifying <b class="const">-public mytypemethod</b>
is equivalent to the following:</p>
<pre class="doctools_example"> typecomponent mycomp
delegate typemethod {mytypemethod *} to mycomp
</pre>
<p>If the <b class="const">-inherit</b> option is specified, then <i class="arg">flag</i> must be a
Boolean value; if <i class="arg">flag</i> is true then all unknown type methods
will be delegated to this type component. (See the note on "delegate
typemethod *", above.) The name <b class="const">-inherit</b>
implies that this type inherits, in a sense, the behavior of
the type component. That is, <b class="const">-inherit yes</b> is equivalent to:</p>
<pre class="doctools_example"> typecomponent mycomp
delegate typemethod * to mycomp
</pre>
</dd>
<dt><a name="24"><b class="cmd">pragma</b> <span class="opt">?<i class="arg">options...</i>?</span></a></dt>
<dd><p>The <b class="cmd">pragma</b> statement provides control over how Snit generates a
type. It takes the following options; in each case, <i class="arg">flag</i> must
be a Boolean value recognized by Tcl, e.g., <b class="const">0</b>, <b class="const">1</b>,
<b class="const">yes</b>, <b class="const">no</b>, and so
on.</p>
<p>By setting the <b class="const">-hastypeinfo</b>, <b class="const">-hastypedestroy</b>, and
<b class="const">-hasinstances</b> pragmas to false and defining appropriate
type methods, you can create an ensemble command without any extraneous
behavior.</p>
<dl class="doctools_definitions">
<dt><b class="const">-canreplace</b> <i class="arg">flag</i></dt>
<dd><p>If false (the default) Snit will not create an instance of a
<b class="cmd">snit::type</b> that has the same name as an existing command; this
prevents subtle errors. Setting this pragma to true restores the
behavior of Snit V0.93 and earlier versions.</p></dd>
<dt><b class="const">-hastypeinfo</b> <i class="arg">flag</i></dt>
<dd><p>If true (the default), the generated type will have a type method
called <b class="cmd"><a href="../../../../index.html#info">info</a></b> that is used for type introspection; the <b class="cmd"><a href="../../../../index.html#info">info</a></b>
type method is documented below. If false, it will not.</p></dd>
<dt><b class="const">-hastypedestroy</b> <i class="arg">flag</i></dt>
<dd><p>If true (the default), the generated type will have a type method
called <b class="cmd">destroy</b> that is used to destroy the type and all of its
instances. The <b class="cmd">destroy</b> type method is documented below. If
false, it will not.</p></dd>
<dt><b class="const">-hastypemethods</b> <i class="arg">flag</i></dt>
<dd><p>If true (the default), the generated type's type command will have
subcommands (type methods) as usual. If false, the type command
will serve only to create instances of the type; the first argument
is the instance name.</p>
<p>This pragma and <b class="const">-hasinstances</b> cannot both be set false.</p></dd>
<dt><b class="const">-hasinstances</b> <i class="arg">flag</i></dt>
<dd><p>If true (the default), the generated type will have a type method
called <b class="cmd">create</b> that is used to create instances of the type,
along with a variety of instance-related features. If false, it will
not.</p>
<p>This pragma and <b class="const">-hastypemethods</b> cannot both be set false.</p></dd>
<dt><b class="const">-hasinfo</b> <i class="arg">flag</i></dt>
<dd><p>If true (the default), instances of the generated type will have
an instance method called <b class="method">info</b> that is used for
instance introspection; the <b class="method">info</b>
method is documented below. If false, it will not.</p></dd>
<dt><b class="const">-simpledispatch</b> <i class="arg">flag</i></dt>
<dd><p>This pragma is intended to make simple, heavily-used abstract
data types (e.g., stacks and queues) more efficient.</p>
<p>If false (the default), instance methods are dispatched normally. If
true, a faster dispatching scheme is used instead.
The speed comes at a price; with <b class="const">-simpledispatch yes</b> you
get the following limitations:</p>
<ul class="doctools_itemized">
<li><p>Methods cannot be delegated.</p></li>
<li><p><b class="cmd">uplevel</b> and <b class="cmd">upvar</b> do not work as expected: the
caller's scope is two levels up rather than one.</p></li>
<li><p>The option-handling methods
(<b class="cmd">cget</b>, <b class="cmd">configure</b>, and <b class="cmd">configurelist</b>) are very
slightly slower.</p></li>
</ul></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">expose</b> <i class="arg">comp</i></a></dt>
<dd></dd>
<dt><a name="26"><b class="cmd">expose</b> <i class="arg">comp</i> <b class="const">as</b> <i class="arg">method</i></a></dt>
<dd><p><b class="const">Deprecated.</b> To expose component <i class="arg">comp</i> publicly, use
<b class="cmd">component</b>'s <b class="const">-public</b> option.</p></dd>
<dt><a name="27"><b class="cmd">onconfigure</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p><b class="const">Deprecated.</b> Define <b class="cmd">option</b>'s <b class="const">-configuremethod</b>
option instead.</p>
<p>As of version 0.95, the following definitions,</p>
<pre class="doctools_example"> option -myoption
onconfigure -myoption {value} {
# Code to save the option's value
}
</pre>
<p>are implemented as follows:</p>
<pre class="doctools_example"> option -myoption -configuremethod _configure-myoption
method _configure-myoption {_option value} {
# Code to save the option's value
}
</pre>
</dd>
<dt><a name="28"><b class="cmd">oncget</b> <i class="arg">name</i> <i class="arg">body</i></a></dt>
<dd><p><b class="const">Deprecated.</b> Define <b class="cmd">option</b>'s <b class="const">-cgetmethod</b>
option instead.</p>
<p>As of version 0.95, the following definitions,</p>
<pre class="doctools_example"> option -myoption
oncget -myoption {
# Code to return the option's value
}
</pre>
<p>are implemented as follows:</p>
<pre class="doctools_example"> option -myoption -cgetmethod _cget-myoption
method _cget-myoption {_option} {
# Code to return the option's value
}
</pre>
</dd>
</dl></dd>
<dt><a name="29"><b class="cmd">snit::widget</b> <i class="arg">name</i> <i class="arg">definition</i></a></dt>
<dd><p>This command defines a Snit megawidget type with the specified
<i class="arg">name</i>. The <i class="arg">definition</i> is defined as for <b class="cmd">snit::type</b>.
A <b class="cmd">snit::widget</b> differs from a <b class="cmd">snit::type</b>
in these ways:</p>
<ul class="doctools_itemized">
<li><p>Every instance of a <b class="cmd">snit::widget</b> has an automatically-created
component called <b class="variable">hull</b>, which is normally a Tk frame widget.
Other widgets created as part of the megawidget will be created within
this widget.</p>
<p>The hull component is initially created with the requested widget
name; then Snit does some magic, renaming the hull component and
installing its own instance command in its place.
The hull component's new name is saved in an instance variable called
<b class="variable">hull</b>.</p></li>
<li><p>The name of an instance must be valid Tk window name, and the parent
window must exist.</p></li>
</ul>
<p>A <b class="cmd">snit::widget</b> definition can include any of statements allowed
in a <b class="cmd">snit::type</b> definition, and may also include the following:</p>
<dl class="doctools_definitions">
<dt><a name="30"><b class="cmd">widgetclass</b> <i class="arg">name</i></a></dt>
<dd><p>Sets the <b class="cmd">snit::widget</b>'s widget class to <i class="arg">name</i>, overriding
the default. See <span class="sectref"><a href="#subsection9">The Tk Option Database</a></span> for more
information.</p></dd>
<dt><a name="31"><b class="cmd">hulltype</b> <i class="arg">type</i></a></dt>
<dd><p>Determines the kind of widget used as the <b class="cmd">snit::widget</b>'s hull.
The <i class="arg">type</i> may be <b class="const">frame</b> (the default), <b class="const">toplevel</b>,
<b class="const">labelframe</b>; the qualified equivalents of these,
<b class="const">tk::frame</b>, <b class="const">tk::toplevel</b>, and <b class="const">tk::labelframe</b>;
or, if available, the equivalent Tile widgets:
<b class="const">ttk::frame</b>, <b class="const">ttk::toplevel</b>, and
<b class="const">ttk::labelframe</b>. In practice, any widget that supports the
<b class="const">-class</b> option can be used as a hull widget by
<b class="cmd">lappend</b>'ing its name to the variable <b class="variable">snit::hulltypes</b>.</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">snit::widgetadaptor</b> <i class="arg">name</i> <i class="arg">definition</i></a></dt>
<dd><p>This command defines a Snit megawidget type with the specified name.
It differs from <b class="cmd">snit::widget</b> in that the instance's <b class="variable">hull</b>
component is not created automatically, but is created in the
constructor and installed using the <b class="cmd">installhull</b> command. Once
the hull is installed, its instance command is renamed and replaced as
with normal <b class="cmd">snit::widget</b>s. The original command is again
accessible in the instance variable <b class="variable">hull</b>.</p>
<p>Note that in general it is not possible to change the
<em>widget class</em> of a <b class="cmd">snit::widgetadaptor</b>'s hull widget.</p>
<p>See <span class="sectref"><a href="#subsection9">The Tk Option Database</a></span> for information on how
<b class="cmd">snit::widgetadaptor</b>s interact with the option database.</p></dd>
<dt><a name="33"><b class="cmd">snit::typemethod</b> <i class="arg">type</i> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Defines a new type method (or redefines an existing type method)
for a previously existing <i class="arg">type</i>.</p></dd>
<dt><a name="34"><b class="cmd">snit::method</b> <i class="arg">type</i> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Defines a new instance method (or redefines an existing instance
method) for a previously existing <i class="arg">type</i>. Note that delegated
instance methods can't be redefined.</p></dd>
<dt><a name="35"><b class="cmd">snit::macro</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Defines a Snit macro with the specified <i class="arg">name</i>, <i class="arg">arglist</i>, and
<i class="arg">body</i>. Macros are used to define new type and widget
definition statements in terms of the statements defined in this man
page.</p>
<p>A macro is simply a Tcl proc that is defined in the slave interpreter
used to compile type and widget definitions. Thus, macros have
access to all of the type and widget definition statements. See
<span class="sectref"><a href="#subsection10">Macros and Meta-programming</a></span> for more details.</p>
<p>The macro <i class="arg">name</i> cannot be the same as any standard Tcl command,
or any Snit type or widget definition statement, e.g., you can't
redefine the <b class="cmd"><a href="../../../../index.html#method">method</a></b> or <b class="cmd">delegate</b> statements, or the
standard <b class="cmd"><a href="../../../../index.html#set">set</a></b>, <b class="cmd"><a href="../../../../index.html#list">list</a></b>, or <b class="cmd"><a href="../../../../index.html#string">string</a></b> commands.</p></dd>
<dt><a name="36"><b class="cmd">snit::compile</b> <i class="arg">which</i> <i class="arg">type</i> <i class="arg">body</i></a></dt>
<dd><p>Snit defines a type, widget, or widgetadaptor by "compiling" the
definition into a Tcl script; this script is then evaluated in the
Tcl interpreter, which actually defines the new type.</p>
<p>This command exposes the "compiler". Given a definition <i class="arg">body</i>
for the named <i class="arg">type</i>, where <i class="arg">which</i> is <b class="const">type</b>,
<b class="const">widget</b>, or <b class="const">widgetadaptor</b>, <b class="cmd">snit::compile</b> returns a list
of two elements. The first element is the fully qualified type name;
the second element is the definition script.</p>
<p><b class="cmd">snit::compile</b> is useful when additional processing
must be done on the Snit-generated code--if it must be instrumented,
for example, or run through the TclDevKit compiler. In addition, the
returned script could be saved in a ".tcl" file and used to define the
type as part of an application or library, thus saving the compilation
overhead at application start-up. Note that the
same version of Snit must be used at run-time as at compile-time.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">The Type Command</a></h3>
<p>A type or widget definition creates a type command, which is used to
create instances of the type. The type command has this form:</p>
<dl class="doctools_definitions">
<dt><a name="37"><b class="cmd">$type</b> <i class="arg">typemethod</i> <i class="arg">args</i>...</a></dt>
<dd><p>The <i class="arg">typemethod</i> can be any of the
<span class="sectref"><a href="#subsection3">Standard Type Methods</a></span> (e.g., <b class="method">create</b>),
or any type method defined in the type
definition.
The subsequent <i class="arg">args</i> depend on the specific <i class="arg">typemethod</i>
chosen.</p>
<p>The type command is most often used to create new instances of the
type; hence, the <b class="method">create</b> method is assumed if the first
argument to the type command doesn't name a valid type method, unless
the type definition includes <b class="cmd">delegate typemethod *</b> or the
<b class="const">-hasinstances</b> pragma is set to false.</p>
<p>Furthermore, if the <b class="const">-hastypemethods</b> pragma is false, then
Snit type commands can be called with no arguments at
all; in this case, the type command creates an instance with an
automatically generated name. In other words, provided that the
<b class="const">-hastypemethods</b> pragma is false and the type
has instances, the following commands are equivalent:</p>
<pre class="doctools_example">snit::type dog { ... }
set mydog [dog create %AUTO%]
set mydog [dog %AUTO%]
set mydog [dog]
</pre>
<p>This doesn't work for Snit widgets, for obvious reasons.</p>
<p><em>Snit 1.x Incompatibility:</em> In Snit 1.x, the above behavior is
available whether <b class="const">-hastypemethods</b> is true (the default) or false.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Standard Type Methods</a></h3>
<p>In addition to any type methods in the type's definition, all type and
widget commands will usually have at least the following subcommands:</p>
<dl class="doctools_definitions">
<dt><a name="38"><b class="cmd">$type</b> <b class="method">create</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i> ...?</span></a></dt>
<dd><p>Creates a new instance of the type, giving it the specified <i class="arg">name</i>
and calling the type's constructor.</p>
<p>For <b class="cmd">snit::type</b>s, if <i class="arg">name</i> is not a fully-qualified command
name, it is assumed to be a name in the namespace in which the call to
<b class="cmd">snit::type</b> appears. The method returns the fully-qualified
instance name.</p>
<p>For <b class="cmd">snit::widget</b>s and <b class="cmd">snit::widgetadaptor</b>s, <i class="arg">name</i>
must be a valid widget name; the method returns the widget name.</p>
<p>So long as <i class="arg">name</i> does not conflict with any defined type method
name the <b class="method">create</b> keyword may be omitted, unless
the type definition includes <b class="cmd">delegate typemethod *</b> or the
<b class="const">-hasinstances</b> pragma is set to false.</p>
<p>If the <i class="arg">name</i> includes the string <b class="const">%AUTO%</b>, it will be
replaced with the string <b class="const">$type$counter</b> where <b class="const">$type</b> is
the type name and <b class="const">$counter</b> is a counter that increments each
time <b class="const">%AUTO%</b> is used for this type.</p>
<p>By default, any arguments following the <i class="arg">name</i> will be a list of
<i class="arg">option</i> names and their <i class="arg">value</i>s; however, a type's
constructor can specify a different argument list.</p>
<p>As of Snit V0.95, <b class="method">create</b> will throw an error if the <i class="arg">name</i>
is the same as any existing command--note that this was always true
for <b class="cmd">snit::widget</b>s and <b class="cmd">snit::widgetadaptor</b>s. You can
restore the previous behavior using the <b class="const">-canreplace</b> pragma.</p></dd>
<dt><a name="39"><b class="cmd">$type</b> <b class="method">info typevars</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the type's type variables (excluding Snit internal
variables); all variable names are fully-qualified.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p></dd>
<dt><a name="40"><b class="cmd">$type</b> <b class="method">info typemethods</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the names of the type's type methods.
If the type has hierarchical
type methods, whether locally-defined or delegated, only the first
word of each will be included in the list.</p>
<p>If the type
definition includes <b class="cmd">delegate typemethod *</b>, the list will
include only the names of those implicitly delegated type methods
that have been called at least once and are still in the type method cache.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p></dd>
<dt><a name="41"><b class="cmd">$type</b> <b class="method">info args</b> <i class="arg">method</i></a></dt>
<dd><p>Returns a list containing the names of the arguments to the type's
<i class="arg">method</i>, in order. This method cannot be applied to delegated
type methods.</p></dd>
<dt><a name="42"><b class="cmd">$type</b> <b class="method">info body</b> <i class="arg">method</i></a></dt>
<dd><p>Returns the body of typemethod <i class="arg">method</i>. This method cannot be
applied to delegated type methods.</p></dd>
<dt><a name="43"><b class="cmd">$type</b> <b class="method">info default</b> <i class="arg">method</i> <i class="arg">aname</i> <i class="arg">varname</i></a></dt>
<dd><p>Returns a boolean value indicating whether the argument <i class="arg">aname</i> of
the type's <i class="arg">method</i> has a default value (<b class="const">true</b>) or not
(<b class="const">false</b>). If the argument has a default its value is placed into
the variable <i class="arg">varname</i>.</p></dd>
<dt><a name="44"><b class="cmd">$type</b> <b class="method">info instances</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the type's instances. For <b class="cmd">snit::type</b>s, it
will be a list of fully-qualified instance names;
for <b class="cmd">snit::widget</b>s, it will be a list of Tk widget names.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p>
<p><em>Snit 1.x Incompatibility:</em> In Snit 1.x, the full multi-word
names of hierarchical type methods are included in the return value.</p></dd>
<dt><a name="45"><b class="cmd">$type</b> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the type's instances, the type's namespace, and the type
command itself.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">The Instance Command</a></h3>
<p>A Snit type or widget's <b class="method">create</b> type method creates objects of
the type; each object has a unique name that is also a Tcl command.
This command is used to access the object's methods and data, and has
this form:</p>
<dl class="doctools_definitions">
<dt><a name="46"><b class="cmd">$object</b> <i class="arg">method</i> <i class="arg">args...</i></a></dt>
<dd><p>The <i class="arg">method</i> can be any of the
<span class="sectref"><a href="#subsection5">Standard Instance Methods</a></span>, or any instance method
defined in the type definition.
The subsequent <i class="arg">args</i> depend on the specific <i class="arg">method</i> chosen.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Standard Instance Methods</a></h3>
<p>In addition to any delegated or locally-defined instance methods in
the type's definition, all Snit objects will have at least the
following subcommands:</p>
<dl class="doctools_definitions">
<dt><a name="47"><b class="cmd">$object</b> <b class="method">configure</b> <span class="opt">?<i class="arg">option</i>?</span> <span class="opt">?<i class="arg">value</i>?</span> ...</a></dt>
<dd><p>Assigns new values to one or more options. If called with one
argument, an <i class="arg">option</i> name, returns a list describing the option,
as Tk widgets do; if called with no arguments, returns a list of lists
describing all options, as Tk widgets do.</p>
<p>Warning: This information will be available for delegated options only
if the component to which they are delegated has a <b class="method">configure</b>
method that returns this same kind of information.</p>
<p>Note: Snit defines this method only if the type has at least one
option.</p></dd>
<dt><a name="48"><b class="cmd">$object</b> <b class="method">configurelist</b> <i class="arg">optionlist</i></a></dt>
<dd><p>Like <b class="method">configure</b>, but takes one argument, a list of options and
their values. It's mostly useful in the type constructor, but can be
used anywhere.</p>
<p>Note: Snit defines this method only if the type has at least one
option.</p></dd>
<dt><a name="49"><b class="cmd">$object</b> <b class="method">cget</b> <i class="arg">option</i></a></dt>
<dd><p>Returns the option's value.</p>
<p>Note: Snit defines this method only if the type has at least one
option.</p></dd>
<dt><a name="50"><b class="cmd">$object</b> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the object, calling the <b class="cmd">destructor</b> and freeing all
related memory.</p>
<p><em>Note:</em>
The <b class="method">destroy</b> method isn't defined for <b class="cmd">snit::widget</b> or
<b class="cmd">snit::widgetadaptor</b> objects; instances of these are destroyed by
calling <b class="package"><a href="../../../../index.html#tk">Tk</a></b>'s <b class="cmd">destroy</b> command, just as normal
widgets are.</p></dd>
<dt><a name="51"><b class="cmd">$object</b> <b class="method">info type</b></a></dt>
<dd><p>Returns the instance's type.</p></dd>
<dt><a name="52"><b class="cmd">$object</b> <b class="method">info vars</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the object's instance variables (excluding Snit
internal variables). The names are fully qualified.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p></dd>
<dt><a name="53"><b class="cmd">$object</b> <b class="method">info typevars</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the object's type's type variables (excluding Snit
internal variables). The names are fully qualified.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p></dd>
<dt><a name="54"><b class="cmd">$object</b> <b class="method">info typemethods</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the names of the type's type methods.
If the type has hierarchical
type methods, whether locally-defined or delegated, only the first
word of each will be included in the list.</p>
<p>If the type
definition includes <b class="cmd">delegate typemethod *</b>, the list will
include only the names of those implicitly delegated type methods
that have been called at least once and are still in the type method cache.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p>
<p><em>Snit 1.x Incompatibility:</em> In Snit 1.x, the full multi-word
names of hierarchical type methods are included in the return value.</p></dd>
<dt><a name="55"><b class="cmd">$object</b> <b class="method">info options</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the object's option names. This always includes
local options and explicitly delegated options. If unknown options
are delegated as well, and if the component to which they are
delegated responds to <b class="cmd">$object configure</b> like Tk widgets do,
then the result will include all possible unknown options that can
be delegated to the component.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p>
<p>Note that the return value might be different for different instances
of the same type, if component object types can vary from one instance
to another.</p></dd>
<dt><a name="56"><b class="cmd">$object</b> <b class="method">info methods</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of the names of the instance's methods.
If the type has hierarchical methods, whether locally-defined or
delegated, only the first word of each will be included in the list.</p>
<p>If the type
definition includes <b class="cmd">delegate method *</b>, the list will
include only the names of those implicitly delegated methods that have
been called at least once and are still in the method cache.</p>
<p>If <i class="arg">pattern</i> is given, it's used as a <b class="cmd">string match</b>
pattern; only names that match the pattern are returned.</p>
<p><em>Snit 1.x Incompatibility:</em> In Snit 1.x, the full multi-word
names of hierarchical type methods are included in the return value.</p></dd>
<dt><a name="57"><b class="cmd">$object</b> <b class="method">info args</b> <i class="arg">method</i></a></dt>
<dd><p>Returns a list containing the names of the arguments to the instance's
<i class="arg">method</i>, in order. This method cannot be applied to delegated methods.</p></dd>
<dt><a name="58"><b class="cmd">$object</b> <b class="method">info body</b> <i class="arg">method</i></a></dt>
<dd><p>Returns the body of the instance's method <i class="arg">method</i>. This method
cannot be applied to delegated methods.</p></dd>
<dt><a name="59"><b class="cmd">$object</b> <b class="method">info default</b> <i class="arg">method</i> <i class="arg">aname</i> <i class="arg">varname</i></a></dt>
<dd><p>Returns a boolean value indicating whether the argument <i class="arg">aname</i> of
the instance's <i class="arg">method</i> has a default value (<b class="const">true</b>) or not
(<b class="const">false</b>). If the argument has a default its value is placed into
the variable <i class="arg">varname</i>.</p></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Commands for use in Object Code</a></h3>
<p>Snit defines the following commands for use in your object code:
that is, for use in type methods, instance methods, constructors,
destructors, onconfigure handlers, oncget handlers, and procs.
They do not reside in the ::snit:: namespace; instead, they are
created with the type, and can be used without qualification.</p>
<dl class="doctools_definitions">
<dt><a name="60"><b class="cmd">mymethod</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args...</i>?</span></a></dt>
<dd><p>The <b class="cmd">mymethod</b> command is used for formatting callback commands to
be passed to other objects. It returns a command that when called
will invoke method <i class="arg">name</i> with the specified arguments, plus of
course any arguments added by the caller. In other words, both of the
following commands will cause the object's
<b class="method">dosomething</b> method to be called when the <b class="cmd">$button</b> is pressed:</p>
<pre class="doctools_example"> $button configure -command [list $self dosomething myargument]
$button configure -command [mymethod dosomething myargument]
</pre>
<p>The chief distinction between the two is that the latter form will not
break if the object's command is renamed.</p></dd>
<dt><a name="61"><b class="cmd">mytypemethod</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args...</i>?</span></a></dt>
<dd><p>The <b class="cmd">mytypemethod</b> command is used for formatting callback commands to
be passed to other objects. It returns a command that when called
will invoke type method <i class="arg">name</i> with the specified arguments, plus of
course any arguments added by the caller. In other words, both of the
following commands will cause the object's <b class="method">dosomething</b> type method
to be called when <b class="cmd">$button</b> is pressed:</p>
<pre class="doctools_example"> $button configure -command [list $type dosomething myargument]
$button configure -command [mytypemethod dosomething myargument]
</pre>
<p>Type commands cannot be renamed, so in practice there's little
difference between the two forms. <b class="cmd">mytypemethod</b> is provided for
parallelism with <b class="cmd">mymethod</b>.</p></dd>
<dt><a name="62"><b class="cmd">myproc</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args...</i>?</span></a></dt>
<dd><p>The <b class="cmd">myproc</b> command is used for formatting callback commands to
be passed to other objects. It returns a command that when called
will invoke the type proc <i class="arg">name</i> with the specified arguments, plus of
course any arguments added by the caller. In other words, both of the
following commands will cause the object's <b class="method">dosomething</b> proc
to be called when <b class="cmd">$button</b> is pressed:</p>
<pre class="doctools_example"> $button configure -command [list ${type}::dosomething myargument]
$button configure -command [myproc dosomething myargument]
</pre>
</dd>
<dt><a name="63"><b class="cmd">myvar</b> <i class="arg">name</i></a></dt>
<dd><p>Given an instance variable name, returns the fully qualified name.
Use this if you're passing the variable to some other object, e.g., as
a <b class="option">-textvariable</b> to a Tk label widget.</p></dd>
<dt><a name="64"><b class="cmd">mytypevar</b> <i class="arg">name</i></a></dt>
<dd><p>Given an type variable name, returns the fully qualified name. Use
this if you're passing the variable to some other object, e.g., as a
<b class="option">-textvariable</b> to a Tk label widget.</p></dd>
<dt><a name="65"><b class="cmd">from</b> <i class="arg">argvName</i> <i class="arg">option</i> <span class="opt">?<i class="arg">defvalue</i>?</span></a></dt>
<dd><p>The <b class="cmd">from</b> command plucks an option value from a list of options
and their values, such as is passed into a type's <b class="cmd">constructor</b>.
<i class="arg">argvName</i> must be the name of a variable containing such a list;
<i class="arg">option</i> is the name of the specific option.</p>
<p><b class="cmd">from</b> looks for <i class="arg">option</i> in the option list. If it is found,
it and its value are removed from the list, and the value is returned.
If <i class="arg">option</i> doesn't appear in the list, then the <i class="arg">defvalue</i> is
returned.
If the option is locally-defined option, and <i class="arg">defvalue</i> is
not specified, then the option's default value as specified in the
type definition will be returned instead.</p></dd>
<dt><a name="66"><b class="cmd">install</b> <i class="arg">compName</i> <b class="const">using</b> <i class="arg">objType</i> <i class="arg">objName</i> <i class="arg">args...</i></a></dt>
<dd><p>Creates a new object of type <i class="arg">objType</i> called <i class="arg">objName</i>
and installs it as component <i class="arg">compName</i>,
as described in <span class="sectref"><a href="#subsection7">Components and Delegation</a></span>. Any additional
<i class="arg">args...</i> are passed along with the name to the <i class="arg">objType</i>
command.
If this is a <b class="cmd">snit::type</b>, then the following two commands are
equivalent:</p>
<pre class="doctools_example"> install myComp using myObjType $self.myComp args...
set myComp [myObjType $self.myComp args...]
</pre>
<p>Note that whichever method is used, <i class="arg">compName</i> must still be
declared in the type definition using <b class="cmd">component</b>, or must be
referenced in at least one <b class="cmd">delegate</b> statement.</p>
<p>If this is a <b class="cmd">snit::widget</b> or <b class="cmd">snit::widgetadaptor</b>, and if
options have been delegated to component <i class="arg">compName</i>, then those
options will receive default values from the Tk option database. Note
that it doesn't matter whether the component to be installed is a
widget or not. See <span class="sectref"><a href="#subsection9">The Tk Option Database</a></span> for more
information.</p>
<p><b class="cmd">install</b> cannot be used to install type components; just assign
the type component's command name to the type component's variable
instead.</p></dd>
<dt><a name="67"><b class="cmd">installhull</b> <b class="const">using</b> <i class="arg">widgetType</i> <i class="arg">args...</i></a></dt>
<dd></dd>
<dt><a name="68"><b class="cmd">installhull</b> <i class="arg">name</i></a></dt>
<dd><p>The constructor of a <b class="cmd">snit::widgetadaptor</b> must create a widget to
be the object's hull component; the widget is installed as the hull
component using this command. Note that the installed widget's name
must be <b class="const">$win</b>.
This command has two forms.</p>
<p>The first form specifies the <i class="arg">widgetType</i> and the <i class="arg">args...</i>
(that is, the hardcoded option list) to use in creating the hull.
Given this form, <b class="cmd">installhull</b> creates the hull widget, and
initializes any options delegated to the hull from the Tk option
database.</p>
<p>In the second form, the hull widget has already been created; note
that its name must be "$win". In this case, the Tk option database is
<em>not</em> queried for any options delegated to the hull.
The longer form is preferred; however, the shorter form allows the
programmer to adapt a widget created elsewhere, which is sometimes
useful. For example, it can be used to adapt a "page" widget created
by a <b class="package">BWidgets</b> tabbed notebook or pages manager widget.</p>
<p>See <span class="sectref"><a href="#subsection9">The Tk Option Database</a></span> for more information
about <b class="cmd">snit::widgetadaptor</b>s and the option database.</p></dd>
<dt><a name="69"><b class="cmd">variable</b> <i class="arg">name</i></a></dt>
<dd><p>Normally, instance variables are defined in the type definition along
with the options, methods, and so forth; such instance variables are
automatically visible in all instance code (e.g., method bodies). However,
instance code can use the <b class="cmd">variable</b> command to declare instance variables
that don't appear in the type definition, and also to bring variables
from other namespaces into scope in the usual way.</p>
<p>It's generally clearest to define all instance variables in the type
definition, and omit declaring them in methods and so forth.</p>
<p>Note that this is an instance-specific version of the standard Tcl
<b class="cmd">::variable</b> command.</p></dd>
<dt><a name="70"><b class="cmd">typevariable</b> <i class="arg">name</i></a></dt>
<dd><p>Normally, type variables are defined in the type definition, along
with the instance variables; such type variables are automatically
visible in all of the type's code. However, type methods, instance
methods and so forth can use <b class="cmd">typevariable</b> to declare type
variables that don't appear in the type definition.</p>
<p>It's generally clearest to declare all type variables in the type
definition, and omit declaring them in methods, type methods, etc.</p></dd>
<dt><a name="71"><b class="cmd">varname</b> <i class="arg">name</i></a></dt>
<dd><p><b class="const">Deprecated.</b> Use <b class="cmd">myvar</b> instead.</p>
<p>Given an instance variable name, returns the fully qualified name.
Use this if you're passing the variable to some other object, e.g., as
a <b class="option">-textvariable</b> to a Tk label widget.</p></dd>
<dt><a name="72"><b class="cmd">typevarname</b> <i class="arg">name</i></a></dt>
<dd><p><b class="const">Deprecated.</b> Use <b class="cmd">mytypevar</b> instead.</p>
<p>Given a type variable name, returns the fully qualified name. Use
this if you're passing the type variable to some other object, e.g., as a
<b class="option">-textvariable</b> to a Tk label widget.</p></dd>
<dt><a name="73"><b class="cmd">codename</b> <i class="arg">name</i></a></dt>
<dd><p><b class="const">Deprecated.</b> Use <b class="cmd">myproc</b> instead.
Given the name of a proc (but not a type or instance method), returns
the fully-qualified command name, suitable for passing as a callback.</p></dd>
</dl>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Components and Delegation</a></h3>
<p>When an object includes other objects, as when a toolbar contains
buttons or a GUI object contains an object that references a database,
the included object is called a component. The standard way to handle
component objects owned by a Snit object is to declare them using
<b class="cmd">component</b>, which creates a component instance variable.
In the following example, a <b class="cmd">dog</b> object has a
<b class="cmd">tail</b> object:</p>
<pre class="doctools_example"> snit::type dog {
component mytail
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
method wag {} {
$mytail wag
}
}
snit::type tail {
option -length 5
option -partof
method wag {} { return "Wag, wag, wag."}
}
</pre>
<p>Because the <b class="cmd">tail</b> object's name is stored in an instance
variable, it's easily accessible in any method.</p>
<p>The <b class="cmd">install</b> command provides an alternate way
to create and install the component:</p>
<pre class="doctools_example"> snit::type dog {
component mytail
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
method wag {} {
$mytail wag
}
}
</pre>
<p>For <b class="cmd">snit::type</b>s, the two methods are equivalent; for
<b class="cmd">snit::widget</b>s and <b class="cmd">snit::widgetadaptor</b>s, the <b class="cmd">install</b>
command properly initializes the widget's options by querying
<span class="sectref"><a href="#subsection9">The Tk Option Database</a></span>.</p>
<p>In the above examples, the <b class="cmd">dog</b> object's <b class="method">wag</b> method
simply calls the <b class="cmd">tail</b> component's <b class="method">wag</b> method. In OO
jargon, this is called delegation. Snit provides an easier way to do
this:</p>
<pre class="doctools_example"> snit::type dog {
delegate method wag to mytail
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
</pre>
<p>The <b class="cmd">delegate</b> statement in the type definition implicitly defines
the instance variable <b class="variable">mytail</b> to hold the component's name
(though it's good form to use <b class="cmd">component</b> to declare it explicitly); it
also defines the <b class="cmd">dog</b> object's <b class="method">wag</b> method, delegating it
to the <b class="variable">mytail</b> component.</p>
<p>If desired, all otherwise unknown methods can be delegated to a
specific component:</p>
<pre class="doctools_example">
snit::type dog {
delegate method * to mytail
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
method bark { return "Bark, bark, bark!" }
}
</pre>
<p>In this case, a <b class="cmd">dog</b> object will handle its own <b class="method">bark</b>
method; but <b class="method">wag</b> will be passed along to <b class="cmd">mytail</b>. Any
other method, being recognized by neither <b class="cmd">dog</b> nor <b class="cmd">tail</b>,
will simply raise an error.</p>
<p>Option delegation is similar to method delegation, except for the
interactions with the Tk option database; this is described in
<span class="sectref"><a href="#subsection9">The Tk Option Database</a></span>.</p>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Type Components and Delegation</a></h3>
<p>The relationship between type components and instance components is
identical to that between type variables and instance variables, and
that between type methods and instance methods. Just as an instance
component is an instance variable that holds the name of a command, so
a type component is a type variable that holds the name of a command.
In essence, a type component is a component that's shared by every
instance of the type.</p>
<p>Just as <b class="cmd">delegate method</b> can be used to delegate methods to
instance components, as described in
<span class="sectref"><a href="#subsection7">Components and Delegation</a></span>, so <b class="cmd">delegate typemethod</b>
can be used to delegate type methods to type components.</p>
<p>Note also that as of Snit 0.95 <b class="cmd">delegate method</b> can delegate
methods to both instance components and type components.</p>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">The Tk Option Database</a></h3>
<p>This section describes how Snit interacts with the Tk option database,
and assumes the reader has a working knowledge of the option database
and its uses. The book <em>Practical Programming in Tcl and Tk</em>
by Welch et al has a good introduction to the option database, as does
<em>Effective Tcl/Tk Programming</em>.</p>
<p>Snit is implemented so that most of the time it will simply do the
right thing with respect to the option database, provided that the
widget developer does the right thing by Snit. The body of this
section goes into great deal about what Snit requires. The following
is a brief statement of the requirements, for reference.</p>
<ul class="doctools_itemized">
<li><p>If the <b class="cmd">snit::widget</b>'s default widget class is not what is desired, set it
explicitly using <b class="cmd">widgetclass</b> in the widget definition.</p></li>
<li><p>When defining or delegating options, specify the resource and class
names explicitly when if the defaults aren't what you want.</p></li>
<li><p>Use <b class="cmd">installhull using</b> to install the hull for
<b class="cmd">snit::widgetadaptor</b>s.</p></li>
<li><p>Use <b class="cmd">install</b> to install all other components.</p></li>
</ul>
<p>The interaction of Tk widgets with the option database is a complex
thing; the interaction of Snit with the option database is even more
so, and repays attention to detail.</p>
<p><b class="const">Setting the widget class:</b> Every Tk widget has a widget class.
For Tk widgets, the widget class name is the just the widget type name
with an initial capital letter, e.g., the widget class for
<b class="cmd">button</b> widgets is "Button".</p>
<p>Similarly, the widget class of a <b class="cmd">snit::widget</b> defaults to the
unqualified type name with the first letter capitalized. For example,
the widget class of</p>
<pre class="doctools_example"> snit::widget ::mylibrary::scrolledText { ... }</pre>
<p>is "ScrolledText". The widget class can also be set explicitly using
the <b class="cmd">widgetclass</b> statement within the <b class="cmd">snit::widget</b>
definition.</p>
<p>Any widget can be used as the <b class="cmd">hulltype</b> provided that it supports
the <b class="const">-class</b> option for changing its widget class name. See
the discussion of the <b class="cmd">hulltype</b> command, above. The user may pass
<b class="const">-class</b> to the widget at instantion.</p>
<p>The widget class of a <b class="cmd">snit::widgetadaptor</b> is just the widget
class of its hull widget; this cannot be changed unless the hull
widget supports <b class="const">-class</b>, in which case it will
usually make more sense to use <b class="cmd">snit::widget</b> rather than
<b class="cmd">snit::widgetadaptor</b>.</p>
<p><b class="const">Setting option resource names and classes:</b> In Tk, every
option has three names: the option name, the resource name, and the
class name. The option name begins with a hyphen and is all lowercase;
it's used when creating widgets, and with the <b class="cmd">configure</b> and
<b class="cmd">cget</b> commands.</p>
<p>The resource and class names are used to initialize option default
values by querying the Tk option database. The resource name is
usually just the option name minus the hyphen, but may contain
uppercase letters at word boundaries; the class name is usually just
the resource name with an initial capital, but not always. For
example, here are the option, resource, and class names for several
<b class="cmd"><a href="../../../../index.html#text">text</a></b> widget options:</p>
<pre class="doctools_example"> -background background Background
-borderwidth borderWidth BorderWidth
-insertborderwidth insertBorderWidth BorderWidth
-padx padX Pad
</pre>
<p>As is easily seen, sometimes the resource and class names can be
inferred from the option name, but not always.</p>
<p>Snit options also have a resource name and a class name. By default,
these names follow the rule given above: the resource name is the
option name without the hyphen, and the class name is the resource
name with an initial capital. This is true for both locally-defined
options and explicitly delegated options:</p>
<pre class="doctools_example"> snit::widget mywidget {
option -background
delegate option -borderwidth to hull
delegate option * to text
# ...
}
</pre>
<p>In this case, the widget class name is "Mywidget". The widget has the
following options: <b class="option">-background</b>, which is locally defined, and
<b class="option">-borderwidth</b>, which is explicitly delegated; all other widgets are
delegated to a component called "text", which is probably a Tk
<b class="cmd"><a href="../../../../index.html#text">text</a></b> widget. If so, <b class="cmd">mywidget</b> has all the same options as
a <b class="cmd"><a href="../../../../index.html#text">text</a></b> widget. The option, resource, and class names are as
follows:</p>
<pre class="doctools_example"> -background background Background
-borderwidth borderwidth Borderwidth
-padx padX Pad
</pre>
<p>Note that the locally defined option, <b class="option">-background</b>, happens to have
the same three names as the standard Tk <b class="option">-background</b> option; and
<b class="option">-pad</b>, which is delegated implicitly to the <b class="variable">text</b>
component, has the
same three names for <b class="cmd">mywidget</b> as it does for the <b class="cmd"><a href="../../../../index.html#text">text</a></b>
widget. <b class="option">-borderwidth</b>, on the other hand, has different resource and
class names than usual, because the internal word "width" isn't
capitalized. For consistency, it should be; this is done as follows:</p>
<pre class="doctools_example"> snit::widget mywidget {
option -background
delegate option {-borderwidth borderWidth} to hull
delegate option * to text
# ...
}
</pre>
<p>The class name will default to "BorderWidth", as expected.</p>
<p>Suppose, however, that <b class="cmd">mywidget</b> also delegated
<b class="option">-padx</b> and
<b class="option">-pady</b> to the hull. In this case, both the resource name and the
class name must be specified explicitly:</p>
<pre class="doctools_example"> snit::widget mywidget {
option -background
delegate option {-borderwidth borderWidth} to hull
delegate option {-padx padX Pad} to hull
delegate option {-pady padY Pad} to hull
delegate option * to text
# ...
}
</pre>
<p><b class="const">Querying the option database:</b> If you set your widgetclass and
option names as described above, Snit will query the option database
when each instance is created, and will generally do the right thing
when it comes to querying the option database. The remainder of this
section goes into the gory details.</p>
<p><b class="const">Initializing locally defined options:</b>
When an instance of a snit::widget is created, its locally defined
options are initialized as follows: each option's resource and class
names are used to query the Tk option database. If the result is
non-empty, it is used as the option's default; otherwise, the default
hardcoded in the type definition is used. In either case, the default
can be overridden by the caller. For example,</p>
<pre class="doctools_example"> option add *Mywidget.texture pebbled
snit::widget mywidget {
option -texture smooth
# ...
}
mywidget .mywidget -texture greasy
</pre>
<p>Here, <b class="option">-texture</b> would normally default to "smooth", but because of
the entry added to the option database it defaults to "pebbled".
However, the caller has explicitly overridden the default, and so the
new widget will be "greasy".</p>
<p><b class="const">Initializing options delegated to the hull:</b>
A <b class="cmd">snit::widget</b>'s hull is a widget, and given that its class has
been set it is expected to query the option database for itself. The
only exception concerns options that are delegated to it with a
different name. Consider the following code:</p>
<pre class="doctools_example"> option add *Mywidget.borderWidth 5
option add *Mywidget.relief sunken
option add *Mywidget.hullbackground red
option add *Mywidget.background green
snit::widget mywidget {
delegate option -borderwidth to hull
delegate option -hullbackground to hull as -background
delegate option * to hull
# ...
}
mywidget .mywidget
set A [.mywidget cget -relief]
set B [.mywidget cget -hullbackground]
set C [.mywidget cget -background]
set D [.mywidget cget -borderwidth]
</pre>
<p>The question is, what are the values of variables A, B, C and D?</p>
<p>The value of A is "sunken". The hull is a Tk frame that has been
given the widget class "Mywidget"; it will automatically query the
option database and pick up this value. Since the <b class="option">-relief</b>
option is implicitly delegated to the hull, Snit takes no action.</p>
<p>The value of B is "red". The hull will automatically pick up the
value "green" for its <b class="option">-background</b> option, just as it picked up the
<b class="option">-relief</b> value. However, Snit knows that
<b class="option">-hullbackground</b> is mapped to
the hull's <b class="option">-background</b> option; hence, it queries the option database
for <b class="option">-hullbackground</b> and gets "red" and updates the hull
accordingly.</p>
<p>The value of C is also "red", because <b class="option">-background</b> is implicitly
delegated to the hull; thus, retrieving it is the same as retrieving
<b class="option">-hullbackground</b>. Note that this case is unusual; in practice,
<b class="option">-background</b> would probably be explicitly delegated to some other
component.</p>
<p>The value of D is "5", but not for the reason you think. Note that as
it is defined above, the resource name for <b class="option">-borderwidth</b>
defaults to "borderwidth", whereas the option database entry is
"borderWidth". As with <b class="option">-relief</b>, the hull picks up its
own <b class="option">-borderwidth</b> option before Snit does anything. Because the
option is delegated under its own name, Snit assumes that the correct
thing has happened, and doesn't worry about it any further.</p>
<p>For <b class="cmd">snit::widgetadaptor</b>s, the case is somewhat altered. Widget
adaptors retain the widget class of their hull, and the hull is not
created automatically by Snit. Instead, the <b class="cmd">snit::widgetadaptor</b>
must call <b class="cmd">installhull</b> in its constructor. The normal way to do
this is as follows:</p>
<pre class="doctools_example"> snit::widgetadaptor mywidget {
# ...
constructor {args} {
# ...
installhull using text -foreground white
#
}
#...
}
</pre>
<p>In this case, the <b class="cmd">installhull</b> command will create the hull using
a command like this:</p>
<pre class="doctools_example"> set hull [text $win -foreground white]
</pre>
<p>The hull is a <b class="cmd"><a href="../../../../index.html#text">text</a></b> widget, so its widget class is "Text". Just
as with <b class="cmd">snit::widget</b> hulls, Snit assumes that it will pick up
all of its normal option values automatically; options delegated from
a different name are initialized from the option database in the same
way.</p>
<p><b class="const">Initializing options delegated to other components:</b>
Non-hull components are matched against the option database in two
ways. First, a component widget remains a widget still, and therefore
is initialized from the option database in the usual way.
Second, the option database is queried for all options delegated to
the component, and the component is initialized accordingly--provided
that the <b class="cmd">install</b> command is used to create it.</p>
<p>Before option database support was added to Snit, the usual way to
create a component was to simply create it in the constructor and
assign its command name to the component variable:</p>
<pre class="doctools_example"> snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
set myComp [text $win.text -foreground black]
}
}
</pre>
<p>The drawback of this method is that Snit has no opportunity to
initialize the component properly. Hence, the following approach is
now used:</p>
<pre class="doctools_example"> snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
install myComp using text $win.text -foreground black
}
}
</pre>
<p>The <b class="cmd">install</b> command does the following:</p>
<ul class="doctools_itemized">
<li><p>Builds a list of the options explicitly included in the <b class="cmd">install</b>
command -- in this case, <b class="option">-foreground</b>.</p></li>
<li><p>Queries the option database for all options delegated explicitly to
the named component.</p></li>
<li><p>Creates the component using the specified command, after inserting
into it a list of options and values read from the option database.
Thus, the explicitly included options (<b class="option">-foreground</b>) will override
anything read from the option database.</p></li>
<li><p>If the widget definition implicitly delegated options to the component
using <b class="cmd">delegate option *</b>, then Snit calls the newly created
component's <b class="cmd">configure</b> method to receive a list of all of the
component's options. From this Snit builds a list of options
implicitly delegated to the component that were not explicitly
included in the <b class="cmd">install</b> command. For all such options, Snit
queries the option database and configures the component accordingly.</p></li>
</ul>
<p><b class="const">Non-widget components:</b> The option database is never queried
for <b class="cmd">snit::type</b>s, since it can only be queried given a Tk widget
name.
However, <b class="cmd">snit::widget</b>s can have non-widget components. And if
options are delegated to those components, and if the <b class="cmd">install</b>
command is used to install those components, then they will be
initialized from the option database just as widget components are.</p>
</div>
<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Macros and Meta-programming</a></h3>
<p>The <b class="cmd">snit::macro</b> command enables a certain amount of
meta-programming with Snit classes. For example, suppose you like to
define properties: instance variables that have set/get methods. Your
code might look like this:</p>
<pre class="doctools_example"> snit::type dog {
variable mood happy
method getmood {} {
return $mood
}
method setmood {newmood} {
set mood $newmood
}
}
</pre>
<p>That's nine lines of text per property. Or, you could define the
following <b class="cmd">snit::macro</b>:</p>
<pre class="doctools_example"> snit::macro property {name initValue} {
variable $name $initValue
method get$name {} "return $name"
method set$name {value} "set $name \$value"
}
</pre>
<p>Note that a <b class="cmd">snit::macro</b> is just a normal Tcl proc defined in
the slave interpreter used to compile type and widget definitions; as
a result, it has access to all the commands used to define types and
widgets.</p>
<p>Given this new macro, you can define a property in one line of code:</p>
<pre class="doctools_example"> snit::type dog {
property mood happy
}
</pre>
<p>Within a macro, the commands <b class="cmd">variable</b> and <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> refer to
the Snit type-definition commands, not the standard Tcl commands. To
get the standard Tcl commands, use <b class="cmd">_variable</b> and <b class="cmd">_proc</b>.</p>
<p>Because a single slave interpreter is used for compiling all Snit
types and widgets in the application, there's the possibility of macro
name collisions. If you're writing a reuseable package using Snit,
and you use some <b class="cmd">snit::macro</b>s, define them in your package
namespace:</p>
<pre class="doctools_example"> snit::macro mypkg::property {name initValue} { ... }
snit::type dog {
mypkg::property mood happy
}
</pre>
<p>This leaves the global namespace open for application authors.</p>
</div>
<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Validation Types</a></h3>
<p>A validation type is an object that can be used to validate
Tcl values of a particular kind. For example,
<b class="cmd">snit::integer</b> is used to validate that a Tcl value is
an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example"> snit::integer validate 5 ;# Does nothing
snit::integer validate 5.0 ;# Throws an error (not an integer!)
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on success,
and throw the <b class="cmd">-errorcode</b> INVALID on error.</p>
<p>Snit defines a family of validation types, all of which are
implemented as <b class="cmd">snit::type</b>'s. They can be used as is;
in addition, their instances serve as parameterized
subtypes. For example, a probability is a number between 0.0 and 1.0
inclusive:</p>
<pre class="doctools_example"> snit::double probability -min 0.0 -max 1.0
</pre>
<p>The example above creates an instance of <b class="cmd">snit::double</b>--a
validation subtype--called
<b class="cmd">probability</b>, which can be used to validate probability values:</p>
<pre class="doctools_example"> probability validate 0.5 ;# Does nothing
probability validate 7.9 ;# Throws an error
</pre>
<p>Validation subtypes can be defined explicitly, as in the above
example; when a locally-defined option's <b class="const">-type</b> is specified,
they may also be created on the fly:</p>
<pre class="doctools_example"> snit::enum ::dog::breed -values {mutt retriever sheepdog}
snit::type dog {
# Define subtypes on the fly...
option -breed -type {
snit::enum -values {mutt retriever sheepdog}
}
# Or use predefined subtypes...
option -breed -type ::dog::breed
}
</pre>
<p>Any object that has a <b class="method">validate</b> method with the semantics
described above can be used as a validation type; see
<span class="sectref"><a href="#subsection12">Defining Validation Types</a></span> for information on how to define
new ones.</p>
<p>Snit defines the following validation types:</p>
<dl class="doctools_definitions">
<dt><a name="74"><b class="cmd">snit::boolean</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="75"><b class="cmd">snit::boolean</b> <i class="arg">name</i></a></dt>
<dd><p>Validates Tcl boolean values: 1, 0, <b class="const">on</b>, <b class="const">off</b>,
<b class="const">yes</b>, <b class="const">no</b>, <b class="const">true</b>, <b class="const">false</b>.
It's possible to define subtypes--that is, instances--of
<b class="cmd">snit::boolean</b>, but as it has no options there's no reason to do
so.</p></dd>
<dt><a name="76"><b class="cmd">snit::double</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="77"><b class="cmd">snit::double</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p>Validates floating-point values. Subtypes may be created with the
following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-min</b> <i class="arg">min</i></dt>
<dd><p>Specifies a floating-point minimum bound; a value is invalid if it is strictly
less than <i class="arg">min</i>.</p></dd>
<dt><b class="const">-max</b> <i class="arg">max</i></dt>
<dd><p>Specifies a floating-point maximum bound; a value is invalid if it is strictly
greater than <i class="arg">max</i>.</p></dd>
</dl></dd>
<dt><a name="78"><b class="cmd">snit::enum</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="79"><b class="cmd">snit::enum</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p>Validates that a value comes from an enumerated list. The base
type is of little use by itself, as only subtypes actually have
an enumerated list to validate against. Subtypes may be created
with the following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-values</b> <i class="arg">list</i></dt>
<dd><p>Specifies a list of valid values. A value is valid if and only if
it's included in the list.</p></dd>
</dl></dd>
<dt><a name="80"><b class="cmd">snit::fpixels</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="81"><b class="cmd">snit::fpixels</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p><em>Tk programs only.</em> Validates screen distances, in any of the
forms accepted by <b class="cmd">winfo fpixels</b>. Subtypes may be created with the
following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-min</b> <i class="arg">min</i></dt>
<dd><p>Specifies a minimum bound; a value is invalid if it is strictly
less than <i class="arg">min</i>. The bound may be expressed in any of the
forms accepted by <b class="cmd">winfo fpixels</b>.</p></dd>
<dt><b class="const">-max</b> <i class="arg">max</i></dt>
<dd><p>Specifies a maximum bound; a value is invalid if it is strictly
greater than <i class="arg">max</i>. The bound may be expressed in any of the
forms accepted by <b class="cmd">winfo fpixels</b>.</p></dd>
</dl></dd>
<dt><a name="82"><b class="cmd">snit::integer</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="83"><b class="cmd">snit::integer</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p>Validates integer values. Subtypes may be created with the
following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-min</b> <i class="arg">min</i></dt>
<dd><p>Specifies an integer minimum bound; a value is invalid if it is strictly
less than <i class="arg">min</i>.</p></dd>
<dt><b class="const">-max</b> <i class="arg">max</i></dt>
<dd><p>Specifies an integer maximum bound; a value is invalid if it is strictly
greater than <i class="arg">max</i>.</p></dd>
</dl></dd>
<dt><a name="84"><b class="cmd">snit::listtype</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="85"><b class="cmd">snit::listtype</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p>Validates Tcl lists. Subtypes may be created with the
following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-minlen</b> <i class="arg">min</i></dt>
<dd><p>Specifies a minimum list length; the value is invalid if it has
fewer than <i class="arg">min</i> elements. Defaults to 0.</p></dd>
<dt><b class="const">-maxlen</b> <i class="arg">max</i></dt>
<dd><p>Specifies a maximum list length; the value is invalid if it
more than <i class="arg">max</i> elements.</p></dd>
<dt><b class="const">-type</b> <i class="arg">type</i></dt>
<dd><p>Specifies the type of the list elements; <i class="arg">type</i> must be
the name of a validation type or subtype. In the
following example, the value of <b class="const">-numbers</b> must be a list
of integers.</p>
<pre class="doctools_example"> option -numbers -type {snit::listtype -type snit::integer}
</pre>
<p>Note that this option doesn't support defining new validation subtypes
on the fly; that is, the following code will not work (yet, anyway):</p>
<pre class="doctools_example"> option -numbers -type {
snit::listtype -type {snit::integer -min 5}
}
</pre>
<p>Instead, define the subtype explicitly:</p>
<pre class="doctools_example"> snit::integer gt4 -min 5
snit::type mytype {
option -numbers -type {snit::listtype -type gt4}
}
</pre>
</dd>
</dl></dd>
<dt><a name="86"><b class="cmd">snit::pixels</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="87"><b class="cmd">snit::pixels</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p><em>Tk programs only.</em> Validates screen distances, in any of the
forms accepted by <b class="cmd">winfo pixels</b>. Subtypes may be created with the
following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-min</b> <i class="arg">min</i></dt>
<dd><p>Specifies a minimum bound; a value is invalid if it is strictly
less than <i class="arg">min</i>. The bound may be expressed in any of the
forms accepted by <b class="cmd">winfo pixels</b>.</p></dd>
<dt><b class="const">-max</b> <i class="arg">max</i></dt>
<dd><p>Specifies a maximum bound; a value is invalid if it is strictly
greater than <i class="arg">max</i>. The bound may be expressed in any of the
forms accepted by <b class="cmd">winfo pixels</b>.</p></dd>
</dl></dd>
<dt><a name="88"><b class="cmd">snit::stringtype</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="89"><b class="cmd">snit::stringtype</b> <i class="arg">name</i> <span class="opt">?<i class="arg">option</i> <i class="arg">value</i>...?</span></a></dt>
<dd><p>Validates Tcl strings. The base type is of little use by itself,
since very Tcl value is also a valid string. Subtypes may be created with the
following options:</p>
<dl class="doctools_definitions">
<dt><b class="const">-minlen</b> <i class="arg">min</i></dt>
<dd><p>Specifies a minimum string length; the value is invalid if it has
fewer than <i class="arg">min</i> characters. Defaults to 0.</p></dd>
<dt><b class="const">-maxlen</b> <i class="arg">max</i></dt>
<dd><p>Specifies a maximum string length; the value is invalid if it has
more than <i class="arg">max</i> characters.</p></dd>
<dt><b class="const">-glob</b> <i class="arg">pattern</i></dt>
<dd><p>Specifies a <b class="cmd">string match</b> pattern; the value is invalid
if it doesn't match the pattern.</p></dd>
<dt><b class="const">-regexp</b> <i class="arg">regexp</i></dt>
<dd><p>Specifies a regular expression; the value is invalid if it doesn't
match the regular expression.</p></dd>
<dt><b class="const">-nocase</b> <i class="arg">flag</i></dt>
<dd><p>By default, both <b class="const">-glob</b> and <b class="const">-regexp</b> matches are
case-sensitive. If <b class="const">-nocase</b> is set to true, then both
<b class="const">-glob</b> and <b class="const">-regexp</b> matches are case-insensitive.</p></dd>
</dl></dd>
<dt><a name="90"><b class="cmd">snit::window</b> <b class="const">validate</b> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd></dd>
<dt><a name="91"><b class="cmd">snit::window</b> <i class="arg">name</i></a></dt>
<dd><p><em>Tk programs only.</em> Validates Tk window names. The value must
cause <b class="cmd">winfo exists</b> to return true; otherwise, the value is
invalid. It's possible to define subtypes--that is, instances--of
<b class="cmd">snit::window</b>, but as it has no options at present there's no
reason to do so.</p></dd>
</dl>
</div>
<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Defining Validation Types</a></h3>
<p>There are three ways to define a new validation type: as a subtype of
one of Snit's validation types, as a validation type command, and as
a full-fledged validation type similar to those provided by Snit.
Defining subtypes of Snit's validation types is described above,
under <span class="sectref"><a href="#subsection11">Validation Types</a></span>.</p>
<p>The next simplest way to create a new validation type is as a
validation type command. A validation type is simply an
object that has a <b class="method">validate</b> method; the <b class="method">validate</b>
method must take one argument, a value, return the value if it is
valid, and throw an error with <b class="cmd">-errorcode</b> INVALID if the
value is invalid. This can be done with a simple <b class="cmd"><a href="../../../../index.html#proc">proc</a></b>. For
example, the <b class="cmd">snit::boolean</b> validate type could have been
implemented like this:</p>
<pre class="doctools_example"> proc ::snit::boolean {"validate" value} {
if {![string is boolean -strict $value]} {
return -code error -errorcode INVALID "invalid boolean \"$value\", should be one of: 1, 0, ..."
}
return $value
}
</pre>
<p>A validation type defined in this way cannot be subtyped, of course;
but for many applications this will be sufficient.</p>
<p>Finally, one can define a full-fledged, subtype-able validation type
as a <b class="cmd">snit::type</b>. Here's a skeleton to get you started:</p>
<pre class="doctools_example"> snit::type myinteger {
# First, define any options you'd like to use to define
# subtypes. Give them defaults such that they won't take
# effect if they aren't used, and marked them "read-only".
# After all, you shouldn't be changing their values after
# a subtype is defined.
#
# For example:
option -min -default "" -readonly 1
option -max -default "" -readonly 1
# Next, define a "validate" type method which should do the
# validation in the basic case. This will allow the
# type command to be used as a validation type.
typemethod validate {value} {
if {![string is integer -strict $value]} {
return -code error -errorcode INVALID "invalid value \"$value\", expected integer"
}
return $value
}
# Next, the constructor should validate the subtype options,
# if any. Since they are all readonly, we don't need to worry
# about validating the options on change.
constructor {args} {
# FIRST, get the options
$self configurelist $args
# NEXT, validate them.
# I'll leave this to your imagination.
}
# Next, define a "validate" instance method; its job is to
# validate values for subtypes.
method validate {value} {
# First, call the type method to do the basic validation.
$type validate $value
# Now we know it's a valid integer.
if {("" != $options(-min) && $value < $options(-min)) ||
("" != $options(-max) && $value > $options(-max))} {
# It's out of range; format a detailed message about
# the error, and throw it.
set msg "...."
return -code error -errorcode INVALID $msg
}
# Otherwise, if it's valid just return it.
return $valid
}
}
</pre>
<p>And now you have a type that can be subtyped.</p>
<p>The file "validate.tcl" in the Snit distribution defines all of Snit's
validation types; you can find the complete implementation for
<b class="cmd">snit::integer</b> and the other types there, to use as examples for
your own types.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">CAVEATS</a></h2>
<p>If you have problems, find bugs, or new ideas you are hereby cordially
invited to submit a report of your problem, bug, or idea as explained
in the section <span class="sectref"><a href="#section8">Bugs, Ideas, Feedback</a></span> below.</p>
<p>Additionally, you might wish to join the Snit mailing list;
see <a href="http://www.wjduquette.com/snit">http://www.wjduquette.com/snit</a> for details.</p>
<p>One particular area to watch is using <b class="cmd">snit::widgetadaptor</b> to
adapt megawidgets created by other megawidget packages; correct
widget destruction depends on the order of the <Destroy> bindings.
The wisest course is simply not to do this.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">KNOWN BUGS</a></h2>
<ul class="doctools_itemized">
<li><p>Error stack traces returned by Snit 1.x are extremely ugly and typically
contain far too much information about Snit internals. The error
messages are much improved in Snit 2.2.</p></li>
<li><p>Also see the Project Trackers as explained in the section
<span class="sectref"><a href="#section8">Bugs, Ideas, Feedback</a></span> below.</p></li>
</ul>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">HISTORY</a></h2>
<p>During the course of developing Notebook
(See <a href="http://www.wjduquette.com/notebook">http://www.wjduquette.com/notebook</a>), my Tcl-based personal
notebook application, I found I was writing it as a collection of
objects. I wasn't using any particular object-oriented framework; I
was just writing objects in pure Tcl following the guidelines in my
Guide to Object Commands
(see <a href="http://www.wjduquette.com/tcl/objects.html">http://www.wjduquette.com/tcl/objects.html</a>), along with a
few other tricks I'd picked up since. And though it was working well,
it quickly became tiresome because of the amount of boilerplate
code associated with each new object type.</p>
<p>So that was one thing--tedium is a powerful motivator. But the other
thing I noticed is that I wasn't using inheritance at all, and I
wasn't missing it. Instead, I was using delegation: objects that
created other objects and delegated methods to them.</p>
<p>And I said to myself, "This is getting tedious...there has got to be a
better way." And one afternoon, on a whim, I started working on Snit,
an object system that works the way Tcl works. Snit doesn't support
inheritance, but it's great at delegation, and it makes creating
megawidgets easy.</p>
<p>If you have any comments or suggestions (or bug reports!) don't
hesitate to send me e-mail at <a href="[email protected]">[email protected]</a>. In addition,
there's a Snit mailing list; you can find out more about it at the
Snit home page (see <a href="http://www.wjduquette.com/snit">http://www.wjduquette.com/snit</a>).</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">CREDITS</a></h2>
<p>Snit has been designed and implemented from the very beginning by
William H. Duquette. However, much credit belongs to the following
people for using Snit and providing me with valuable feedback: Rolf
Ade, Colin McCormack, Jose Nazario, Jeff Godfrey, Maurice Diamanti,
Egon Pasztor, David S. Cargo, Tom Krehbiel, Michael Cleverly,
Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian
Griffin, Donal Fellows, Miguel Sofer, Kenneth Green,
and Anton Kovalenko.
If I've forgotten anyone, my apologies; let me know and I'll add
your name to the list.</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>snit</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bwidget">BWidget</a>, <a href="../../../../index.html#c_">C++</a>, <a href="../../../../index.html#incr_tcl">Incr Tcl</a>, <a href="../../../../index.html#snit">Snit</a>, <a href="../../../../index.html#adaptors">adaptors</a>, <a href="../../../../index.html#class">class</a>, <a href="../../../../index.html#mega_widget">mega widget</a>, <a href="../../../../index.html#object">object</a>, <a href="../../../../index.html#object_oriented">object oriented</a>, <a href="../../../../index.html#type">type</a>, <a href="../../../../index.html#widget">widget</a>, <a href="../../../../index.html#widget_adaptors">widget adaptors</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2009, by William H. Duquette</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/snit/snitfaq.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
|
<div class='fossil-doc' data-title='snitfaq - Snit's Not Incr Tcl, OO system'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">snitfaq(n) 2.2 tcllib "Snit's Not Incr Tcl, OO system"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>snitfaq - Snit Frequently Asked Questions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">What is this document?</a></li>
<li class="doctools_subsection"><a href="#subsection2">What is Snit?</a></li>
<li class="doctools_subsection"><a href="#subsection3">What version of Tcl does Snit require?</a></li>
<li class="doctools_subsection"><a href="#subsection4">Where can I download Snit?</a></li>
<li class="doctools_subsection"><a href="#subsection5">What are Snit's goals?</a></li>
<li class="doctools_subsection"><a href="#subsection6">How is Snit different from other OO frameworks?</a></li>
<li class="doctools_subsection"><a href="#subsection7">What can I do with Snit?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">SNIT VERSIONS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection8">Which version of Snit should I use?</a></li>
<li class="doctools_subsection"><a href="#subsection9">How do I select the version of Snit I want to use?</a></li>
<li class="doctools_subsection"><a href="#subsection10">How are Snit 1.3 and Snit 2.2 incompatible?</a></li>
<li class="doctools_subsection"><a href="#subsection11">Are there other differences between Snit 1.x and Snit 2.2?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">OBJECTS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection12">What is an object?</a></li>
<li class="doctools_subsection"><a href="#subsection13">What is an abstract data type?</a></li>
<li class="doctools_subsection"><a href="#subsection14">What kinds of abstract data types does Snit provide?</a></li>
<li class="doctools_subsection"><a href="#subsection15">What is a snit::type?</a></li>
<li class="doctools_subsection"><a href="#subsection16">What is a snit::widget?, the short story</a></li>
<li class="doctools_subsection"><a href="#subsection17">What is a snit::widgetadaptor?, the short story</a></li>
<li class="doctools_subsection"><a href="#subsection18">How do I create an instance of a snit::type?</a></li>
<li class="doctools_subsection"><a href="#subsection19">How do I refer to an object indirectly?</a></li>
<li class="doctools_subsection"><a href="#subsection20">How can I generate the object name automatically?</a></li>
<li class="doctools_subsection"><a href="#subsection21">Can types be renamed?</a></li>
<li class="doctools_subsection"><a href="#subsection22">Can objects be renamed?</a></li>
<li class="doctools_subsection"><a href="#subsection23">How do I destroy a Snit object?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">INSTANCE METHODS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection24">What is an instance method?</a></li>
<li class="doctools_subsection"><a href="#subsection25">How do I define an instance method?</a></li>
<li class="doctools_subsection"><a href="#subsection26">How does a client call an instance method?</a></li>
<li class="doctools_subsection"><a href="#subsection27">How does an instance method call another instance method?</a></li>
<li class="doctools_subsection"><a href="#subsection28">Are there any limitations on instance method names?</a></li>
<li class="doctools_subsection"><a href="#subsection29">What is a hierarchical method?</a></li>
<li class="doctools_subsection"><a href="#subsection30">How do I define a hierarchical method?</a></li>
<li class="doctools_subsection"><a href="#subsection31">How do I call hierarchical methods?</a></li>
<li class="doctools_subsection"><a href="#subsection32">How do I make an instance method private?</a></li>
<li class="doctools_subsection"><a href="#subsection33">Are there any limitations on instance method arguments?</a></li>
<li class="doctools_subsection"><a href="#subsection34">What implicit arguments are passed to each instance method?</a></li>
<li class="doctools_subsection"><a href="#subsection35">What is $type?</a></li>
<li class="doctools_subsection"><a href="#subsection36">What is $self?</a></li>
<li class="doctools_subsection"><a href="#subsection37">What is $selfns?</a></li>
<li class="doctools_subsection"><a href="#subsection38">What is $win?</a></li>
<li class="doctools_subsection"><a href="#subsection39">How do I pass an instance method as a callback?</a></li>
<li class="doctools_subsection"><a href="#subsection40">How do I delegate instance methods to a component?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">INSTANCE VARIABLES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection41">What is an instance variable?</a></li>
<li class="doctools_subsection"><a href="#subsection42">How is a scalar instance variable defined?</a></li>
<li class="doctools_subsection"><a href="#subsection43">How is an array instance variable defined?</a></li>
<li class="doctools_subsection"><a href="#subsection44">What happens if I don't initialize an instance variable?</a></li>
<li class="doctools_subsection"><a href="#subsection45">Are there any limitations on instance variable names?</a></li>
<li class="doctools_subsection"><a href="#subsection46">Do I need to declare my instance variables in my methods?</a></li>
<li class="doctools_subsection"><a href="#subsection47">How do I pass an instance variable's name to another object?</a></li>
<li class="doctools_subsection"><a href="#subsection48">How do I make an instance variable public?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">OPTIONS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection49">What is an option?</a></li>
<li class="doctools_subsection"><a href="#subsection50">How do I define an option?</a></li>
<li class="doctools_subsection"><a href="#subsection51">How can a client set options at object creation?</a></li>
<li class="doctools_subsection"><a href="#subsection52">How can a client retrieve an option's value?</a></li>
<li class="doctools_subsection"><a href="#subsection53">How can a client set options after object creation?</a></li>
<li class="doctools_subsection"><a href="#subsection54">How should an instance method access an option value?</a></li>
<li class="doctools_subsection"><a href="#subsection55">How can I make an option read-only?</a></li>
<li class="doctools_subsection"><a href="#subsection56">How can I catch accesses to an option's value?</a></li>
<li class="doctools_subsection"><a href="#subsection57">What is a -cgetmethod?</a></li>
<li class="doctools_subsection"><a href="#subsection58">How can I catch changes to an option's value?</a></li>
<li class="doctools_subsection"><a href="#subsection59">What is a -configuremethod?</a></li>
<li class="doctools_subsection"><a href="#subsection60">How can I validate an option's value?</a></li>
<li class="doctools_subsection"><a href="#subsection61">What is a -validatemethod?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section8">TYPE VARIABLES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection62">What is a type variable?</a></li>
<li class="doctools_subsection"><a href="#subsection63">How is a scalar type variable defined?</a></li>
<li class="doctools_subsection"><a href="#subsection64">How is an array-valued type variable defined?</a></li>
<li class="doctools_subsection"><a href="#subsection65">What happens if I don't initialize a type variable?</a></li>
<li class="doctools_subsection"><a href="#subsection66">Are there any limitations on type variable names?</a></li>
<li class="doctools_subsection"><a href="#subsection67">Do I need to declare my type variables in my methods?</a></li>
<li class="doctools_subsection"><a href="#subsection68">How do I pass a type variable's name to another object?</a></li>
<li class="doctools_subsection"><a href="#subsection69">How do I make a type variable public?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section9">TYPE METHODS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection70">What is a type method?</a></li>
<li class="doctools_subsection"><a href="#subsection71">How do I define a type method?</a></li>
<li class="doctools_subsection"><a href="#subsection72">How does a client call a type method?</a></li>
<li class="doctools_subsection"><a href="#subsection73">Are there any limitations on type method names?</a></li>
<li class="doctools_subsection"><a href="#subsection74">How do I make a type method private?</a></li>
<li class="doctools_subsection"><a href="#subsection75">Are there any limitations on type method arguments?</a></li>
<li class="doctools_subsection"><a href="#subsection76">How does an instance or type method call a type method?</a></li>
<li class="doctools_subsection"><a href="#subsection77">How do I pass a type method as a callback?</a></li>
<li class="doctools_subsection"><a href="#subsection78">Can type methods be hierarchical?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section10">PROCS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection79">What is a proc?</a></li>
<li class="doctools_subsection"><a href="#subsection80">How do I define a proc?</a></li>
<li class="doctools_subsection"><a href="#subsection81">Are there any limitations on proc names?</a></li>
<li class="doctools_subsection"><a href="#subsection82">How does a method call a proc?</a></li>
<li class="doctools_subsection"><a href="#subsection83">How can I pass a proc to another object as a callback?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section11">TYPE CONSTRUCTORS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection84">What is a type constructor?</a></li>
<li class="doctools_subsection"><a href="#subsection85">How do I define a type constructor?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section12">CONSTRUCTORS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection86">What is a constructor?</a></li>
<li class="doctools_subsection"><a href="#subsection87">How do I define a constructor?</a></li>
<li class="doctools_subsection"><a href="#subsection88">What does the default constructor do?</a></li>
<li class="doctools_subsection"><a href="#subsection89">Can I choose a different set of arguments for the constructor?</a></li>
<li class="doctools_subsection"><a href="#subsection90">Are there any limitations on constructor arguments?</a></li>
<li class="doctools_subsection"><a href="#subsection91">Is there anything special about writing the constructor?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section13">DESTRUCTORS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection92">What is a destructor?</a></li>
<li class="doctools_subsection"><a href="#subsection93">How do I define a destructor?</a></li>
<li class="doctools_subsection"><a href="#subsection94">Are there any limitations on destructor arguments?</a></li>
<li class="doctools_subsection"><a href="#subsection95">What implicit arguments are passed to the destructor?</a></li>
<li class="doctools_subsection"><a href="#subsection96">Must components be destroyed explicitly?</a></li>
<li class="doctools_subsection"><a href="#subsection97">Is there any special about writing a destructor?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section14">COMPONENTS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection98">What is a component?</a></li>
<li class="doctools_subsection"><a href="#subsection99">How do I declare a component?</a></li>
<li class="doctools_subsection"><a href="#subsection100">How is a component named?</a></li>
<li class="doctools_subsection"><a href="#subsection101">Are there any limitations on component names?</a></li>
<li class="doctools_subsection"><a href="#subsection102">What is an owned component?</a></li>
<li class="doctools_subsection"><a href="#subsection103">What does the install command do?</a></li>
<li class="doctools_subsection"><a href="#subsection104">Must owned components be created in the constructor?</a></li>
<li class="doctools_subsection"><a href="#subsection105">Are there any limitations on component object names?</a></li>
<li class="doctools_subsection"><a href="#subsection106">Must I destroy the components I own?</a></li>
<li class="doctools_subsection"><a href="#subsection107">Can I expose a component's object command as part of my interface?</a></li>
<li class="doctools_subsection"><a href="#subsection108">How do I expose a component's object command?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section15">TYPE COMPONENTS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection109">What is a type component?</a></li>
<li class="doctools_subsection"><a href="#subsection110">How do I declare a type component?</a></li>
<li class="doctools_subsection"><a href="#subsection111">How do I install a type component?</a></li>
<li class="doctools_subsection"><a href="#subsection112">Are there any limitations on type component names?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section16">DELEGATION</a>
<ul>
<li class="doctools_subsection"><a href="#subsection113">What is delegation?</a></li>
<li class="doctools_subsection"><a href="#subsection114">How can I delegate a method to a component object?</a></li>
<li class="doctools_subsection"><a href="#subsection115">Can I delegate to a method with a different name?</a></li>
<li class="doctools_subsection"><a href="#subsection116">Can I delegate to a method with additional arguments?</a></li>
<li class="doctools_subsection"><a href="#subsection117">Can I delegate a method to something other than an object?</a></li>
<li class="doctools_subsection"><a href="#subsection118">How can I delegate a method to a type component object?</a></li>
<li class="doctools_subsection"><a href="#subsection119">How can I delegate a type method to a type component object?</a></li>
<li class="doctools_subsection"><a href="#subsection120">How can I delegate an option to a component object?</a></li>
<li class="doctools_subsection"><a href="#subsection121">Can I delegate to an option with a different name?</a></li>
<li class="doctools_subsection"><a href="#subsection122">How can I delegate any unrecognized method or option to a component object?</a></li>
<li class="doctools_subsection"><a href="#subsection123">How can I delegate all but certain methods or options to a component?</a></li>
<li class="doctools_subsection"><a href="#subsection124">Can a hierarchical method be delegated?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section17">WIDGETS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection125">What is a snit::widget?</a></li>
<li class="doctools_subsection"><a href="#subsection126">How do I define a snit::widget?</a></li>
<li class="doctools_subsection"><a href="#subsection127">How do snit::widgets differ from snit::types?</a></li>
<li class="doctools_subsection"><a href="#subsection128">What is a hull component?</a></li>
<li class="doctools_subsection"><a href="#subsection129">How can I set the hull type for a snit::widget?</a></li>
<li class="doctools_subsection"><a href="#subsection130">How should I name widgets which are components of a snit::widget?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section18">WIDGET ADAPTORS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection131">What is a snit::widgetadaptor?</a></li>
<li class="doctools_subsection"><a href="#subsection132">How do I define a snit::widgetadaptor?</a></li>
<li class="doctools_subsection"><a href="#subsection133">Can I adapt a widget created elsewhere in the program?</a></li>
<li class="doctools_subsection"><a href="#subsection134">Can I adapt another megawidget?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section19">THE TK OPTION DATABASE</a>
<ul>
<li class="doctools_subsection"><a href="#subsection135">What is the Tk option database?</a></li>
<li class="doctools_subsection"><a href="#subsection136">Do snit::types use the Tk option database?</a></li>
<li class="doctools_subsection"><a href="#subsection137">What is my snit::widget's widget class?</a></li>
<li class="doctools_subsection"><a href="#subsection138">What is my snit::widgetadaptor's widget class?</a></li>
<li class="doctools_subsection"><a href="#subsection139">What are option resource and class names?</a></li>
<li class="doctools_subsection"><a href="#subsection140">What are the resource and class names for my megawidget's options?</a></li>
<li class="doctools_subsection"><a href="#subsection141">How does Snit initialize my megawidget's locally-defined options?</a></li>
<li class="doctools_subsection"><a href="#subsection142">How does Snit initialize delegated options?</a></li>
<li class="doctools_subsection"><a href="#subsection143">How does Snit initialize options delegated to the hull?</a></li>
<li class="doctools_subsection"><a href="#subsection144">How does Snit initialize options delegated to other components?</a></li>
<li class="doctools_subsection"><a href="#subsection145">What happens if I install a non-widget as a component of widget?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section20">ENSEMBLE COMMANDS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection146">What is an ensemble command?</a></li>
<li class="doctools_subsection"><a href="#subsection147">How can I create an ensemble command using Snit?</a></li>
<li class="doctools_subsection"><a href="#subsection148">How can I create an ensemble command using an instance of a snit::type?</a></li>
<li class="doctools_subsection"><a href="#subsection149">How can I create an ensemble command using a snit::type?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section21">PRAGMAS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection150">What is a pragma?</a></li>
<li class="doctools_subsection"><a href="#subsection151">How do I set a pragma?</a></li>
<li class="doctools_subsection"><a href="#subsection152">How can I get rid of the "info" type method?</a></li>
<li class="doctools_subsection"><a href="#subsection153">How can I get rid of the "destroy" type method?</a></li>
<li class="doctools_subsection"><a href="#subsection154">How can I get rid of the "create" type method?</a></li>
<li class="doctools_subsection"><a href="#subsection155">How can I get rid of type methods altogether?</a></li>
<li class="doctools_subsection"><a href="#subsection156">Why can't I create an object that replaces an old object with the same name?</a></li>
<li class="doctools_subsection"><a href="#subsection157">How can I make my simple type run faster?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section22">MACROS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection158">What is a macro?</a></li>
<li class="doctools_subsection"><a href="#subsection159">What are macros good for?</a></li>
<li class="doctools_subsection"><a href="#subsection160">How do I do conditional compilation?</a></li>
<li class="doctools_subsection"><a href="#subsection161">How do I define new type definition syntax?</a></li>
<li class="doctools_subsection"><a href="#subsection162">Are there are restrictions on macro names?</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section23">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">What is this document?</a></h3>
<p>This is an atypical FAQ list, in that few of the questions are
frequently asked. Rather, these are the questions I think a newcomer
to Snit should be asking. This file is not a complete reference to
Snit, however; that information is in the <b class="cmd"><a href="snit.html">snit</a></b> man page.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">What is Snit?</a></h3>
<p>Snit is a framework for defining abstract data types and megawidgets
in pure Tcl. The name "Snit" stands for "Snit's Not Incr Tcl",
signifying that Snit takes a different approach to defining objects
than does Incr Tcl, the best known object framework for Tcl. Had
I realized that Snit would become at all popular, I'd probably have
chosen something else.</p>
<p>The primary purpose of Snit is to be <i class="term">object glue</i>--to help you
compose diverse objects from diverse sources into types and
megawidgets with clean, convenient interfaces so that you can more
easily build your application.</p>
<p>Snit isn't about theoretical purity or minimalist design; it's about
being able to do powerful things easily and consistently without
having to think about them--so that you can concentrate on building
your application.</p>
<p>Snit isn't about implementing thousands of nearly identical
carefully-specified lightweight thingamajigs--not as individual Snit
objects. Traditional Tcl methods will be much faster, and not much
more complicated. But Snit <em>is</em> about implementing a clean interface
to manage a collection of thousands of nearly identical
carefully-specified lightweight thingamajigs (e.g., think of the text
widget and text tags, or the canvas widget and canvas objects). Snit
lets you hide the details of just how those thingamajigs are
stored--so that you can ignore it, and concentrate on building your
application.</p>
<p>Snit isn't a way of life, a silver bullet, or the Fountain of
Youth. It's just a way of managing complexity--and of managing some of
the complexity of managing complexity--so that you can concentrate on
building your application.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">What version of Tcl does Snit require?</a></h3>
<p>Snit 1.3 requires Tcl 8.3 or later; Snit 2.2 requires Tcl 8.5 or
later. See <span class="sectref"><a href="#section3">SNIT VERSIONS</a></span> for the differences between Snit
1.3 and Snit 2.2.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Where can I download Snit?</a></h3>
<p>Snit is part of Tcllib, the standard Tcl library, so you might already
have it. It's also available at the Snit Home Page,
<a href="http://www.wjduquette.com/snit">http://www.wjduquette.com/snit</a>.</p>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">What are Snit's goals?</a></h3>
<ul class="doctools_itemized">
<li><p>A Snit object should be at least as efficient as a hand-coded Tcl
object (see <a href="http://www.wjduquette.com/tcl/objects.html">http://www.wjduquette.com/tcl/objects.html</a>).</p></li>
<li><p>The fact that Snit was used in an object's implementation should be
transparent (and irrelevant) to clients of that object.</p></li>
<li><p>Snit should be able to encapsulate objects from other sources,
particularly Tk widgets.</p></li>
<li><p>Snit megawidgets should be (to the extent possible) indistinguishable
in interface from Tk widgets.</p></li>
<li><p>Snit should be Tclish--that is, rather than trying to emulate C++,
Smalltalk, or anything else, it should try to emulate Tcl itself.</p></li>
<li><p>It should have a simple, easy-to-use, easy-to-remember syntax.</p></li>
</ul>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">How is Snit different from other OO frameworks?</a></h3>
<p>Snit is unique among Tcl object systems in that
it is based not on inheritance but on delegation. Object
systems based on inheritance only allow you to inherit from classes
defined using the same system, and that's a shame. In Tcl, an object
is anything that acts like an object; it shouldn't matter how the
object was implemented. I designed Snit to help me build applications
out of the materials at hand; thus, Snit is designed to be able to
incorporate and build on any object, whether it's a hand-coded object,
a Tk widget, an Incr Tcl object, a BWidget or almost anything else.</p>
<p>Note that you can achieve the effect of inheritance using
<span class="sectref"><a href="#section14">COMPONENTS</a></span> and <span class="sectref"><a href="#section16">DELEGATION</a></span>--and you can inherit
from anything that looks like a Tcl object.</p>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">What can I do with Snit?</a></h3>
<p>Using Snit, a programmer can:</p>
<ul class="doctools_itemized">
<li><p>Create abstract data types and Tk megawidgets.</p></li>
<li><p>Define instance variables, type variables, and Tk-style options.</p></li>
<li><p>Define constructors, destructors, instance methods, type methods, procs.</p></li>
<li><p>Assemble a type out of component types. Instance methods and options
can be delegated to the component types automatically.</p></li>
</ul>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">SNIT VERSIONS</a></h2>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Which version of Snit should I use?</a></h3>
<p>The current Snit distribution includes two versions, Snit 1.3 and Snit
2.2. The reason that both are included is that Snit 2.2 takes
advantage of a number of new features of Tcl 8.5 to improve run-time
efficiency; as a side-effect, the ugliness of Snit's error messages
and stack traces has been reduced considerably. The cost of using
Snit 2.2, of course, is that you must target Tcl 8.5.</p>
<p>Snit 1.3, on the other hand, lacks Snit 2.2's optimizations, but
requires only Tcl 8.3 and later.</p>
<p>In short, if you're targetting Tcl 8.3 or 8.4 you should use Snit 1.3. If
you can afford to target Tcl 8.5, you should definitely use Snit 2.2.
If you will be targetting both, you can use Snit 1.3 exclusively, or
(if your code is unaffected by the minor incompatibilities between the
two versions) you can use Snit 1.3 for Tcl 8.4 and Snit 2.2 for Tcl
8.5.</p>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">How do I select the version of Snit I want to use?</a></h3>
<p>To always use Snit 1.3 (or a later version of Snit 1.x), invoke Snit
as follows:</p>
<pre class="doctools_example">package require snit 1.3
</pre>
<p>To always use Snit 2.2 (or a later version of Snit 2.x), say this
instead:</p>
<pre class="doctools_example">package require snit 2.2
</pre>
<p>Note that if you request Snit 2.2 explicitly, your application will
halt with Tcl 8.4, since Snit 2.2 is unavailable for Tcl 8.4.</p>
<p>If you wish your application to always use the latest available
version of Snit, don't specify a version number:</p>
<pre class="doctools_example">package require snit
</pre>
<p>Tcl will find and load the latest version that's available relative to
the version of Tcl being used. In this case, be careful to avoid
using any incompatible features.</p>
</div>
<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">How are Snit 1.3 and Snit 2.2 incompatible?</a></h3>
<p>To the extent possible, Snit 2.2 is intended to be a drop-in
replacement for Snit 1.3. Unfortunately, some incompatibilities were
inevitable because Snit 2.2 uses Tcl 8.5's new
<b class="cmd">namespace ensemble</b> mechanism to implement subcommand dispatch.
This approach is much faster than the mechanism used in Snit 1.3, and
also results in much better error messages; however, it also places
new constraints on the implementation.</p>
<p>There are four specific incompatibilities between Snit 1.3 and Snit 2.2.</p>
<ul class="doctools_itemized">
<li><p>Snit 1.3 supports implicit naming of objects. Suppose you define a
new <b class="cmd">snit::type</b> called <b class="cmd">dog</b>. You can create instances of
<b class="cmd">dog</b> in three ways:</p>
<pre class="doctools_example">dog spot ;# Explicit naming
set obj1 [dog %AUTO%] ;# Automatic naming
set obj2 [dog] ;# Implicit naming
</pre>
<p>In Snit 2.2, type commands are defined using the <b class="cmd">namespace ensemble</b>
mechanism; and <b class="cmd">namespace ensemble</b> doesn't allow an ensemble command
to be called without a subcommand. In short, using
<b class="cmd">namespace ensemble</b> there's no way to support implicit naming.</p>
<p>All is not lost, however. If the type has no type methods, then the
type command is a simple command rather than an ensemble, and
<b class="cmd">namespace ensemble</b> is not used. In this case, implicit naming
is still possible.</p>
<p>In short, you can have implicit naming if you're willing to do without
type methods (including the standard type methods, like
<b class="cmd">$type info</b>). To do so, use the <b class="const">-hastypemethods</b> pragma:</p>
<pre class="doctools_example">pragma -hastypemethods 0</pre>
</li>
<li><p>Hierarchical methods and type methods are implemented differently in
Snit 2.2.</p>
<p>A hierarchical method is an instance method which has
subcommands; these subcommands are themselves methods. The Tk text
widget's <b class="cmd">tag</b> command and its subcommands are examples of
hierarchical methods. You can implement such subcommands in Snit
simply by including multiple words in the method names:</p>
<pre class="doctools_example">method {tag configure} {tag args} { ... }
method {tag cget} {tag option} {...}
</pre>
<p>Here we've implicitly defined a <b class="cmd">tag</b> method which has two
subcommands, <b class="cmd">configure</b> and <b class="cmd">cget</b>.</p>
<p>In Snit 1.3, hierarchical methods could be called in two ways:</p>
<pre class="doctools_example">$obj tag cget -myoption ;# The good way
$obj {tag cget} -myoption ;# The weird way
</pre>
<p>In the second call, we see that a hierarchical method or type method
is simply one whose name contains multiple words.</p>
<p>In Snit 2.2 this is no longer the case, and the "weird" way of calling
hierarchical methods and type methods no longer works.</p></li>
<li><p>The third incompatibility derives from the second. In Snit 1.3,
hierarchical methods were also simply methods whose name contains
multiple words. As a result, <b class="cmd">$obj info methods</b> returned the
full names of all hierarchical methods. In the example above,
the list returned by <b class="cmd">$obj info methods</b> would include
<b class="cmd">tag configure</b> and <b class="cmd">tag cget</b> but not <b class="cmd">tag</b>, since
<b class="cmd">tag</b> is defined only implicitly.</p>
<p>In Snit 2.2, hierarchical methods and type methods are no longer
simply ones whose
name contains multiple words; in the above example, the list returned
by <b class="cmd">$obj info methods</b> would include <b class="cmd">tag</b> but not
<b class="cmd">tag configure</b> or <b class="cmd">tag cget</b>.</p></li>
<li><p>The fourth incompatibility is due to a new feature. Snit 2.2 uses
the new <b class="cmd">namespace path</b> command so that a type's code can
call any command defined in the type's parent namespace without
qualification or importation. For example, suppose you have a
package called <b class="cmd">mypackage</b> which defines a number of commands
including a type, <b class="cmd">::mypackage::mytype</b>. Thanks to
<b class="cmd">namespace path</b>, the type's code can call any of the other
commands defined in <b class="cmd">::mypackage::</b>.</p>
<p>This is extremely convenient. However, it also means that commands
defined in the parent namespace, <b class="cmd">::mypackage::</b> can block the
type's access to identically named commands in the global namespace.
This can lead to bugs. For example, Tcllib includes a type called
<b class="cmd">::tie::std::file</b>. This type's code calls the standard
<b class="cmd"><a href="../../../../index.html#file">file</a></b> command. When run with Snit 2.2, the code broke--
the type's command, <b class="cmd">::tie::std::file</b>, is itself a command
in the type's parent namespace, and so instead of calling
the standard <b class="cmd"><a href="../../../../index.html#file">file</a></b> command, the type found itself calling
itself.</p></li>
</ul>
</div>
<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Are there other differences between Snit 1.x and Snit 2.2?</a></h3>
<p>Yes.</p>
<ul class="doctools_itemized">
<li><p>Method dispatch is considerably faster.</p></li>
<li><p>Many error messages and stack traces are cleaner.</p></li>
<li><p>The <b class="const">-simpledispatch</b> pragma is obsolete, and ignored if
present. In Snit 1.x, <b class="const">-simpledispatch</b> substitutes a faster
mechanism for method dispatch, at the cost of losing certain features.
Snit 2.2 method dispatch is faster still in all cases, so
<b class="const">-simpledispatch</b> is no longer needed.</p></li>
<li><p>In Snit 2.2, a type's code (methods, type methods, etc.) can call commands
from the type's parent namespace without qualifying or importing
them, i.e., type <b class="cmd">::parentns::mytype</b>'s code can call
<b class="cmd">::parentns::someproc</b> as just <b class="cmd">someproc</b>.</p>
<p>This is extremely useful when a type is defined as part of a larger
package, and shares a parent namespace with the rest of the package;
it means that the type can call other commands defined by the
package without any extra work.</p>
<p>This feature depends on the new Tcl 8.5 <b class="cmd">namespace path</b> command,
which is why it hasn't been implemented for V1.x. V1.x code can
achieve something similar by placing</p>
<pre class="doctools_example">namespace import [namespace parent]::*</pre>
<p>in a type constructor. This is less useful, however, as it picks up
only those commands which have already been exported by the parent
namespace at the time the type is defined.</p></li>
</ul>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">OBJECTS</a></h2>
<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">What is an object?</a></h3>
<p>A full description of object-oriented programming is beyond
the scope of this FAQ, obviously. In simple terms, an object is an instance of
an abstract data type--a coherent bundle of code and data.
There are many ways to represent objects in Tcl/Tk; the best known
examples are the Tk widgets.</p>
<p>A Tk widget is an object; it is represented by a Tcl command.
The object's methods are subcommands of the Tcl command. The object's
properties are options accessed using the <b class="method">configure</b> and
<b class="method">cget</b> methods. Snit uses the same conventions as Tk widgets do.</p>
</div>
<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">What is an abstract data type?</a></h3>
<p>In computer science terms, an abstract data type is a complex data
structure along with a set of operations--a stack, a queue, a
binary tree, etc--that is to say, in modern terms, an object. In systems
that include some form of inheritance the word <i class="term"><a href="../../../../index.html#class">class</a></i> is
usually used instead of <i class="term">abstract data type</i>, but as Snit
doesn't implement inheritance as it's ordinarily understood
the older term seems more appropriate. Sometimes this is called
<i class="term">object-based</i> programming as opposed to object-oriented
programming. Note that you can easily create the effect of
inheritance using <span class="sectref"><a href="#section14">COMPONENTS</a></span> and <span class="sectref"><a href="#section16">DELEGATION</a></span>.</p>
<p>In Snit, as in Tk, a <i class="term"><a href="../../../../index.html#type">type</a></i> is a command that creates instances
-- objects -- which belong to the type. Most types define some number
of <i class="term">options</i> which can be set at creation time, and usually can be
changed later.</p>
<p>Further, an <i class="term">instance</i> is also a Tcl command--a command that
gives access to the operations which are defined for that abstract
data type. Conventionally, the operations are defined as subcommands
of the instance command. For example, to insert
text into a Tk text widget, you use the text widget's <b class="method">insert</b>
subcommand:</p>
<pre class="doctools_example"> # Create a text widget and insert some text in it.
text .mytext -width 80 -height 24
.mytext insert end "Howdy!"
</pre>
<p>In this example, <b class="cmd"><a href="../../../../index.html#text">text</a></b> is the <i class="term"><a href="../../../../index.html#type">type</a></i> command and
<b class="cmd">.mytext</b> is the <i class="term">instance</i> command.</p>
<p>In Snit, object subcommands are generally called
<span class="sectref"><a href="#section5">INSTANCE METHODS</a></span>.</p>
</div>
<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">What kinds of abstract data types does Snit provide?</a></h3>
<p>Snit allows you to define three kinds of abstract data type:</p>
<ul class="doctools_itemized">
<li><p><b class="cmd">snit::type</b></p></li>
<li><p><b class="cmd">snit::widget</b></p></li>
<li><p><b class="cmd">snit::widgetadaptor</b></p></li>
</ul>
</div>
<div id="subsection15" class="doctools_subsection"><h3><a name="subsection15">What is a snit::type?</a></h3>
<p>A <b class="cmd">snit::type</b> is a non-GUI abstract data type, e.g., a stack or a
queue. <b class="cmd">snit::type</b>s are defined using the <b class="cmd">snit::type</b>
command. For example, if you were designing a kennel management
system for a dog breeder, you'd need a dog type.</p>
<pre class="doctools_example">% snit::type dog {
# ...
}
::dog
%
</pre>
<p>This definition defines a new command (<b class="cmd">::dog</b>, in this case)
that can be used to define dog objects.</p>
<p>An instance of a <b class="cmd">snit::type</b> can have <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span>,
<span class="sectref"><a href="#section6">INSTANCE VARIABLES</a></span>, <span class="sectref"><a href="#section7">OPTIONS</a></span>, and <span class="sectref"><a href="#section14">COMPONENTS</a></span>.
The type itself can have <span class="sectref"><a href="#section9">TYPE METHODS</a></span>,
<span class="sectref"><a href="#section8">TYPE VARIABLES</a></span>, <span class="sectref"><a href="#section15">TYPE COMPONENTS</a></span>, and
<span class="sectref"><a href="#section10">PROCS</a></span>.</p>
</div>
<div id="subsection16" class="doctools_subsection"><h3><a name="subsection16">What is a snit::widget?, the short story</a></h3>
<p>A <b class="cmd">snit::widget</b> is a Tk megawidget built using Snit; it is very
similar to a <b class="cmd">snit::type</b>. See <span class="sectref"><a href="#section17">WIDGETS</a></span>.</p>
</div>
<div id="subsection17" class="doctools_subsection"><h3><a name="subsection17">What is a snit::widgetadaptor?, the short story</a></h3>
<p>A <b class="cmd">snit::widgetadaptor</b> uses Snit to wrap an existing widget type
(e.g., a Tk label), modifying its interface to a lesser or greater
extent. It is very similar to a <b class="cmd">snit::widget</b>.
See <span class="sectref"><a href="#section18">WIDGET ADAPTORS</a></span>.</p>
</div>
<div id="subsection18" class="doctools_subsection"><h3><a name="subsection18">How do I create an instance of a snit::type?</a></h3>
<p>You create an instance of a <b class="cmd">snit::type</b> by passing the new
instance's name to the type's create method. In the following
example, we create a <b class="cmd">dog</b> object called <b class="cmd">spot</b>.</p>
<pre class="doctools_example">% snit::type dog {
# ....
}
::dog
% dog create spot
::spot
%
</pre>
<p>In general, the <b class="method">create</b> method name can be omitted so long as
the instance name doesn't conflict with any defined
<span class="sectref"><a href="#section9">TYPE METHODS</a></span>. (See <span class="sectref"><a href="#section15">TYPE COMPONENTS</a></span> for the
special case in which this doesn't work.)
So the following example is identical to the
previous example:</p>
<pre class="doctools_example">% snit::type dog {
# ....
}
::dog
% dog spot
::spot
%
</pre>
<p>This document generally uses the shorter form.</p>
<p>If the <b class="cmd">dog</b> type defines <span class="sectref"><a href="#section7">OPTIONS</a></span>, these can usually be
given defaults at creation time:</p>
<pre class="doctools_example">% snit::type dog {
option -breed mongrel
option -color brown
method bark {} { return "$self barks." }
}
::dog
% dog create spot -breed dalmation -color spotted
::spot
% spot cget -breed
dalmation
% spot cget -color
spotted
%
</pre>
<p>Once created, the instance name now names a new Tcl command that is used
to manipulate the object. For example, the following code makes the
dog bark:</p>
<pre class="doctools_example">% spot bark
::spot barks.
%
</pre>
</div>
<div id="subsection19" class="doctools_subsection"><h3><a name="subsection19">How do I refer to an object indirectly?</a></h3>
<p>Some programmers prefer to save the object name in a variable, and
reference it that way. For example,</p>
<pre class="doctools_example">% snit::type dog { ... }
::dog
% set d [dog spot -breed dalmation -color spotted]
::spot
% $d cget -breed
dalmation
% $d bark
::spot barks.
%
</pre>
<p>If you prefer this style, you might prefer to have Snit
generate the instance's name automatically.</p>
</div>
<div id="subsection20" class="doctools_subsection"><h3><a name="subsection20">How can I generate the object name automatically?</a></h3>
<p>If you'd like Snit to generate an object name for you,
use the <b class="const">%AUTO%</b> keyword as the requested name:</p>
<pre class="doctools_example">% snit::type dog { ... }
::dog
% set d [dog %AUTO%]
::dog2
% $d bark
::dog2 barks.
%
</pre>
<p>The <b class="const">%AUTO%</b> keyword can be embedded in a longer string:</p>
<pre class="doctools_example">% set d [dog obj_%AUTO%]
::obj_dog4
% $d bark
::obj_dog4 barks.
%
</pre>
</div>
<div id="subsection21" class="doctools_subsection"><h3><a name="subsection21">Can types be renamed?</a></h3>
<p>Tcl's <b class="cmd">rename</b> command renames other commands. It's a common
technique in Tcl to modify an existing command by renaming it and
defining a new command with the original name; the new command usually
calls the renamed command.</p>
<p><b class="cmd">snit::type</b> commands, however, should never be renamed; to do so breaks
the connection between the type and its objects.</p>
</div>
<div id="subsection22" class="doctools_subsection"><h3><a name="subsection22">Can objects be renamed?</a></h3>
<p>Tcl's <b class="cmd">rename</b> command renames other commands. It's a common
technique in Tcl to modify an existing command by renaming it and
defining a new command with the original name; the new command usually
calls the renamed command.</p>
<p>All Snit objects (including <i class="term">widgets</i> and <i class="term">widgetadaptors</i>)
can be renamed, though this flexibility has some consequences:</p>
<ul class="doctools_itemized">
<li><p>In an instance method, the implicit argument <b class="variable">self</b> will always
contain the object's current name, so instance methods can always call
other instance methods using <b class="variable">$self</b>.</p></li>
<li><p>If the object is renamed, however, then <b class="variable">$self</b>'s value will change.
Therefore, don't use <b class="variable">$self</b> for anything that will break if
<b class="variable">$self</b> changes. For example, don't pass a callback command to
another object like this:</p>
<pre class="doctools_example">
.btn configure -command [list $self ButtonPress]
</pre>
<p>You'll get an error if <b class="cmd">.btn</b> calls your command after your object is
renamed.</p></li>
<li><p>Instead, your object should define its callback command like this:</p>
<pre class="doctools_example">
.btn configure -command [mymethod ButtonPress]
</pre>
<p>The <b class="cmd">mymethod</b> command returns code that will call the desired
method safely; the caller of the callback can add additional
arguments to the end of the command as usual.</p></li>
<li><p>Every object has a private namespace; the name of this namespace is
available in method bodies, etc., as the value of the implicit
argument <b class="variable">selfns</b>. This value is constant for the life of the
object. Use <b class="variable">$selfns</b> instead of <b class="variable">$self</b> if you need a
unique token to identify the object.</p></li>
<li><p>When a <b class="cmd">snit::widget</b>'s instance command is renamed, its Tk window
name remains the same -- and is still extremely
important. Consequently, the Tk window name is available in
method bodies as the value of the implicit argument <b class="variable">win</b>.
This value is constant for the
life of the object. When creating child windows, it's best to use
<b class="variable">$win.child</b> rather than <b class="variable">$self.child</b> as the name of the
child window.</p></li>
</ul>
</div>
<div id="subsection23" class="doctools_subsection"><h3><a name="subsection23">How do I destroy a Snit object?</a></h3>
<p>Any Snit object of any type can be destroyed by renaming
it to the empty string using the Tcl <b class="cmd">rename</b> command.</p>
<p>Snit megawidgets (i.e., instances of <b class="cmd">snit::widget</b> and
<b class="cmd">snit::widgetadaptor</b>) can be destroyed like any other widget: by
using the Tk <b class="cmd">destroy</b> command on the widget or on one of its
ancestors in the window hierarchy.</p>
<p>Every instance of a <b class="cmd">snit::type</b> has a <b class="method">destroy</b> method:</p>
<pre class="doctools_example">% snit::type dog { ... }
::dog
% dog spot
::spot
% spot bark
::spot barks.
% spot destroy
% spot barks
invalid command name "spot"
%
</pre>
<p>Finally, every Snit type has a type method called <b class="method">destroy</b>; calling it
destroys the type and all of its instances:</p>
<pre class="doctools_example">% snit::type dog { ... }
::dog
% dog spot
::spot
% spot bark
::spot barks.
% dog destroy
% spot bark
invalid command name "spot"
% dog fido
invalid command name "dog"
%
</pre>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">INSTANCE METHODS</a></h2>
<div id="subsection24" class="doctools_subsection"><h3><a name="subsection24">What is an instance method?</a></h3>
<p>An instance method is a procedure associated with a specific object
and called as a subcommand of the object's command. It is given free
access to all of the object's type variables, instance variables, and
so forth.</p>
</div>
<div id="subsection25" class="doctools_subsection"><h3><a name="subsection25">How do I define an instance method?</a></h3>
<p>Instance methods are defined in the type definition using
the <b class="cmd"><a href="../../../../index.html#method">method</a></b> statement. Consider the following code that might be
used to add dogs to a computer simulation:</p>
<pre class="doctools_example">% snit::type dog {
method bark {} {
return "$self barks."
}
method chase {thing} {
return "$self chases $thing."
}
}
::dog
%
</pre>
<p>A dog can bark, and it can chase things.</p>
<p>The <b class="cmd"><a href="../../../../index.html#method">method</a></b> statement looks just like a normal Tcl <b class="cmd"><a href="../../../../index.html#proc">proc</a></b>,
except that it appears in a <b class="cmd">snit::type</b> definition. Notice that
every instance method gets an implicit argument called <b class="variable">self</b>;
this argument contains the object's name. (There's more on
implicit method arguments below.)</p>
</div>
<div id="subsection26" class="doctools_subsection"><h3><a name="subsection26">How does a client call an instance method?</a></h3>
<p>The method name becomes a subcommand of the object. For example,
let's put a simulated dog through its paces:</p>
<pre class="doctools_example">% dog spot
::spot
% spot bark
::spot barks.
% spot chase cat
::spot chases cat.
%
</pre>
</div>
<div id="subsection27" class="doctools_subsection"><h3><a name="subsection27">How does an instance method call another instance method?</a></h3>
<p>If method A needs to call method B on the same object, it does so just
as a client does: it calls method B as a subcommand of the object
itself, using the object name stored in the implicit argument <b class="variable">self</b>.</p>
<p>Suppose, for example, that our dogs never chase anything without
barking at them:</p>
<pre class="doctools_example">% snit::type dog {
method bark {} {
return "$self barks."
}
method chase {thing} {
return "$self chases $thing. [$self bark]"
}
}
::dog
% dog spot
::spot
% spot bark
::spot barks.
% spot chase cat
::spot chases cat. ::spot barks.
%
</pre>
</div>
<div id="subsection28" class="doctools_subsection"><h3><a name="subsection28">Are there any limitations on instance method names?</a></h3>
<p>Not really, so long as you avoid the standard instance method names:
<b class="method">configure</b>, <b class="method">configurelist</b>, <b class="method">cget</b>,
<b class="method">destroy</b>, and <b class="method">info</b>. Also, method names consisting of
multiple words define hierarchical methods.</p>
</div>
<div id="subsection29" class="doctools_subsection"><h3><a name="subsection29">What is a hierarchical method?</a></h3>
<p>An object's methods are subcommands of the object's instance command.
Hierarchical methods allow an object's methods to have subcommands of
their own; and these can in turn have subcommands, and so on. This
allows the programmer to define a tree-shaped command structure, such
as is used by many of the Tk widgets--the subcommands of the
Tk <b class="cmd"><a href="../../../../index.html#text">text</a></b> widget's <b class="cmd">tag</b> method are hierarchical methods.</p>
</div>
<div id="subsection30" class="doctools_subsection"><h3><a name="subsection30">How do I define a hierarchical method?</a></h3>
<p>Define methods whose names consist of multiple words. These words
define the hierarchy implicitly. For example, the following code
defines a <b class="cmd">tag</b> method with subcommands <b class="cmd">cget</b> and
<b class="cmd">configure</b>:</p>
<pre class="doctools_example">snit::widget mytext {
method {tag configure} {tag args} { ... }
method {tag cget} {tag option} {...}
}
</pre>
<p>Note that there is no explicit definition for the <b class="cmd">tag</b> method;
it is implicit in the definition of <b class="cmd">tag configure</b> and
<b class="cmd">tag cget</b>. If you tried to define <b class="cmd">tag</b> explicitly in this
example, you'd get an error.</p>
</div>
<div id="subsection31" class="doctools_subsection"><h3><a name="subsection31">How do I call hierarchical methods?</a></h3>
<p>As subcommands of subcommands.</p>
<pre class="doctools_example">% mytext .text
.text
% .text tag configure redtext -foreground red -background black
% .text tag cget redtext -foreground
red
%
</pre>
</div>
<div id="subsection32" class="doctools_subsection"><h3><a name="subsection32">How do I make an instance method private?</a></h3>
<p>It's often useful to define private methods, that is, instance methods
intended to be called only by other methods of the same object.</p>
<p>Snit doesn't implement any access control on instance methods, so all
methods are <em>de facto</em> public. Conventionally, though, the
names of public methods begin with a lower-case letter, and the names
of private methods begin with an upper-case letter.</p>
<p>For example, suppose our simulated dogs only bark in response to other
stimuli; they never bark just for fun. So the <b class="method">bark</b> method
becomes <b class="method">Bark</b> to indicate that it is private:</p>
<pre class="doctools_example">% snit::type dog {
# Private by convention: begins with uppercase letter.
method Bark {} {
return "$self barks."
}
method chase {thing} {
return "$self chases $thing. [$self Bark]"
}
}
::dog
% dog fido
::fido
% fido chase cat
::fido chases cat. ::fido barks.
%
</pre>
</div>
<div id="subsection33" class="doctools_subsection"><h3><a name="subsection33">Are there any limitations on instance method arguments?</a></h3>
<p>Method argument lists are defined just like normal Tcl <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> argument
lists; in particular, they can include arguments with default values
and the <b class="variable">args</b> argument.</p>
<p>However, every method also has a number of implicit arguments
provided by Snit in addition to those explicitly defined. The names
of these implicit arguments may not used to name explicit arguments.</p>
</div>
<div id="subsection34" class="doctools_subsection"><h3><a name="subsection34">What implicit arguments are passed to each instance method?</a></h3>
<p>The arguments implicitly passed to every method are <b class="variable">type</b>,
<b class="variable">selfns</b>, <b class="variable">win</b>, and <b class="variable">self</b>.</p>
</div>
<div id="subsection35" class="doctools_subsection"><h3><a name="subsection35">What is $type?</a></h3>
<p>The implicit argument <b class="variable">type</b> contains the fully qualified name of
the object's type:</p>
<pre class="doctools_example">% snit::type thing {
method mytype {} {
return $type
}
}
::thing
% thing something
::something
% something mytype
::thing
%
</pre>
</div>
<div id="subsection36" class="doctools_subsection"><h3><a name="subsection36">What is $self?</a></h3>
<p>The implicit argument <b class="variable">self</b> contains the object's fully
qualified name.</p>
<p>If the object's command is renamed, then <b class="variable">$self</b> will change to
match in subsequent calls. Thus, your code should not assume that
<b class="variable">$self</b> is constant unless you know for sure that the object
will never be renamed.</p>
<pre class="doctools_example">% snit::type thing {
method myself {} {
return $self
}
}
::thing
% thing mutt
::mutt
% mutt myself
::mutt
% rename mutt jeff
% jeff myself
::jeff
%
</pre>
</div>
<div id="subsection37" class="doctools_subsection"><h3><a name="subsection37">What is $selfns?</a></h3>
<p>Each Snit object has a private namespace in which to store its
<span class="sectref"><a href="#section6">INSTANCE VARIABLES</a></span> and <span class="sectref"><a href="#section7">OPTIONS</a></span>. The implicit argument
<b class="variable">selfns</b> contains the name of this namespace; its value never changes, and
is constant for the life of the object, even if the object's name
changes:</p>
<pre class="doctools_example">% snit::type thing {
method myNameSpace {} {
return $selfns
}
}
::thing
% thing jeff
::jeff
% jeff myNameSpace
::thing::Snit_inst3
% rename jeff mutt
% mutt myNameSpace
::thing::Snit_inst3
%
</pre>
<p>The above example reveals how Snit names an instance's private
namespace; however, you should not write code that depends on the
specific naming convention, as it might change in future releases.</p>
</div>
<div id="subsection38" class="doctools_subsection"><h3><a name="subsection38">What is $win?</a></h3>
<p>The implicit argument <b class="variable">win</b> is defined for all Snit methods,
though it really makes sense only for those of
<span class="sectref"><a href="#section17">WIDGETS</a></span> and <span class="sectref"><a href="#section18">WIDGET ADAPTORS</a></span>. <b class="variable">$win</b> is simply
the original name of the object, whether it's been renamed or not.
For widgets and widgetadaptors, it is also therefore the name of a Tk
window.</p>
<p>When a <b class="cmd">snit::widgetadaptor</b> is used to modify the interface of a
widget or megawidget, it must rename the widget's original command and
replace it with its own.</p>
<p>Thus, using <b class="variable">win</b> whenever the Tk window name is called for
means that a <b class="cmd">snit::widget</b> or <b class="cmd">snit::widgetadaptor</b> can be
adapted by a <b class="cmd">snit::widgetadaptor</b>. See <span class="sectref"><a href="#section17">WIDGETS</a></span> for
more information.</p>
</div>
<div id="subsection39" class="doctools_subsection"><h3><a name="subsection39">How do I pass an instance method as a callback?</a></h3>
<p>It depends on the context.</p>
<p>Suppose in my application I have a <b class="cmd">dog</b> object named <b class="cmd">fido</b>,
and I want <b class="cmd">fido</b> to bark when a Tk button called <b class="cmd">.bark</b> is
pressed. In this case, I create the callback command in the usual
way, using <b class="cmd"><a href="../../../../index.html#list">list</a></b>:</p>
<pre class="doctools_example"> button .bark -text "Bark!" -command [list fido bark]
</pre>
<p>In typical Tcl style, we use a callback to hook two independent
components together. But suppose that the <b class="cmd">dog</b> object has
a graphical interface and owns the button itself? In this case,
the <b class="cmd">dog</b> must pass one of its own instance methods to the
button it owns. The obvious thing to do is this:</p>
<pre class="doctools_example">% snit::widget dog {
constructor {args} {
#...
button $win.barkbtn -text "Bark!" -command [list $self bark]
#...
}
}
::dog
%
</pre>
<p>(Note that in this example, our <b class="cmd">dog</b>
becomes a <b class="cmd">snit::widget</b>, because it has GUI behavior. See
<span class="sectref"><a href="#section17">WIDGETS</a></span> for more.) Thus, if we create a <b class="cmd">dog</b> called
<b class="cmd">.spot</b>, it will create a Tk button called <b class="cmd">.spot.barkbtn</b>;
when pressed, the button will call <b class="cmd">$self bark</b>.</p>
<p>Now, this will work--provided that <b class="cmd">.spot</b> is never renamed to
something else. But surely renaming widgets is
abnormal? And so it is--unless <b class="cmd">.spot</b> is the hull component of a
<b class="cmd">snit::widgetadaptor</b>. If it is, then it will be renamed, and
<b class="cmd">.spot</b> will become the name of the <b class="cmd">snit::widgetadaptor</b>
object. When the button is pressed, the command <b class="cmd">$self bark</b>
will be handled by the <b class="cmd">snit::widgetadaptor</b>, which might or might
not do the right thing.</p>
<p>There's a safer way to do it, and it looks like this:</p>
<pre class="doctools_example">% snit::widget dog {
constructor {args} {
#...
button $win.barkbtn -text "Bark!" -command [mymethod bark]
#...
}
}
::dog
%
</pre>
<p>The command <b class="cmd">mymethod</b> takes any number of arguments, and can be
used like <b class="cmd"><a href="../../../../index.html#list">list</a></b> to build up a callback command; the only
difference is that <b class="cmd">mymethod</b> returns a
form of the command that won't change even if the instance's name
changes.</p>
<p>On the other hand, you might prefer to allow a widgetadaptor to
override a method such that your renamed widget will call the
widgetadaptor's method instead of its own. In this case,
using <b class="cmd">[list $self bark]</b> will do what you want...but
this is a technique which should be used only in carefully controlled
circumstances.</p>
</div>
<div id="subsection40" class="doctools_subsection"><h3><a name="subsection40">How do I delegate instance methods to a component?</a></h3>
<p>See <span class="sectref"><a href="#section16">DELEGATION</a></span>.</p>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">INSTANCE VARIABLES</a></h2>
<div id="subsection41" class="doctools_subsection"><h3><a name="subsection41">What is an instance variable?</a></h3>
<p>An instance variable is a private variable associated with some
particular Snit object. Instance variables can be scalars or arrays.</p>
</div>
<div id="subsection42" class="doctools_subsection"><h3><a name="subsection42">How is a scalar instance variable defined?</a></h3>
<p>Scalar instance variables are defined in the type definition using the
<b class="cmd">variable</b> statement. You can simply name it, or you can
initialize it with a value:</p>
<pre class="doctools_example">snit::type mytype {
# Define variable "greeting" and initialize it with "Howdy!"
variable greeting "Howdy!"
}
</pre>
</div>
<div id="subsection43" class="doctools_subsection"><h3><a name="subsection43">How is an array instance variable defined?</a></h3>
<p>Array instance variables are also defined in the type definition
using the <b class="cmd">variable</b> command. You can initialize them at the same
time by specifying the <b class="const">-array</b> option:</p>
<pre class="doctools_example">snit::type mytype {
# Define array variable "greetings"
variable greetings -array {
formal "Good Evening"
casual "Howdy!"
}
}
</pre>
</div>
<div id="subsection44" class="doctools_subsection"><h3><a name="subsection44">What happens if I don't initialize an instance variable?</a></h3>
<p>Variables do not really exist until they are given values. If you
do not initialize a variable when you define it, then you must be
sure to assign a value to it (in the constructor, say, or in some
method) before you reference it.</p>
</div>
<div id="subsection45" class="doctools_subsection"><h3><a name="subsection45">Are there any limitations on instance variable names?</a></h3>
<p>Just a few.</p>
<p>First, every Snit object has a built-in instance variable called
<b class="variable">options</b>, which should never be redefined.</p>
<p>Second, all names beginning with "Snit_" are reserved for
use by Snit internal code.</p>
<p>Third, instance variable names containing the namespace delimiter
(<b class="const">::</b>) are likely to cause great confusion.</p>
</div>
<div id="subsection46" class="doctools_subsection"><h3><a name="subsection46">Do I need to declare my instance variables in my methods?</a></h3>
<p>No. Once you've defined an instance variable in the type definition,
it can be used in any instance code (instance methods, the
constructor, and the destructor) without declaration. This differs
from normal Tcl practice, in which all non-local variables in a proc
need to be declared.</p>
<p>There is a speed penalty to having all instance variables implicitly
available in all instance code. Even though your code need not
declare the variables explicitly, Snit must still declare them,
and that takes time. If you have ten instance variables, a method
that uses none of them must still pay the declaration penalty for
all ten. In most cases, the additional runtime cost is negligible.
If extreme cases, you might wish to avoid it; there are two methods
for doing so.</p>
<p>The first is to define a single instance variable, an array, and store
all of your instance data in the array. This way, you're only paying
the declaration penalty for one variable--and you probably need the
variable most of the time anyway. This method breaks down if your
instance variables include multiple arrays; in Tcl 8.5, however,
the <b class="cmd"><a href="../../../../index.html#dict">dict</a></b> command might come to your rescue.</p>
<p>The second method is to declare your instance variables explicitly
in your instance code, while <em>not</em> including them in the type
definition:</p>
<pre class="doctools_example">snit::type dog {
constructor {} {
variable mood
set mood happy
}
method setmood {newMood} {
variable mood
set mood $newMood
}
method getmood {} {
variable mood
return $mood
}
}
</pre>
<p>This allows you to ensure that only the required variables are
included in each method, at the cost of longer code and run-time
errors when you forget to declare a variable you need.</p>
</div>
<div id="subsection47" class="doctools_subsection"><h3><a name="subsection47">How do I pass an instance variable's name to another object?</a></h3>
<p>In Tk, it's common to pass a widget a variable name; for example, Tk
label widgets have a <b class="option">-textvariable</b> option which names the
variable which will contain the widget's text. This allows the
program to update the label's value just by assigning a new value to
the variable.</p>
<p>If you naively pass the instance variable name to the label widget,
you'll be confused by the result; Tk will assume that the name names a
global variable. Instead, you need to provide a fully-qualified
variable name. From within an instance method or a constructor, you
can fully qualify the variable's name using the <b class="cmd">myvar</b> command:</p>
<pre class="doctools_example">snit::widget mywidget {
variable labeltext ""
constructor {args} {
# ...
label $win.label -textvariable [myvar labeltext]
# ...
}
}
</pre>
</div>
<div id="subsection48" class="doctools_subsection"><h3><a name="subsection48">How do I make an instance variable public?</a></h3>
<p>Practically speaking, you don't. Instead, you'll implement public
variables as <span class="sectref"><a href="#section7">OPTIONS</a></span>.
Alternatively, you can write <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span> to set and get
the variable's value.</p>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">OPTIONS</a></h2>
<div id="subsection49" class="doctools_subsection"><h3><a name="subsection49">What is an option?</a></h3>
<p>A type's options are the equivalent of what other object-oriented
languages would call public member variables or properties: they are
data values which can be retrieved and (usually) set by the clients of
an object.</p>
<p>Snit's implementation of options follows the Tk model fairly exactly,
except that <b class="cmd">snit::type</b> objects usually don't interact with
<span class="sectref"><a href="#section19">THE TK OPTION DATABASE</a></span>; <b class="cmd">snit::widget</b> and
<b class="cmd">snit::widgetadaptor</b> objects, on the other hand, always do.</p>
</div>
<div id="subsection50" class="doctools_subsection"><h3><a name="subsection50">How do I define an option?</a></h3>
<p>Options are defined in the type definition using the <b class="cmd">option</b>
statement. Consider the following type, to be used in an application
that manages a list of dogs for a pet store:</p>
<pre class="doctools_example">snit::type dog {
option -breed -default mongrel
option -color -default brown
option -akc -default 0
option -shots -default 0
}
</pre>
<p>According to this, a dog has four notable properties: a
breed, a color, a flag that says whether it's pedigreed with the
American Kennel Club, and another flag that says whether it has had
its shots. The default dog, evidently, is a brown mutt.</p>
<p>There are a number of options you can specify when defining an option;
if <b class="const">-default</b> is the only one, you can omit the word
<b class="const">-default</b> as follows:</p>
<pre class="doctools_example">snit::type dog {
option -breed mongrel
option -color brown
option -akc 0
option -shots 0
}
</pre>
<p>If no <b class="const">-default</b> value is specified, the option's default value
will be the empty string (but see <span class="sectref"><a href="#section19">THE TK OPTION DATABASE</a></span>).</p>
<p>The Snit man page refers to options like these as "locally defined" options.</p>
</div>
<div id="subsection51" class="doctools_subsection"><h3><a name="subsection51">How can a client set options at object creation?</a></h3>
<p>The normal convention is that the client may pass any number of
options and their values after the object's name at object creation.
For example, the <b class="cmd">::dog</b> command defined in the previous answer can now
be used to create individual dogs. Any or all of the options may be
set at creation time.</p>
<pre class="doctools_example">% dog spot -breed beagle -color "mottled" -akc 1 -shots 1
::spot
% dog fido -shots 1
::fido
%
</pre>
<p>So <b class="cmd">::spot</b> is a pedigreed beagle; <b class="cmd">::fido</b> is a typical mutt,
but his owners evidently take care of him, because he's had his shots.</p>
<p><em>Note:</em> If the type defines a constructor, it can specify a
different object-creation syntax. See <span class="sectref"><a href="#section12">CONSTRUCTORS</a></span> for more
information.</p>
</div>
<div id="subsection52" class="doctools_subsection"><h3><a name="subsection52">How can a client retrieve an option's value?</a></h3>
<p>Retrieve option values using the <b class="method">cget</b> method:</p>
<pre class="doctools_example">% spot cget -color
mottled
% fido cget -breed
mongrel
%
</pre>
</div>
<div id="subsection53" class="doctools_subsection"><h3><a name="subsection53">How can a client set options after object creation?</a></h3>
<p>Any number of options may be set at one time using the
<b class="method">configure</b> instance method. Suppose that closer inspection
shows that ::fido is not a brown mongrel, but rather a rare Arctic Boar
Hound of a lovely dun color:</p>
<pre class="doctools_example">% fido configure -color dun -breed "Arctic Boar Hound"
% fido cget -color
dun
% fido cget -breed
Arctic Boar Hound
</pre>
<p>Alternatively, the <b class="method">configurelist</b> method takes a list of
options and values; occasionally this is more convenient:</p>
<pre class="doctools_example">% set features [list -color dun -breed "Arctic Boar Hound"]
-color dun -breed {Arctic Boar Hound}
% fido configurelist $features
% fido cget -color
dun
% fido cget -breed
Arctic Boar Hound
%
</pre>
<p>In Tcl 8.5, the <b class="cmd">*</b> keyword can be used with
<b class="method">configure</b> in this case:</p>
<pre class="doctools_example">% set features [list -color dun -breed "Arctic Boar Hound"]
-color dun -breed {Arctic Boar Hound}
% fido configure {*}$features
% fido cget -color
dun
% fido cget -breed
Arctic Boar Hound
%
</pre>
<p>The results are the same.</p>
</div>
<div id="subsection54" class="doctools_subsection"><h3><a name="subsection54">How should an instance method access an option value?</a></h3>
<p>There are two ways an instance method can set and retrieve an option's
value. One is to use the <b class="method">configure</b> and <b class="method">cget</b>
methods, as shown below.</p>
<pre class="doctools_example">% snit::type dog {
option -weight 10
method gainWeight {} {
set wt [$self cget -weight]
incr wt
$self configure -weight $wt
}
}
::dog
% dog fido
::fido
% fido cget -weight
10
% fido gainWeight
% fido cget -weight
11
%
</pre>
<p>Alternatively, Snit provides a built-in array instance variable called
<b class="variable">options</b>. The indices are the option names; the values are the
option values. The method <b class="method">gainWeight</b> can thus be rewritten as
follows:</p>
<pre class="doctools_example">
method gainWeight {} {
incr options(-weight)
}
</pre>
<p>As you can see, using the <b class="variable">options</b> variable involves considerably
less typing and is the usual way to do it. But if you use
<b class="const">-configuremethod</b> or <b class="const">-cgetmethod</b> (described in the following
answers), you might wish to use the <b class="method">configure</b> and
<b class="method">cget</b> methods anyway, just so that any special processing you've
implemented is sure to get done. Also, if the option is delegated to
a component then <b class="method">configure</b> and <b class="method">cget</b> are the only way
to access it without accessing the component directly. See
<span class="sectref"><a href="#section16">DELEGATION</a></span> for more information.</p>
</div>
<div id="subsection55" class="doctools_subsection"><h3><a name="subsection55">How can I make an option read-only?</a></h3>
<p>Define the option with <b class="const">-readonly yes</b>.</p>
<p>Suppose you've got an option that determines how
instances of your type are constructed; it must be set at creation
time, after which it's constant. For example, a dog never changes its
breed; it might or might not have had its shots, and if not can have
them at a later time. <b class="const">-breed</b> should be read-only, but
<b class="const">-shots</b> should not be.</p>
<pre class="doctools_example">% snit::type dog {
option -breed -default mongrel -readonly yes
option -shots -default no
}
::dog
% dog fido -breed retriever
::fido
% fido configure -shots yes
% fido configure -breed terrier
option -breed can only be set at instance creation
%
</pre>
</div>
<div id="subsection56" class="doctools_subsection"><h3><a name="subsection56">How can I catch accesses to an option's value?</a></h3>
<p>Define a <b class="const">-cgetmethod</b> for the option.</p>
</div>
<div id="subsection57" class="doctools_subsection"><h3><a name="subsection57">What is a -cgetmethod?</a></h3>
<p>A <b class="const">-cgetmethod</b> is a method that's called whenever the related
option's value is queried via the
<b class="method">cget</b> instance method. The handler can compute the option's
value, retrieve it from a database, or do anything else you'd like it to do.</p>
<p>Here's what the default behavior would look like if
written using a <b class="const">-cgetmethod</b>:</p>
<pre class="doctools_example">snit::type dog {
option -color -default brown -cgetmethod GetOption
method GetOption {option} {
return $options($option)
}
}
</pre>
<p>Any instance method can be used, provided that it takes one argument,
the name of the option whose value is to be retrieved.</p>
</div>
<div id="subsection58" class="doctools_subsection"><h3><a name="subsection58">How can I catch changes to an option's value?</a></h3>
<p>Define a <b class="const">-configuremethod</b> for the option.</p>
</div>
<div id="subsection59" class="doctools_subsection"><h3><a name="subsection59">What is a -configuremethod?</a></h3>
<p>A <b class="const">-configuremethod</b> is a method that's called whenever the
related option is given a new value via the <b class="method">configure</b> or
<b class="method">configurelist</b> instance methods. The method can
pass the value on to some other object, store it in a database, or do
anything else you'd like it to do.</p>
<p>Here's what the default configuration behavior would look like if
written using a <b class="const">-configuremethod</b>:</p>
<pre class="doctools_example">snit::type dog {
option -color -default brown -configuremethod SetOption
method SetOption {option value} {
set options($option) $value
}
}
</pre>
<p>Any instance method can be used, provided that it takes two arguments,
the name of the option and the new value.</p>
<p>Note that if your method doesn't store the value in the <b class="variable">options</b>
array, the <b class="variable">options</b> array won't get updated.</p>
</div>
<div id="subsection60" class="doctools_subsection"><h3><a name="subsection60">How can I validate an option's value?</a></h3>
<p>Define a <b class="const">-validatemethod</b>.</p>
</div>
<div id="subsection61" class="doctools_subsection"><h3><a name="subsection61">What is a -validatemethod?</a></h3>
<p>A <b class="const">-validatemethod</b> is a method that's called whenever the
related option is given a new value via the <b class="method">configure</b> or
<b class="method">configurelist</b> instance methods. It's the method's
responsibility to determine whether the new value is valid, and throw
an error if it isn't. The <b class="const">-validatemethod</b>, if any, is called
before the value is stored in the <b class="variable">options</b> array; in particular,
it's called before the <b class="const">-configuremethod</b>, if any.</p>
<p>For example, suppose an option always takes a Boolean value. You can
ensure that the value is in fact a valid Boolean like this:</p>
<pre class="doctools_example">% snit::type dog {
option -shots -default no -validatemethod BooleanOption
method BooleanOption {option value} {
if {![string is boolean -strict $value]} {
error "expected a boolean value, got \"$value\""
}
}
}
::dog
% dog fido
% fido configure -shots yes
% fido configure -shots NotABooleanValue
expected a boolean value, got "NotABooleanValue"
%
</pre>
<p>Note that the same <b class="const">-validatemethod</b> can be used to validate any number
of boolean options.</p>
<p>Any method can be a <b class="const">-validatemethod</b> provided that it takes
two arguments, the option name and the new option value.</p>
</div>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">TYPE VARIABLES</a></h2>
<div id="subsection62" class="doctools_subsection"><h3><a name="subsection62">What is a type variable?</a></h3>
<p>A type variable is a private variable associated with a Snit type
rather than with a particular instance of the type. In C++ and Java,
the term <i class="term">static member variable</i> is used for the same notion.
Type variables can be scalars or arrays.</p>
</div>
<div id="subsection63" class="doctools_subsection"><h3><a name="subsection63">How is a scalar type variable defined?</a></h3>
<p>Scalar type variables are defined in the type definition using the
<b class="cmd">typevariable</b> statement. You can simply name it, or you can
initialize it with a value:</p>
<pre class="doctools_example">
snit::type mytype {
# Define variable "greeting" and initialize it with "Howdy!"
typevariable greeting "Howdy!"
}
</pre>
<p>Every object of type <b class="cmd">mytype</b> now has access to a single variable
called <b class="variable">greeting</b>.</p>
</div>
<div id="subsection64" class="doctools_subsection"><h3><a name="subsection64">How is an array-valued type variable defined?</a></h3>
<p>Array-valued type variables are also defined using the
<b class="cmd">typevariable</b> command; to initialize them, include the
<b class="const">-array</b> option:</p>
<pre class="doctools_example">snit::type mytype {
# Define typearray variable "greetings"
typevariable greetings -array {
formal "Good Evening"
casual "Howdy!"
}
}
</pre>
</div>
<div id="subsection65" class="doctools_subsection"><h3><a name="subsection65">What happens if I don't initialize a type variable?</a></h3>
<p>Variables do not really exist until they are given values. If you
do not initialize a variable when you define it, then you must be
sure to assign a value to it (in the type constructor, say)
before you reference it.</p>
</div>
<div id="subsection66" class="doctools_subsection"><h3><a name="subsection66">Are there any limitations on type variable names?</a></h3>
<p>Type variable names have the same restrictions as
the names of <span class="sectref"><a href="#section6">INSTANCE VARIABLES</a></span> do.</p>
</div>
<div id="subsection67" class="doctools_subsection"><h3><a name="subsection67">Do I need to declare my type variables in my methods?</a></h3>
<p>No. Once you've defined a type variable in the type definition, it can
be used in <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span> or <span class="sectref"><a href="#section9">TYPE METHODS</a></span> without
declaration. This differs from normal Tcl practice, in which all
non-local variables in a proc need to be declared.</p>
<p>Type variables are subject to the same speed/readability tradeoffs
as instance variables; see
<span class="sectref"><a href="#subsection46">Do I need to declare my instance variables in my methods?</a></span></p>
</div>
<div id="subsection68" class="doctools_subsection"><h3><a name="subsection68">How do I pass a type variable's name to another object?</a></h3>
<p>In Tk, it's common to pass a widget a variable name; for example, Tk
label widgets have a <b class="option">-textvariable</b> option which names the
variable which will contain the widget's text. This allows the
program to update the label's value just by assigning a new value to
the variable.</p>
<p>If you naively pass a type variable name to the label widget, you'll
be confused by the result; Tk will assume that the name names a global
variable. Instead, you need to provide a fully-qualified variable
name. From within an instance method or a constructor, you can fully
qualify the type variable's name using the <b class="cmd">mytypevar</b> command:</p>
<pre class="doctools_example">snit::widget mywidget {
typevariable labeltext ""
constructor {args} {
# ...
label $win.label -textvariable [mytypevar labeltext]
# ...
}
}
</pre>
</div>
<div id="subsection69" class="doctools_subsection"><h3><a name="subsection69">How do I make a type variable public?</a></h3>
<p>There are two ways to do this. The preferred way is to write a pair
of <span class="sectref"><a href="#section9">TYPE METHODS</a></span> to set and query the type variable's value.</p>
<p>Type variables are stored in the type's namespace, which has
the same name as the type itself. Thus, you can also
publicize the type variable's name in your
documentation so that clients can access it directly. For example,</p>
<pre class="doctools_example">snit::type mytype {
typevariable myvariable
}
set ::mytype::myvariable "New Value"
</pre>
</div>
</div>
<div id="section9" class="doctools_section"><h2><a name="section9">TYPE METHODS</a></h2>
<div id="subsection70" class="doctools_subsection"><h3><a name="subsection70">What is a type method?</a></h3>
<p>A type method is a procedure associated with the type itself rather
than with any specific instance of the type, and called as a
subcommand of the type command.</p>
</div>
<div id="subsection71" class="doctools_subsection"><h3><a name="subsection71">How do I define a type method?</a></h3>
<p>Type methods are defined in the type definition using the
<b class="cmd">typemethod</b> statement:</p>
<pre class="doctools_example">snit::type dog {
# List of pedigreed dogs
typevariable pedigreed
typemethod pedigreedDogs {} {
return $pedigreed
}
}
</pre>
<p>Suppose the <b class="cmd">dog</b> type maintains a list of the names of the dogs
that have pedigrees. The <b class="cmd">pedigreedDogs</b> type method returns this
list.</p>
<p>The <b class="cmd">typemethod</b> statement looks just like a normal Tcl
<b class="cmd"><a href="../../../../index.html#proc">proc</a></b>, except that it appears in a <b class="cmd">snit::type</b> definition.
Notice that every type method gets an implicit argument called
<b class="variable">type</b>, which contains the fully-qualified type name.</p>
</div>
<div id="subsection72" class="doctools_subsection"><h3><a name="subsection72">How does a client call a type method?</a></h3>
<p>The type method name becomes a subcommand of the type's command. For
example, assuming that the constructor adds each pedigreed dog to the
list of <b class="variable">pedigreedDogs</b>,</p>
<pre class="doctools_example">snit::type dog {
option -pedigreed 0
# List of pedigreed dogs
typevariable pedigreed
typemethod pedigreedDogs {} {
return $pedigreed
}
# ...
}
dog spot -pedigreed 1
dog fido
foreach dog [dog pedigreedDogs] { ... }
</pre>
</div>
<div id="subsection73" class="doctools_subsection"><h3><a name="subsection73">Are there any limitations on type method names?</a></h3>
<p>Not really, so long as you avoid the standard type method names:
<b class="method">create</b>, <b class="method">destroy</b>, and <b class="method">info</b>.</p>
</div>
<div id="subsection74" class="doctools_subsection"><h3><a name="subsection74">How do I make a type method private?</a></h3>
<p>It's sometimes useful to define private type methods, that is, type
methods intended to be called only by other type or instance methods
of the same object.</p>
<p>Snit doesn't implement any access control on type methods; by
convention, the names of public methods begin with a lower-case
letter, and the names of private methods begin with an upper-case
letter.</p>
<p>Alternatively, a Snit <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> can be used as a private type method; see
<span class="sectref"><a href="#section10">PROCS</a></span>.</p>
</div>
<div id="subsection75" class="doctools_subsection"><h3><a name="subsection75">Are there any limitations on type method arguments?</a></h3>
<p>Method argument lists are defined just like normal Tcl proc argument
lists; in particular, they can include arguments with default values
and the <b class="variable">args</b> argument.</p>
<p>However, every type method is called with an implicit argument called
<b class="variable">type</b> that contains the name of the type command. In addition,
type methods should by convention avoid using the names of the
arguments implicitly defined for <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span>.</p>
</div>
<div id="subsection76" class="doctools_subsection"><h3><a name="subsection76">How does an instance or type method call a type method?</a></h3>
<p>If an instance or type method needs to call a type method, it should
use <b class="variable">$type</b> to do so:</p>
<pre class="doctools_example">snit::type dog {
typemethod pedigreedDogs {} { ... }
typemethod printPedigrees {} {
foreach obj [$type pedigreedDogs] { ... }
}
}
</pre>
</div>
<div id="subsection77" class="doctools_subsection"><h3><a name="subsection77">How do I pass a type method as a callback?</a></h3>
<p>It's common in Tcl to pass a snippet of code to another object, for it
to call later. Because types cannot be renamed, you can just
use the type name, or, if the callback is registered from within
a type method, <b class="variable">type</b>. For example, suppose we want to print a
list of pedigreed dogs when a Tk button is pushed:</p>
<pre class="doctools_example">
button .btn -text "Pedigrees" -command [list dog printPedigrees]
pack .btn
</pre>
<p>Alternatively, from a method or type method you can use the
<b class="cmd">mytypemethod</b> command, just as you would use <b class="cmd">mymethod</b>
to define a callback command for <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span>.</p>
</div>
<div id="subsection78" class="doctools_subsection"><h3><a name="subsection78">Can type methods be hierarchical?</a></h3>
<p>Yes, you can define hierarchical type methods in just the same way as
you can define hierarchical instance methods. See
<span class="sectref"><a href="#section5">INSTANCE METHODS</a></span> for more.</p>
</div>
</div>
<div id="section10" class="doctools_section"><h2><a name="section10">PROCS</a></h2>
<div id="subsection79" class="doctools_subsection"><h3><a name="subsection79">What is a proc?</a></h3>
<p>A Snit <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> is really just a Tcl proc defined within the type's
namespace. You can use procs for private code that isn't related to
any particular instance.</p>
</div>
<div id="subsection80" class="doctools_subsection"><h3><a name="subsection80">How do I define a proc?</a></h3>
<p>Procs are defined by including a <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> statement in the type
definition:</p>
<pre class="doctools_example">snit::type mytype {
# Pops and returns the first item from the list stored in the
# listvar, updating the listvar
proc pop {listvar} { ... }
# ...
}
</pre>
</div>
<div id="subsection81" class="doctools_subsection"><h3><a name="subsection81">Are there any limitations on proc names?</a></h3>
<p>Any name can be used, so long as it does not begin with <b class="const">Snit_</b>;
names beginning with <b class="const">Snit_</b> are reserved for Snit's own use.
However, the wise programmer will avoid <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> names (<b class="cmd"><a href="../../../../index.html#set">set</a></b>,
<b class="cmd"><a href="../../../../index.html#list">list</a></b>, <b class="cmd">if</b>, etc.) that would shadow standard Tcl
command names.</p>
<p><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> names, being private, should begin with a capital letter according
to convention; however, as there are typically no public <b class="cmd"><a href="../../../../index.html#proc">proc</a></b>s
in the type's namespace it doesn't matter much either way.</p>
</div>
<div id="subsection82" class="doctools_subsection"><h3><a name="subsection82">How does a method call a proc?</a></h3>
<p>Just like it calls any Tcl command. For example,</p>
<pre class="doctools_example">snit::type mytype {
# Pops and returns the first item from the list stored in the
# listvar, updating the listvar
proc pop {listvar} { ... }
variable requestQueue {}
# Get one request from the queue and process it.
method processRequest {} {
set req [pop requestQueue]
}
}
</pre>
</div>
<div id="subsection83" class="doctools_subsection"><h3><a name="subsection83">How can I pass a proc to another object as a callback?</a></h3>
<p>The <b class="cmd">myproc</b> command returns a callback command for the
<b class="cmd"><a href="../../../../index.html#proc">proc</a></b>, just as <b class="cmd">mymethod</b> does for a method.</p>
</div>
</div>
<div id="section11" class="doctools_section"><h2><a name="section11">TYPE CONSTRUCTORS</a></h2>
<div id="subsection84" class="doctools_subsection"><h3><a name="subsection84">What is a type constructor?</a></h3>
<p>A type constructor is a body of code that initializes the type as a
whole, rather like a C++ static initializer. The body of a type
constructor is executed once when the type is defined, and never
again.</p>
<p>A type can have at most one type constructor.</p>
</div>
<div id="subsection85" class="doctools_subsection"><h3><a name="subsection85">How do I define a type constructor?</a></h3>
<p>A type constructor is defined by using the <b class="cmd">typeconstructor</b>
statement in the type definition. For example, suppose the type uses
an array-valued type variable as a look-up table, and the values in
the array have to be computed at start-up.</p>
<pre class="doctools_example">% snit::type mytype {
typevariable lookupTable
typeconstructor {
array set lookupTable {key value...}
}
}
</pre>
</div>
</div>
<div id="section12" class="doctools_section"><h2><a name="section12">CONSTRUCTORS</a></h2>
<div id="subsection86" class="doctools_subsection"><h3><a name="subsection86">What is a constructor?</a></h3>
<p>In object-oriented programming, an object's constructor is responsible
for initializing the object completely at creation time. The constructor
receives the list of options passed to the <b class="cmd">snit::type</b> command's
<b class="method">create</b> method and can then do whatever it likes. That might include
computing instance variable values, reading data from files, creating
other objects, updating type and instance variables, and so forth.</p>
<p>The constructor's return value is ignored (unless it's an
error, of course).</p>
</div>
<div id="subsection87" class="doctools_subsection"><h3><a name="subsection87">How do I define a constructor?</a></h3>
<p>A constructor is defined by using the <b class="cmd">constructor</b> statement in
the type definition. Suppose that it's desired to keep a list of all
pedigreed dogs. The list can be maintained in a
type variable and retrieved by a type method. Whenever a dog is
created, it can add itself to the list--provided that it's registered
with the American Kennel Club.</p>
<pre class="doctools_example">% snit::type dog {
option -akc 0
typevariable akcList {}
constructor {args} {
$self configurelist $args
if {$options(-akc)} {
lappend akcList $self
}
}
typemethod akclist {} {
return $akcList
}
}
::dog
% dog spot -akc 1
::spot
% dog fido
::fido
% dog akclist
::spot
%
</pre>
</div>
<div id="subsection88" class="doctools_subsection"><h3><a name="subsection88">What does the default constructor do?</a></h3>
<p>If you don't provide a constructor explicitly, you get the default
constructor, which is identical to the explicitly-defined
constructor shown here:</p>
<pre class="doctools_example">snit::type dog {
constructor {args} {
$self configurelist $args
}
}
</pre>
<p>When the constructor is called, <b class="variable">args</b> will be set to the list of
arguments that follow the object's name. The constructor is allowed
to interpret this list any way it chooses; the normal convention is
to assume that it's a list of option names and values, as shown in the
example above. If you simply want to save the option values, you
should use the <b class="method">configurelist</b> method, as shown.</p>
</div>
<div id="subsection89" class="doctools_subsection"><h3><a name="subsection89">Can I choose a different set of arguments for the constructor?</a></h3>
<p>Yes, you can. For example, suppose we wanted to be sure that the
breed was explicitly stated for every dog at creation time, and
couldn't be changed thereafter. One way to do that is as follows:</p>
<pre class="doctools_example">% snit::type dog {
variable breed
option -color brown
option -akc 0
constructor {theBreed args} {
set breed $theBreed
$self configurelist $args
}
method breed {} { return $breed }
}
::dog
% dog spot dalmatian -color spotted -akc 1
::spot
% spot breed
dalmatian
</pre>
<p>The drawback is that this syntax is non-standard, and may
limit the compatibility of your new type with other people's code.
For example, Snit assumes that it can create
<span class="sectref"><a href="#section14">COMPONENTS</a></span> using the standard creation syntax.</p>
</div>
<div id="subsection90" class="doctools_subsection"><h3><a name="subsection90">Are there any limitations on constructor arguments?</a></h3>
<p>Constructor argument lists are subject to the same limitations
as those on instance method argument lists. It has the
same implicit arguments, and can contain default values and the
<b class="variable">args</b> argument.</p>
</div>
<div id="subsection91" class="doctools_subsection"><h3><a name="subsection91">Is there anything special about writing the constructor?</a></h3>
<p>Yes. Writing the constructor can be tricky if you're delegating
options to components, and there are specific issues relating to
<b class="cmd">snit::widget</b>s and <b class="cmd">snit::widgetadaptor</b>s. See
<span class="sectref"><a href="#section16">DELEGATION</a></span>, <span class="sectref"><a href="#section17">WIDGETS</a></span>,
<span class="sectref"><a href="#section18">WIDGET ADAPTORS</a></span>, and <span class="sectref"><a href="#section19">THE TK OPTION DATABASE</a></span>.</p>
</div>
</div>
<div id="section13" class="doctools_section"><h2><a name="section13">DESTRUCTORS</a></h2>
<div id="subsection92" class="doctools_subsection"><h3><a name="subsection92">What is a destructor?</a></h3>
<p>A destructor is a special kind of method that's called when an object
is destroyed. It's responsible for doing any necessary clean-up when
the object goes away: destroying <span class="sectref"><a href="#section14">COMPONENTS</a></span>, closing files,
and so forth.</p>
</div>
<div id="subsection93" class="doctools_subsection"><h3><a name="subsection93">How do I define a destructor?</a></h3>
<p>Destructors are defined by using the <b class="cmd">destructor</b> statement in the
type definition.</p>
<p>Suppose we're maintaining a list of pedigreed dogs;
then we'll want to remove dogs from it when they are destroyed.</p>
<pre class="doctools_example">snit::type dog {
option -akc 0
typevariable akcList {}
constructor {args} {
$self configurelist $args
if {$options(-akc)} {
lappend akcList $self
}
}
destructor {
set ndx [lsearch $akcList $self]
if {$ndx != -1} {
set akcList [lreplace $akcList $ndx $ndx]
}
}
typemethod akclist {} {
return $akcList
}
}
</pre>
</div>
<div id="subsection94" class="doctools_subsection"><h3><a name="subsection94">Are there any limitations on destructor arguments?</a></h3>
<p>Yes; a destructor has no explicit arguments.</p>
</div>
<div id="subsection95" class="doctools_subsection"><h3><a name="subsection95">What implicit arguments are passed to the destructor?</a></h3>
<p>The destructor gets the same implicit arguments that are passed to
<span class="sectref"><a href="#section5">INSTANCE METHODS</a></span>: <b class="variable">type</b>, <b class="variable">selfns</b>, <b class="variable">win</b>, and
<b class="variable">self</b>.</p>
</div>
<div id="subsection96" class="doctools_subsection"><h3><a name="subsection96">Must components be destroyed explicitly?</a></h3>
<p>Yes and no.</p>
<p>Any Tk widgets created by a <b class="cmd">snit::widget</b> or
<b class="cmd">snit::widgetadaptor</b> will be destroyed automatically by Tk
when the megawidget is destroyed, in keeping with normal Tk behavior
(destroying a parent widget destroys the whole tree).</p>
<p>Components of normal <b class="cmd">snit::types</b>, on the other hand,
are never destroyed automatically, nor are non-widget components
of Snit megawidgets. If your object creates them in its
constructor, then it should generally destroy them in its destructor.</p>
</div>
<div id="subsection97" class="doctools_subsection"><h3><a name="subsection97">Is there any special about writing a destructor?</a></h3>
<p>Yes. If an object's constructor throws an error, the object's
destructor will be called to clean up; this means that the object
might not be completely constructed when the destructor is called.
This can cause the destructor to throw its own error; the result
is usually misleading, confusing, and unhelpful. Consequently, it's
important to write your destructor so that it's fail-safe.</p>
<p>For example, a <b class="cmd">dog</b> might create a <b class="cmd">tail</b> component; the
component will need to be destroyed. But suppose there's an error
while processing the creation options--the destructor will be called,
and there will be no <b class="cmd">tail</b> to destroy. The simplest solution is
generally to catch and ignore any errors while destroying components.</p>
<pre class="doctools_example">snit::type dog {
component tail
constructor {args} {
$self configurelist $args
set tail [tail %AUTO%]
}
destructor {
catch {$tail destroy}
}
}
</pre>
</div>
</div>
<div id="section14" class="doctools_section"><h2><a name="section14">COMPONENTS</a></h2>
<div id="subsection98" class="doctools_subsection"><h3><a name="subsection98">What is a component?</a></h3>
<p>Often an object will create and manage a number of other objects. A
Snit megawidget, for example, will often create a number of Tk
widgets. These objects are part of the main object; it is composed
of them, so they are called components of the object.</p>
<p>But Snit also has a more precise meaning for
<span class="sectref"><a href="#section14">COMPONENT</a></span>. The components of a Snit object are those
objects to which methods or options can be delegated.
(See <span class="sectref"><a href="#section16">DELEGATION</a></span> for more information about delegation.)</p>
</div>
<div id="subsection99" class="doctools_subsection"><h3><a name="subsection99">How do I declare a component?</a></h3>
<p>First, you must decide what role a component plays within your object,
and give the role a name. Then, you declare the component using its
role name and the <b class="cmd">component</b> statement. The <b class="cmd">component</b>
statement declares an <i class="term">instance variable</i> which is used to
store the component's command name when the component is created.</p>
<p>For example, suppose your <b class="cmd">dog</b> object
creates a <b class="cmd">tail</b> object (the better to wag with, no doubt):</p>
<pre class="doctools_example">snit::type dog {
component mytail
constructor {args} {
# Create and save the component's command
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
method wag {} {
$mytail wag
}
}
</pre>
<p>As shown here, it doesn't matter what the <b class="cmd">tail</b> object's real
name is; the <b class="cmd">dog</b> object refers to it by its component name.</p>
<p>The above example shows one way to delegate the <b class="method">wag</b> method to
the <b class="variable">mytail</b> component; see <span class="sectref"><a href="#section16">DELEGATION</a></span> for an easier way.</p>
</div>
<div id="subsection100" class="doctools_subsection"><h3><a name="subsection100">How is a component named?</a></h3>
<p>A component has two names. The first name is that of the component
variable; this represents the role the component object plays within
the Snit object. This is the component name proper, and is the name
used to refer to the component within Snit code. The second name is
the name of the actual component object created by the Snit object's
constructor. This second name is always a Tcl command name, and is
referred to as the component's object name.</p>
<p>In the example in the previous question, the component name is
<b class="const">mytail</b>; the <b class="const">mytail</b> component's object name is chosen
automatically by Snit since <b class="const">%AUTO%</b> was used when the component
object was created.</p>
</div>
<div id="subsection101" class="doctools_subsection"><h3><a name="subsection101">Are there any limitations on component names?</a></h3>
<p>Yes. <b class="cmd">snit::widget</b> and <b class="cmd">snit::widgetadaptor</b> objects have a special
component called the <b class="variable">hull</b> component; thus, the name <b class="variable">hull</b>
should be used for no other purpose.</p>
<p>Otherwise, since component names are in fact instance variable names
they must follow the rules for <span class="sectref"><a href="#section6">INSTANCE VARIABLES</a></span>.</p>
</div>
<div id="subsection102" class="doctools_subsection"><h3><a name="subsection102">What is an owned component?</a></h3>
<p>An <i class="term">owned</i> component is a component whose object command's
lifetime is controlled by the <b class="cmd">snit::type</b> or <b class="cmd">snit::widget</b>.</p>
<p>As stated above, a component is an object to
which our object can delegate methods or options. Under this
definition, our object will usually create its component objects,
but not necessarily. Consider the following: a dog object has a tail
component; but tail knows that it's part of the dog:</p>
<pre class="doctools_example">snit::type dog {
component mytail
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
destructor {
catch {$mytail destroy}
}
delegate method wagtail to mytail as wag
method bark {} {
return "$self barked."
}
}
snit::type tail {
component mydog
option -partof -readonly yes
constructor {args} {
$self configurelist $args
set mydog $options(-partof)
}
method wag {} {
return "Wag, wag."
}
method pull {} {
$mydog bark
}
}
</pre>
<p>Thus, if you ask a dog to wag its tail, it tells its tail to wag;
and if you pull the dog's tail, the tail tells the dog to bark. In
this scenario, the tail is a component of the dog, and the dog is a
component of the tail, but the dog owns the tail and not the other way
around.</p>
</div>
<div id="subsection103" class="doctools_subsection"><h3><a name="subsection103">What does the install command do?</a></h3>
<p>The <b class="cmd">install</b> command creates an owned component using a specified
command, and assigns the result to the component's instance variable.
For example:</p>
<pre class="doctools_example">snit::type dog {
component mytail
constructor {args} {
# set mytail [tail %AUTO% -partof $self]
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
</pre>
<p>In a <b class="cmd">snit::type</b>'s code, the <b class="cmd">install</b>
command shown above is equivalent to the <b class="const">set mytail</b> command
that's commented out. In a <b class="cmd">snit::widget</b>'s or
<b class="cmd">snit::widgetadaptor</b>'s, code, however, the
<b class="cmd">install</b> command also queries <span class="sectref"><a href="#section19">THE TK OPTION DATABASE</a></span>
and initializes the new component's options accordingly. For consistency,
it's a good idea to get in the habit of using <b class="cmd">install</b> for all
owned components.</p>
</div>
<div id="subsection104" class="doctools_subsection"><h3><a name="subsection104">Must owned components be created in the constructor?</a></h3>
<p>No, not necessarily. In fact, there's no reason why an
object can't destroy and recreate a component multiple times over
its own lifetime.</p>
</div>
<div id="subsection105" class="doctools_subsection"><h3><a name="subsection105">Are there any limitations on component object names?</a></h3>
<p>Yes.</p>
<p>Component objects which are Tk widgets or megawidgets must have valid
Tk window names.</p>
<p>Component objects which are not widgets or megawidgets must have
fully-qualified command names, i.e., names which include the full
namespace of the command. Note that Snit always creates objects with
fully qualified names.</p>
<p>Next, the object names of components and owned by your object
must be unique. This is no problem for widget components, since
widget names are always unique; but consider the following code:</p>
<pre class="doctools_example">snit::type tail { ... }
snit::type dog {
delegate method wag to mytail
constructor {} {
install mytail using tail mytail
}
}
</pre>
<p>This code uses the component name, <b class="const">mytail</b>, as the component object
name. This is not good, and here's why: Snit instance code executes
in the Snit type's namespace. In this case, the <b class="const">mytail</b> component is
created in the <b class="const">::dog::</b> namespace, and will thus have the name
<b class="cmd">::dog::mytail</b>.</p>
<p>Now, suppose you create two dogs. Both dogs will attempt to
create a tail called <b class="cmd">::dog::mytail</b>. The first will succeed,
and the second will fail, since Snit won't let you create an object if
its name is already a command. Here are two ways to avoid this situation:</p>
<p>First, if the component type is a <b class="cmd">snit::type</b> you can
specify <b class="const">%AUTO%</b> as its name, and be guaranteed to get a unique name.
This is the safest thing to do:</p>
<pre class="doctools_example">
install mytail using tail %AUTO%
</pre>
<p>If the component type isn't a <b class="cmd">snit::type</b> you can create
the component in the object's instance namespace:</p>
<pre class="doctools_example">
install mytail using tail ${selfns}::mytail
</pre>
<p>Make sure you pick a unique name within the instance namespace.</p>
</div>
<div id="subsection106" class="doctools_subsection"><h3><a name="subsection106">Must I destroy the components I own?</a></h3>
<p>That depends. When a parent widget is destroyed, all child widgets
are destroyed automatically. Thus, if your object is a <b class="cmd">snit::widget</b>
or <b class="cmd">snit::widgetadaptor</b> you don't need to destroy any components
that are widgets, because they will generally be children or
descendants of your megawidget.</p>
<p>If your object is an instance of <b class="cmd">snit::type</b>, though, none of its
owned components will be destroyed automatically, nor will be
non-widget components of a <b class="cmd">snit::widget</b> be destroyed
automatically. All such owned components must be destroyed
explicitly, or they won't be destroyed at all.</p>
</div>
<div id="subsection107" class="doctools_subsection"><h3><a name="subsection107">Can I expose a component's object command as part of my interface?</a></h3>
<p>Yes, and there are two ways to do it. The most appropriate way is
usually to use <span class="sectref"><a href="#section16">DELEGATION</a></span>. Delegation allows you to pass
the options and methods you specify along to particular components.
This effectively hides the components from the users of your type, and
ensures good encapsulation.</p>
<p>However, there are times when it's appropriate, not to mention
simpler, just to make the entire component part of your type's public
interface.</p>
</div>
<div id="subsection108" class="doctools_subsection"><h3><a name="subsection108">How do I expose a component's object command?</a></h3>
<p>When you declare the component, specify the <b class="cmd">component</b>
statement's <b class="const">-public</b> option. The value of this option is the
name of a method which will be delegated to your component's object
command.</p>
<p>For example, supposed you've written a combobox megawidget which owns
a listbox widget, and you want to make the listbox's entire interface
public. You can do it like this:</p>
<pre class="doctools_example">snit::widget combobox {
component listbox -public listbox
constructor {args} {
install listbox using listbox $win.listbox ....
}
}
combobox .mycombo
.mycombo listbox configure -width 30
</pre>
<p>Your comobox widget, <b class="cmd">.mycombo</b>, now has a <b class="method">listbox</b> method
which has all of the same subcommands as the listbox widget itself.
Thus, the above code sets the listbox component's width to 30.</p>
<p>Usually you'll let the method name be the same as the component name;
however, you can name it anything you like.</p>
</div>
</div>
<div id="section15" class="doctools_section"><h2><a name="section15">TYPE COMPONENTS</a></h2>
<div id="subsection109" class="doctools_subsection"><h3><a name="subsection109">What is a type component?</a></h3>
<p>A type component is a component that belongs to the type itself
instead of to a particular instance of the type. The relationship
between components and type components is the same as the
relationship between <span class="sectref"><a href="#section6">INSTANCE VARIABLES</a></span> and
<span class="sectref"><a href="#section8">TYPE VARIABLES</a></span>. Both <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span> and
<span class="sectref"><a href="#section9">TYPE METHODS</a></span> can be delegated to type components.</p>
<p>Once you understand <span class="sectref"><a href="#section14">COMPONENTS</a></span> and
<span class="sectref"><a href="#section16">DELEGATION</a></span>, type components are just more of the same.</p>
</div>
<div id="subsection110" class="doctools_subsection"><h3><a name="subsection110">How do I declare a type component?</a></h3>
<p>Declare a type component using the <b class="cmd">typecomponent</b> statement. It
takes the same options (<b class="const">-inherit</b> and <b class="const">-public</b>) as the
<b class="cmd">component</b> statement does, and defines a type variable to hold
the type component's object command.</p>
<p>Suppose in your model you've got many dogs, but only one
veterinarian. You might make the veterinarian a type component.</p>
<pre class="doctools_example">snit::type veterinarian { ... }
snit::type dog {
typecomponent vet
# ...
}
</pre>
</div>
<div id="subsection111" class="doctools_subsection"><h3><a name="subsection111">How do I install a type component?</a></h3>
<p>Just use the <b class="cmd"><a href="../../../../index.html#set">set</a></b> command to assign the component's object
command to the type component. Because types
(even <b class="cmd">snit::widget</b> types) are not widgets, and do not have
options anyway, the extra features of the <b class="cmd">install</b> command are
not needed.</p>
<p>You'll usually install type components in the type constructor, as
shown here:</p>
<pre class="doctools_example">snit::type veterinarian { ... }
snit::type dog {
typecomponent vet
typeconstructor {
set vet [veterinarian %AUTO%]
}
}
</pre>
</div>
<div id="subsection112" class="doctools_subsection"><h3><a name="subsection112">Are there any limitations on type component names?</a></h3>
<p>Yes, the same as on <span class="sectref"><a href="#section6">INSTANCE VARIABLES</a></span>,
<span class="sectref"><a href="#section8">TYPE VARIABLES</a></span>, and normal <span class="sectref"><a href="#section14">COMPONENTS</a></span>.</p>
</div>
</div>
<div id="section16" class="doctools_section"><h2><a name="section16">DELEGATION</a></h2>
<div id="subsection113" class="doctools_subsection"><h3><a name="subsection113">What is delegation?</a></h3>
<p>Delegation, simply put, is when you pass a task you've been given to
one of your assistants. (You do have assistants, don't you?) Snit
objects can do the same thing. The following example shows one way in
which the <b class="cmd">dog</b> object can delegate its <b class="cmd">wag</b> method and its
<b class="option">-taillength</b> option to its <b class="cmd">tail</b> component.</p>
<pre class="doctools_example">snit::type dog {
variable mytail
option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption
method SetTailOption {option value} {
$mytail configure $option $value
}
method GetTailOption {option} {
$mytail cget $option
}
method wag {} {
$mytail wag
}
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
</pre>
<p>This is the hard way to do it, by it demonstrates what delegation is
all about. See the following answers for the easy way to do it.</p>
<p>Note that the constructor calls the <b class="method">configurelist</b> method
<b class="cmd"><a href="../../../../index.html#after">after</a></b> it creates its <b class="cmd">tail</b>; otherwise,
if <b class="option">-taillength</b> appeared in the list of <b class="variable">args</b> we'd get an
error.</p>
</div>
<div id="subsection114" class="doctools_subsection"><h3><a name="subsection114">How can I delegate a method to a component object?</a></h3>
<p>Delegation occurs frequently enough that Snit makes it easy. Any
method can be delegated to any component or type component
by placing a single <b class="cmd">delegate</b> statement in the type definition.
(See <span class="sectref"><a href="#section14">COMPONENTS</a></span> and <span class="sectref"><a href="#section15">TYPE COMPONENTS</a></span>
for more information about component names.)</p>
<p>For example, here's a much better way to delegate the <b class="cmd">dog</b>
object's <b class="cmd">wag</b> method:</p>
<pre class="doctools_example">% snit::type dog {
delegate method wag to mytail
constructor {} {
install mytail using tail %AUTO%
}
}
::dog
% snit::type tail {
method wag {} { return "Wag, wag, wag."}
}
::tail
% dog spot
::spot
% spot wag
Wag, wag, wag.
</pre>
<p>This code has the same effect as the code shown under the previous
question: when a <b class="cmd">dog</b>'s <b class="cmd">wag</b> method is called, the call and
its arguments are passed along automatically to the <b class="cmd">tail</b> object.</p>
<p>Note that when a component is mentioned in a <b class="cmd">delegate</b> statement,
the component's instance variable is defined implicitly. However,
it's still good practice to declare it explicitly using the
<b class="cmd">component</b> statement.</p>
<p>Note also that you can define a method name using the <b class="cmd"><a href="../../../../index.html#method">method</a></b>
statement, or you can define it using <b class="cmd">delegate</b>; you can't do
both.</p>
</div>
<div id="subsection115" class="doctools_subsection"><h3><a name="subsection115">Can I delegate to a method with a different name?</a></h3>
<p>Suppose you wanted to delegate the <b class="cmd">dog</b>'s <b class="method">wagtail</b> method to
the <b class="cmd">tail</b>'s <b class="method">wag</b> method. After all you wag the tail, not
the dog. It's easily done:</p>
<pre class="doctools_example">snit::type dog {
delegate method wagtail to mytail as wag
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
</pre>
</div>
<div id="subsection116" class="doctools_subsection"><h3><a name="subsection116">Can I delegate to a method with additional arguments?</a></h3>
<p>Suppose the <b class="cmd">tail</b>'s <b class="method">wag</b> method takes as an argument the
number of times the tail should be wagged. You want to delegate the
<b class="cmd">dog</b>'s <b class="method">wagtail</b> method to the <b class="cmd">tail</b>'s <b class="method">wag</b>
method, specifying that the tail should be wagged exactly three times.
This is easily done, too:</p>
<pre class="doctools_example">snit::type dog {
delegate method wagtail to mytail as {wag 3}
# ...
}
snit::type tail {
method wag {count} {
return [string repeat "Wag " $count]
}
# ...
}
</pre>
</div>
<div id="subsection117" class="doctools_subsection"><h3><a name="subsection117">Can I delegate a method to something other than an object?</a></h3>
<p>Normal method delegation assumes that you're delegating a method (a
subcommand of an object command) to a method of another object (a
subcommand of a different object command). But not all Tcl objects
follow Tk conventions, and not everything you'd to which you'd like
to delegate a method is necessary an object. Consequently, Snit makes
it easy to delegate a method to pretty much anything you like using
the <b class="cmd">delegate</b> statement's <b class="const">using</b> clause.</p>
<p>Suppose your dog simulation stores dogs in a database, each dog as a
single record. The database API you're using provides a number of
commands to manage records; each takes the record ID (a string you
choose) as its first argument. For example, <b class="cmd">saverec</b>
saves a record. If you let the record ID be the name of the dog
object, you can delegate the dog's <b class="method">save</b> method to the
<b class="cmd">saverec</b> command as follows:</p>
<pre class="doctools_example">snit::type dog {
delegate method save using {saverec %s}
}
</pre>
<p>The <b class="const">%s</b> is replaced with the instance name when the
<b class="method">save</b> method is called; any additional arguments are the
appended to the resulting command.</p>
<p>The <b class="const">using</b> clause understands a number of other %-conversions;
in addition to the instance name, you can substitute in the method
name (<b class="const">%m</b>), the type name (<b class="const">%t</b>), the instance
namespace (<b class="const">%n</b>), the Tk window name (<b class="const">%w</b>), and,
if a component or typecomponent name was given in the
<b class="cmd">delegate</b> statement, the component's object command
(<b class="const">%c</b>).</p>
</div>
<div id="subsection118" class="doctools_subsection"><h3><a name="subsection118">How can I delegate a method to a type component object?</a></h3>
<p>Just exactly as you would to a component object. The
<b class="cmd">delegate method</b> statement accepts both component and type
component names in its <b class="const">to</b> clause.</p>
</div>
<div id="subsection119" class="doctools_subsection"><h3><a name="subsection119">How can I delegate a type method to a type component object?</a></h3>
<p>Use the <b class="cmd">delegate typemethod</b> statement. It works like
<b class="cmd">delegate method</b>, with these differences: first, it defines
a type method instead of an instance method; second, the
<b class="const">using</b> clause ignores the <b class="const">%s</b>, <b class="const">%n</b>,
and <b class="const">%w</b> %-conversions.</p>
<p>Naturally, you can't delegate a type method to an instance
component...Snit wouldn't know which instance should receive it.</p>
</div>
<div id="subsection120" class="doctools_subsection"><h3><a name="subsection120">How can I delegate an option to a component object?</a></h3>
<p>The first question in this section (see <span class="sectref"><a href="#section16">DELEGATION</a></span>) shows
one way to delegate an option to a component; but this pattern occurs
often enough that Snit makes it easy. For example, every <b class="cmd">tail</b>
object has a <b class="option">-length</b> option; we want to allow the creator of
a <b class="cmd">dog</b> object to set the tail's length. We can do this:</p>
<pre class="doctools_example">% snit::type dog {
delegate option -length to mytail
constructor {args} {
install mytail using tail %AUTO% -partof $self
$self configurelist $args
}
}
::dog
% snit::type tail {
option -partof
option -length 5
}
::tail
% dog spot -length 7
::spot
% spot cget -length
7
</pre>
<p>This produces nearly the same result as the <b class="const">-configuremethod</b> and
<b class="const">-cgetmethod</b> shown under the first question in this
section: whenever a <b class="cmd">dog</b> object's <b class="option">-length</b> option is set
or retrieved, the underlying <b class="cmd">tail</b> object's option is set or
retrieved in turn.</p>
<p>Note that you can define an option name using the <b class="cmd">option</b>
statement, or you can define it using <b class="cmd">delegate</b>; you can't do
both.</p>
</div>
<div id="subsection121" class="doctools_subsection"><h3><a name="subsection121">Can I delegate to an option with a different name?</a></h3>
<p>In the previous answer we delegated the <b class="cmd">dog</b>'s <b class="option">-length</b>
option down to its <b class="cmd">tail</b>. This is, of course, wrong. The dog
has a length, and the tail has a length, and they are different. What
we'd really like to do is give the <b class="cmd">dog</b> a <b class="option">-taillength</b>
option, but delegate it to the <b class="cmd">tail</b>'s <b class="option">-length</b> option:</p>
<pre class="doctools_example">snit::type dog {
delegate option -taillength to mytail as -length
constructor {args} {
set mytail [tail %AUTO% -partof $self]
$self configurelist $args
}
}
</pre>
</div>
<div id="subsection122" class="doctools_subsection"><h3><a name="subsection122">How can I delegate any unrecognized method or option to a component object?</a></h3>
<p>It may happen that a Snit object gets most of its behavior from one of
its components. This often happens with <b class="cmd">snit::widgetadaptors</b>,
for example, where we wish to slightly the modify the behavior of an
existing widget. To carry on with our <b class="cmd">dog</b> example, however, suppose
that we have a <b class="cmd">snit::type</b> called <b class="cmd">animal</b> that implements a
variety of animal behaviors--moving, eating, sleeping, and so forth.
We want our <b class="cmd">dog</b> objects to inherit these same behaviors, while
adding dog-like behaviors of its own.
Here's how we can give a <b class="cmd">dog</b> methods and options of its own
while delegating all other methods and options to its <b class="cmd">animal</b>
component:</p>
<pre class="doctools_example">snit::type dog {
delegate option * to animal
delegate method * to animal
option -akc 0
constructor {args} {
install animal using animal %AUTO% -name $self
$self configurelist $args
}
method wag {} {
return "$self wags its tail"
}
}
</pre>
<p>That's it. A <b class="cmd">dog</b> is now an <b class="cmd">animal</b> that has a
<b class="option">-akc</b> option and can <b class="cmd">wag</b> its tail.</p>
<p>Note that we don't need to specify the full list of method names or
option names that <b class="cmd">animal</b> will receive.
It gets anything <b class="cmd">dog</b> doesn't recognize--and if it doesn't
recognize it either, it will simply throw an error, just as it should.</p>
<p>You can also delegate all unknown type methods to a type component
using <b class="cmd">delegate typemethod *</b>.</p>
</div>
<div id="subsection123" class="doctools_subsection"><h3><a name="subsection123">How can I delegate all but certain methods or options to a component?</a></h3>
<p>In the previous answer, we said that every <b class="cmd">dog</b> is
an <b class="cmd">animal</b> by delegating all unknown methods and options to the
<b class="variable">animal</b> component. But what if the <b class="cmd">animal</b> type has some
methods or options that we'd like to suppress?</p>
<p>One solution is to explicitly delegate all the options and methods,
and forgo the convenience of <b class="cmd">delegate method *</b> and
<b class="cmd">delegate option *</b>. But if we wish to suppress only a few
options or methods, there's an easier way:</p>
<pre class="doctools_example">snit::type dog {
delegate option * to animal except -numlegs
delegate method * to animal except {fly climb}
# ...
constructor {args} {
install animal using animal %AUTO% -name $self -numlegs 4
$self configurelist $args
}
# ...
}
</pre>
<p>Dogs have four legs, so we specify that explicitly when we create the
<b class="variable">animal</b> component, and explicitly exclude <b class="option">-numlegs</b> from the
set of delegated options. Similarly, dogs can neither
<b class="method">fly</b> nor <b class="method">climb</b>,
so we exclude those <b class="cmd">animal</b> methods as shown.</p>
</div>
<div id="subsection124" class="doctools_subsection"><h3><a name="subsection124">Can a hierarchical method be delegated?</a></h3>
<p>Yes; just specify multiple words in the delegated method's name:</p>
<pre class="doctools_example">snit::type tail {
method wag {} {return "Wag, wag"}
method droop {} {return "Droop, droop"}
}
snit::type dog {
delegate method {tail wag} to mytail
delegate method {tail droop} to mytail
# ...
constructor {args} {
install mytail using tail %AUTO%
$self configurelist $args
}
# ...
}
</pre>
<p>Unrecognized hierarchical methods can also be delegated; the following
code delegates all subcommands of the "tail" method to the "mytail"
component:</p>
<pre class="doctools_example">snit::type dog {
delegate method {tail *} to mytail
# ...
}
</pre>
</div>
</div>
<div id="section17" class="doctools_section"><h2><a name="section17">WIDGETS</a></h2>
<div id="subsection125" class="doctools_subsection"><h3><a name="subsection125">What is a snit::widget?</a></h3>
<p>A <b class="cmd">snit::widget</b> is the Snit version of what Tcl programmers
usually call a <i class="term">megawidget</i>: a widget-like object usually
consisting of one or more Tk widgets all contained within a Tk frame.</p>
<p>A <b class="cmd">snit::widget</b> is also a special kind of <b class="cmd">snit::type</b>. Just
about everything in this FAQ list that relates to <b class="cmd">snit::types</b>
also applies to <b class="cmd">snit::widgets</b>.</p>
</div>
<div id="subsection126" class="doctools_subsection"><h3><a name="subsection126">How do I define a snit::widget?</a></h3>
<p><b class="cmd">snit::widgets</b> are defined using the <b class="cmd">snit::widget</b> command,
just as <b class="cmd">snit::types</b> are defined by the <b class="cmd">snit::type</b> command.</p>
<p>The body of the definition can contain all of the same kinds of
statements, plus a couple of others which will be mentioned below.</p>
</div>
<div id="subsection127" class="doctools_subsection"><h3><a name="subsection127">How do snit::widgets differ from snit::types?</a></h3>
<ul class="doctools_itemized">
<li><p>The name of an instance of a <b class="cmd">snit::type</b> can be any valid Tcl
command name, in any namespace.
The name of an instance of a <b class="cmd">snit::widget</b> must be a valid Tk
widget name, and its parent widget must already exist.</p></li>
<li><p>An instance of a <b class="cmd">snit::type</b> can be destroyed by calling
its <b class="cmd">destroy</b> method. Instances of a <b class="cmd">snit::widget</b> have no
destroy method; use the Tk <b class="cmd">destroy</b> command instead.</p></li>
<li><p>Every instance of a <b class="cmd">snit::widget</b> has one predefined component
called its <b class="variable">hull</b> component.
The hull is usually a Tk <b class="cmd"><a href="../../../../index.html#frame">frame</a></b> or <b class="cmd">toplevel</b> widget; any other
widgets created as part of the <b class="cmd">snit::widget</b> will usually be
contained within the hull.</p></li>
<li><p><b class="cmd">snit::widget</b>s can have their options receive default values from
<span class="sectref"><a href="#section19">THE TK OPTION DATABASE</a></span>.</p></li>
</ul>
</div>
<div id="subsection128" class="doctools_subsection"><h3><a name="subsection128">What is a hull component?</a></h3>
<p>Snit can't create a Tk widget object; only Tk can do that.
Thus, every instance of a <b class="cmd">snit::widget</b> must be wrapped around a
genuine Tk widget; this Tk widget is called the <i class="term">hull component</i>.
Snit effectively piggybacks the behavior you define (methods, options,
and so forth) on top of the hull component so that the whole thing
behaves like a standard Tk widget.</p>
<p>For <b class="cmd">snit::widget</b>s the hull component must be a Tk widget that
defines the <b class="const">-class</b> option.</p>
<p><b class="cmd">snit::widgetadaptor</b>s differ from <b class="cmd">snit::widget</b>s chiefly in
that any kind of widget can be used as the hull component; see
<span class="sectref"><a href="#section18">WIDGET ADAPTORS</a></span>.</p>
</div>
<div id="subsection129" class="doctools_subsection"><h3><a name="subsection129">How can I set the hull type for a snit::widget?</a></h3>
<p>A <b class="cmd">snit::widget</b>'s hull component will usually be a Tk <b class="cmd"><a href="../../../../index.html#frame">frame</a></b>
widget; however, it may be any Tk widget that defines the
<b class="const">-class</b> option. You can
explicitly choose the hull type you prefer by including the <b class="cmd">hulltype</b>
command in the widget definition:</p>
<pre class="doctools_example">snit::widget mytoplevel {
hulltype toplevel
# ...
}
</pre>
<p>If no <b class="cmd">hulltype</b> command appears, the hull will be a <b class="cmd"><a href="../../../../index.html#frame">frame</a></b>.</p>
<p>By default, Snit recognizes the following hull types: the Tk widgets
<b class="cmd"><a href="../../../../index.html#frame">frame</a></b>, <b class="cmd">labelframe</b>, <b class="cmd">toplevel</b>, and the Tile widgets
<b class="cmd">ttk::frame</b>, <b class="cmd">ttk::labelframe</b>, and <b class="cmd">ttk::toplevel</b>. To
enable the use of some other kind of widget as the hull type, you can
<b class="cmd">lappend</b> the widget command to the variable <b class="variable">snit::hulltypes</b> (always
provided the widget defines the <b class="const">-class</b> option. For example,
suppose Tk gets a new widget type called a <b class="cmd">prettyframe</b>:</p>
<pre class="doctools_example">lappend snit::hulltypes prettyframe
snit::widget mywidget {
hulltype prettyframe
# ...
}
</pre>
</div>
<div id="subsection130" class="doctools_subsection"><h3><a name="subsection130">How should I name widgets which are components of a snit::widget?</a></h3>
<p>Every widget, whether a genuine Tk widget or a Snit megawidget, has to
have a valid Tk window name. When a <b class="cmd">snit::widget</b> is first
created, its instance name, <b class="variable">self</b>, is a Tk window name;
however, if the <b class="cmd">snit::widget</b> is used as the hull component by a
<b class="cmd">snit::widgetadaptor</b> its instance name will be changed to
something else. For this reason, every <b class="cmd">snit::widget</b> method,
constructor, destructor, and so forth is passed another implicit
argument, <b class="variable">win</b>, which is the window name of the megawidget. Any
children should be named using <b class="variable">win</b> as the root.</p>
<p>Thus, suppose you're writing a toolbar widget, a frame consisting of a
number of buttons placed side-by-side. It might look something like
this:</p>
<pre class="doctools_example">snit::widget toolbar {
delegate option * to hull
constructor {args} {
button $win.open -text Open -command [mymethod open]
button $win.save -text Save -command [mymethod save]
# ....
$self configurelist $args
}
}
</pre>
<p>See also the question on renaming objects, toward the top of this
file.</p>
</div>
</div>
<div id="section18" class="doctools_section"><h2><a name="section18">WIDGET ADAPTORS</a></h2>
<div id="subsection131" class="doctools_subsection"><h3><a name="subsection131">What is a snit::widgetadaptor?</a></h3>
<p>A <b class="cmd">snit::widgetadaptor</b> is a kind of <b class="cmd">snit::widget</b>. Whereas
a <b class="cmd">snit::widget</b>'s hull is automatically created and is always a
Tk frame, a <b class="cmd">snit::widgetadaptor</b> can be based on any Tk
widget--or on any Snit megawidget, or even (with luck) on megawidgets
defined using some other package.</p>
<p>It's called a <i class="term">widget adaptor</i> because it allows you to take an
existing widget and customize its behavior.</p>
</div>
<div id="subsection132" class="doctools_subsection"><h3><a name="subsection132">How do I define a snit::widgetadaptor?</a></h3>
<p>Use the <b class="cmd">snit::widgetadaptor</b> command. The definition for a
<b class="cmd">snit::widgetadaptor</b> looks just like that for a <b class="cmd">snit::type</b>
or <b class="cmd">snit::widget</b>, except that the constructor must create and
install the hull component.</p>
<p>For example, the following code creates a read-only text widget by the
simple device of turning its <b class="method">insert</b> and <b class="method">delete</b>
methods into no-ops. Then, we define new methods, <b class="method">ins</b> and
<b class="method">del</b>,
which get delegated to the hull component as <b class="method">insert</b> and
<b class="method">delete</b>. Thus, we've adapted the text widget and given it new
behavior while still leaving it fundamentally a text widget.</p>
<pre class="doctools_example">::snit::widgetadaptor rotext {
constructor {args} {
# Create the text widget; turn off its insert cursor
installhull using text -insertwidth 0
# Apply any options passed at creation time.
$self configurelist $args
}
# Disable the text widget's insert and delete methods, to
# make this readonly.
method insert {args} {}
method delete {args} {}
# Enable ins and del as synonyms, so the program can insert and
# delete.
delegate method ins to hull as insert
delegate method del to hull as delete
# Pass all other methods and options to the real text widget, so
# that the remaining behavior is as expected.
delegate method * to hull
delegate option * to hull
}
</pre>
<p>The most important part is in the constructor.
Whereas <b class="cmd">snit::widget</b> creates the hull for you,
<b class="cmd">snit::widgetadaptor</b> cannot -- it doesn't know what kind of
widget you want. So the first thing the constructor does is create
the hull component (a Tk text widget in this case), and then installs
it using the <b class="cmd">installhull</b> command.</p>
<p><em>Note:</em> There is no instance command until you create one by
installing a hull component. Any attempt to pass methods to <b class="variable">$self</b>
prior to calling <b class="cmd">installhull</b> will fail.</p>
</div>
<div id="subsection133" class="doctools_subsection"><h3><a name="subsection133">Can I adapt a widget created elsewhere in the program?</a></h3>
<p>Yes.</p>
<p>At times, it can be convenient to adapt a pre-existing widget instead
of creating your own.
For example, the Bwidget <b class="cmd">PagesManager</b> widget manages a
set of <b class="cmd"><a href="../../../../index.html#frame">frame</a></b> widgets, only one of which is visible at a time.
The application chooses which <b class="cmd"><a href="../../../../index.html#frame">frame</a></b> is visible. All of the
These <b class="cmd"><a href="../../../../index.html#frame">frame</a></b>s are created by the <b class="cmd">PagesManager</b> itself, using
its <b class="method">add</b> method. It's convenient to adapt these frames to
do what we'd like them to do.</p>
<p>In a case like this, the Tk widget will already exist when the
<b class="cmd">snit::widgetadaptor</b> is created. Snit provides an alternate form
of the <b class="cmd">installhull</b> command for this purpose:</p>
<pre class="doctools_example">snit::widgetadaptor pageadaptor {
constructor {args} {
# The widget already exists; just install it.
installhull $win
# ...
}
}
</pre>
</div>
<div id="subsection134" class="doctools_subsection"><h3><a name="subsection134">Can I adapt another megawidget?</a></h3>
<p>Maybe. If the other megawidget is a <b class="cmd">snit::widget</b> or
<b class="cmd">snit::widgetadaptor</b>, then yes. If it isn't then, again, maybe.
You'll have to try it and see. You're most likely to have trouble
with widget destruction--you have to make sure that your
megawidget code receives the <b class="const"><Destroy></b> event before the
megawidget you're adapting does.</p>
</div>
</div>
<div id="section19" class="doctools_section"><h2><a name="section19">THE TK OPTION DATABASE</a></h2>
<div id="subsection135" class="doctools_subsection"><h3><a name="subsection135">What is the Tk option database?</a></h3>
<p>The Tk option database is a database of default option values
maintained by Tk itself; every Tk application has one. The concept of
the option database derives from something called the X Windows
resource database; however, the option database is available in every
Tk implementation, including those which do not use the X Windows
system (e.g., Microsoft Windows).</p>
<p>Full details about the Tk option database are beyond the scope of this
document; both <em>Practical Programming in Tcl and Tk</em> by Welch,
Jones, and Hobbs, and <em>Effective Tcl/Tk Programming</em> by
Harrison and McClennan., have good introductions to it.</p>
<p>Snit is implemented so that most of the time it will simply do the
right thing with respect to the option database, provided that the
widget developer does the right thing by Snit. The body of this
section goes into great deal about what Snit requires. The following
is a brief statement of the requirements, for reference.</p>
<ul class="doctools_itemized">
<li><p>If the widget's default widget class is not what is desired, set it
explicitly using the <b class="cmd">widgetclass</b> statement in the widget
definition.</p></li>
<li><p>When defining or delegating options, specify the resource and class
names explicitly when necessary.</p></li>
<li><p>Use the <b class="cmd">installhull using</b> command to create and install the
hull for <b class="cmd">snit::widgetadaptor</b>s.</p></li>
<li><p>Use the <b class="cmd">install</b> command to create and install all
components which are widgets.</p></li>
<li><p>Use the <b class="cmd">install</b> command to create and install
components which aren't widgets if you'd like them to
receive option values from the option database.</p></li>
</ul>
<p>The interaction of Tk widgets with the option database is a complex
thing; the interaction of Snit with the option database is even more
so, and repays attention to detail.</p>
</div>
<div id="subsection136" class="doctools_subsection"><h3><a name="subsection136">Do snit::types use the Tk option database?</a></h3>
<p>No, they don't; querying the option database requires a Tk window
name, and <b class="cmd">snit::type</b>s don't have one.</p>
<p>If you create an instance of a <b class="cmd">snit::type</b> as a
component of a <b class="cmd">snit::widget</b> or <b class="cmd">snit::widgetadaptor</b>, on the
other hand, and if any options are delegated to the component,
and if you use <b class="cmd">install</b> to create and install it, then
the megawidget will query the option database on the
<b class="cmd">snit::type</b>'s behalf. This might or might not be what you
want, so take care.</p>
</div>
<div id="subsection137" class="doctools_subsection"><h3><a name="subsection137">What is my snit::widget's widget class?</a></h3>
<p>Every Tk widget has a "widget class": a name that is used when adding
option settings to the database. For Tk widgets, the widget class is
the same as the widget command name with an initial capital. For
example, the widget class of the Tk <b class="cmd">button</b> widget is
<b class="const">Button</b>.</p>
<p>Similarly, the widget class of a <b class="cmd">snit::widget</b> defaults to the
unqualified type name with the first letter capitalized. For example,
the widget class of</p>
<pre class="doctools_example">snit::widget ::mylibrary::scrolledText { ... }
</pre>
<p>is <b class="const">ScrolledText</b>.</p>
<p>The widget class can also be set explicitly using the
<b class="cmd">widgetclass</b> statement within the <b class="cmd">snit::widget</b> definition:</p>
<pre class="doctools_example">snit::widget ::mylibrary::scrolledText {
widgetclass Text
# ...
}
</pre>
<p>The above definition says that a <b class="cmd">scrolledText</b> megawidget has the
same widget class as an ordinary <b class="cmd"><a href="../../../../index.html#text">text</a></b> widget. This might or
might not be a good idea, depending on how the rest of the megawidget
is defined, and how its options are delegated.</p>
</div>
<div id="subsection138" class="doctools_subsection"><h3><a name="subsection138">What is my snit::widgetadaptor's widget class?</a></h3>
<p>The widget class of a <b class="cmd">snit::widgetadaptor</b> is just the widget
class of its hull widget; Snit has no control over this.</p>
<p>Note that the widget class can be changed only for <b class="cmd"><a href="../../../../index.html#frame">frame</a></b> and
<b class="cmd">toplevel</b> widgets, which is why these are the valid hull types
for <b class="cmd">snit::widget</b>s.</p>
<p>Try to use <b class="cmd">snit::widgetadaptor</b>s only to make small modifications
to another widget's behavior. Then, it will usually not make sense to
change the widget's widget class anyway.</p>
</div>
<div id="subsection139" class="doctools_subsection"><h3><a name="subsection139">What are option resource and class names?</a></h3>
<p>Every Tk widget option has three names: the option name, the resource
name, and the class name.
The option name begins with a hyphen and is all lowercase; it's used
when creating widgets, and with the <b class="cmd">configure</b> and <b class="cmd">cget</b>
commands.</p>
<p>The resource and class names are used to initialize option
default values by querying the option database.
The resource name is usually just the option
name minus the hyphen, but may contain uppercase letters at word
boundaries; the class name is usually just the resource
name with an initial capital, but not always. For example, here are
the option, resource, and class names for several Tk <b class="cmd"><a href="../../../../index.html#text">text</a></b>
widget options:</p>
<pre class="doctools_example"> -background background Background
-borderwidth borderWidth BorderWidth
-insertborderwidth insertBorderWidth BorderWidth
-padx padX Pad
</pre>
<p>As is easily seen, sometimes the resource and class names can be
inferred from the option name, but not always.</p>
</div>
<div id="subsection140" class="doctools_subsection"><h3><a name="subsection140">What are the resource and class names for my megawidget's options?</a></h3>
<p>For options implicitly delegated to a component using
<b class="cmd">delegate option *</b>, the resource and class names will be
exactly those defined by the component. The <b class="cmd">configure</b> method
returns these names, along with the option's default and current
values:</p>
<pre class="doctools_example">% snit::widget mytext {
delegate option * to text
constructor {args} {
install text using text .text
# ...
}
# ...
}
::mytext
% mytext .text
.text
% .text configure -padx
-padx padX Pad 1 1
%
</pre>
<p>For all other options (whether locally defined or explicitly
delegated), the resource and class names can be defined explicitly, or
they can be allowed to have default values.</p>
<p>By default, the resource name is just the option name minus the
hyphen; the the class name is just the option name with an initial
capital letter. For example, suppose we explicitly delegate "-padx":</p>
<pre class="doctools_example">% snit::widget mytext {
option -myvalue 5
delegate option -padx to text
delegate option * to text
constructor {args} {
install text using text .text
# ...
}
# ...
}
::mytext
% mytext .text
.text
% .text configure -myvalue
-myvalue myvalue Myvalue 5 5
% .text configure -padx
-padx padx Padx 1 1
%
</pre>
<p>Here the resource and class names are chosen using the default rules.
Often these rules are sufficient, but in the case of "-padx" we'd most
likely prefer that the option's resource and class names are the same
as for the built-in Tk widgets. This is easily done:</p>
<pre class="doctools_example">% snit::widget mytext {
delegate option {-padx padX Pad} to text
# ...
}
::mytext
% mytext .text
.text
% .text configure -padx
-padx padX Pad 1 1
%
</pre>
</div>
<div id="subsection141" class="doctools_subsection"><h3><a name="subsection141">How does Snit initialize my megawidget's locally-defined options?</a></h3>
<p>The option database is queried for each of the megawidget's
locally-defined options, using the option's resource and class name.
If the result isn't "", then it replaces the default value given in
widget definition. In either case, the default can be overridden by
the caller. For example,</p>
<pre class="doctools_example">option add *Mywidget.texture pebbled
snit::widget mywidget {
option -texture smooth
# ...
}
mywidget .mywidget -texture greasy
</pre>
<p>Here, <b class="const">-texture</b> would normally default to "smooth", but because of
the entry added to the option database it defaults to "pebbled".
However, the caller has explicitly overridden the default, and so the
new widget will be "greasy".</p>
</div>
<div id="subsection142" class="doctools_subsection"><h3><a name="subsection142">How does Snit initialize delegated options?</a></h3>
<p>That depends on whether the options are delegated to the hull, or to
some other component.</p>
</div>
<div id="subsection143" class="doctools_subsection"><h3><a name="subsection143">How does Snit initialize options delegated to the hull?</a></h3>
<p>A <b class="cmd">snit::widget</b>'s hull is a widget, and given that its class has
been set it is expected to query the option database for itself. The
only exception concerns options that are delegated to it with a
different name. Consider the following code:</p>
<pre class="doctools_example">option add *Mywidget.borderWidth 5
option add *Mywidget.relief sunken
option add *Mywidget.hullbackground red
option add *Mywidget.background green
snit::widget mywidget {
delegate option -borderwidth to hull
delegate option -hullbackground to hull as -background
delegate option * to hull
# ...
}
mywidget .mywidget
set A [.mywidget cget -relief]
set B [.mywidget cget -hullbackground]
set C [.mywidget cget -background]
set D [.mywidget cget -borderwidth]
</pre>
<p>The question is, what are the values of variables A, B, C and D?</p>
<p>The value of A is "sunken". The hull is a Tk frame which has been
given the widget class <b class="const">Mywidget</b>; it will automatically query the
option database and pick up this value. Since the <b class="const">-relief</b> option is
implicitly delegated to the hull, Snit takes no action.</p>
<p>The value of B is "red". The hull will automatically pick up the
value "green" for its <b class="const">-background</b> option, just as it picked up the
<b class="const">-relief</b> value. However, Snit knows that <b class="const">-hullbackground</b>
is mapped to the hull's <b class="const">-background</b> option; hence, it queries
the option database for <b class="const">-hullbackground</b> and gets "red" and
updates the hull accordingly.</p>
<p>The value of C is also "red", because <b class="const">-background</b> is implicitly
delegated to the hull; thus, retrieving it is the same as retrieving
<b class="const">-hullbackground</b>. Note that this case is unusual; the
<b class="const">-background</b> option should probably have been excluded using the delegate
statement's <b class="const">except</b> clause, or (more likely) delegated to some other
component.</p>
<p>The value of D is "5", but not for the reason you think. Note that as
it is defined above, the resource name for <b class="const">-borderwidth</b> defaults to
<b class="const">borderwidth</b>, whereas the option database entry is
<b class="const">borderWidth</b>, in
accordance with the standard Tk naming for this option. As with
<b class="const">-relief</b>, the hull picks up its own <b class="const">-borderwidth</b>
option before Snit
does anything. Because the option is delegated under its own name,
Snit assumes that the correct thing has happened, and doesn't worry
about it any further. To avoid confusion, the
<b class="const">-borderwidth</b> option
should have been delegated like this:</p>
<pre class="doctools_example"> delegate option {-borderwidth borderWidth BorderWidth} to hull
</pre>
<p>For <b class="cmd">snit::widgetadaptor</b>s, the case is somewhat altered. Widget
adaptors retain the widget class of their hull, and the hull is not
created automatically by Snit. Instead, the <b class="cmd">snit::widgetadaptor</b>
must call <b class="cmd">installhull</b> in its constructor. The normal way
to do this is as follows:</p>
<pre class="doctools_example">snit::widgetadaptor mywidget {
# ...
constructor {args} {
# ...
installhull using text -foreground white
# ...
}
# ...
}
</pre>
<p>In this case, the <b class="cmd">installhull</b> command will create the hull using
a command like this:</p>
<pre class="doctools_example"> set hull [text $win -foreground white]
</pre>
<p>The hull is a <b class="cmd"><a href="../../../../index.html#text">text</a></b> widget, so its widget class is <b class="const">Text</b>. Just
as with <b class="cmd">snit::widget</b> hulls, Snit assumes that it will pick up
all of its normal option values automatically, without help from Snit.
Options delegated from a different name are initialized from the
option database in the same way as described above.</p>
<p>In earlier versions of Snit, <b class="cmd">snit::widgetadaptor</b>s were expected
to call <b class="cmd">installhull</b> like this:</p>
<pre class="doctools_example"> installhull [text $win -foreground white]
</pre>
<p>This form still works--but Snit will not query the option database as
described above.</p>
</div>
<div id="subsection144" class="doctools_subsection"><h3><a name="subsection144">How does Snit initialize options delegated to other components?</a></h3>
<p>For hull components, Snit assumes that Tk will do most of the work
automatically. Non-hull components are somewhat more complicated, because
they are matched against the option database twice.</p>
<p>A component widget remains a widget still, and is therefore
initialized from the option database in the usual way. A <b class="cmd"><a href="../../../../index.html#text">text</a></b>
widget remains a <b class="cmd"><a href="../../../../index.html#text">text</a></b> widget whether it is a component of a
megawidget or not, and will be created as such.</p>
<p>But then, the option database is queried for all options delegated to
the component, and the component is initialized accordingly--provided
that the <b class="cmd">install</b> command is used to create it.</p>
<p>Before option database support was added to Snit, the usual way to
create a component was to simply create it in the constructor and
assign its command name to the component variable:</p>
<pre class="doctools_example">snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
set myComp [text $win.text -foreground black]
}
}
</pre>
<p>The drawback of this method is that Snit has no opportunity to
initialize the component properly. Hence, the following approach is
now used:</p>
<pre class="doctools_example">snit::widget mywidget {
delegate option -background to myComp
constructor {args} {
install myComp using text $win.text -foreground black
}
}
</pre>
<p>The <b class="cmd">install</b> command does the following:</p>
<ul class="doctools_itemized">
<li><p>Builds a list of the options explicitly included in the <b class="cmd">install</b>
command--in this case, <b class="const">-foreground</b>.</p></li>
<li><p>Queries the option database for all options delegated explicitly to
the named component.</p></li>
<li><p>Creates the component using the specified command, after inserting
into it a list of options and values read from the option database.
Thus, the explicitly included options (like <b class="const">-foreground</b>) will
override anything read from the option database.</p></li>
<li><p>If the widget definition implicitly delegated options to the component
using <b class="cmd">delegate option *</b>, then Snit calls the newly created
component's <b class="cmd">configure</b> method to receive a list of all of the
component's options. From this Snit builds a list of options
implicitly delegated to the component which were not explicitly
included in the <b class="cmd">install</b> command. For all such options, Snit
queries the option database and configures the component accordingly.</p></li>
</ul>
<p>You don't really need to know all of this; just use <b class="cmd">install</b> to
install your components, and Snit will try to do the right thing.</p>
</div>
<div id="subsection145" class="doctools_subsection"><h3><a name="subsection145">What happens if I install a non-widget as a component of widget?</a></h3>
<p>A <b class="cmd">snit::type</b> never queries the option database.
However, a <b class="cmd">snit::widget</b> can have non-widget components. And if
options are delegated to those components, and if the <b class="cmd">install</b>
command is used to install those components, then they will be
initialized from the option database just as widget components are.</p>
<p>However, when used within a megawidget, <b class="cmd">install</b> assumes that the
created component uses a reasonably standard widget-like creation
syntax. If it doesn't, don't use <b class="cmd">install</b>.</p>
</div>
</div>
<div id="section20" class="doctools_section"><h2><a name="section20">ENSEMBLE COMMANDS</a></h2>
<div id="subsection146" class="doctools_subsection"><h3><a name="subsection146">What is an ensemble command?</a></h3>
<p>An ensemble command is a command with subcommands. Snit objects are
all ensemble commands; however, the term more usually refers to
commands like the standard Tcl commands <b class="cmd"><a href="../../../../index.html#string">string</a></b>, <b class="cmd"><a href="../../../../index.html#file">file</a></b>,
and <b class="cmd">clock</b>. In a sense, these are singleton objects--there's
only one instance of them.</p>
</div>
<div id="subsection147" class="doctools_subsection"><h3><a name="subsection147">How can I create an ensemble command using Snit?</a></h3>
<p>There are two ways--as a <b class="cmd">snit::type</b>, or as an instance of
a <b class="cmd">snit::type</b>.</p>
</div>
<div id="subsection148" class="doctools_subsection"><h3><a name="subsection148">How can I create an ensemble command using an instance of a snit::type?</a></h3>
<p>Define a type whose <span class="sectref"><a href="#section5">INSTANCE METHODS</a></span> are the subcommands
of your ensemble command. Then, create an instance of the type with
the desired name.</p>
<p>For example, the following code uses <span class="sectref"><a href="#section16">DELEGATION</a></span> to create
a work-alike for the standard <b class="cmd"><a href="../../../../index.html#string">string</a></b> command:</p>
<pre class="doctools_example">snit::type ::mynamespace::mystringtype {
delegate method * to stringhandler
constructor {} {
set stringhandler string
}
}
::mynamespace::mystringtype mystring
</pre>
<p>We create the type in a namespace, so that the type command is hidden;
then we create a single instance with the desired name--
<b class="cmd">mystring</b>, in this case.</p>
<p>This method has two drawbacks. First, it leaves the type command
floating about. More seriously, your shiny new ensemble
command will have <b class="method">info</b> and <b class="method">destroy</b> subcommands that
you probably have no use for. But read on.</p>
</div>
<div id="subsection149" class="doctools_subsection"><h3><a name="subsection149">How can I create an ensemble command using a snit::type?</a></h3>
<p>Define a type whose <span class="sectref"><a href="#section9">TYPE METHODS</a></span> are the subcommands
of your ensemble command.</p>
<p>For example, the following code uses <span class="sectref"><a href="#section16">DELEGATION</a></span> to create
a work-alike for the standard <b class="cmd"><a href="../../../../index.html#string">string</a></b> command:</p>
<pre class="doctools_example">snit::type mystring {
delegate typemethod * to stringhandler
typeconstructor {
set stringhandler string
}
}
</pre>
<p>Now the type command itself is your ensemble command.</p>
<p>This method has only one drawback, and though it's major, it's
also surmountable. Your new ensemble command will have
<b class="method">create</b>, <b class="method">info</b> and <b class="method">destroy</b> subcommands
you don't want. And worse yet, since the <b class="method">create</b> method
can be implicit, users of your command will accidentally be creating
instances of your <b class="cmd">mystring</b> type if they should mispell one
of the subcommands. The command will succeed--the first time--but
won't do what's wanted. This is very bad.</p>
<p>The work around is to set some <span class="sectref"><a href="#section21">PRAGMAS</a></span>, as shown here:</p>
<pre class="doctools_example">snit::type mystring {
pragma -hastypeinfo no
pragma -hastypedestroy no
pragma -hasinstances no
delegate typemethod * to stringhandler
typeconstructor {
set stringhandler string
}
}
</pre>
<p>Here we've used the <b class="cmd">pragma</b> statement to tell Snit that we don't
want the <b class="method">info</b> typemethod or the <b class="method">destroy</b> typemethod,
and that our type has no instances; this eliminates the
<b class="method">create</b> typemethod and all related code. As
a result, our ensemble command will be well-behaved, with no
unexpected subcommands.</p>
</div>
</div>
<div id="section21" class="doctools_section"><h2><a name="section21">PRAGMAS</a></h2>
<div id="subsection150" class="doctools_subsection"><h3><a name="subsection150">What is a pragma?</a></h3>
<p>A pragma is an option you can set in your type definitions that
affects how the type is defined and how it works once it is defined.</p>
</div>
<div id="subsection151" class="doctools_subsection"><h3><a name="subsection151">How do I set a pragma?</a></h3>
<p>Use the <b class="cmd">pragma</b> statement. Each pragma is an option with a
value; each time you use the <b class="cmd">pragma</b> statement you can set one or
more of them.</p>
</div>
<div id="subsection152" class="doctools_subsection"><h3><a name="subsection152">How can I get rid of the "info" type method?</a></h3>
<p>Set the <b class="const">-hastypeinfo</b> pragma to <b class="const">no</b>:</p>
<pre class="doctools_example">snit::type dog {
pragma -hastypeinfo no
# ...
}
</pre>
<p>Snit will refrain from defining the <b class="method">info</b> type method.</p>
</div>
<div id="subsection153" class="doctools_subsection"><h3><a name="subsection153">How can I get rid of the "destroy" type method?</a></h3>
<p>Set the <b class="const">-hastypedestroy</b> pragma to <b class="const">no</b>:</p>
<pre class="doctools_example">snit::type dog {
pragma -hastypedestroy no
# ...
}
</pre>
<p>Snit will refrain from defining the <b class="method">destroy</b> type method.</p>
</div>
<div id="subsection154" class="doctools_subsection"><h3><a name="subsection154">How can I get rid of the "create" type method?</a></h3>
<p>Set the <b class="const">-hasinstances</b> pragma to <b class="const">no</b>:</p>
<pre class="doctools_example">snit::type dog {
pragma -hasinstances no
# ...
}
</pre>
<p>Snit will refrain from defining the <b class="method">create</b> type method;
if you call the type command with an unknown method name, you'll get
an error instead of a new instance of the type.</p>
<p>This is useful if you wish to use a <b class="cmd">snit::type</b> to define
an ensemble command rather than a type with instances.</p>
<p>Pragmas <b class="const">-hastypemethods</b> and <b class="const">-hasinstances</b> cannot
both be false (or there'd be nothing left).</p>
</div>
<div id="subsection155" class="doctools_subsection"><h3><a name="subsection155">How can I get rid of type methods altogether?</a></h3>
<p>Normal Tk widget type commands don't have subcommands; all they do is
create widgets--in Snit terms, the type command calls the
<b class="method">create</b> type method directly. To get the same behavior from
Snit, set the <b class="const">-hastypemethods</b> pragma to <b class="const">no</b>:</p>
<pre class="doctools_example">snit::type dog {
pragma -hastypemethods no
#...
}
# Creates ::spot
dog spot
# Tries to create an instance called ::create
dog create spot
</pre>
<p>Pragmas <b class="const">-hastypemethods</b> and <b class="const">-hasinstances</b> cannot
both be false (or there'd be nothing left).</p>
</div>
<div id="subsection156" class="doctools_subsection"><h3><a name="subsection156">Why can't I create an object that replaces an old object with the same name?</a></h3>
<p>Up until Snit 0.95, you could use any name for an instance of a
<b class="cmd">snit::type</b>, even if the name was already in use by some other
object or command. You could do the following, for example:</p>
<pre class="doctools_example">snit::type dog { ... }
dog proc
</pre>
<p>You now have a new dog named "proc", which is probably not something
that you really wanted to do. As a result, Snit now throws an error
if your chosen instance name names an existing command. To restore
the old behavior, set the <b class="const">-canreplace</b> pragma to <b class="const">yes</b>:</p>
<pre class="doctools_example">snit::type dog {
pragma -canreplace yes
# ...
}
</pre>
</div>
<div id="subsection157" class="doctools_subsection"><h3><a name="subsection157">How can I make my simple type run faster?</a></h3>
<p>In Snit 1.x, you can set the <b class="const">-simpledispatch</b> pragma to <b class="const">yes</b>.</p>
<p>Snit 1.x method dispatch is both flexible and fast, but the flexibility
comes with a price. If your type doesn't require the flexibility, the
<b class="const">-simpledispatch</b> pragma allows you to substitute a simpler
dispatch mechanism that runs quite a bit faster. The limitations
are these:</p>
<ul class="doctools_itemized">
<li><p>Methods cannot be delegated.</p></li>
<li><p><b class="cmd">uplevel</b> and <b class="cmd">upvar</b> do not work as expected: the
caller's scope is two levels up rather than one.</p></li>
<li><p>The option-handling methods
(<b class="cmd">cget</b>, <b class="cmd">configure</b>, and <b class="cmd">configurelist</b>) are very
slightly slower.</p></li>
</ul>
<p>In Snit 2.2, the <b class="const">-simpledispatch</b> macro is obsolete, and
ignored; all Snit 2.2 method dispatch is faster than Snit 1.x's
<b class="const">-simpledispatch</b>.</p>
</div>
</div>
<div id="section22" class="doctools_section"><h2><a name="section22">MACROS</a></h2>
<div id="subsection158" class="doctools_subsection"><h3><a name="subsection158">What is a macro?</a></h3>
<p>A Snit macro is nothing more than a Tcl proc that's defined in the
Tcl interpreter used to compile Snit type definitions.</p>
</div>
<div id="subsection159" class="doctools_subsection"><h3><a name="subsection159">What are macros good for?</a></h3>
<p>You can use Snit macros to define new type definition syntax, and to
support conditional compilation.</p>
</div>
<div id="subsection160" class="doctools_subsection"><h3><a name="subsection160">How do I do conditional compilation?</a></h3>
<p>Suppose you want your type to use a fast C extension if it's
available; otherwise, you'll fallback to a slower Tcl implementation.
You want to define one set of methods in the first case, and another
set in the second case. But how can your type definition know whether
the fast C extension is available or not?</p>
<p>It's easily done. Outside of any type definition, define a macro that
returns 1 if the extension is available, and 0 otherwise:</p>
<pre class="doctools_example">if {$gotFastExtension} {
snit::macro fastcode {} {return 1}
} else {
snit::macro fastcode {} {return 0}
}
</pre>
<p>Then, use your macro in your type definition:</p>
<pre class="doctools_example">snit::type dog {
if {[fastcode]} {
# Fast methods
method bark {} {...}
method wagtail {} {...}
} else {
# Slow methods
method bark {} {...}
method wagtail {} {...}
}
}
</pre>
</div>
<div id="subsection161" class="doctools_subsection"><h3><a name="subsection161">How do I define new type definition syntax?</a></h3>
<p>Use a macro. For example, your <b class="cmd">snit::widget</b>'s
<b class="const">-background</b> option should be propagated to a number
of component widgets. You could implement that like this:</p>
<pre class="doctools_example">snit::widget mywidget {
option -background -default white -configuremethod PropagateBackground
method PropagateBackground {option value} {
$comp1 configure $option $value
$comp2 configure $option $value
$comp3 configure $option $value
}
}
</pre>
<p>For one option, this is fine; if you've got a number of options, it
becomes tedious and error prone. So package it as a macro:</p>
<pre class="doctools_example">snit::macro propagate {option "to" components} {
option $option -configuremethod Propagate$option
set body "\n"
foreach comp $components {
append body "\$$comp configure $option \$value\n"
}
method Propagate$option {option value} $body
}
</pre>
<p>Then you can use it like this:</p>
<pre class="doctools_example">snit::widget mywidget {
option -background default -white
option -foreground default -black
propagate -background to {comp1 comp2 comp3}
propagate -foreground to {comp1 comp2 comp3}
}
</pre>
</div>
<div id="subsection162" class="doctools_subsection"><h3><a name="subsection162">Are there are restrictions on macro names?</a></h3>
<p>Yes, there are. You can't redefine any standard Tcl commands or Snit
type definition statements. You can use any other command name,
including the name of a previously defined macro.</p>
<p>If you're using Snit macros in your application, go ahead and name
them in the global namespace, as shown above. But if you're using
them to define types or widgets for use by others, you should define
your macros in the same namespace as your types or widgets. That way,
they won't conflict with other people's macros.</p>
<p>If my fancy <b class="cmd">snit::widget</b> is called <b class="cmd">::mylib::mywidget</b>,
for example, then I should define my <b class="cmd">propagate</b> macro as
<b class="cmd">::mylib::propagate</b>:</p>
<pre class="doctools_example">snit::macro mylib::propagate {option "to" components} { ... }
snit::widget ::mylib::mywidget {
option -background default -white
option -foreground default -black
mylib::propagate -background to {comp1 comp2 comp3}
mylib::propagate -foreground to {comp1 comp2 comp3}
}
</pre>
</div>
</div>
<div id="section23" class="doctools_section"><h2><a name="section23">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>snit</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bwidget">BWidget</a>, <a href="../../../../index.html#c_">C++</a>, <a href="../../../../index.html#incr_tcl">Incr Tcl</a>, <a href="../../../../index.html#adaptors">adaptors</a>, <a href="../../../../index.html#class">class</a>, <a href="../../../../index.html#mega_widget">mega widget</a>, <a href="../../../../index.html#object">object</a>, <a href="../../../../index.html#object_oriented">object oriented</a>, <a href="../../../../index.html#widget">widget</a>, <a href="../../../../index.html#widget_adaptors">widget adaptors</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2006, by William H. Duquette</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/soundex/soundex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<div class='fossil-doc' data-title='soundex - Soundex'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">soundex(n) 1.0 tcllib "Soundex"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>soundex - Soundex</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">soundex <span class="opt">?1.0?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::soundex::knuth</b> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides soundex algorithms which allow the
comparison of words based on their phonetic likeness.</p>
<p>Currently only an algorithm by Knuth is provided, which
is tuned to english names and words.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::soundex::knuth</b> <i class="arg">string</i></a></dt>
<dd><p>Computes the soundex code of the input <i class="arg">string</i> using
Knuth's algorithm and returns it as the result of the
command.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<pre class="doctools_example">
% ::soundex::knuth Knuth
K530
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>soundex</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#knuth">knuth</a>, <a href="../../../../index.html#soundex">soundex</a>, <a href="../../../../index.html#text_comparison">text comparison</a>, <a href="../../../../index.html#text_likeness">text likeness</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © ????, Algorithm: Donald E. Knuth<br>
Copyright © 2003, Documentation: Andreas Kupries <[email protected]><br>
Copyright © 1998, Tcl port: Evan Rempel <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/stooop/stooop.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
<div class='fossil-doc' data-title='stooop - Simple Tcl Only Object Oriented Programming'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">stooop(n) 4.4.1 tcllib "Simple Tcl Only Object Oriented Programming"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>stooop - Object oriented extension.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">DEBUGGING</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">stooop <span class="opt">?4.4.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::stooop::class</b> <i class="arg">name body</i></a></li>
<li><a href="#2"><b class="cmd">::stooop::new</b> <i class="arg">class</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::stooop::delete</b> <i class="arg">object</i> <span class="opt">?<i class="arg">object ...</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::stooop::virtual</b> <b class="const">proc</b> <i class="arg">name</i> {<b class="const">this</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span>} <span class="opt">?<i class="arg">body</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::stooop::classof</b> <i class="arg">object</i></a></li>
<li><a href="#6"><b class="cmd">::stooop::new</b> <i class="arg">object</i></a></li>
<li><a href="#7"><b class="cmd">::stooop::printObjects</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::stooop::record</b></a></li>
<li><a href="#9"><b class="cmd">::stooop::report</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to extend Tcl in an object oriented
manner, using a familiar C++ like syntax and behaviour. Stooop only
introduces a few new commands: <b class="cmd"><a href="../../../../index.html#class">class</a></b>, <b class="cmd">new</b>, <b class="cmd">delete</b>,
<b class="cmd">virtual</b> and <b class="cmd">classof</b>. Along with a few coding conventions,
that is basically all you need to know to use stooop. Stooop is meant
to be as simple to use as possible.</p>
<p>This manual is very succinct and is to be used as a quick reminder for
the programmer, who should have read the thorough <a href="stooop_man.html">stooop_man.html</a>
HTML documentation at this point.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::stooop::class</b> <i class="arg">name body</i></a></dt>
<dd><p>This command creates a class. The body, similar in contents to a Tcl
namespace (which a class actually also is), contains member procedure
definitions. Member procedures can also be defined outside the class
body, by prefixing their name with <b class="const">class::</b>, as you would
proceed with namespace procedures.</p>
<dl class="doctools_definitions">
<dt><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> <i class="arg">class</i> {<b class="const">this</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span>} <span class="opt">?<i class="arg">base</i> {<span class="opt">?<i class="arg">arg arg ...</i>?</span>} ...?</span> <i class="arg">body</i></dt>
<dd><p>This is the constructor procedure for the class. It is invoked
following a <b class="cmd">new</b> invocation on the class. It must have the same
name as the class and a first argument named <b class="const">this</b>. Any number
of base classes specifications, including arguments to be passed to
their constructor, are allowed before the actual body of the
procedure.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> ~<i class="arg">class</i> {<b class="const">this</b>} <i class="arg">body</i></dt>
<dd><p>This is the destructor procedure for the class. It is invoked
following a <b class="cmd">delete</b> invocation. Its name must be the
concatenation of a single <b class="const">~</b> character followed by the class
name (as in C++). It must have a single argument named <b class="const">this</b>.</p></dd>
<dt><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> <i class="arg">name</i> {<b class="const">this</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span>} <i class="arg">body</i></dt>
<dd><p>This is a member procedure of the class, as its first argument is
named <b class="const">this</b>. It allows a simple access of member data for the
object referenced by <b class="const">this</b> inside the procedure. For example:</p>
<pre class="doctools_example">
set ($this,data) 0
</pre>
</dd>
<dt><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> <i class="arg">name</i> {<span class="opt">?<i class="arg">arg arg ...</i>?</span>} <i class="arg">body</i></dt>
<dd><p>This is a static (as in C++) member procedure of the class, as its
first argument is not named <b class="const">this</b>. Static (global) class data
can be accessed as in:</p>
<pre class="doctools_example">
set (data) 0
</pre>
</dd>
<dt><b class="cmd"><a href="../../../../index.html#proc">proc</a></b> <i class="arg">class</i> {<b class="const">this copy</b>} <i class="arg">body</i></dt>
<dd><p>This is the optional copy procedure for the class. It must have the
same name as the class and exactly 2 arguments named <b class="const">this</b> and
<b class="const">copy</b>. It is invoked following a <b class="cmd">new</b> invocation on an
existing object of the class.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::stooop::new</b> <i class="arg">class</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>This command is used to create an object. The first argument is the
class name and is followed by the arguments needed by the
corresponding class constructor. A unique identifier for the object
just created is returned.</p></dd>
<dt><a name="3"><b class="cmd">::stooop::delete</b> <i class="arg">object</i> <span class="opt">?<i class="arg">object ...</i>?</span></a></dt>
<dd><p>This command is used to delete one or several objects. It takes one or
more object identifiers as argument(s).</p></dd>
<dt><a name="4"><b class="cmd">::stooop::virtual</b> <b class="const">proc</b> <i class="arg">name</i> {<b class="const">this</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span>} <span class="opt">?<i class="arg">body</i>?</span></a></dt>
<dd><p>The <b class="cmd">virtual</b> specifier may be used on member procedures to
achieve dynamic binding. A procedure in a base class can then be
redefined (overloaded) in the derived class(es). If the base class
procedure is invoked on an object, it is actually the derived class
procedure which is invoked, if it exists. If the base class procedure
has no body, then it is considered to be a pure virtual and the
derived class procedure is always invoked.</p></dd>
<dt><a name="5"><b class="cmd">::stooop::classof</b> <i class="arg">object</i></a></dt>
<dd><p>This command returns the class of the existing object passed as single
parameter.</p></dd>
<dt><a name="6"><b class="cmd">::stooop::new</b> <i class="arg">object</i></a></dt>
<dd><p>This command is used to create an object by copying an existing
object. The copy constructor of the corresponding class is invoked if
it exists, otherwise a simple copy of the copied object data members
is performed.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">DEBUGGING</a></h2>
<dl class="doctools_definitions">
<dt>Environment variables</dt>
<dd><dl class="doctools_definitions">
<dt><b class="variable">STOOOPCHECKDATA</b></dt>
<dd><p>Setting this variable to any true value will cause stooop to check for
invalid member or class data access.</p></dd>
<dt><b class="variable">STOOOPCHECKPROCEDURES</b></dt>
<dd><p>Setting this variable to any true value will cause stooop to check for
invalid member procedure arguments and pure interface classes
instanciation.</p></dd>
<dt><b class="variable">STOOOPCHECKALL</b></dt>
<dd><p>Setting this variable to any true value will cause stooop to activate
both procedure and data member checking.</p></dd>
<dt><b class="variable">STOOOPCHECKOBJECTS</b></dt>
<dd><p>Setting this variable to any true value will cause stooop to activate
object checking. The following stooop namespace procedures then become
available for debugging: <b class="cmd">printObjects</b>, <b class="cmd"><a href="../../../../index.html#record">record</a></b> and
<b class="cmd"><a href="../report/report.html">report</a></b>.</p></dd>
<dt><b class="variable">STOOOPTRACEPROCEDURES</b></dt>
<dd><p>Setting this environment variable to either <b class="const">stdout</b>,
<b class="const">stderr</b> or a file name, activates procedure tracing. The
stooop library will then output to the specified channel 1 line of
informational text for each member procedure invocation.</p></dd>
<dt><b class="variable">STOOOPTRACEPROCEDURESFORMAT</b></dt>
<dd><p>Defines the trace procedures output format. Defaults to
<b class="const">"class: %C, procedure: %p, object: %O, arguments: %a"</b>.</p></dd>
<dt><b class="variable">STOOOPTRACEDATA</b></dt>
<dd><p>Setting this environment variable to either <b class="const">stdout</b>,
<b class="const">stderr</b> or a file name, activates data tracing. The stooop
library will then output to the specified channel 1 line of
informational text for each member data access.</p></dd>
<dt><b class="variable">STOOOPTRACEDATAFORMAT</b></dt>
<dd><p>Defines the trace data output format. Defaults to
<b class="const">"class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v"</b>.</p></dd>
<dt><b class="variable">STOOOPTRACEDATAOPERATIONS</b></dt>
<dd><p>When tracing data output, by default, all read, write and unsetting
accesses are reported, but the user can set this variable to any
combination of the letters <b class="const">r</b>, <b class="const">w</b>, and <b class="const">u</b> for
more specific tracing (please refer to the <b class="cmd"><a href="../../../../index.html#trace">trace</a></b> Tcl manual page
for more information).</p></dd>
<dt><b class="variable">STOOOPTRACEALL</b></dt>
<dd><p>Setting this environment variable to either <b class="const">stdout</b>,
<b class="const">stderr</b> or a file name, enables both procedure and data
tracing.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::stooop::printObjects</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Prints an ordered list of existing objects, in creation order, oldest
first. Each output line contains the class name, object identifier and
the procedure within which the creation occurred. The optional pattern
argument (as in the Tcl <b class="cmd">string match</b> command) can be used to
limit the output to matching class names.</p></dd>
<dt><a name="8"><b class="cmd">::stooop::record</b></a></dt>
<dd><p>When invoked, a snapshot of all existing stooop objects is
taken. Reporting can then be used at a later time to see which objects
were created or deleted in the interval.</p></dd>
<dt><a name="9"><b class="cmd">::stooop::report</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Prints the created and deleted objects since the <b class="cmd">::stooop::record</b>
procedure was invoked last. If present, the pattern argument limits
the output to matching class names.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>Please see the full HTML documentation in <a href="stooop_man.html">stooop_man.html</a>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>stooop</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#c_">C++</a>, <a href="../../../../index.html#class">class</a>, <a href="../../../../index.html#object">object</a>, <a href="../../../../index.html#object_oriented">object oriented</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/stooop/switched.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
|
<div class='fossil-doc' data-title='switched - Simple Tcl Only Object Oriented Programming'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">switched(n) 2.2.1 tcllib "Simple Tcl Only Object Oriented Programming"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>switched - switch/option management.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">switched <span class="opt">?2.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><switched></b> <b class="method">complete</b> <i class="arg">this</i></a></li>
<li><a href="#2"><b class="cmd"><switched></b> <b class="method">options</b> <i class="arg">this</i></a></li>
<li><a href="#3"><b class="cmd"><switched></b> <b class="method">set-<b class="option">option</b></b> <i class="arg">this</i> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="class">switched</b> class serves as base class for user classes with
switch / option configuration procedures. It provides facilities for
managing options through a simple interface.</p>
<p>For example:</p>
<pre class="doctools_example">
set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel]
puts "my car was running on [switched::cget $vehicle -fuel]"
switched::configure $vehicle -power 40 -fuel electricity
puts "but is now running on clean [switched::cget $vehicle -fuel]"
</pre>
<p>Of course, as you might have guessed, the <b class="class">car</b> class is
derived from the <b class="class">switched</b> class. Let us see how it works:</p>
<pre class="doctools_example">
class car {
proc car {this args} switched {$args} {
# car specific initialization code here
switched::complete $this
}
...
}
</pre>
<p>The switched class constructor takes the optional configuration
option / value pairs as parameters.
The switched class layer then completely manages the switched options:
it checks their validity, stores their values and provides a clean
interface to the user layer configuration setting procedures.</p>
<p>The switched class members available to the programmer are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><switched></b> <b class="method">complete</b> <i class="arg">this</i></a></dt>
<dd><p>This procedure is used to tell the switched layer that the derived
class object (a car in the examples) is completely built.
At that time, the initial configuration of the switched object occurs,
using default option values (see procedure <b class="method">options</b>)
eventually overridden by construction time values, passed at the time
of the <b class="method">new</b> operator invocation.
This procedure must be called only once, usually around or at the end
of the derived class constructor.
(<em>Note</em>: Also check the <b class="variable">complete</b> data member later in this
chapter).</p></dd>
<dt><a name="2"><b class="cmd"><switched></b> <b class="method">options</b> <i class="arg">this</i></a></dt>
<dd><p>This procedure must return the configuration description for
<em>all</em> options that the switched object will accept.
It is a pure virtual member procedure and therefore its implementation
is <em>mandatory</em> in the derived class layer.
The procedure must return a list of lists.
Each list pertains to a single option and is composed of the switch
name, the default value for the option and an optional initial value.
For example:</p>
<pre class="doctools_example">
class car {
...
proc options {this} {
return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ]
}
proc set-fuel {this value} {
...
}
...
}
</pre>
<p>In this case, 4 options are specified:
<b class="option">fuel</b>, <b class="option">length</b>, <b class="option">power</b> and <b class="option">width</b>.
The default and initial values for the <b class="option">fuel</b> option are
identical and set to <b class="option">petrol</b>.
For the other options, values are all empty.</p>
<p>For each option, there must be a corresponding
<b class="method">set-<b class="option">option</b></b> procedure defined in the derived class
layer.
For example, since we defined a <b class="option">fuel</b> option, there is a
<b class="method">set-fuel</b> procedure in the car class.
The parameters always are the object identifier (since this is not a
static procedure, but rather a dynamically defined virtual one),
followed by the new value for the option.
A <b class="method">set-<b class="option">option</b></b> procedure is only invoked if the new
value differs from the current one (a caching scheme for improving
performance), or if there is no initial value set in the
<b class="method">options</b> procedure for that option.</p>
<p>In this procedure, if the initial value differs from the
default value or is omitted, then initial configuration is forced and
the corresponding <b class="method">set-<b class="option">option</b></b> procedure is invoked by
the switched <b class="method">complete</b> procedure located at the end of the
derived class constructor.
For example:</p>
<pre class="doctools_example">
class car {
...
proc options {this} {
return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ]
}
...
}
</pre>
<p>In this case, configuration is forced on the <b class="option">fuel</b> and
<b class="option">power</b> options, that is the corresponding
<b class="method">set-<b class="option">option</b></b> procedures will be invoked when the
switched object is constructed (see <b class="method">set-<b class="option">option</b></b>
procedures documentation below).</p>
<p>For the <b class="option">fuel</b> option, since there is no initial value,
the <b class="method">set-<b class="option">fuel</b></b> procedure is called with the default
value (<b class="const">petrol</b>) as argument.
For the <b class="option">power</b> option, since the initial value differs from
the default value, the <b class="method">set-<b class="option">power</b></b> procedure is called
with the initial value as argument (<b class="const">50</b>).</p>
<p>For the other options, since the initial values (last elements
of the option lists) are identical to their default values, the
corresponding <b class="method">set-<b class="option">option</b></b> procedures will not be
invoked. It is the programmer's responsibility to insure that the
initial option values are correct.</p></dd>
<dt><a name="3"><b class="cmd"><switched></b> <b class="method">set-<b class="option">option</b></b> <i class="arg">this</i> <i class="arg">value</i></a></dt>
<dd><p>These procedures may be viewed as dynamic virtual functions.
There must be one implementation per supported option, as returned by
the <b class="method">options</b> procedure.
For example:</p>
<pre class="doctools_example">
class car {
...
proc options {this} {
return [list ...
[list -width {} {}] ]
}
...
proc set-width {this value} {
...
}
...
}
</pre>
<p>Since the <b class="option">-width</b> option was listed in the <b class="method">options</b>
procedure, a <b class="method">set-width</b> procedure implementation is provided, which
of course would proceed to set the width of the car (and would modify
the looks of a graphical representation, for example).</p>
<p>As you add a supported <b class="option">option</b> in the list returned by
the <b class="method">options</b> procedure, the corresponding
<b class="method">set-<b class="option">option</b></b> procedure may be called as soon as the
switched object is complete, which occurs when the switched level
<b class="method">complete</b> procedure is invoked.
For example:</p>
<pre class="doctools_example">
class car {
proc car {this args} switched {args} {
...
switched::complete $this
}
...
proc options {this} {
return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ]
}
proc set-fuel {this value} {
...
}
proc set-length {this value} {
...
}
proc set-power {this value} {
...
}
proc set-width {this value} {
...
}
}
new car
</pre>
<p>In this case, a new car is created with no options, which
causes the car constructor to be called, which in turns calls the
switched level <b class="method">complete</b> procedure after the car object layer
is completely initialized.
At this point, since there are no initial values in any option list in
the options procedure, the <b class="method">set-fuel</b> procedure is called with
its default value of <b class="const">petrol</b> as parameter, followed by the
<b class="method">set-length</b> call with <b class="const">4.5</b> value, <b class="method">set-power</b>
with <b class="const">350</b> value and finally with <b class="method">set-width</b> with
<b class="const">1.8</b> as parameter.
This is a good way to test the <b class="method">set-<b class="option">option</b></b> procedures
when debugging, and when done, just fill-in the initial option values.</p>
<p>The switched layer checks that an option is valid (that is,
listed in the <b class="method">options</b> procedure) but obviously does not check
the validity of the value passed to the <b class="method">set-<b class="option">option</b></b>
procedure, which should throw an error (for example by using the Tcl
error command) if the value is invalid.</p>
<p>The switched layer also keeps track of the options current
values, so that a <b class="method">set-<b class="option">option</b></b> procedure is called
only when the corresponding option value passed as parameter is
different from the current value (see <b class="variable">-option</b> data members
description).</p></dd>
<dt><b class="variable">-option</b></dt>
<dd><p>The <b class="variable">-option</b> data member is an options current value.
There is one for each option listed in the options procedure. It is a
read-only value which the switched layer checks against when an option
is changed.
It is rarely used at the layer derived from switched, except in the
few cases, such as in the following example:</p>
<pre class="doctools_example">
...
proc car::options {this} {
return {
...
{-manufacturer {} {}}
...
}
}
proc car::set-manufacturer {this value} {}
proc car::printData {this} {
puts "manufacturer: $switched::($this,-manufacturer)"
...
}
</pre>
<p>In this case, the manufacturer's name is stored at the switched
layer level (this is why the set-manufacturer procedure has nothing to
do) and later retrieved in the printData procedure.</p></dd>
<dt><b class="variable">complete</b></dt>
<dd><p>The <b class="variable">complete</b> data member (not to be confused with the
<b class="method">complete</b> procedure) is a boolean.
Its initial value is <b class="const">false</b> and it is set to <b class="const">true</b> at
the very end of the switched <b class="method">complete</b> procedure.
It becomes useful when some options should be set at construction time
only and not dynamically, as the following example shows:</p>
<pre class="doctools_example">
proc car::set-width {this value} {
if {$switched::($this,complete)} {
error {option -width cannot be set dynamically}
}
...
}
</pre>
</dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>stooop</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#c_">C++</a>, <a href="../../../../index.html#class">class</a>, <a href="../../../../index.html#object">object</a>, <a href="../../../../index.html#object_oriented">object oriented</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/string/token.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
<div class='fossil-doc' data-title='string::token - Text and string utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">string::token(n) 1 tcllib "Text and string utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>string::token - Regex based iterative lexing</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">string::token <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">fileutil</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::string token text</b> <i class="arg">lex</i> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::string token file</b> <i class="arg">lex</i> <i class="arg">path</i></a></li>
<li><a href="#3"><b class="cmd">::string token chomp</b> <i class="arg">lex</i> <i class="arg">startvar</i> <i class="arg">string</i> <i class="arg">resultvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands for regular expression based lexing
(tokenization) of strings.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::string token text</b> <i class="arg">lex</i> <i class="arg">string</i></a></dt>
<dd><p>This command takes an ordered dictionary <i class="arg">lex</i> mapping regular
expressions to labels, and tokenizes the <i class="arg">string</i> according to
this dictionary.</p>
<p>The result of the command is a list of tokens, where each token
is a 3-element list of label, start- and end-index in the <i class="arg">string</i>.</p>
<p>The command will throw an error if it is not able to tokenize
the whole string.</p></dd>
<dt><a name="2"><b class="cmd">::string token file</b> <i class="arg">lex</i> <i class="arg">path</i></a></dt>
<dd><p>This command is a convenience wrapper around
<b class="cmd">::string token text</b> above, and <b class="cmd">fileutil::cat</b>, enabling
the easy tokenization of whole files.
<em>Note</em> that this command loads the file wholly into memory before
starting to process it.</p>
<p>If the file is too large for this mode of operation a command
directly based on <b class="cmd">::string token chomp</b> below will be
necessary.</p></dd>
<dt><a name="3"><b class="cmd">::string token chomp</b> <i class="arg">lex</i> <i class="arg">startvar</i> <i class="arg">string</i> <i class="arg">resultvar</i></a></dt>
<dd><p>This command is the work horse underlying <b class="cmd">::string token text</b>
above. It is exposed to enable users to write their own lexers, which,
for example may apply different lexing dictionaries according to some
internal state, etc.</p>
<p>The command takes an ordered dictionary <i class="arg">lex</i> mapping
regular expressions to labels, a variable <i class="arg">startvar</i> which
indicates where to start lexing in the input <i class="arg">string</i>, and a
result variable <i class="arg">resultvar</i> to extend.</p>
<p>The result of the command is a tri-state numeric code
indicating one of</p>
<dl class="doctools_definitions">
<dt><b class="const">0</b></dt>
<dd><p>No token found.</p></dd>
<dt><b class="const">1</b></dt>
<dd><p>Token found.</p></dd>
<dt><b class="const">2</b></dt>
<dd><p>End of string reached.</p></dd>
</dl>
<p>Note that recognition of a token from <i class="arg">lex</i> is started at the
character index in <i class="arg">startvar</i>.</p>
<p>If a token was recognized (status <b class="const">1</b>) the command will
update the index in <i class="arg">startvar</i> to point to the first character of
the <i class="arg">string</i> past the recognized token, and it will further extend
the <i class="arg">resultvar</i> with a 3-element list containing the label
associated with the regular expression of the token, and the start-
and end-character-indices of the token in <i class="arg">string</i>.</p>
<p>Neither <i class="arg">startvar</i> nor <i class="arg">resultvar</i> will be updated if
no token is recognized at all.</p>
<p>Note that the regular expressions are applied (tested) in the
order they are specified in <i class="arg">lex</i>, and the first matching pattern
stops the process. Because of this it is recommended to specify the
patterns to lex with from the most specific to the most general.</p>
<p>Further note that all regex patterns are implicitly prefixed
with the constraint escape <b class="const">A</b> to ensure that a match starts
exactly at the character index found in <i class="arg">startvar</i>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#lexing">lexing</a>, <a href="../../../../index.html#regex">regex</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#tokenization">tokenization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/string/token_shell.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
<div class='fossil-doc' data-title='string::token::shell - Text and string utilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">string::token::shell(n) 1.2 tcllib "Text and string utilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>string::token::shell - Parsing of shell command line</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">string::token::shell <span class="opt">?1.2?</span></b></li>
<li>package require <b class="pkgname">string::token <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">fileutil</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::string token shell</b> <span class="opt">?<b class="option">-indices</b>?</span> <span class="opt">?<b class="option">-partial</b>?</span> <span class="opt">?--?</span> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a command which parses a line of text using
basic <b class="syscmd">sh</b>-syntax into a list of words.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::string token shell</b> <span class="opt">?<b class="option">-indices</b>?</span> <span class="opt">?<b class="option">-partial</b>?</span> <span class="opt">?--?</span> <i class="arg">string</i></a></dt>
<dd><p>This command parses the input <i class="arg">string</i> under the assumption of it
following basic <b class="syscmd">sh</b>-syntax.
The result of the command is a list of words in the <i class="arg">string</i>.
An error is thrown if the input does not follow the allowed syntax.
The behaviour can be modified by specifying any of the two options
<b class="option">-indices</b> and <b class="option">-partial</b>.</p>
<dl class="doctools_options">
<dt><b class="option">--</b></dt>
<dd><p>When specified option parsing stops at this point. This option is
needed if the input <i class="arg">string</i> may start with dash. In other words,
this is pretty much required if <i class="arg">string</i> is user input.</p></dd>
<dt><b class="option">-indices</b></dt>
<dd><p>When specified the output is not a list of words, but a list of
4-tuples describing the words. Each tuple contains the type of the
word, its start- and end-indices in the input, and the actual text of
the word.</p>
<p>Note that the length of the word as given by the indices can
differ from the length of the word found in the last element of the
tuple. The indices describe the words extent in the input, including
delimiters, intra-word quoting, etc. whereas for the actual text of
the word delimiters are stripped, intra-word quoting decoded, etc.</p>
<p>The possible token types are</p>
<dl class="doctools_definitions">
<dt><b class="const">PLAIN</b></dt>
<dd><p>Plain word, not quoted.</p></dd>
<dt><b class="const">D:QUOTED</b></dt>
<dd><p>Word is delimited by double-quotes.</p></dd>
<dt><b class="const">S:QUOTED</b></dt>
<dd><p>Word is delimited by single-quotes.</p></dd>
<dt><b class="const">D:QUOTED:PART</b></dt>
<dd></dd>
<dt><b class="const">S:QUOTED:PART</b></dt>
<dd><p>Like the previous types, but the word has no closing quote, i.e. is
incomplete. These token types can occur if and only if the option
<b class="option">-partial</b> was specified, and only for the last word of the
result. If the option <b class="option">-partial</b> was not specified such
incomplete words cause the command to thrown an error instead.</p></dd>
</dl></dd>
<dt><b class="option">-partial</b></dt>
<dd><p>When specified the parser will accept an incomplete quoted word
(i.e. without closing quote) at the end of the line as valid instead
of throwing an error.</p></dd>
</dl>
<p>The basic shell syntax accepted here are unquoted, single- and
double-quoted words, separated by whitespace. Leading and trailing
whitespace are possible too, and stripped.
Shell variables in their various forms are <em>not</em> recognized, nor
are sub-shells.
As for the recognized forms of words, see below for the detailed
specification.</p>
<dl class="doctools_definitions">
<dt><b class="const">single-quoted word</b></dt>
<dd><p>A single-quoted word begins with a single-quote character, i.e.
<b class="const">'</b> (ASCII 39) followed by zero or more unicode characters not a
single-quote, and then closed by a single-quote.</p>
<p>The word must be followed by either the end of the string, or
whitespace. A word cannot directly follow the word.</p></dd>
<dt><b class="const">double-quoted word</b></dt>
<dd><p>A double-quoted word begins with a double-quote character, i.e.
<b class="const">"</b> (ASCII 34) followed by zero or more unicode characters not a
double-quote, and then closed by a double-quote.</p>
<p>Contrary to single-quoted words a double-quote can be embedded
into the word, by prefacing, i.e. escaping, i.e. quoting it with a
backslash character <b class="const">\</b> (ASCII 92). Similarly a backslash
character must be quoted with itself to be inserted literally.</p></dd>
<dt><b class="const">unquoted word</b></dt>
<dd><p>Unquoted words are not delimited by quotes and thus cannot contain
whitespace or single-quote characters. Double-quote and backslash
characters can be put into unquoted words, by quting them like for
double-quoted words.</p></dd>
<dt><b class="const">whitespace</b></dt>
<dd><p>Whitespace is any unicode space character.
This is equivalent to <b class="cmd">string is space</b>, or the regular
expression \\s.</p>
<p>Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bash">bash</a>, <a href="../../../../index.html#lexing">lexing</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#shell">shell</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#tokenization">tokenization</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/stringprep/stringprep.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<div class='fossil-doc' data-title='stringprep - Preparation of Internationalized Strings'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">stringprep(n) 1.0.1 tcllib "Preparation of Internationalized Strings"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>stringprep - Implementation of stringprep</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">stringprep 1.0.1</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::stringprep::register</b> <i class="arg">profile</i> <span class="opt">?<i class="arg">-mapping list</i>?</span> <span class="opt">?<i class="arg">-normalization form</i>?</span> <span class="opt">?<i class="arg">-prohibited list</i>?</span> <span class="opt">?<i class="arg">-prohibitedList list</i>?</span> <span class="opt">?<i class="arg">-prohibitedCommand command</i>?</span> <span class="opt">?<i class="arg">-prohibitedBidi boolean</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::stringprep::stringprep</b> <i class="arg">profile</i> <i class="arg">string</i></a></li>
<li><a href="#3"><b class="cmd">::stringprep::compare</b> <i class="arg">profile</i> <i class="arg">string1</i> <i class="arg">string2</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This is an implementation in Tcl of the Preparation of Internationalized
Strings ("stringprep"). It allows to define stringprep profiles and use
them to prepare Unicode strings for comparison as defined in RFC-3454.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::stringprep::register</b> <i class="arg">profile</i> <span class="opt">?<i class="arg">-mapping list</i>?</span> <span class="opt">?<i class="arg">-normalization form</i>?</span> <span class="opt">?<i class="arg">-prohibited list</i>?</span> <span class="opt">?<i class="arg">-prohibitedList list</i>?</span> <span class="opt">?<i class="arg">-prohibitedCommand command</i>?</span> <span class="opt">?<i class="arg">-prohibitedBidi boolean</i>?</span></a></dt>
<dd><p>Register the <b class="package">stringprep</b> profile named <i class="arg">profile</i>. Options
are the following.</p>
<p>Option <i class="arg">-mapping</i> specifies <b class="package">stringprep</b> mapping tables.
This parameter takes list of tables from appendix B of RFC-3454. The usual
list values are {B.1 B.2} or {B.1 B.3} where B.1 contains characters which
commonly map to nothing, B.3 specifies case folding, and B.2 is used in
profiles with unicode normalization form KC. Defult value is {} which means
no mapping.</p>
<p>Option <i class="arg">-normalization</i> takes a string and if it is nonempty then it
uses as a name of Unicode normalization form. Any value of "D", "C", "KD"
or "KC" may be used, though RFC-3454 defines only two options: no
normalization or normalization using form KC.</p>
<p>Option <i class="arg">-prohibited</i> takes a list of RFC-3454 tables with prohibited
characters. Current version does allow to prohibit either all tables from
C.3 to C.9 or neither of them. An example of this list for RFC-3491 is
{A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}.</p>
<p>Option <i class="arg">-prohibitedList</i> specifies a list of additional prohibited
characters. The list contains not characters themselves but their Unicode
numbers. For example, Nodeprep specification from RFC-3920 forbids the
following codes: {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} (\" \& \' / : < > @).</p>
<p>Option <i class="arg">-prohibitedCommand</i> specifies a command which is called for
every character code in mapped and normalized string. If the command returns
true then the character is considered prohibited. This option is useful when
a list for <i class="arg">-prohibitedList</i> is too large.</p>
<p>Option <i class="arg">-prohibitedBidi</i> takes boolean value and if it is true then the
bidirectional character processing rules defined in section 6 of RFC-3454 are
used.</p></dd>
<dt><a name="2"><b class="cmd">::stringprep::stringprep</b> <i class="arg">profile</i> <i class="arg">string</i></a></dt>
<dd><p>Performs <b class="package">stringprep</b> operations defined in profile <i class="arg">profile</i>
to string <i class="arg">string</i>. Result is a prepared string or one of the following
errors: <i class="arg">invalid_profile</i> (profile <i class="arg">profile</i> is not defined),
<i class="arg">prohibited_character</i> (string <i class="arg">string</i> contains a prohibited character)
or <i class="arg">prohibited_bidi</i> (string <i class="arg">string</i> contains a prohibited bidirectional
sequence).</p></dd>
<dt><a name="3"><b class="cmd">::stringprep::compare</b> <i class="arg">profile</i> <i class="arg">string1</i> <i class="arg">string2</i></a></dt>
<dd><p>Compares two unicode strings prepared accordingly to <b class="package">stringprep</b>
profile <i class="arg">profile</i>. The command returns 0 if prepared strings are equal,
-1 if <i class="arg">string1</i> is lexicographically less than <i class="arg">string2</i>, or
1 if <i class="arg">string1</i> is lexicographically greater than <i class="arg">string2</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>Nameprep profile definition (see RFC-3491):</p>
<pre class="doctools_example">
::stringprep::register nameprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1
</pre>
<p>Nodeprep and resourceprep profile definitions (see RFC-3920):</p>
<pre class="doctools_example">
::stringprep::register nodeprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedList {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} -prohibitedBidi 1
::stringprep::register resourceprep -mapping {B.1} -normalization KC -prohibited {A.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>"Preparation of Internationalized Strings ('stringprep')",
(<a href="http://www.ietf.org/rfc/rfc3454.txt">http://www.ietf.org/rfc/rfc3454.txt</a>)</p></li>
<li><p>"Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)",
(<a href="http://www.ietf.org/rfc/rfc3491.txt">http://www.ietf.org/rfc/rfc3491.txt</a>)</p></li>
<li><p>"Extensible Messaging and Presence Protocol (XMPP): Core",
(<a href="http://www.ietf.org/rfc/rfc3920.txt">http://www.ietf.org/rfc/rfc3920.txt</a>)</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Sergei Golovan</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>stringprep</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="unicode.html">unicode(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#stringprep">stringprep</a>, <a href="../../../../index.html#unicode">unicode</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2009, Sergei Golovan <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/stringprep/stringprep_data.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
<div class='fossil-doc' data-title='stringprep::data - Preparation of Internationalized Strings'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">stringprep::data(n) 1.0.1 tcllib "Preparation of Internationalized Strings"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>stringprep::data - stringprep data tables, generated, internal</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">stringprep::data 1.0.1</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">stringprep::data</b> package is a helper for
<b class="package"><a href="stringprep.html">stringprep</a></b>, providing it with the data tables needed to
perform its functions. It is an <em>internal</em> package which should
not be accessed on its own. Because of that it has no publicly
documented API either. Its implementation is generated by a script.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>stringprep</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#stringprep">stringprep</a>, <a href="../../../../index.html#unicode">unicode</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2009, Sergei Golovan <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/stringprep/unicode.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<div class='fossil-doc' data-title='unicode - Unicode normalization'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">unicode(n) 1.0.0 tcllib "Unicode normalization"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>unicode - Implementation of Unicode normalization</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">unicode 1.0</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::unicode::fromstring</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::unicode::tostring</b> <i class="arg">uclist</i></a></li>
<li><a href="#3"><b class="cmd">::unicode::normalize</b> <i class="arg">form</i> <i class="arg">uclist</i></a></li>
<li><a href="#4"><b class="cmd">::unicode::normalizeS</b> <i class="arg">form</i> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This is an implementation in Tcl of the Unicode normalization forms.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::unicode::fromstring</b> <i class="arg">string</i></a></dt>
<dd><p>Converts <i class="arg">string</i> to list of integer Unicode character codes which
is used in <b class="package">unicode</b> for internal string representation.</p></dd>
<dt><a name="2"><b class="cmd">::unicode::tostring</b> <i class="arg">uclist</i></a></dt>
<dd><p>Converts list of integers <i class="arg">uclist</i> back to Tcl string.</p></dd>
<dt><a name="3"><b class="cmd">::unicode::normalize</b> <i class="arg">form</i> <i class="arg">uclist</i></a></dt>
<dd><p>Normalizes Unicode characters list <i class="arg">ulist</i> according to <i class="arg">form</i>
and returns the normalized list. Form <i class="arg">form</i> takes one of the following
values: <i class="arg">D</i> (canonical decomposition), <i class="arg">C</i> (canonical decomposition, followed
by canonical composition), <i class="arg">KD</i> (compatibility decomposition), or <i class="arg">KC</i>
(compatibility decomposition, followed by canonical composition).</p></dd>
<dt><a name="4"><b class="cmd">::unicode::normalizeS</b> <i class="arg">form</i> <i class="arg">string</i></a></dt>
<dd><p>A shortcut to
::unicode::tostring [unicode::normalize \$form [::unicode::fromstring \$string]].
Normalizes Tcl string and returns normalized string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
% ::unicode::fromstring "\u0410\u0411\u0412\u0413"
1040 1041 1042 1043
% ::unicode::tostring {49 50 51 52 53}
12345
%
</pre>
<pre class="doctools_example">
% ::unicode::normalize D {7692 775}
68 803 775
% ::unicode::normalizeS KD "\u1d2c"
A
%
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>"Unicode Standard Annex #15: Unicode Normalization Forms",
(<a href="http://unicode.org/reports/tr15/">http://unicode.org/reports/tr15/</a>)</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Sergei Golovan</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>stringprep</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="stringprep.html">stringprep(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#normalization">normalization</a>, <a href="../../../../index.html#unicode">unicode</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007, Sergei Golovan <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/stringprep/unicode_data.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
<div class='fossil-doc' data-title='unicode::data - Preparation of Internationalized Strings'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">unicode::data(n) 1.0.0 tcllib "Preparation of Internationalized Strings"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>unicode::data - unicode data tables, generated, internal</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">unicode::data 1.0.0</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">unicode::data</b> package is a helper for
<b class="package"><a href="unicode.html">unicode</a></b>, providing it with the data tables needed to
perform its functions. It is an <em>internal</em> package which should
not be accessed on its own. Because of that it has no publicly
documented API either. Its implementation is generated by a script.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>stringprep</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#stringprep">stringprep</a>, <a href="../../../../index.html#unicode">unicode</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007, Sergei Golovan <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/disjointset.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
<div class='fossil-doc' data-title='struct::disjointset - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::disjointset(n) 1.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::disjointset - Disjoint set data structure</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">struct::disjointset <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::disjointset</b> <i class="arg">disjointsetName</i></a></li>
<li><a href="#2"><i class="arg">disjointsetName</i> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">disjointsetName</i> <b class="method">add-element</b> <i class="arg">item</i></a></li>
<li><a href="#4"><i class="arg">disjointsetName</i> <b class="method">add-partition</b> <i class="arg">elements</i></a></li>
<li><a href="#5"><i class="arg">disjointsetName</i> <b class="method">partitions</b></a></li>
<li><a href="#6"><i class="arg">disjointsetName</i> <b class="method">num-partitions</b></a></li>
<li><a href="#7"><i class="arg">disjointsetName</i> <b class="method">equal</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#8"><i class="arg">disjointsetName</i> <b class="method">merge</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#9"><i class="arg">disjointsetName</i> <b class="method">find</b> <i class="arg">e</i></a></li>
<li><a href="#10"><i class="arg">disjointsetName</i> <b class="method">exemplars</b></a></li>
<li><a href="#11"><i class="arg">disjointsetName</i> <b class="method">find-exemplar</b> <i class="arg">e</i></a></li>
<li><a href="#12"><i class="arg">disjointsetName</i> <b class="method">destroy</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides <i class="term">disjoint sets</i>. An alternative name for
this kind of structure is <i class="term">merge-find</i>.</p>
<p>Normally when dealing with sets and their elements the question is "Is
this element E contained in this set S?", with both E and S known.</p>
<p>Here the question is "Which of several sets contains the element
E?". I.e. while the element is known, the set is not, and we wish to
find it quickly. It is not quite the inverse of the original question,
but close.
Another operation which is often wanted is that of quickly merging two
sets into one, with the result still fast for finding elements. Hence
the alternative term <i class="term">merge-find</i> for this.</p>
<p>Why now is this named a <i class="term">disjoint-set</i> ?
Because another way of describing the whole situation is that we have</p>
<ul class="doctools_itemized">
<li><p>a finite <i class="term"><a href="../../../../index.html#set">set</a></i> S, containing</p></li>
<li><p>a number of <i class="term">elements</i> E, split into</p></li>
<li><p>a set of <i class="term">partitions</i> P. The latter term
applies, because the intersection of each pair P, P' of
partitions is empty, with the union of all partitions
covering the whole set.</p></li>
<li><p>An alternative name for the <i class="term">partitions</i> would be
<i class="term">equvalence classes</i>, and all elements in the same
class are considered as equal.</p></li>
</ul>
<p>Here is a pictorial representation of the concepts listed above:</p>
<pre class="doctools_example">
+-----------------+ The outer lines are the boundaries of the set S.
| / | The inner regions delineated by the skewed lines
| * / * | are the partitions P. The *'s denote the elements
| * / \ | E in the set, each in a single partition, their
|* / \ | equivalence class.
| / * \ |
| / * / |
| * /\ * / |
| / \ / |
| / \/ * |
| / * \ |
| / * \ |
+-----------------+
</pre>
<p>For more information see <a href="http://en.wikipedia.org/wiki/Disjoint_set_data_structure">http://en.wikipedia.org/wiki/Disjoint_set_data_structure</a>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports a single command, <b class="cmd">::struct::disjointset</b>. All
functionality provided here can be reached through a subcommand of
this command.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::disjointset</b> <i class="arg">disjointsetName</i></a></dt>
<dd><p>Creates a new disjoint set object with an associated global Tcl
command whose name is <em>disjointsetName</em>. This command may be used
to invoke various operations on the disjointset. It has the following
general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">disjointsetName</i> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The <b class="cmd">option</b> and the <i class="arg">arg</i>s determine the exact behavior of
the command. The following commands are possible for disjointset
objects:</p></dd>
</dl></dd>
<dt><a name="3"><i class="arg">disjointsetName</i> <b class="method">add-element</b> <i class="arg">item</i></a></dt>
<dd><p>Creates a new partition in the specified disjoint set, and fills it
with the single item <i class="arg">item</i>. The command maintains
the integrity of the disjoint set, i.e. it verifies that none of the
<i class="arg">elements</i> are already part of the disjoint set and throws an
error otherwise.</p>
<p>The result of this method is the empty string.</p>
<p>This method runs in constant time.</p></dd>
<dt><a name="4"><i class="arg">disjointsetName</i> <b class="method">add-partition</b> <i class="arg">elements</i></a></dt>
<dd><p>Creates a new partition in specified disjoint set, and fills it with
the values found in the set of <i class="arg">elements</i>. The command maintains
the integrity of the disjoint set, i.e. it verifies that none of the
<i class="arg">elements</i> are already part of the disjoint set and throws an
error otherwise.</p>
<p>The result of the command is the empty string.</p>
<p>This method runs in time proportional to the size of <i class="arg">elements</i>].</p></dd>
<dt><a name="5"><i class="arg">disjointsetName</i> <b class="method">partitions</b></a></dt>
<dd><p>Returns the set of partitions the named disjoint set currently
consists of. The form of the result is a list of lists; the inner
lists contain the elements of the partitions.</p>
<p>This method runs in time O(N*alpha(N)),
where N is the number of elements in the disjoint set and alpha
is the inverse Ackermann function.</p></dd>
<dt><a name="6"><i class="arg">disjointsetName</i> <b class="method">num-partitions</b></a></dt>
<dd><p>Returns the number of partitions the named disjoint set currently
consists of.</p>
<p>This method runs in constant time.</p></dd>
<dt><a name="7"><i class="arg">disjointsetName</i> <b class="method">equal</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Determines if the two elements <i class="arg">a</i> and <i class="arg">b</i> of the disjoint set
belong to the same partition. The result of the method is a boolean
value, <b class="const">True</b> if the two elements are contained in the same
partition, and <b class="const">False</b> otherwise.</p>
<p>An error will be thrown if either <i class="arg">a</i> or <i class="arg">b</i> are not elements
of the disjoint set.</p>
<p>This method runs in amortized time O(alpha(N)), where N is the number of
elements in the larger partition and alpha is the inverse Ackermann function.</p></dd>
<dt><a name="8"><i class="arg">disjointsetName</i> <b class="method">merge</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Determines the partitions the elements <i class="arg">a</i> and <i class="arg">b</i> are
contained in and merges them into a single partition. If the two
elements were already contained in the same partition nothing will
change.</p>
<p>The result of the method is the empty string.</p>
<p>This method runs in amortized time O(alpha(N)), where N is the number of
items in the larger of the partitions being merged. The worst case time
is O(N).</p></dd>
<dt><a name="9"><i class="arg">disjointsetName</i> <b class="method">find</b> <i class="arg">e</i></a></dt>
<dd><p>Returns a list of the members of the partition of the disjoint set
which contains the element
<i class="arg">e</i>.</p>
<p>This method runs in O(N*alpha(N)) time, where N is the total number of
items in the disjoint set and alpha is the inverse Ackermann function,
See <b class="method">find-exemplar</b> for a faster method, if all that is needed
is a unique identifier for the partition, rather than an enumeration
of all its elements.</p></dd>
<dt><a name="10"><i class="arg">disjointsetName</i> <b class="method">exemplars</b></a></dt>
<dd><p>Returns a list containing an exemplar of each partition in the disjoint
set. The exemplar is a member of the partition, chosen arbitrarily.</p>
<p>This method runs in O(N*alpha(N)) time, where N is the total number of items
in the disjoint set and alpha is the inverse Ackermann function.</p></dd>
<dt><a name="11"><i class="arg">disjointsetName</i> <b class="method">find-exemplar</b> <i class="arg">e</i></a></dt>
<dd><p>Returns the exemplar of the partition of the disjoint set containing
the element <i class="arg">e</i>. Throws an error if <i class="arg">e</i> is not found in the
disjoint set. The exemplar is an arbitrarily chosen member of the partition.
The only operation that will change the exemplar of any partition is
<b class="method">merge</b>.</p>
<p>This method runs in O(alpha(N)) time, where N is the number of items in
the partition containing E, and alpha is the inverse Ackermann function.</p></dd>
<dt><a name="12"><i class="arg">disjointsetName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the disjoint set object and all associated memory.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: disjointset</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#disjoint_set">disjoint set</a>, <a href="../../../../index.html#equivalence_class">equivalence class</a>, <a href="../../../../index.html#find">find</a>, <a href="../../../../index.html#merge_find">merge find</a>, <a href="../../../../index.html#partition">partition</a>, <a href="../../../../index.html#partitioned_set">partitioned set</a>, <a href="../../../../index.html#union">union</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/graph.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
|
<div class='fossil-doc' data-title='struct::graph - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::graph(n) 2.4.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::graph - Create and manipulate directed graph objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Changes for 2.0</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">struct::graph <span class="opt">?2.4.1?</span></b></li>
<li>package require <b class="pkgname">struct::list <span class="opt">?1.5?</span></b></li>
<li>package require <b class="pkgname">struct::set <span class="opt">?2.2.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::graph</b> <span class="opt">?<i class="arg">graphName</i>?</span> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">source</i>?</span></a></li>
<li><a href="#2"><b class="cmd">graphName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">graphName</i> <b class="method">=</b> <i class="arg">sourcegraph</i></a></li>
<li><a href="#4"><i class="arg">graphName</i> <b class="method">--></b> <i class="arg">destgraph</i></a></li>
<li><a href="#5"><i class="arg">graphName</i> <b class="method">append</b> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#6"><i class="arg">graphName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></li>
<li><a href="#7"><i class="arg">graphName</i> <b class="method">destroy</b></a></li>
<li><a href="#8"><i class="arg">graphName</i> <b class="method">arc append</b> <i class="arg">arc</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#9"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i></a></li>
<li><a href="#10"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i> <b class="option">-arcs</b> <i class="arg">list</i></a></li>
<li><a href="#11"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i> <b class="option">-glob</b> <i class="arg">globpattern</i></a></li>
<li><a href="#12"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i> <b class="option">-regexp</b> <i class="arg">repattern</i></a></li>
<li><a href="#13"><i class="arg">graphName</i> <b class="method">arc delete</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">arc</i> ...?</span></a></li>
<li><a href="#14"><i class="arg">graphName</i> <b class="method">arc exists</b> <i class="arg">arc</i></a></li>
<li><a href="#15"><i class="arg">graphName</i> <b class="method">arc flip</b> <i class="arg">arc</i></a></li>
<li><a href="#16"><i class="arg">graphName</i> <b class="method">arc get</b> <i class="arg">arc</i> <i class="arg">key</i></a></li>
<li><a href="#17"><i class="arg">graphName</i> <b class="method">arc getall</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#18"><i class="arg">graphName</i> <b class="method">arc getunweighted</b></a></li>
<li><a href="#19"><i class="arg">graphName</i> <b class="method">arc getweight</b> <i class="arg">arc</i></a></li>
<li><a href="#20"><i class="arg">graphName</i> <b class="method">arc keys</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#21"><i class="arg">graphName</i> <b class="method">arc keyexists</b> <i class="arg">arc</i> <i class="arg">key</i></a></li>
<li><a href="#22"><i class="arg">graphName</i> <b class="method">arc insert</b> <i class="arg">start</i> <i class="arg">end</i> <span class="opt">?<i class="arg">child</i>?</span></a></li>
<li><a href="#23"><i class="arg">graphName</i> <b class="method">arc lappend</b> <i class="arg">arc</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#24"><i class="arg">graphName</i> <b class="method">arc rename</b> <i class="arg">arc</i> <i class="arg">newname</i></a></li>
<li><a href="#25"><i class="arg">graphName</i> <b class="method">arc set</b> <i class="arg">arc</i> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#26"><i class="arg">graphName</i> <b class="method">arc setunweighted</b> <span class="opt">?<i class="arg">weight</i>?</span></a></li>
<li><a href="#27"><i class="arg">graphName</i> <b class="method">arc setweight</b> <i class="arg">arc</i> <i class="arg">weight</i></a></li>
<li><a href="#28"><i class="arg">graphName</i> <b class="method">arc unsetweight</b> <i class="arg">arc</i></a></li>
<li><a href="#29"><i class="arg">graphName</i> <b class="method">arc hasweight</b> <i class="arg">arc</i></a></li>
<li><a href="#30"><i class="arg">graphName</i> <b class="method">arc source</b> <i class="arg">arc</i></a></li>
<li><a href="#31"><i class="arg">graphName</i> <b class="method">arc target</b> <i class="arg">arc</i></a></li>
<li><a href="#32"><i class="arg">graphName</i> <b class="method">arc nodes</b> <i class="arg">arc</i></a></li>
<li><a href="#33"><i class="arg">graphName</i> <b class="method">arc move-source</b> <i class="arg">arc</i> <i class="arg">newsource</i></a></li>
<li><a href="#34"><i class="arg">graphName</i> <b class="method">arc move-target</b> <i class="arg">arc</i> <i class="arg">newtarget</i></a></li>
<li><a href="#35"><i class="arg">graphName</i> <b class="method">arc move</b> <i class="arg">arc</i> <i class="arg">newsource</i> <i class="arg">newtarget</i></a></li>
<li><a href="#36"><i class="arg">graphName</i> <b class="method">arc unset</b> <i class="arg">arc</i> <i class="arg">key</i></a></li>
<li><a href="#37"><i class="arg">graphName</i> <b class="method">arc weights</b></a></li>
<li><a href="#38"><i class="arg">graphName</i> <b class="method">arcs</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-filter <i class="arg">cmdprefix</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">node node...</i>?</span></a></li>
<li><a href="#39"><i class="arg">graphName</i> <b class="method">lappend</b> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#40"><i class="arg">graphName</i> <b class="method">node append</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#41"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i></a></li>
<li><a href="#42"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i> <b class="option">-nodes</b> <i class="arg">list</i></a></li>
<li><a href="#43"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i> <b class="option">-glob</b> <i class="arg">globpattern</i></a></li>
<li><a href="#44"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i> <b class="option">-regexp</b> <i class="arg">repattern</i></a></li>
<li><a href="#45"><i class="arg">graphName</i> <b class="method">node degree</b> <span class="opt">?-in|-out?</span> <i class="arg">node</i></a></li>
<li><a href="#46"><i class="arg">graphName</i> <b class="method">node delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i>...?</span></a></li>
<li><a href="#47"><i class="arg">graphName</i> <b class="method">node exists</b> <i class="arg">node</i></a></li>
<li><a href="#48"><i class="arg">graphName</i> <b class="method">node get</b> <i class="arg">node</i> <i class="arg">key</i></a></li>
<li><a href="#49"><i class="arg">graphName</i> <b class="method">node getall</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#50"><i class="arg">graphName</i> <b class="method">node keys</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#51"><i class="arg">graphName</i> <b class="method">node keyexists</b> <i class="arg">node</i> <i class="arg">key</i></a></li>
<li><a href="#52"><i class="arg">graphName</i> <b class="method">node insert</b> <span class="opt">?<i class="arg">node</i>...?</span></a></li>
<li><a href="#53"><i class="arg">graphName</i> <b class="method">node lappend</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#54"><i class="arg">graphName</i> <b class="method">node opposite</b> <i class="arg">node</i> <i class="arg">arc</i></a></li>
<li><a href="#55"><i class="arg">graphName</i> <b class="method">node rename</b> <i class="arg">node</i> <i class="arg">newname</i></a></li>
<li><a href="#56"><i class="arg">graphName</i> <b class="method">node set</b> <i class="arg">node</i> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#57"><i class="arg">graphName</i> <b class="method">node unset</b> <i class="arg">node</i> <i class="arg">key</i></a></li>
<li><a href="#58"><i class="arg">graphName</i> <b class="method">nodes</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-filter <i class="arg">cmdprefix</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">node</i> <i class="arg">node</i>...?</span></a></li>
<li><a href="#59"><i class="arg">graphName</i> <b class="method">get</b> <i class="arg">key</i></a></li>
<li><a href="#60"><i class="arg">graphName</i> <b class="method">getall</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#61"><i class="arg">graphName</i> <b class="method">keys</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#62"><i class="arg">graphName</i> <b class="method">keyexists</b> <i class="arg">key</i></a></li>
<li><a href="#63"><i class="arg">graphName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">node</i>...?</span></a></li>
<li><a href="#64"><i class="arg">graphName</i> <b class="method">set</b> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#65"><i class="arg">graphName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></li>
<li><a href="#66"><i class="arg">graphName</i> <b class="method">unset</b> <i class="arg">key</i></a></li>
<li><a href="#67"><i class="arg">graphName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?-order <i class="arg">order</i>?</span> <span class="opt">?-type <i class="arg">type</i>?</span> <span class="opt">?-dir <i class="arg">direction</i>?</span> -command <i class="arg">cmd</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>A directed graph is a structure containing two collections of
elements, called <i class="term">nodes</i> and <i class="term">arcs</i> respectively, together
with a relation ("connectivity") that places a general structure upon
the nodes and arcs.</p>
<p>Each arc is connected to two nodes, one of which is called the
<i class="term"><a href="../../../../index.html#source">source</a></i> and the other the <i class="term">target</i>. This imposes a
direction upon the arc, which is said to go from the source to the
target. It is allowed that source and target of an arc are the same
node. Such an arc is called a <i class="term"><a href="../../../../index.html#loop">loop</a></i>.
Whenever a node is either the source or target of an arc both are said
to be <i class="term"><a href="../../../../index.html#adjacent">adjacent</a></i>. This extends into a relation between nodes,
i.e. if two nodes are connected through at least one arc they are said
to be <i class="term"><a href="../../../../index.html#adjacent">adjacent</a></i> too.</p>
<p>Each node can be the source and target for any number of arcs. The
former are called the <i class="term">outgoing arcs</i> of the node, the latter
the <i class="term">incoming arcs</i> of the node. The number of arcs in either
set is called the <i class="term">in-degree</i> resp. the <i class="term">out-degree</i> of the
node.</p>
<p>In addition to maintaining the node and arc relationships, this graph
implementation allows any number of named <i class="term">attributes</i> to be
associated with the graph itself, and each node or arc.</p>
<p><em>Note:</em> The major version of the package <b class="package"><a href="../../../../index.html#struct">struct</a></b> has
been changed to version 2.0, due to backward incompatible changes in
the API of this module. Please read the section
<span class="sectref"><a href="#section2">Changes for 2.0</a></span> for a full list of all changes,
incompatible and otherwise.</p>
<p><em>Note:</em> A C-implementation of the command can be had from the
location <a href="http://www.purl.org/NET/schlenker/tcl/cgraph">http://www.purl.org/NET/schlenker/tcl/cgraph</a>. See also
<a href="http://wiki.tcl.tk/cgraph">http://wiki.tcl.tk/cgraph</a>. This implementation uses a bit less
memory than the tcl version provided here directly, and is faster. Its
support is limited to versions of the package before 2.0.</p>
<p>As of version 2.2 of this package a critcl based C implementation is
available from here as well. This implementation however requires Tcl
8.4 to run.</p>
<p>The main command of the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::graph</b> <span class="opt">?<i class="arg">graphName</i>?</span> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">source</i>?</span></a></dt>
<dd><p>The command creates a new graph object with an associated global Tcl
command whose name is <i class="arg">graphName</i>. This command may be used to
invoke various operations on the graph. It has the following general
form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">graphName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>If <i class="arg">graphName</i> is not specified a unique name will be generated by
the package itself. If a <i class="arg">source</i> is specified the new graph will
be initialized to it. For the operators <b class="const">=</b>, <b class="const">:=</b>, and
<b class="const">as</b> the <i class="arg">source</i> argument is interpreted as the name of
another graph object, and the assignment operator <b class="method">=</b> will be
executed. For the operator <b class="const">deserialize</b> the <i class="arg">source</i> is a
serialized graph object and <b class="method">deserialize</b> will be executed.</p>
<p>In other words</p>
<pre class="doctools_example">
::struct::graph mygraph = b
</pre>
<p>is equivalent to</p>
<pre class="doctools_example">
::struct::graph mygraph
mygraph = b
</pre>
<p>and</p>
<pre class="doctools_example">
::struct::graph mygraph deserialize $b
</pre>
<p>is equivalent to</p>
<pre class="doctools_example">
::struct::graph mygraph
mygraph deserialize $b
</pre>
</dd>
</dl>
<p>The following commands are possible for graph objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">graphName</i> <b class="method">=</b> <i class="arg">sourcegraph</i></a></dt>
<dd><p>This is the <i class="term">assignment</i> operator for graph objects. It copies
the graph contained in the graph object <i class="arg">sourcegraph</i> over the
graph data in <i class="arg">graphName</i>. The old contents of <i class="arg">graphName</i> are
deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">graphName</i> <b class="method">deserialize</b> [<i class="arg">sourcegraph</i> <b class="method">serialize</b>]
</pre>
<p>The operation assumes that the <i class="arg">sourcegraph</i> provides the method
<b class="method">serialize</b> and that this method returns a valid graph
serialization.</p></dd>
<dt><a name="4"><i class="arg">graphName</i> <b class="method">--></b> <i class="arg">destgraph</i></a></dt>
<dd><p>This is the <i class="term">reverse assignment</i> operator for graph objects. It
copies the graph contained in the graph object <i class="arg">graphName</i> over
the graph data in the object <i class="arg">destgraph</i>.
The old contents of <i class="arg">destgraph</i> are deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">destgraph</i> <b class="method">deserialize</b> [<i class="arg">graphName</i> <b class="method">serialize</b>]
</pre>
<p>The operation assumes that the <i class="arg">destgraph</i> provides the method
<b class="method">deserialize</b> and that this method takes a graph serialization.</p></dd>
<dt><a name="5"><i class="arg">graphName</i> <b class="method">append</b> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with the graph.
Returns the new value given to the attribute <i class="arg">key</i>.</p></dd>
<dt><a name="6"><i class="arg">graphName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces the graph
data in <i class="arg">graphName</i> with the graph described by the
<i class="arg">serialization</i> value. The old contents of <i class="arg">graphName</i> are
deleted by this operation.</p></dd>
<dt><a name="7"><i class="arg">graphName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the graph, including its storage space and associated command.</p></dd>
<dt><a name="8"><i class="arg">graphName</i> <b class="method">arc append</b> <i class="arg">arc</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with an
<i class="arg">arc</i>. Returns the new value given to the attribute <i class="arg">key</i>.</p></dd>
<dt><a name="9"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i></a></dt>
<dd></dd>
<dt><a name="10"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i> <b class="option">-arcs</b> <i class="arg">list</i></a></dt>
<dd></dd>
<dt><a name="11"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i> <b class="option">-glob</b> <i class="arg">globpattern</i></a></dt>
<dd></dd>
<dt><a name="12"><i class="arg">graphName</i> <b class="method">arc attr</b> <i class="arg">key</i> <b class="option">-regexp</b> <i class="arg">repattern</i></a></dt>
<dd><p>This method retrieves the value of the attribute named <i class="arg">key</i>, for
all arcs in the graph (matching the restriction specified via one of
the possible options) and having the specified attribute.</p>
<p>The result is a dictionary mapping from arc names to the value of
attribute <i class="arg">key</i> at that arc.
Arcs not having the attribute <i class="arg">key</i>, or not passing a
specified restriction, are not listed in the result.</p>
<p>The possible restrictions are:</p>
<dl class="doctools_options">
<dt><b class="option">-arcs</b></dt>
<dd><p>The value is a list of arcs. Only the arcs mentioned in this list
are searched for the attribute.</p></dd>
<dt><b class="option">-glob</b></dt>
<dd><p>The value is a glob pattern. Only the arcs in the graph whose names
match this pattern are searched for the attribute.</p></dd>
<dt><b class="option">-regexp</b></dt>
<dd><p>The value is a regular expression. Only the arcs in the graph whose
names match this pattern are searched for the attribute.</p></dd>
</dl></dd>
<dt><a name="13"><i class="arg">graphName</i> <b class="method">arc delete</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">arc</i> ...?</span></a></dt>
<dd><p>Remove the specified arcs from the graph.</p></dd>
<dt><a name="14"><i class="arg">graphName</i> <b class="method">arc exists</b> <i class="arg">arc</i></a></dt>
<dd><p>Return true if the specified <i class="arg">arc</i> exists in the graph.</p></dd>
<dt><a name="15"><i class="arg">graphName</i> <b class="method">arc flip</b> <i class="arg">arc</i></a></dt>
<dd><p>Reverses the direction of the named <i class="arg">arc</i>, i.e. the source and
target nodes of the arc are exchanged with each other.</p></dd>
<dt><a name="16"><i class="arg">graphName</i> <b class="method">arc get</b> <i class="arg">arc</i> <i class="arg">key</i></a></dt>
<dd><p>Returns the value associated with the key <i class="arg">key</i> for the <i class="arg">arc</i>.</p></dd>
<dt><a name="17"><i class="arg">graphName</i> <b class="method">arc getall</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a dictionary (suitable for use with [<b class="cmd">array set</b>])
for the <i class="arg">arc</i>.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned dictionary. The pattern
is a <b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="18"><i class="arg">graphName</i> <b class="method">arc getunweighted</b></a></dt>
<dd><p>Returns a list containing the names of all arcs in the graph which
have no weight associated with them.</p></dd>
<dt><a name="19"><i class="arg">graphName</i> <b class="method">arc getweight</b> <i class="arg">arc</i></a></dt>
<dd><p>Returns the weight associated with the <i class="arg">arc</i>. Throws an error if
the arc has no weight associated with it.</p></dd>
<dt><a name="20"><i class="arg">graphName</i> <b class="method">arc keys</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of keys for the <i class="arg">arc</i>.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned list. The pattern is a
<b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="21"><i class="arg">graphName</i> <b class="method">arc keyexists</b> <i class="arg">arc</i> <i class="arg">key</i></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the <i class="arg">arc</i>.</p></dd>
<dt><a name="22"><i class="arg">graphName</i> <b class="method">arc insert</b> <i class="arg">start</i> <i class="arg">end</i> <span class="opt">?<i class="arg">child</i>?</span></a></dt>
<dd><p>Insert an arc named <i class="arg">child</i> into the graph beginning at the node
<i class="arg">start</i> and ending at the node <i class="arg">end</i>. If the name of the new
arc is not specified the system will generate a unique name of the
form <em>arc</em><i class="arg">x</i>.</p></dd>
<dt><a name="23"><i class="arg">graphName</i> <b class="method">arc lappend</b> <i class="arg">arc</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with an <i class="arg">arc</i>. Returns the new value given to the
attribute <i class="arg">key</i>.</p></dd>
<dt><a name="24"><i class="arg">graphName</i> <b class="method">arc rename</b> <i class="arg">arc</i> <i class="arg">newname</i></a></dt>
<dd><p>Renames the arc <i class="arg">arc</i> to <i class="arg">newname</i>. An error is thrown if
either the arc does not exist, or a arc with name <i class="arg">newname</i> does
exist. The result of the command is the new name of the arc.</p></dd>
<dt><a name="25"><i class="arg">graphName</i> <b class="method">arc set</b> <i class="arg">arc</i> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with an arc.
An arc may have any number of keyed values associated with it.
If <i class="arg">value</i> is not specified, this command returns the current value assigned to the key;
if <i class="arg">value</i> is specified, this command assigns that value to the key, and returns
that value.</p></dd>
<dt><a name="26"><i class="arg">graphName</i> <b class="method">arc setunweighted</b> <span class="opt">?<i class="arg">weight</i>?</span></a></dt>
<dd><p>Sets the weight of all arcs without a weight to <i class="arg">weight</i>. Returns
the empty string as its result. If not present <i class="arg">weight</i> defaults
to <b class="const">0</b>.</p></dd>
<dt><a name="27"><i class="arg">graphName</i> <b class="method">arc setweight</b> <i class="arg">arc</i> <i class="arg">weight</i></a></dt>
<dd><p>Sets the weight of the <i class="arg">arc</i> to <i class="arg">weight</i>. Returns <i class="arg">weight</i>.</p></dd>
<dt><a name="28"><i class="arg">graphName</i> <b class="method">arc unsetweight</b> <i class="arg">arc</i></a></dt>
<dd><p>Removes the weight of the <i class="arg">arc</i>, if present. Does nothing
otherwise. Returns the empty string.</p></dd>
<dt><a name="29"><i class="arg">graphName</i> <b class="method">arc hasweight</b> <i class="arg">arc</i></a></dt>
<dd><p>Determines if the <i class="arg">arc</i> has a weight associated with it. The
result is a boolean value, <b class="const">True</b> if a weight is defined, and
<b class="const">False</b> otherwise.</p></dd>
<dt><a name="30"><i class="arg">graphName</i> <b class="method">arc source</b> <i class="arg">arc</i></a></dt>
<dd><p>Return the node the given <i class="arg">arc</i> begins at.</p></dd>
<dt><a name="31"><i class="arg">graphName</i> <b class="method">arc target</b> <i class="arg">arc</i></a></dt>
<dd><p>Return the node the given <i class="arg">arc</i> ends at.</p></dd>
<dt><a name="32"><i class="arg">graphName</i> <b class="method">arc nodes</b> <i class="arg">arc</i></a></dt>
<dd><p>Return the nodes the given <i class="arg">arc</i> begins and ends at,
as a two-element list.</p></dd>
<dt><a name="33"><i class="arg">graphName</i> <b class="method">arc move-source</b> <i class="arg">arc</i> <i class="arg">newsource</i></a></dt>
<dd><p>Changes the source node of the arc to <i class="arg">newsource</i>. It can be said
that the arc rotates around its target node.</p></dd>
<dt><a name="34"><i class="arg">graphName</i> <b class="method">arc move-target</b> <i class="arg">arc</i> <i class="arg">newtarget</i></a></dt>
<dd><p>Changes the target node of the arc to <i class="arg">newtarget</i>. It can be said
that the arc rotates around its source node.</p></dd>
<dt><a name="35"><i class="arg">graphName</i> <b class="method">arc move</b> <i class="arg">arc</i> <i class="arg">newsource</i> <i class="arg">newtarget</i></a></dt>
<dd><p>Changes both source and target nodes of the arc to <i class="arg">newsource</i>,
and <i class="arg">newtarget</i> resp.</p></dd>
<dt><a name="36"><i class="arg">graphName</i> <b class="method">arc unset</b> <i class="arg">arc</i> <i class="arg">key</i></a></dt>
<dd><p>Remove a keyed value from the arc <i class="arg">arc</i>. The method will do
nothing if the <i class="arg">key</i> does not exist.</p></dd>
<dt><a name="37"><i class="arg">graphName</i> <b class="method">arc weights</b></a></dt>
<dd><p>Returns a dictionary whose keys are the names of all arcs which have a
weight associated with them, and the values are these weights.</p></dd>
<dt><a name="38"><i class="arg">graphName</i> <b class="method">arcs</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-filter <i class="arg">cmdprefix</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">node node...</i>?</span></a></dt>
<dd><p>Returns a list of arcs in the graph. If no restriction is specified a
list containing all arcs is returned. Restrictions can limit the list
of returned arcs based on the nodes that are connected by the arc, on
the keyed values associated with the arc, or both. A general filter
command can be used as well. The restrictions that involve connected
nodes take a variable number of nodes as argument, specified after the
name of the restriction itself.</p>
<p>The restrictions imposed by either <b class="option">-in</b>, <b class="option">-out</b>,
<b class="option">-adj</b>, <b class="option">-inner</b>, or <b class="option">-embedded</b> are applied
first. Specifying more than one of them is illegal.</p>
<p>After that the restrictions set via <b class="option">-key</b> (and
<b class="option">-value</b>) are applied. Specifying more than one <b class="option">-key</b>
(and <b class="option">-value</b>) is illegal. Specifying <b class="option">-value</b> alone,
without <b class="option">-key</b> is illegal as well.</p>
<p>Any restriction set through <b class="option">-filter</b> is applied
last. Specifying more than one <b class="option">-filter</b> is illegal.</p>
<p>Coming back to the restrictions based on a set of nodes, the command
recognizes the following switches:</p>
<dl class="doctools_definitions">
<dt><b class="option">-in</b></dt>
<dd><p>Return a list of all arcs whose target is one of the nodes in the set
of nodes. I.e. it computes the union of all incoming arcs of the nodes
in the set.</p></dd>
<dt><b class="option">-out</b></dt>
<dd><p>Return a list of all arcs whose source is one of the nodes in the set
of nodes. I.e. it computes the union of all outgoing arcs of the nodes
in the set.</p></dd>
<dt><b class="option">-adj</b></dt>
<dd><p>Return a list of all arcs adjacent to at least one of the nodes in the
set. This is the union of the nodes returned by <b class="option">-in</b> and
<b class="option">-out</b>.</p></dd>
<dt><b class="option">-inner</b></dt>
<dd><p>Return a list of all arcs which are adjacent to two of the nodes in
the set. This is the set of arcs in the subgraph spawned by the
specified nodes.</p></dd>
<dt><b class="option">-embedding</b></dt>
<dd><p>Return a list of all arcs adjacent to exactly one of the nodes in the
set. This is the set of arcs connecting the subgraph spawned by the
specified nodes to the rest of the graph.</p></dd>
<dt><b class="option">-key</b> <i class="arg">key</i></dt>
<dd><p>Limit the list of arcs that are returned to those arcs that have an
associated key <i class="arg">key</i>.</p></dd>
<dt><b class="option">-value</b> <i class="arg">value</i></dt>
<dd><p>This restriction can only be used in combination with
<b class="option">-key</b>. It limits the list of arcs that are returned to those
arcs whose associated key <i class="arg">key</i> has the value <i class="arg">value</i>.</p></dd>
<dt><b class="option">-filter</b> <i class="arg">cmdrefix</i></dt>
<dd><p>Limit the list of arcs that are returned to those arcs that pass the
test. The command in <i class="arg">cmdprefix</i> is called with two arguments, the
name of the graph object, and the name of the arc in question. It is
executed in the context of the caller and has to return a boolean
value. Arcs for which the command returns <b class="const">false</b> are removed
from the result list before it is returned to the caller.</p></dd>
</dl></dd>
<dt><a name="39"><i class="arg">graphName</i> <b class="method">lappend</b> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with the graph. Returns the new value given to the
attribute <i class="arg">key</i>.</p></dd>
<dt><a name="40"><i class="arg">graphName</i> <b class="method">node append</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with an
<i class="arg">node</i>. Returns the new value given to the attribute <i class="arg">key</i>.</p></dd>
<dt><a name="41"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i></a></dt>
<dd></dd>
<dt><a name="42"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i> <b class="option">-nodes</b> <i class="arg">list</i></a></dt>
<dd></dd>
<dt><a name="43"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i> <b class="option">-glob</b> <i class="arg">globpattern</i></a></dt>
<dd></dd>
<dt><a name="44"><i class="arg">graphName</i> <b class="method">node attr</b> <i class="arg">key</i> <b class="option">-regexp</b> <i class="arg">repattern</i></a></dt>
<dd><p>This method retrieves the value of the attribute named <i class="arg">key</i>, for
all nodes in the graph (matching the restriction specified via one of
the possible options) and having the specified attribute.</p>
<p>The result is a dictionary mapping from node names to the value of
attribute <i class="arg">key</i> at that node.
Nodes not having the attribute <i class="arg">key</i>, or not passing a
specified restriction, are not listed in the result.</p>
<p>The possible restrictions are:</p>
<dl class="doctools_options">
<dt><b class="option">-nodes</b></dt>
<dd><p>The value is a list of nodes. Only the nodes mentioned in this list
are searched for the attribute.</p></dd>
<dt><b class="option">-glob</b></dt>
<dd><p>The value is a glob pattern. Only the nodes in the graph whose names
match this pattern are searched for the attribute.</p></dd>
<dt><b class="option">-regexp</b></dt>
<dd><p>The value is a regular expression. Only the nodes in the graph whose
names match this pattern are searched for the attribute.</p></dd>
</dl></dd>
<dt><a name="45"><i class="arg">graphName</i> <b class="method">node degree</b> <span class="opt">?-in|-out?</span> <i class="arg">node</i></a></dt>
<dd><p>Return the number of arcs adjacent to the specified <i class="arg">node</i>. If one
of the restrictions <b class="option">-in</b> or <b class="option">-out</b> is given only the
incoming resp. outgoing arcs are counted.</p></dd>
<dt><a name="46"><i class="arg">graphName</i> <b class="method">node delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i>...?</span></a></dt>
<dd><p>Remove the specified nodes from the graph. All of the nodes' arcs
will be removed as well to prevent unconnected arcs.</p></dd>
<dt><a name="47"><i class="arg">graphName</i> <b class="method">node exists</b> <i class="arg">node</i></a></dt>
<dd><p>Return true if the specified <i class="arg">node</i> exists in the graph.</p></dd>
<dt><a name="48"><i class="arg">graphName</i> <b class="method">node get</b> <i class="arg">node</i> <i class="arg">key</i></a></dt>
<dd><p>Return the value associated with the key <i class="arg">key</i> for the <i class="arg">node</i>.</p></dd>
<dt><a name="49"><i class="arg">graphName</i> <b class="method">node getall</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a dictionary (suitable for use with [<b class="cmd">array set</b>])
for the <i class="arg">node</i>.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned dictionary. The pattern
is a <b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="50"><i class="arg">graphName</i> <b class="method">node keys</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of keys for the <i class="arg">node</i>.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned list. The pattern is a
<b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="51"><i class="arg">graphName</i> <b class="method">node keyexists</b> <i class="arg">node</i> <i class="arg">key</i></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the <i class="arg">node</i>.</p></dd>
<dt><a name="52"><i class="arg">graphName</i> <b class="method">node insert</b> <span class="opt">?<i class="arg">node</i>...?</span></a></dt>
<dd><p>Insert one or more nodes into the graph. The new nodes have no arcs
connected to them. If no node is specified one node will be inserted,
and the system will generate a unique name of the form
<em>node</em><i class="arg">x</i> for it.</p></dd>
<dt><a name="53"><i class="arg">graphName</i> <b class="method">node lappend</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with an <i class="arg">node</i>. Returns the new value given to the
attribute <i class="arg">key</i>.</p></dd>
<dt><a name="54"><i class="arg">graphName</i> <b class="method">node opposite</b> <i class="arg">node</i> <i class="arg">arc</i></a></dt>
<dd><p>Return the node at the other end of the specified <i class="arg">arc</i>, which has
to be adjacent to the given <i class="arg">node</i>.</p></dd>
<dt><a name="55"><i class="arg">graphName</i> <b class="method">node rename</b> <i class="arg">node</i> <i class="arg">newname</i></a></dt>
<dd><p>Renames the node <i class="arg">node</i> to <i class="arg">newname</i>. An error is thrown if
either the node does not exist, or a node with name <i class="arg">newname</i> does
exist. The result of the command is the new name of the node.</p></dd>
<dt><a name="56"><i class="arg">graphName</i> <b class="method">node set</b> <i class="arg">node</i> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with a node. A node may have any
number of keyed values associated with it. If <i class="arg">value</i> is not
specified, this command returns the current value assigned to the key;
if <i class="arg">value</i> is specified, this command assigns that value to the
key.</p></dd>
<dt><a name="57"><i class="arg">graphName</i> <b class="method">node unset</b> <i class="arg">node</i> <i class="arg">key</i></a></dt>
<dd><p>Remove a keyed value from the node <i class="arg">node</i>. The method will do
nothing if the <i class="arg">key</i> does not exist.</p></dd>
<dt><a name="58"><i class="arg">graphName</i> <b class="method">nodes</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-filter <i class="arg">cmdprefix</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">node</i> <i class="arg">node</i>...?</span></a></dt>
<dd><p>Return a list of nodes in the graph. Restrictions can limit the list
of returned nodes based on neighboring nodes, or based on the keyed
values associated with the node. The restrictions that involve
neighboring nodes have a list of nodes as argument, specified after
the name of the restriction itself.</p>
<p>The possible restrictions are the same as for method
<b class="method">arcs</b>. The exact meanings change slightly, as they operate on
nodes instead of arcs. The command recognizes:</p>
<dl class="doctools_definitions">
<dt><b class="option">-in</b></dt>
<dd><p>Return a list of all nodes with at least one outgoing arc ending in a
node found in the specified set of nodes. Alternatively specified as
the set of source nodes for the <b class="option">-in</b> arcs of the node set. The
<i class="term">incoming neighbours</i>.</p></dd>
<dt><b class="option">-out</b></dt>
<dd><p>Return a list of all nodes with at least one incoming arc starting in
a node found in the specified set of nodes. Alternatively specified as
the set of target nodes for the <b class="option">-out</b> arcs of the node
set. The <i class="term">outgoing neighbours</i>.</p></dd>
<dt><b class="option">-adj</b></dt>
<dd><p>This is the union of the nodes returned by <b class="option">-in</b> and
<b class="option">-out</b>. The <i class="term">neighbours</i>.</p></dd>
<dt><b class="option">-inner</b></dt>
<dd><p>The set of neighbours (see <b class="option">-adj</b> above) which are also in the
set of nodes. I.e. the intersection between the set of nodes and the
neighbours per <b class="option">-adj</b>.</p></dd>
<dt><b class="option">-embedding</b></dt>
<dd><p>The set of neighbours (see <b class="option">-adj</b> above) which are not in the
set of nodes. I.e. the difference between the neighbours as per
<b class="option">-adj</b>, and the set of nodes.</p></dd>
<dt><b class="option">-key</b> <i class="arg">key</i></dt>
<dd><p>Limit the list of nodes that are returned to those nodes that have an
associated key <i class="arg">key</i>.</p></dd>
<dt><b class="option">-value</b> <i class="arg">value</i></dt>
<dd><p>This restriction can only be used in combination with
<b class="option">-key</b>. It limits the list of nodes that are returned to those
nodes whose associated key <i class="arg">key</i> has the value <i class="arg">value</i>.</p></dd>
<dt><b class="option">-filter</b> <i class="arg">cmdrefix</i></dt>
<dd><p>Limit the list of nodes that are returned to those nodes that pass the
test. The command in <i class="arg">cmdprefix</i> is called with two arguments, the
name of the graph object, and the name of the node in question. It is
executed in the context of the caller and has to return a boolean
value. Nodes for which the command returns <b class="const">false</b> are removed
from the result list before it is returned to the caller.</p></dd>
</dl></dd>
<dt><a name="59"><i class="arg">graphName</i> <b class="method">get</b> <i class="arg">key</i></a></dt>
<dd><p>Return the value associated with the key <i class="arg">key</i> for the graph.</p></dd>
<dt><a name="60"><i class="arg">graphName</i> <b class="method">getall</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a dictionary (suitable for use with [<b class="cmd">array set</b>])
for the whole graph.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned dictionary. The pattern
is a <b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="61"><i class="arg">graphName</i> <b class="method">keys</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of keys for the whole graph.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned list. The pattern is a
<b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="62"><i class="arg">graphName</i> <b class="method">keyexists</b> <i class="arg">key</i></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the whole graph.</p></dd>
<dt><a name="63"><i class="arg">graphName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">node</i>...?</span></a></dt>
<dd><p>This method serializes the sub-graph spanned up by the <i class="arg">node</i>s. In
other words it returns a tcl value completely describing that
graph. If no nodes are specified the whole graph will be serialized.
This allows, for example, the transfer of graph objects (or parts
thereof) over arbitrary channels, persistence, etc.
This method is also the basis for both the copy constructor and
the assignment operator.</p>
<p>The result of this method has to be semantically identical over all
implementations of the graph interface. This is what will enable us to
copy graph data between different implementations of the same
interface.</p>
<p>The result is a list containing a multiple of three items, plus one!
In other words, '[llength $serial] % 3 == 1'. Valid values
include 1, 4, 7, ...</p>
<p>The last element of the list is a dictionary containing the attributes
associated with the whole graph.
Regarding the other elements; each triple consists of</p>
<ol class="doctools_enumerated">
<li><p>The name of the node to be described,</p></li>
<li><p>A dictionary containing the attributes associated with the node,</p></li>
<li><p>And a list describing all the arcs starting at that node.</p></li>
</ol>
<p>The elements of the arc list are lists containing three or four
elements each, i.e.</p>
<ol class="doctools_enumerated">
<li><p>The name of the arc described by the element,</p></li>
<li><p>A reference to the destination node of the arc. This reference is an
integer number given the index of that node in the main serialization
list. As that it is greater than or equal to zero, less than the
length of the serialization, and a multiple of three.
<em>Note:</em> For internal consistency no arc name may be used twice,
whether in the same node, or at some other node. This is a global
consistency requirement for the serialization.</p></li>
<li><p>And a dictionary containing the attributes associated with the arc.</p></li>
<li><p>The weight associated with the arc. This value is optional. Its
non-presence means that the arc in question has no weight associated
with it.</p>
<p><em>Note:</em> This information is new, compared to the
serialization of <b class="package"><a href="../../../../index.html#graph">graph</a></b> 2.3 and earlier. By making it an
optional element the new format is maximally compatible with the
old. This means that any graph not using weights will generate a
serialization which is still understood by the older graph package. A
serialization will not be understood any longer by the older packages
if, and only if the graph it was generated from actually has arcs with
weights.</p></li>
</ol>
<p>For all attribute dictionaries they keys are the names of the
attributes, and the values are the values for each name.</p>
<p><em>Note:</em> The order of the nodes in the serialization has no
relevance, nor has the order of the arcs per node.</p>
<pre class="doctools_example">
# A possible serialization for the graph structure
#
# d -----> %2
# / ^ \\
# / / \\
# / b \\
# / / \\
# %1 <- a - %0 e
# ^ \\ /
# \\ c /
# \\ \\ /
# \\ v v
# f ------ %3
# is
#
# %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {}
#
# This assumes that the graph has neither attribute data nor weighted arcs.
</pre>
</dd>
<dt><a name="64"><i class="arg">graphName</i> <b class="method">set</b> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with a graph. A graph
may have any number of keyed values associated with it. If <i class="arg">value</i>
is not specified, this command returns the current value assigned to
the key; if <i class="arg">value</i> is specified, this command assigns that value
to the key.</p></dd>
<dt><a name="65"><i class="arg">graphName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></dt>
<dd><p>Swap the position of <i class="arg">node1</i> and <i class="arg">node2</i> in the graph.</p></dd>
<dt><a name="66"><i class="arg">graphName</i> <b class="method">unset</b> <i class="arg">key</i></a></dt>
<dd><p>Remove a keyed value from the graph. The method will do nothing if the
<i class="arg">key</i> does not exist.</p></dd>
<dt><a name="67"><i class="arg">graphName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?-order <i class="arg">order</i>?</span> <span class="opt">?-type <i class="arg">type</i>?</span> <span class="opt">?-dir <i class="arg">direction</i>?</span> -command <i class="arg">cmd</i></a></dt>
<dd><p>Perform a breadth-first or depth-first walk of the graph starting at
the node <i class="arg">node</i> going in either the direction of outgoing or
opposite to the incoming arcs.</p>
<p>The type of walk, breadth-first or depth-first, is determined by the
value of <i class="arg">type</i>; <b class="const">bfs</b> indicates breadth-first,
<b class="const">dfs</b> indicates depth-first. Depth-first is the default.</p>
<p>The order of the walk, pre-order, post-order or both-order is
determined by the value of <i class="arg">order</i>; <b class="const">pre</b> indicates
pre-order, <b class="const">post</b> indicates post-order, <b class="const">both</b> indicates
both-order. Pre-order is the default. Pre-order walking means that a
node is visited before any of its neighbors (as defined by the
<i class="arg">direction</i>, see below). Post-order walking means that a parent is
visited after any of its neighbors. Both-order walking means that a
node is visited before <em>and</em> after any of its neighbors. The
combination of a breadth-first walk with post- or both-order is illegal.</p>
<p>The direction of the walk is determined by the value of <i class="arg">dir</i>;
<b class="const">backward</b> indicates the direction opposite to the incoming
arcs, <b class="const">forward</b> indicates the direction of the outgoing arcs.</p>
<p>As the walk progresses, the command <i class="arg">cmd</i> will be evaluated at
each node, with the mode of the call (<b class="const">enter</b> or
<b class="const">leave</b>) and values <i class="arg">graphName</i> and the name of the current
node appended. For a pre-order walk, all nodes are <b class="const">enter</b>ed, for a
post-order all nodes are left. In a both-order walk the first visit of
a node <b class="const">enter</b>s it, the second visit <b class="const">leave</b>s it.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Changes for 2.0</a></h2>
<p>The following noteworthy changes have occurred:</p>
<ol class="doctools_enumerated">
<li><p>The API for accessing attributes and their values has been
simplified.</p>
<p>All functionality regarding the default attribute "data" has been
removed. This default attribute does not exist anymore. All accesses
to attributes have to specify the name of the attribute in
question. This backward <em>incompatible</em> change allowed us to
simplify the signature of all methods handling attributes.</p>
<p>Especially the flag <b class="option">-key</b> is not required anymore, even more,
its use is now forbidden. Please read the documentation for the arc
and node methods <b class="method">set</b>, <b class="method">get</b>, <b class="method">getall</b>,
<b class="method">unset</b>, <b class="method">append</b>, <b class="method">lappend</b>, <b class="method">keyexists</b>
and <b class="method">keys</b> for a description of the new API's.</p></li>
<li><p>The methods <b class="method">keys</b> and <b class="method">getall</b> now take an optional
pattern argument and will return only attribute data for keys matching
this pattern.</p></li>
<li><p>Arcs and nodes can now be renamed. See the documentation for the
methods <b class="method">arc rename</b> and <b class="method">node rename</b>.</p></li>
<li><p>The structure has been extended with API's for the serialization and
deserialization of graph objects, and a number of operations based on
them (graph assignment, copy construction).</p>
<p>Please read the documentation for the methods <b class="method">serialize</b>,
<b class="method">deserialize</b>, <b class="method">=</b>, and <b class="method">--></b>, and the
documentation on the construction of graph objects.</p>
<p>Beyond the copying of whole graph objects these new API's also enable
the transfer of graph objects over arbitrary channels and for easy
persistence.</p></li>
<li><p>A new method, <b class="method">attr</b>, was added to both <b class="method">arc</b> and
<b class="method">node</b> allowing the query and retrieval of attribute data
without regard to arc and node relationships.</p></li>
<li><p>Both methods <b class="method">arcs</b> and <b class="method">nodes</b> have been extended with
the ability to select arcs and nodes based on an arbitrary filtering
criterium.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: graph</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#adjacent">adjacent</a>, <a href="../../../../index.html#arc">arc</a>, <a href="../../../../index.html#cgraph">cgraph</a>, <a href="../../../../index.html#degree">degree</a>, <a href="../../../../index.html#edge">edge</a>, <a href="../../../../index.html#graph">graph</a>, <a href="../../../../index.html#loop">loop</a>, <a href="../../../../index.html#neighbour">neighbour</a>, <a href="../../../../index.html#node">node</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#subgraph">subgraph</a>, <a href="../../../../index.html#vertex">vertex</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/graph1.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
|
<div class='fossil-doc' data-title='struct::graph_v1 - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::graph_v1(n) 1.2.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::graph_v1 - Create and manipulate directed graph objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::graph <span class="opt">?1.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">graphName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><i class="arg">graphName</i> <b class="method">destroy</b></a></li>
<li><a href="#3"><i class="arg">graphName</i> <b class="method">arc append</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#4"><i class="arg">graphName</i> <b class="method">arc delete</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">arc</i> ...?</span></a></li>
<li><a href="#5"><i class="arg">graphName</i> <b class="method">arc exists</b> <i class="arg">arc</i></a></li>
<li><a href="#6"><i class="arg">graphName</i> <b class="method">arc get</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#7"><i class="arg">graphName</i> <b class="method">arc getall</b> <i class="arg">arc</i></a></li>
<li><a href="#8"><i class="arg">graphName</i> <b class="method">arc keys</b> <i class="arg">arc</i></a></li>
<li><a href="#9"><i class="arg">graphName</i> <b class="method">arc keyexists</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#10"><i class="arg">graphName</i> <b class="method">arc insert</b> <i class="arg">start</i> <i class="arg">end</i> <span class="opt">?<i class="arg">child</i>?</span></a></li>
<li><a href="#11"><i class="arg">graphName</i> <b class="method">arc lappend</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#12"><i class="arg">graphName</i> <b class="method">arc set</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#13"><i class="arg">graphName</i> <b class="method">arc source</b> <i class="arg">arc</i></a></li>
<li><a href="#14"><i class="arg">graphName</i> <b class="method">arc target</b> <i class="arg">arc</i></a></li>
<li><a href="#15"><i class="arg">graphName</i> <b class="method">arc unset</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#16"><i class="arg">graphName</i> <b class="method">arcs</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">nodelist</i>?</span></a></li>
<li><a href="#17"><i class="arg">graphName</i> <b class="method">node append</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#18"><i class="arg">graphName</i> <b class="method">node degree</b> <span class="opt">?-in|-out?</span> <i class="arg">node</i></a></li>
<li><a href="#19"><i class="arg">graphName</i> <b class="method">node delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></li>
<li><a href="#20"><i class="arg">graphName</i> <b class="method">node exists</b> <i class="arg">node</i></a></li>
<li><a href="#21"><i class="arg">graphName</i> <b class="method">node get</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#22"><i class="arg">graphName</i> <b class="method">node getall</b> <i class="arg">node</i></a></li>
<li><a href="#23"><i class="arg">graphName</i> <b class="method">node keys</b> <i class="arg">node</i></a></li>
<li><a href="#24"><i class="arg">graphName</i> <b class="method">node keyexists</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#25"><i class="arg">graphName</i> <b class="method">node insert</b> <span class="opt">?<i class="arg">child</i>?</span></a></li>
<li><a href="#26"><i class="arg">graphName</i> <b class="method">node lappend</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#27"><i class="arg">graphName</i> <b class="method">node opposite</b> <i class="arg">node</i> <i class="arg">arc</i></a></li>
<li><a href="#28"><i class="arg">graphName</i> <b class="method">node set</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#29"><i class="arg">graphName</i> <b class="method">node unset</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#30"><i class="arg">graphName</i> <b class="method">nodes</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">nodelist</i>?</span></a></li>
<li><a href="#31"><i class="arg">graphName</i> <b class="method">get</b> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#32"><i class="arg">graphName</i> <b class="method">getall</b></a></li>
<li><a href="#33"><i class="arg">graphName</i> <b class="method">keys</b></a></li>
<li><a href="#34"><i class="arg">graphName</i> <b class="method">keyexists</b> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#35"><i class="arg">graphName</i> <b class="method">set</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#36"><i class="arg">graphName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></li>
<li><a href="#37"><i class="arg">graphName</i> <b class="method">unset</b> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#38"><i class="arg">graphName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?-order <i class="arg">order</i>?</span> <span class="opt">?-type <i class="arg">type</i>?</span> <span class="opt">?-dir <i class="arg">direction</i>?</span> -command <i class="arg">cmd</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::graph</b> command creates a new graph object with an
associated global Tcl command whose name is <i class="arg">graphName</i>. This
command may be used to invoke various operations on the graph. It has
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">graphName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>A directed graph is a structure containing two collections of
elements, called <em>nodes</em> and <em>arcs</em> respectively, together
with a relation ("connectivity") that places a general structure upon
the nodes and arcs.</p>
<p>Each arc is connected to two nodes, one of which is called the
<em>source</em> and the other the <em>target</em>. This imposes a
direction upon the arc, which is said to go from the source to the
target. It is allowed that source and target of an arc are the same
node. Such an arc is called a <em>loop</em>. Whenever a node is source
or target of an arc both are said to be <em>adjacent</em>. This extends
into a relation between nodes, i.e. if two nodes are connected through
at least one arc they are said to be <em>adjacent</em> too.</p>
<p>Each node can be the source and target for any number of arcs. The
former are called the <em>outgoing arcs</em> of the node, the latter
the <em>incoming arcs</em> of the node. The number of edges in either
set is called the <em>in-</em> resp. the <em>out-degree</em> of the node.</p>
<p>In addition to maintaining the node and arc relationships, this graph
implementation allows any number of keyed values to be associated with
each node and arc.</p>
<p>The following commands are possible for graph objects:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">graphName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroy the graph, including its storage space and associated command.</p></dd>
<dt><a name="3"><i class="arg">graphName</i> <b class="method">arc append</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with an
<i class="arg">arc</i>. If no <i class="arg">key</i> is specified, the key <b class="const">data</b> is
assumed.</p></dd>
<dt><a name="4"><i class="arg">graphName</i> <b class="method">arc delete</b> <i class="arg">arc</i> <span class="opt">?<i class="arg">arc</i> ...?</span></a></dt>
<dd><p>Remove the specified arcs from the graph.</p></dd>
<dt><a name="5"><i class="arg">graphName</i> <b class="method">arc exists</b> <i class="arg">arc</i></a></dt>
<dd><p>Return true if the specified <i class="arg">arc</i> exists in the graph.</p></dd>
<dt><a name="6"><i class="arg">graphName</i> <b class="method">arc get</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return the value associated with the key <i class="arg">key</i> for the <i class="arg">arc</i>.
If no key is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="7"><i class="arg">graphName</i> <b class="method">arc getall</b> <i class="arg">arc</i></a></dt>
<dd><p>Returns a serialized list of key/value pairs (suitable for use with
[<b class="cmd">array set</b>]) for the <i class="arg">arc</i>.</p></dd>
<dt><a name="8"><i class="arg">graphName</i> <b class="method">arc keys</b> <i class="arg">arc</i></a></dt>
<dd><p>Returns a list of keys for the <i class="arg">arc</i>.</p></dd>
<dt><a name="9"><i class="arg">graphName</i> <b class="method">arc keyexists</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the <i class="arg">arc</i>. If no
<i class="arg">key</i> is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="10"><i class="arg">graphName</i> <b class="method">arc insert</b> <i class="arg">start</i> <i class="arg">end</i> <span class="opt">?<i class="arg">child</i>?</span></a></dt>
<dd><p>Insert an arc named <i class="arg">child</i> into the graph beginning at the node
<i class="arg">start</i> and ending at the node <i class="arg">end</i>. If the name of the new
arc is not specified the system will generate a unique name of the
form <em>arc</em><i class="arg">x</i>.</p></dd>
<dt><a name="11"><i class="arg">graphName</i> <b class="method">arc lappend</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with an <i class="arg">arc</i>. If no <i class="arg">key</i> is specified, the key
<b class="const">data</b> is assumed.</p></dd>
<dt><a name="12"><i class="arg">graphName</i> <b class="method">arc set</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with an arc. If no key
is specified, the key <b class="const">data</b> is assumed. Each arc that is
added to a graph has the empty string assigned to the key
<b class="const">data</b> automatically. An arc may have any number of keyed
values associated with it. If <i class="arg">value</i> is not specified, this
command returns the current value assigned to the key; if <i class="arg">value</i>
is specified, this command assigns that value to the key.</p></dd>
<dt><a name="13"><i class="arg">graphName</i> <b class="method">arc source</b> <i class="arg">arc</i></a></dt>
<dd><p>Return the node the given <i class="arg">arc</i> begins at.</p></dd>
<dt><a name="14"><i class="arg">graphName</i> <b class="method">arc target</b> <i class="arg">arc</i></a></dt>
<dd><p>Return the node the given <i class="arg">arc</i> ends at.</p></dd>
<dt><a name="15"><i class="arg">graphName</i> <b class="method">arc unset</b> <i class="arg">arc</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Remove a keyed value from the arc <i class="arg">arc</i>. If no key is specified,
the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="16"><i class="arg">graphName</i> <b class="method">arcs</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">nodelist</i>?</span></a></dt>
<dd><p>Return a list of arcs in the graph. If no restriction is specified a
list containing all arcs is returned. Restrictions can limit the list
of returned arcs based on the nodes that are connected by the arc, on
the keyed values associated with the arc, or both. The restrictions
that involve connected nodes have a list of nodes as argument,
specified after the name of the restriction itself.</p>
<dl class="doctools_definitions">
<dt><b class="option">-in</b></dt>
<dd><p>Return a list of all arcs whose target is one of the nodes in the
<i class="arg">nodelist</i>.</p></dd>
<dt><b class="option">-out</b></dt>
<dd><p>Return a list of all arcs whose source is one of the nodes in the
<i class="arg">nodelist</i>.</p></dd>
<dt><b class="option">-adj</b></dt>
<dd><p>Return a list of all arcs adjacent to at least one of the nodes in the
<i class="arg">nodelist</i>. This is the union of the nodes returned by
<b class="option">-in</b> and <b class="option">-out</b>.</p></dd>
<dt><b class="option">-inner</b></dt>
<dd><p>Return a list of all arcs adjacent to two of the nodes in the
<i class="arg">nodelist</i>. This is the set of arcs in the subgraph spawned by the
specified nodes.</p></dd>
<dt><b class="option">-embedding</b></dt>
<dd><p>Return a list of all arcs adjacent to exactly one of the nodes in the
<i class="arg">nodelist</i>. This is the set of arcs connecting the subgraph
spawned by the specified nodes to the rest of the graph.</p></dd>
<dt><b class="option">-key</b> <i class="arg">key</i></dt>
<dd><p>Limit the list of arcs that are returned to those arcs that have an
associated key <i class="arg">key</i>.</p></dd>
<dt><b class="option">-value</b> <i class="arg">value</i></dt>
<dd><p>This restriction can only be used in combination with
<b class="option">-key</b>. It limits the list of arcs that are returned to those
arcs whose associated key <i class="arg">key</i> has the value <i class="arg">value</i>.</p></dd>
</dl>
<p>The restrictions imposed by either <b class="option">-in</b>, <b class="option">-out</b>,
<b class="option">-adj</b>, <b class="option">-inner</b>, or <b class="option">-embedded</b> are applied
first. Specifying more than one of them is illegal.
At last the restrictions set via <b class="option">-key</b> (and <b class="option">-value</b>)
are applied.
Specifying more than one <b class="option">-key</b> (and <b class="option">-value</b>) is
illegal.</p></dd>
<dt><a name="17"><i class="arg">graphName</i> <b class="method">node append</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with an
<i class="arg">node</i>. If no <i class="arg">key</i> is specified, the key <b class="const">data</b> is
assumed.</p></dd>
<dt><a name="18"><i class="arg">graphName</i> <b class="method">node degree</b> <span class="opt">?-in|-out?</span> <i class="arg">node</i></a></dt>
<dd><p>Return the number of arcs adjacent to the specified <i class="arg">node</i>. If one
of the restrictions <b class="option">-in</b> or <b class="option">-out</b> is given only the
incoming resp. outgoing arcs are counted.</p></dd>
<dt><a name="19"><i class="arg">graphName</i> <b class="method">node delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></dt>
<dd><p>Remove the specified nodes from the graph. All of the nodes' arcs
will be removed as well to prevent unconnected arcs.</p></dd>
<dt><a name="20"><i class="arg">graphName</i> <b class="method">node exists</b> <i class="arg">node</i></a></dt>
<dd><p>Return true if the specified <i class="arg">node</i> exists in the graph.</p></dd>
<dt><a name="21"><i class="arg">graphName</i> <b class="method">node get</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return the value associated with the key <i class="arg">key</i> for the <i class="arg">node</i>.
If no key is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="22"><i class="arg">graphName</i> <b class="method">node getall</b> <i class="arg">node</i></a></dt>
<dd><p>Returns a serialized list of key/value pairs (suitable for use with
[<b class="cmd">array set</b>]) for the <i class="arg">node</i>.</p></dd>
<dt><a name="23"><i class="arg">graphName</i> <b class="method">node keys</b> <i class="arg">node</i></a></dt>
<dd><p>Returns a list of keys for the <i class="arg">node</i>.</p></dd>
<dt><a name="24"><i class="arg">graphName</i> <b class="method">node keyexists</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the <i class="arg">node</i>. If
no <i class="arg">key</i> is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="25"><i class="arg">graphName</i> <b class="method">node insert</b> <span class="opt">?<i class="arg">child</i>?</span></a></dt>
<dd><p>Insert a node named <i class="arg">child</i> into the graph. The nodes has no arcs
connected to it. If the name of the new child is not specified the
system will generate a unique name of the form <em>node</em><i class="arg">x</i>.</p></dd>
<dt><a name="26"><i class="arg">graphName</i> <b class="method">node lappend</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with an <i class="arg">node</i>. If no <i class="arg">key</i> is specified, the key
<b class="const">data</b> is assumed.</p></dd>
<dt><a name="27"><i class="arg">graphName</i> <b class="method">node opposite</b> <i class="arg">node</i> <i class="arg">arc</i></a></dt>
<dd><p>Return the node at the other end of the specified <i class="arg">arc</i>, which has
to be adjacent to the given <i class="arg">node</i>.</p></dd>
<dt><a name="28"><i class="arg">graphName</i> <b class="method">node set</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with a node. If no key
is specified, the key <b class="const">data</b> is assumed. Each node that is
added to a graph has the empty string assigned to the key
<b class="const">data</b> automatically. A node may have any number of keyed
values associated with it. If <i class="arg">value</i> is not specified, this
command returns the current value assigned to the key; if <i class="arg">value</i>
is specified, this command assigns that value to the key.</p></dd>
<dt><a name="29"><i class="arg">graphName</i> <b class="method">node unset</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Remove a keyed value from the node <i class="arg">node</i>. If no key is
specified, the key <b class="method">data</b> is assumed.</p></dd>
<dt><a name="30"><i class="arg">graphName</i> <b class="method">nodes</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?-value <i class="arg">value</i>?</span> <span class="opt">?-in|-out|-adj|-inner|-embedding <i class="arg">nodelist</i>?</span></a></dt>
<dd><p>Return a list of nodes in the graph. Restrictions can limit the list
of returned nodes based on neighboring nodes, or based on the keyed
values associated with the node. The restrictions that involve
neighboring nodes have a list of nodes as argument, specified after
the name of the restriction itself.</p>
<p>The possible restrictions are the same as for method
<b class="method">arcs</b>. The set of nodes to return is computed as the union of
all source and target nodes for all the arcs satisfying the
restriction as defined for <b class="method">arcs</b>.</p></dd>
<dt><a name="31"><i class="arg">graphName</i> <b class="method">get</b> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return the value associated with the key <i class="arg">key</i> for the graph. If
no key is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="32"><i class="arg">graphName</i> <b class="method">getall</b></a></dt>
<dd><p>Returns a serialized list of key/value pairs (suitable for use with
[<b class="cmd">array set</b>]) for the whole graph.</p></dd>
<dt><a name="33"><i class="arg">graphName</i> <b class="method">keys</b></a></dt>
<dd><p>Returns a list of keys for the whole graph.</p></dd>
<dt><a name="34"><i class="arg">graphName</i> <b class="method">keyexists</b> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the whole graph. If no
<i class="arg">key</i> is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="35"><i class="arg">graphName</i> <b class="method">set</b> <span class="opt">?-key <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with a graph. If no key
is specified, the key <b class="const">data</b> is assumed. Each graph has the
empty string assigned to the key <b class="const">data</b> automatically. A graph
may have any number of keyed values associated with it. If <i class="arg">value</i>
is not specified, this command returns the current value assigned to
the key; if <i class="arg">value</i> is specified, this command assigns that value
to the key.</p></dd>
<dt><a name="36"><i class="arg">graphName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></dt>
<dd><p>Swap the position of <i class="arg">node1</i> and <i class="arg">node2</i> in the graph.</p></dd>
<dt><a name="37"><i class="arg">graphName</i> <b class="method">unset</b> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Remove a keyed value from the graph. If no key is specified, the key
<b class="const">data</b> is assumed.</p></dd>
<dt><a name="38"><i class="arg">graphName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?-order <i class="arg">order</i>?</span> <span class="opt">?-type <i class="arg">type</i>?</span> <span class="opt">?-dir <i class="arg">direction</i>?</span> -command <i class="arg">cmd</i></a></dt>
<dd><p>Perform a breadth-first or depth-first walk of the graph starting at
the node <i class="arg">node</i> going in either the direction of outgoing or
opposite to the incoming arcs.</p>
<p>The type of walk, breadth-first or depth-first, is determined by the
value of <i class="arg">type</i>; <b class="const">bfs</b> indicates breadth-first,
<b class="const">dfs</b> indicates depth-first. Depth-first is the default.</p>
<p>The order of the walk, pre-order, post-order or both-order is
determined by the value of <i class="arg">order</i>; <b class="const">pre</b> indicates
pre-order, <b class="const">post</b> indicates post-order, <b class="const">both</b> indicates
both-order. Pre-order is the default. Pre-order walking means that a
node is visited before any of its neighbors (as defined by the
<i class="arg">direction</i>, see below). Post-order walking means that a parent is
visited after any of its neighbors. Both-order walking means that a
node is visited before <em>and</em> after any of its neighbors. The
combination of a bread-first walk with post- or both-order is illegal.</p>
<p>The direction of the walk is determined by the value of <i class="arg">dir</i>;
<b class="const">backward</b> indicates the direction opposite to the incoming
arcs, <b class="const">forward</b> indicates the direction of the outgoing arcs.</p>
<p>As the walk progresses, the command <i class="arg">cmd</i> will be evaluated at
each node, with the mode of the call (<b class="const">enter</b> or
<b class="const">leave</b>) and values <i class="arg">graphName</i> and the name of the current
node appended. For a pre-order walk, all nodes are <b class="const">enter</b>ed, for a
post-order all nodes are left. In a both-order walk the first visit of
a node <b class="const">enter</b>s it, the second visit <b class="const">leave</b>s it.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: graph</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cgraph">cgraph</a>, <a href="../../../../index.html#graph">graph</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/graphops.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
|
<div class='fossil-doc' data-title='struct::graph::op - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::graph::op(n) 0.11.3 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::graph::op - Operation for (un)directed graph objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Operations</a></li>
<li class="doctools_section"><a href="#section3">Background theory and terms</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Shortest Path Problem</a></li>
<li class="doctools_subsection"><a href="#subsection2">Travelling Salesman Problem</a></li>
<li class="doctools_subsection"><a href="#subsection3">Matching Problem</a></li>
<li class="doctools_subsection"><a href="#subsection4">Cut Problems</a></li>
<li class="doctools_subsection"><a href="#subsection5">K-Center Problem</a></li>
<li class="doctools_subsection"><a href="#subsection6">Flow Problems</a></li>
<li class="doctools_subsection"><a href="#subsection7">Approximation algorithm</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">References</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">struct::graph::op <span class="opt">?0.11.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">struct::graph::op::toAdjacencyMatrix</b> <i class="arg">g</i></a></li>
<li><a href="#2"><b class="cmd">struct::graph::op::toAdjacencyList</b> <i class="arg">G</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">struct::graph::op::kruskal</b> <i class="arg">g</i></a></li>
<li><a href="#4"><b class="cmd">struct::graph::op::prim</b> <i class="arg">g</i></a></li>
<li><a href="#5"><b class="cmd">struct::graph::op::isBipartite?</b> <i class="arg">g</i> <span class="opt">?<i class="arg">bipartvar</i>?</span></a></li>
<li><a href="#6"><b class="cmd">struct::graph::op::tarjan</b> <i class="arg">g</i></a></li>
<li><a href="#7"><b class="cmd">struct::graph::op::connectedComponents</b> <i class="arg">g</i></a></li>
<li><a href="#8"><b class="cmd">struct::graph::op::connectedComponentOf</b> <i class="arg">g</i> <i class="arg">n</i></a></li>
<li><a href="#9"><b class="cmd">struct::graph::op::isConnected?</b> <i class="arg">g</i></a></li>
<li><a href="#10"><b class="cmd">struct::graph::op::isCutVertex?</b> <i class="arg">g</i> <i class="arg">n</i></a></li>
<li><a href="#11"><b class="cmd">struct::graph::op::isBridge?</b> <i class="arg">g</i> <i class="arg">a</i></a></li>
<li><a href="#12"><b class="cmd">struct::graph::op::isEulerian?</b> <i class="arg">g</i> <span class="opt">?<i class="arg">tourvar</i>?</span></a></li>
<li><a href="#13"><b class="cmd">struct::graph::op::isSemiEulerian?</b> <i class="arg">g</i> <span class="opt">?<i class="arg">pathvar</i>?</span></a></li>
<li><a href="#14"><b class="cmd">struct::graph::op::dijkstra</b> <i class="arg">g</i> <i class="arg">start</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#15"><b class="cmd">struct::graph::op::distance</b> <i class="arg">g</i> <i class="arg">origin</i> <i class="arg">destination</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#16"><b class="cmd">struct::graph::op::eccentricity</b> <i class="arg">g</i> <i class="arg">n</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#17"><b class="cmd">struct::graph::op::radius</b> <i class="arg">g</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#18"><b class="cmd">struct::graph::op::diameter</b> <i class="arg">g</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#19"><b class="cmd">struct::graph::op::BellmanFord</b> <i class="arg">G</i> <i class="arg">startnode</i></a></li>
<li><a href="#20"><b class="cmd">struct::graph::op::Johnsons</b> <i class="arg">G</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#21"><b class="cmd">struct::graph::op::FloydWarshall</b> <i class="arg">G</i></a></li>
<li><a href="#22"><b class="cmd">struct::graph::op::MetricTravellingSalesman</b> <i class="arg">G</i></a></li>
<li><a href="#23"><b class="cmd">struct::graph::op::Christofides</b> <i class="arg">G</i></a></li>
<li><a href="#24"><b class="cmd">struct::graph::op::GreedyMaxMatching</b> <i class="arg">G</i></a></li>
<li><a href="#25"><b class="cmd">struct::graph::op::MaxCut</b> <i class="arg">G</i> <i class="arg">U</i> <i class="arg">V</i></a></li>
<li><a href="#26"><b class="cmd">struct::graph::op::UnweightedKCenter</b> <i class="arg">G</i> <i class="arg">k</i></a></li>
<li><a href="#27"><b class="cmd">struct::graph::op::WeightedKCenter</b> <i class="arg">G</i> <i class="arg">nodeWeights</i> <i class="arg">W</i></a></li>
<li><a href="#28"><b class="cmd">struct::graph::op::GreedyMaxIndependentSet</b> <i class="arg">G</i></a></li>
<li><a href="#29"><b class="cmd">struct::graph::op::GreedyWeightedMaxIndependentSet</b> <i class="arg">G</i> <i class="arg">nodeWeights</i></a></li>
<li><a href="#30"><b class="cmd">struct::graph::op::VerticesCover</b> <i class="arg">G</i></a></li>
<li><a href="#31"><b class="cmd">struct::graph::op::EdmondsKarp</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i></a></li>
<li><a href="#32"><b class="cmd">struct::graph::op::BusackerGowen</b> <i class="arg">G</i> <i class="arg">desiredFlow</i> <i class="arg">s</i> <i class="arg">t</i></a></li>
<li><a href="#33"><b class="cmd">struct::graph::op::ShortestsPathsByBFS</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">outputFormat</i></a></li>
<li><a href="#34"><b class="cmd">struct::graph::op::BFS</b> <i class="arg">G</i> <i class="arg">s</i> <span class="opt">?<i class="arg">outputFormat</i>...?</span></a></li>
<li><a href="#35"><b class="cmd">struct::graph::op::MinimumDiameterSpanningTree</b> <i class="arg">G</i></a></li>
<li><a href="#36"><b class="cmd">struct::graph::op::MinimumDegreeSpanningTree</b> <i class="arg">G</i></a></li>
<li><a href="#37"><b class="cmd">struct::graph::op::MaximumFlowByDinic</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i> <i class="arg">blockingFlowAlg</i></a></li>
<li><a href="#38"><b class="cmd">struct::graph::op::BlockingFlowByDinic</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i></a></li>
<li><a href="#39"><b class="cmd">struct::graph::op::BlockingFlowByMKM</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i></a></li>
<li><a href="#40"><b class="cmd">struct::graph::op::createResidualGraph</b> <i class="arg">G</i> <i class="arg">f</i></a></li>
<li><a href="#41"><b class="cmd">struct::graph::op::createAugmentingNetwork</b> <i class="arg">G</i> <i class="arg">f</i> <i class="arg">path</i></a></li>
<li><a href="#42"><b class="cmd">struct::graph::op::createLevelGraph</b> <i class="arg">Gf</i> <i class="arg">s</i></a></li>
<li><a href="#43"><b class="cmd">struct::graph::op::TSPLocalSearching</b> <i class="arg">G</i> <i class="arg">C</i></a></li>
<li><a href="#44"><b class="cmd">struct::graph::op::TSPLocalSearching3Approx</b> <i class="arg">G</i> <i class="arg">C</i></a></li>
<li><a href="#45"><b class="cmd">struct::graph::op::createSquaredGraph</b> <i class="arg">G</i></a></li>
<li><a href="#46"><b class="cmd">struct::graph::op::createCompleteGraph</b> <i class="arg">G</i> <i class="arg">originalEdges</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package described by this document, <b class="package">struct::graph::op</b>,
is a companion to the package <b class="package"><a href="graph.html">struct::graph</a></b>. It provides a
series of common operations and algorithms applicable to (un)directed
graphs.</p>
<p>Despite being a companion the package is not directly dependent on
<b class="package"><a href="graph.html">struct::graph</a></b>, only on the API defined by that
package. I.e. the operations of this package can be applied to any and
all graph objects which provide the same API as the objects created
through <b class="package"><a href="graph.html">struct::graph</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Operations</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">struct::graph::op::toAdjacencyMatrix</b> <i class="arg">g</i></a></dt>
<dd><p>This command takes the graph <i class="arg">g</i> and returns a nested list
containing the adjacency matrix of <i class="arg">g</i>.</p>
<p>The elements of the outer list are the rows of the matrix, the inner
elements are the column values in each row. The matrix has "<b class="variable">n</b>+1"
rows and columns, with the first row and column (index 0) containing
the name of the node the row/column is for. All other elements are
boolean values, <b class="const">True</b> if there is an arc between the 2 nodes
of the respective row and column, and <b class="const">False</b> otherwise.</p>
<p>Note that the matrix is symmetric. It does not represent the
directionality of arcs, only their presence between nodes. It is also
unable to represent parallel arcs in <i class="arg">g</i>.</p></dd>
<dt><a name="2"><b class="cmd">struct::graph::op::toAdjacencyList</b> <i class="arg">G</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>Procedure creates for input graph <i class="arg">G</i>, it's representation as <i class="term"><a href="../../../../index.html#adjacency_list">Adjacency List</a></i>.
It handles both directed and undirected graphs (default is undirected).
It returns dictionary that for each node (key) returns list of nodes adjacent
to it. When considering weighted version, for each adjacent node there is also
weight of the edge included.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph object <i class="arg">G</i> (input)</dt>
<dd><p>A graph to convert into an <i class="term"><a href="../../../../index.html#adjacency_list">Adjacency List</a></i>.</p></dd>
</dl></dd>
<dt>Options:</dt>
<dd><dl class="doctools_options">
<dt><b class="option">-directed</b></dt>
<dd><p>By default <i class="arg">G</i> is operated as if it were an <i class="term">Undirected graph</i>.
Using this option tells the command to handle <i class="arg">G</i> as the directed graph it is.</p></dd>
<dt><b class="option">-weights</b></dt>
<dd><p>By default any weight information the graph <i class="arg">G</i> may have is ignored.
Using this option tells the command to put weight information into the result.
In that case it is expected that all arcs have a proper weight, and an error
is thrown if that is not the case.</p></dd>
</dl></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">struct::graph::op::kruskal</b> <i class="arg">g</i></a></dt>
<dd><p>This command takes the graph <i class="arg">g</i> and returns a list containing the
names of the arcs in <i class="arg">g</i> which span up a minimum weight spanning tree
(MST), or, in the case of an un-connected graph, a minimum weight spanning
forest (except for the 1-vertex components). Kruskal's algorithm is used
to compute the tree or forest.
This algorithm has a time complexity of <i class="term">O(E*log E)</i> or <i class="term">O(E* log V)</i>,
where <i class="term">V</i> is the number of vertices and <i class="term"><a href="../../../../index.html#e">E</a></i> is the number of edges
in graph <i class="arg">g</i>.</p>
<p>The command will throw an error if one or more arcs in <i class="arg">g</i> have no
weight associated with them.</p>
<p>A note regarding the result, the command refrains from explicitly
listing the nodes of the MST as this information is implicitly
provided in the arcs already.</p></dd>
<dt><a name="4"><b class="cmd">struct::graph::op::prim</b> <i class="arg">g</i></a></dt>
<dd><p>This command takes the graph <i class="arg">g</i> and returns a list containing the
names of the arcs in <i class="arg">g</i> which span up a minimum weight spanning tree
(MST), or, in the case of an un-connected graph, a minimum weight spanning
forest (except for the 1-vertex components). Prim's algorithm is used to
compute the tree or forest.
This algorithm has a time complexity between <i class="term">O(E+V*log V)</i> and <i class="term">O(V*V)</i>,
depending on the implementation (Fibonacci heap + Adjacency list versus
Adjacency Matrix). As usual <i class="term">V</i> is the number of vertices and
<i class="term"><a href="../../../../index.html#e">E</a></i> the number of edges in graph <i class="arg">g</i>.</p>
<p>The command will throw an error if one or more arcs in <i class="arg">g</i> have no
weight associated with them.</p>
<p>A note regarding the result, the command refrains from explicitly
listing the nodes of the MST as this information is implicitly
provided in the arcs already.</p></dd>
<dt><a name="5"><b class="cmd">struct::graph::op::isBipartite?</b> <i class="arg">g</i> <span class="opt">?<i class="arg">bipartvar</i>?</span></a></dt>
<dd><p>This command takes the graph <i class="arg">g</i> and returns a boolean value
indicating whether it is bipartite (<b class="const">true</b>) or not
(<b class="const">false</b>). If the variable <i class="arg">bipartvar</i> is specified the two
partitions of the graph are there as a list, if, and only if the graph
is bipartit. If it is not the variable, if specified, is not touched.</p></dd>
<dt><a name="6"><b class="cmd">struct::graph::op::tarjan</b> <i class="arg">g</i></a></dt>
<dd><p>This command computes the set of <em>strongly connected</em>
components (SCCs) of the graph <i class="arg">g</i>. The result of the command is a
list of sets, each of which contains the nodes for one of the SCCs of
<i class="arg">g</i>. The union of all SCCs covers the whole graph, and no two SCCs
intersect with each other.</p>
<p>The graph <i class="arg">g</i> is <i class="term">acyclic</i> if all SCCs in the result contain
only a single node. The graph <i class="arg">g</i> is <i class="term">strongly connected</i>
if the result contains only a single SCC containing all nodes of
<i class="arg">g</i>.</p></dd>
<dt><a name="7"><b class="cmd">struct::graph::op::connectedComponents</b> <i class="arg">g</i></a></dt>
<dd><p>This command computes the set of <em>connected</em> components (CCs) of
the graph <i class="arg">g</i>. The result of the command is a list of sets, each
of which contains the nodes for one of the CCs of <i class="arg">g</i>. The union
of all CCs covers the whole graph, and no two CCs intersect with each
other.</p>
<p>The graph <i class="arg">g</i> is <i class="term">connected</i> if the result contains only a
single SCC containing all nodes of <i class="arg">g</i>.</p></dd>
<dt><a name="8"><b class="cmd">struct::graph::op::connectedComponentOf</b> <i class="arg">g</i> <i class="arg">n</i></a></dt>
<dd><p>This command computes the <em>connected</em> component (CC) of the graph
<i class="arg">g</i> containing the node <i class="arg">n</i>. The result of the command is a
sets which contains the nodes for the CC of <i class="arg">n</i> in <i class="arg">g</i>.</p>
<p>The command will throw an error if <i class="arg">n</i> is not a node of the graph
<i class="arg">g</i>.</p></dd>
<dt><a name="9"><b class="cmd">struct::graph::op::isConnected?</b> <i class="arg">g</i></a></dt>
<dd><p>This is a convenience command determining whether the graph <i class="arg">g</i> is
<i class="term">connected</i> or not. The result is a boolean value, <b class="const">true</b>
if the graph is connected, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="10"><b class="cmd">struct::graph::op::isCutVertex?</b> <i class="arg">g</i> <i class="arg">n</i></a></dt>
<dd><p>This command determines whether the node <i class="arg">n</i> in the graph <i class="arg">g</i>
is a <i class="term"><a href="../../../../index.html#cut_vertex">cut vertex</a></i> (aka <i class="term"><a href="../../../../index.html#articulation_point">articulation point</a></i>). The result
is a boolean value, <b class="const">true</b> if the node is a cut vertex, and
<b class="const">false</b> otherwise.</p>
<p>The command will throw an error if <i class="arg">n</i> is not a node of the graph
<i class="arg">g</i>.</p></dd>
<dt><a name="11"><b class="cmd">struct::graph::op::isBridge?</b> <i class="arg">g</i> <i class="arg">a</i></a></dt>
<dd><p>This command determines whether the arc <i class="arg">a</i> in the graph <i class="arg">g</i>
is a <i class="term"><a href="../../../../index.html#bridge">bridge</a></i> (aka <i class="term"><a href="../../../../index.html#cut_edge">cut edge</a></i>, or <i class="term"><a href="../../../../index.html#isthmus">isthmus</a></i>). The
result is a boolean value, <b class="const">true</b> if the arc is a bridge, and
<b class="const">false</b> otherwise.</p>
<p>The command will throw an error if <i class="arg">a</i> is not an arc of the graph
<i class="arg">g</i>.</p></dd>
<dt><a name="12"><b class="cmd">struct::graph::op::isEulerian?</b> <i class="arg">g</i> <span class="opt">?<i class="arg">tourvar</i>?</span></a></dt>
<dd><p>This command determines whether the graph <i class="arg">g</i> is <i class="term">eulerian</i>
or not. The result is a boolean value, <b class="const">true</b> if the graph is
eulerian, and <b class="const">false</b> otherwise.</p>
<p>If the graph is eulerian and <i class="arg">tourvar</i> is specified then an euler
tour is computed as well and stored in the named variable. The tour is
represented by the list of arcs traversed, in the order of traversal.</p></dd>
<dt><a name="13"><b class="cmd">struct::graph::op::isSemiEulerian?</b> <i class="arg">g</i> <span class="opt">?<i class="arg">pathvar</i>?</span></a></dt>
<dd><p>This command determines whether the graph <i class="arg">g</i> is
<i class="term">semi-eulerian</i> or not. The result is a boolean value, <b class="const">true</b>
if the graph is semi-eulerian, and <b class="const">false</b> otherwise.</p>
<p>If the graph is semi-eulerian and <i class="arg">pathvar</i> is specified then an
euler path is computed as well and stored in the named variable. The
path is represented by the list of arcs traversed, in the order of
traversal.</p></dd>
<dt><a name="14"><b class="cmd">struct::graph::op::dijkstra</b> <i class="arg">g</i> <i class="arg">start</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command determines distances in the weighted <i class="arg">g</i> from the
node <i class="arg">start</i> to all other nodes in the graph. The options specify
how to traverse graphs, and the format of the result.</p>
<p>Two options are recognized</p>
<dl class="doctools_options">
<dt><b class="option">-arcmode</b> mode</dt>
<dd><p>The accepted mode values are <b class="const">directed</b> and <b class="const">undirected</b>.
For directed traversal all arcs are traversed from source to
target. For undirected traversal all arcs are traversed in the
opposite direction as well. Undirected traversal is the default.</p></dd>
<dt><b class="option">-outputformat</b> format</dt>
<dd><p>The accepted format values are <b class="const">distances</b> and <b class="const">tree</b>. In
both cases the result is a dictionary keyed by the names of all nodes
in the graph. For <b class="const">distances</b> the value is the distance of the
node to <i class="arg">start</i>, whereas for <b class="const">tree</b> the value is the path
from the node to <i class="arg">start</i>, excluding the node itself, but including
<i class="arg">start</i>. Tree format is the default.</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">struct::graph::op::distance</b> <i class="arg">g</i> <i class="arg">origin</i> <i class="arg">destination</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command determines the (un)directed distance between the two
nodes <i class="arg">origin</i> and <i class="arg">destination</i> in the graph <i class="arg">g</i>. It
accepts the option <b class="option">-arcmode</b> of <b class="cmd">struct::graph::op::dijkstra</b>.</p></dd>
<dt><a name="16"><b class="cmd">struct::graph::op::eccentricity</b> <i class="arg">g</i> <i class="arg">n</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command determines the (un)directed <i class="term"><a href="../../../../index.html#eccentricity">eccentricity</a></i> of the
node <i class="arg">n</i> in the graph <i class="arg">g</i>. It accepts the option
<b class="option">-arcmode</b> of <b class="cmd">struct::graph::op::dijkstra</b>.</p>
<p>The (un)directed <i class="term"><a href="../../../../index.html#eccentricity">eccentricity</a></i> of a node is the maximal
(un)directed distance between the node and any other node in the
graph.</p></dd>
<dt><a name="17"><b class="cmd">struct::graph::op::radius</b> <i class="arg">g</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command determines the (un)directed <i class="term"><a href="../../../../index.html#radius">radius</a></i> of the graph
<i class="arg">g</i>. It accepts the option <b class="option">-arcmode</b> of <b class="cmd">struct::graph::op::dijkstra</b>.</p>
<p>The (un)directed <i class="term"><a href="../../../../index.html#radius">radius</a></i> of a graph is the minimal (un)directed
<i class="term"><a href="../../../../index.html#eccentricity">eccentricity</a></i> of all nodes in the graph.</p></dd>
<dt><a name="18"><b class="cmd">struct::graph::op::diameter</b> <i class="arg">g</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command determines the (un)directed <i class="term"><a href="../../../../index.html#diameter">diameter</a></i> of the graph
<i class="arg">g</i>. It accepts the option <b class="option">-arcmode</b> of <b class="cmd">struct::graph::op::dijkstra</b>.</p>
<p>The (un)directed <i class="term"><a href="../../../../index.html#diameter">diameter</a></i> of a graph is the maximal (un)directed
<i class="term"><a href="../../../../index.html#eccentricity">eccentricity</a></i> of all nodes in the graph.</p></dd>
<dt><a name="19"><b class="cmd">struct::graph::op::BellmanFord</b> <i class="arg">G</i> <i class="arg">startnode</i></a></dt>
<dd><p>Searching for <span class="sectref"><a href="#subsection1">shortests paths</a></span> between chosen node and all other nodes in graph <i class="arg">G</i>. Based
on relaxation method. In comparison to <b class="cmd">struct::graph::op::dijkstra</b> it doesn't need assumption that all weights
on edges in input graph <i class="arg">G</i> have to be positive.</p>
<p>That generality sets the complexity of algorithm to - <i class="term">O(V*E)</i>, where <i class="term">V</i> is the number of vertices
and <i class="term"><a href="../../../../index.html#e">E</a></i> is number of edges in graph <i class="arg">G</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph object <i class="arg">G</i> (input)</dt>
<dd><p>Directed, connected and edge weighted graph <i class="arg">G</i>, without any negative cycles ( presence of cycles with the negative sum
of weight means that there is no shortest path, since the total weight becomes lower each time the cycle is
traversed ). Negative weights on edges are allowed.</p></dd>
<dt>Node <i class="arg">startnode</i> (input)</dt>
<dd><p>The node for which we find all shortest paths to each other node in graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Dictionary containing for each node (key) distances to each other node in graph <i class="arg">G</i>.</p></dd>
</dl>
<p><em>Note:</em> If algorithm finds a negative cycle, it will return error message.</p></dd>
<dt><a name="20"><b class="cmd">struct::graph::op::Johnsons</b> <i class="arg">G</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>Searching for <span class="sectref"><a href="#subsection1">shortest paths</a></span> between all pairs of vertices in graph. For sparse graphs
asymptotically quicker than <b class="cmd">struct::graph::op::FloydWarshall</b> algorithm. Johnson's algorithm
uses <b class="cmd">struct::graph::op::BellmanFord</b> and <b class="cmd">struct::graph::op::dijkstra</b> as subprocedures.</p>
<p>Time complexity: <i class="term">O(n**2*log(n) +n*m)</i>, where <i class="term">n</i> is the number of nodes and <i class="term">m</i> is
the number of edges in graph <i class="arg">G</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph object <i class="arg">G</i> (input)</dt>
<dd><p>Directed graph <i class="arg">G</i>, weighted on edges and not containing
any cycles with negative sum of weights ( the presence of such cycles means
there is no shortest path, since the total weight becomes lower each time the
cycle is traversed ). Negative weights on edges are allowed.</p></dd>
</dl></dd>
<dt>Options:</dt>
<dd><dl class="doctools_options">
<dt><b class="option">-filter</b></dt>
<dd><p>Returns only existing distances, cuts all <i class="term">Inf</i> values for
non-existing connections between pairs of nodes.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Dictionary containing distances between all pairs of vertices.</p></dd>
</dl></dd>
<dt><a name="21"><b class="cmd">struct::graph::op::FloydWarshall</b> <i class="arg">G</i></a></dt>
<dd><p>Searching for <span class="sectref"><a href="#subsection1">shortest paths</a></span> between all pairs of edges in weighted graphs.</p>
<p>Time complexity: <i class="term">O(V^3)</i> - where <i class="term">V</i> is number of vertices.</p>
<p>Memory complexity: <i class="term">O(V^2)</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph object <i class="arg">G</i> (input)</dt>
<dd><p>Directed and weighted graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Dictionary containing shortest distances to each node from each node.</p></dd>
</dl>
<p><em>Note:</em> Algorithm finds solutions dynamically. It compares all possible paths through the graph
between each pair of vertices. Graph shouldn't possess any cycle with negative
sum of weights (the presence of such cycles means there is no shortest path,
since the total weight becomes lower each time the cycle is traversed).</p>
<p>On the other hand algorithm can be used to find those cycles - if any shortest distance
found by algorithm for any nodes <i class="term">v</i> and <i class="term">u</i> (when <i class="term">v</i> is the same node as <i class="term">u</i>) is negative,
that node surely belong to at least one negative cycle.</p></dd>
<dt><a name="22"><b class="cmd">struct::graph::op::MetricTravellingSalesman</b> <i class="arg">G</i></a></dt>
<dd><p>Algorithm for solving a metric variation of <span class="sectref"><a href="#subsection2">Travelling salesman problem</a></span>.
<i class="term">TSP problem</i> is <i class="term">NP-Complete</i>, so there is no efficient algorithm to solve it. Greedy methods
are getting extremely slow, with the increase in the set of nodes.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected, weighted graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Approximated solution of minimum <i class="term">Hamilton Cycle</i> - closed path visiting all nodes,
each exactly one time.</p></dd>
</dl>
<p><em>Note:</em> <span class="sectref"><a href="#subsection7">It's 2-approximation algorithm.</a></span></p></dd>
<dt><a name="23"><b class="cmd">struct::graph::op::Christofides</b> <i class="arg">G</i></a></dt>
<dd><p>Another algorithm for solving <span class="sectref"><a href="#subsection2">metric <i class="term">TSP problem</i></a></span>.
Christofides implementation uses <i class="term">Max Matching</i> for reaching better approximation factor.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected, weighted graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Approximated solution of minimum <i class="term">Hamilton Cycle</i> - closed path visiting all nodes,
each exactly one time.</p></dd>
</dl>
<p><em>Note:</em> <span class="sectref"><a href="#subsection7">It's is a 3/2 approximation algorithm. </a></span></p></dd>
<dt><a name="24"><b class="cmd">struct::graph::op::GreedyMaxMatching</b> <i class="arg">G</i></a></dt>
<dd><p><i class="term">Greedy Max Matching</i> procedure, which finds <span class="sectref"><a href="#subsection3">maximal matching</a></span> (not maximum)
for given graph <i class="arg">G</i>. It adds edges to solution, beginning from edges with the
lowest cost.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Set of edges - the max matching for graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt><a name="25"><b class="cmd">struct::graph::op::MaxCut</b> <i class="arg">G</i> <i class="arg">U</i> <i class="arg">V</i></a></dt>
<dd><p>Algorithm solving a <span class="sectref"><a href="#subsection4">Maximum Cut Problem</a></span>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>The graph to cut.</p></dd>
<dt>List <i class="arg">U</i> (output)</dt>
<dd><p>Variable storing first set of nodes (cut) given by solution.</p></dd>
<dt>List <i class="arg">V</i> (output)</dt>
<dd><p>Variable storing second set of nodes (cut) given by solution.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns number of edges between found two sets of nodes.</p></dd>
</dl>
<p><em>Note:</em> <i class="term">MaxCut</i> is a <span class="sectref"><a href="#subsection7">2-approximation algorithm.</a></span></p></dd>
<dt><a name="26"><b class="cmd">struct::graph::op::UnweightedKCenter</b> <i class="arg">G</i> <i class="arg">k</i></a></dt>
<dd><p>Approximation algorithm that solves a <span class="sectref"><a href="#subsection5">k-center problem</a></span>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected complete graph <i class="arg">G</i>, which satisfies triangle inequality.</p></dd>
<dt>Integer <i class="arg">k</i> (input)</dt>
<dd><p>Positive integer that sets the number of nodes that will be included in <i class="term">k-center</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Set of nodes - <i class="arg">k</i> center for graph <i class="arg">G</i>.</p></dd>
</dl>
<p><em>Note:</em> <i class="term">UnweightedKCenter</i> is a <span class="sectref"><a href="#subsection7">2-approximation algorithm.</a></span></p></dd>
<dt><a name="27"><b class="cmd">struct::graph::op::WeightedKCenter</b> <i class="arg">G</i> <i class="arg">nodeWeights</i> <i class="arg">W</i></a></dt>
<dd><p>Approximation algorithm that solves a weighted version of <span class="sectref"><a href="#subsection5">k-center problem</a></span>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected complete graph <i class="arg">G</i>, which satisfies triangle inequality.</p></dd>
<dt>Integer <i class="arg">W</i> (input)</dt>
<dd><p>Positive integer that sets the maximum possible weight of <i class="term">k-center</i> found by algorithm.</p></dd>
<dt>List <i class="arg">nodeWeights</i> (input)</dt>
<dd><p>List of nodes and its weights in graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Set of nodes, which is solution found by algorithm.</p></dd>
</dl>
<p><em>Note:</em><i class="term">WeightedKCenter</i> is a <span class="sectref"><a href="#subsection7">3-approximation algorithm.</a></span></p></dd>
<dt><a name="28"><b class="cmd">struct::graph::op::GreedyMaxIndependentSet</b> <i class="arg">G</i></a></dt>
<dd><p>A <i class="term">maximal independent set</i> is an <i class="term"><a href="../../../../index.html#independent_set">independent set</a></i> such that adding any other node
to the set forces the set to contain an edge.</p>
<p>Algorithm for input graph <i class="arg">G</i> returns set of nodes (list), which are contained in Max Independent
Set found by algorithm.</p></dd>
<dt><a name="29"><b class="cmd">struct::graph::op::GreedyWeightedMaxIndependentSet</b> <i class="arg">G</i> <i class="arg">nodeWeights</i></a></dt>
<dd><p>Weighted variation of <i class="term">Maximal Independent Set</i>. It takes as an input argument
not only graph <i class="arg">G</i> but also set of weights for all vertices in graph <i class="arg">G</i>.</p>
<p><em>Note:</em>
Read also <i class="term">Maximal Independent Set</i> description for more info.</p></dd>
<dt><a name="30"><b class="cmd">struct::graph::op::VerticesCover</b> <i class="arg">G</i></a></dt>
<dd><p><i class="term">Vertices cover</i> is a set of vertices such that each edge of the graph is incident to
at least one vertex of the set. This 2-approximation algorithm searches for minimum
<i class="term">vertices cover</i>, which is a classical optimization problem in computer science and
is a typical example of an <i class="term">NP-hard</i> optimization problem that has an approximation
algorithm.
For input graph <i class="arg">G</i> algorithm returns the set of edges (list), which is Vertex Cover found by algorithm.</p></dd>
<dt><a name="31"><b class="cmd">struct::graph::op::EdmondsKarp</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i></a></dt>
<dd><p>Improved Ford-Fulkerson's algorithm, computing the <span class="sectref"><a href="#subsection6">maximum flow</a></span> in given flow network <i class="arg">G</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Weighted and directed graph. Each edge should have set integer attribute considered as
maximum throughputs that can be carried by that link (edge).</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>The node that is a source for graph <i class="arg">G</i>.</p></dd>
<dt>Node <i class="arg">t</i> (input)</dt>
<dd><p>The node that is a sink for graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Procedure returns the dictionary containing throughputs for all edges. For
each key ( the edge between nodes <i class="term">u</i> and <i class="term">v</i> in the form of <i class="term">list u v</i> ) there is
a value that is a throughput for that key. Edges where throughput values
are equal to 0 are not returned ( it is like there was no link in the flow network
between nodes connected by such edge).</p></dd>
</dl>
<p>The general idea of algorithm is finding the shortest augumenting paths in graph <i class="arg">G</i>, as long
as they exist, and for each path updating the edge's weights along that path,
with maximum possible throughput. The final (maximum) flow is found
when there is no other augumenting path from source to sink.</p>
<p><em>Note:</em> Algorithm complexity : <i class="term">O(V*E)</i>, where <i class="term">V</i> is the number of nodes and <i class="term"><a href="../../../../index.html#e">E</a></i> is the number
of edges in graph <i class="term">G</i>.</p></dd>
<dt><a name="32"><b class="cmd">struct::graph::op::BusackerGowen</b> <i class="arg">G</i> <i class="arg">desiredFlow</i> <i class="arg">s</i> <i class="arg">t</i></a></dt>
<dd><p>Algorithm finds solution for a <span class="sectref"><a href="#subsection6">minimum cost flow problem</a></span>. So, the goal is to find a flow,
whose max value can be <i class="arg">desiredFlow</i>, from source node <i class="arg">s</i> to sink node <i class="arg">t</i> in given flow network <i class="arg">G</i>.
That network except throughputs at edges has also defined a non-negative cost on each edge - cost of using that edge when
directing flow with that edge ( it can illustrate e.g. fuel usage, time or any other measure dependent on usages ).</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Flow network (directed graph), each edge in graph should have two integer attributes: <i class="term">cost</i> and <i class="term">throughput</i>.</p></dd>
<dt>Integer <i class="arg">desiredFlow</i> (input)</dt>
<dd><p>Max value of the flow for that network.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>The source node for graph <i class="arg">G</i>.</p></dd>
<dt>Node <i class="arg">t</i> (input)</dt>
<dd><p>The sink node for graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Dictionary containing values of used throughputs for each edge ( key ).
found by algorithm.</p></dd>
</dl>
<p><em>Note:</em> Algorithm complexity : <i class="term">O(V**2*desiredFlow)</i>, where <i class="term">V</i> is the number of nodes in graph <i class="arg">G</i>.</p></dd>
<dt><a name="33"><b class="cmd">struct::graph::op::ShortestsPathsByBFS</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">outputFormat</i></a></dt>
<dd><p>Shortest pathfinding algorithm using BFS method. In comparison to <b class="cmd">struct::graph::op::dijkstra</b> it can
work with negative weights on edges. Of course negative cycles are not allowed. Algorithm is better than dijkstra
for sparse graphs, but also there exist some pathological cases (those cases generally don't appear in practise) that
make time complexity increase exponentially with the growth of the number of nodes.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Input graph.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>Source node for which all distances to each other node in graph <i class="arg">G</i> are computed.</p></dd>
</dl></dd>
<dt>Options and result:</dt>
<dd><dl class="doctools_options">
<dt><b class="option">distances</b></dt>
<dd><p>When selected <i class="arg">outputFormat</i> is <b class="const">distances</b> - procedure returns dictionary containing
distances between source node <i class="arg">s</i> and each other node in graph <i class="arg">G</i>.</p></dd>
<dt><b class="option">paths</b></dt>
<dd><p>When selected <i class="arg">outputFormat</i> is <b class="const">paths</b> - procedure returns dictionary containing
for each node <i class="term">v</i>, a list of nodes, which is a path between source node <i class="arg">s</i> and node <i class="term">v</i>.</p></dd>
</dl></dd>
</dl></dd>
<dt><a name="34"><b class="cmd">struct::graph::op::BFS</b> <i class="arg">G</i> <i class="arg">s</i> <span class="opt">?<i class="arg">outputFormat</i>...?</span></a></dt>
<dd><p>Breadth-First Search - algorithm creates the BFS Tree.
Memory and time complexity: <i class="term">O(V + E)</i>, where <i class="term">V</i> is the number of nodes and <i class="term"><a href="../../../../index.html#e">E</a></i>
is number of edges.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Input graph.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>Source node for BFS procedure.</p></dd>
</dl></dd>
<dt>Options and result:</dt>
<dd><dl class="doctools_options">
<dt><b class="option">graph</b></dt>
<dd><p>When selected <b class="option">outputFormat</b> is <b class="option">graph</b> - procedure returns a graph structure (<b class="cmd"><a href="graph.html">struct::graph</a></b>),
which is equivalent to BFS tree found by algorithm.</p></dd>
<dt><b class="option">tree</b></dt>
<dd><p>When selected <b class="option">outputFormat</b> is <b class="option">tree</b> - procedure returns a tree structure (<b class="cmd"><a href="struct_tree.html">struct::tree</a></b>),
which is equivalent to BFS tree found by algorithm.</p></dd>
</dl></dd>
</dl></dd>
<dt><a name="35"><b class="cmd">struct::graph::op::MinimumDiameterSpanningTree</b> <i class="arg">G</i></a></dt>
<dd><p>The goal is to find for input graph <i class="arg">G</i>, the <i class="term">spanning tree</i> that
has the minimum <i class="term"><a href="../../../../index.html#diameter">diameter</a></i> value.</p>
<p>General idea of algorithm is to run <i class="term"><a href="../../../../index.html#bfs">BFS</a></i> over all vertices in graph
<i class="arg">G</i>. If the diameter <i class="term">d</i> of the tree is odd, then we are sure that tree
given by <i class="term"><a href="../../../../index.html#bfs">BFS</a></i> is minimum (considering diameter value). When, diameter <i class="term">d</i>
is even, then optimal tree can have minimum <i class="term"><a href="../../../../index.html#diameter">diameter</a></i> equal to <i class="term">d</i> or
<i class="term">d-1</i>.</p>
<p>In that case, what algorithm does is rebuilding the tree given by <i class="term"><a href="../../../../index.html#bfs">BFS</a></i>, by
adding a vertice between root node and root's child node (nodes), such that
subtree created with child node as root node is the greatest one (has the
greatests height). In the next step for such rebuilded tree, we run again <i class="term"><a href="../../../../index.html#bfs">BFS</a></i>
with new node as root node. If the height of the tree didn't changed, we have found
a better solution.</p>
<p>For input graph <i class="arg">G</i> algorithm returns the graph structure (<b class="cmd"><a href="graph.html">struct::graph</a></b>) that is
a spanning tree with minimum diameter found by algorithm.</p></dd>
<dt><a name="36"><b class="cmd">struct::graph::op::MinimumDegreeSpanningTree</b> <i class="arg">G</i></a></dt>
<dd><p>Algorithm finds for input graph <i class="arg">G</i>, a spanning tree <i class="term">T</i> with the minimum possible
degree. That problem is <i class="term">NP-hard</i>, so algorithm is an approximation algorithm.</p>
<p>Let <i class="term">V</i> be the set of nodes for graph <i class="arg">G</i> and let <i class="term">W</i> be any subset of <i class="term">V</i>. Lets
assume also that <i class="term">OPT</i> is optimal solution and <i class="term">ALG</i> is solution found by algorithm for input
graph <i class="arg">G</i>.</p>
<p>It can be proven that solution found with the algorithm must fulfil inequality:</p>
<p><i class="term">((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected simple graph.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns graph structure, which is equivalent to spanning tree <i class="term">T</i> found by algorithm.</p></dd>
</dl></dd>
<dt><a name="37"><b class="cmd">struct::graph::op::MaximumFlowByDinic</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i> <i class="arg">blockingFlowAlg</i></a></dt>
<dd><p>Algorithm finds <span class="sectref"><a href="#subsection6">maximum flow</a></span> for the flow network represented by graph <i class="arg">G</i>. It is based on
the blocking-flow finding methods, which give us different complexities what makes a better fit for
different graphs.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Directed graph <i class="arg">G</i> representing the flow network. Each edge should have attribute
<i class="term">throughput</i> set with integer value.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>The source node for the flow network <i class="arg">G</i>.</p></dd>
<dt>Node <i class="arg">t</i> (input)</dt>
<dd><p>The sink node for the flow network <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Options:</dt>
<dd><dl class="doctools_options">
<dt><b class="option">dinic</b></dt>
<dd><p>Procedure will find maximum flow for flow network <i class="arg">G</i> using Dinic's algorithm (<b class="cmd">struct::graph::op::BlockingFlowByDinic</b>)
for blocking flow computation.</p></dd>
<dt><b class="option">mkm</b></dt>
<dd><p>Procedure will find maximum flow for flow network <i class="arg">G</i> using Malhotra, Kumar and Maheshwari's algorithm (<b class="cmd">struct::graph::op::BlockingFlowByMKM</b>)
for blocking flow computation.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns dictionary containing it's flow value for each edge (key) in network <i class="arg">G</i>.</p></dd>
</dl>
<p><em>Note:</em> <b class="cmd">struct::graph::op::BlockingFlowByDinic</b> gives <i class="term">O(m*n^2)</i> complexity and
<b class="cmd">struct::graph::op::BlockingFlowByMKM</b> gives <i class="term">O(n^3)</i> complexity, where <i class="term">n</i> is the number of nodes
and <i class="term">m</i> is the number of edges in flow network <i class="arg">G</i>.</p></dd>
<dt><a name="38"><b class="cmd">struct::graph::op::BlockingFlowByDinic</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i></a></dt>
<dd><p>Algorithm for given network <i class="arg">G</i> with source <i class="arg">s</i> and sink <i class="arg">t</i>, finds a <span class="sectref"><a href="#subsection6">blocking
flow</a></span>, which can be used to obtain a <i class="term"><a href="../../../../index.html#maximum_flow">maximum flow</a></i> for that network <i class="arg">G</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Directed graph <i class="arg">G</i> representing the flow network. Each edge should have attribute
<i class="term">throughput</i> set with integer value.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>The source node for the flow network <i class="arg">G</i>.</p></dd>
<dt>Node <i class="arg">t</i> (input)</dt>
<dd><p>The sink node for the flow network <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network <i class="arg">G</i>.</p></dd>
</dl>
<p><em>Note:</em> Algorithm's complexity is <i class="term">O(n*m)</i>, where <i class="term">n</i> is the number of nodes
and <i class="term">m</i> is the number of edges in flow network <i class="arg">G</i>.</p></dd>
<dt><a name="39"><b class="cmd">struct::graph::op::BlockingFlowByMKM</b> <i class="arg">G</i> <i class="arg">s</i> <i class="arg">t</i></a></dt>
<dd><p>Algorithm for given network <i class="arg">G</i> with source <i class="arg">s</i> and sink <i class="arg">t</i>, finds a <span class="sectref"><a href="#subsection6">blocking
flow</a></span>, which can be used to obtain a <i class="term"><a href="../../../../index.html#maximum_flow">maximum flow</a></i> for that <i class="term"><a href="../../../../index.html#network">network</a></i> <i class="arg">G</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Directed graph <i class="arg">G</i> representing the flow network. Each edge should have attribute
<i class="term">throughput</i> set with integer value.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>The source node for the flow network <i class="arg">G</i>.</p></dd>
<dt>Node <i class="arg">t</i> (input)</dt>
<dd><p>The sink node for the flow network <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network <i class="arg">G</i>.</p></dd>
</dl>
<p><em>Note:</em> Algorithm's complexity is <i class="term">O(n^2)</i>, where <i class="term">n</i> is the number of nodes in flow network <i class="arg">G</i>.</p></dd>
<dt><a name="40"><b class="cmd">struct::graph::op::createResidualGraph</b> <i class="arg">G</i> <i class="arg">f</i></a></dt>
<dd><p>Procedure creates a <i class="term"><a href="../../../../index.html#residual_graph">residual graph</a></i> (or <span class="sectref"><a href="#subsection6">residual network</a></span> ) for network <i class="arg">G</i> and given
flow <i class="arg">f</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Flow network (directed graph where each edge has set attribute: <i class="term">throughput</i> ).</p></dd>
<dt>dictionary <i class="arg">f</i> (input)</dt>
<dd><p>Current flows in flow network <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Procedure returns graph structure that is a <i class="term"><a href="../../../../index.html#residual_graph">residual graph</a></i> created from input flow
network <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt><a name="41"><b class="cmd">struct::graph::op::createAugmentingNetwork</b> <i class="arg">G</i> <i class="arg">f</i> <i class="arg">path</i></a></dt>
<dd><p>Procedure creates an <span class="sectref"><a href="#subsection6">augmenting network</a></span> for a given residual network <i class="arg">G</i>
, flow <i class="arg">f</i> and augmenting path <i class="arg">path</i>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Residual network (directed graph), where for every edge there are set two attributes: throughput and cost.</p></dd>
<dt>Dictionary <i class="arg">f</i> (input)</dt>
<dd><p>Dictionary which contains for every edge (key), current value of the flow on that edge.</p></dd>
<dt>List <i class="arg">path</i> (input)</dt>
<dd><p>Augmenting path, set of edges (list) for which we create the network modification.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns graph structure containing the modified augmenting network.</p></dd>
</dl></dd>
<dt><a name="42"><b class="cmd">struct::graph::op::createLevelGraph</b> <i class="arg">Gf</i> <i class="arg">s</i></a></dt>
<dd><p>For given residual graph <i class="arg">Gf</i> procedure finds the <span class="sectref"><a href="#subsection6">level graph</a></span>.</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">Gf</i> (input)</dt>
<dd><p>Residual network, where each edge has it's attribute <i class="term">throughput</i> set with certain value.</p></dd>
<dt>Node <i class="arg">s</i> (input)</dt>
<dd><p>The source node for the residual network <i class="arg">Gf</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Procedure returns a <i class="term"><a href="../../../../index.html#level_graph">level graph</a></i> created from input <i class="term">residual network</i>.</p></dd>
</dl></dd>
<dt><a name="43"><b class="cmd">struct::graph::op::TSPLocalSearching</b> <i class="arg">G</i> <i class="arg">C</i></a></dt>
<dd><p>Algorithm is a <i class="term">heuristic of local searching</i> for <i class="term">Travelling Salesman Problem</i>. For some
solution of <i class="term">TSP problem</i>, it checks if it's possible to find a better solution. As <i class="term">TSP</i>
is well known NP-Complete problem, so algorithm is a approximation algorithm (with 2 approximation factor).</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected and complete graph with attributes "weight" set on each single edge.</p></dd>
<dt>List <i class="arg">C</i> (input)</dt>
<dd><p>A list of edges being <i class="term">Hamiltonian cycle</i>, which is solution of <i class="term">TSP Problem</i> for graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns the best solution for <i class="term">TSP problem</i>, it was able to find.</p></dd>
</dl>
<p><em>Note:</em> The solution depends on the choosing of the beginning cycle <i class="arg">C</i>. It's not true that better cycle
assures that better solution will be found, but practise shows that we should give starting cycle with as small
sum of weights as possible.</p></dd>
<dt><a name="44"><b class="cmd">struct::graph::op::TSPLocalSearching3Approx</b> <i class="arg">G</i> <i class="arg">C</i></a></dt>
<dd><p>Algorithm is a <i class="term">heuristic of local searching</i> for <i class="term">Travelling Salesman Problem</i>. For some
solution of <i class="term">TSP problem</i>, it checks if it's possible to find a better solution. As <i class="term">TSP</i>
is well known NP-Complete problem, so algorithm is a approximation algorithm (with 3 approximation factor).</p>
<dl class="doctools_definitions">
<dt>Arguments:</dt>
<dd><dl class="doctools_arguments">
<dt>Graph Object <i class="arg">G</i> (input)</dt>
<dd><p>Undirected and complete graph with attributes "weight" set on each single edge.</p></dd>
<dt>List <i class="arg">C</i> (input)</dt>
<dd><p>A list of edges being <i class="term">Hamiltonian cycle</i>, which is solution of <i class="term">TSP Problem</i> for graph <i class="arg">G</i>.</p></dd>
</dl></dd>
<dt>Result:</dt>
<dd><p>Algorithm returns the best solution for <i class="term">TSP problem</i>, it was able to find.</p></dd>
</dl>
<p><em>Note:</em> In practise 3-approximation algorithm turns out to be far more effective than 2-approximation, but it gives
worser approximation factor. Further heuristics of local searching (e.g. 4-approximation) doesn't give enough boost to
square the increase of approximation factor, so 2 and 3 approximations are mainly used.</p></dd>
<dt><a name="45"><b class="cmd">struct::graph::op::createSquaredGraph</b> <i class="arg">G</i></a></dt>
<dd><p>X-Squared graph is a graph with the same set of nodes as input graph <i class="arg">G</i>, but a different set of edges. X-Squared graph
has edge <i class="term">(u,v)</i>, if and only if, the distance between <i class="term">u</i> and <i class="term">v</i> nodes is not greater than X and <i class="term">u != v</i>.</p>
<p>Procedure for input graph <i class="arg">G</i>, returns its two-squared graph.</p>
<p><em>Note:</em> Distances used in choosing new set of edges are considering the number of edges, not the sum of weights at edges.</p></dd>
<dt><a name="46"><b class="cmd">struct::graph::op::createCompleteGraph</b> <i class="arg">G</i> <i class="arg">originalEdges</i></a></dt>
<dd><p>For input graph <i class="arg">G</i> procedure adds missing arcs to make it a <i class="term"><a href="../../../../index.html#complete_graph">complete graph</a></i>. It also holds in
variable <i class="arg">originalEdges</i> the set of arcs that graph <i class="arg">G</i> possessed before that operation.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Background theory and terms</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Shortest Path Problem</a></h3>
<dl class="doctools_definitions">
<dt>Definition (<i class="term">single-pair shortest path problem</i>):</dt>
<dd><p>Formally, given a weighted graph (let <i class="term">V</i> be the set of vertices, and <i class="term"><a href="../../../../index.html#e">E</a></i> a set of edges),
and one vertice <i class="term">v</i> of <i class="term">V</i>, find a path <i class="term">P</i> from <i class="term">v</i> to a <i class="term">v'</i> of V so that
the sum of weights on edges along the path is minimal among all paths connecting v to v'.</p></dd>
<dt>Generalizations:</dt>
<dd><ul class="doctools_itemized">
<li><p><i class="term">The single-source shortest path problem</i>, in which we have to find shortest paths from a source vertex v to all other vertices in the graph.</p></li>
<li><p><i class="term">The single-destination shortest path problem</i>, in which we have to find shortest paths from all vertices in the graph to a single destination vertex v. This can be reduced to the single-source shortest path problem by reversing the edges in the graph.</p></li>
<li><p><i class="term">The all-pairs shortest path problem</i>, in which we have to find shortest paths between every pair of vertices v, v' in the graph.</p></li>
</ul>
<p><em>Note:</em>
The result of <i class="term">Shortest Path problem</i> can be <i class="term">Shortest Path tree</i>, which is a subgraph of a given (possibly weighted) graph constructed so that the
distance between a selected root node and all other nodes is minimal. It is a tree because if there are two paths between the root node and some
vertex v (i.e. a cycle), we can delete the last edge of the longer path without increasing the distance from the root node to any node in the subgraph.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Travelling Salesman Problem</a></h3>
<dl class="doctools_definitions">
<dt>Definition:</dt>
<dd><p>For given edge-weighted (weights on edges should be positive) graph the goal is to find the cycle that visits each node in graph
exactly once (<i class="term">Hamiltonian cycle</i>).</p></dd>
<dt>Generalizations:</dt>
<dd><ul class="doctools_itemized">
<li><p><i class="term">Metric TSP</i> - A very natural restriction of the <i class="term">TSP</i> is to require that the distances between cities form a <i class="term">metric</i>, i.e.,
they satisfy <i class="term">the triangle inequality</i>. That is, for any 3 cities <i class="term">A</i>, <i class="term">B</i> and <i class="term"><a href="../../../../index.html#c">C</a></i>, the distance between <i class="term">A</i> and <i class="term"><a href="../../../../index.html#c">C</a></i>
must be at most the distance from <i class="term">A</i> to <i class="term">B</i> plus the distance from <i class="term">B</i> to <i class="term"><a href="../../../../index.html#c">C</a></i>. Most natural instances of <i class="term">TSP</i>
satisfy this constraint.</p></li>
<li><p><i class="term">Euclidean TSP</i> - Euclidean TSP, or <i class="term">planar TSP</i>, is the <i class="term">TSP</i> with the distance being the ordinary <i class="term">Euclidean distance</i>.
<i class="term">Euclidean TSP</i> is a particular case of <i class="term">TSP</i> with <i class="term">triangle inequality</i>, since distances in plane obey triangle inequality. However,
it seems to be easier than general <i class="term">TSP</i> with <i class="term">triangle inequality</i>. For example, <i class="term">the minimum spanning tree</i> of the graph associated
with an instance of <i class="term">Euclidean TSP</i> is a <i class="term">Euclidean minimum spanning tree</i>, and so can be computed in expected <i class="term">O(n log n)</i> time for
<i class="term">n</i> points (considerably less than the number of edges). This enables the simple <i class="term">2-approximation algorithm</i> for TSP with triangle
inequality above to operate more quickly.</p></li>
<li><p><i class="term">Asymmetric TSP</i> - In most cases, the distance between two nodes in the <i class="term">TSP</i> network is the same in both directions.
The case where the distance from <i class="term">A</i> to <i class="term">B</i> is not equal to the distance from <i class="term">B</i> to <i class="term">A</i> is called <i class="term">asymmetric TSP</i>.
A practical application of an <i class="term">asymmetric TSP</i> is route optimisation using street-level routing (asymmetric due to one-way streets,
slip-roads and motorways).</p></li>
</ul></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Matching Problem</a></h3>
<dl class="doctools_definitions">
<dt>Definition:</dt>
<dd><p>Given a graph <i class="term">G = (V,E)</i>, a matching or <i class="term">edge-independent set</i> <i class="term">M</i> in <i class="term">G</i> is a set of pairwise non-adjacent edges,
that is, no two edges share a common vertex. A vertex is <i class="term">matched</i> if it is incident to an edge in the <i class="term">matching M</i>.
Otherwise the vertex is <i class="term">unmatched</i>.</p></dd>
<dt>Generalizations:</dt>
<dd><ul class="doctools_itemized">
<li><p><i class="term">Maximal matching</i> - a matching <i class="term">M</i> of a graph G with the property that if any edge not in <i class="term">M</i> is added to <i class="term">M</i>,
it is no longer a <i class="term"><a href="../../../../index.html#matching">matching</a></i>, that is, <i class="term">M</i> is maximal if it is not a proper subset of any other <i class="term"><a href="../../../../index.html#matching">matching</a></i> in graph G.
In other words, a <i class="term">matching M</i> of a graph G is maximal if every edge in G has a non-empty intersection with at least one edge in <i class="term">M</i>.</p></li>
<li><p><i class="term">Maximum matching</i> - a matching that contains the largest possible number of edges. There may be many <i class="term">maximum matchings</i>.
The <i class="term">matching number</i> of a graph G is the size of a <i class="term">maximum matching</i>. Note that every <i class="term">maximum matching</i> is <i class="term">maximal</i>,
but not every <i class="term">maximal matching</i> is a <i class="term">maximum matching</i>.</p></li>
<li><p><i class="term">Perfect matching</i> - a matching which matches all vertices of the graph. That is, every vertex of the graph is incident to exactly one
edge of the matching. Every <i class="term">perfect matching</i> is <i class="term"><a href="../../../../index.html#maximum">maximum</a></i> and hence <i class="term">maximal</i>. In some literature, the term <i class="term">complete matching</i>
is used. A <i class="term">perfect matching</i> is also a <i class="term">minimum-size edge cover</i>. Moreover, the size of a <i class="term">maximum matching</i> is no larger than the
size of a <i class="term">minimum edge cover</i>.</p></li>
<li><p><i class="term">Near-perfect matching</i> - a matching in which exactly one vertex is unmatched. This can only occur when the graph has an odd number of vertices,
and such a <i class="term"><a href="../../../../index.html#matching">matching</a></i> must be <i class="term"><a href="../../../../index.html#maximum">maximum</a></i>. If, for every vertex in a graph, there is a near-perfect matching that omits only that vertex, the graph
is also called <i class="term">factor-critical</i>.</p></li>
</ul></dd>
<dt>Related terms:</dt>
<dd><ul class="doctools_itemized">
<li><p><i class="term">Alternating path</i> - given a matching <i class="term">M</i>, an <i class="term">alternating path</i> is a path in which the edges belong alternatively
to the matching and not to the matching.</p></li>
<li><p><i class="term"><a href="../../../../index.html#augmenting_path">Augmenting path</a></i> - given a matching <i class="term">M</i>, an <i class="term"><a href="../../../../index.html#augmenting_path">augmenting path</a></i> is an <i class="term">alternating path</i> that starts from
and ends on free (unmatched) vertices.</p></li>
</ul></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Cut Problems</a></h3>
<dl class="doctools_definitions">
<dt>Definition:</dt>
<dd><p>A <i class="term">cut</i> is a partition of the vertices of a graph into two <i class="term">disjoint subsets</i>. The <i class="term">cut-set</i> of the <i class="term">cut</i> is the
set of edges whose end points are in different subsets of the partition. Edges are said to be crossing the cut if they are in its <i class="term">cut-set</i>.</p>
<p>Formally:</p>
<ul class="doctools_itemized">
<li><p>a <i class="term">cut</i> <i class="term">C = (S,T)</i> is a partition of <i class="term">V</i> of a graph <i class="term">G = (V, E)</i>.</p></li>
<li><p>an <i class="term">s-t cut</i> <i class="term">C = (S,T)</i> of a <i class="term"><a href="../../../../index.html#flow_network">flow network</a></i> <i class="term">N = (V, E)</i> is a cut of <i class="term">N</i> such that <i class="term">s</i> is included in <i class="term">S</i>
and <i class="term">t</i> is included in <i class="term">T</i>, where <i class="term">s</i> and <i class="term">t</i> are the <i class="term"><a href="../../../../index.html#source">source</a></i> and the <i class="term">sink</i> of <i class="term">N</i> respectively.</p></li>
<li><p>The <i class="term">cut-set</i> of a <i class="term">cut C = (S,T)</i> is such set of edges from graph <i class="term">G = (V, E)</i> that each edge <i class="term">(u, v)</i> satisfies
condition that <i class="term">u</i> is included in <i class="term">S</i> and <i class="term">v</i> is included in <i class="term">T</i>.</p></li>
</ul>
<p>In an <i class="term">unweighted undirected</i> graph, the size or weight of a cut is the number of edges crossing the cut. In a <i class="term">weighted graph</i>,
the same term is defined by the sum of the weights of the edges crossing the cut.</p>
<p>In a <i class="term"><a href="../../../../index.html#flow_network">flow network</a></i>, an <i class="term">s-t cut</i> is a cut that requires the <i class="term"><a href="../../../../index.html#source">source</a></i> and the <i class="term">sink</i> to be in different subsets,
and its <i class="term">cut-set</i> only consists of edges going from the <i class="term">source's</i> side to the <i class="term">sink's</i> side. The capacity of an <i class="term">s-t cut</i>
is defined by the sum of capacity of each edge in the <i class="term">cut-set</i>.</p>
<p>The <i class="term">cut</i> of a graph can sometimes refer to its <i class="term">cut-set</i> instead of the partition.</p></dd>
<dt>Generalizations:</dt>
<dd><ul class="doctools_itemized">
<li><p><i class="term">Minimum cut</i> - A cut is minimum if the size of the cut is not larger than the size of any other cut.</p></li>
<li><p><i class="term">Maximum cut</i> - A cut is maximum if the size of the cut is not smaller than the size of any other cut.</p></li>
<li><p><i class="term">Sparsest cut</i> - The <i class="term">Sparsest cut problem</i> is to bipartition the vertices so as to minimize the ratio of the number
of edges across the cut divided by the number of vertices in the smaller half of the partition.</p></li>
</ul></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">K-Center Problem</a></h3>
<dl class="doctools_definitions">
<dt>Definitions:</dt>
<dd><dl class="doctools_definitions">
<dt><i class="term">Unweighted K-Center</i></dt>
<dd><p>For any set <i class="term">S</i> ( which is subset of <i class="term">V</i> ) and node <i class="term">v</i>, let the <i class="term">connect(v,S)</i> be the
cost of cheapest edge connecting <i class="term">v</i> with any node in <i class="term">S</i>. The goal is to find
such <i class="term">S</i>, that <i class="term">|S| = k</i> and <i class="term">max_v{connect(v,S)}</i> is possibly small.</p>
<p>In other words, we can use it i.e. for finding best locations in the city ( nodes
of input graph ) for placing k buildings, such that those buildings will be as close
as possible to all other locations in town.</p></dd>
<dt><i class="term">Weighted K-Center</i></dt>
<dd><p>The variation of <i class="term">unweighted k-center problem</i>. Besides the fact graph is edge-weighted,
there are also weights on vertices of input graph <i class="arg">G</i>. We've got also restriction
<i class="arg">W</i>. The goal is to choose such set of nodes <i class="term">S</i> ( which is a subset of <i class="term">V</i> ), that it's
total weight is not greater than <i class="arg">W</i> and also function: <i class="term">max_v { min_u { cost(u,v) }}</i>
has the smallest possible worth ( <i class="term">v</i> is a node in <i class="term">V</i> and <i class="term">u</i> is a node in <i class="term">S</i> ).</p></dd>
</dl></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Flow Problems</a></h3>
<dl class="doctools_definitions">
<dt>Definitions:</dt>
<dd><ul class="doctools_itemized">
<li><p><i class="term">the maximum flow problem</i> - the goal is to find a feasible flow through a single-source, single-sink flow network that is maximum.
The <i class="term">maximum flow problem</i> can be seen as a special case of more complex network flow problems, such as the <i class="term">circulation problem</i>.
The maximum value of an <i class="term">s-t flow</i> is equal to the minimum capacity of an <i class="term">s-t cut</i> in the network, as stated in the
<i class="term">max-flow min-cut theorem</i>.</p>
<p>More formally for flow network <i class="term">G = (V,E)</i>, where for each edge <i class="term">(u, v)</i> we have its throuhgput <i class="term">c(u,v)</i> defined. As <i class="term"><a href="../../../../index.html#flow">flow</a></i>
<i class="term">F</i> we define set of non-negative integer attributes <i class="term">f(u,v)</i> assigned to edges, satisfying such conditions:</p>
<ol class="doctools_enumerated">
<li><p>for each edge <i class="term">(u, v)</i> in <i class="term">G</i> such condition should be satisfied: 0 <= f(u,v) <= c(u,v)</p></li>
<li><p>Network <i class="term">G</i> has source node <i class="term">s</i> such that the flow <i class="term">F</i> is equal to the sum of outcoming flow decreased by the sum of incoming flow from that source node <i class="term">s</i>.</p></li>
<li><p>Network <i class="term">G</i> has sink node <i class="term">t</i> such that the the <i class="term">-F</i> value is equal to the sum of the incoming flow decreased by the sum of outcoming flow from that sink node <i class="term">t</i>.</p></li>
<li><p>For each node that is not a <i class="term"><a href="../../../../index.html#source">source</a></i> or <i class="term">sink</i> the sum of incoming flow and sum of outcoming flow should be equal.</p></li>
</ol>
</li>
<li><p><i class="term">the minimum cost flow problem</i> - the goal is finding the cheapest possible way of sending a certain amount of flow through a <i class="term"><a href="../../../../index.html#flow_network">flow network</a></i>.</p></li>
<li><p><i class="term"><a href="../../../../index.html#blocking_flow">blocking flow</a></i> - a <i class="term"><a href="../../../../index.html#blocking_flow">blocking flow</a></i> for a <i class="term">residual network</i> <i class="term">Gf</i> we name such flow <i class="term">b</i> in <i class="term">Gf</i> that:</p>
<ol class="doctools_enumerated">
<li><p>Each path from <i class="term">sink</i> to <i class="term"><a href="../../../../index.html#source">source</a></i> is the shortest path in <i class="term">Gf</i>.</p></li>
<li><p>Each shortest path in <i class="term">Gf</i> contains an edge with fully used throughput in <i class="term">Gf+b</i>.</p></li>
</ol>
</li>
<li><p><i class="term">residual network</i> - for a flow network <i class="term">G</i> and flow <i class="term">f</i> <i class="term">residual network</i> is built with those edges, which can
send larger flow. It contains only those edges, which can send flow larger than 0.</p></li>
<li><p><i class="term">level network</i> - it has the same set of nodes as <i class="term"><a href="../../../../index.html#residual_graph">residual graph</a></i>, but has only those edges <i class="term">(u,v)</i> from <i class="arg">Gf</i>
for which such equality is satisfied: <i class="term">distance(s,u)+1 = distance(s,v)</i>.</p></li>
<li><p><i class="term"><a href="../../../../index.html#augmenting_network">augmenting network</a></i> - it is a modification of <i class="term">residual network</i> considering the new
flow values. Structure stays unchanged but values of throughputs and costs at edges
are different.</p></li>
</ul></dd>
</dl>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Approximation algorithm</a></h3>
<dl class="doctools_definitions">
<dt>k-approximation algorithm:</dt>
<dd><p>Algorithm is a k-approximation, when for <i class="term">ALG</i> (solution returned by algorithm) and
<i class="term">OPT</i> (optimal solution), such inequality is true:</p>
<ul class="doctools_itemized">
<li><p>for minimalization problems: <i class="term">ALG/OPT <= k</i></p></li>
<li><p>for maximalization problems: <i class="term">OPT/ALG <= k</i></p></li>
</ul></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://en.wikipedia.org/wiki/Adjacency_matrix">Adjacency matrix</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Adjacency_list">Adjacency list</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Kruskal%27s_algorithm">Kruskal's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Prim%27s_algorithm">Prim's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Bipartite_graph">Bipartite graph</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Strongly_connected_components">Strongly connected components</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm">Tarjan's strongly connected components algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Cut_vertex">Cut vertex</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Bridge_(graph_theory)">Bridge</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Bellman-Ford_algorithm">Bellman-Ford's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Johnson_algorithm">Johnson's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Floyd-Warshall_algorithm">Floyd-Warshall's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Travelling_salesman_problem">Travelling Salesman Problem</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Christofides_algorithm">Christofides Algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Maxcut">Max Cut</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Matching">Matching</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Maximal_independent_set">Max Independent Set</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Vertex_cover_problem">Vertex Cover</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Ford-Fulkerson_algorithm">Ford-Fulkerson's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Maximum_flow_problem">Maximum Flow problem</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Minimum_cost_flow_problem">Busacker-Gowen's algorithm</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Dinic's_algorithm">Dinic's algorithm</a></p></li>
<li><p><a href="http://www.csc.kth.se/~viggo/wwwcompendium/node128.html">K-Center problem</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Breadth-first_search">BFS</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree">Minimum Degree Spanning Tree</a></p></li>
<li><p><a href="http://en.wikipedia.org/wiki/Approximation_algorithm">Approximation algorithm</a></p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: graph</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#adjacency_list">adjacency list</a>, <a href="../../../../index.html#adjacency_matrix">adjacency matrix</a>, <a href="../../../../index.html#adjacent">adjacent</a>, <a href="../../../../index.html#approximation_algorithm">approximation algorithm</a>, <a href="../../../../index.html#arc">arc</a>, <a href="../../../../index.html#articulation_point">articulation point</a>, <a href="../../../../index.html#augmenting_network">augmenting network</a>, <a href="../../../../index.html#augmenting_path">augmenting path</a>, <a href="../../../../index.html#bfs">bfs</a>, <a href="../../../../index.html#bipartite">bipartite</a>, <a href="../../../../index.html#blocking_flow">blocking flow</a>, <a href="../../../../index.html#bridge">bridge</a>, <a href="../../../../index.html#complete_graph">complete graph</a>, <a href="../../../../index.html#connected_component">connected component</a>, <a href="../../../../index.html#cut_edge">cut edge</a>, <a href="../../../../index.html#cut_vertex">cut vertex</a>, <a href="../../../../index.html#degree">degree</a>, <a href="../../../../index.html#degree_constrained_spanning_tree">degree constrained spanning tree</a>, <a href="../../../../index.html#diameter">diameter</a>, <a href="../../../../index.html#dijkstra">dijkstra</a>, <a href="../../../../index.html#distance">distance</a>, <a href="../../../../index.html#eccentricity">eccentricity</a>, <a href="../../../../index.html#edge">edge</a>, <a href="../../../../index.html#flow_network">flow network</a>, <a href="../../../../index.html#graph">graph</a>, <a href="../../../../index.html#heuristic">heuristic</a>, <a href="../../../../index.html#independent_set">independent set</a>, <a href="../../../../index.html#isthmus">isthmus</a>, <a href="../../../../index.html#level_graph">level graph</a>, <a href="../../../../index.html#local_searching">local searching</a>, <a href="../../../../index.html#loop">loop</a>, <a href="../../../../index.html#matching">matching</a>, <a href="../../../../index.html#max_cut">max cut</a>, <a href="../../../../index.html#maximum_flow">maximum flow</a>, <a href="../../../../index.html#minimal_spanning_tree">minimal spanning tree</a>, <a href="../../../../index.html#minimum_cost_flow">minimum cost flow</a>, <a href="../../../../index.html#minimum_degree_spanning_tree">minimum degree spanning tree</a>, <a href="../../../../index.html#minimum_diameter_spanning_tree">minimum diameter spanning tree</a>, <a href="../../../../index.html#neighbour">neighbour</a>, <a href="../../../../index.html#node">node</a>, <a href="../../../../index.html#radius">radius</a>, <a href="../../../../index.html#residual_graph">residual graph</a>, <a href="../../../../index.html#shortest_path">shortest path</a>, <a href="../../../../index.html#squared_graph">squared graph</a>, <a href="../../../../index.html#strongly_connected_component">strongly connected component</a>, <a href="../../../../index.html#subgraph">subgraph</a>, <a href="../../../../index.html#travelling_salesman">travelling salesman</a>, <a href="../../../../index.html#vertex">vertex</a>, <a href="../../../../index.html#vertex_cover">vertex cover</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Alejandro Paz <[email protected]><br>
Copyright © 2008 (docs) Andreas Kupries <[email protected]><br>
Copyright © 2009 Michal Antoniewski <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/matrix.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
|
<div class='fossil-doc' data-title='struct::matrix - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::matrix(n) 2.0.3 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::matrix - Create and manipulate matrix objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::matrix <span class="opt">?2.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::matrix</b> <span class="opt">?<i class="arg">matrixName</i>?</span> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">source</i>?</span></a></li>
<li><a href="#2"><b class="cmd">matrixName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">matrixName</i> <b class="method">=</b> <i class="arg">sourcematrix</i></a></li>
<li><a href="#4"><i class="arg">matrixName</i> <b class="method">--></b> <i class="arg">destmatrix</i></a></li>
<li><a href="#5"><i class="arg">matrixName</i> <b class="method">add column</b> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#6"><i class="arg">matrixName</i> <b class="method">add row</b> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#7"><i class="arg">matrixName</i> <b class="method">add columns</b> <i class="arg">n</i></a></li>
<li><a href="#8"><i class="arg">matrixName</i> <b class="method">add rows</b> <i class="arg">n</i></a></li>
<li><a href="#9"><i class="arg">matrixName</i> <b class="method">cells</b></a></li>
<li><a href="#10"><i class="arg">matrixName</i> <b class="method">cellsize</b> <i class="arg">column row</i></a></li>
<li><a href="#11"><i class="arg">matrixName</i> <b class="method">columns</b></a></li>
<li><a href="#12"><i class="arg">matrixName</i> <b class="method">columnwidth</b> <i class="arg">column</i></a></li>
<li><a href="#13"><i class="arg">matrixName</i> <b class="method">delete column</b> <i class="arg">column</i></a></li>
<li><a href="#14"><i class="arg">matrixName</i> <b class="method">delete columns</b> <i class="arg">n</i></a></li>
<li><a href="#15"><i class="arg">matrixName</i> <b class="method">delete row</b> <i class="arg">row</i></a></li>
<li><a href="#16"><i class="arg">matrixName</i> <b class="method">delete rows</b> <i class="arg">n</i></a></li>
<li><a href="#17"><i class="arg">matrixName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></li>
<li><a href="#18"><i class="arg">matrixName</i> <b class="method">destroy</b></a></li>
<li><a href="#19"><i class="arg">matrixName</i> <b class="method">format 2string</b> <span class="opt">?<i class="arg">report</i>?</span></a></li>
<li><a href="#20"><i class="arg">matrixName</i> <b class="method">format 2chan</b> <span class="opt">?<span class="opt">?<i class="arg">report</i>?</span> <i class="arg">channel</i>?</span></a></li>
<li><a href="#21"><i class="arg">matrixName</i> <b class="method">get cell</b> <i class="arg">column row</i></a></li>
<li><a href="#22"><i class="arg">matrixName</i> <b class="method">get column</b> <i class="arg">column</i></a></li>
<li><a href="#23"><i class="arg">matrixName</i> <b class="method">get rect</b> <i class="arg">column_tl row_tl column_br row_br</i></a></li>
<li><a href="#24"><i class="arg">matrixName</i> <b class="method">get row</b> <i class="arg">row</i></a></li>
<li><a href="#25"><i class="arg">matrixName</i> <b class="method">insert column</b> <i class="arg">column</i> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#26"><i class="arg">matrixName</i> <b class="method">insert row</b> <i class="arg">row</i> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#27"><i class="arg">matrixName</i> <b class="method">link</b> <span class="opt">?-transpose?</span> <i class="arg">arrayvar</i></a></li>
<li><a href="#28"><i class="arg">matrixName</i> <b class="method">links</b></a></li>
<li><a href="#29"><i class="arg">matrixName</i> <b class="method">rowheight</b> <i class="arg">row</i></a></li>
<li><a href="#30"><i class="arg">matrixName</i> <b class="method">rows</b></a></li>
<li><a href="#31"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">all</b> <i class="arg">pattern</i></a></li>
<li><a href="#32"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">column</b> <i class="arg">column pattern</i></a></li>
<li><a href="#33"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">row</b> <i class="arg">row pattern</i></a></li>
<li><a href="#34"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">rect</b> <i class="arg">column_tl row_tl column_br row_br pattern</i></a></li>
<li><a href="#35"><i class="arg">matrixName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">column_tl row_tl column_br row_br</i>?</span></a></li>
<li><a href="#36"><i class="arg">matrixName</i> <b class="method">set cell</b> <i class="arg">column row value</i></a></li>
<li><a href="#37"><i class="arg">matrixName</i> <b class="method">set column</b> <i class="arg">column values</i></a></li>
<li><a href="#38"><i class="arg">matrixName</i> <b class="method">set rect</b> <i class="arg">column row values</i></a></li>
<li><a href="#39"><i class="arg">matrixName</i> <b class="method">set row</b> <i class="arg">row values</i></a></li>
<li><a href="#40"><i class="arg">matrixName</i> <b class="method">sort columns</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">row</i></a></li>
<li><a href="#41"><i class="arg">matrixName</i> <b class="method">sort rows</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">column</i></a></li>
<li><a href="#42"><i class="arg">matrixName</i> <b class="method">swap columns</b> <i class="arg">column_a column_b</i></a></li>
<li><a href="#43"><i class="arg">matrixName</i> <b class="method">swap rows</b> <i class="arg">row_a row_b</i></a></li>
<li><a href="#44"><i class="arg">matrixName</i> <b class="method">transpose</b></a></li>
<li><a href="#45"><i class="arg">matrixName</i> <b class="method">unlink</b> <i class="arg">arrayvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>A matrix is a rectangular collection of cells, i.e. organized in rows
and columns. Each cell contains exactly one value of arbitrary
form. The cells in the matrix are addressed by pairs of integer
numbers, with the first (left) number in the pair specifying the
column and the second (right) number specifying the row the cell is
in. These indices are counted from 0 upward. The special non-numeric
index <b class="const">end</b> refers to the last row or column in the matrix,
depending on the context. Indices of the form
<b class="const">end</b>-<b class="variable">number</b> are counted from the end of the row or
column, like they are for standard Tcl lists. Trying to access
non-existing cells causes an error.</p>
<p>The matrices here are created empty, i.e. they have neither rows nor
columns. The user then has to add rows and columns as needed by his
application. A specialty of this structure is the ability to export an
array-view onto its contents. Such can be used by tkTable, for
example, to link the matrix into the display.</p>
<p>The main command of the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::matrix</b> <span class="opt">?<i class="arg">matrixName</i>?</span> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">source</i>?</span></a></dt>
<dd><p>The command creates a new matrix object with an associated global Tcl
command whose name is <i class="arg">matrixName</i>. This command may be used to
invoke various operations on the matrix. It has the following general
form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">matrixName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>If <i class="arg">matrixName</i> is not specified a unique name will be generated
by the package itself. If a <i class="arg">source</i> is specified the new matrix
will be initialized to it. For the operators <b class="const">=</b>, <b class="const">:=</b>,
and <b class="const">as</b> the argument <i class="arg">source</i> is interpreted as the name of
another matrix object, and the assignment operator <b class="method">=</b> will be
executed. For <b class="const">deserialize</b> the <i class="arg">source</i> is a serialized
matrix object and <b class="method">deserialize</b> will be executed.</p>
<p>In other words</p>
<pre class="doctools_example">
::struct::matrix mymatrix = b
</pre>
<p>is equivalent to</p>
<pre class="doctools_example">
::struct::matrix mymatrix
mymatrix = b
</pre>
<p>and</p>
<pre class="doctools_example">
::struct::matrix mymatrix deserialize $b
</pre>
<p>is equivalent to</p>
<pre class="doctools_example">
::struct::matrix mymatrix
mymatrix deserialize $b
</pre>
</dd>
</dl>
<p>The following commands are possible for matrix objects:</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">matrixName</i> <b class="method">=</b> <i class="arg">sourcematrix</i></a></dt>
<dd><p>This is the assignment operator for matrix objects. It copies the matrix
contained in the matrix object <i class="arg">sourcematrix</i> over the matrix data in
<i class="arg">matrixName</i>. The old contents of <i class="arg">matrixName</i> are deleted by
this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">matrixName</i> <b class="method">deserialize</b> [<i class="arg">sourcematrix</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="4"><i class="arg">matrixName</i> <b class="method">--></b> <i class="arg">destmatrix</i></a></dt>
<dd><p>This is the reverse assignment operator for matrix objects. It copies
the matrix contained in the matrix object <i class="arg">matrixName</i> over the matrix
data in the object <i class="arg">destmatrix</i>.
The old contents of <i class="arg">destmatrix</i> are deleted by this operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">destmatrix</i> <b class="method">deserialize</b> [<i class="arg">matrixName</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="5"><i class="arg">matrixName</i> <b class="method">add column</b> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one column and then acts like <b class="method">set column</b>
(see below) on this new column if there were <i class="arg">values</i>
supplied. Without <i class="arg">values</i> the new cells will be set to the empty
string. The new column is appended immediately behind the last
existing column.</p></dd>
<dt><a name="6"><i class="arg">matrixName</i> <b class="method">add row</b> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one row and then acts like <b class="method">set row</b> (see
below) on this new row if there were <i class="arg">values</i> supplied. Without
<i class="arg">values</i> the new cells will be set to the empty string. The new
row is appended immediately behind the last existing row.</p></dd>
<dt><a name="7"><i class="arg">matrixName</i> <b class="method">add columns</b> <i class="arg">n</i></a></dt>
<dd><p>Extends the matrix by <i class="arg">n</i> columns. The new cells will be set to
the empty string. The new columns are appended immediately behind the
last existing column. A value of <i class="arg">n</i> equal to or smaller than 0 is
not allowed.</p></dd>
<dt><a name="8"><i class="arg">matrixName</i> <b class="method">add rows</b> <i class="arg">n</i></a></dt>
<dd><p>Extends the matrix by <i class="arg">n</i> rows. The new cells will be set to the
empty string. The new rows are appended immediately behind the last
existing row. A value of <i class="arg">n</i> equal to or smaller than 0 is not
allowed.</p></dd>
<dt><a name="9"><i class="arg">matrixName</i> <b class="method">cells</b></a></dt>
<dd><p>Returns the number of cells currently managed by the matrix. This is
the product of <b class="method">rows</b> and <b class="method">columns</b>.</p></dd>
<dt><a name="10"><i class="arg">matrixName</i> <b class="method">cellsize</b> <i class="arg">column row</i></a></dt>
<dd><p>Returns the length of the string representation of the value currently
contained in the addressed cell.</p></dd>
<dt><a name="11"><i class="arg">matrixName</i> <b class="method">columns</b></a></dt>
<dd><p>Returns the number of columns currently managed by the matrix.</p></dd>
<dt><a name="12"><i class="arg">matrixName</i> <b class="method">columnwidth</b> <i class="arg">column</i></a></dt>
<dd><p>Returns the length of the longest string representation of all the
values currently contained in the cells of the addressed column if
these are all spanning only one line. For cell values spanning
multiple lines the length of their longest line goes into the
computation.</p>
<p><em>Note:</em> The command recognizes ANSI color control sequences
and excludes them from the width of a line, as they are logically of
zero width.</p></dd>
<dt><a name="13"><i class="arg">matrixName</i> <b class="method">delete column</b> <i class="arg">column</i></a></dt>
<dd><p>Deletes the specified column from the matrix and shifts all columns
with higher indices one index down.</p></dd>
<dt><a name="14"><i class="arg">matrixName</i> <b class="method">delete columns</b> <i class="arg">n</i></a></dt>
<dd><p>Deletes <i class="arg">n</i> columns from the right of the matrix. The value of
<i class="arg">n</i> has to satisfy the constraint
"0 < <i class="arg">n</i> < [<b class="cmd">matrixName</b> <b class="method">columns</b>]"</p></dd>
<dt><a name="15"><i class="arg">matrixName</i> <b class="method">delete row</b> <i class="arg">row</i></a></dt>
<dd><p>Deletes the specified row from the matrix and shifts all row with
higher indices one index down.</p></dd>
<dt><a name="16"><i class="arg">matrixName</i> <b class="method">delete rows</b> <i class="arg">n</i></a></dt>
<dd><p>Deletes <i class="arg">n</i> rows from the bottom of the matrix. The value of
<i class="arg">n</i> has to satisfy the constraint
"0 < <i class="arg">n</i> < [<b class="cmd">matrixName</b> <b class="method">rows</b>]"</p></dd>
<dt><a name="17"><i class="arg">matrixName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces matrix data
in <i class="arg">matrixName</i> with the matrix described by the <i class="arg">serialization</i>
value. The old contents of <i class="arg">matrixName</i> are deleted by this
operation.</p></dd>
<dt><a name="18"><i class="arg">matrixName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the matrix, including its storage space and associated
command.</p></dd>
<dt><a name="19"><i class="arg">matrixName</i> <b class="method">format 2string</b> <span class="opt">?<i class="arg">report</i>?</span></a></dt>
<dd><p>Formats the matrix using the specified report object and returns the
string containing the result of this operation. The report has to
support the <b class="method">printmatrix</b> method. If no <i class="arg">report</i> is
specified the system will use an internal report definition to format
the matrix.</p></dd>
<dt><a name="20"><i class="arg">matrixName</i> <b class="method">format 2chan</b> <span class="opt">?<span class="opt">?<i class="arg">report</i>?</span> <i class="arg">channel</i>?</span></a></dt>
<dd><p>Formats the matrix using the specified report object and writes the
string containing the result of this operation into the channel. The
report has to support the <b class="method">printmatrix2channel</b> method. If no
<i class="arg">report</i> is specified the system will use an internal report
definition to format the matrix. If no <i class="arg">channel</i> is specified the
system will use <b class="const">stdout</b>.</p></dd>
<dt><a name="21"><i class="arg">matrixName</i> <b class="method">get cell</b> <i class="arg">column row</i></a></dt>
<dd><p>Returns the value currently contained in the cell identified by row
and column index.</p></dd>
<dt><a name="22"><i class="arg">matrixName</i> <b class="method">get column</b> <i class="arg">column</i></a></dt>
<dd><p>Returns a list containing the values from all cells in the column
identified by the index. The contents of the cell in row 0 are stored
as the first element of this list.</p></dd>
<dt><a name="23"><i class="arg">matrixName</i> <b class="method">get rect</b> <i class="arg">column_tl row_tl column_br row_br</i></a></dt>
<dd><p>Returns a list of lists of cell values. The values stored in the
result come from the sub-matrix whose top-left and bottom-right cells
are specified by <i class="arg">column_tl, row_tl</i> and
<i class="arg">column_br, row_br</i> resp. Note that the following equations have
to be true: "<i class="arg">column_tl</i> <= <i class="arg">column_br</i>" and "<i class="arg">row_tl</i> <=
<i class="arg">row_br</i>". The result is organized as follows: The outer list is
the list of rows, its elements are lists representing a single
row. The row with the smallest index is the first element of the outer
list. The elements of the row lists represent the selected cell
values. The cell with the smallest index is the first element in each
row list.</p></dd>
<dt><a name="24"><i class="arg">matrixName</i> <b class="method">get row</b> <i class="arg">row</i></a></dt>
<dd><p>Returns a list containing the values from all cells in the row
identified by the index. The contents of the cell in column 0 are
stored as the first element of this list.</p></dd>
<dt><a name="25"><i class="arg">matrixName</i> <b class="method">insert column</b> <i class="arg">column</i> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one column and then acts like <b class="method">set column</b>
(see below) on this new column if there were <i class="arg">values</i>
supplied. Without <i class="arg">values</i> the new cells will be set to the empty
string. The new column is inserted just before the column specified by
the given index. This means, if <i class="arg">column</i> is less than or equal to
zero, then the new column is inserted at the beginning of the matrix,
before the first column. If <i class="arg">column</i> has the value <b class="const">end</b>,
or if it is greater than or equal to the number of columns in the
matrix, then the new column is appended to the matrix, behind the last
column. The old column at the chosen index and all columns with higher
indices are shifted one index upward.</p></dd>
<dt><a name="26"><i class="arg">matrixName</i> <b class="method">insert row</b> <i class="arg">row</i> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one row and then acts like <b class="method">set row</b> (see
below) on this new row if there were <i class="arg">values</i> supplied. Without
<i class="arg">values</i> the new cells will be set to the empty string. The new
row is inserted just before the row specified by the given index. This
means, if <i class="arg">row</i> is less than or equal to zero, then the new row is
inserted at the beginning of the matrix, before the first row. If
<i class="arg">row</i> has the value <b class="const">end</b>, or if it is greater than or
equal to the number of rows in the matrix, then the new row is
appended to the matrix, behind the last row. The old row at that index
and all rows with higher indices are shifted one index upward.</p></dd>
<dt><a name="27"><i class="arg">matrixName</i> <b class="method">link</b> <span class="opt">?-transpose?</span> <i class="arg">arrayvar</i></a></dt>
<dd><p>Links the matrix to the specified array variable. This means that the
contents of all cells in the matrix is stored in the array too, with
all changes to the matrix propagated there too. The contents of the
cell <i class="arg">(column,row)</i> is stored in the array using the key
<i class="arg">column,row</i>. If the option <b class="option">-transpose</b> is specified the
key <i class="arg">row,column</i> will be used instead. It is possible to link the
matrix to more than one array. Note that the link is bidirectional,
i.e. changes to the array are mirrored in the matrix too.</p></dd>
<dt><a name="28"><i class="arg">matrixName</i> <b class="method">links</b></a></dt>
<dd><p>Returns a list containing the names of all array variables the matrix
was linked to through a call to method <b class="method">link</b>.</p></dd>
<dt><a name="29"><i class="arg">matrixName</i> <b class="method">rowheight</b> <i class="arg">row</i></a></dt>
<dd><p>Returns the height of the specified row in lines. This is the highest
number of lines spanned by a cell over all cells in the row.</p></dd>
<dt><a name="30"><i class="arg">matrixName</i> <b class="method">rows</b></a></dt>
<dd><p>Returns the number of rows currently managed by the matrix.</p></dd>
<dt><a name="31"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">all</b> <i class="arg">pattern</i></a></dt>
<dd><p>Searches the whole matrix for cells matching the <i class="arg">pattern</i> and
returns a list with all matches. Each item in the aforementioned list
is a list itself and contains the column and row index of the matching
cell, in this order. The results are ordered by column first and row
second, both times in ascending order. This means that matches to the
left and the top of the matrix come before matches to the right and
down.</p>
<p>The type of the pattern (string, glob, regular expression) is
determined by the option after the <b class="method">search</b> keyword. If no
option is given it defaults to <b class="option">-exact</b>.</p>
<p>If the option <b class="option">-nocase</b> is specified the search will be
case-insensitive.</p></dd>
<dt><a name="32"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">column</b> <i class="arg">column pattern</i></a></dt>
<dd><p>Like <b class="method">search all</b>, but the search is restricted to the
specified column.</p></dd>
<dt><a name="33"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">row</b> <i class="arg">row pattern</i></a></dt>
<dd><p>Like <b class="method">search all</b>, but the search is restricted to the
specified row.</p></dd>
<dt><a name="34"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">rect</b> <i class="arg">column_tl row_tl column_br row_br pattern</i></a></dt>
<dd><p>Like <b class="method">search all</b>, but the search is restricted to the
specified rectangular area of the matrix.</p></dd>
<dt><a name="35"><i class="arg">matrixName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">column_tl row_tl column_br row_br</i>?</span></a></dt>
<dd><p>This method serializes the sub-matrix spanned up by the rectangle
specification. In other words it returns a tcl <em>value</em> completely
describing that matrix. If no rectangle is specified the whole matrix
will be serialized.
This allows, for example, the transfer of matrix objects (or parts
thereof) over arbitrary channels, persistence, etc.
This method is also the basis for both the copy constructor and the
assignment operator.</p>
<p>The result of this method has to be semantically identical over all
implementations of the matrix interface. This is what will enable us
to copy matrix data between different implementations of the same
interface.</p>
<p>The result is a list containing exactly three items.</p>
<p>The first two elements of the list specify the number of rows and
columns of the matrix, in that order. The values integer numbers
greater than or equal to zero.</p>
<p>The last element of the list contains the values of the matrix cells
we have serialized, in the form of a value like it is returned by the
<b class="method">get rect</b>. However empty cells to the right and bottom of
the matrix can be left out of that value as the size information in
the serialization allows the receiver the creation of a matrix with
the proper size despite the missing values.</p>
<pre class="doctools_example">
# A possible serialization for the matrix structure
#
# | a b d g |
# | c e |
# | f |
#
# is
#
# 3 4 {{a b d g} {c e} {f}}
</pre>
</dd>
<dt><a name="36"><i class="arg">matrixName</i> <b class="method">set cell</b> <i class="arg">column row value</i></a></dt>
<dd><p>Sets the value in the cell identified by row and column index to the
data in the third argument.</p></dd>
<dt><a name="37"><i class="arg">matrixName</i> <b class="method">set column</b> <i class="arg">column values</i></a></dt>
<dd><p>Sets the values in the cells identified by the column index to the
elements of the list provided as the third argument. Each element of
the list is assigned to one cell, with the first element going into
the cell in row 0 and then upward. If there are less values in the
list than there are rows the remaining rows are set to the empty
string. If there are more values in the list than there are rows the
superfluous elements are ignored. The matrix is not extended by this
operation.</p></dd>
<dt><a name="38"><i class="arg">matrixName</i> <b class="method">set rect</b> <i class="arg">column row values</i></a></dt>
<dd><p>Takes a list of lists of cell values and writes them into the
submatrix whose top-left cell is specified by the two indices. If the
sublists of the outerlist are not of equal length the shorter sublists
will be filled with empty strings to the length of the longest
sublist. If the submatrix specified by the top-left cell and the
number of rows and columns in the <i class="arg">values</i> extends beyond the
matrix we are modifying the over-extending parts of the values are
ignored, i.e. essentially cut off. This subcommand expects its input
in the format as returned by <b class="method">get rect</b>.</p></dd>
<dt><a name="39"><i class="arg">matrixName</i> <b class="method">set row</b> <i class="arg">row values</i></a></dt>
<dd><p>Sets the values in the cells identified by the row index to the
elements of the list provided as the third argument. Each element of
the list is assigned to one cell, with the first element going into
the cell in column 0 and then upward. If there are less values in the
list than there are columns the remaining columns are set to the empty
string. If there are more values in the list than there are columns
the superfluous elements are ignored. The matrix is not extended by
this operation.</p></dd>
<dt><a name="40"><i class="arg">matrixName</i> <b class="method">sort columns</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">row</i></a></dt>
<dd><p>Sorts the columns in the matrix using the data in the specified
<i class="arg">row</i> as the key to sort by. The options <b class="option">-increasing</b>
and <b class="option">-decreasing</b> have the same meaning as for <b class="cmd">lsort</b>.
If no option is specified <b class="option">-increasing</b> is assumed.</p></dd>
<dt><a name="41"><i class="arg">matrixName</i> <b class="method">sort rows</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">column</i></a></dt>
<dd><p>Sorts the rows in the matrix using the data in the specified
<i class="arg">column</i> as the key to sort by. The options <b class="option">-increasing</b>
and <b class="option">-decreasing</b> have the same meaning as for <b class="cmd">lsort</b>.
If no option is specified <b class="option">-increasing</b> is assumed.</p></dd>
<dt><a name="42"><i class="arg">matrixName</i> <b class="method">swap columns</b> <i class="arg">column_a column_b</i></a></dt>
<dd><p>Swaps the contents of the two specified columns.</p></dd>
<dt><a name="43"><i class="arg">matrixName</i> <b class="method">swap rows</b> <i class="arg">row_a row_b</i></a></dt>
<dd><p>Swaps the contents of the two specified rows.</p></dd>
<dt><a name="44"><i class="arg">matrixName</i> <b class="method">transpose</b></a></dt>
<dd><p>Transposes the contents of the matrix, i.e. swaps rows for columns and
vice versa.</p></dd>
<dt><a name="45"><i class="arg">matrixName</i> <b class="method">unlink</b> <i class="arg">arrayvar</i></a></dt>
<dd><p>Removes the link between the matrix and the specified arrayvariable,
if there is one.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>The examples below assume a 5x5 matrix M with the first row containing
the values 1 to 5, with 1 in the top-left cell. Each other row
contains the contents of the row above it, rotated by one cell to the
right.</p>
<pre class="doctools_example">
% M get rect 0 0 4 4
{{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
</pre>
<pre class="doctools_example">
% M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M get rect 0 0 4 4
{{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
</pre>
<p>Assuming that the style definitions in the example section of the
manpage for the package <b class="package"><a href="../report/report.html">report</a></b> are loaded into the
interpreter now an example which formats a matrix into a tabular
report. The code filling the matrix with data is not shown. contains
useful data.</p>
<pre class="doctools_example">
% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% m format 2string r
+---+-------------------+-------+-------+--------+
|000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok |7 |13 |53.85 |
|002|CATCH return error |68 |91 |74.73 |
|003|CATCH no catch used|7 |14 |50.00 |
|004|IF if true numeric |12 |33 |36.36 |
|005|IF elseif |15 |47 |31.91 |
| |true numeric | | | |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% r printmatrix m
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: matrix</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#matrix">matrix</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002-2013 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/matrix1.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
|
<div class='fossil-doc' data-title='struct::matrix_v1 - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::matrix_v1(n) 1.2.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::matrix_v1 - Create and manipulate matrix objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::matrix <span class="opt">?1.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">matrixName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><i class="arg">matrixName</i> <b class="method">add column</b> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#3"><i class="arg">matrixName</i> <b class="method">add row</b> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#4"><i class="arg">matrixName</i> <b class="method">add columns</b> <i class="arg">n</i></a></li>
<li><a href="#5"><i class="arg">matrixName</i> <b class="method">add rows</b> <i class="arg">n</i></a></li>
<li><a href="#6"><i class="arg">matrixName</i> <b class="method">cells</b></a></li>
<li><a href="#7"><i class="arg">matrixName</i> <b class="method">cellsize</b> <i class="arg">column row</i></a></li>
<li><a href="#8"><i class="arg">matrixName</i> <b class="method">columns</b></a></li>
<li><a href="#9"><i class="arg">matrixName</i> <b class="method">columnwidth</b> <i class="arg">column</i></a></li>
<li><a href="#10"><i class="arg">matrixName</i> <b class="method">delete column</b> <i class="arg">column</i></a></li>
<li><a href="#11"><i class="arg">matrixName</i> <b class="method">delete row</b> <i class="arg">row</i></a></li>
<li><a href="#12"><i class="arg">matrixName</i> <b class="method">destroy</b></a></li>
<li><a href="#13"><i class="arg">matrixName</i> <b class="method">format 2string</b> <span class="opt">?<i class="arg">report</i>?</span></a></li>
<li><a href="#14"><i class="arg">matrixName</i> <b class="method">format 2chan</b> <span class="opt">?<span class="opt">?<i class="arg">report</i>?</span> <i class="arg">channel</i>?</span></a></li>
<li><a href="#15"><i class="arg">matrixName</i> <b class="method">get cell</b> <i class="arg">column row</i></a></li>
<li><a href="#16"><i class="arg">matrixName</i> <b class="method">get column</b> <i class="arg">column</i></a></li>
<li><a href="#17"><i class="arg">matrixName</i> <b class="method">get rect</b> <i class="arg">column_tl row_tl column_br row_br</i></a></li>
<li><a href="#18"><i class="arg">matrixName</i> <b class="method">get row</b> <i class="arg">row</i></a></li>
<li><a href="#19"><i class="arg">matrixName</i> <b class="method">insert column</b> <i class="arg">column</i> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#20"><i class="arg">matrixName</i> <b class="method">insert row</b> <i class="arg">row</i> <span class="opt">?<i class="arg">values</i>?</span></a></li>
<li><a href="#21"><i class="arg">matrixName</i> <b class="method">link</b> <span class="opt">?-transpose?</span> <i class="arg">arrayvar</i></a></li>
<li><a href="#22"><i class="arg">matrixName</i> <b class="method">links</b></a></li>
<li><a href="#23"><i class="arg">matrixName</i> <b class="method">rowheight</b> <i class="arg">row</i></a></li>
<li><a href="#24"><i class="arg">matrixName</i> <b class="method">rows</b></a></li>
<li><a href="#25"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">all</b> <i class="arg">pattern</i></a></li>
<li><a href="#26"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">column</b> <i class="arg">column pattern</i></a></li>
<li><a href="#27"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">row</b> <i class="arg">row pattern</i></a></li>
<li><a href="#28"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">rect</b> <i class="arg">column_tl row_tl column_br row_br pattern</i></a></li>
<li><a href="#29"><i class="arg">matrixName</i> <b class="method">set cell</b> <i class="arg">column row value</i></a></li>
<li><a href="#30"><i class="arg">matrixName</i> <b class="method">set column</b> <i class="arg">column values</i></a></li>
<li><a href="#31"><i class="arg">matrixName</i> <b class="method">set rect</b> <i class="arg">column row values</i></a></li>
<li><a href="#32"><i class="arg">matrixName</i> <b class="method">set row</b> <i class="arg">row values</i></a></li>
<li><a href="#33"><i class="arg">matrixName</i> <b class="method">sort columns</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">row</i></a></li>
<li><a href="#34"><i class="arg">matrixName</i> <b class="method">sort rows</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">column</i></a></li>
<li><a href="#35"><i class="arg">matrixName</i> <b class="method">swap columns</b> <i class="arg">column_a column_b</i></a></li>
<li><a href="#36"><i class="arg">matrixName</i> <b class="method">swap rows</b> <i class="arg">row_a row_b</i></a></li>
<li><a href="#37"><i class="arg">matrixName</i> <b class="method">unlink</b> <i class="arg">arrayvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::matrix</b> command creates a new matrix object with an
associated global Tcl command whose name is <i class="arg">matrixName</i>. This
command may be used to invoke various operations on the matrix. It has
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">matrixName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>A matrix is a rectangular collection of cells, i.e. organized in rows
and columns. Each cell contains exactly one value of arbitrary
form. The cells in the matrix are addressed by pairs of integer
numbers, with the first (left) number in the pair specifying the
column and the second (right) number specifying the row the cell is
in. These indices are counted from 0 upward. The special non-numeric
index <b class="const">end</b> refers to the last row or column in the matrix,
depending on the context. Indices of the form
<b class="const">end</b>-<b class="variable">number</b> are counted from the end of the row or
column, like they are for standard Tcl lists. Trying to access
non-existing cells causes an error.</p>
<p>The matrices here are created empty, i.e. they have neither rows nor
columns. The user then has to add rows and columns as needed by his
application. A specialty of this structure is the ability to export an
array-view onto its contents. Such can be used by tkTable, for
example, to link the matrix into the display.</p>
<p>The following commands are possible for matrix objects:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">matrixName</i> <b class="method">add column</b> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one column and then acts like <b class="method">setcolumn</b>
(see below) on this new column if there were <i class="arg">values</i>
supplied. Without <i class="arg">values</i> the new cells will be set to the empty
string. The new column is appended immediately behind the last
existing column.</p></dd>
<dt><a name="3"><i class="arg">matrixName</i> <b class="method">add row</b> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one row and then acts like <b class="method">setrow</b> (see
below) on this new row if there were <i class="arg">values</i> supplied. Without
<i class="arg">values</i> the new cells will be set to the empty string. The new
row is appended immediately behind the last existing row.</p></dd>
<dt><a name="4"><i class="arg">matrixName</i> <b class="method">add columns</b> <i class="arg">n</i></a></dt>
<dd><p>Extends the matrix by <i class="arg">n</i> columns. The new cells will be set to
the empty string. The new columns are appended immediately behind the
last existing column. A value of <i class="arg">n</i> equal to or smaller than 0 is
not allowed.</p></dd>
<dt><a name="5"><i class="arg">matrixName</i> <b class="method">add rows</b> <i class="arg">n</i></a></dt>
<dd><p>Extends the matrix by <i class="arg">n</i> rows. The new cells will be set to the
empty string. The new rows are appended immediately behind the last
existing row. A value of <i class="arg">n</i> equal to or smaller than 0 is not
allowed.</p></dd>
<dt><a name="6"><i class="arg">matrixName</i> <b class="method">cells</b></a></dt>
<dd><p>Returns the number of cells currently managed by the matrix. This is
the product of <b class="method">rows</b> and <b class="method">columns</b>.</p></dd>
<dt><a name="7"><i class="arg">matrixName</i> <b class="method">cellsize</b> <i class="arg">column row</i></a></dt>
<dd><p>Returns the length of the string representation of the value currently
contained in the addressed cell.</p></dd>
<dt><a name="8"><i class="arg">matrixName</i> <b class="method">columns</b></a></dt>
<dd><p>Returns the number of columns currently managed by the matrix.</p></dd>
<dt><a name="9"><i class="arg">matrixName</i> <b class="method">columnwidth</b> <i class="arg">column</i></a></dt>
<dd><p>Returns the length of the longest string representation of all the
values currently contained in the cells of the addressed column if
these are all spanning only one line. For cell values spanning
multiple lines the length of their longest line goes into the
computation.</p></dd>
<dt><a name="10"><i class="arg">matrixName</i> <b class="method">delete column</b> <i class="arg">column</i></a></dt>
<dd><p>Deletes the specified column from the matrix and shifts all columns
with higher indices one index down.</p></dd>
<dt><a name="11"><i class="arg">matrixName</i> <b class="method">delete row</b> <i class="arg">row</i></a></dt>
<dd><p>Deletes the specified row from the matrix and shifts all row with
higher indices one index down.</p></dd>
<dt><a name="12"><i class="arg">matrixName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroys the matrix, including its storage space and associated
command.</p></dd>
<dt><a name="13"><i class="arg">matrixName</i> <b class="method">format 2string</b> <span class="opt">?<i class="arg">report</i>?</span></a></dt>
<dd><p>Formats the matrix using the specified report object and returns the
string containing the result of this operation. The report has to
support the <b class="method">printmatrix</b> method. If no <i class="arg">report</i> is
specified the system will use an internal report definition to format
the matrix.</p></dd>
<dt><a name="14"><i class="arg">matrixName</i> <b class="method">format 2chan</b> <span class="opt">?<span class="opt">?<i class="arg">report</i>?</span> <i class="arg">channel</i>?</span></a></dt>
<dd><p>Formats the matrix using the specified report object and writes the
string containing the result of this operation into the channel. The
report has to support the <b class="method">printmatrix2channel</b> method. If no
<i class="arg">report</i> is specified the system will use an internal report
definition to format the matrix. If no <i class="arg">channel</i> is specified the
system will use <b class="const">stdout</b>.</p></dd>
<dt><a name="15"><i class="arg">matrixName</i> <b class="method">get cell</b> <i class="arg">column row</i></a></dt>
<dd><p>Returns the value currently contained in the cell identified by row
and column index.</p></dd>
<dt><a name="16"><i class="arg">matrixName</i> <b class="method">get column</b> <i class="arg">column</i></a></dt>
<dd><p>Returns a list containing the values from all cells in the column
identified by the index. The contents of the cell in row 0 are stored
as the first element of this list.</p></dd>
<dt><a name="17"><i class="arg">matrixName</i> <b class="method">get rect</b> <i class="arg">column_tl row_tl column_br row_br</i></a></dt>
<dd><p>Returns a list of lists of cell values. The values stored in the
result come from the sub-matrix whose top-left and bottom-right cells
are specified by <i class="arg">column_tl, row_tl</i> and
<i class="arg">column_br, row_br</i> resp. Note that the following equations have
to be true: "<i class="arg">column_tl</i> <= <i class="arg">column_br</i>" and "<i class="arg">row_tl</i> <=
<i class="arg">row_br</i>". The result is organized as follows: The outer list is
the list of rows, its elements are lists representing a single
row. The row with the smallest index is the first element of the outer
list. The elements of the row lists represent the selected cell
values. The cell with the smallest index is the first element in each
row list.</p></dd>
<dt><a name="18"><i class="arg">matrixName</i> <b class="method">get row</b> <i class="arg">row</i></a></dt>
<dd><p>Returns a list containing the values from all cells in the row
identified by the index. The contents of the cell in column 0 are
stored as the first element of this list.</p></dd>
<dt><a name="19"><i class="arg">matrixName</i> <b class="method">insert column</b> <i class="arg">column</i> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one column and then acts like <b class="method">setcolumn</b>
(see below) on this new column if there were <i class="arg">values</i>
supplied. Without <i class="arg">values</i> the new cells will be set to the empty
string. The new column is inserted just before the column specified by
the given index. This means, if <i class="arg">column</i> is less than or equal to
zero, then the new column is inserted at the beginning of the matrix,
before the first column. If <i class="arg">column</i> has the value <b class="const">end</b>,
or if it is greater than or equal to the number of columns in the
matrix, then the new column is appended to the matrix, behind the last
column. The old column at the chosen index and all columns with higher
indices are shifted one index upward.</p></dd>
<dt><a name="20"><i class="arg">matrixName</i> <b class="method">insert row</b> <i class="arg">row</i> <span class="opt">?<i class="arg">values</i>?</span></a></dt>
<dd><p>Extends the matrix by one row and then acts like <b class="method">setrow</b> (see
below) on this new row if there were <i class="arg">values</i> supplied. Without
<i class="arg">values</i> the new cells will be set to the empty string. The new
row is inserted just before the row specified by the given index. This
means, if <i class="arg">row</i> is less than or equal to zero, then the new row is
inserted at the beginning of the matrix, before the first row. If
<i class="arg">row</i> has the value <b class="const">end</b>, or if it is greater than or
equal to the number of rows in the matrix, then the new row is
appended to the matrix, behind the last row. The old row at that index
and all rows with higher indices are shifted one index upward.</p></dd>
<dt><a name="21"><i class="arg">matrixName</i> <b class="method">link</b> <span class="opt">?-transpose?</span> <i class="arg">arrayvar</i></a></dt>
<dd><p>Links the matrix to the specified array variable. This means that the
contents of all cells in the matrix is stored in the array too, with
all changes to the matrix propagated there too. The contents of the
cell <i class="arg">(column,row)</i> is stored in the array using the key
<i class="arg">column,row</i>. If the option <b class="option">-transpose</b> is specified the
key <i class="arg">row,column</i> will be used instead. It is possible to link the
matrix to more than one array. Note that the link is bidirectional,
i.e. changes to the array are mirrored in the matrix too.</p></dd>
<dt><a name="22"><i class="arg">matrixName</i> <b class="method">links</b></a></dt>
<dd><p>Returns a list containing the names of all array variables the matrix
was linked to through a call to method <b class="method">link</b>.</p></dd>
<dt><a name="23"><i class="arg">matrixName</i> <b class="method">rowheight</b> <i class="arg">row</i></a></dt>
<dd><p>Returns the height of the specified row in lines. This is the highest
number of lines spanned by a cell over all cells in the row.</p></dd>
<dt><a name="24"><i class="arg">matrixName</i> <b class="method">rows</b></a></dt>
<dd><p>Returns the number of rows currently managed by the matrix.</p></dd>
<dt><a name="25"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">all</b> <i class="arg">pattern</i></a></dt>
<dd><p>Searches the whole matrix for cells matching the <i class="arg">pattern</i> and
returns a list with all matches. Each item in the aforementioned list
is a list itself and contains the column and row index of the matching
cell, in this order. The results are ordered by column first and row
second, both times in ascending order. This means that matches to the
left and the top of the matrix come before matches to the right and
down.</p>
<p>The type of the pattern (string, glob, regular expression) is
determined by the option after the <b class="method">search</b> keyword. If no
option is given it defaults to <b class="option">-exact</b>.</p>
<p>If the option <b class="option">-nocase</b> is specified the search will be
case-insensitive.</p></dd>
<dt><a name="26"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">column</b> <i class="arg">column pattern</i></a></dt>
<dd><p>Like <b class="method">search all</b>, but the search is restricted to the
specified column.</p></dd>
<dt><a name="27"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">row</b> <i class="arg">row pattern</i></a></dt>
<dd><p>Like <b class="method">search all</b>, but the search is restricted to the
specified row.</p></dd>
<dt><a name="28"><i class="arg">matrixName</i> <b class="method">search</b> <span class="opt">?-nocase?</span> <span class="opt">?-exact|-glob|-regexp?</span> <b class="method">rect</b> <i class="arg">column_tl row_tl column_br row_br pattern</i></a></dt>
<dd><p>Like <b class="method">search all</b>, but the search is restricted to the
specified rectangular area of the matrix.</p></dd>
<dt><a name="29"><i class="arg">matrixName</i> <b class="method">set cell</b> <i class="arg">column row value</i></a></dt>
<dd><p>Sets the value in the cell identified by row and column index to the
data in the third argument.</p></dd>
<dt><a name="30"><i class="arg">matrixName</i> <b class="method">set column</b> <i class="arg">column values</i></a></dt>
<dd><p>Sets the values in the cells identified by the column index to the
elements of the list provided as the third argument. Each element of
the list is assigned to one cell, with the first element going into
the cell in row 0 and then upward. If there are less values in the
list than there are rows the remaining rows are set to the empty
string. If there are more values in the list than there are rows the
superfluous elements are ignored. The matrix is not extended by this
operation.</p></dd>
<dt><a name="31"><i class="arg">matrixName</i> <b class="method">set rect</b> <i class="arg">column row values</i></a></dt>
<dd><p>Takes a list of lists of cell values and writes them into the
submatrix whose top-left cell is specified by the two indices. If the
sublists of the outerlist are not of equal length the shorter sublists
will be filled with empty strings to the length of the longest
sublist. If the submatrix specified by the top-left cell and the
number of rows and columns in the <i class="arg">values</i> extends beyond the
matrix we are modifying the over-extending parts of the values are
ignored, i.e. essentially cut off. This subcommand expects its input
in the format as returned by <b class="method">getrect</b>.</p></dd>
<dt><a name="32"><i class="arg">matrixName</i> <b class="method">set row</b> <i class="arg">row values</i></a></dt>
<dd><p>Sets the values in the cells identified by the row index to the
elements of the list provided as the third argument. Each element of
the list is assigned to one cell, with the first element going into
the cell in column 0 and then upward. If there are less values in the
list than there are columns the remaining columns are set to the empty
string. If there are more values in the list than there are columns
the superfluous elements are ignored. The matrix is not extended by
this operation.</p></dd>
<dt><a name="33"><i class="arg">matrixName</i> <b class="method">sort columns</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">row</i></a></dt>
<dd><p>Sorts the columns in the matrix using the data in the specified
<i class="arg">row</i> as the key to sort by. The options <b class="option">-increasing</b>
and <b class="option">-decreasing</b> have the same meaning as for <b class="cmd">lsort</b>.
If no option is specified <b class="option">-increasing</b> is assumed.</p></dd>
<dt><a name="34"><i class="arg">matrixName</i> <b class="method">sort rows</b> <span class="opt">?<b class="option">-increasing</b>|<b class="option">-decreasing</b>?</span> <i class="arg">column</i></a></dt>
<dd><p>Sorts the rows in the matrix using the data in the specified
<i class="arg">column</i> as the key to sort by. The options <b class="option">-increasing</b>
and <b class="option">-decreasing</b> have the same meaning as for <b class="cmd">lsort</b>.
If no option is specified <b class="option">-increasing</b> is assumed.</p></dd>
<dt><a name="35"><i class="arg">matrixName</i> <b class="method">swap columns</b> <i class="arg">column_a column_b</i></a></dt>
<dd><p>Swaps the contents of the two specified columns.</p></dd>
<dt><a name="36"><i class="arg">matrixName</i> <b class="method">swap rows</b> <i class="arg">row_a row_b</i></a></dt>
<dd><p>Swaps the contents of the two specified rows.</p></dd>
<dt><a name="37"><i class="arg">matrixName</i> <b class="method">unlink</b> <i class="arg">arrayvar</i></a></dt>
<dd><p>Removes the link between the matrix and the specified arrayvariable,
if there is one.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>The examples below assume a 5x5 matrix M with the first row containing
the values 1 to 5, with 1 in the top-left cell. Each other row
contains the contents of the row above it, rotated by one cell to the
right.</p>
<pre class="doctools_example">
% M getrect 0 0 4 4
{{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
</pre>
<pre class="doctools_example">
% M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
% M getrect 0 0 4 4
{{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
</pre>
<p>Assuming that the style definitions in the example section of the
manpage for the package <b class="package"><a href="../report/report.html">report</a></b> are loaded into the
interpreter now an example which formats a matrix into a tabular
report. The code filling the matrix with data is not shown. contains
useful data.</p>
<pre class="doctools_example">
% ::struct::matrix m
% # ... fill m with data, assume 5 columns
% ::report::report r 5 style captionedtable 1
% m format 2string r
+---+-------------------+-------+-------+--------+
|000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%|
+---+-------------------+-------+-------+--------+
|001|CATCH return ok |7 |13 |53.85 |
|002|CATCH return error |68 |91 |74.73 |
|003|CATCH no catch used|7 |14 |50.00 |
|004|IF if true numeric |12 |33 |36.36 |
|005|IF elseif |15 |47 |31.91 |
| |true numeric | | | |
+---+-------------------+-------+-------+--------+
%
% # alternate way of doing the above
% r printmatrix m
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: matrix</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#matrix">matrix</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/pool.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
|
<div class='fossil-doc' data-title='struct::pool - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::pool(n) 1.2.3 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::pool - Create and manipulate pool objects (of discrete items)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">POOLS AND ALLOCATION</a></li>
<li class="doctools_section"><a href="#section3">ITEMS</a></li>
<li class="doctools_section"><a href="#section4">POOL OBJECT COMMAND</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::pool <span class="opt">?1.2.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::pool</b> <span class="opt">?<i class="arg">poolName</i>?</span> <span class="opt">?<i class="arg">maxsize</i>?</span></a></li>
<li><a href="#2"><b class="cmd">poolName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">poolName</i> <b class="method">add</b> <i class="arg">itemName1</i> <span class="opt">?<i class="arg">itemName2 itemName3 ...</i>?</span></a></li>
<li><a href="#4"><i class="arg">poolName</i> <b class="method">clear</b> <span class="opt">?<b class="option">-force</b>?</span></a></li>
<li><a href="#5"><i class="arg">poolName</i> <b class="method">destroy</b> <span class="opt">?<b class="option">-force</b>?</span></a></li>
<li><a href="#6"><i class="arg">poolName</i> <b class="method">info</b> <i class="arg">type</i> <span class="opt">?<i class="arg">arg</i>?</span></a></li>
<li><a href="#7"><i class="arg">poolName</i> <b class="method">maxsize</b> <span class="opt">?<i class="arg">maxsize</i>?</span></a></li>
<li><a href="#8"><i class="arg">poolName</i> <b class="method">release</b> <i class="arg">itemName</i></a></li>
<li><a href="#9"><i class="arg">poolName</i> <b class="method">remove</b> <i class="arg">itemName</i> <span class="opt">?<b class="option">-force</b>?</span></a></li>
<li><a href="#10"><i class="arg">poolName</i> <b class="method">request</b> itemVar <span class="opt">?options?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides pool objects which can be used to manage
finite collections of discrete items.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::pool</b> <span class="opt">?<i class="arg">poolName</i>?</span> <span class="opt">?<i class="arg">maxsize</i>?</span></a></dt>
<dd><p>Creates a new pool object. If no <i class="arg">poolName</i> is supplied, then the
new pool will be named pool<b class="variable">X</b>, where X is a positive integer.
The optional second argument <i class="arg">maxsize</i> has to be a positive
integer indicating the maximum size of the pool; this is the maximum
number of items the pool may hold. The default for this value is
<b class="const">10</b>.</p>
<p>The pool object has an associated global Tcl command whose name is
<i class="arg">poolName</i>. This command may be used to invoke various
configuration operations on the report. It has the following general
form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">poolName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. See section <span class="sectref"><a href="#section4">POOL OBJECT COMMAND</a></span> for a detailed
list of options and their behaviour.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">POOLS AND ALLOCATION</a></h2>
<p>The purpose of the pool command and the pool object command that it
generates, is to manage pools of discrete items.
Examples of a pool of discrete items are:</p>
<ul class="doctools_itemized">
<li><p>the seats in a cinema, theatre, train etc.. for which visitors/travelers can make a reservation;</p></li>
<li><p>the dynamic IP-addresses that an ISP can dole out to subscribers;</p></li>
<li><p>a car rental's collection of cars, which can be rented by customers;</p></li>
<li><p>the class rooms in a school building, which need to be scheduled;</p></li>
<li><p>the database connections available to client-threads in a web-server application;</p></li>
<li><p>the books in a library that customers can borrow;</p></li>
<li><p>etc ...</p></li>
</ul>
<p>The common denominator in the examples is that there is a more or less
fixed number of items (seats, IP-addresses, cars, ...) that are
supposed to be allocated on a more or less regular basis. An item can
be allocated only once at a time. An item that is allocated, must be
released before it can be re-allocated. While several items in a pool
are being allocated and released continuously, the total number of
items in the pool remains constant.</p>
<p>Keeping track of which items are allocated, and by whom, is the
purpose of the pool command and its subordinates.</p>
<p><em>Pool parlance</em>: If we say that an item is
<i class="term">allocated</i>, it means that the item is <i class="term">busy</i>,
<i class="term">owned</i> or <i class="term">occupied</i>; it is not available anymore. If
an item is <i class="term">free</i>, it is <i class="term">available</i>. Deallocating an
item is equivalent to setting free or releasing an item. The person or
entity to which the item has been allotted is said to own the item.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">ITEMS</a></h2>
<p><em>Discrete items</em></p>
<p>The <b class="cmd"><a href="../../../../index.html#pool">pool</a></b> command is designed for
<em>discrete items only</em>. Note that there are pools where
allocation occurs on a non-discrete basis, for example computer
memory. There are also pools from which the shares that are doled out
are not expected to be returned, for example a charity fund or a pan
of soup from which you may receive a portion. Finally, there are even
pools from which nothing is ever allocated or returned, like a
swimming pool or a cesspool.</p>
<p><em>Unique item names</em></p>
<p>A pool cannot manage duplicate item names. Therefore, items in a pool
must have unique names.</p>
<p><em>Item equivalence</em></p>
<p>From the point of view of the manager of a pool, items are
equivalent. The manager of a pool is indifferent about which
entity/person occupies a given item. However, clients may have
preferences for a particular item, based on some item property they
know.</p>
<p><em>Preferences</em></p>
<p>A future owner may have a preference for a particular item. Preference
based allocation is supported (see the <b class="option">-prefer</b> option to the
request subcommand). A preference for a particular item is most likely
to result from variability among features associated with the
items. Note that the pool commands themselves are not designed to
manage such item properties. If item properties play a role in an
application, they should be managed separately.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">POOL OBJECT COMMAND</a></h2>
<p>The following subcommands and corresponding arguments are available to
any pool object command.</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">poolName</i> <b class="method">add</b> <i class="arg">itemName1</i> <span class="opt">?<i class="arg">itemName2 itemName3 ...</i>?</span></a></dt>
<dd><p>This command adds the items on the command line to the pool. If
duplicate item names occur on the command line, an error is raised. If
one or more of the items already exist in the pool, this also is
considered an error.</p></dd>
<dt><a name="4"><i class="arg">poolName</i> <b class="method">clear</b> <span class="opt">?<b class="option">-force</b>?</span></a></dt>
<dd><p>Removes all items from the pool. If there are any allocated items at
the time when the command is invoked, an error is raised. This
behaviour may be modified through the <b class="option">-force</b> argument. If it
is supplied on the command line, the pool will be cleared regardless
the allocation state of its items.</p></dd>
<dt><a name="5"><i class="arg">poolName</i> <b class="method">destroy</b> <span class="opt">?<b class="option">-force</b>?</span></a></dt>
<dd><p>Destroys the pool data structure, all associated variables and the
associated pool object command. By default, the command checks whether
any items are still allocated and raises an error if such is the
case. This behaviour may be modified through the argument
<b class="option">-force</b>. If it is supplied on the command line, the pool data
structure will be destroyed regardless allocation state of its items.</p></dd>
<dt><a name="6"><i class="arg">poolName</i> <b class="method">info</b> <i class="arg">type</i> <span class="opt">?<i class="arg">arg</i>?</span></a></dt>
<dd><p>Returns various information about the pool for further programmatic
use. The <i class="arg">type</i> argument indicates the type of information
requested. Only the type <b class="const">allocID</b> uses an additional argument.</p>
<dl class="doctools_definitions">
<dt><b class="const">allocID</b> <i class="arg">itemName</i></dt>
<dd><p>returns the allocID of the item whose name is <i class="arg">itemName</i>. Free
items have an allocation id of <b class="const">-1</b>.</p></dd>
<dt><b class="const">allitems</b></dt>
<dd><p>returns a list of all items in the pool.</p></dd>
<dt><b class="const">allocstate</b></dt>
<dd><p>Returns a list of key-value pairs, where the keys are the items and
the values are the corresponding allocation id's. Free items have an
allocation id of <b class="const">-1</b>.</p></dd>
<dt><b class="const">cursize</b></dt>
<dd><p>returns the current pool size, i.e. the number of items in the pool.</p></dd>
<dt><b class="const">freeitems</b></dt>
<dd><p>returns a list of items that currently are not allocated.</p></dd>
<dt><b class="const">maxsize</b></dt>
<dd><p>returns the maximum size of the pool.</p></dd>
</dl></dd>
<dt><a name="7"><i class="arg">poolName</i> <b class="method">maxsize</b> <span class="opt">?<i class="arg">maxsize</i>?</span></a></dt>
<dd><p>Sets or queries the maximum size of the pool, depending on whether the
<i class="arg">maxsize</i> argument is supplied or not. If <i class="arg">maxsize</i> is
supplied, the maximum size of the pool will be set to that value. If
no argument is supplied, the current maximum size of the pool is
returned. In this variant, the command is an alias for:</p>
<p><b class="cmd">poolName info maxsize</b>.</p>
<p>The <i class="arg">maxsize</i> argument has to be a positive integer.</p></dd>
<dt><a name="8"><i class="arg">poolName</i> <b class="method">release</b> <i class="arg">itemName</i></a></dt>
<dd><p>Releases the item whose name is <i class="arg">itemName</i> that was allocated
previously. An error is raised if the item was not allocated at the
time when the command was issued.</p></dd>
<dt><a name="9"><i class="arg">poolName</i> <b class="method">remove</b> <i class="arg">itemName</i> <span class="opt">?<b class="option">-force</b>?</span></a></dt>
<dd><p>Removes the item whose name is <i class="arg">itemName</i> from the pool. If the
item was allocated at the time when the command was invoked, an error
is raised. This behaviour may be modified through the optional
argument <b class="option">-force</b>. If it is supplied on the command line, the
item will be removed regardless its allocation state.</p></dd>
<dt><a name="10"><i class="arg">poolName</i> <b class="method">request</b> itemVar <span class="opt">?options?</span></a></dt>
<dd><p>Handles a request for an item, taking into account a possible
preference for a particular item. There are two possible outcomes
depending on the availability of items:</p>
<ol class="doctools_enumerated">
<li><p>The request is honoured, an item is allocated and the variable whose
name is passed with the argument <i class="arg">itemVar</i> will be set to the name
of the item that was allocated. The command returns 1.</p></li>
<li><p>The request is denied. No item is allocated. The variable whose name
is itemVar is not set. Attempts to read <i class="arg">itemVar</i> may raise an
error if the variable was not defined before issuing the request. The
command returns 0.</p></li>
</ol>
<p>The return values from this command are meant to be inspected. The
examples below show how to do this. Failure to check the return value
may result in erroneous behaviour. If no preference for a particular
item is supplied through the option <b class="option">-prefer</b> (see below), then
all requests are honoured as long as items are available.</p>
<p>The following options are supported:</p>
<dl class="doctools_definitions">
<dt><b class="option">-allocID</b> <i class="arg">allocID</i></dt>
<dd><p>If the request is honoured, an item will be allocated to the entity
identified by allocID. If the allocation state of an item is queried,
it is this allocation ID that will be returned. If the option
<b class="option">-allocID</b> is not supplied, the item will be given to and owned
by <b class="const">dummyID</b>. Allocation id's may be anything except the value
-1, which is reserved for free items.</p></dd>
<dt><b class="option">-prefer</b> <i class="arg">preferredItem</i></dt>
<dd><p>This option modifies the allocation strategy as follows: If the item
whose name is <i class="arg">preferredItem</i> is not allocated at the time when
the command is invoked, the request is honoured (return value is
1). If the item was allocated at the time when the command was
invoked, the request is denied (return value is 0).</p></dd>
</dl></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>Two examples are provided. The first one mimics a step by step
interactive tclsh session, where each step is explained. The second
example shows the usage in a server application that talks to a
back-end application.</p>
<p><em>Example 1</em></p>
<p>This example presents an interactive tclsh session which considers the
case of a Car rental's collection of cars. Ten steps explain its usage
in chronological order, from the creation of the pool, via the most
important stages in the usage of a pool, to the final destruction.</p>
<p><em>Note aside:</em></p>
<p>In this example, brand names are used to label the various
items. However, a brand name could be regarded as a property of an
item. Because the pool command is not designed to manage properties of
items, they need to be managed separately. In the latter case the
items should be labeled with more neutral names such as: car1, car2,
car3 , etc ... and a separate database or array should hold the brand
names associated with the car labels.</p>
<pre class="doctools_example">
1. Load the package into an interpreter
% package require pool
0.1
2. Create a pool object called `CarPool' with a maximum size of 55 items (cars):
% pool CarPool 55
CarPool
4. Add items to the pool:
% CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen
5. Somebody crashed the Toyota. Remove it from the pool as follows:
% CarPool remove Toyota
6. Acquired a new car for the pool. Add it as follows:
% CarPool add Nissan
7. Check whether the pool was adjusted correctly:
% CarPool info allitems
Trabant Chrysler1 Chrysler2 Volkswagen Nissan
</pre>
<p>Suspend the interactive session temporarily, and show the programmatic
use of the request subcommand:</p>
<pre class="doctools_example">
# Mrs. Swift needs a car. She doesn't have a preference for a
# particular car. We'll issue a request on her behalf as follows:
if { [CarPool request car -allocID "Mrs. Swift"] } {
# request was honoured, process the variable `car'
puts "$car has been allocated to [CarPool info allocID $car]."
} else {
# request was denied
puts "No car available."
}
</pre>
<p>Note how the <b class="cmd">if</b> command uses the value returned by the
<b class="method">request</b> subcommand.</p>
<pre class="doctools_example">
# Suppose Mr. Wiggly has a preference for the Trabant:
if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] } {
# request was honoured, process the variable `car'
puts "$car has been allocated to [CarPool info allocID $car]."
} else {
# request was denied
puts "The Trabant was not available."
}
</pre>
<p>Resume the interactive session:</p>
<pre class="doctools_example">
8. When the car is returned then you can render it available by:
% CarPool release Trabant
9. When done, you delete the pool.
% CarPool destroy
Couldn't destroy `CarPool' because some items are still allocated.
Oops, forgot that Mrs. Swift still occupies a car.
10. We force the destruction of the pool as follows:
% CarPool destroy -force
</pre>
<p><em>Example 2</em></p>
<p>This example describes the case from which the author's need for pool
management originated. It is an example of a server application that
receives requests from client applications. The client requests are
dispatched onto a back-end application before being returned to the
client application. In many cases there are a few equivalent instances
of back-end applications to which a client request may be passed
along. The file descriptors that identify the channels to these
back-end instances make up a pool of connections. A particular
connection may be allocated to just one client request at a time.</p>
<pre class="doctools_example">
# Create the pool of connections (pipes)
set maxpipes 10
pool Pipes $maxpipes
for {set i 0} {$i < $maxpipes} {incr i} {
set fd [open "|backendApplication" w+]
Pipes add $fd
}
# A client request comes in. The request is identified as `clientX'.
# Dispatch it onto an instance of a back-end application
if { [Pipes request fd -allocID clientX] } {
# a connection was allocated
# communicate to the back-end application via the variable `fd'
puts $fd "someInstruction"
# ...... etc.
} else {
# all connections are currently occupied
# store the client request in a queue for later processing,
# or return a 'Server busy' message to the client.
}
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: pool</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#discrete_items">discrete items</a>, <a href="../../../../index.html#finite">finite</a>, <a href="../../../../index.html#pool">pool</a>, <a href="../../../../index.html#struct">struct</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Erik Leunissen <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/prioqueue.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<div class='fossil-doc' data-title='struct::prioqueue - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::prioqueue(n) 1.4 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::prioqueue - Create and manipulate prioqueue objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::prioqueue <span class="opt">?1.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::prioqueue</b> <span class="opt">?<b class="option">-ascii|-dictionary|-integer|-real</b>?</span> <span class="opt">?<i class="arg">prioqueueName</i>?</span></a></li>
<li><a href="#2"><i class="arg">prioqueueName</i> <b class="cmd">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">prioqueueName</i> <b class="cmd">clear</b></a></li>
<li><a href="#4"><i class="arg">prioqueueName</i> <b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <i class="arg">item</i></a></li>
<li><a href="#5"><i class="arg">prioqueueName</i> <b class="cmd">destroy</b></a></li>
<li><a href="#6"><i class="arg">prioqueueName</i> <b class="cmd">get</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#7"><i class="arg">prioqueueName</i> <b class="cmd">peek</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#8"><i class="arg">prioqueueName</i> <b class="cmd">peekpriority</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#9"><i class="arg">prioqueueName</i> <b class="cmd">put</b> <i class="arg">item prio</i> <span class="opt">?<i class="arg">item prio ...</i>?</span></a></li>
<li><a href="#10"><i class="arg">prioqueueName</i> <b class="cmd">size</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a simple priority queue using nested tcl lists.</p>
<p>The command <b class="cmd">::struct::prioqueue</b> creates a new priority queue
with default priority key type <i class="arg">-integer</i>. This means that keys
given to the <b class="method">put</b> subcommand must have this type.</p>
<p>This also sets the priority ordering. For key types <i class="arg">-ascii</i> and
<i class="arg">-dictionary</i> the data is sorted in ascending order (as with
<b class="cmd">lsort</b> <i class="arg">-increasing</i>), thereas for <i class="arg">-integer</i> and
<i class="arg">-real</i> the data is sorted in descending order (as with
<b class="cmd">lsort</b> <i class="arg">-decreasing</i>).</p>
<p>Prioqueue names are unrestricted, but may be recognized as options if
no priority type is given.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::prioqueue</b> <span class="opt">?<b class="option">-ascii|-dictionary|-integer|-real</b>?</span> <span class="opt">?<i class="arg">prioqueueName</i>?</span></a></dt>
<dd><p>The <b class="cmd">::struct::prioqueue</b> command creates a new prioqueue object
with an associated global Tcl command whose name is
<em>prioqueueName</em>. This command may be used to invoke various
operations on the prioqueue. It has the following general form:</p></dd>
<dt><a name="2"><i class="arg">prioqueueName</i> <b class="cmd">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><b class="cmd">option</b> and the <i class="arg">arg</i>s determine the exact behavior of the
command. The following commands are possible for prioqueue objects:</p></dd>
<dt><a name="3"><i class="arg">prioqueueName</i> <b class="cmd">clear</b></a></dt>
<dd><p>Remove all items from the prioqueue.</p></dd>
<dt><a name="4"><i class="arg">prioqueueName</i> <b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <i class="arg">item</i></a></dt>
<dd><p>Remove the selected item from this priority queue.</p></dd>
<dt><a name="5"><i class="arg">prioqueueName</i> <b class="cmd">destroy</b></a></dt>
<dd><p>Destroy the prioqueue, including its storage space and associated
command.</p></dd>
<dt><a name="6"><i class="arg">prioqueueName</i> <b class="cmd">get</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the front <i class="arg">count</i> items of the prioqueue (but not their
priorities) and remove them from the prioqueue.
If <i class="arg">count</i> is not specified, it defaults to 1. If <i class="arg">count</i> is
1, the result is a simple string; otherwise, it is a list. If
specified, <i class="arg">count</i> must be greater than or equal to 1. If there
are no or too few items in the prioqueue, this command will throw an
error.</p></dd>
<dt><a name="7"><i class="arg">prioqueueName</i> <b class="cmd">peek</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the front <i class="arg">count</i> items of the prioqueue (but not their
priorities), without removing them from the prioqueue.
If <i class="arg">count</i> is not specified, it defaults to 1. If <i class="arg">count</i> is
1, the result is a simple string; otherwise, it is a list. If
specified, <i class="arg">count</i> must be greater than or equal to 1. If there
are no or too few items in the queue, this command will throw an
error.</p></dd>
<dt><a name="8"><i class="arg">prioqueueName</i> <b class="cmd">peekpriority</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the front <i class="arg">count</i> items priority keys, without removing
them from the prioqueue.
If <i class="arg">count</i> is not specified, it defaults to 1. If <i class="arg">count</i> is
1, the result is a simple string; otherwise, it is a list. If
specified, <i class="arg">count</i> must be greater than or equal to 1. If there
are no or too few items in the queue, this command will throw an
error.</p></dd>
<dt><a name="9"><i class="arg">prioqueueName</i> <b class="cmd">put</b> <i class="arg">item prio</i> <span class="opt">?<i class="arg">item prio ...</i>?</span></a></dt>
<dd><p>Put the <i class="arg">item</i> or items specified into the prioqueue. <i class="arg">prio</i>
must be a valid priority key for this type of prioqueue, otherwise an
error is thrown and no item is added. Items are inserted at their
priority ranking. Items with equal priority are added in the order
they were added.</p></dd>
<dt><a name="10"><i class="arg">prioqueueName</i> <b class="cmd">size</b></a></dt>
<dd><p>Return the number of items in the prioqueue.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: prioqueue</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ordered_list">ordered list</a>, <a href="../../../../index.html#prioqueue">prioqueue</a>, <a href="../../../../index.html#priority_queue">priority queue</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003 Michael Schlenker <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/queue.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
<div class='fossil-doc' data-title='struct::queue - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::queue(n) 1.4.5 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::queue - Create and manipulate queue objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">struct::queue <span class="opt">?1.4.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><i class="arg">queueName</i> <b class="cmd">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><i class="arg">queueName</i> <b class="cmd">clear</b></a></li>
<li><a href="#3"><i class="arg">queueName</i> <b class="cmd">destroy</b></a></li>
<li><a href="#4"><i class="arg">queueName</i> <b class="cmd">get</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#5"><i class="arg">queueName</i> <b class="cmd">peek</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#6"><i class="arg">queueName</i> <b class="cmd">put</b> <i class="arg">item</i> <span class="opt">?<i class="arg">item ...</i>?</span></a></li>
<li><a href="#7"><i class="arg">queueName</i> <b class="cmd">unget</b> <i class="arg">item</i></a></li>
<li><a href="#8"><i class="arg">queueName</i> <b class="cmd">size</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="namespace">::struct</b> namespace contains a commands for processing
finite queues.</p>
<p>It exports a single command, <b class="cmd">::struct::queue</b>. All functionality
provided here can be reached through a subcommand of this command.</p>
<p><em>Note:</em> As of version 1.4.1 of this package a critcl based C
implementation is available. This implementation however requires Tcl
8.4 to run.</p>
<p>The <b class="cmd">::struct::queue</b> command creates a new queue object with an
associated global Tcl command whose name is <em>queueName</em>. This
command may be used to invoke various operations on the queue. It has
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="1"><i class="arg">queueName</i> <b class="cmd">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. The following commands are possible for queue objects:</p></dd>
<dt><a name="2"><i class="arg">queueName</i> <b class="cmd">clear</b></a></dt>
<dd><p>Remove all items from the queue.</p></dd>
<dt><a name="3"><i class="arg">queueName</i> <b class="cmd">destroy</b></a></dt>
<dd><p>Destroy the queue, including its storage space and associated command.</p></dd>
<dt><a name="4"><i class="arg">queueName</i> <b class="cmd">get</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the front <i class="arg">count</i> items of the queue and remove them from
the queue. If <i class="arg">count</i> is not specified, it defaults to 1. If
<i class="arg">count</i> is 1, the result is a simple string; otherwise, it is a
list. If specified, <i class="arg">count</i> must be greater than or equal to 1.
If there are not enough items in the queue to fulfull the request,
this command will throw an error.</p></dd>
<dt><a name="5"><i class="arg">queueName</i> <b class="cmd">peek</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the front <i class="arg">count</i> items of the queue, without removing them
from the queue. If <i class="arg">count</i> is not specified, it defaults to 1.
If <i class="arg">count</i> is 1, the result is a simple string; otherwise, it is a
list. If specified, <i class="arg">count</i> must be greater than or equal to 1.
If there are not enough items in the queue to fulfull the request,
this command will throw an error.</p></dd>
<dt><a name="6"><i class="arg">queueName</i> <b class="cmd">put</b> <i class="arg">item</i> <span class="opt">?<i class="arg">item ...</i>?</span></a></dt>
<dd><p>Put the <i class="arg">item</i> or items specified into the queue. If more than
one <i class="arg">item</i> is given, they will be added in the order they are
listed.</p></dd>
<dt><a name="7"><i class="arg">queueName</i> <b class="cmd">unget</b> <i class="arg">item</i></a></dt>
<dd><p>Put the <i class="arg">item</i> into the queue, at the front, i.e. before any other
items already in the queue. This makes this operation the complement
to the method <b class="method">get</b>.</p></dd>
<dt><a name="8"><i class="arg">queueName</i> <b class="cmd">size</b></a></dt>
<dd><p>Return the number of items in the queue.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: queue</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#graph">graph</a>, <a href="../../../../index.html#list">list</a>, <a href="../../../../index.html#matrix">matrix</a>, <a href="../../../../index.html#pool">pool</a>, <a href="../../../../index.html#prioqueue">prioqueue</a>, <a href="../../../../index.html#record">record</a>, <a href="../../../../index.html#set">set</a>, <a href="../../../../index.html#skiplist">skiplist</a>, <a href="../../../../index.html#stack">stack</a>, <a href="../../../../index.html#tree">tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/record.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
|
<div class='fossil-doc' data-title='struct::record - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::record(n) 1.2.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::record - Define and create records (similar to 'C' structures)</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">RECORD MEMBERS</a></li>
<li class="doctools_section"><a href="#section3">RECORD COMMAND</a></li>
<li class="doctools_section"><a href="#section4">INSTANCE COMMAND</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::record <span class="opt">?1.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">record define</b> <i class="arg">recordName</i> <i class="arg">recordMembers</i> <span class="opt">?<i class="arg">instanceName1 instanceName2 ...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">record show</b> <i class="arg">record</i></a></li>
<li><a href="#3"><b class="cmd">record show</b> <i class="arg">instances</i> <i class="arg">recordName</i></a></li>
<li><a href="#4"><b class="cmd">record show</b> <i class="arg">members</i> <i class="arg">recordName</i></a></li>
<li><a href="#5"><b class="cmd">record show</b> <i class="arg">values</i> <i class="arg">instanceName</i></a></li>
<li><a href="#6"><b class="cmd">record exists</b> <i class="arg">record</i> <i class="arg">recordName</i></a></li>
<li><a href="#7"><b class="cmd">record exists</b> <i class="arg">instance</i> <i class="arg">instanceName</i></a></li>
<li><a href="#8"><b class="cmd">record delete</b> <i class="arg">record</i> <i class="arg">recordName</i></a></li>
<li><a href="#9"><b class="cmd">record delete</b> <i class="arg">instance</i> <i class="arg">instanceName</i></a></li>
<li><a href="#10"><i class="arg">recordName</i> <b class="method"><i class="arg">instanceName|#auto</i></b> <span class="opt">?<i class="arg">-member1 value1 -member2 value2 ...</i>?</span></a></li>
<li><a href="#11"><i class="arg">instanceName</i> <b class="method">cget</b> <span class="opt">?<i class="arg">-member1 -member2 ...</i>?</span></a></li>
<li><a href="#12"><i class="arg">instanceName</i> <b class="method">configure</b> <span class="opt">?<i class="arg">-member1 value1 -member2 value2 ...</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::record</b> package provides a mechanism to group variables together
as one data structure, similar to a 'C' structure. The members of a
record can be variables or other records. However, a record can not contain circular
record, i.e. records that contain the same record as a
member.</p>
<p>This package was structured so that it is very similar to how Tk objects work. Each record
definition creates a record object that encompasses that definition. Subsequently, that
record object can create instances of that record. These instances can then
be manipulated with the <b class="method">cget</b> and <b class="method">configure</b> methods.</p>
<p>The package only contains one top level command, but several sub commands (see below). It also obeys the namespace in which the record was define, hence the objects returned are fully qualified.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">record define</b> <i class="arg">recordName</i> <i class="arg">recordMembers</i> <span class="opt">?<i class="arg">instanceName1 instanceName2 ...</i>?</span></a></dt>
<dd><p>Defines a record. <i class="arg">recordName</i> is the name of the record, and is also
used as an object command. This object command is used to create instances of the
record definition. <i class="arg">recordMembers</i> are the members of
the record that make up the record definition. These are variables
and other record. If optional <i class="arg">instanceName</i> args are given, then an instance
is generated after the definition is created for each <i class="arg">instanceName</i>.</p></dd>
<dt><a name="2"><b class="cmd">record show</b> <i class="arg">record</i></a></dt>
<dd><p>Returns a list of records that have been defined.</p></dd>
<dt><a name="3"><b class="cmd">record show</b> <i class="arg">instances</i> <i class="arg">recordName</i></a></dt>
<dd><p>Returns the instances that have been instantiated by
<i class="arg">recordName</i>.</p></dd>
<dt><a name="4"><b class="cmd">record show</b> <i class="arg">members</i> <i class="arg">recordName</i></a></dt>
<dd><p>Returns the members that are defined for
record <i class="arg">recordName</i>. It returns the same format as how the
records were defined.</p></dd>
<dt><a name="5"><b class="cmd">record show</b> <i class="arg">values</i> <i class="arg">instanceName</i></a></dt>
<dd><p>Returns a list of values that are set for the instance
<i class="arg">instanceName</i>. The output is a list of key/value pairs. If there
are nested records, then the values of the nested records will
itself be a list.</p></dd>
<dt><a name="6"><b class="cmd">record exists</b> <i class="arg">record</i> <i class="arg">recordName</i></a></dt>
<dd><p>Tests for the existence of a <i class="arg">record</i> with the
name <i class="arg">recordName</i>.</p></dd>
<dt><a name="7"><b class="cmd">record exists</b> <i class="arg">instance</i> <i class="arg">instanceName</i></a></dt>
<dd><p>Tests for the existence of a <i class="arg">instance</i> with the
name <i class="arg">instanceName</i>.</p></dd>
<dt><a name="8"><b class="cmd">record delete</b> <i class="arg">record</i> <i class="arg">recordName</i></a></dt>
<dd><p>Deletes <i class="arg">recordName</i>, and all instances of <i class="arg">recordName</i>. It will return
an error if the record does not exist.</p></dd>
<dt><a name="9"><b class="cmd">record delete</b> <i class="arg">instance</i> <i class="arg">instanceName</i></a></dt>
<dd><p>Deletes <i class="arg">instance</i> with the name of <i class="arg">instanceName</i>. It
will return an error if the instance does not exist.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">RECORD MEMBERS</a></h2>
<p>Record members can either be variables, or other records, However, the
same record can not be nested witin itself (circular). To define a
nested record, you need to specify the <b class="const">record</b> keyword, along
the with name of the record, and the name of the instance of that
nested record. For example, it would look like this:</p>
<pre class="doctools_example">
# this is the nested record
record define mynestedrecord {
nest1
nest2
}
# This is the main record
record define myrecord {
mem1
mem2
{record mynestedrecord mem3}
}
</pre>
<p>You can also assign default or initial values to the members of a record,
by enclosing the member entry in braces:</p>
<pre class="doctools_example">
record define myrecord {
mem1
{mem2 5}
}
</pre>
<p>All instances created from this record definition, will initially have 5 as
the value for <i class="arg">mem2</i>. If no default is given, then the value will be the empty string.</p>
<p><em>Getting Values</em></p>
<p>To get a value of a member, there are several ways to do this.</p>
<ol class="doctools_enumerated">
<li><p>To get a member value, then use the instance built-in <b class="method">cget</b> method:</p>
<p><i class="arg">instanceName</i> <b class="method">cget</b> -mem1</p></li>
<li><p>To get multiple member values, you can specify them all in one command:</p>
<p><i class="arg">instanceName</i> <b class="method">cget</b> -mem1 -mem2</p></li>
<li><p>To get a list of the key/value of all of the members, there are 3 ways:</p>
<p>- <i class="arg">instanceName</i> <b class="method">cget</b></p>
<p>- <i class="arg">instanceName</i> <b class="method">configure</b></p>
<p>- <i class="arg">instanceName</i></p></li>
<li><p>To get a value of a nested member, then use the dot notation:</p>
<p><i class="arg">instanceName</i> <b class="method">cget</b> -mem3.nest1</p></li>
</ol>
<p><em>Setting Values</em></p>
<p>To set a value of a member, there are several ways to do this.</p>
<ol class="doctools_enumerated">
<li><p>To set a member value, then use the instance built-in <b class="method">configure</b> method:</p>
<p><i class="arg">instanceName</i> <b class="method">configure</b> -mem1 val1</p></li>
<li><p>To set multiple member values, you can specify them all in one command:</p>
<p><i class="arg">instanceName</i> <b class="method">configure</b> -mem1 va1 -mem2 val2</p></li>
<li><p>To set a value of a nested member, then use the dot notation:</p>
<p><i class="arg">instanceName</i> <b class="method">configure</b> -mem3.nest1 value</p></li>
</ol>
<p><em>Alias access</em></p>
<p>In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed. However,
there was a concensus to make the interface more Tcl like, which made sense. However, the original alias access still
exists. It might prove to be helpful to some.</p>
<p>Basically, for every member of every instance, an alias is created. This alias is used to get and set values for that
member. An example will illustrate the point, using the above defined records:</p>
<pre class="doctools_example">
# Create an instance first
% myrecord inst1
::inst1
% # To get a member of an instance, just use the
% # alias (it behaves like a Tcl command):
% inst1.mem1
%
% # To set a member via the alias, just include
% # a value (optionally the equal sign - syntactic sugar)
% inst1.mem1 = 5
5
% inst1.mem1
5
% # For nested records, just continue with the
% # dot notation (note no equal sign)
% inst1.mem3.nest1 10
10
% inst1.mem3.nest1
10
% # just the instance by itself gives all
% # member/values pairs for that instance
% inst1
-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
% # and to get all members within the nested record
% inst1.mem3
-nest1 10 -nest2 {}
%
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">RECORD COMMAND</a></h2>
<p>The following subcommands and corresponding arguments are available to any
record command:</p>
<dl class="doctools_definitions">
<dt><a name="10"><i class="arg">recordName</i> <b class="method"><i class="arg">instanceName|#auto</i></b> <span class="opt">?<i class="arg">-member1 value1 -member2 value2 ...</i>?</span></a></dt>
<dd><p>Using the <i class="arg">recordName</i> object command that was created from the record definition,
instances of the record definition can be created. Once a instance is
created, then it inherits the members of the record definition, very
similar to how objects work. During instance generation, an object command for the instance
is created as well, using <i class="arg">instanceName</i>. This object command is used
to access the data members of the instance. During the instantiation, values for
that instance can be given, <em>but</em> all values must be given, and be given
in key/value pairs. Nested records, need to be in list format.</p>
<p>Optionally, <i class="arg">#auto</i> can be used in place of <i class="arg">instanceName</i>. When #auto is used,
then a instance name will automatically be generated, of the form recordName<integer>, where
<integer> is a unique integer (starting at 0) that is generated.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">INSTANCE COMMAND</a></h2>
<p>The following subcommands and corresponding arguments are available to
any record instance command:</p>
<dl class="doctools_definitions">
<dt><a name="11"><i class="arg">instanceName</i> <b class="method">cget</b> <span class="opt">?<i class="arg">-member1 -member2 ...</i>?</span></a></dt>
<dd><p>Each instance has the sub command <b class="method">cget</b> associated with it. This
is very similar to how Tk widget's cget command works. It queries
the values of the member for that particular instance. If
no arguments are given, then a key/value list is returned.</p></dd>
<dt><a name="12"><i class="arg">instanceName</i> <b class="method">configure</b> <span class="opt">?<i class="arg">-member1 value1 -member2 value2 ...</i>?</span></a></dt>
<dd><p>Each instance has the sub command <b class="method">configure</b> associated with it. This
is very similar to how Tk widget's configure command works. It sets
the values of the particular member for that particular instance. If
no arguments are given, then a key/value list is returned.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>Two examples are provided to give an good illustration on how to use
this package.</p>
<p><em>Example 1</em></p>
<p>Probably the most obvious example would be to hold contact information,
such as addresses, phone numbers, comments, etc. Since a person can have
multiple phone numbers, multiple email addresses, etc, we will use nested
records to define these. So, the first thing we do is define the nested
records:</p>
<pre class="doctools_example">
##
## This is an interactive example, to see what is
## returned by each command as well.
##
% namespace import ::struct::record::*
% # define a nested record. Notice that country has default 'USA'.
% record define locations {
street
street2
city
state
zipcode
{country USA}
phone
}
::locations
% # Define the main record. Notice that it uses the location record twice.
% record define contacts {
first
middle
last
{record locations home}
{record locations work}
}
::contacts
% # Create an instance for the contacts record.
% contacts cont1
::cont1
% # Display some introspection values
% record show records
::contacts ::locations
% #
% record show values cont1
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% #
% record show instances contacts
::cont1
% #
% cont1 config
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% #
% cont1 cget
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% # copy one record to another record
% record define contacts2 [record show members contacts]
::contacts2
% record show members contacts2
first middle last {record locations home} {record locations work}
% record show members contacts
first middle last {record locations home} {record locations work}
%
</pre>
<p><em>Example 1</em></p>
<p>This next example just illustrates a simple linked list</p>
<pre class="doctools_example">
% # define a very simple record for linked list
% record define llist {
value
next
}
::llist
% llist lstart
::lstart
% lstart config -value 1 -next [llist #auto]
% [lstart cget -next] config -value 2 -next [llist #auto]
% [[lstart cget -next] cget -next] config -value 3 -next "end"
% set next lstart
lstart
% while 1 {
lappend values [$next cget -value]
set next [$next cget -next]
if {[string match "end" $next]} {break}
}
% puts "$values"
1 2 3
% # cleanup linked list
% # We could just use delete record llist also
% foreach I [record show instances llist] {
record delete instance $I
}
% record show instances llist
%
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: record</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_structures">data structures</a>, <a href="../../../../index.html#record">record</a>, <a href="../../../../index.html#struct">struct</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002, Brett Schwarz <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/skiplist.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<div class='fossil-doc' data-title='struct::skiplist - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::skiplist(n) 1.3 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::skiplist - Create and manipulate skiplists</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::skiplist <span class="opt">?1.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">skiplistName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><i class="arg">skiplistName</i> <b class="method">delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i>...?</span></a></li>
<li><a href="#3"><i class="arg">skiplistName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">skiplistName</i> <b class="method">insert</b> <i class="arg">key value</i></a></li>
<li><a href="#5"><i class="arg">skiplistName</i> <b class="method">search</b> <i class="arg">node</i> <span class="opt">?<b class="const">-key</b> <i class="arg">key</i>?</span></a></li>
<li><a href="#6"><i class="arg">skiplistName</i> <b class="method">size</b></a></li>
<li><a href="#7"><i class="arg">skiplistName</i> <b class="method">walk</b> <i class="arg">cmd</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::skiplist</b> command creates a new skiplist object
with an associated global Tcl command whose name is
<i class="arg">skiplistName</i>. This command may be used to invoke various
operations on the skiplist. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">skiplistName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>Skip lists are an alternative data structure to binary trees. They can
be used to maintain ordered lists over any sequence of insertions and
deletions. Skip lists use randomness to achieve probabilistic
balancing, and as a result the algorithms for insertion and deletion
in skip lists are much simpler and faster than those for binary trees.</p>
<p>To read more about skip lists see Pugh, William.
<em>Skip lists: a probabilistic alternative to balanced trees</em>
In: Communications of the ACM, June 1990, 33(6) 668-676.</p>
<p>Currently, the key can be either a number or a string, and comparisons
are performed with the built in greater than operator.
The following commands are possible for skiplist objects:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">skiplistName</i> <b class="method">delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i>...?</span></a></dt>
<dd><p>Remove the specified nodes from the skiplist.</p></dd>
<dt><a name="3"><i class="arg">skiplistName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroy the skiplist, including its storage space and associated command.</p></dd>
<dt><a name="4"><i class="arg">skiplistName</i> <b class="method">insert</b> <i class="arg">key value</i></a></dt>
<dd><p>Insert a node with the given <i class="arg">key</i> and <i class="arg">value</i> into the
skiplist. If a node with that key already exists, then the that node's
value is updated and its node level is returned. Otherwise a new node
is created and 0 is returned.</p></dd>
<dt><a name="5"><i class="arg">skiplistName</i> <b class="method">search</b> <i class="arg">node</i> <span class="opt">?<b class="const">-key</b> <i class="arg">key</i>?</span></a></dt>
<dd><p>Search for a given key in a skiplist. If not found then 0 is returned.
If found, then a two element list of 1 followed by the node's value is retuned.</p></dd>
<dt><a name="6"><i class="arg">skiplistName</i> <b class="method">size</b></a></dt>
<dd><p>Return a count of the number of nodes in the skiplist.</p></dd>
<dt><a name="7"><i class="arg">skiplistName</i> <b class="method">walk</b> <i class="arg">cmd</i></a></dt>
<dd><p>Walk the skiplist from the first node to the last. At each node, the
command <i class="arg">cmd</i> will be evaluated with the key and value of the
current node appended.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: skiplist</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#skiplist">skiplist</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2000 Keith Vetter</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/stack.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<div class='fossil-doc' data-title='struct::stack - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::stack(n) 1.5.3 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::stack - Create and manipulate stack objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">struct::stack <span class="opt">?1.5.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><i class="arg">stackName</i> <b class="cmd">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><i class="arg">stackName</i> <b class="method">clear</b></a></li>
<li><a href="#3"><i class="arg">stackName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">stackName</i> <b class="method">get</b></a></li>
<li><a href="#5"><i class="arg">stackName</i> <b class="method">getr</b></a></li>
<li><a href="#6"><i class="arg">stackName</i> <b class="method">peek</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#7"><i class="arg">stackName</i> <b class="method">peekr</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#8"><i class="arg">stackName</i> <b class="method">trim</b> <span class="opt">?<i class="arg">newsize</i>?</span></a></li>
<li><a href="#9"><i class="arg">stackName</i> <b class="method">trim*</b> <span class="opt">?<i class="arg">newsize</i>?</span></a></li>
<li><a href="#10"><i class="arg">stackName</i> <b class="method">pop</b> <span class="opt">?<i class="arg">count</i>?</span></a></li>
<li><a href="#11"><i class="arg">stackName</i> <b class="method">push</b> <i class="arg">item</i> <span class="opt">?<i class="arg">item...</i>?</span></a></li>
<li><a href="#12"><i class="arg">stackName</i> <b class="method">size</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="namespace">::struct</b> namespace contains a commands for processing
finite stacks.</p>
<p>It exports a single command, <b class="cmd">::struct::stack</b>. All functionality
provided here can be reached through a subcommand of this command.</p>
<p><em>Note:</em> As of version 1.3.3 of this package a critcl based C
implementation is available. This implementation however requires Tcl
8.4 to run.</p>
<p>The <b class="cmd">::struct::stack</b> command creates a new stack object with an
associated global Tcl command whose name is <em>stackName</em>. This
command may be used to invoke various operations on the stack. It has
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="1"><i class="arg">stackName</i> <b class="cmd">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command. The following commands are possible for stack objects:</p></dd>
<dt><a name="2"><i class="arg">stackName</i> <b class="method">clear</b></a></dt>
<dd><p>Remove all items from the stack.</p></dd>
<dt><a name="3"><i class="arg">stackName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroy the stack, including its storage space and associated command.</p></dd>
<dt><a name="4"><i class="arg">stackName</i> <b class="method">get</b></a></dt>
<dd><p>Returns the whole contents of the stack as a list, without removing
them from the stack.</p></dd>
<dt><a name="5"><i class="arg">stackName</i> <b class="method">getr</b></a></dt>
<dd><p>A variant of <b class="method">get</b>, which returns the contents in reversed order.</p></dd>
<dt><a name="6"><i class="arg">stackName</i> <b class="method">peek</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the top <i class="arg">count</i> items of the stack, without removing them from
the stack. If <i class="arg">count</i> is not specified, it defaults to 1. If
<i class="arg">count</i> is 1, the result is a simple string; otherwise, it is a
list. If specified, <i class="arg">count</i> must be greater than or equal to 1.
If there are not enoughs items on the stack to fulfull the request,
this command will throw an error.</p></dd>
<dt><a name="7"><i class="arg">stackName</i> <b class="method">peekr</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>A variant of <b class="method">peek</b>, which returns the items in reversed order.</p></dd>
<dt><a name="8"><i class="arg">stackName</i> <b class="method">trim</b> <span class="opt">?<i class="arg">newsize</i>?</span></a></dt>
<dd><p>Shrinks the stack to contain at most <i class="arg">newsize</i> elements and
returns a list containing the elements which were removed. Nothing is
done if the stack is already at the specified size, or smaller. In
that case the result is the empty list.</p></dd>
<dt><a name="9"><i class="arg">stackName</i> <b class="method">trim*</b> <span class="opt">?<i class="arg">newsize</i>?</span></a></dt>
<dd><p>A variant of <b class="method">trim</b> which performs the shrinking, but does not
return the removed elements.</p></dd>
<dt><a name="10"><i class="arg">stackName</i> <b class="method">pop</b> <span class="opt">?<i class="arg">count</i>?</span></a></dt>
<dd><p>Return the top <i class="arg">count</i> items of the stack, and remove them
from the stack. If <i class="arg">count</i> is not specified, it defaults to 1.
If <i class="arg">count</i> is 1, the result is a simple string; otherwise, it is a
list. If specified, <i class="arg">count</i> must be greater than or equal to 1.
If there are not enoughs items on the stack to fulfull the request,
this command will throw an error.</p></dd>
<dt><a name="11"><i class="arg">stackName</i> <b class="method">push</b> <i class="arg">item</i> <span class="opt">?<i class="arg">item...</i>?</span></a></dt>
<dd><p>Push the <i class="arg">item</i> or items specified onto the stack. If more than
one <i class="arg">item</i> is given, they will be pushed in the order they are
listed.</p></dd>
<dt><a name="12"><i class="arg">stackName</i> <b class="method">size</b></a></dt>
<dd><p>Return the number of items on the stack.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: stack</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#graph">graph</a>, <a href="../../../../index.html#matrix">matrix</a>, <a href="../../../../index.html#queue">queue</a>, <a href="../../../../index.html#tree">tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/struct_list.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
|
<div class='fossil-doc' data-title='struct::list - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::list(n) 1.8.4 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::list - Procedures for manipulating lists</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON</a></li>
<li class="doctools_section"><a href="#section4">TABLE JOIN</a></li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">struct::list <span class="opt">?1.8.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::list</b> <b class="method">longestCommonSubsequence</b> <i class="arg">sequence1</i> <i class="arg">sequence2</i> <span class="opt">?<i class="arg">maxOccurs</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::struct::list</b> <b class="method">longestCommonSubsequence2</b> <i class="arg">sequence1 sequence2</i> <span class="opt">?<i class="arg">maxOccurs</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::struct::list</b> <b class="method">lcsInvert</b> <i class="arg">lcsData</i> <i class="arg">len1</i> <i class="arg">len2</i></a></li>
<li><a href="#4"><b class="cmd">::struct::list</b> <b class="method">lcsInvert2</b> <i class="arg">lcs1</i> <i class="arg">lcs2</i> <i class="arg">len1</i> <i class="arg">len2</i></a></li>
<li><a href="#5"><b class="cmd">::struct::list</b> <b class="method">lcsInvertMerge</b> <i class="arg">lcsData</i> <i class="arg">len1</i> <i class="arg">len2</i></a></li>
<li><a href="#6"><b class="cmd">::struct::list</b> <b class="method">lcsInvertMerge2</b> <i class="arg">lcs1</i> <i class="arg">lcs2</i> <i class="arg">len1</i> <i class="arg">len2</i></a></li>
<li><a href="#7"><b class="cmd">::struct::list</b> <b class="method">reverse</b> <i class="arg">sequence</i></a></li>
<li><a href="#8"><b class="cmd">::struct::list</b> <b class="method">shuffle</b> <i class="arg">list</i></a></li>
<li><a href="#9"><b class="cmd">::struct::list</b> <b class="method">assign</b> <i class="arg">sequence</i> <i class="arg">varname</i> <span class="opt">?<i class="arg">varname</i>?</span>...</a></li>
<li><a href="#10"><b class="cmd">::struct::list</b> <b class="method">flatten</b> <span class="opt">?<b class="option">-full</b>?</span> <span class="opt">?<b class="option">--</b>?</span> <i class="arg">sequence</i></a></li>
<li><a href="#11"><b class="cmd">::struct::list</b> <b class="method">map</b> <i class="arg">sequence</i> <i class="arg">cmdprefix</i></a></li>
<li><a href="#12"><b class="cmd">::struct::list</b> <b class="method">mapfor</b> <i class="arg">var</i> <i class="arg">sequence</i> <i class="arg">script</i></a></li>
<li><a href="#13"><b class="cmd">::struct::list</b> <b class="method">filter</b> <i class="arg">sequence</i> <i class="arg">cmdprefix</i></a></li>
<li><a href="#14"><b class="cmd">::struct::list</b> <b class="method">filterfor</b> <i class="arg">var</i> <i class="arg">sequence</i> <i class="arg">expr</i></a></li>
<li><a href="#15"><b class="cmd">::struct::list</b> <b class="method">split</b> <i class="arg">sequence</i> <i class="arg">cmdprefix</i> <span class="opt">?<i class="arg">passVar</i> <i class="arg">failVar</i>?</span></a></li>
<li><a href="#16"><b class="cmd">::struct::list</b> <b class="method">fold</b> <i class="arg">sequence</i> <i class="arg">initialvalue</i> <i class="arg">cmdprefix</i></a></li>
<li><a href="#17"><b class="cmd">::struct::list</b> <b class="method">shift</b> <i class="arg">listvar</i></a></li>
<li><a href="#18"><b class="cmd">::struct::list</b> <b class="method">iota</b> <i class="arg">n</i></a></li>
<li><a href="#19"><b class="cmd">::struct::list</b> <b class="method">equal</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#20"><b class="cmd">::struct::list</b> <b class="method">repeat</b> <i class="arg">size</i> <i class="arg">element1</i> <span class="opt">?<i class="arg">element2</i> <i class="arg">element3</i>...?</span></a></li>
<li><a href="#21"><b class="cmd">::struct::list</b> <b class="method">repeatn</b> <i class="arg">value</i> <i class="arg">size</i>...</a></li>
<li><a href="#22"><b class="cmd">::struct::list</b> <b class="method">dbJoin</b> <span class="opt">?<b class="option">-inner</b>|<b class="option">-left</b>|<b class="option">-right</b>|<b class="option">-full</b>?</span> <span class="opt">?<b class="option">-keys</b> <i class="arg">varname</i>?</span> {<i class="arg">keycol</i> <i class="arg">table</i>}...</a></li>
<li><a href="#23"><b class="cmd">::struct::list</b> <b class="method">dbJoinKeyed</b> <span class="opt">?<b class="option">-inner</b>|<b class="option">-left</b>|<b class="option">-right</b>|<b class="option">-full</b>?</span> <span class="opt">?<b class="option">-keys</b> <i class="arg">varname</i>?</span> <i class="arg">table</i>...</a></li>
<li><a href="#24"><b class="cmd">::struct::list</b> <b class="method">swap</b> <i class="arg">listvar</i> <i class="arg">i</i> <i class="arg">j</i></a></li>
<li><a href="#25"><b class="cmd">::struct::list</b> <b class="method">firstperm</b> <i class="arg">list</i></a></li>
<li><a href="#26"><b class="cmd">::struct::list</b> <b class="method">nextperm</b> <i class="arg">perm</i></a></li>
<li><a href="#27"><b class="cmd">::struct::list</b> <b class="method">permutations</b> <i class="arg">list</i></a></li>
<li><a href="#28"><b class="cmd">::struct::list</b> <b class="method">foreachperm</b> <i class="arg">var</i> <i class="arg">list</i> <i class="arg">body</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::list</b> namespace contains several useful commands
for processing Tcl lists. Generally speaking, they implement
algorithms more complex or specialized than the ones provided by Tcl
itself.</p>
<p>It exports only a single command, <b class="cmd">struct::list</b>. All
functionality provided here can be reached through a subcommand of
this command.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::list</b> <b class="method">longestCommonSubsequence</b> <i class="arg">sequence1</i> <i class="arg">sequence2</i> <span class="opt">?<i class="arg">maxOccurs</i>?</span></a></dt>
<dd><p>Returns the longest common subsequence of elements in the two lists
<i class="arg">sequence1</i> and <i class="arg">sequence2</i>. If the <i class="arg">maxOccurs</i> parameter
is provided, the common subsequence is restricted to elements that
occur no more than <i class="arg">maxOccurs</i> times in <i class="arg">sequence2</i>.</p>
<p>The return value is a list of two lists of equal length. The first
sublist is of indices into <i class="arg">sequence1</i>, and the second sublist is
of indices into <i class="arg">sequence2</i>. Each corresponding pair of indices
corresponds to equal elements in the sequences; the sequence returned
is the longest possible.</p></dd>
<dt><a name="2"><b class="cmd">::struct::list</b> <b class="method">longestCommonSubsequence2</b> <i class="arg">sequence1 sequence2</i> <span class="opt">?<i class="arg">maxOccurs</i>?</span></a></dt>
<dd><p>Returns an approximation to the longest common sequence of elements in
the two lists <i class="arg">sequence1</i> and <i class="arg">sequence2</i>.
If the <i class="arg">maxOccurs</i> parameter is omitted, the subsequence computed
is exactly the longest common subsequence; otherwise, the longest
common subsequence is approximated by first determining the longest
common sequence of only those elements that occur no more than
<i class="arg">maxOccurs</i> times in <i class="arg">sequence2</i>, and then using that result
to align the two lists, determining the longest common subsequences of
the sublists between the two elements.</p>
<p>As with <b class="method">longestCommonSubsequence</b>, the return value is a list
of two lists of equal length. The first sublist is of indices into
<i class="arg">sequence1</i>, and the second sublist is of indices into
<i class="arg">sequence2</i>. Each corresponding pair of indices corresponds to
equal elements in the sequences. The sequence approximates the
longest common subsequence.</p></dd>
<dt><a name="3"><b class="cmd">::struct::list</b> <b class="method">lcsInvert</b> <i class="arg">lcsData</i> <i class="arg">len1</i> <i class="arg">len2</i></a></dt>
<dd><p>This command takes a description of a longest common subsequence
(<i class="arg">lcsData</i>), inverts it, and returns the result. Inversion means
here that as the input describes which parts of the two sequences are
identical the output describes the differences instead.</p>
<p>To be fully defined the lengths of the two sequences have to be known
and are specified through <i class="arg">len1</i> and <i class="arg">len2</i>.</p>
<p>The result is a list where each element describes one chunk of the
differences between the two sequences. This description is a list
containing three elements, a type and two pairs of indices into
<i class="arg">sequence1</i> and <i class="arg">sequence2</i> respectively, in this order.
The type can be one of three values:</p>
<dl class="doctools_definitions">
<dt><b class="const">added</b></dt>
<dd><p>Describes an addition. I.e. items which are missing in <i class="arg">sequence1</i>
can be found in <i class="arg">sequence2</i>.
The pair of indices into <i class="arg">sequence1</i> describes where the added
range had been expected to be in <i class="arg">sequence1</i>. The first index
refers to the item just before the added range, and the second index
refers to the item just after the added range.
The pair of indices into <i class="arg">sequence2</i> describes the range of items
which has been added to it. The first index refers to the first item
in the range, and the second index refers to the last item in the
range.</p></dd>
<dt><b class="const">deleted</b></dt>
<dd><p>Describes a deletion. I.e. items which are in <i class="arg">sequence1</i> are
missing from <i class="arg">sequence2</i>.
The pair of indices into <i class="arg">sequence1</i> describes the range of items
which has been deleted. The first index refers to the first item in
the range, and the second index refers to the last item in the range.
The pair of indices into <i class="arg">sequence2</i> describes where the deleted
range had been expected to be in <i class="arg">sequence2</i>. The first index
refers to the item just before the deleted range, and the second index
refers to the item just after the deleted range.</p></dd>
<dt><b class="const">changed</b></dt>
<dd><p>Describes a general change. I.e a range of items in <i class="arg">sequence1</i>
has been replaced by a different range of items in <i class="arg">sequence2</i>.
The pair of indices into <i class="arg">sequence1</i> describes the range of items
which has been replaced. The first index refers to the first item in
the range, and the second index refers to the last item in the range.
The pair of indices into <i class="arg">sequence2</i> describes the range of items
replacing the original range. Again the first index refers to the
first item in the range, and the second index refers to the last item
in the range.</p></dd>
</dl>
<pre class="doctools_example">
sequence 1 = {a b r a c a d a b r a}
lcs 1 = {1 2 4 5 8 9 10}
lcs 2 = {0 1 3 4 5 6 7}
sequence 2 = {b r i c a b r a c}
Inversion = {{deleted {0 0} {-1 0}}
{changed {3 3} {2 2}}
{deleted {6 7} {4 5}}
{added {10 11} {8 8}}}
</pre>
<p><em>Notes:</em></p>
<ul class="doctools_itemized">
<li><p>An index of <b class="const">-1</b> in a <i class="term">deleted</i> chunk refers to just before
the first element of the second sequence.</p></li>
<li><p>Also an index equal to the length of the first sequence in an
<i class="term">added</i> chunk refers to just behind the end of the sequence.</p></li>
</ul></dd>
<dt><a name="4"><b class="cmd">::struct::list</b> <b class="method">lcsInvert2</b> <i class="arg">lcs1</i> <i class="arg">lcs2</i> <i class="arg">len1</i> <i class="arg">len2</i></a></dt>
<dd><p>Similar to <b class="method">lcsInvert</b>. Instead of directly taking the result
of a call to <b class="method">longestCommonSubsequence</b> this subcommand expects
the indices for the two sequences in two separate lists.</p></dd>
<dt><a name="5"><b class="cmd">::struct::list</b> <b class="method">lcsInvertMerge</b> <i class="arg">lcsData</i> <i class="arg">len1</i> <i class="arg">len2</i></a></dt>
<dd><p>Similar to <b class="method">lcsInvert</b>. It returns essentially the same
structure as that command, except that it may contain chunks of type
<b class="const">unchanged</b> too.</p>
<p>These new chunks describe the parts which are unchanged between the
two sequences. This means that the result of this command describes
both the changed and unchanged parts of the two sequences in one
structure.</p>
<pre class="doctools_example">
sequence 1 = {a b r a c a d a b r a}
lcs 1 = {1 2 4 5 8 9 10}
lcs 2 = {0 1 3 4 5 6 7}
sequence 2 = {b r i c a b r a c}
Inversion/Merge = {{deleted {0 0} {-1 0}}
{unchanged {1 2} {0 1}}
{changed {3 3} {2 2}}
{unchanged {4 5} {3 4}}
{deleted {6 7} {4 5}}
{unchanged {8 10} {5 7}}
{added {10 11} {8 8}}}
</pre>
</dd>
<dt><a name="6"><b class="cmd">::struct::list</b> <b class="method">lcsInvertMerge2</b> <i class="arg">lcs1</i> <i class="arg">lcs2</i> <i class="arg">len1</i> <i class="arg">len2</i></a></dt>
<dd><p>Similar to <b class="method">lcsInvertMerge</b>. Instead of directly taking the
result of a call to <b class="method">longestCommonSubsequence</b> this subcommand
expects the indices for the two sequences in two separate lists.</p></dd>
<dt><a name="7"><b class="cmd">::struct::list</b> <b class="method">reverse</b> <i class="arg">sequence</i></a></dt>
<dd><p>The subcommand takes a single <i class="arg">sequence</i> as argument and returns a new
sequence containing the elements of the input sequence in reverse
order.</p></dd>
<dt><a name="8"><b class="cmd">::struct::list</b> <b class="method">shuffle</b> <i class="arg">list</i></a></dt>
<dd><p>The subcommand takes a <i class="arg">list</i> and returns a copy of that list
with the elements it contains in random order. Every possible
ordering of elements is equally likely to be generated. The
Fisher-Yates shuffling algorithm is used internally.</p></dd>
<dt><a name="9"><b class="cmd">::struct::list</b> <b class="method">assign</b> <i class="arg">sequence</i> <i class="arg">varname</i> <span class="opt">?<i class="arg">varname</i>?</span>...</a></dt>
<dd><p>The subcommand assigns the first <b class="variable">n</b> elements of the input
<i class="arg">sequence</i> to the one or more variables whose names were listed
after the sequence, where <b class="variable">n</b> is the number of specified
variables.</p>
<p>If there are more variables specified than there are elements in the
<i class="arg">sequence</i> the empty string will be assigned to the superfluous
variables.</p>
<p>If there are more elements in the <i class="arg">sequence</i> than variable names
specified the subcommand returns a list containing the unassigned
elements. Else an empty list is returned.</p>
<pre class="doctools_example">
tclsh> ::struct::list assign {a b c d e} foo bar
c d e
tclsh> set foo
a
tclsh> set bar
b
</pre>
</dd>
<dt><a name="10"><b class="cmd">::struct::list</b> <b class="method">flatten</b> <span class="opt">?<b class="option">-full</b>?</span> <span class="opt">?<b class="option">--</b>?</span> <i class="arg">sequence</i></a></dt>
<dd><p>The subcommand takes a single <i class="arg">sequence</i> and returns a new
sequence where one level of nesting was removed from the input
sequence. In other words, the sublists in the input sequence are
replaced by their elements.</p>
<p>The subcommand will remove any nesting it finds if the option
<b class="option">-full</b> is specified.</p>
<pre class="doctools_example">
tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10}
1 2 3 4 5 6 7 {8 9} 10
tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10}
1 2 3 4 5 6 7 8 9 10
</pre>
</dd>
<dt><a name="11"><b class="cmd">::struct::list</b> <b class="method">map</b> <i class="arg">sequence</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The subcommand takes a <i class="arg">sequence</i> to operate on and a command
prefix (<i class="arg">cmdprefix</i>) specifying an operation, applies the command
prefix to each element of the sequence and returns a sequence
consisting of the results of that application.</p>
<p>The command prefix will be evaluated with a single word appended to
it. The evaluation takes place in the context of the caller of the
subcommand.</p>
<pre class="doctools_example">
tclsh> # squaring all elements in a list
tclsh> proc sqr {x} {expr {$x*$x}}
tclsh> ::struct::list map {1 2 3 4 5} sqr
1 4 9 16 25
tclsh> # Retrieving the second column from a matrix
tclsh> # given as list of lists.
tclsh> proc projection {n list} {::lindex $list $n}
tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1}
b 2 f
</pre>
</dd>
<dt><a name="12"><b class="cmd">::struct::list</b> <b class="method">mapfor</b> <i class="arg">var</i> <i class="arg">sequence</i> <i class="arg">script</i></a></dt>
<dd><p>The subcommand takes a <i class="arg">sequence</i> to operate on and a tcl <i class="arg">script</i>,
applies the script to each element of the sequence and returns a sequence
consisting of the results of that application.</p>
<p>The script will be evaluated as is, and has access to the current list element
through the specified iteration variable <i class="arg">var</i>. The evaluation takes place
in the context of the caller of the subcommand.</p>
<pre class="doctools_example">
tclsh> # squaring all elements in a list
tclsh> ::struct::list mapfor x {1 2 3 4 5} {
expr {$x * $x}
}
1 4 9 16 25
tclsh> # Retrieving the second column from a matrix
tclsh> # given as list of lists.
tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} {
lindex $x 1
}
b 2 f
</pre>
</dd>
<dt><a name="13"><b class="cmd">::struct::list</b> <b class="method">filter</b> <i class="arg">sequence</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The subcommand takes a <i class="arg">sequence</i> to operate on and a command
prefix (<i class="arg">cmdprefix</i>) specifying an operation, applies the command
prefix to each element of the sequence and returns a sequence
consisting of all elements of the <i class="arg">sequence</i> for which the command
prefix returned <b class="const">true</b>.
In other words, this command filters out all elements of the input
<i class="arg">sequence</i> which fail the test the <i class="arg">cmdprefix</i> represents, and
returns the remaining elements.</p>
<p>The command prefix will be evaluated with a single word appended to
it. The evaluation takes place in the context of the caller of the
subcommand.</p>
<pre class="doctools_example">
tclsh> # removing all odd numbers from the input
tclsh> proc even {x} {expr {($x % 2) == 0}}
tclsh> ::struct::list filter {1 2 3 4 5} even
2 4
</pre>
<p><em>Note:</em> The <b class="method">filter</b> is a specialized application of
<b class="method">fold</b> where the result is extended with the current item or
not, depending o nthe result of the test.</p></dd>
<dt><a name="14"><b class="cmd">::struct::list</b> <b class="method">filterfor</b> <i class="arg">var</i> <i class="arg">sequence</i> <i class="arg">expr</i></a></dt>
<dd><p>The subcommand takes a <i class="arg">sequence</i> to operate on and a tcl expression
(<i class="arg">expr</i>) specifying a condition, applies the conditionto each element
of the sequence and returns a sequence consisting of all elements of the
<i class="arg">sequence</i> for which the expression returned <b class="const">true</b>.
In other words, this command filters out all elements of the input
<i class="arg">sequence</i> which fail the test the condition <i class="arg">expr</i> represents, and
returns the remaining elements.</p>
<p>The expression will be evaluated as is, and has access to the current list
element through the specified iteration variable <i class="arg">var</i>. The evaluation
takes place in the context of the caller of the subcommand.</p>
<pre class="doctools_example">
tclsh> # removing all odd numbers from the input
tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0}
2 4
</pre>
</dd>
<dt><a name="15"><b class="cmd">::struct::list</b> <b class="method">split</b> <i class="arg">sequence</i> <i class="arg">cmdprefix</i> <span class="opt">?<i class="arg">passVar</i> <i class="arg">failVar</i>?</span></a></dt>
<dd><p>This is a variant of method <b class="method">filter</b>, see above. Instead of
returning just the elements passing the test we get lists of both
passing and failing elements.</p>
<p>If no variable names are specified then the result of the command will
be a list containing the list of passing elements, and the list of
failing elements, in this order. Otherwise the lists of passing and
failing elements are stored into the two specified variables, and the
result will be a list containing two numbers, the number of elements
passing the test, and the number of elements failing, in this order.</p>
<p>The interface to the test is the same as used by <b class="method">filter</b>.</p></dd>
<dt><a name="16"><b class="cmd">::struct::list</b> <b class="method">fold</b> <i class="arg">sequence</i> <i class="arg">initialvalue</i> <i class="arg">cmdprefix</i></a></dt>
<dd><p>The subcommand takes a <i class="arg">sequence</i> to operate on, an arbitrary
string <i class="arg">initial value</i> and a command prefix (<i class="arg">cmdprefix</i>)
specifying an operation.</p>
<p>The command prefix will be evaluated with two words appended to
it. The second of these words will always be an element of the
sequence. The evaluation takes place in the context of the caller of
the subcommand.</p>
<p>It then reduces the sequence into a single value through repeated
application of the command prefix and returns that value. This
reduction is done by</p>
<dl class="doctools_definitions">
<dt><b class="const">1</b></dt>
<dd><p>Application of the command to the initial value and the first element
of the list.</p></dd>
<dt><b class="const">2</b></dt>
<dd><p>Application of the command to the result of the last call and the
second element of the list.</p></dd>
<dt><b class="const">...</b></dt>
<dd></dd>
<dt><b class="const">i</b></dt>
<dd><p>Application of the command to the result of the last call and the
<b class="variable">i</b>'th element of the list.</p></dd>
<dt><b class="const">...</b></dt>
<dd></dd>
<dt><b class="const">end</b></dt>
<dd><p>Application of the command to the result of the last call and the last
element of the list. The result of this call is returned as the result
of the subcommand.</p></dd>
</dl>
<pre class="doctools_example">
tclsh> # summing the elements in a list.
tclsh> proc + {a b} {expr {$a + $b}}
tclsh> ::struct::list fold {1 2 3 4 5} 0 +
15
</pre>
</dd>
<dt><a name="17"><b class="cmd">::struct::list</b> <b class="method">shift</b> <i class="arg">listvar</i></a></dt>
<dd><p>The subcommand takes the list contained in the variable named by
<i class="arg">listvar</i> and shifts it down one element.
After the call <i class="arg">listvar</i> will contain a list containing the second
to last elements of the input list. The first element of the ist is
returned as the result of the command. Shifting the empty list does
nothing.</p></dd>
<dt><a name="18"><b class="cmd">::struct::list</b> <b class="method">iota</b> <i class="arg">n</i></a></dt>
<dd><p>The subcommand returns a list containing the integer numbers
in the range <b class="const">[0,n)</b>. The element at index <b class="variable">i</b>
of the list contain the number <b class="const">i</b>.</p>
<p>For "<i class="arg">n</i> == <b class="const">0</b>" an empty list will be returned.</p></dd>
<dt><a name="19"><b class="cmd">::struct::list</b> <b class="method">equal</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>The subcommand compares the two lists <i class="arg">a</i> and <i class="arg">b</i> for
equality. In other words, they have to be of the same length and have
to contain the same elements in the same order. If an element is a
list the same definition of equality applies recursively.</p>
<p>A boolean value will be returned as the result of the command.
This value will be <b class="const">true</b> if the two lists are equal, and
<b class="const">false</b> else.</p></dd>
<dt><a name="20"><b class="cmd">::struct::list</b> <b class="method">repeat</b> <i class="arg">size</i> <i class="arg">element1</i> <span class="opt">?<i class="arg">element2</i> <i class="arg">element3</i>...?</span></a></dt>
<dd><p>The subcommand creates a list of length
"<i class="arg">size</i> * <em>number of elements</em>" by repeating <i class="arg">size</i>
times the sequence of elements
<i class="arg">element1</i> <i class="arg">element2</i> <i class="arg">...</i>.
<i class="arg">size</i> must be a positive integer, <i class="arg">element</i><b class="variable">n</b> can be any
Tcl value.
Note that <b class="cmd">repeat 1 arg ...</b> is identical to
<b class="cmd">list arg ...</b>, though the <i class="arg">arg</i> is required
with <b class="method">repeat</b>.</p>
<p><em>Examples:</em></p>
<pre class="doctools_example">
tclsh> ::struct::list repeat 3 a
a a a
tclsh> ::struct::list repeat 3 [::struct::list repeat 3 0]
{0 0 0} {0 0 0} {0 0 0}
tclsh> ::struct::list repeat 3 a b c
a b c a b c a b c
tclsh> ::struct::list repeat 3 [::struct::list repeat 2 a] b c
{a a} b c {a a} b c {a a} b c
</pre>
</dd>
<dt><a name="21"><b class="cmd">::struct::list</b> <b class="method">repeatn</b> <i class="arg">value</i> <i class="arg">size</i>...</a></dt>
<dd><p>The subcommand creates a (nested) list containing the <i class="arg">value</i> in
all positions. The exact size and degree of nesting is determined by
the <i class="arg">size</i> arguments, all of which have to be integer numbers
greater than or equal to zero.</p>
<p>A single argument <i class="arg">size</i> which is a list of more than one element
will be treated as if more than argument <i class="arg">size</i> was specified.</p>
<p>If only one argument <i class="arg">size</i> is present the returned list will not
be nested, of length <i class="arg">size</i> and contain <i class="arg">value</i> in all
positions.
If more than one <i class="arg">size</i> argument is present the returned
list will be nested, and of the length specified by the last
<i class="arg">size</i> argument given to it. The elements of that list
are defined as the result of <b class="cmd">Repeat</b> for the same arguments,
but with the last <i class="arg">size</i> value removed.</p>
<p>An empty list will be returned if no <i class="arg">size</i> arguments are present.</p>
<pre class="doctools_example">
tclsh> ::struct::list repeatn 0 3 4
{0 0 0} {0 0 0} {0 0 0} {0 0 0}
tclsh> ::struct::list repeatn 0 {3 4}
{0 0 0} {0 0 0} {0 0 0} {0 0 0}
tclsh> ::struct::list repeatn 0 {3 4 5}
{{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}}
</pre>
</dd>
<dt><a name="22"><b class="cmd">::struct::list</b> <b class="method">dbJoin</b> <span class="opt">?<b class="option">-inner</b>|<b class="option">-left</b>|<b class="option">-right</b>|<b class="option">-full</b>?</span> <span class="opt">?<b class="option">-keys</b> <i class="arg">varname</i>?</span> {<i class="arg">keycol</i> <i class="arg">table</i>}...</a></dt>
<dd><p>The method performs a table join according to relational algebra. The
execution of any of the possible outer join operation is triggered by
the presence of either option <b class="option">-left</b>, <b class="option">-right</b>, or
<b class="option">-full</b>. If none of these options is present a regular inner
join will be performed. This can also be triggered by specifying
<b class="option">-inner</b>. The various possible join operations are explained in
detail in section <span class="sectref"><a href="#section4">TABLE JOIN</a></span>.</p>
<p>If the <b class="option">-keys</b> is present its argument is the name of a
variable to store the full list of found keys into. Depending on the
exact nature of the input table and the join mode the output table may
not contain all the keys by default. In such a case the caller can
declare a variable for this information and then insert it into the
output table on its own, as she will have more information about the
placement than this command.</p>
<p>What is left to explain is the format of the arguments.</p>
<p>The <i class="arg">keycol</i> arguments are the indices of the columns in the
tables which contain the key values to use for the joining. Each
argument applies to the table following immediately after it. The
columns are counted from <b class="const">0</b>, which references the first
column. The table associated with the column index has to have at
least <i class="arg">keycol</i>+1 columns. An error will be thrown if there are
less.</p>
<p>The <i class="arg">table</i> arguments represent a table or matrix of rows and
columns of values. We use the same representation as generated and
consumed by the methods <b class="method">get rect</b> and <b class="method">set rect</b> of
<b class="cmd"><a href="../../../../index.html#matrix">matrix</a></b> objects. In other words, each argument is a list,
representing the whole matrix. Its elements are lists too, each
representing a single rows of the matrix. The elements of the
row-lists are the column values.</p>
<p>The table resulting from the join operation is returned as the result
of the command. We use the same representation as described above for
the input <i class="arg">table</i>s.</p></dd>
<dt><a name="23"><b class="cmd">::struct::list</b> <b class="method">dbJoinKeyed</b> <span class="opt">?<b class="option">-inner</b>|<b class="option">-left</b>|<b class="option">-right</b>|<b class="option">-full</b>?</span> <span class="opt">?<b class="option">-keys</b> <i class="arg">varname</i>?</span> <i class="arg">table</i>...</a></dt>
<dd><p>The operations performed by this method are the same as described
above for <b class="method">dbJoin</b>. The only difference is in the specification
of the keys to use. Instead of using column indices separate from the
table here the keys are provided within the table itself. The row
elements in each <i class="arg">table</i> are not the lists of column values, but a
two-element list where the second element is the regular list of
column values and the first element is the key to use.</p></dd>
<dt><a name="24"><b class="cmd">::struct::list</b> <b class="method">swap</b> <i class="arg">listvar</i> <i class="arg">i</i> <i class="arg">j</i></a></dt>
<dd><p>The subcommand exchanges the elements at the indices <i class="arg">i</i> and
<i class="arg">j</i> in the list stored in the variable named by <i class="arg">listvar</i>. The
list is modified in place, and also returned as the result of the
subcommand.</p></dd>
<dt><a name="25"><b class="cmd">::struct::list</b> <b class="method">firstperm</b> <i class="arg">list</i></a></dt>
<dd><p>This subcommand returns the lexicographically first permutation of the
input <i class="arg">list</i>.</p></dd>
<dt><a name="26"><b class="cmd">::struct::list</b> <b class="method">nextperm</b> <i class="arg">perm</i></a></dt>
<dd><p>This subcommand accepts a permutation of a set of elements (provided
by <i class="arg">perm</i>) and returns the next permutatation in lexicographic
sequence.</p>
<p>The algorithm used here is by Donal E. Knuth, see section
<span class="sectref"><a href="#section5">REFERENCES</a></span> for details.</p></dd>
<dt><a name="27"><b class="cmd">::struct::list</b> <b class="method">permutations</b> <i class="arg">list</i></a></dt>
<dd><p>This subcommand returns a list containing all permutations of the
input <i class="arg">list</i> in lexicographic order.</p></dd>
<dt><a name="28"><b class="cmd">::struct::list</b> <b class="method">foreachperm</b> <i class="arg">var</i> <i class="arg">list</i> <i class="arg">body</i></a></dt>
<dd><p>This subcommand executes the script <i class="arg">body</i> once for each
permutation of the specified <i class="arg">list</i>. The permutations are visited
in lexicographic order, and the variable <i class="arg">var</i> is set to the
permutation for which <i class="arg">body</i> is currently executed. The result of
the loop command is the empty string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON</a></h2>
<p>The <b class="method">longestCommonSubsequence</b> subcommand forms the core of a
flexible system for doing differential comparisons of files, similar
to the capability offered by the Unix command <b class="syscmd"><a href="../../../../index.html#diff">diff</a></b>.
While this procedure is quite rapid for many tasks of file comparison,
its performance degrades severely if <i class="arg">sequence2</i> contains many
equal elements (as, for instance, when using this procedure to compare
two files, a quarter of whose lines are blank. This drawback is
intrinsic to the algorithm used (see the Reference for details).</p>
<p>One approach to dealing with the performance problem that is sometimes
effective in practice is arbitrarily to exclude elements that appear
more than a certain number of times.
This number is provided as the <i class="arg">maxOccurs</i> parameter. If frequent
lines are excluded in this manner, they will not appear in the common
subsequence that is computed; the result will be the longest common
subsequence of infrequent elements.
The procedure <b class="method">longestCommonSubsequence2</b> implements this
heuristic.
It functions as a wrapper around <b class="method">longestCommonSubsequence</b>; it
computes the longest common subsequence of infrequent elements, and
then subdivides the subsequences that lie between the matches to
approximate the true longest common subsequence.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TABLE JOIN</a></h2>
<p>This is an operation from relational algebra for relational databases.</p>
<p>The easiest way to understand the regular inner join is that it
creates the cartesian product of all the tables involved first and
then keeps only all those rows in the resulting table for which the
values in the specified key columns are equal to each other.</p>
<p>Implementing this description naively, i.e. as described above will
generate a <em>huge</em> intermediate result. To avoid this the
cartesian product and the filtering of row are done at the same
time. What is required is a fast way to determine if a key is present
in a table. In a true database this is done through indices. Here we
use arrays internally.</p>
<p>An <i class="term">outer</i> join is an extension of the inner join for two
tables. There are three variants of outerjoins, called <i class="term">left</i>,
<i class="term">right</i>, and <i class="term">full</i> outer joins. Their result always
contains all rows from an inner join and then some additional rows.</p>
<ol class="doctools_enumerated">
<li><p>For the left outer join the additional rows are all rows from the left
table for which there is no key in the right table. They are joined to
an empty row of the right table to fit them into the result.</p></li>
<li><p>For the right outer join the additional rows are all rows from the right
table for which there is no key in the left table. They are joined to
an empty row of the left table to fit them into the result.</p></li>
<li><p>The full outer join combines both left and right outer join. In other
words, the additional rows are as defined for left outer join, and
right outer join, combined.</p></li>
</ol>
<p>We extend all the joins from two to <b class="variable">n</b> tables (<b class="variable">n</b> > 2) by
executing</p>
<pre class="doctools_example">
(...((table1 join table2) join table3) ...) join tableN
</pre>
<p>Examples for all the joins:</p>
<pre class="doctools_example">
Inner Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} inner join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver}
Left Outer Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} left outer join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver} {2 blue {} {}}
Right Outer Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} right outer join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver} {{} {} 3 driver}
Full Outer Join
{0 foo} {0 bagel} {0 foo 0 bagel}
{1 snarf} full outer join {1 snatz} = {1 snarf 1 snatz}
{2 blue} {3 driver} {2 blue {} {}}
{{} {} 3 driver}
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>J. W. Hunt and M. D. McIlroy, "An algorithm for differential
file comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone
Laboratories (1976). Available on the Web at the second
author's personal site: <a href="http://www.cs.dartmouth.edu/~doug/">http://www.cs.dartmouth.edu/~doug/</a></p></li>
<li><p>Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming'
volume 4". Available on the Web at the author's personal site:
<a href="http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz">http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz</a>.</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: list</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fisher_yates">Fisher-Yates</a>, <a href="../../../../index.html#assign">assign</a>, <a href="../../../../index.html#common">common</a>, <a href="../../../../index.html#comparison">comparison</a>, <a href="../../../../index.html#diff">diff</a>, <a href="../../../../index.html#differential">differential</a>, <a href="../../../../index.html#equal">equal</a>, <a href="../../../../index.html#equality">equality</a>, <a href="../../../../index.html#filter">filter</a>, <a href="../../../../index.html#first_permutation">first permutation</a>, <a href="../../../../index.html#flatten">flatten</a>, <a href="../../../../index.html#folding">folding</a>, <a href="../../../../index.html#full_outer_join">full outer join</a>, <a href="../../../../index.html#generate_permutations">generate permutations</a>, <a href="../../../../index.html#inner_join">inner join</a>, <a href="../../../../index.html#join">join</a>, <a href="../../../../index.html#left_outer_join">left outer join</a>, <a href="../../../../index.html#list">list</a>, <a href="../../../../index.html#longest_common_subsequence">longest common subsequence</a>, <a href="../../../../index.html#map">map</a>, <a href="../../../../index.html#next_permutation">next permutation</a>, <a href="../../../../index.html#outer_join">outer join</a>, <a href="../../../../index.html#permutation">permutation</a>, <a href="../../../../index.html#reduce">reduce</a>, <a href="../../../../index.html#repeating">repeating</a>, <a href="../../../../index.html#repetition">repetition</a>, <a href="../../../../index.html#reshuffle">reshuffle</a>, <a href="../../../../index.html#reverse">reverse</a>, <a href="../../../../index.html#right_outer_join">right outer join</a>, <a href="../../../../index.html#shuffle">shuffle</a>, <a href="../../../../index.html#subsequence">subsequence</a>, <a href="../../../../index.html#swapping">swapping</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2003-2005 by Kevin B. Kenny. All rights reserved<br>
Copyright © 2003-2012 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/struct_set.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
<div class='fossil-doc' data-title='struct::set - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::set(n) 2.2.3 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::set - Procedures for manipulating sets</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">REFERENCES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.0</b></li>
<li>package require <b class="pkgname">struct::set <span class="opt">?2.2.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::set</b> <b class="method">empty</b> <i class="arg">set</i></a></li>
<li><a href="#2"><b class="cmd">::struct::set</b> <b class="method">size</b> <i class="arg">set</i></a></li>
<li><a href="#3"><b class="cmd">::struct::set</b> <b class="method">contains</b> <i class="arg">set</i> <i class="arg">item</i></a></li>
<li><a href="#4"><b class="cmd">::struct::set</b> <b class="method">union</b> <span class="opt">?<i class="arg">set1</i>...?</span></a></li>
<li><a href="#5"><b class="cmd">::struct::set</b> <b class="method">intersect</b> <span class="opt">?<i class="arg">set1</i>...?</span></a></li>
<li><a href="#6"><b class="cmd">::struct::set</b> <b class="method">difference</b> <i class="arg">set1</i> <i class="arg">set2</i></a></li>
<li><a href="#7"><b class="cmd">::struct::set</b> <b class="method">symdiff</b> <i class="arg">set1</i> <i class="arg">set2</i></a></li>
<li><a href="#8"><b class="cmd">::struct::set</b> <b class="method">intersect3</b> <i class="arg">set1</i> <i class="arg">set2</i></a></li>
<li><a href="#9"><b class="cmd">::struct::set</b> <b class="method">equal</b> <i class="arg">set1</i> <i class="arg">set2</i></a></li>
<li><a href="#10"><b class="cmd">::struct::set</b> <b class="method">include</b> <i class="arg">svar</i> <i class="arg">item</i></a></li>
<li><a href="#11"><b class="cmd">::struct::set</b> <b class="method">exclude</b> <i class="arg">svar</i> <i class="arg">item</i></a></li>
<li><a href="#12"><b class="cmd">::struct::set</b> <b class="method">add</b> <i class="arg">svar</i> <i class="arg">set</i></a></li>
<li><a href="#13"><b class="cmd">::struct::set</b> <b class="method">subtract</b> <i class="arg">svar</i> <i class="arg">set</i></a></li>
<li><a href="#14"><b class="cmd">::struct::set</b> <b class="method">subsetof</b> <i class="arg">A</i> <i class="arg">B</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::set</b> namespace contains several useful commands for
processing finite sets.</p>
<p>It exports only a single command, <b class="cmd">struct::set</b>. All
functionality provided here can be reached through a subcommand of
this command.</p>
<p><em>Note:</em> As of version 2.2 of this package a critcl based C
implementation is available. This implementation however requires Tcl
8.4 to run.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::set</b> <b class="method">empty</b> <i class="arg">set</i></a></dt>
<dd><p>Returns a boolean value indicating if the <i class="arg">set</i> is
empty (<b class="const">true</b>), or not (<b class="const">false</b>).</p></dd>
<dt><a name="2"><b class="cmd">::struct::set</b> <b class="method">size</b> <i class="arg">set</i></a></dt>
<dd><p>Returns an integer number greater than or equal to zero. This is the
number of elements in the <i class="arg">set</i>. In other words, its cardinality.</p></dd>
<dt><a name="3"><b class="cmd">::struct::set</b> <b class="method">contains</b> <i class="arg">set</i> <i class="arg">item</i></a></dt>
<dd><p>Returns a boolean value indicating if the <i class="arg">set</i> contains the
element <i class="arg">item</i> (<b class="const">true</b>), or not (<b class="const">false</b>).</p></dd>
<dt><a name="4"><b class="cmd">::struct::set</b> <b class="method">union</b> <span class="opt">?<i class="arg">set1</i>...?</span></a></dt>
<dd><p>Computes the set containing the union of <i class="arg">set1</i>, <i class="arg">set2</i>,
etc., i.e. "<i class="arg">set1</i> + <i class="arg">set2</i> + ...", and returns this set
as the result of the command.</p></dd>
<dt><a name="5"><b class="cmd">::struct::set</b> <b class="method">intersect</b> <span class="opt">?<i class="arg">set1</i>...?</span></a></dt>
<dd><p>Computes the set containing the intersection of <i class="arg">set1</i>,
<i class="arg">set2</i>, etc., i.e. "<i class="arg">set1</i> * <i class="arg">set2</i> * ...", and
returns this set as the result of the command.</p></dd>
<dt><a name="6"><b class="cmd">::struct::set</b> <b class="method">difference</b> <i class="arg">set1</i> <i class="arg">set2</i></a></dt>
<dd><p>Computes the set containing the difference of <i class="arg">set1</i> and
<i class="arg">set2</i>, i.e. ("<i class="arg">set1</i> - <i class="arg">set2</i>") and returns this
set as the result of the command.</p></dd>
<dt><a name="7"><b class="cmd">::struct::set</b> <b class="method">symdiff</b> <i class="arg">set1</i> <i class="arg">set2</i></a></dt>
<dd><p>Computes the set containing the symmetric difference of <i class="arg">set1</i> and
<i class="arg">set2</i>, i.e. ("(<i class="arg">set1</i> - <i class="arg">set2</i>) + (<i class="arg">set2</i> - <i class="arg">set1</i>)")
and returns this set as the result of the command.</p></dd>
<dt><a name="8"><b class="cmd">::struct::set</b> <b class="method">intersect3</b> <i class="arg">set1</i> <i class="arg">set2</i></a></dt>
<dd><p>This command is a combination of the methods <b class="method">intersect</b> and
<b class="method">difference</b>.
It returns a three-element list containing "<i class="arg">set1</i>*<i class="arg">set2</i>",
"<i class="arg">set1</i>-<i class="arg">set2</i>", and "<i class="arg">set2</i>-<i class="arg">set1</i>", in this
order. In other words, the intersection of the two parameter sets, and
their differences.</p></dd>
<dt><a name="9"><b class="cmd">::struct::set</b> <b class="method">equal</b> <i class="arg">set1</i> <i class="arg">set2</i></a></dt>
<dd><p>Returns a boolean value indicating if the two sets are equal
(<b class="const">true</b>) or not (<b class="const">false</b>).</p></dd>
<dt><a name="10"><b class="cmd">::struct::set</b> <b class="method">include</b> <i class="arg">svar</i> <i class="arg">item</i></a></dt>
<dd><p>The element <i class="arg">item</i> is added to the set specified by the variable
name in <i class="arg">svar</i>. The return value of the command is empty. This is
the equivalent of <b class="cmd">lappend</b> for sets. If the variable named by
<i class="arg">svar</i> does not exist it will be created.</p></dd>
<dt><a name="11"><b class="cmd">::struct::set</b> <b class="method">exclude</b> <i class="arg">svar</i> <i class="arg">item</i></a></dt>
<dd><p>The element <i class="arg">item</i> is removed from the set specified by the
variable name in <i class="arg">svar</i>. The return value of the command is
empty. This is a near-equivalent of <b class="cmd">lreplace</b> for sets.</p></dd>
<dt><a name="12"><b class="cmd">::struct::set</b> <b class="method">add</b> <i class="arg">svar</i> <i class="arg">set</i></a></dt>
<dd><p>All the element of <i class="arg">set</i> are added to the set specified by the
variable name in <i class="arg">svar</i>. The return value of the command is
empty. This is like the method <b class="method">include</b>, but for the addition
of a whole set. If the variable named by <i class="arg">svar</i> does not exist it
will be created.</p></dd>
<dt><a name="13"><b class="cmd">::struct::set</b> <b class="method">subtract</b> <i class="arg">svar</i> <i class="arg">set</i></a></dt>
<dd><p>All the element of <i class="arg">set</i> are removed from the set specified by the
variable name in <i class="arg">svar</i>. The return value of the command is
empty. This is like the method <b class="method">exclude</b>, but for the removal
of a whole set.</p></dd>
<dt><a name="14"><b class="cmd">::struct::set</b> <b class="method">subsetof</b> <i class="arg">A</i> <i class="arg">B</i></a></dt>
<dd><p>Returns a boolean value indicating if the set <i class="arg">A</i> is a true
subset of or equal to the set <i class="arg">B</i> (<b class="const">true</b>), or not
(<b class="const">false</b>).</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">REFERENCES</a></h2>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: set</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cardinality">cardinality</a>, <a href="../../../../index.html#difference">difference</a>, <a href="../../../../index.html#emptiness">emptiness</a>, <a href="../../../../index.html#exclusion">exclusion</a>, <a href="../../../../index.html#inclusion">inclusion</a>, <a href="../../../../index.html#intersection">intersection</a>, <a href="../../../../index.html#membership">membership</a>, <a href="../../../../index.html#set">set</a>, <a href="../../../../index.html#symmetric_difference">symmetric difference</a>, <a href="../../../../index.html#union">union</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/struct_tree.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
|
<div class='fossil-doc' data-title='struct::tree - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::tree(n) 2.1.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::tree - Create and manipulate tree objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Tree CLASS API</a></li>
<li class="doctools_subsection"><a href="#subsection2">Tree OBJECT API</a></li>
<li class="doctools_subsection"><a href="#subsection3">Changes for 2.0</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::tree <span class="opt">?2.1.1?</span></b></li>
<li>package require <b class="pkgname">struct::list <span class="opt">?1.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::struct::tree</b> <span class="opt">?<i class="arg">treeName</i>?</span> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">source</i>?</span></a></li>
<li><a href="#2"><b class="cmd">treeName</b> <b class="method">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::struct::tree::prune</b></a></li>
<li><a href="#4"><i class="arg">treeName</i> <b class="method">=</b> <i class="arg">sourcetree</i></a></li>
<li><a href="#5"><i class="arg">treeName</i> <b class="method">--></b> <i class="arg">desttree</i></a></li>
<li><a href="#6"><i class="arg">treeName</i> <b class="method">ancestors</b> <i class="arg">node</i></a></li>
<li><a href="#7"><i class="arg">treeName</i> <b class="method">append</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#8"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i></a></li>
<li><a href="#9"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i> <b class="option">-nodes</b> <i class="arg">list</i></a></li>
<li><a href="#10"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i> <b class="option">-glob</b> <i class="arg">globpattern</i></a></li>
<li><a href="#11"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i> <b class="option">-regexp</b> <i class="arg">repattern</i></a></li>
<li><a href="#12"><i class="arg">treeName</i> <b class="method">children</b> <span class="opt">?<b class="option">-all</b>?</span> <i class="arg">node</i> <span class="opt">?<b class="const">filter</b> <i class="arg">cmdprefix</i>?</span></a></li>
<li><a href="#13"><i class="arg">treeName</i> <b class="method">cut</b> <i class="arg">node</i></a></li>
<li><a href="#14"><i class="arg">treeName</i> <b class="method">delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></li>
<li><a href="#15"><i class="arg">treeName</i> <b class="method">depth</b> <i class="arg">node</i></a></li>
<li><a href="#16"><i class="arg">treeName</i> <b class="method">descendants</b> <i class="arg">node</i> <span class="opt">?<b class="const">filter</b> <i class="arg">cmdprefix</i>?</span></a></li>
<li><a href="#17"><i class="arg">treeName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></li>
<li><a href="#18"><i class="arg">treeName</i> <b class="method">destroy</b></a></li>
<li><a href="#19"><i class="arg">treeName</i> <b class="method">exists</b> <i class="arg">node</i></a></li>
<li><a href="#20"><i class="arg">treeName</i> <b class="method">get</b> <i class="arg">node</i> <i class="arg">key</i></a></li>
<li><a href="#21"><i class="arg">treeName</i> <b class="method">getall</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#22"><i class="arg">treeName</i> <b class="method">keys</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#23"><i class="arg">treeName</i> <b class="method">keyexists</b> <i class="arg">node</i> <i class="arg">key</i></a></li>
<li><a href="#24"><i class="arg">treeName</i> <b class="method">index</b> <i class="arg">node</i></a></li>
<li><a href="#25"><i class="arg">treeName</i> <b class="method">insert</b> <i class="arg">parent</i> <i class="arg">index</i> <span class="opt">?<i class="arg">child</i> <span class="opt">?<i class="arg">child</i> ...?</span>?</span></a></li>
<li><a href="#26"><i class="arg">treeName</i> <b class="method">isleaf</b> <i class="arg">node</i></a></li>
<li><a href="#27"><i class="arg">treeName</i> <b class="method">lappend</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#28"><i class="arg">treeName</i> <b class="method">leaves</b></a></li>
<li><a href="#29"><i class="arg">treeName</i> <b class="method">move</b> <i class="arg">parent</i> <i class="arg">index</i> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></li>
<li><a href="#30"><i class="arg">treeName</i> <b class="method">next</b> <i class="arg">node</i></a></li>
<li><a href="#31"><i class="arg">treeName</i> <b class="method">numchildren</b> <i class="arg">node</i></a></li>
<li><a href="#32"><i class="arg">treeName</i> <b class="method">nodes</b></a></li>
<li><a href="#33"><i class="arg">treeName</i> <b class="method">parent</b> <i class="arg">node</i></a></li>
<li><a href="#34"><i class="arg">treeName</i> <b class="method">previous</b> <i class="arg">node</i></a></li>
<li><a href="#35"><i class="arg">treeName</i> <b class="method">rename</b> <i class="arg">node</i> <i class="arg">newname</i></a></li>
<li><a href="#36"><i class="arg">treeName</i> <b class="method">rootname</b></a></li>
<li><a href="#37"><i class="arg">treeName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">node</i>?</span></a></li>
<li><a href="#38"><i class="arg">treeName</i> <b class="method">set</b> <i class="arg">node</i> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#39"><i class="arg">treeName</i> <b class="method">size</b> <span class="opt">?<i class="arg">node</i>?</span></a></li>
<li><a href="#40"><i class="arg">treeName</i> <b class="method">splice</b> <i class="arg">parent</i> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span> <span class="opt">?<i class="arg">child</i>?</span></a></li>
<li><a href="#41"><i class="arg">treeName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></li>
<li><a href="#42"><i class="arg">treeName</i> <b class="method">unset</b> <i class="arg">node</i> <i class="arg">key</i></a></li>
<li><a href="#43"><i class="arg">treeName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?<b class="option">-order</b> <i class="arg">order</i>?</span> <span class="opt">?<b class="option">-type</b> <i class="arg">type</i>?</span> <i class="arg">loopvar</i> <i class="arg">script</i></a></li>
<li><a href="#44"><i class="arg">treeName</i> <b class="method">walkproc</b> <i class="arg">node</i> <span class="opt">?<b class="option">-order</b> <i class="arg">order</i>?</span> <span class="opt">?<b class="option">-type</b> <i class="arg">type</i>?</span> <i class="arg">cmdprefix</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>A tree is a collection of named elements, called nodes, one of which is
distinguished as a root, along with a relation ("parenthood") that
places a hierarchical structure on the nodes. (Data Structures and
Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987). In
addition to maintaining the node relationships, this tree
implementation allows any number of keyed values to be associated with
each node.</p>
<p>The element names can be arbitrary strings.</p>
<p>A tree is thus similar to an array, but with three important
differences:</p>
<ol class="doctools_enumerated">
<li><p>Trees are accessed through an object command, whereas arrays are
accessed as variables. (This means trees cannot be local to a procedure.)</p></li>
<li><p>Trees have a hierarchical structure, whereas an array is just an
unordered collection.</p></li>
<li><p>Each node of a tree has a separate collection of attributes and
values. This is like an array where every value is a dictionary.</p></li>
</ol>
<p><em>Note:</em> The major version of the package <b class="package"><a href="../../../../index.html#struct">struct</a></b> has
been changed to version 2.0, due to backward incompatible changes in
the API of this module. Please read the section
<span class="sectref"><a href="#subsection3">Changes for 2.0</a></span> for a full list of all changes,
incompatible and otherwise.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Tree CLASS API</a></h3>
<p>The main commands of the package are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::struct::tree</b> <span class="opt">?<i class="arg">treeName</i>?</span> <span class="opt">?<b class="const">=</b>|<b class="const">:=</b>|<b class="const">as</b>|<b class="const">deserialize</b> <i class="arg">source</i>?</span></a></dt>
<dd><p>The command creates a new tree object with an associated global Tcl
command whose name is <i class="arg">treeName</i>. This command may be used to
invoke various operations on the tree.
It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">treeName</b> <b class="method">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>If <i class="arg">treeName</i> is not specified a unique name will be generated by
the package itself. If a <i class="arg">source</i> is specified the new tree will
be initialized to it. For the operators <b class="const">=</b>, <b class="const">:=</b>, and
<b class="const">as</b> <i class="arg">source</i> is interpreted as the name of another tree
object, and the assignment operator <b class="method">=</b> will be executed. For
<b class="const">deserialize</b> the <i class="arg">source</i> is a serialized tree object and
<b class="method">deserialize</b> will be executed.</p>
<p>In other words</p>
<pre class="doctools_example">
::struct::tree mytree = b
</pre>
<p>is equivalent to</p>
<pre class="doctools_example">
::struct::tree mytree
mytree = b
</pre>
<p>and</p>
<pre class="doctools_example">
::struct::tree mytree deserialize $b
</pre>
<p>is equivalent to</p>
<pre class="doctools_example">
::struct::tree mytree
mytree deserialize $b
</pre>
</dd>
<dt><a name="3"><b class="cmd">::struct::tree::prune</b></a></dt>
<dd><p>This command is provided outside of the tree methods, as it is not a
tree method per se. It however interacts tightly with the method
<b class="method">walk</b>. When used in the walk script it causes the traversal to
ignore the children of the node we are currently at.
This command cannot be used with the traversal modes which look at
children before their parent, i.e. <b class="const">post</b> and <b class="const">in</b>. The
only applicable orders of traversal are <b class="const">pre</b> and
<b class="const">both</b>. An error is thrown if the command and chosen order of
traversal do not fit.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Tree OBJECT API</a></h3>
<p>Two general observations beforehand:</p>
<ol class="doctools_enumerated">
<li><p>The root node of the tree can be used in most places where a node is
asked for. The default name of the rootnode is "root", but this can be
changed with the method <b class="method">rename</b> (see below). Whatever the
current name for the root node of the tree is, it can be retrieved by
calling the method <b class="method">rootname</b>.</p></li>
<li><p>The method <b class="method">insert</b> is the only way to create new nodes, and
they are automatically added to a parent. A tree object cannot have
nodes without a parent, save the root node.</p></li>
</ol>
<p>And now the methods supported by tree objects created by this package:</p>
<dl class="doctools_definitions">
<dt><a name="4"><i class="arg">treeName</i> <b class="method">=</b> <i class="arg">sourcetree</i></a></dt>
<dd><p>This is the assignment operator for tree objects. It copies the tree
contained in the tree object <i class="arg">sourcetree</i> over the tree data in
<i class="arg">treeName</i>. The old contents of <i class="arg">treeName</i> are deleted by this
operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">treeName</i> <b class="method">deserialize</b> [<i class="arg">sourcetree</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="5"><i class="arg">treeName</i> <b class="method">--></b> <i class="arg">desttree</i></a></dt>
<dd><p>This is the reverse assignment operator for tree objects. It copies the tree
contained in the tree object <i class="arg">treeName</i> over the tree data in the object
<i class="arg">desttree</i>. The old contents of <i class="arg">desttree</i> are deleted by this
operation.</p>
<p>This operation is in effect equivalent to</p>
<pre class="doctools_example">
<i class="arg">desttree</i> <b class="method">deserialize</b> [<i class="arg">treeName</i> <b class="method">serialize</b>]
</pre>
</dd>
<dt><a name="6"><i class="arg">treeName</i> <b class="method">ancestors</b> <i class="arg">node</i></a></dt>
<dd><p>This method extends the method <b class="method">parent</b> and returns a list
containing all ancestor nodes to the specified <i class="arg">node</i>. The
immediate ancestor, in other words, parent node, is the first element
in that list, its parent the second element, and so on until the root
node is reached, making it the last element of the returned list.</p></dd>
<dt><a name="7"><i class="arg">treeName</i> <b class="method">append</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with an
node. Returns the new value given to the attribute <i class="arg">key</i>.</p></dd>
<dt><a name="8"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i></a></dt>
<dd></dd>
<dt><a name="9"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i> <b class="option">-nodes</b> <i class="arg">list</i></a></dt>
<dd></dd>
<dt><a name="10"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i> <b class="option">-glob</b> <i class="arg">globpattern</i></a></dt>
<dd></dd>
<dt><a name="11"><i class="arg">treeName</i> <b class="method">attr</b> <i class="arg">key</i> <b class="option">-regexp</b> <i class="arg">repattern</i></a></dt>
<dd><p>This method retrieves the value of the attribute named <i class="arg">key</i>, for
all nodes in the tree (matching the restriction specified via one of
the possible options) and having the specified attribute.</p>
<p>The result is a dictionary mapping from node names to the value of
attribute <i class="arg">key</i> at that node.
Nodes not having the attribute <i class="arg">key</i>, or not passing a
specified restriction, are not listed in the result.</p>
<p>The possible restrictions are:</p>
<dl class="doctools_options">
<dt><b class="option">-nodes</b></dt>
<dd><p>The value is a list of nodes. Only the nodes mentioned in this list
are searched for the attribute.</p></dd>
<dt><b class="option">-glob</b></dt>
<dd><p>The value is a glob pattern. Only the nodes in the tree whose names
match this pattern are searched for the attribute.</p></dd>
<dt><b class="option">-regexp</b></dt>
<dd><p>The value is a regular expression. Only the nodes in the tree whose
names match this pattern are searched for the attribute.</p></dd>
</dl></dd>
<dt><a name="12"><i class="arg">treeName</i> <b class="method">children</b> <span class="opt">?<b class="option">-all</b>?</span> <i class="arg">node</i> <span class="opt">?<b class="const">filter</b> <i class="arg">cmdprefix</i>?</span></a></dt>
<dd><p>Return a list of the children of <i class="arg">node</i>.
If the option <b class="option">-all</b> is specified, then not only the direct
children, but their children, and so on are returned in the result.
If a filter command is specified only those nodes are listed in the
final result which pass the test. The command in <i class="arg">cmdprefix</i> is
called with two arguments, the name of the tree object, and the name
of the node in question. It is executed in the context of the caller
and has to return a boolean value. Nodes for which the command returns
<b class="const">false</b> are removed from the result list before it is returned
to the caller.</p>
<p>Some examples:</p>
<pre class="doctools_example">
mytree insert root end 0 ; mytree set 0 volume 30
mytree insert root end 1
mytree insert root end 2
mytree insert 0 end 3
mytree insert 0 end 4
mytree insert 4 end 5 ; mytree set 5 volume 50
mytree insert 4 end 6
proc vol {t n} {
$t keyexists $n volume
}
proc vgt40 {t n} {
if {![$t keyexists $n volume]} {return 0}
expr {[$t get $n volume] > 40}
}
tclsh> lsort [mytree children -all root filter vol]
0 5
tclsh> lsort [mytree children -all root filter vgt40]
5
tclsh> lsort [mytree children root filter vol]
0
tclsh> puts ([lsort [mytree children root filter vgt40]])
()
</pre>
</dd>
<dt><a name="13"><i class="arg">treeName</i> <b class="method">cut</b> <i class="arg">node</i></a></dt>
<dd><p>Removes the node specified by <i class="arg">node</i> from the tree, but not its
children. The children of <i class="arg">node</i> are made children of the parent
of the <i class="arg">node</i>, at the index at which <i class="arg">node</i> was located.</p></dd>
<dt><a name="14"><i class="arg">treeName</i> <b class="method">delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></dt>
<dd><p>Removes the specified nodes from the tree. All of the nodes' children
will be removed as well to prevent orphaned nodes.</p></dd>
<dt><a name="15"><i class="arg">treeName</i> <b class="method">depth</b> <i class="arg">node</i></a></dt>
<dd><p>Return the number of steps from node <i class="arg">node</i> to the root node.</p></dd>
<dt><a name="16"><i class="arg">treeName</i> <b class="method">descendants</b> <i class="arg">node</i> <span class="opt">?<b class="const">filter</b> <i class="arg">cmdprefix</i>?</span></a></dt>
<dd><p>This method extends the method <b class="method">children</b> and returns a list
containing all nodes descending from <i class="arg">node</i>, and passing the
filter, if such was specified.</p>
<p>This is actually the same as
"<i class="arg">treeName</i> <b class="method">children</b> <b class="option">-all</b>".
<b class="method">descendants</b> should be prefered, and "children -all"
will be deprecated sometime in the future.</p></dd>
<dt><a name="17"><i class="arg">treeName</i> <b class="method">deserialize</b> <i class="arg">serialization</i></a></dt>
<dd><p>This is the complement to <b class="method">serialize</b>. It replaces tree data in
<i class="arg">treeName</i> with the tree described by the <i class="arg">serialization</i>
value. The old contents of <i class="arg">treeName</i> are deleted by this
operation.</p></dd>
<dt><a name="18"><i class="arg">treeName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroy the tree, including its storage space and associated command.</p></dd>
<dt><a name="19"><i class="arg">treeName</i> <b class="method">exists</b> <i class="arg">node</i></a></dt>
<dd><p>Returns true if the specified node exists in the tree.</p></dd>
<dt><a name="20"><i class="arg">treeName</i> <b class="method">get</b> <i class="arg">node</i> <i class="arg">key</i></a></dt>
<dd><p>Returns the value associated with the key <i class="arg">key</i> for the node
<i class="arg">node</i>.</p></dd>
<dt><a name="21"><i class="arg">treeName</i> <b class="method">getall</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a dictionary (suitable for use with [<b class="cmd">array set</b>])
containing the attribute data for the <i class="arg">node</i>.
If the glob <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the dictionary.</p></dd>
<dt><a name="22"><i class="arg">treeName</i> <b class="method">keys</b> <i class="arg">node</i> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>Returns a list of keys for the <i class="arg">node</i>.
If the <i class="arg">pattern</i> is specified only the attributes whose names
match the pattern will be part of the returned list. The pattern is a
<b class="cmd">glob</b> pattern.</p></dd>
<dt><a name="23"><i class="arg">treeName</i> <b class="method">keyexists</b> <i class="arg">node</i> <i class="arg">key</i></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the <i class="arg">node</i>.</p></dd>
<dt><a name="24"><i class="arg">treeName</i> <b class="method">index</b> <i class="arg">node</i></a></dt>
<dd><p>Returns the index of <i class="arg">node</i> in its parent's list of children. For
example, if a node has <i class="term">nodeFoo</i>, <i class="term">nodeBar</i>, and
<i class="term">nodeBaz</i> as children, in that order, the index of
<i class="term">nodeBar</i> is 1.</p></dd>
<dt><a name="25"><i class="arg">treeName</i> <b class="method">insert</b> <i class="arg">parent</i> <i class="arg">index</i> <span class="opt">?<i class="arg">child</i> <span class="opt">?<i class="arg">child</i> ...?</span>?</span></a></dt>
<dd><p>Insert one or more nodes into the tree as children of the node
<i class="arg">parent</i>. The nodes will be added in the order they are given. If
<i class="arg">parent</i> is <b class="const">root</b>, it refers to the root of the tree. The
new nodes will be added to the <i class="arg">parent</i> node's child list at the
index given by <i class="arg">index</i>. The <i class="arg">index</i> can be <b class="const">end</b> in
which case the new nodes will be added after the current last child.
Indices of the form "end-<b class="variable">n</b>" are accepted as well.</p>
<p>If any of the specified children already exist in <i class="arg">treeName</i>,
those nodes will be moved from their original location to the new
location indicated by this command.</p>
<p>If no <i class="arg">child</i> is specified, a single node will be added, and a
name will be generated for the new node. The generated name is of the
form <em>node</em><b class="variable">x</b>, where <b class="variable">x</b> is a number. If names are
specified they must neither contain whitespace nor colons (":").</p>
<p>The return result from this command is a list of nodes added.</p></dd>
<dt><a name="26"><i class="arg">treeName</i> <b class="method">isleaf</b> <i class="arg">node</i></a></dt>
<dd><p>Returns true if <i class="arg">node</i> is a leaf of the tree (if <i class="arg">node</i> has no
children), false otherwise.</p></dd>
<dt><a name="27"><i class="arg">treeName</i> <b class="method">lappend</b> <i class="arg">node</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with an <i class="arg">node</i>. Returns the new value given to the
attribute <i class="arg">key</i>.</p></dd>
<dt><a name="28"><i class="arg">treeName</i> <b class="method">leaves</b></a></dt>
<dd><p>Return a list containing all leaf nodes known to the tree.</p></dd>
<dt><a name="29"><i class="arg">treeName</i> <b class="method">move</b> <i class="arg">parent</i> <i class="arg">index</i> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></dt>
<dd><p>Make the specified nodes children of <i class="arg">parent</i>, inserting them into
the parent's child list at the index given by <i class="arg">index</i>. Note that
the command will take all nodes out of the tree before inserting them
under the new parent, and that it determines the position to place
them into after the removal, before the re-insertion. This behaviour
is important when it comes to moving one or more nodes to a different
index without changing their parent node.</p></dd>
<dt><a name="30"><i class="arg">treeName</i> <b class="method">next</b> <i class="arg">node</i></a></dt>
<dd><p>Return the right sibling of <i class="arg">node</i>, or the empty string if
<i class="arg">node</i> was the last child of its parent.</p></dd>
<dt><a name="31"><i class="arg">treeName</i> <b class="method">numchildren</b> <i class="arg">node</i></a></dt>
<dd><p>Return the number of immediate children of <i class="arg">node</i>.</p></dd>
<dt><a name="32"><i class="arg">treeName</i> <b class="method">nodes</b></a></dt>
<dd><p>Return a list containing all nodes known to the tree.</p></dd>
<dt><a name="33"><i class="arg">treeName</i> <b class="method">parent</b> <i class="arg">node</i></a></dt>
<dd><p>Return the parent of <i class="arg">node</i>.</p></dd>
<dt><a name="34"><i class="arg">treeName</i> <b class="method">previous</b> <i class="arg">node</i></a></dt>
<dd><p>Return the left sibling of <i class="arg">node</i>, or the empty string if
<i class="arg">node</i> was the first child of its parent.</p></dd>
<dt><a name="35"><i class="arg">treeName</i> <b class="method">rename</b> <i class="arg">node</i> <i class="arg">newname</i></a></dt>
<dd><p>Renames the node <i class="arg">node</i> to <i class="arg">newname</i>. An error is thrown if
either the node does not exist, or a node with name <i class="arg">newname</i> does
exist. The result of the command is the new name of the node.</p></dd>
<dt><a name="36"><i class="arg">treeName</i> <b class="method">rootname</b></a></dt>
<dd><p>Returns the name of the root node of the tree.</p></dd>
<dt><a name="37"><i class="arg">treeName</i> <b class="method">serialize</b> <span class="opt">?<i class="arg">node</i>?</span></a></dt>
<dd><p>This method serializes the sub-tree starting at <i class="arg">node</i>. In other
words it returns a tcl <em>value</em> completely describing the tree
starting at <i class="arg">node</i>.
This allows, for example, the transfer of tree objects (or parts
thereof) over arbitrary channels, persistence, etc.
This method is also the basis for both the copy constructor and
the assignment operator.</p>
<p>The result of this method has to be semantically identical over all
implementations of the tree interface. This is what will enable us to
copy tree data between different implementations of the same
interface.</p>
<p>The result is a list containing containing a multiple of three
elements. It is like a serialized array except that there are two
values following each key. They are the names of the nodes in the
serialized tree. The two values are a reference to the parent node and
the attribute data, in this order.</p>
<p>The reference to the parent node is the empty string for the root node
of the tree. For all other nodes it is the index of the parent node in
the list. This means that they are integers, greater than or equal to
zero, less than the length of the list, and multiples of three.
The order of the nodes in the list is important insofar as it is used
to reconstruct the lists of children for each node. The children of a
node have to be listed in the serialization in the same order as they
are listed in their parent in the tree.</p>
<p>The attribute data of a node is a dictionary, i.e. a list of even
length containing a serialized array. For a node without attribute
data the dictionary is the empty list.</p>
<p><em>Note:</em> While the current implementation returns the root node as
the first element of the list, followed by its children and their
children in a depth-first traversal this is not necessarily true for
other implementations.
The only information a reader of the serialized data can rely on for
the structure of the tree is that the root node is signaled by the
empty string for the parent reference, that all other nodes refer to
their parent through the index in the list, and that children occur in
the same order as in their parent.</p>
<pre class="doctools_example">
A possible serialization for the tree structure
+- d
+- a -+
root -+- b +- e
+- c
is
{root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}}
The above assumes that none of the nodes have attributes.
</pre>
</dd>
<dt><a name="38"><i class="arg">treeName</i> <b class="method">set</b> <i class="arg">node</i> <i class="arg">key</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with a node. A node may
have any number of keyed values associated with it. If <i class="arg">value</i> is
not specified, this command returns the current value assigned to the
key; if <i class="arg">value</i> is specified, this command assigns that value to
the key, and returns it.</p></dd>
<dt><a name="39"><i class="arg">treeName</i> <b class="method">size</b> <span class="opt">?<i class="arg">node</i>?</span></a></dt>
<dd><p>Return a count of the number of descendants of the node <i class="arg">node</i>; if
no node is specified, <b class="const">root</b> is assumed.</p></dd>
<dt><a name="40"><i class="arg">treeName</i> <b class="method">splice</b> <i class="arg">parent</i> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span> <span class="opt">?<i class="arg">child</i>?</span></a></dt>
<dd><p>Insert a node named <i class="arg">child</i> into the tree as a child of the node
<i class="arg">parent</i>. If <i class="arg">parent</i> is <b class="const">root</b>, it refers to the root
of the tree. The new node will be added to the parent node's child
list at the index given by <i class="arg">from</i>. The children of <i class="arg">parent</i>
which are in the range of the indices <i class="arg">from</i> and <i class="arg">to</i> are made
children of <i class="arg">child</i>. If the value of <i class="arg">to</i> is not specified it
defaults to <b class="const">end</b>. If no name is given for <i class="arg">child</i>, a name
will be generated for the new node. The generated name is of the form
<em>node</em><b class="variable">x</b>, where <b class="variable">x</b> is a number. The return result
from this command is the name of the new node.</p>
<p>The arguments <i class="arg">from</i> and <i class="arg">to</i> are regular list indices, i.e.
the form "end-<b class="variable">n</b>" is accepted as well.</p></dd>
<dt><a name="41"><i class="arg">treeName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></dt>
<dd><p>Swap the position of <i class="arg">node1</i> and <i class="arg">node2</i> in the tree.</p></dd>
<dt><a name="42"><i class="arg">treeName</i> <b class="method">unset</b> <i class="arg">node</i> <i class="arg">key</i></a></dt>
<dd><p>Removes a keyed value from the node <i class="arg">node</i>. The method will do
nothing if the <i class="arg">key</i> does not exist.</p></dd>
<dt><a name="43"><i class="arg">treeName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?<b class="option">-order</b> <i class="arg">order</i>?</span> <span class="opt">?<b class="option">-type</b> <i class="arg">type</i>?</span> <i class="arg">loopvar</i> <i class="arg">script</i></a></dt>
<dd><p>Perform a breadth-first or depth-first walk of the tree starting at
the node <i class="arg">node</i>. The type of walk, breadth-first or depth-first,
is determined by the value of <i class="arg">type</i>; <b class="const">bfs</b> indicates
breadth-first, <b class="const">dfs</b> indicates depth-first. Depth-first is the
default. The order of the walk, pre-, post-, both- or in-order is
determined by the value of <i class="arg">order</i>; <b class="const">pre</b> indicates
pre-order, <b class="const">post</b> indicates post-order, <b class="const">both</b> indicates
both-order and <b class="const">in</b> indicates in-order. Pre-order is the
default.</p>
<p>Pre-order walking means that a parent node is visited before any of
its children. For example, a breadth-first search starting from the
root will visit the root, followed by all of the root's children,
followed by all of the root's grandchildren. Post-order walking means
that a parent node is visited after any of its children. Both-order
walking means that a parent node is visited before <em>and</em> after
any of its children. In-order walking means that a parent node is
visited after its first child and before the second. This is a
generalization of in-order walking for binary trees and will do the
right thing if a binary tree is walked. The combination of a breadth-first
walk with in-order is illegal.</p>
<p>As the walk progresses, the <i class="arg">script</i> will be evaluated at each
node. The evaluation takes place in the context of the caller of the
method.
Regarding loop variables, these are listed in <i class="arg">loopvar</i>. If one
only one variable is specified it will be set to the id of the
node. When two variables are specified, i.e. <i class="arg">loopvar</i> is a true
list, then the first variable will be set to the action performed at
the node, and the other to the id of the node itself.
All loop variables are created in the context of the caller.</p>
<p>There are three possible actions: <b class="const">enter</b>, <b class="const">leave</b>,
or <b class="const">visit</b>. <b class="const">enter</b> actions occur during pre-order
walks; <b class="const">leave</b> actions occur during post-order walks;
<b class="const">visit</b> actions occur during in-order walks. In a both-order
walk, the command will be evaluated twice for each node; the action is
<b class="const">enter</b> for the first evaluation, and <b class="const">leave</b> for the
second.</p>
<p><em>Note</em>: The <b class="const">enter</b> action for a node is always performed
before the walker will look at the children of that node. This means
that changes made by the <i class="arg">script</i> to the children of the node
will immediately influence the walker and the steps it will take.</p>
<p>Any other manipulation, for example of nodes higher in the tree (i.e
already visited), or upon leaving will have undefined results. They
may succeed, error out, silently compute the wrong result, or anything
in between.</p>
<p>At last a small table showing the relationship between the various
options and the possible actions.</p>
<pre class="doctools_example">
order type actions notes
----- ---- ----- -----
pre dfs enter parent before children
post dfs leave parent after children
in dfs visit parent between first and second child.
both dfs enter, leave parent before and after children
----- ---- ----- -----
pre bfs enter parent before children
post bfs leave parent after children
in bfs -- illegal --
both bfs enter, leave parent before and after children
----- ---- ----- -----
</pre>
<p>Note the command <b class="cmd">::struct::tree::prune</b>. This command can be used
in the walk script to force the command to ignore the children of the
node we are currently at. It will throw an error if the order of
traversal is either <b class="const">post</b> or <b class="const">in</b> as these modes visit
the children before their parent, making pruning non-sensical.</p></dd>
<dt><a name="44"><i class="arg">treeName</i> <b class="method">walkproc</b> <i class="arg">node</i> <span class="opt">?<b class="option">-order</b> <i class="arg">order</i>?</span> <span class="opt">?<b class="option">-type</b> <i class="arg">type</i>?</span> <i class="arg">cmdprefix</i></a></dt>
<dd><p>This method is like method <b class="method">walk</b> in all essentials, except the
interface to the user code. This method invokes a command prefix with
three additional arguments (tree, node, and action), instead of
evaluating a script and passing the node via a loop variable.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Changes for 2.0</a></h3>
<p>The following noteworthy changes have occurred:</p>
<ol class="doctools_enumerated">
<li><p>The API for accessing attributes and their values has been
simplified.</p>
<p>All functionality regarding the default attribute "data" has been
removed. This default attribute does not exist anymore. All accesses
to attributes have to specify the name of the attribute in
question. This backward <em>incompatible</em> change allowed us to
simplify the signature of all methods handling attributes.</p>
<p>Especially the flag <b class="option">-key</b> is not required anymore, even more,
its use is now forbidden. Please read the documentation for the
methods <b class="method">set</b>, <b class="method">get</b>, <b class="method">getall</b>, <b class="method">unset</b>,
<b class="method">append</b>, <b class="method">lappend</b>, <b class="method">keyexists</b>
and <b class="method">keys</b> for a description of the new API's.</p></li>
<li><p>The methods <b class="method">keys</b> and <b class="method">getall</b> now take an optional
pattern argument and will return only attribute data for keys matching
this pattern.</p></li>
<li><p>Nodes can now be renamed. See the documentation for the method
<b class="method">rename</b>.</p></li>
<li><p>The structure has been extended with API's for the serialization and
deserialization of tree objects, and a number of operations based on
them (tree assignment, copy construction).</p>
<p>Please read the documentation for the methods <b class="method">serialize</b>,
<b class="method">deserialize</b>, <b class="method">=</b>, and <b class="method">--></b>, and the
documentation on the construction of tree objects.</p>
<p>Beyond the copying of whole tree objects these new API's also enable
the transfer of tree objects over arbitrary channels and for easy
persistence.</p></li>
<li><p>The walker API has been streamlined and made more similar to the
command <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b>. In detail:</p>
<ul class="doctools_itemized">
<li><p>The superfluous option <b class="option">-command</b> has been removed.</p></li>
<li><p>Ditto for the place holders. Instead of the placeholders two loop
variables have to be specified to contain node and action information.</p></li>
<li><p>The old command argument has been documented as a script now, which it
was in the past too.</p></li>
<li><p>The fact that <b class="const">enter</b> actions are called before the walker looks
at the children of a node has been documented now. In other words it
is now officially allowed to manipulate the list of children for a
node under <em>these</em> circumstances. It has been made clear that
changes under any other circumstances will have undefined results,
from silently computing the wrong result to erroring out.</p></li>
</ul>
</li>
<li><p>A new method, <b class="method">attr</b>, was added allowing the query and
retrieval of attribute data without regard to the node relationship.</p></li>
<li><p>The method <b class="method">children</b> has been extended with the ability to
select from the children of the node based on an arbitrary filtering
criterium. Another extension is the ability to look not only at the
immediate children of the node, but the whole tree below it.</p></li>
</ol>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>The following example demonstrates the creation of new nodes:</p>
<pre class="doctools_example">
mytree insert root end 0 ; # Create node 0, as child of the root
mytree insert root end 1 2 ; # Ditto nodes 1 & 2
mytree insert 0 end 3 ; # Now create node 3 as child of node 0
mytree insert 0 end ; # Create another child of 0, with a
# generated name. The name is returned
# as the result of the command.
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: tree</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#breadth_first">breadth-first</a>, <a href="../../../../index.html#depth_first">depth-first</a>, <a href="../../../../index.html#in_order">in-order</a>, <a href="../../../../index.html#node">node</a>, <a href="../../../../index.html#post_order">post-order</a>, <a href="../../../../index.html#pre_order">pre-order</a>, <a href="../../../../index.html#serialization">serialization</a>, <a href="../../../../index.html#tree">tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002-2004,2012 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/struct/struct_tree1.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
|
<div class='fossil-doc' data-title='struct::tree_v1 - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">struct::tree_v1(n) 1.2.2 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>struct::tree_v1 - Create and manipulate tree objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">struct::tree <span class="opt">?1.2.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">treeName</b> <b class="method">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#2"><i class="arg">treeName</i> <b class="method">append</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#3"><i class="arg">treeName</i> <b class="method">children</b> <i class="arg">node</i></a></li>
<li><a href="#4"><i class="arg">treeName</i> <b class="method">cut</b> <i class="arg">node</i></a></li>
<li><a href="#5"><i class="arg">treeName</i> <b class="method">delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></li>
<li><a href="#6"><i class="arg">treeName</i> <b class="method">depth</b> <i class="arg">node</i></a></li>
<li><a href="#7"><i class="arg">treeName</i> <b class="method">destroy</b></a></li>
<li><a href="#8"><i class="arg">treeName</i> <b class="method">exists</b> <i class="arg">node</i></a></li>
<li><a href="#9"><i class="arg">treeName</i> <b class="method">get</b> <i class="arg">node</i> <span class="opt">?<b class="option">-key</b> <i class="arg">key</i>?</span></a></li>
<li><a href="#10"><i class="arg">treeName</i> <b class="method">getall</b> <i class="arg">node</i></a></li>
<li><a href="#11"><i class="arg">treeName</i> <b class="method">keys</b> <i class="arg">node</i></a></li>
<li><a href="#12"><i class="arg">treeName</i> <b class="method">keyexists</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></li>
<li><a href="#13"><i class="arg">treeName</i> <b class="method">index</b> <i class="arg">node</i></a></li>
<li><a href="#14"><i class="arg">treeName</i> <b class="method">insert</b> <i class="arg">parent</i> <i class="arg">index</i> <span class="opt">?<i class="arg">child</i> <span class="opt">?<i class="arg">child</i> ...?</span>?</span></a></li>
<li><a href="#15"><i class="arg">treeName</i> <b class="method">isleaf</b> <i class="arg">node</i></a></li>
<li><a href="#16"><i class="arg">treeName</i> <b class="method">lappend</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#17"><i class="arg">treeName</i> <b class="method">move</b> <i class="arg">parent</i> <i class="arg">index</i> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></li>
<li><a href="#18"><i class="arg">treeName</i> <b class="method">next</b> <i class="arg">node</i></a></li>
<li><a href="#19"><i class="arg">treeName</i> <b class="method">numchildren</b> <i class="arg">node</i></a></li>
<li><a href="#20"><i class="arg">treeName</i> <b class="method">parent</b> <i class="arg">node</i></a></li>
<li><a href="#21"><i class="arg">treeName</i> <b class="method">previous</b> <i class="arg">node</i></a></li>
<li><a href="#22"><i class="arg">treeName</i> <b class="method">set</b> <i class="arg">node</i> <span class="opt">?<b class="option">-key</b> <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#23"><i class="arg">treeName</i> <b class="method">size</b> <span class="opt">?<i class="arg">node</i>?</span></a></li>
<li><a href="#24"><i class="arg">treeName</i> <b class="method">splice</b> <i class="arg">parent</i> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span> <span class="opt">?<i class="arg">child</i>?</span></a></li>
<li><a href="#25"><i class="arg">treeName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></li>
<li><a href="#26"><i class="arg">treeName</i> <b class="method">unset</b> <i class="arg">node</i> <span class="opt">?<b class="option">-key</b> <i class="arg">key</i>?</span></a></li>
<li><a href="#27"><i class="arg">treeName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?<b class="option">-order</b> <i class="arg">order</i>?</span> <span class="opt">?<b class="option">-type</b> <i class="arg">type</i>?</span> <b class="option">-command</b> <i class="arg">cmd</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">::struct::tree</b> command creates a new tree object with an
associated global Tcl command whose name is <i class="arg">treeName</i>. This
command may be used to invoke various operations on the tree. It has
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">treeName</b> <b class="method">option</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>A tree is a collection of named elements, called nodes, one of which is
distinguished as a root, along with a relation ("parenthood") that
places a hierarchical structure on the nodes. (Data Structures and
Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987). In
addition to maintaining the node relationships, this tree
implementation allows any number of keyed values to be associated with
each node.</p>
<p>The element names can be arbitrary strings.</p>
<p>A tree is thus similar to an array, but with three important
differences:</p>
<ol class="doctools_enumerated">
<li><p>Trees are accessed through an object command, whereas arrays are
accessed as variables. (This means trees cannot be local to a procedure.)</p></li>
<li><p>Trees have a hierarchical structure, whereas an array is just an
unordered collection.</p></li>
<li><p>Each node of a tree has a separate collection of attributes and
values. This is like an array where every value is a dictionary.</p></li>
</ol>
<p>The following commands are possible for tree objects:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">treeName</i> <b class="method">append</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> to one of the keyed values associated with an
node. If no <i class="arg">key</i> is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="3"><i class="arg">treeName</i> <b class="method">children</b> <i class="arg">node</i></a></dt>
<dd><p>Return a list of the children of <i class="arg">node</i>.</p></dd>
<dt><a name="4"><i class="arg">treeName</i> <b class="method">cut</b> <i class="arg">node</i></a></dt>
<dd><p>Removes the node specified by <i class="arg">node</i> from the tree, but not its
children. The children of <i class="arg">node</i> are made children of the parent
of the <i class="arg">node</i>, at the index at which <i class="arg">node</i> was located.</p></dd>
<dt><a name="5"><i class="arg">treeName</i> <b class="method">delete</b> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></dt>
<dd><p>Removes the specified nodes from the tree. All of the nodes' children
will be removed as well to prevent orphaned nodes.</p></dd>
<dt><a name="6"><i class="arg">treeName</i> <b class="method">depth</b> <i class="arg">node</i></a></dt>
<dd><p>Return the number of steps from node <i class="arg">node</i> to the root node.</p></dd>
<dt><a name="7"><i class="arg">treeName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroy the tree, including its storage space and associated command.</p></dd>
<dt><a name="8"><i class="arg">treeName</i> <b class="method">exists</b> <i class="arg">node</i></a></dt>
<dd><p>Returns true if the specified node exists in the tree.</p></dd>
<dt><a name="9"><i class="arg">treeName</i> <b class="method">get</b> <i class="arg">node</i> <span class="opt">?<b class="option">-key</b> <i class="arg">key</i>?</span></a></dt>
<dd><p>Return the value associated with the key <i class="arg">key</i> for the node
<i class="arg">node</i>. If no key is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="10"><i class="arg">treeName</i> <b class="method">getall</b> <i class="arg">node</i></a></dt>
<dd><p>Returns a serialized list of key/value pairs (suitable for use with
[<b class="cmd">array set</b>]) for the <i class="arg">node</i>.</p></dd>
<dt><a name="11"><i class="arg">treeName</i> <b class="method">keys</b> <i class="arg">node</i></a></dt>
<dd><p>Returns a list of keys for the <i class="arg">node</i>.</p></dd>
<dt><a name="12"><i class="arg">treeName</i> <b class="method">keyexists</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span></a></dt>
<dd><p>Return true if the specified <i class="arg">key</i> exists for the <i class="arg">node</i>. If
no <i class="arg">key</i> is specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="13"><i class="arg">treeName</i> <b class="method">index</b> <i class="arg">node</i></a></dt>
<dd><p>Returns the index of <i class="arg">node</i> in its parent's list of children. For
example, if a node has <i class="term">nodeFoo</i>, <i class="term">nodeBar</i>, and
<i class="term">nodeBaz</i> as children, in that order, the index of
<i class="term">nodeBar</i> is 1.</p></dd>
<dt><a name="14"><i class="arg">treeName</i> <b class="method">insert</b> <i class="arg">parent</i> <i class="arg">index</i> <span class="opt">?<i class="arg">child</i> <span class="opt">?<i class="arg">child</i> ...?</span>?</span></a></dt>
<dd><p>Insert one or more nodes into the tree as children of the node
<i class="arg">parent</i>. The nodes will be added in the order they are given. If
<i class="arg">parent</i> is <b class="const">root</b>, it refers to the root of the tree. The
new nodes will be added to the <i class="arg">parent</i> node's child list at the
index given by <i class="arg">index</i>. The <i class="arg">index</i> can be <b class="const">end</b> in
which case the new nodes will be added after the current last child.</p>
<p>If any of the specified children already exist in <i class="arg">treeName</i>,
those nodes will be moved from their original location to the new
location indicated by this command.</p>
<p>If no <i class="arg">child</i> is specified, a single node will be added, and a
name will be generated for the new node. The generated name is of the
form <em>node</em><b class="variable">x</b>, where <b class="variable">x</b> is a number. If names are
specified they must neither contain whitespace nor colons (":").</p>
<p>The return result from this command is a list of nodes added.</p></dd>
<dt><a name="15"><i class="arg">treeName</i> <b class="method">isleaf</b> <i class="arg">node</i></a></dt>
<dd><p>Returns true if <i class="arg">node</i> is a leaf of the tree (if <i class="arg">node</i> has no
children), false otherwise.</p></dd>
<dt><a name="16"><i class="arg">treeName</i> <b class="method">lappend</b> <i class="arg">node</i> <span class="opt">?-key <i class="arg">key</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Appends a <i class="arg">value</i> (as a list) to one of the keyed values
associated with an <i class="arg">node</i>. If no <i class="arg">key</i> is specified, the key
<b class="const">data</b> is assumed.</p></dd>
<dt><a name="17"><i class="arg">treeName</i> <b class="method">move</b> <i class="arg">parent</i> <i class="arg">index</i> <i class="arg">node</i> <span class="opt">?<i class="arg">node</i> ...?</span></a></dt>
<dd><p>Make the specified nodes children of <i class="arg">parent</i>, inserting them into
the parent's child list at the index given by <i class="arg">index</i>. Note that
the command will take all nodes out of the tree before inserting them
under the new parent, and that it determines the position to place
them into after the removal, before the re-insertion. This behaviour
is important when it comes to moving one or more nodes to a different
index without changing their parent node.</p></dd>
<dt><a name="18"><i class="arg">treeName</i> <b class="method">next</b> <i class="arg">node</i></a></dt>
<dd><p>Return the right sibling of <i class="arg">node</i>, or the empty string if
<i class="arg">node</i> was the last child of its parent.</p></dd>
<dt><a name="19"><i class="arg">treeName</i> <b class="method">numchildren</b> <i class="arg">node</i></a></dt>
<dd><p>Return the number of immediate children of <i class="arg">node</i>.</p></dd>
<dt><a name="20"><i class="arg">treeName</i> <b class="method">parent</b> <i class="arg">node</i></a></dt>
<dd><p>Return the parent of <i class="arg">node</i>.</p></dd>
<dt><a name="21"><i class="arg">treeName</i> <b class="method">previous</b> <i class="arg">node</i></a></dt>
<dd><p>Return the left sibling of <i class="arg">node</i>, or the empty string if
<i class="arg">node</i> was the first child of its parent.</p></dd>
<dt><a name="22"><i class="arg">treeName</i> <b class="method">set</b> <i class="arg">node</i> <span class="opt">?<b class="option">-key</b> <i class="arg">key</i>?</span> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p>Set or get one of the keyed values associated with a node. If no key
is specified, the key <b class="const">data</b> is assumed. Each node that is
added to a tree has the value "" assigned to the key <b class="const">data</b>
automatically. A node may have any number of keyed values associated
with it. If <i class="arg">value</i> is not specified, this command returns the
current value assigned to the key; if <i class="arg">value</i> is specified, this
command assigns that value to the key.</p></dd>
<dt><a name="23"><i class="arg">treeName</i> <b class="method">size</b> <span class="opt">?<i class="arg">node</i>?</span></a></dt>
<dd><p>Return a count of the number of descendants of the node <i class="arg">node</i>; if
no node is specified, <b class="const">root</b> is assumed.</p></dd>
<dt><a name="24"><i class="arg">treeName</i> <b class="method">splice</b> <i class="arg">parent</i> <i class="arg">from</i> <span class="opt">?<i class="arg">to</i>?</span> <span class="opt">?<i class="arg">child</i>?</span></a></dt>
<dd><p>Insert a node named <i class="arg">child</i> into the tree as a child of the node
<i class="arg">parent</i>. If <i class="arg">parent</i> is <b class="const">root</b>, it refers to the root
of the tree. The new node will be added to the parent node's child
list at the index given by <i class="arg">from</i>. The children of <i class="arg">parent</i>
which are in the range of the indices <i class="arg">from</i> and <i class="arg">to</i> are made
children of <i class="arg">child</i>. If the value of <i class="arg">to</i> is not specified it
defaults to <b class="const">end</b>. If no name is given for <i class="arg">child</i>, a name
will be generated for the new node. The generated name is of the form
<em>node</em><b class="variable">x</b>, where <b class="variable">x</b> is a number. The return result
from this command is the name of the new node.</p></dd>
<dt><a name="25"><i class="arg">treeName</i> <b class="method">swap</b> <i class="arg">node1</i> <i class="arg">node2</i></a></dt>
<dd><p>Swap the position of <i class="arg">node1</i> and <i class="arg">node2</i> in the tree.</p></dd>
<dt><a name="26"><i class="arg">treeName</i> <b class="method">unset</b> <i class="arg">node</i> <span class="opt">?<b class="option">-key</b> <i class="arg">key</i>?</span></a></dt>
<dd><p>Removes a keyed value from the node <i class="arg">node</i>. If no key is
specified, the key <b class="const">data</b> is assumed.</p></dd>
<dt><a name="27"><i class="arg">treeName</i> <b class="method">walk</b> <i class="arg">node</i> <span class="opt">?<b class="option">-order</b> <i class="arg">order</i>?</span> <span class="opt">?<b class="option">-type</b> <i class="arg">type</i>?</span> <b class="option">-command</b> <i class="arg">cmd</i></a></dt>
<dd><p>Perform a breadth-first or depth-first walk of the tree starting at
the node <i class="arg">node</i>. The type of walk, breadth-first or depth-first,
is determined by the value of <i class="arg">type</i>; <b class="const">bfs</b> indicates
breadth-first, <b class="const">dfs</b> indicates depth-first. Depth-first is the
default. The order of the walk, pre-, post-, both- or in-order is
determined by the value of <i class="arg">order</i>; <b class="const">pre</b> indicates
pre-order, <b class="const">post</b> indicates post-order, <b class="const">both</b> indicates
both-order and <b class="const">in</b> indicates in-order. Pre-order is the
default.</p>
<p>Pre-order walking means that a parent node is visited before any of
its children. For example, a breadth-first search starting from the
root will visit the root, followed by all of the root's children,
followed by all of the root's grandchildren. Post-order walking means
that a parent node is visited after any of its children. Both-order
walking means that a parent node is visited before <em>and</em> after
any of its children. In-order walking means that a parent node is
visited after its first child and before the second. This is a
generalization of in-order walking for binary trees and will do the
right thing if a binary is walked. The combination of a breadth-first
walk with in-order is illegal.</p>
<p>As the walk progresses, the command <i class="arg">cmd</i> will be evaluated at
each node. Percent substitution will be performed on <i class="arg">cmd</i> before
evaluation, just as in a <b class="cmd"><a href="../../../../index.html#bind">bind</a></b> script. The following
substitutions are recognized:</p>
<dl class="doctools_definitions">
<dt><b class="const">%%</b></dt>
<dd><p>Insert the literal % character.</p></dd>
<dt><b class="const">%t</b></dt>
<dd><p>Name of the tree object.</p></dd>
<dt><b class="const">%n</b></dt>
<dd><p>Name of the current node.</p></dd>
<dt><b class="const">%a</b></dt>
<dd><p>Name of the action occurring; one of <b class="const">enter</b>, <b class="const">leave</b>,
or <b class="const">visit</b>. <b class="const">enter</b> actions occur during pre-order
walks; <b class="const">leave</b> actions occur during post-order walks;
<b class="const">visit</b> actions occur during in-order walks. In a both-order
walk, the command will be evaluated twice for each node; the action is
<b class="const">enter</b> for the first evaluation, and <b class="const">leave</b> for the
second.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>struct :: tree</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tree">tree</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2002 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tar/tar.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
<div class='fossil-doc' data-title='tar - Tar file handling'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tar(n) 0.11 tcllib "Tar file handling"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tar - Tar file creation, extraction & manipulation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">tar <span class="opt">?0.11?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tar::contents</b> <i class="arg">tarball</i> <span class="opt">?<b class="option">-chan</b>?</span></a></li>
<li><a href="#2"><b class="cmd">::tar::stat</b> <i class="arg">tarball</i> <span class="opt">?file?</span> <span class="opt">?<b class="option">-chan</b>?</span></a></li>
<li><a href="#3"><b class="cmd">::tar::untar</b> <i class="arg">tarball</i> <i class="arg">args</i></a></li>
<li><a href="#4"><b class="cmd">::tar::get</b> <i class="arg">tarball</i> <i class="arg">fileName</i> <span class="opt">?<b class="option">-chan</b>?</span></a></li>
<li><a href="#5"><b class="cmd">::tar::create</b> <i class="arg">tarball</i> <i class="arg">files</i> <i class="arg">args</i></a></li>
<li><a href="#6"><b class="cmd">::tar::add</b> <i class="arg">tarball</i> <i class="arg">files</i> <i class="arg">args</i></a></li>
<li><a href="#7"><b class="cmd">::tar::remove</b> <i class="arg">tarball</i> <i class="arg">files</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Note: Starting with version 0.8 the tar reader commands
(contents, stats, get, untar) support the GNU LongName extension
(header type 'L') for large paths.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tar::contents</b> <i class="arg">tarball</i> <span class="opt">?<b class="option">-chan</b>?</span></a></dt>
<dd><p>Returns a list of the files contained in <i class="arg">tarball</i>. The order is not sorted and depends on the order
files were stored in the archive.</p>
<p>If the option <b class="option">-chan</b> is present <i class="arg">tarball</i> is interpreted as an open channel.
It is assumed that the channel was opened for reading, and configured for binary input.
The command will <em>not</em> close the channel.</p></dd>
<dt><a name="2"><b class="cmd">::tar::stat</b> <i class="arg">tarball</i> <span class="opt">?file?</span> <span class="opt">?<b class="option">-chan</b>?</span></a></dt>
<dd><p>Returns a nested dict containing information on the named <span class="opt">?file?</span> in <i class="arg">tarball</i>,
or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys
"<b class="const">mode</b> <b class="const">uid</b> <b class="const">gid</b> <b class="const">size</b> <b class="const">mtime</b> <b class="const">type</b> <b class="const">linkname</b> <b class="const">uname</b> <b class="const">gname</b>
<b class="const">devmajor</b> <b class="const">devminor</b>"</p>
<pre class="doctools_example">
% ::tar::stat tarball.tar
foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
</pre>
<p>If the option <b class="option">-chan</b> is present <i class="arg">tarball</i> is interpreted as an open channel.
It is assumed that the channel was opened for reading, and configured for binary input.
The command will <em>not</em> close the channel.</p></dd>
<dt><a name="3"><b class="cmd">::tar::untar</b> <i class="arg">tarball</i> <i class="arg">args</i></a></dt>
<dd><p>Extracts <i class="arg">tarball</i>. <i class="arg">-file</i> and <i class="arg">-glob</i> limit the extraction
to files which exactly match or pattern match the given argument. No error is
thrown if no files match. Returns a list of filenames extracted and the file
size. The size will be null for non regular files. Leading path seperators are
stripped so paths will always be relative.</p>
<dl class="doctools_options">
<dt><b class="option">-dir</b> dirName</dt>
<dd><p>Directory to extract to. Uses <b class="cmd">pwd</b> if none is specified</p></dd>
<dt><b class="option">-file</b> fileName</dt>
<dd><p>Only extract the file with this name. The name is matched against the complete path
stored in the archive including directories.</p></dd>
<dt><b class="option">-glob</b> pattern</dt>
<dd><p>Only extract files patching this glob style pattern. The pattern is matched against the complete path
stored in the archive.</p></dd>
<dt><b class="option">-nooverwrite</b></dt>
<dd><p>Dont overwrite files that already exist</p></dd>
<dt><b class="option">-nomtime</b></dt>
<dd><p>Leave the file modification time as the current time instead of setting it to the value in the archive.</p></dd>
<dt><b class="option">-noperms</b></dt>
<dd><p>In Unix, leave the file permissions as the current umask instead of setting them to the values in the archive.</p></dd>
<dt><b class="option">-chan</b></dt>
<dd><p>If this option is present <i class="arg">tarball</i> is interpreted as an open channel.
It is assumed that the channel was opened for reading, and configured for binary input.
The command will <em>not</em> close the channel.</p></dd>
</dl>
<pre class="doctools_example">
% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
puts "Extracted $file ($size bytes)"
}
</pre>
</dd>
<dt><a name="4"><b class="cmd">::tar::get</b> <i class="arg">tarball</i> <i class="arg">fileName</i> <span class="opt">?<b class="option">-chan</b>?</span></a></dt>
<dd><p>Returns the contents of <i class="arg">fileName</i> from the <i class="arg">tarball</i>.</p>
<pre class="doctools_example">
% set readme [::tar::get tarball.tar doc/README] {
% puts $readme
}
</pre>
<p>If the option <b class="option">-chan</b> is present <i class="arg">tarball</i> is
interpreted as an open channel. It is assumed that the channel was
opened for reading, and configured for binary input. The command will
<em>not</em> close the channel.</p>
<p>An error is thrown when <i class="arg">fileName</i> is not found in the tar
archive.</p></dd>
<dt><a name="5"><b class="cmd">::tar::create</b> <i class="arg">tarball</i> <i class="arg">files</i> <i class="arg">args</i></a></dt>
<dd><p>Creates a new tar file containing the <i class="arg">files</i>. <i class="arg">files</i> must be specified
as a single argument which is a proper list of filenames.</p>
<dl class="doctools_options">
<dt><b class="option">-dereference</b></dt>
<dd><p>Normally <b class="cmd">create</b> will store links as an actual link pointing at a file that may
or may not exist in the archive. Specifying this option will cause the actual file point to
by the link to be stored instead.</p></dd>
<dt><b class="option">-chan</b></dt>
<dd><p>If this option is present <i class="arg">tarball</i> is interpreted as an open channel.
It is assumed that the channel was opened for writing, and configured for binary output.
The command will <em>not</em> close the channel.</p></dd>
</dl>
<pre class="doctools_example">
% ::tar::create new.tar [glob -nocomplain file*]
% ::tar::contents new.tar
file1 file2 file3
</pre>
</dd>
<dt><a name="6"><b class="cmd">::tar::add</b> <i class="arg">tarball</i> <i class="arg">files</i> <i class="arg">args</i></a></dt>
<dd><p>Appends <i class="arg">files</i> to the end of the existing <i class="arg">tarball</i>. <i class="arg">files</i> must be specified
as a single argument which is a proper list of filenames.</p>
<dl class="doctools_options">
<dt><b class="option">-dereference</b></dt>
<dd><p>Normally <b class="cmd">add</b> will store links as an actual link pointing at a file that may
or may not exist in the archive. Specifying this option will cause the actual file point to
by the link to be stored instead.</p></dd>
<dt><b class="option">-prefix</b> string</dt>
<dd><p>Normally <b class="cmd">add</b> will store files under exactly the name specified as
argument. Specifying a <span class="opt">?-prefix?</span> causes the <i class="arg">string</i> to be
prepended to every name.</p></dd>
<dt><b class="option">-quick</b></dt>
<dd><p>The only sure way to find the position in the <i class="arg">tarball</i> where new
files can be added is to read it from start, but if <i class="arg">tarball</i> was
written with a "blocksize" of 1 (as this package does) then one can
alternatively find this position by seeking from the end. The
<span class="opt">?-quick?</span> option tells <b class="cmd">add</b> to do the latter.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">::tar::remove</b> <i class="arg">tarball</i> <i class="arg">files</i></a></dt>
<dd><p>Removes <i class="arg">files</i> from the <i class="arg">tarball</i>. No error will result if the file does not exist in the
tarball. Directory write permission and free disk space equivalent to at least the size of the tarball
will be needed.</p>
<pre class="doctools_example">
% ::tar::remove new.tar {file2 file3}
% ::tar::contents new.tar
file3
</pre>
</dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tar</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#archive">archive</a>, <a href="../../../../index.html#tape_archive">tape archive</a>, <a href="../../../../index.html#tar">tar</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File formats</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
|
<div class='fossil-doc' data-title='tepam::argument_dialogbox - Tcl's Enhanced Procedure and Argument Manager'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tepam::argument_dialogbox(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">ARGUMENT DIALOGBOX CALL</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Context Definition Items</a></li>
<li class="doctools_subsection"><a href="#subsection2">Formatting and Display Options</a></li>
<li class="doctools_subsection"><a href="#subsection3">Global Custom Data Validation</a></li>
<li class="doctools_subsection"><a href="#subsection4">Data Entry Widget Items</a></li>
<li class="doctools_subsection"><a href="#subsection5">Entry Widget Item Attributes</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">APPLICATION SPECIFIC ENTRY WIDGETS</a></li>
<li class="doctools_section"><a href="#section4">VARIABLES</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">Tk 8.3</b></li>
<li>package require <b class="pkgname">tepam <span class="opt">?0.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">tepam::argument_dialogbox</b> <i class="arg">item_name item_attributes <span class="opt">?item_name item_attributes?</span> <span class="opt">?...?</span></i></a></li>
<li><a href="#2"><b class="cmd">tepam::argument_dialogbox</b> {<i class="arg">item_name item_attributes <span class="opt">?item_name item_attributes?</span> <span class="opt">?...?</span></i>}</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">ARGUMENT DIALOGBOX CALL</a></h2>
<p>The TEPAM <b class="cmd">argument_dialogbox</b> is a flexible and easily usable data entry form generator that is available if Tk has been loaded. Each data entry element of a form is defined via a <em>data entry item</em> that can be provided to <b class="cmd">argument_dialogbox</b> in two formats:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">tepam::argument_dialogbox</b> <i class="arg">item_name item_attributes <span class="opt">?item_name item_attributes?</span> <span class="opt">?...?</span></i></a></dt>
<dd><p>Using this first format, each <em>data entry item</em> is defined via a pair of two arguments. The first one is the <em>item name</em> that defines the entry widget that has to be used in the form. The second argument, called <em>item attributes</em>, specifies the variable which is attributed to the data entry element as well as eventual formatting and context information.</p>
<p>The <b class="cmd">argument_dialogbox</b> returns <b class="const">ok</b> if the entered data have been acknowledged (via the <em>OK</em> button) and validated by a data checker. If the entered data have been rejected (via the <em>Cancel</em> button) the <b class="cmd">argument_dialogbox</b> returns <b class="const">cancel</b>.</p>
<p>A small example illustrates how the <b class="cmd">argument_dialogbox</b> can be employed:</p>
<pre class="doctools_example">set DialogResult [<b class="cmd">tepam::argument_dialogbox</b> \
<b class="cmd">-title</b> "Itinerary selection" \
<b class="cmd">-file</b> {<i class="arg">-label "Itinerary report" -variable report_file</i>} \
<b class="cmd">-frame</b> {<i class="arg">-label "Itinerary start"</i>} \
<b class="cmd">-comment</b> {<i class="arg">-text "Specify your itinerary start location"</i>} \
<b class="cmd">-entry</b> {<i class="arg">-label "City" -variable start_city -type string</i>} \
<b class="cmd">-entry</b> {<i class="arg">-label "Street" -variable start_street -type string -optional 1</i>} \
<b class="cmd">-entry</b> {<i class="arg">-label "Street number" -variable start_street_nbr -type integer -optional 1</i>} \
<b class="cmd">-frame</b> {<i class="arg">-label "Itinerary destination"</i>} \
<b class="cmd">-comment</b> {<i class="arg">-text "Specify your itinerary destination"</i>} \
<b class="cmd">-entry</b> {<i class="arg">-label "City" -variable dest_city -type string</i>} \
<b class="cmd">-entry</b> {<i class="arg">-label "Street" -variable dest_street -type string -optional 1</i>} \
<b class="cmd">-entry</b> {<i class="arg">-label "Street number" -variable dest_street_nbr -type integer -optional 1</i>} \
<b class="cmd">-frame</b> {} \
<b class="cmd">-checkbutton</b> {<i class="arg">-label "Don't use highways" -variable no_highway</i>}]</pre>
<p>This example opens a dialog box that has the title <em>Itinerary selection</em>. A first entry widget in this box allows selecting a report file. It follows two frames to define respectively an itinerary start and end location. Each of these locations that are described with a comment has three entry widgets to specify respectively the city, street and the street number. Bellow the second frame there is a check button that allows specifying if eventual highways should be ignored.</p></dd>
<dt><a name="2"><b class="cmd">tepam::argument_dialogbox</b> {<i class="arg">item_name item_attributes <span class="opt">?item_name item_attributes?</span> <span class="opt">?...?</span></i>}</a></dt>
<dd><p>Sometimes it is simpler to provide all the data entry item definitions in form of a single list to <b class="cmd">argument_dialogbox</b>, and not as individual arguments. The second format that is supported by <b class="cmd">argument_dialogbox</b> corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to <b class="cmd">argument_dialogbox</b>. The previous example can therefore also be written in the following way:</p>
<pre class="doctools_example">set DialogResult [<b class="cmd">tepam::argument_dialogbox {</b>
<b class="cmd">-title</b> "Itinerary selection"
<b class="cmd">-file</b> {<i class="arg">-label "Itinerary report" -variable report_file</i>}
...
<b class="cmd">-checkbutton</b> {<i class="arg">-label "Don't use highways" -variable no_highway</i>} <b class="cmd">}</b>]</pre>
</dd>
</dl>
<p>The commands <b class="cmd">argument_dialogbox</b> as well as <b class="cmd"><a href="../../../../index.html#procedure">procedure</a></b> are exported from the namespace <b class="namespace">tepam</b>. To use these commands without the <b class="namespace">tepam::</b> namespace prefix, it is sufficient to import them into the main namespace:</p>
<pre class="doctools_example"><b class="cmd">namespace import tepam::*</b>
set DialogResult [<b class="cmd">argument_dialogbox</b> \
-title "Itinerary selection"
...</pre>
<p>The following subsections explain the different argument item types that are accepted by the <b class="cmd">argument_dialogbox</b>, classified into three groups. The first data entry item definition format will be used in the remaining document, knowing that this format can always be transformed into the second format by putting all arguments into a single list that is then provided to <b class="cmd">argument_dialogbox</b>.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Context Definition Items</a></h3>
<p>The first item group allows specifying some context aspects of an argument dialog box. These items are taking a simple character string as item attribute:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-<argument_name></b> <i class="arg">string</i> \
...</pre>
<p>The following items are classified into this group:</p>
<dl class="doctools_definitions">
<dt>-title <i class="arg">string</i></dt>
<dd><p>The dialog box window title which is by default <em>Dialog</em> can be changed with the <em>-title</em> item:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-title</b> "System configuration" \
...</pre>
</dd>
<dt>-window <i class="arg">string</i></dt>
<dd><p>The argument dialog box uses by default <em>.dialog</em> as dialog top level window. This path can be changed with the <em>-window</em> item:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-window</b> .dialog \
...</pre>
</dd>
<dt>-parent <i class="arg">string</i></dt>
<dd><p>By defining a parent window, the argument dialog box will be displayed beside this one. Without explicit parent window definition, the top-level window will be considered as parent window.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-parent</b> .my_appl \
...</pre>
</dd>
<dt>-context <i class="arg">string</i></dt>
<dd><p>If a context is defined the dialog box state, e.g. the entered data as well as the window size and position, is restored the next time the argument dialog box is called. The assignment of a context allows saving the dialog box state in its context to distinguish between different usages of the argument dialog box.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-context</b> destination_definitions \
...</pre>
</dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Formatting and Display Options</a></h3>
<p>Especially for big, complex forms it becomes important that the different data entry widgets are graphically well organized and commented to provide an immediate and clear overview to the user. A couple of items allow structuring and commenting the dialog boxes.</p>
<p>The items of this classification group require as item attributes a definition list, which contains itself attribute name and value pairs:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-<argument_name></b> { <i class="arg">
<span class="opt">?-<attribute_name> <attribute_value>?</span>
<span class="opt">?-<attribute_name> <attribute_value>?</span>
<span class="opt">?...?</span></i>
}
...</pre>
<p>The following items are classified into this group:</p>
<dl class="doctools_definitions">
<dt>-frame <i class="arg">list</i></dt>
<dd><p>The <em>-frame</em> item allows packing all following entry widgets into a labeled frame, until a next frame item is defined or until the last entry widget has been defined. It recognizes the following attributes inside the item attribute list:</p>
<dl class="doctools_definitions">
<dt>-label <i class="arg">string</i></dt>
<dd><p>An optional frame label can be specified with the <i class="arg">-label</i> statement.</p></dd>
</dl>
<p>Example:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-frame</b> {<i class="arg">-label "Destination address"</i>}
...</pre>
<p>To close an open frame without opening a new one, an empty list has to be provided to the <i class="arg">-frame</i> statement.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-frame</b> {}
...</pre>
</dd>
<dt>-sep [const {{}}]</dt>
<dd><p>Entry widgets can be separated with the <i class="arg">-sep</i> statement which doesn't require additional definitions. The related definition list has to exist, but its content is ignored.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-sep</b> {}
...</pre>
</dd>
<dt>-comment <i class="arg">string</i></dt>
<dd><p>Comments and descriptions can be added with the <i class="arg">-text</i> attribute of the <i class="arg">-comment</i> item. Please note that each entry widget itself can also contain a <i class="arg">-text</i> attribute for comments and descriptions. But the <i class="arg">-comment</i> item allows for example adding a description between two frames.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-comment</b> {<i class="arg">-text "Specify bellow the destination address"</i>}
...</pre>
</dd>
<dt>-yscroll <b class="const">0</b>|<b class="const">1</b>|<b class="const">auto</b></dt>
<dd><p>This attribute allows controlling an eventual vertical scrollbar. Setting it to <b class="const">0</b> will permanently disable the scrollbar, setting it to <b class="const">1</b> will enable it. By default it is set to <b class="const">auto</b>. The scrollbar is enabled in this mode only if the vertical data entry form size exceeds 66% of the screen height.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-yscroll</b> <b class="const">auto</b>
...</pre>
</dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Global Custom Data Validation</a></h3>
<p>This item group allows specifying global custom checks to validate the entered data.</p>
<dl class="doctools_definitions">
<dt>-validatecommand <i class="arg">script</i></dt>
<dd><p>Custom data checks can be performed via validation commands that are defined with the <i class="arg">-validatecommand</i> item. Example:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-entry {-label "Your comment" -variable YourCom} \
<b class="cmd">-validatecommand</b> {IllegalWordDetector $YourCom}</pre>
<p>The validation command is executed in the context of the calling procedure, once all the basic data checks have been performed and data variables are assigned. All data is accessed via the data variables. Note that there is also an entry widget specific attribute <i class="arg">-validatecommand</i> that allows declaring custom checks for specific data entries.</p>
<p>The attribute <i class="arg">-validatecommand</i> can be repeated to declare multiple custom checks.</p></dd>
<dt>-validatecommand_error_text <i class="arg">string</i></dt>
<dd><p>This item allows overriding the default error message for a global custom argument validation (defined by <i class="arg">-validatecommand</i>). Also this attribute can be repeated in case multiple checks are declared.</p></dd>
<dt>-validatecommand2 <i class="arg">script</i></dt>
<dd></dd>
<dt>-validatecommand2_error_text <i class="arg">string</i></dt>
<dd><p>These items are mainly for TEPAM internal usage.</p>
<p>These items corrspond respectively to <i class="arg">-validatecommand</i> and <i class="arg">-validatecommand_error_text</i>. However, the data validation is not performed in the next upper stack level, but two stack levels higher.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Data Entry Widget Items</a></h3>
<p>Data entry widgets are created with the widget items. These items require as item attributes a definition list, which contains itself attribute name and value pairs:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
...
<b class="cmd">-<argument_name></b> { <i class="arg">
<span class="opt">?-<attribute_name> <attribute_value>?</span>
<span class="opt">?-<attribute_name> <attribute_value>?</span>
<span class="opt">?...?</span></i>
}
...</pre>
<p>The attribute list can contain various attributes to describe and comment an entry widget and to constrain its entered value. All entry widgets are accepting a common set of attributes that are described in the section <span class="sectref"><a href="#subsection5">Entry Widget Item Attributes</a></span>.</p>
<p>TEPAM defines a rich set of entry widgets. If necessary, this set can be extended with additional application specific entry widgets (see <span class="sectref"><a href="#section3">APPLICATION SPECIFIC ENTRY WIDGETS</a></span>):</p>
<dl class="doctools_definitions">
<dt>-entry <i class="arg">list</i></dt>
<dd><p>The <i class="arg">-entry</i> item generates the simplest but most universal data entry widget. It allows entering any kind of data in form of single line strings.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-entry</b> {-label Name -variable Entry}</pre>
</dd>
<dt>-text <i class="arg">list</i></dt>
<dd><p>The <i class="arg">-text</i> item generates a multi line text entry widget. The widget height can be selected with the <i class="arg">-height</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-text</b> {-label Name -variable Text -height 5}</pre>
</dd>
<dt>-checkbox <i class="arg">list</i></dt>
<dd><p>A group of check boxes is created with the <i class="arg">-checkbox</i> item. The number of check boxes and their option values are specified with a list assigned to the <i class="arg">-choices</i> attribute or via a variable declared with the <i class="arg">-choicevariable</i> attribute:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-checkbox</b> {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} -default italic}</pre>
<p>If the labels of the check boxes should differ from the option values, their labels can be defined with the <i class="arg">-choicelabels</i> attribute:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-checkbox</b> {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} \
-choicelabels {Bold Italic Underline} \
-default italic}</pre>
<p>In contrast to a radio box group, a check box group allows selecting simultaneously several choice options. The selection is stored for this reason inside the defined variable in form of a list, even if only one choice option has been selected.</p></dd>
<dt>-radiobox <i class="arg">list</i></dt>
<dd><p>A group of radio boxes is created with the <i class="arg">-radiobox</i> item. The number of radio boxes and their option values are specified with a list assigned to the <i class="arg">-choices</i> attribute or via a variable declared with the <i class="arg">-choicevariable</i> attribute.</p>
<p>In contrast to a check box group, a radio box group allows selecting simultaneously only one choice option. The selected option value is stored directly, and not in form of a list, inside the defined variable.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-radiobox</b> {-label "Text adjustment" -variable Adjustment \
-choices {left center right} -default left}</pre>
<p>If the labels of the radio boxes should differ from the option values, their labels can be defined with the <i class="arg">-choicelabels</i> attribute:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-radiobox</b> {-label "Text adjustment" -variable Adjustment \
-choices {left center right} \
-choicelabels {Left Center Right} -default left}</pre>
</dd>
<dt>-checkbutton <i class="arg">list</i></dt>
<dd><p>The <i class="arg">-checkbutton</i> entry widget allows activating or deactivating a single choice option. The result written into the variable will either be <b class="const">0</b> if the check button was not activated or <b class="const">1</b> if it was activated. An eventually provided default value has also to be either <b class="const">0</b> or <b class="const">1</b>.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-checkbutton</b> {-label Capitalize -variable Capitalize -default 1}</pre>
</dd>
</dl>
<p>Several types of list and combo boxes are available to handle selection lists.</p>
<dl class="doctools_definitions">
<dt>-combobox <i class="arg">list</i></dt>
<dd><p>The combobox is a combination of a normal entry widget together with a drop-down list box. The combobox allows selecting from this drop-down list box a single element. The list of the available elements can be provided either as a list to the <i class="arg">-choices</i> attribute, or via a variable that is specified with the <i class="arg">-choicevariable</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-combobox</b> {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}</pre>
<p>And here is an example of using a variable to define the selection list:</p>
<pre class="doctools_example">set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
<b class="cmd">-combobox</b> {-label "Text size" -variable Size -choicevariable TextSizes -default 12}</pre>
</dd>
<dt>-listbox <i class="arg">list</i></dt>
<dd><p>In contrast to the combo box, the list box is always displayed by the <i class="arg">listbox</i> entry widget. Only one element is selectable unless the <i class="arg">-multiple_selection</i> attribute is set. The list box height can be selected with the <i class="arg">-height</i> attribute. If the height is not explicitly defined, the list box height is automatically adapted to the argument dialog box size.
The first example uses a variable to define the available choices:</p>
<pre class="doctools_example">set set AvailableSizes
for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
tepam::argument_dialogbox \
<b class="cmd">-listbox</b> {-label "Distance" -variable Distance \
-choicevariable AvailableSizes -default 6 -height 5}</pre>
<p>Here is a multi-element selection example. Please note that also the default selection can contain multiple elements:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-listbox</b> {-label "Text styles" -variable Styles \
-choices {bold italic underline overstrike} \
-choicelabels {Bold Italic Underline Overstrike} \
-default {bold underline} -multiple_selection 1 \
-height 3}</pre>
</dd>
<dt>-disjointlistbox <i class="arg">list</i></dt>
<dd><p>A disjoint list box has to be used instead of a normal list box if the selection order is important. The disjoint list box entry widget has in fact two list boxes, one to select elements and one to display the selected elements in the chosen order.</p>
<p>Disjoint listboxes allow always selecting multiple elements. With the exception of the <i class="arg">-multiple_selection</i> attribute, disjointed list boxes are accepting the same attributes as the normal listbox, e.g. <i class="arg">-height, -choices, -choicevariable, -default</i>.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-disjointlistbox</b> {-label "Preferred scripting languages" -variable Languages \
-comment "Please select your preferred languages in the order" \
-choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
-default {Tcl Perl Python}}</pre>
</dd>
</dl>
<p>The file and directory selectors are building a next group of data entry widgets. A paragraph of section <span class="sectref"><a href="#subsection5">Entry Widget Item Attributes</a></span> explains the widget specific attributes that allow specifying the targeted file types, active directory etc.</p>
<dl class="doctools_definitions">
<dt>-file <i class="arg">list</i></dt>
<dd><p>The item <i class="arg">-file</i> creates a group composed by an entry widget together with a button that allows opening a file browser. The data type <i class="arg">file</i> is automatically selected for this entry if no data type has been explicitly defined with the <i class="arg">-type</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-file</b> {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
-initialfile "picture.gif"}</pre>
</dd>
<dt>-existingfile <i class="arg">list</i></dt>
<dd><p>The item <i class="arg">-existingfile</i> creates a group composed by an entry widget together with a button that allows opening a browser to select an existing file. The data type <i class="arg">existingfile</i> is automatically selected for this entry if no data type has been explicitly defined with the <i class="arg">-type</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-existingfile</b> {-label "Image file" -variable ImageF \
-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
-initialfile "picture.gif"}</pre>
</dd>
<dt>-directory <i class="arg">list</i></dt>
<dd><p>The item <i class="arg">-directory</i> creates a group composed by an entry widget together with a button that allows opening a directory browser. The data type <i class="arg">directory</i> is automatically selected for this entry if no data type has been explicitly defined with the <i class="arg">-type</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-directory</b> {-label "Report directory" -variable ReportDir}</pre>
</dd>
<dt>-existingdirectory <i class="arg">list</i></dt>
<dd><p>The item <i class="arg">-existingdirectory</i> creates a group composed by an entry widget together with a button that allows opening a browser to select an existing directory. The data type <i class="arg">existingdirectory</i> is automatically selected for this entry if no data type has been explicitly defined with the <i class="arg">-type</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-existingdirectory</b> {-label "Report directory" -variable ReportDir}</pre>
</dd>
</dl>
<p>Finally, there is a last group of some other special data entry widgets.</p>
<dl class="doctools_definitions">
<dt>-color <i class="arg">list</i></dt>
<dd><p>The color selector is composed by an entry widget together with a button that allows opening a color browser. The data type <i class="arg">color</i> is automatically selected for this entry widget type if no data type has been explicitly defined with the <i class="arg">-type</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-color</b> {-label "Background color" -variable Color -default red}</pre>
</dd>
<dt>-font <i class="arg">list</i></dt>
<dd><p>The font selector is composed by an entry widget together with a button that allows opening a font browser. The data type <i class="arg">font</i> is automatically selected for this entry widget type if no data type has been explicitly defined with the <i class="arg">-type</i> attribute. The entry widget displays an example text in the format of the selected font.</p>
<p>The font browser allows selecting by default the font families provided by the <b class="cmd">font families</b> Tk command as well as a reasonable set of different font sizes between 6 points and 40 points. Different sets of font families and font sizes can be specified respectively via the <i class="arg">-font_families</i> or <i class="arg">-font_sizes</i> attributes.</p>
<p>If no default font is provided via the <i class="arg">-default</i> attribute, the default font of the label widget to display the selected font will be used as default selected font. If the font family of this label widget is not part of the available families the first available family is used as default. If the font size of this label widget is not part of the available sizes the next close available size is selected as default size.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-font</b> {-label "Font" -variable Font \
-font_sizes {8 10 12 16} \
-default {Arial 20 italic}}</pre>
</dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Entry Widget Item Attributes</a></h3>
<p>All the entry widget items are accepting the following attributes:</p>
<dl class="doctools_definitions">
<dt>-text <i class="arg">string</i></dt>
<dd><p>Eventual descriptions and comments specified with the <i class="arg">-text</i> attribute are displayed above the entry widget.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-entry {<b class="cmd">-text "Please enter your name bellow"</b> -variable Name}</pre>
</dd>
<dt>-label <i class="arg">string</i></dt>
<dd><p>The label attribute creates left to the entry widget a label using the provided string as label text:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-entry {<b class="cmd">-label Name</b> -variable Name}</pre>
</dd>
<dt>-variable <i class="arg">string</i></dt>
<dd><p>All entry widgets require a specified variable. After accepting the entered information with the OK button, the entry widget data is stored inside the defined variables.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-existingdirectory {-label "Report directory" <b class="cmd">-variable ReportDir</b>}</pre>
</dd>
<dt>-default <i class="arg">string</i></dt>
<dd><p>Eventual default data for the entry widgets can be provided via the <i class="arg">-default</i> attribute. The default value is overridden if an argument dialog box with a defined context is called another time. The value acknowledged in a previous call will be used in this case as default value.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} <b class="cmd">-default italic</b>}</pre>
</dd>
<dt>-optional <b class="const">0</b>|<b class="const">1</b></dt>
<dd><p>Data can be specified as optional or mandatory with the <i class="arg">-optional</i> attribute that requires either <b class="const">0</b> (mandatory) or <b class="const">1</b> (optional) as attribute data.</p>
<p>In case an entry is optional and no data has been entered, e.g. the entry contains an empty character string, the entry will be considered as undefined and the assigned variable will not be defined.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-entry {-label "City" -variable start_city -type string} \
-entry {-label "Street" -variable start_street -type string <b class="cmd">-optional 0</b>} \
-entry {-label "Street number" -variable start_street_nbr -type integer <b class="cmd">-optional 1</b>} \</pre>
</dd>
<dt>-type <i class="arg">string</i></dt>
<dd><p>If the data type is defined with the <i class="arg">-type</i> attribute the argument dialog box will automatically perform a data type check after acknowledging the entered values and before the dialog box is closed. If a type incompatible value is found an error message box appears and the user can correct the value.</p>
<p>The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by <b class="cmd"><a href="tepam_procedure.html">tepam::procedure</a></b> (see the <em>tepam::procedure reference manual</em>).</p>
<p>Some entry widgets like the file and directory widgets, as well as the color and font widgets are specifying automatically the default data type if no type has been specified explicitly with the <i class="arg">-type</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
<b class="cmd">-entry</b> {-label "Street number" -variable start_street_nbr <b class="cmd">-type integer</b>} \</pre>
</dd>
<dt>-range <i class="arg">string</i></dt>
<dd><p>Values can be constrained with the <i class="arg">-range</i> attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value.</p>
<p>The <i class="arg">-range</i> attribute has to be used only for numerical arguments, like integers and doubles.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-entry {-label Month -variable Month -type integer <b class="cmd">-range {1 12}</b>}</pre>
</dd>
<dt>-validatecommand <i class="arg">string</i></dt>
<dd><p>Custom argument value validations can be performed via specific validation commands that are defined with the <i class="arg">-validatecommand</i> attribute. The provided validation command can be a complete script in which the pattern <em>%P</em> is placeholder for the argument value that has to be validated.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-entry {-label "Your comment" -variable YourCom \
<b class="cmd">-validatecommand</b> "IllegalWordDetector %P"}</pre>
<p>While the purpose of this custom argument validation attribute is the validation of a specific argument, there is also a global data validation attribute <i class="arg">-validatecommand</i> that allows performing validation that involves multiple arguments.</p></dd>
<dt>-validatecommand_error_text <i class="arg">string</i></dt>
<dd><p>This attribute allows overriding the default error message for a custom argument validation (defined by <i class="arg">-validatecommand</i>).</p></dd>
</dl>
<p>Some other attributes are supported by the list and combo boxes as well as by the radio and check buttons.</p>
<dl class="doctools_definitions">
<dt>-choices <i class="arg">string</i></dt>
<dd><p>Choice lists can directly be defined with the <i class="arg">-choices</i> attribute. This way to define choice lists is especially adapted for smaller, fixed selection lists.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
<b class="cmd">-choices {bold italic underline}</b> -default underline</pre>
</dd>
<dt>-choicelabels <i class="arg">string</i> <em>(only check and radio buttons)</em></dt>
<dd><p>If the labels of the check and radio boxes should differ from the option values, they can be defined with the <i class="arg">-choicelabels</i> attribute:</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-checkbox {-label "Font sytle" -variable FontStyle \
-choices {bold italic underline} \
<b class="cmd">-choicelabels {Bold Italic Underline}</b> </pre>
</dd>
<dt>-choicevariable <i class="arg">string</i></dt>
<dd><p>Another way to define the choice lists is using the <i class="arg">-choicevariable</i> attribute. This way to define choice lists is especially adapted for huge and eventually variable selection lists.</p>
<pre class="doctools_example">set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
-combobox {-label "Text size" -variable Size <b class="cmd">-choicevariable TextSizes</b>}</pre>
</dd>
<dt>-multiple_selection <b class="const">0</b>|<b class="const">1</b></dt>
<dd><p>The list box item (<b class="cmd">-listbox</b>) allows by default selecting only one list element. By setting the <i class="arg">-multiple_selection</i> attribute to <b class="const">1</b>, multiple elements can be selected.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-listbox {-label "Text styles" -variable Styles \
-choices {bold italic underline} -default underline \
<b class="cmd">-multiple_selection 1</b> -height 3}</pre>
</dd>
</dl>
<p>Some additional attributes are supported by the file and directory selection widgets.</p>
<dl class="doctools_definitions">
<dt>-filetypes <i class="arg">string</i></dt>
<dd><p>The file type attribute is used by the <b class="cmd">-file</b> and <b class="cmd">-existingfile</b> items to define the file endings that are searched by the file browser.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-file {-label "Image file" -variable ImageF \
<b class="cmd">-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}</b>}</pre>
</dd>
<dt>-initialfile <i class="arg">string</i></dt>
<dd><p>The initial file used by the file browsers of the <b class="cmd">-file</b> and <b class="cmd">-existingfile</b> widgets are by default the file defined with the <i class="arg">-default</i> attribute, unless a file is specified with the <i class="arg">-initialfile</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-file {-variable ImageF <b class="cmd">-initialfile "picture.gif"</b>}</pre>
</dd>
<dt>-activedir <i class="arg">string</i></dt>
<dd><p>The <i class="arg">-activedir</i> attribute will override the default active search directory used by the file browsers of all file and directory entry widgets. The default active search directory is defined by the directory of a specified initial file (<i class="arg">-initialfile</i>) if defined, and otherwise by the directory of the default file/directory, specified with the <i class="arg">-default</i> attribute.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-file "-variable ImageF <b class="cmd">-activedir $pwd</b>"</pre>
</dd>
</dl>
<p>Finally, there is a last attribute supported by some widgets:</p>
<dl class="doctools_definitions">
<dt>-height <i class="arg">string</i></dt>
<dd><p>All widgets containing a selection list (<b class="cmd">-listbox</b>, <b class="cmd">-disjointlistbox</b>, <b class="cmd">-font</b>) as well as the multi line <b class="cmd">-text</b> widget are accepting the <i class="arg">-height</i> attribute that defines the number of displayed rows of the selection lists.</p>
<pre class="doctools_example">tepam::argument_dialogbox \
-listbox {-label "Text size" -variable Size \
-choices {8 9 10 12 15 18} -default 12 <b class="cmd">-height 3</b>}</pre>
<p>If the no height has been explicitly specified the height of the widget will be dynamically adapted to the argument dialog box size.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">APPLICATION SPECIFIC ENTRY WIDGETS</a></h2>
<p>An application specific entry widget can be made available to the argument dialog box by adding a dedicated procedure to the <b class="namespace">tepam</b> namespace. This procedure has three arguments; the first one is the widget path, the second one a subcommand and the third argument has various purposes:</p>
<pre class="doctools_example"><i class="arg">proc</i> tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
<i class="arg">upvar Option Option; # if required</i>
<i class="arg">variable argument_dialogbox; # if required</i>
switch $Command {
"create" <CreateCommandSequence>
"set_choice" <SetChoiceCommandSequence>
"set" <SetCommandv>
"get" <GetCommandSequence>
}
}</pre>
<p><b class="cmd">Argument_dialogbox</b> takes care about the <i class="arg">-label</i> and <i class="arg">-text</i> attributes for all entry widgets. For any data entry widget it creates a frame into which the data entry widget components can be placed. The path to this frame is provided via the <i class="arg">W</i> argument.</p>
<p>The entry widget procedure has to support 3 mandatory and an optional command that are selected via the argument <i class="arg">Command</i>:</p>
<dl class="doctools_definitions">
<dt><i class="arg">create</i></dt>
<dd><p>The entry widget is called a first time with the command <i class="arg">create</i> to build the data entry widget.</p>
<p>The frames that are made available by <b class="cmd">argument_dialogbox</b> for the entry widgets are by default only extendable in the X direction. To make them also extendable in the Y direction, for example for extendable list boxes, the command <b class="cmd">ad_form(make_expandable) $W</b> has to be executed when an entry widget is built.</p></dd>
<dt><i class="arg">set_choice</i></dt>
<dd><p>The entry widget procedure is only called with the <i class="arg">set_choice</i> command if the <i class="arg">-choices</i> or <i class="arg">-choicevariable</i> has been specified. The command is therefore only relevant for list and combo boxes.</p>
<p>The available selection list that is either specified with the <i class="arg">-choices</i> or <i class="arg">-choicevariable</i> attribute is provided via the <i class="arg">Par</i> argument to the entry widget procedure. This list can be used to initialize an available choice list.</p></dd>
<dt><i class="arg">set</i></dt>
<dd><p>If a default value is either defined via the <i class="arg">-default</i> attribute or via a preceding call the entry widget procedure is called with the <i class="arg">set</i> command. The argument <i class="arg">Par</i> contains in this case the value to which the entry widget has to be initialized.</p></dd>
<dt><i class="arg">get</i></dt>
<dd><p>The entry widget procedure command <i class="arg">get</i> has to return the current value of the entry widget.</p></dd>
</dl>
<p>Eventually specified entry widget item attributes are available via the <b class="variable">Option</b> array variable of the calling procedure. This variable becomes accessible inside the entry widget procedure via the <b class="cmd">upvar</b> command.</p>
<p>There may be a need to store some information in a variable. The array variable <b class="variable">argument_dialogbox</b> has to be used for this purpose together with array indexes starting with <em>"$W,"</em>, e.g. <em>argument_dialogbox($W,values)</em>.</p>
<p>Examples of entry widget procedures are directly provided by the TEPAM package source file that specifies the standard entry widget procedures. The simplest procedure is the one for the basic <em>entry</em> widget:</p>
<pre class="doctools_example">proc tepam::ad_form(entry) {W Command {Par ""}} {
switch $Command {
"create" {pack [entry \$W.entry] -fill x \
-expand yes -pady 4 -side left}
"set" {\$W.entry insert 0 $Par}
"get" {return [\$W.entry get]}
}
}</pre>
<p>It is also possible to relay on an existing entry widget procedure to derive a new, more specific one. The <em>radiobox</em> widget is used for example, to create a new entry widget that allows selecting either <em>left</em>, <em>center</em> or <em>right</em>. The original <em>radiobox</em> widget is called with the <i class="arg">set_choice</i> command immediately after the <em>create</em> command, to define the fixed list of selection options.</p>
<pre class="doctools_example">proc tepam::ad_form(rcl) {W Command {Par ""}} {
set Res [ad_form(radiobox) $W $Command $Par]
if {$Command=="create"} {
ad_form(radiobox) $W set_choice {left center right}
}
return $Res
}</pre>
<p>Please consult the TEPAM package source file to find additional and more complex examples of entry widget procedures.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">VARIABLES</a></h2>
<p>The <b class="cmd">argument_dialogbox</b> is using two variables inside the namespace <b class="namespace">::tepam</b>:</p>
<dl class="doctools_definitions">
<dt><b class="variable">argument_dialogbox</b></dt>
<dd><p>Application specific entry widget procedures can use this array variable to store their own data, using as index the widget path provided to the procedure, e.g. <em>argument_dialogbox($W,<sub_index>)</em>.</p></dd>
<dt><b class="variable">last_parameters</b></dt>
<dd><p>This array variable is only used by an argument dialog box if its context has been specified via the <i class="arg">-context</i> attribute. The argument dialog box position and size as well as its entered data are stored inside this variable if the data are acknowledged and the form is closed. This allows the form to restore its previous state once it is called another time.</p>
<p>To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the <b class="variable">last_parameter</b> array variable contents in a configuration file which is loaded the next time an application is launched.</p></dd>
</dl>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="tepam_introduction.html">tepam(n)</a>, <a href="tepam_procedure.html">tepam::procedure(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_entry_form">data entry form</a>, <a href="../../../../index.html#parameter_entry_form">parameter entry form</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Argument entry form, mega widget</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2013, Andreas Drollinger</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tepam/tepam_doc_gen.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
<div class='fossil-doc' data-title='tepam::doc_gen - Tcl's Enhanced Procedure and Argument Manager'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tepam::doc_gen(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tepam::doc_gen - TEPAM DOC Generation, reference manual</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">ARGUMENTS</a></li>
<li class="doctools_section"><a href="#section3">PREDEFINED DOCUMENT FORMATS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">TXT - Text format</a></li>
<li class="doctools_subsection"><a href="#subsection2">HTML - HTML format</a></li>
<li class="doctools_subsection"><a href="#subsection3">POD - Perl document format</a></li>
<li class="doctools_subsection"><a href="#subsection4">DT - TclLib DocTools format</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">ADDING SUPPORT FOR NEW DOCUMENT FORMATS</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection5">tepam::doc_gen::generate</a></li>
<li class="doctools_subsection"><a href="#subsection6">tepam::doc_gen::patch</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">tepam 0.5</b></li>
<li>package require <b class="pkgname">tepam::doc_gen <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">tepam::doc_gen::generate</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-style <i class="arg">style</i>?</span> <span class="opt">?-header_footer?</span> <span class="opt">?-dest_file <i class="arg">dest_file</i>?</span> <i class="arg">name</i></a></li>
<li><a href="#2"><b class="cmd">tepam::doc_gen::patch</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-style <i class="arg">style</i>?</span> <span class="opt">?-search_pattern <i class="arg">search_pattern</i>?</span> <span class="opt">?-src_string <i class="arg">src_string</i> | -src_file <i class="arg">src_file</i>?</span> <span class="opt">?-dest_file <i class="arg">dest_file</i>?</span> <span class="opt">?name?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package generates documentations of TEPAM procedures (procedures that have been declared with <b class="cmd"><a href="tepam_procedure.html">tepam::procedure</a></b>). The documents are generated in the classic UNIX document style using the following document sections: Name, Synopsis, Description, Arguments and Example. <b class="package">TEPAM Doc Gen</b> provides support for various document formats. Support for additional formats can be added if necessary.</p>
<p>The <b class="package">TEPAM Doc Gen</b> package provides the following commands:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">tepam::doc_gen::generate</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-style <i class="arg">style</i>?</span> <span class="opt">?-header_footer?</span> <span class="opt">?-dest_file <i class="arg">dest_file</i>?</span> <i class="arg">name</i></a></dt>
<dd><p>This command generates the documentation for a specified procedure (<i class="arg">name</i>) in one of the supported formats (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool), or in a custom specific format. The format is specified via <span class="opt">?format?</span>. The flag <span class="opt">?-header_footer?</span> adds to the documentation file header and footer. If <span class="opt">?dest_file?</span> is specified the documentation is stored in a file (the file header and footer are added automatically in this case) and the file name is returned. Otherwise the documentation string is returned by <b class="cmd">generate</b>.</p></dd>
<dt><a name="2"><b class="cmd">tepam::doc_gen::patch</b> <span class="opt">?-format <i class="arg">format</i>?</span> <span class="opt">?-style <i class="arg">style</i>?</span> <span class="opt">?-search_pattern <i class="arg">search_pattern</i>?</span> <span class="opt">?-src_string <i class="arg">src_string</i> | -src_file <i class="arg">src_file</i>?</span> <span class="opt">?-dest_file <i class="arg">dest_file</i>?</span> <span class="opt">?name?</span></a></dt>
<dd><p>This command inserts procedure documentations into an existing master document at the locations indicated by insertion placeholders which are matching the pattern of <span class="opt">?search_pattern?</span>. The existing master document is either provided as data to the argument (<span class="opt">?src_string?</span>) or via a file (<span class="opt">?src_file?</span>). The final document is returned by <b class="cmd"><a href="../../../../index.html#patch">patch</a></b> if no destination file is defined (<span class="opt">?dest_file?</span>). Otherwise, the document is stored in the specified file, and the number of insertion placeholders that could be handled successfully is returned.</p>
<p>Any insertion placeholders of the master document are handled by default. By defining the argument <span class="opt">?name?</span> the documentation insertion will be restricted to a particular procedure.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">ARGUMENTS</a></h2>
<dl class="doctools_definitions">
<dt><span class="opt">?-format <i class="arg">format</i>?</span></dt>
<dd><p>Specifies the documentation format. <b class="package">TEPAM Doc Gen</b> provides support for the following formats:</p>
<ul class="doctools_itemized">
<li><p>TXT - Text format (default)</p></li>
<li><p>HTML</p></li>
<li><p>POD - Perl Plain Old Documentation format (PerlPOD)</p></li>
<li><p>DT - TclLib DocTool format</p></li>
</ul>
<p>Section <span class="sectref"><a href="#section4">ADDING SUPPORT FOR NEW DOCUMENT FORMATS</a></span> shows how support for additional formats can be added.</p></dd>
<dt><span class="opt">?-style <i class="arg">style</i>?</span></dt>
<dd><p>The documentation is by default generated in Tcl style (e.g. <b class="cmd">command arg1 arg2 ...</b>). C-style documentation can be generated by setting this argument to 'C' (e.g. <b class="cmd">command(arg1,arg2,...)</b>).</p></dd>
<dt><span class="opt">?-dest_file <i class="arg">dest_file</i>?</span></dt>
<dd><p>If <span class="opt">?dest_file?</span> is defined the documentation is written into the specified destination file. Otherwise the documentation string is returned by the commands <b class="cmd">generate</b> and <b class="cmd"><a href="../../../../index.html#patch">patch</a></b>.</p></dd>
<dt><i class="arg">name</i> / <span class="opt">?name?</span></dt>
<dd><p>This is the name of the procedure for which the documentation has to be generated. This is a mandatory argument for <b class="cmd">generate</b>, but an optional argument for <b class="cmd"><a href="../../../../index.html#patch">patch</a></b>.</p></dd>
<dt><span class="opt">?-header_footer?</span></dt>
<dd><p><b class="cmd">Generate</b> adds to the generated procedure documentation the file header and footer only if a file is generated. By selecting the flag <span class="opt">?-header_footer?</span> the header and footer are also generated if the documentation is returned as string by <b class="cmd">generate</b>.</p></dd>
<dt><span class="opt">?-src_string <i class="arg">src_string</i> | -src_file <i class="arg">src_file</i>?</span></dt>
<dd><p><b class="cmd"><a href="../../../../index.html#patch">Patch</a></b> inserts procedure documentations into an existing document that is either provided as string to the argument (<span class="opt">?src_string?</span>) or as a file (<span class="opt">?src_file?</span>). One of these two arguments need to be specified.</p></dd>
<dt><span class="opt">?-search_pattern <i class="arg">search_pattern</i>?</span></dt>
<dd><p>The argument <span class="opt">?search_pattern?</span> defines the documentation insertion placeholder used in a document. It is a regular expression accepted by <b class="cmd">regexp</b> and needs to contain a parenthesized sub-expression that contains the procedure name for which the documentation needs to be inserted.</p>
<p>The default insertion placeholder pattern is <em>\{!(.*?)!\}</em>, which means that the procedure name will be embedded between <em>{!</em> and <em>!}</em>. The section <span class="sectref"><a href="#section5">EXAMPLES</a></span> contains a custom insertion placeholder pattern example.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PREDEFINED DOCUMENT FORMATS</a></h2>
<p><b class="package">TEPAM Doc Gen</b> pre-defines the following document formats:</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">TXT - Text format</a></h3>
<p>The documentation will be generated in a simple text format if this format is selected. The format can be customized via the following variable:</p>
<dl class="doctools_definitions">
<dt><b class="variable">tepam::doc_gen::Option(TXT,MaxLineLength)</b></dt>
<dd><p>Default: 80</p>
<p>This variable defines the line wrapping limit (character position).</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">HTML - HTML format</a></h3>
<p><b class="package">TEPAM Doc Gen</b> generates CSS styled HTML files. The HTML documentation can be customized via the following variable:</p>
<dl class="doctools_definitions">
<dt><b class="variable">tepam::doc_gen::Option(HTML,CssFile)</b></dt>
<dd><p>Default: "<b class="file">tepam_doc_stylesheet.css</b>"</p>
<p>This variable specifies the CSS stylesheet file that is referred by the generated HTML files.</p></dd>
</dl>
<p>The CSS stylesheet can be customized to change the documentation formatting. A good starting point to create a customized CSS stylesheet is to use the CSS file provided by the <b class="package">TEPAM Doc Gen</b> example/demo. The HTML documentation uses the following CSS class styles:</p>
<ul class="doctools_itemized">
<li><p><em>h1.tepam_page_title</em> - Document page title. Only used by <b class="cmd">generate</b> if a file is created or if the header and footer are built (flag <span class="opt">?-header_footer?</span> selected).</p></li>
<li><p><em>div.tepam_command_help</em> - Documentation container. The entire procedure documentation is placed inside this container.</p></li>
<li><p><em>p.tepam_section_title</em> - Section title (e.g. <em>Name</em>, <em>Synopsis</em>, <em>Description</em>, ...)</p></li>
<li><p><em>p.tepam_sub_section_title</em> - Sub-section title (used to separate the documentation of multiple sub-procedures)</p></li>
<li><p><em>p.tepam_name</em> - Name section</p></li>
<li><p><em>p.tepam_synopsis</em> - Synopsis section</p></li>
<li><p><em>p.tepam_description</em> - Single description paragraph</p></li>
<li><p><em>ul.tepam_description_list</em> - Item of a HTML bulleted/unordered list inside the description section</p></li>
<li><p><em>dt.tepam_argument</em> - Item of a HTML description list used to list the procedure arguments</p></li>
<li><p><em>p.tepam_argument_description</em> - Argument description paragraph</p></li>
<li><p><em>p.tepam_argument_attribute</em> - Argument attribute line</p></li>
<li><p><em>pre.tepam_example</em> - Example section</p></li>
</ul>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">POD - Perl document format</a></h3>
<p>The documentation is generated in the Perl Plain Old Documentation format (PerlPOD) if this format is selected.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">DT - TclLib DocTools format</a></h3>
<p>The documentation is generated in the Tcllib DocTools format if this format is selected.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">ADDING SUPPORT FOR NEW DOCUMENT FORMATS</a></h2>
<p>Support for a new document format can be added by defining in the <b class="namespace">tepam::doc_gen</b> namespace a set of procedures that generate the different document components.</p>
<p>The following documentation listing contains tokens that refer to the different document generation procedures:</p>
<pre class="doctools_example"> <em> <01></em>
<em><03> <20s></em> NAME<em><20e></em>
<em> <30s></em> message_box - Displays text in a message box<em><30e></em>
<em> <20s></em> SYNOPSYS<em><20e></em>
<em> <40s></em> message_box [-mtype <mtype>] <text><em><40e></em>
<em> <20s></em> DESCRIPTION<em><20e></em>
<em> <21s> message_box<21e></em>
<em> <54s> message_box [-mtype <mtype>] <text><54e></em>
<em> <50s></em> This procedure allows displaying a text in an message box. The following
<em> </em> message types are supported:<em><50e></em>
<em><51> <53s></em> * Info<em><53e></em>
<em> <53s></em> * Warning<em><53e></em>
<em> <53s></em> * Error<em><53e></em> <em><52></em>
<em> <50s></em> If the text parameter is use multiple times the different texts are
<em> </em> concatenated to create the message text.<em><50e></em>
<em> <20s></em> ARGUMENTS<em><20e></em>
<em><60> <62s></em> [-mtype <mtype>]<em><62e></em>
<em><63> <65s></em> Message type<em><65e></em>
<em> <66s></em> Default: "Warning"<em><66e></em>
<em> <66s></em> Multiple: yes<em><66e></em>
<em> <66s></em> Choices: Info, Warning, Error<em><66e></em> <em><64></em>
<em> <62s></em> <text><em><62e></em>
<em><63> <65s></em> One or multiple text lines to display<em><65e></em>
<em> <66s></em> Type: string<em><66e></em>
<em> <66s></em> Multiple: yes<em><66e></em> <em><64><61></em>
<em> <20s></em> EXAMPLE<em><20e></em>
<em><70> <72s></em> message_box "Please save first the document"<em><72e></em>
<em> <73s></em> -> 1<em><73e></em> <em><71><04></em>
<em> <02></em></pre>
<p>There are 2 types of document generation procedures:</p>
<dl class="doctools_definitions">
<dt>Content generation procedures (e.g. <40s>...<40e>)</dt>
<dd><p>These procedures generate some document content based on the text that is provided as procedure argument. The listing above shows two tokens for these procedures to indicate the beginning and the end of the generated content.</p></dd>
<dt>Control generation procedures (e.g. <03>)</dt>
<dd><p>These procedures generate control constructs, for example to generate the prolog code and epilog code for lists, sections, etc. These procedures have no argument.</p></dd>
</dl>
<p>The following set of procedures needs to be defined to provide support for a new document format:</p>
<dl class="doctools_definitions">
<dt><em>01</em> - <b class="cmd">gen($Format,Header)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Only called if <b class="cmd">doc_gen</b> generates a file or if it is called with the flag <span class="opt">?-header_footer?</span>. The procedure creates the file header. The provided parameter is the procedure name for which the documentation has to be generated.</p></dd>
<dt><em>02</em> - <b class="cmd">gen($Format,Footer)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Only called if <b class="cmd">doc_gen</b> generates a file or if it is called with the flag <span class="opt">?-header_footer?</span>. The procedure creates the file footer.</p></dd>
<dt><em>03</em> - <b class="cmd">gen($Format,Begin)</b> {}</dt>
<dd><p>Generates the documentation prolog (preamble)</p></dd>
<dt><em>04</em> - <b class="cmd">gen($Format,End)</b> {}</dt>
<dd><p>Generates the documentation epilog</p></dd>
<dt><em>20</em> - <b class="cmd">gen($Format,SectionTitle)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a section title (e.g. <em>Name</em>, <em>Synopsis</em>, <em>Description</em>, ...). The raw title text is provided as parameter</p></dd>
<dt><em>21</em> - <b class="cmd">gen($Format,SubSectionTitle)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a sub-section title. Sub-sections are used if a single documentation is generated for multiple sub-commands to make a separation between them. The raw title text is provided as parameter</p></dd>
<dt><em>30</em> - <b class="cmd">gen($Format,Name)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates the name section (without title). The raw section text is provided as parameter.</p></dd>
<dt><em>40</em> - <b class="cmd">gen($Format,Synopsis)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates the synopsis section (without title). The section text provided as parameter is pre-formatted (the argument strings are generated by <b class="cmd">gen($Format,ArgumentString)</b>).</p></dd>
<dt><em>50</em> - <b class="cmd">gen($Format,Description)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a description paragraph. The raw paragraph text is provided as parameter.</p></dd>
<dt><em>51</em> - <b class="cmd">gen($Format,DescriptionListBegin)</b> {}</dt>
<dd><p>Generates the prolog of a bulleted/unordered list inside the description section. This prolog is usually the start code of a list structure.</p></dd>
<dt><em>52</em> - <b class="cmd">gen($Format,DescriptionListEnd)</b> {}</dt>
<dd><p>Generates the epilog of a bulleted/unordered list inside the description section. This epilog is usually the end code of a list structure.</p></dd>
<dt><em>53</em> - <b class="cmd">gen($Format,DescriptionListItem)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a text item in a bulleted/unordered description list. The raw item text is provided as parameter.</p></dd>
<dt><em>54</em> - <b class="cmd">gen($Format,DescriptionSynopsis)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates the synopsis line on the beginning of the description section. The command can return an empty string if no synopsys line is required at this place.</p>
<p>Some formats (e.g. Tcl DocTools) require that the synopsis line is defined in the description section, to build then automatically the synopsis section. The section text provided as parameter is pre-formatted (the argument strings are generated by <b class="cmd">gen($Format,ArgumentString)</b>).</p></dd>
<dt><em>60</em> - <b class="cmd">gen($Format,ArgumentListBegin)</b> {}</dt>
<dd><p>Generates the prolog of argument list (definition/non-bulleted list). This prolog is usually the start code of a definition list.</p></dd>
<dt><em>61</em> - <b class="cmd">gen($Format,ArgumentListEnd)</b> {}</dt>
<dd><p>Generates the epilog of the argument list. This epilog is usually the end string of a list structure.</p></dd>
<dt><em>62</em> - <b class="cmd">gen($Format,ArgumentListItem)</b> {Name IsOptional IsNamed Type}</dt>
<dd><p>Generates an argument item line inside the argument list. This command can rely on <b class="cmd">gen($Format,ArgumentDetailBegin)</b> since the parameters are identical.</p></dd>
<dt><em>63</em> - <b class="cmd">gen($Format,ArgumentDetailBegin)</b> {}</dt>
<dd><p>Generates the argument details prolog (preamble).</p></dd>
<dt><em>64</em> - <b class="cmd">gen($Format,ArgumentDetailEnd)</b> {}</dt>
<dd><p>Generates the argument details epilog</p></dd>
<dt><em>65</em> - <b class="cmd">gen($Format,ArgumentDescription)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates the argument description (single paragraph).</p></dd>
<dt><em>66</em> - <b class="cmd">gen($Format,ArgumentAttribute)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a single argument attribute string. The command is called individually for each attribute.</p></dd>
<dt><em>70</em> - <b class="cmd">gen($Format,ExampleBegin)</b> {}</dt>
<dd><p>Generates the example section prolog (preamble)</p></dd>
<dt><em>71</em> - <b class="cmd">gen($Format,ExampleEnd)</b> {}</dt>
<dd><p>Generates the example section epilog</p></dd>
<dt><em>72</em> - <b class="cmd">gen($Format,ExampleCommandLine)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a single command line in the example section. The command is called for each individual command line.</p></dd>
<dt><em>73</em> - <b class="cmd">gen($Format,ExampleResultLine)</b> {<i class="arg">Text</i>}</dt>
<dd><p>Generates a command result line</p></dd>
<dt><em>80</em> - <b class="cmd">gen($Format,ArgumentString)</b> {Name IsOptional IsNamed Type}</dt>
<dd><p>Generates the part of the command line or the synopsis that is specific to an argument. The generated string has to indicate if an argument is optional, named and if it is a flag.</p>
<p>The following parameters are provided to this procedure:</p>
<dl class="doctools_definitions">
<dt><i class="arg">Name</i></dt>
<dd><p>Name of the argument</p></dd>
<dt><i class="arg">IsOptional</i></dt>
<dd><p>If true (=<b class="const">1</b>) the argument is optional which should be indicated by the generated string (for example by putting the argument into brackets {[]} or into question marks '?'):</p>
<pre class="doctools_example">gen(TXT,ArgumentString) mtype 1 0 string -> <em>"[mtype]"</em></pre>
</dd>
<dt><i class="arg">IsNamed</i></dt>
<dd><p>If true (=<b class="const">1</b>) an argument is a named argument (option). The generated string should in this case contain the argument/option name, followed by the argument itself:</p>
<pre class="doctools_example">gen(TXT,ArgumentString) mtype 0 1 string -> <em>"-mtype <mtype>"</em></pre>
<p>Named arguments can also be optional:</p>
<pre class="doctools_example">gen(TXT,ArgumentString) mtype 1 1 string -> <em>"[-mtype <mtype>]"</em></pre>
</dd>
<dt><i class="arg">Type</i></dt>
<dd><p>Indicates the type of the argument. If the type is set to <b class="const">none</b> the argument is a flag, which needs to be indicated by the generated string. Example:</p>
<pre class="doctools_example">gen(TXT,ArgumentString) close 1 1 none -> <em>"[-close]"</em></pre>
</dd>
</dl></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">tepam::doc_gen::generate</a></h3>
<p>The <b class="package">TEPAM Doc Gen</b> package can be explored by generating the documentation of the command <b class="cmd">tepam::doc_gen::generate</b>. The following example generates the document in text format (default format):</p>
<pre class="doctools_example"><b class="cmd">tepam::doc_gen::generate</b> tepam::doc_gen::generate</pre>
<p>The next example generates the documentation in HTML format:</p>
<pre class="doctools_example"><b class="cmd">tepam::doc_gen::generate</b> -format HTML tepam::doc_gen::generate</pre>
<p>The flag <span class="opt">?header_footer?</span> adds also the file header and footer:</p>
<pre class="doctools_example"><b class="cmd">tepam::doc_gen::generate</b> -format HTML -header_footer tepam::doc_gen::generate</pre>
<p>The documentation can directly be stored in a file. The file header and footer are automatically generated in this way:</p>
<pre class="doctools_example"><b class="cmd">tepam::doc_gen::generate</b> -format HTML -dest_file doc_gen.html tepam::doc_gen::generate</pre>
<p>The generated HTML file refers a CSS stylesheet file (default: tepam_doc_stylesheet.css). To display the HTML file correctly this CSS stylesheet file needs to be copied into the directory of the generated HTML file.</p>
<p>The Tcl DOC Tools format can be used as intermediate format to generate other formats, for example HTML:</p>
<pre class="doctools_example">
<em># Generate the documentation in Tcl Doc Tool format</em>
set dt [<b class="cmd">tepam::doc_gen::generate</b> -format DT -header_footer tepam::doc_gen::generate]
<em></em>
<em># Create a new doc tools object (HTML format)</em>
package require doctools
::doctools::new myDoc -format html
<em></em>
<em># Open the HTML file, and write the HTML formatted documentation</em>
set fHtml [open doc_gen.dt.html w]
puts $fHtml [myDoc format $dt]
close $fHtml
</pre>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">tepam::doc_gen::patch</a></h3>
<p>While <b class="cmd">generate</b> provides a limited number of possibilities to vary the document structure, <b class="cmd"><a href="../../../../index.html#patch">patch</a></b> offers more flexibility. Multiple documentations for different procedures and meta information can for example be added.</p>
<p>The following listing shows how the <b class="cmd"><a href="../../../../index.html#patch">patch</a></b> command works. It defines first a HTML master document string that contains 2 procedure documentation placeholders (<em>{*<ProcedureName>*}</em>). There placeholders are replaced by <b class="cmd"><a href="../../../../index.html#patch">patch</a></b> with the generated documentation of the referred procedures. Since nonstandard placeholders are used, <b class="cmd"><a href="../../../../index.html#patch">patch</a></b> is called with an explicit placeholder pattern definition (argument <i class="arg">search_pattern</i>).</p>
<pre class="doctools_example">
<em># Define the HTML master document</em>
set HtmlMasterDoc {\
<html>
<head>
<title>tepam::doc_gen</title>
<link rel="stylesheet" href="tepam_doc_stylesheet.css">
<meta content="documentation" name="keywords"></meta>
</head>
<body>
<h1>tepam::doc_gen</h1>
<h2>Generate</h2>
<b class="cmd">{*tepam::doc_gen::generate*}</b>
<h2>Patch</h2>
<b class="cmd">{*tepam::doc_gen::patch*}</b>
</body>
<html>\
}
<em></em>
<em># Patch the master document: This will replace the placeholders by the
# procedure documentation divisions:</em>
<b class="cmd">tepam::doc_gen::patch</b> -format HTML -search_pattern {\{\*(.*?)\*\}} \
-src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html
</pre>
</div>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="tepam_introduction.html">tepam(n)</a>, <a href="tepam_procedure.html">tepam::procedure(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#automatic_documentation">automatic documentation</a>, <a href="../../../../index.html#documentation">documentation</a>, <a href="../../../../index.html#procedure_documentation">procedure documentation</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2013, Andreas Drollinger</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tepam/tepam_introduction.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
|
<div class='fossil-doc' data-title='tepam - Tcl's Enhanced Procedure and Argument Manager'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tepam(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">OVERVIEW</a></li>
<li class="doctools_section"><a href="#section3">PROCEDURE DECLARATION</a></li>
<li class="doctools_section"><a href="#section4">PROCEDURE HELP</a></li>
<li class="doctools_section"><a href="#section5">PROCEDURE CALL</a></li>
<li class="doctools_section"><a href="#section6">INTERACTIVE PROCEDURE CALLS</a></li>
<li class="doctools_section"><a href="#section7">FLEXIBLE ARGUMENT DIALOG BOX</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This document is an informal introduction into TEPAM, the Tcl's Enhanced Procedure and Argument Manager. Detailed information to the TEPAM package is provided in the <em>tepam::procedure</em> and <em>tepam::argument_dialogbox</em> reference manuals.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">OVERVIEW</a></h2>
<p>This package provides a new Tcl procedure declaration syntax that simplifies the implementation of procedure subcommands and the handling of the different types of procedure arguments like flags or switches, options, unnamed arguments, optional and mandatory options and arguments, default values, etc. Procedure declarations can be enriched with detailed information about the procedure and its arguments. This information is used for the following purposes:</p>
<p>First of all, a preamble is added in front of the body of a procedure that is declared with TEPAM. This preamble calls an argument manager that that uses the provided information to check the validity of the argument types and values before the procedure body is executed. Then, the information is used to generate help and usage texts if requested, or to generate clear error message in case an argument validation fails. The information also allows generating automatically graphical forms that allows an interactive definition of all arguments, in case a procedure is called interactively. And finally, the additional information helps self-commenting in a clean way the declaration of a procedure and of all its arguments.</p>
<p>The graphical form generator that creates the necessary argument specification forms for the interactive procedure calls is also available for other purposes than for procedure argument specifications. It allows creating code efficiently complex parameter entry forms that are usable independently from TEPAM's new procedure definition method.</p>
<p>Here is a short overview about all major TEPAM features:</p>
<ul class="doctools_itemized">
<li><p>New self-documenting procedure declaration syntax: The additional information to declare properly a procedure has not to be provided with additional statements, but can be added in a natural syntax directly into the procedure header.</p></li>
<li><p>Easy way to specify subcommands: A subcommand is declared like a procedure, simply with a procedure name composed by a base name followed by a subcommand name. Sub-subcommands are created identically using simply procedure names composed by 3 words.</p></li>
<li><p>Flexible usage of flags (switches), options (named arguments) and unnamed arguments. Option names are optionally automatically completed.</p></li>
<li><p>Support for default values, mandatory/optional options and arguments, choice lists, value ranges, multiple usable options/arguments.</p></li>
<li><p>Choice of a <em>named arguments first, unnamed arguments later</em> procedure calling style (typical for Tcl commands) or of an <em>unnamed arguments first, named arguments later</em> procedure calling style (typical for Tk commands).</p></li>
<li><p>In case the <em>named arguments first, unnamed arguments later</em> style (Tcl) is selected: Clear separation between options and arguments via the "--" flag. The unnamed arguments can optionally be accessed as options (named arguments).</p></li>
<li><p>Automatic type and value check before the procedure body is executed, taking into account validation ranges, choice lists and custom validation commands. Generation of clear error message if necessary.</p></li>
<li><p>Many predefined types exist (integer, boolean, double, color, file, font, ...). Other application specific types can easily be added.</p></li>
<li><p>Automatic help and usage text generation if a procedure is called with the <i class="arg">-help</i> flag.</p></li>
<li><p>Automatic generation of an interactive argument definition form, in case a procedure is called with the <i class="arg">-interactive</i> flag.</p></li>
<li><p>Procedure calls can be logged which is useful to get for interactively called procedures the command call lines.</p></li>
<li><p>Powerful and code efficient generation of complex parameter definition forms.</p></li>
</ul>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROCEDURE DECLARATION</a></h2>
<p>TEPAM's procedure declaration syntax is simple and self-explaining. Instead of declaring a procedure with the Tcl key word <b class="cmd"><a href="../../../../index.html#proc">proc</a></b>, a procedure is declared with the TEPAM command <b class="cmd"><a href="../../../../index.html#procedure">procedure</a></b> which takes as <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> also 3 arguments: The procedure name, the procedure header and the procedure body.</p>
<p>The following example declares the subcommand <b class="cmd"><a href="../../../../index.html#message">message</a></b> of the procedure <b class="cmd">display</b>. This command has several named and unnamed arguments:</p>
<pre class="doctools_example"><b class="cmd"><a href="tepam_procedure.html">tepam::procedure</a></b> {display message} {
-return -
-short_description "Displays a simple message box"
-description "This procedure allows displaying a configurable message box."
-args {
{-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
{-font -type font -default {Arial 10 italic} -description "Message text font"}
{-level -type integer -optional -range {1 10} -description "Message level"}
{-fg -type color -default black -description "Message color"}
{-bg -type color -optional -description "Background color"}
{-no_border -type none -description "Use a splash window style (no border)"}
{-log_file -type file -optional -description "Optional message log file"}
{text -type string -multiple -description "Multiple text lines to display"}
}
} {
<em> puts "display message:"
foreach var {mtype font level fg bg no_border log_file text} {
if {[info exists $var]} {
puts " $var=[set $var]"
}
}
</em>}</pre>
<p>A call of procedure that has been declared in this way will first invoke the TEPAM argument manager, before the procedure body is executed. The argument manager parses the provided arguments, validates them, completes them eventually with some default values, and makes them finally available to the procedure body as local variables. In case an argument is missing or has a wrong type, the argument manager generates an error message that explains the reason for the error.</p>
<p>As the example above shows, the TEPAM command <b class="cmd"><a href="../../../../index.html#procedure">procedure</a></b> accepts subcommand definitions as procedure name and allows defining much more information than just the argument list inside the procedure header. The procedure body on the other hand is identical between a command declared with <b class="cmd"><a href="../../../../index.html#proc">proc</a></b> and a command declared with <b class="cmd"><a href="../../../../index.html#procedure">procedure</a></b>.</p>
<p>The procedure header allows defining in addition to the arguments some procedure attributes, like a description, information concerning the return value, etc. This information is basically used for the automatic generation of comprehensive help and usage texts.</p>
<p>A list of argument definition statements assigned to the <i class="arg">-args</i> argument is defining the procedure arguments. Each argument definition statement starts with the argument name, optionally followed by some argument attributes.</p>
<p>Three types of arguments can be defined: Unnamed arguments, named arguments and flags. The distinction between the named and unnamed arguments is made by the first argument name character which is simply "-" for named arguments. A flag is defined as named argument that has the type <em>none</em>.</p>
<p>Named and unnamed arguments are mandatory, unless they are declared with the <i class="arg">-optional</i> flag and unless they have a default value specified with the <i class="arg">-default</i> option. Named arguments and the last unnamed argument can have the attribute <i class="arg">-multiple</i>, which means that they can be defined multiple times. The expected argument data type is specified with the <i class="arg">-type</i> option. TEPAM defines a large set of standard data types which can easily be completed with application specific data types.</p>
<p>The argument declaration order has only an importance for unnamed arguments that are by default parsed after the named arguments (Tcl style). A variable allows changing this behavior in a way that unnamed arguments are parsed first, before the named arguments (Tk style).</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">PROCEDURE HELP</a></h2>
<p>The declared procedure can simply be called with the <i class="arg">-help</i> option to get the information about the usage of the procedure and its arguments:</p>
<pre class="doctools_example"><b class="cmd">display message</b> -help
<em> ->
NAME
display message - Displays a simple message box
SYNOPSYS
display message
[-mtype <mtype>] :
Message type, default: "Warning", choices: {Info Warning Error}
[-font <font>] :
Message text font, type: font, default: Arial 10 italic
[-level <level>] :
Message level, type: integer, range: 1..10
[-fg <fg>] :
Message color, type: color, default: black
[-bg <bg>] :
Background color, type: color
[-no_border ] :
Use a splash window style (no border)
[-log_file <log_file>] :
Optional message log file, type: file
<text> :
Multiple text lines to display, type: string
DESCRIPTION
This procedure allows displaying a configurable message box.</em></pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">PROCEDURE CALL</a></h2>
<p>The specified procedure can be called in many ways. The following listing shows some valid procedure calls:</p>
<pre class="doctools_example"><b class="cmd">display message</b> "The document hasn't yet been saved!"
<em>-> display message:
mtype=Warning
font=Arial 10 italic
fg=black
no_border=0
text={The document hasn't yet been saved!}</em>
<b class="cmd">display message</b> -fg red -bg black "Please save first the document"
<em>-> display message:
mtype=Warning
font=Arial 10 italic
fg=red
bg=black
no_border=0
text={Please save first the document}</em>
<b class="cmd">display message</b> -mtype Error -no_border "Why is here no border?"
<em>-> display message:
mtype=Error
font=Arial 10 italic
fg=black
no_border=1
text={Why is here no border?}</em>
<b class="cmd">display message</b> -font {Courier 12} -level 10 \
"Is there enough space?" "Reduce otherwise the font size!"
<em>-> display message:
mtype=Warning
font=Courier 12
level=10
fg=black
no_border=0
text={Is there enough space?} {Reduce otherwise the font size!}</em></pre>
<p>The next lines show how wrong arguments are recognized. The <i class="arg">text</i> argument that is mandatory is missing in the first procedure call:</p>
<pre class="doctools_example"><b class="cmd">display message</b> -font {Courier 12}
<em> -> display message: Required argument is missing: text</em></pre>
<p>Only known arguments are accepted:</p>
<pre class="doctools_example"><b class="cmd">display message</b> -category warning Hello
<em> -> display message: Argument '-category' not known</em></pre>
<p>Argument types are automatically checked and an error message is generated in case the argument value has not the expected type:</p>
<pre class="doctools_example"><b class="cmd">display message</b> -fg MyColor "Hello"
<em> -> display message: Argument 'fg' requires type 'color'. Provided value: 'MyColor'</em></pre>
<p>Selection choices have to be respected ...</p>
<pre class="doctools_example"><b class="cmd">display message</b> -mtype Fatal Hello
<em> -> display message: Argument (mtype) has to be one of the following elements: Info, Warning, Error</em></pre>
<p>... as well as valid value ranges:</p>
<pre class="doctools_example"><b class="cmd">display message</b> -level 12 Hello
<em> -> display message: Argument (level) has to be between 1 and 10</em></pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">INTERACTIVE PROCEDURE CALLS</a></h2>
<p>The most intuitive way to call the procedure is using an form that allows specifying all arguments interactively. This form will automatically be generated if the declared procedure is called with the <i class="arg">-interactive</i> flag. To use this feature the Tk library has to be loaded.</p>
<pre class="doctools_example"><b class="cmd">display message</b> -interactive</pre>
<p>The generated form contains for each argument a data entry widget that is adapted to the argument type. Check buttons are used to specify flags, radio boxes for tiny choice lists, disjoint list boxes for larger choice lists and files, directories, fonts and colors can be selected with dedicated browsers.</p>
<p>After acknowledging the specified argument data via an OK button, the entered data are first validated, before the provided arguments are transformed into local variables and the procedure body is executed. In case the entered data are invalid, a message appears and the user can correct them until they are valid.</p>
<p>The procedure calls can optionally be logged in a variable. This is for example useful to get the command call lines of interactively called procedures.</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">FLEXIBLE ARGUMENT DIALOG BOX</a></h2>
<p>The form generator that creates in the previous example the argument dialog box for the interactive procedure call is also available for other purposes than for the definition of procedure arguments. If Tk has been loaded TEPAM provides and argument dialog box that allows creating complex parameter definition forms in a very efficient way.</p>
<p>The following example tries to illustrate the simplicity to create complex data entry forms. It creates an input mask that allows specifying a file to copy, a destination folder as well as a checkbox that allows specifying if an eventual existing file can be overwritten. Comfortable browsers can be used to select files and directories. And finally, the form offers also the possibility to accept and decline the selection. Here is the code snippet that is doing all this:</p>
<pre class="doctools_example"><b class="cmd"><a href="tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></b> \
<b class="cmd">-existingfile</b> {-label "Source file" -variable SourceFile} \
<b class="cmd">-existingdirectory</b> {-label "Destination folder" -variable DestDir} \
<b class="cmd">-checkbutton</b> {-label "Overwrite existing file" -variable Overwrite}</pre>
<p>The <b class="cmd">argument_dialogbox</b> returns <b class="const">ok</b> if the entered data are validated. It will return <b class="const">cancel</b> if the data entry has been canceled. After the validation of the entered data, the <b class="cmd">argument_dialogbox</b> defines all the specified variables with the entered data inside the calling context.</p>
<p>An <b class="cmd">argument_dialogbox</b> requires a pair of arguments for each variable that it has to handle. The first argument defines the entry widget type used to select the variable's value and the second one is a lists of attributes related to the variable and the entry widget.</p>
<p>Many entry widget types are available: Beside the simple generic entries, there are different kinds of list and combo boxes available, browsers for existing and new files and directories, check and radio boxes and buttons, as well as color and font pickers. If necessary, additional entry widgets can be defined.</p>
<p>The attribute list contains pairs of attribute names and attribute data. The primary attribute is <i class="arg">-variable</i> used to specify the variable in the calling context into which the entered data has to be stored. Another often used attribute is <i class="arg">-label</i> that allows adding a label to the data entry widget. Other attributes are available that allow specifying default values, the expected data types, valid data ranges, etc.</p>
<p>The next example of a more complex argument dialog box provides a good overview about the different available entry widget types and parameter attributes. The example contains also some formatting instructions like <i class="arg">-frame</i> and <i class="arg">-sep</i> which allows organizing the different entry widgets in frames and sections:</p>
<pre class="doctools_example">set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
set Result [<b class="cmd"><a href="tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></b> \
<b class="cmd">-title</b> "System configuration" \
<b class="cmd">-context</b> test_1 \
<b class="cmd">-frame</b> {-label "Entries"} \
<b class="cmd">-entry</b> {-label Entry1 -variable Entry1} \
<b class="cmd">-entry</b> {-label Entry2 -variable Entry2 -default "my default"} \
<b class="cmd">-frame</b> {-label "Listbox & combobox"} \
<b class="cmd">-listbox</b> {-label "Listbox, single selection" -variable Listbox1 \
-choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
<b class="cmd">-listbox</b> {-label "Listbox, multiple selection" -variable Listbox2
-choicevariable ChoiceList -default {"Choice 2" "Choice 3"}
-multiple_selection 1 -height 3} \
<b class="cmd">-disjointlistbox</b> {-label "Disjoined listbox" -variable DisJntListbox
-choicevariable ChoiceList \
-default {"Choice 3" "Choice 5"} -height 3} \
<b class="cmd">-combobox</b> {-label "Combobox" -variable Combobox \
-choices {1 2 3 4 5 6 7 8} -default 3} \
<b class="cmd">-frame</b> {-label "Checkbox, radiobox and checkbutton"} \
<b class="cmd">-checkbox</b> {-label Checkbox -variable Checkbox
-choices {bold italic underline} -choicelabels {Bold Italic Underline} \
-default italic} \
<b class="cmd">-radiobox</b> {-label Radiobox -variable Radiobox
-choices {bold italic underline} -choicelabels {Bold Italic Underline} \
-default underline} \
<b class="cmd">-checkbutton</b> {-label CheckButton -variable Checkbutton -default 1} \
<b class="cmd">-frame</b> {-label "Files & directories"} \
<b class="cmd">-existingfile</b> {-label "Input file" -variable InputFile} \
<b class="cmd">-file</b> {-label "Output file" -variable OutputFile} \
<b class="cmd">-sep</b> {} \
<b class="cmd">-existingdirectory</b> {-label "Input directory" -variable InputDirectory} \
<b class="cmd">-directory</b> {-label "Output irectory" -variable OutputDirectory} \
<b class="cmd">-frame</b> {-label "Colors and fonts"} \
<b class="cmd">-color</b> {-label "Background color" -variable Color -default red} \
<b class="cmd">-sep</b> {} \
<b class="cmd">-font</b> {-label "Font" -variable Font -default {Courier 12 italic}}]</pre>
<p>The <b class="cmd">argument_dialogbox</b> defines all the specified variables with the entered data and returns <b class="const">ok</b> if the data have been validated via the Ok button. If the data entry is cancelled by activating the Cancel button, the <b class="cmd">argument_dialogbox</b> returns <b class="const">cancel</b>.</p>
<pre class="doctools_example">if {$Result=="cancel"} {
puts "Canceled"
} else { # $Result=="ok"
puts "Arguments: "
foreach Var {
Entry1 Entry2
Listbox1 Listbox2 DisJntListbox
Combobox Checkbox Radiobox Checkbutton
InputFile OutputFile InputDirectory OutputDirectory
Color Font
} {
puts " $Var: '[set $Var]'"
}
}
<em>-> Arguments:
Entry1: 'Hello, this is a trial'
Entry2: 'my default'
Listbox1: '1'
Listbox2: '{Choice 2} {Choice 3}'
DisJntListbox: '{Choice 3} {Choice 5}'
Combobox: '3'
Checkbox: 'italic'
Radiobox: 'underline'
Checkbutton: '1'
InputFile: 'c:\tepam\in.txt'
OutputFile: 'c:\tepam\out.txt'
InputDirectory: 'c:\tepam\input'
OutputDirectory: 'c:\tepam\output'
Color: 'red'
Font: 'Courier 12 italic'</em></pre>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="tepam_argument_dialogbox.html">tepam::argument_dialogbox(n)</a>, <a href="tepam_procedure.html">tepam::procedure(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#argument_integrity">argument integrity</a>, <a href="../../../../index.html#argument_validation">argument validation</a>, <a href="../../../../index.html#arguments">arguments</a>, <a href="../../../../index.html#entry_mask">entry mask</a>, <a href="../../../../index.html#parameter_entry_form">parameter entry form</a>, <a href="../../../../index.html#procedure">procedure</a>, <a href="../../../../index.html#subcommand">subcommand</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Procedures, arguments, parameters, options</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2013, Andreas Drollinger</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tepam/tepam_procedure.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
|
<div class='fossil-doc' data-title='tepam::procedure - Tcl's Enhanced Procedure and Argument Manager'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tepam::procedure(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tepam::procedure - TEPAM procedure, reference manual</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">TERMINOLOGY</a></li>
<li class="doctools_section"><a href="#section3">PROCEDURE DECLARATION</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Procedure Attributes</a></li>
<li class="doctools_subsection"><a href="#subsection2">Argument Declaration</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">VARIABLES</a></li>
<li class="doctools_section"><a href="#section5">ARGUMENT TYPES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">Predefined Argument Types</a></li>
<li class="doctools_subsection"><a href="#subsection4">Defining Application Specific Argument Types</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">PROCEDURE CALLS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection5">Help</a></li>
<li class="doctools_subsection"><a href="#subsection6">Interactive Procedure Call</a></li>
<li class="doctools_subsection"><a href="#subsection7">Unnamed Arguments</a></li>
<li class="doctools_subsection"><a href="#subsection8">Named Arguments</a></li>
<li class="doctools_subsection"><a href="#subsection9">Unnamed Arguments First, Named Arguments Later (Tk Style)</a></li>
<li class="doctools_subsection"><a href="#subsection10">Named Arguments First, Unnamed Arguments Later (Tcl Style)</a></li>
<li class="doctools_subsection"><a href="#subsection11">Raw Argument List</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.3</b></li>
<li>package require <b class="pkgname">tepam <span class="opt">?0.5?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">tepam::procedure</b> <i class="arg">name</i> <i class="arg">attributes</i> <i class="arg">body</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides an alternative way to declare Tcl procedures and to manage its arguments. There is a lot of benefit to declare a procedure with TEPAM rather than with the Tcl standard command <b class="function">proc</b>: TEPAM allows specifying inside the procedure declaration all information that is required to generate comprehensive documentations and help support. The information is also used by an automatically invoked argument checker that validates the provided procedure arguments before the procedure body is executed. Finally, a procedure can be called interactively which will open a graphical form that allows specifying the procedure arguments.</p>
<p>TEPAM simplifies also the handling of the different types of argument, like the <em>named arguments</em> (often also called <em>options</em>) and the <em>unnamed arguments</em>. TEPAM supports the <em>named first, unnamed later</em> style (typical Tcl command style) as well as also the <em>unnamed first, named later</em> style (typical Tk command style). TEPAM takes care about default values for arguments, optional arguments, multiple applicable arguments, etc. and eliminates the need to check the validity of the argument inside the procedure bodies.</p>
<p>An informal overview of all the TEPAM procedure declaration and calling features as well as a short introduction into TEPAM is provided by <em>tepam(n)</em>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">TERMINOLOGY</a></h2>
<p>The exact meaning of several terms that are used in this document will be shortly explained to avoid any ambiguities and misunderstandings.</p>
<dl class="doctools_definitions">
<dt><em>Subcommand</em></dt>
<dd><p>The usage of subcommands is heavily used in the Tcl language. Several commands are incorporated into a single main command and are selectable via the first argument.</p>
<p>The <b class="function">string</b> command is an example of such a command that implements for example subcommands to check a character string length, to compare strings, to extract substrings, etc:</p>
<pre class="doctools_example"><b class="function">string length</b> <i class="arg">string</i>
<b class="function">string compare</b> <i class="arg">string</i> <i class="arg">string</i>
<b class="function">string range</b> <i class="arg">string</i> <i class="arg">first</i> <i class="arg">last</i>
...</pre>
<p>TEPAM provides a framework that allows implementing easily such subcommands in form of Tcl procedures. It allows not only defining a first level of subcommands, but also a higher level of subcommands. The <b class="function">string</b> command class check could be implemented as independent sub-sub-commands of the <b class="function">string</b> command:</p>
<pre class="doctools_example"><b class="function">string is alnum</b> <i class="arg">string</i>
<b class="function">string is integer</b> <i class="arg">string</i>
<b class="function">string is double</b> <i class="arg">string</i>
...</pre>
</dd>
<dt><em>Procedure attribute</em></dt>
<dd><p>TEPAM allows attaching to a declared procedure different kind of attributes. Some of these attributes are <em>just</em> used for documentation purposes, but other attributes specify the way how the procedure has to be called. Also the procedure arguments are defined in form of a procedure attribute.</p></dd>
<dt><em>Argument</em></dt>
<dd><p>TEPAM uses the term <em>argument</em> for the parameters of a procedure.</p>
<p>The following example calls the subcommand <b class="cmd">string compare</b> with several arguments:</p>
<pre class="doctools_example"><b class="cmd">string compare</b> <i class="arg">-nocase -length 3 "emphasized" "emphasised"</i></pre>
<p>The following paragraphs discuss these different argument types.</p></dd>
<dt><em>Named argument</em></dt>
<dd><p>Some parameters, as <i class="arg">-length 3</i> of the subcommand <b class="cmd">string compare</b> have to be provided as pairs of argument names and argument values. This parameter type is often also called <em>option</em>.</p>
<p>TEPAM uses the term <em>named argument</em> for such options as well as for the flags (see next item).</p></dd>
<dt><em>Flag, switch</em></dt>
<dd><p>Another parameter type is the <em>flag</em> or the <em>switch</em>. Flags are provided simply by naming the flag leading with the '-' character. The <i class="arg">-nocase</i> of the previous <b class="cmd">string compare</b> example is such a flag.</p>
<p><em>Flags</em> are considered by TEPAM like a special form of <em>named arguments</em>.</p></dd>
<dt><em>Unnamed argument</em></dt>
<dd><p>For the other parameters, e.g. the ones for which the argument name has not to be mentioned, TEPAM uses the term <em>unnamed argument</em>. The previous <b class="cmd">string compare</b> example uses for the two provided character strings two <em>unnamed arguments</em>.</p></dd>
<dt><em>Argument attribute</em></dt>
<dd><p>TEPAM allows describing the purpose of each procedure argument with <em>argument attributes</em>. While some of them are just documenting the attributes, most attributes are used by an argument manager to control and validate the arguments that are provided during a procedure call. Argument attributes are used to specify default values, parameter classes (integer, xdigit, font, ...), choice validation lists, value ranges, etc.</p></dd>
<dt><em>Named arguments first, unnamed arguments later</em></dt>
<dd><p>The <b class="cmd">string compare</b> command of the previous example requires that the <em>named arguments</em> (options, flags) are provided first. The two mandatory (unnamed) arguments have to be provided as last argument.</p>
<pre class="doctools_example"><b class="cmd">string compare</b> <i class="arg">-nocase -length 3 Water $Text</i></pre>
<p>This is the usual Tcl style (exceptions exist) which is referred in the TEPAM documentation as <em>named arguments first, unnamed arguments later style</em>.</p></dd>
<dt><em>Unnamed arguments first, named arguments later</em></dt>
<dd><p>In contrast to most Tcl commands, Tk uses generally (exceptions exist also here) a different calling style where the <em>unnamed arguments</em> have to be provided first, before the <em>named arguments</em> have to be provided:</p>
<pre class="doctools_example"><b class="cmd">pack</b> <i class="arg">.ent1 .ent2 -fill x -expand yes -side left</i></pre>
<p>This style is referred in the TEPAM documentation as <em>unnamed arguments first, named arguments later style</em>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">PROCEDURE DECLARATION</a></h2>
<p>TEPAM allows declaring new Tcl procedures with the command <b class="function">tepam::procedure</b> that has similar to the standard Tcl command <b class="function">proc</b> also 3 arguments:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">tepam::procedure</b> <i class="arg">name</i> <i class="arg">attributes</i> <i class="arg">body</i></a></dt>
<dd></dd>
</dl>
<p>The TEPAM procedure declaration syntax is demonstrated by the following example:</p>
<pre class="doctools_example"><b class="function">tepam::procedure</b> {display message} {
-short_description
"Displays a simple message box"
-description
"This procedure allows displaying a configurable\
message box. The default message type that is\
created is a warning, but also errors and info can\
be generated.
The procedure accepts multiple text lines."
-example
{display message -mtype Warning "Save first your job"}
-args {
{-mtype -choices {Info Warning Error} \
-default Warning -description "Message type"}
{text -type string -multiple \
-description "Multiple text lines to display"}
}
} {
puts "Message type: $mtype"
puts "Message: $text"
}</pre>
<p>The 3 arguments of <b class="function">procedure</b> are:</p>
<dl class="doctools_definitions">
<dt><i class="arg">name</i></dt>
<dd><p>The procedure name can be used in very flexible ways. Procedure names can have namespace qualifiers. By providing a two element name list as procedure name, a subcommand of a procedure will be declared. It is even possible to declare sub-sub-commands of a procedure by providing name lists with three elements.</p>
<p>Here are some valid procedure declarations using different procedure names (the attribute and body arguments are empty for simplicity):</p>
<pre class="doctools_example"><em># Simple procedure name:</em>
tepam::procedure <b class="function">display_message</b> {} {}
<em></em>
<em># Procedure declared in the main namespace:</em>
tepam::procedure <b class="function">::display_message</b> {} {}
<em></em>
<em># Procedure in the namespace</em> <b class="namespace">::ns</b><em>:</em>
tepam::procedure <b class="function">::ns::display_message</b> {} {}
<em></em>
<em># Declaration of the subcommand</em> <b class="function">message</b> <em>of the procedure</em> <b class="function">display</b><em>:</em>
tepam::procedure <b class="function">{display message}</b> {} {}</pre>
</dd>
<dt><i class="arg">attributes</i></dt>
<dd><p>All procedure attributes are provided in form of an option list that contains pairs of option names and option values. The example above has as procedure attribute a short and a normal description, but also the procedure arguments are defined in form of a procedure attribute.</p>
<p>Most procedure attributes are providing information for documentation purposes. But some of them affect also the way how the procedure can be called. The section <span class="sectref"><a href="#subsection1">Procedure Attributes</a></span> discusses in detail the available procedure attributes.</p>
<p>The procedure arguments are defined in form of a special procedure attribute. Most of the information provided in the argument definition is not just used for documentation purposes. This information is in fact used by the TEPAM argument manager to handle and validate the various forms of arguments that are provided during the procedure calls. The section <span class="sectref"><a href="#subsection2">Argument Declaration</a></span> discusses in detail all the argument definition attributes.</p></dd>
<dt><i class="arg">body</i></dt>
<dd><p>This is the normal procedure body. The declared arguments will be available to the procedure body in form of variables.</p>
<p>The procedure body will only be executed if the provided set of arguments could be validated by the TEPAM argument manager.</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args {
{-<b class="variable">mtype</b> -default Warning -choices {Warning Error}}
{<b class="variable">text</b> -type string}
}
} {
puts "Message type: <b class="variable">$mtype</b>"
puts "Message: <b class="variable">$text</b>"
}</pre>
</dd>
</dl>
<p>The commands <b class="cmd"><a href="../../../../index.html#procedure">procedure</a></b> as well as <b class="cmd">argument_dialogbox</b> are exported from the namespace <b class="namespace">tepam</b>. To use these commands without the <b class="namespace">tepam::</b> namespace prefix, it is sufficient to import them into the main namespace:</p>
<pre class="doctools_example"><b class="cmd">namespace import tepam::*</b>
<b class="cmd"><a href="../../../../index.html#procedure">procedure</a></b> {display_message} {
-args {
...</pre>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Procedure Attributes</a></h3>
<p>The first group of attributes affect the behavior of the declared procedure:</p>
<dl class="doctools_definitions">
<dt>-named_arguments_first <b class="const">0</b>|<b class="const">1</b></dt>
<dd><p>This attribute defines the calling style of a procedure. TEPAM uses by default the <em>named arguments first, unnamed arguments later</em> style (Tcl). This default behavior can globally be changed by setting the variable <b class="variable">tepam::named_arguments_first</b> to <b class="const">0</b>. This global calling style can be changed individually for a procedure with the <i class="arg">-named_arguments_first</i> attribute.</p></dd>
<dt>-auto_argument_name_completion <b class="const">0</b>|<b class="const">1</b></dt>
<dd><p>The declared procedures will by default automatically try to match eventually abbreviated argument names to the defined arguments names. This default behavior can globally be changed by setting the variable <b class="variable">tepam::auto_argument_name_completion</b> to <b class="const">0</b>. This global setting of the automatic argument name completion can be changed individually for a procedure with the <i class="arg">-auto_argument_name_completion</i> procedure attribute.</p></dd>
<dt>-interactive_display_format <b class="const">extended</b>|<b class="const">short</b></dt>
<dd><p>A procedure declared with the TEPAM <b class="function">procedure</b> command can always be called with the <b class="variable">-interactive</b> option. By doing so, a graphical form will be generated that allows specifying all procedure argument values. There are two display modes for these interactive forms. While the <em>extended</em> mode is more adapted for small procedure argument sets, the <b class="const">short</b> form is more adequate for huge procedure argument sets.</p>
<p>The choice to use short or extended forms can be globally configured via the variable <b class="variable">tepam::interactive_display_format</b>. This global setting can then be changed individually for a procedure with the <i class="arg">-interactive_display_format</i> procedure attribute.</p></dd>
<dt>-args <i class="arg">list</i></dt>
<dd><p>The procedure arguments are declared via the <i class="arg">-args</i> attribute. An argument is defined via a list having as first element the argument name, followed by eventual argument attributes. All these argument definition lists are packaged themselves into a global list that is assigned to the <i class="arg">-args</i> attribute.</p>
<p>The argument definition syntax will be described more in detail in the following sub section.</p></dd>
</dl>
<p>The next attributes allow specifying custom argument checks as well as custom error messages in case these checks are failing:</p>
<dl class="doctools_definitions">
<dt>-validatecommand <i class="arg">script</i></dt>
<dd><p>Custom argument validations can be performed via specific validation commands that are defined with the <i class="arg">-validatecommand</i> attribute.</p>
<p>Validation command declaration example:</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args {
{text -type string -description "Message text"} }
<b class="cmd">-validatecommand {IllegalWordDetector $text}</b>
} {
}</pre>
<p>The validation command is executed in the context of the declared procedure body. The different argument values are accessed via the argument names. Note there is also an argument attribute <i class="arg">-validatecommand</i> that allows declaring custom checks for specific arguments.</p>
<p>The attribute <i class="arg">-validatecommand</i> can be repeated to declare multiple custom checks.</p></dd>
<dt>-validatecommand_error_text <i class="arg">string</i></dt>
<dd><p>This attribute allows overriding the default error message for a custom argument validation (defined by <i class="arg">-validatecommand</i>). Also this attribute can be repeated in case multiple argument checks are declared.</p></dd>
</dl>
<p>The following attribute allows controlling the logging settings for an individual procedure:</p>
<dl class="doctools_definitions">
<dt>-command_log <b class="const">0</b>|<b class="const">1</b>|<b class="const">"interactive"</b></dt>
<dd><p>This argument configures the logging of the procedure calls into the list variable <b class="variable">tepam::ProcedureCallLogList</b>. The default configuration defined by the variable <b class="variable">tepam::command_log</b> will be used if this argument is not defined in a procedure declaration.</p>
<p>Setting this argument to <b class="const">0</b> will disable any procedure call loggings, setting it to <b class="const">1</b> will log any procedure calls and setting it to <b class="const">interactive</b> will log just the procedures that are called interactively (procedures called with the <b class="const">-interactive</b> flag).</p></dd>
</dl>
<p>The next group of procedure attributes is just used for the purpose of documentation and help text generation:</p>
<dl class="doctools_definitions">
<dt>-category <i class="arg">string</i></dt>
<dd><p>A category can be assigned to a procedure for documentation purposes. Any string is accepted as category.</p></dd>
<dt>-short_description <i class="arg">string</i></dt>
<dd><p>The short description of a procedure is used in the documentation summary of a generated procedure list as well as
in the NAME section of a generated procedure manual page.</p></dd>
<dt>-description <i class="arg">string</i></dt>
<dd><p>The (full) description assigned to a procedure is used to create user manual and help pages.</p></dd>
<dt>-return <i class="arg">string</i></dt>
<dd><p>The <em>-return</em> attribute allows defining the expected return value of a procedure (used for documentation purposes).</p></dd>
<dt>-example <i class="arg">string</i></dt>
<dd><p>A help text or manual page of a procedure can be enriched with eventual examples, using the <em>-example</em> attribute.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Argument Declaration</a></h3>
<p>The following example shows the structure that is used for the argument definitions in the context of a procedure declaration:</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args <b class="cmd">{
{-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
{-font -type font -default {Arial 10 italic} -description "Message text font"}
{-level -type integer -optional -range {1 10} -description "Message level"}
{-fg -type color -optional -description "Message color"}
{-log_file -type file -optional -description "Optional message log file"}
{text -type string -multiple -description "Multiple text lines to display"}
}</b>
} {
}</pre>
<p>Each of the procedure arguments is declared with a list that has as first element the argument name, followed by eventual attributes. The argument definition syntax can be formalized in the following way:</p>
<pre class="doctools_example">tepam::procedure <name> {
-args <b class="cmd">{
{<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a> <arg_attr_name_1b> <arg_attr_value_1b> ...}
{<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a> <arg_attr_name_2b> <arg_attr_value_2b> ...}
...
}</b>
} <body></pre>
<p>The argument names and attributes have to be used in the following way:</p>
<dl class="doctools_definitions">
<dt>Argument name (<em><argument_name_<n>></em>)</dt>
<dd><p>The provided argument name specifies whether the argument is an <em>unnamed argument</em> or a <em>named argument</em>. In addition to this, an argument name can also be blank to indicate an argument comment, or it can start with # to indicate a section comment.</p>
<dl class="doctools_definitions">
<dt><i class="arg">"<Name>"</i></dt>
<dd><p>This is the simplest form of an argument name: An argument whose name is not starting with '-' is an <em>unnamed argument</em>. The parameter provided during a procedure call will be assigned to a variable with the name <em><Name></em>.</p>
<pre class="doctools_example">tepam::procedure {print_string} {
-args {
{<b class="cmd"><a href="../../../../index.html#text">text</a></b> -type string -description "This is an unnamed argument"}
}
} {
puts <b class="cmd">$text</b>
}
print_string <b class="cmd">"Hello"</b>
<em> -> Hello</em></pre>
</dd>
<dt><i class="arg">"-<Name>"</i></dt>
<dd><p>An argument whose name starts with '-' is a <em>named argument</em> (also called <em>option</em>). The parameter provided during a procedure call will be assigned to a variable with the name <em><Name></em> (not <em>-<Name></em>).</p>
<pre class="doctools_example">tepam::procedure {print_string} {
-args {
{<b class="cmd">-text</b> -type string -description "This is a named argument"}
}
} {
puts <b class="cmd">$text</b>
}
print_string <b class="cmd">-text "Hello"</b>
<em> -> Hello</em></pre>
</dd>
<dt><i class="arg">"--"</i></dt>
<dd><p>This flag allows clearly specifying the end of the named arguments and the beginning of the unnamed arguments, in case the <em>named arguments first, unnamed arguments later style (Tcl)</em> has been selected.</p>
<p>If the <em>unnamed arguments first, named arguments later style (Tk)</em> style is selected, this flag is ignored if the unnamed arguments have already been parsed. Otherwise it will be assigned to the corresponding unnamed argument.</p></dd>
<dt><i class="arg">"-"</i> or <i class="arg">""</i></dt>
<dd><p>A blank argument name (either '-' or <em>''</em>) starts a comment for the following arguments.</p>
<pre class="doctools_example">tepam::procedure {print_time} {
-interactive_display_format short
-args {
{hours -type integer -description "Hour"}
{minutes -type integer -description "Minute"}
<b class="cmd">{- The following arguments are optional:}</b>
{seconds -type integer -default 0 -description "Seconds"}
{milliseconds -type integer -default 0 -description "Milliseconds"}
}
} {
puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]"
}</pre>
<p>Argument comments are basically used in the graphical argument definition forms that are created if a procedure is called interactively.</p></dd>
<dt><i class="arg">"#*"</i></dt>
<dd><p>An argument definition list that starts with '#' is considered as a section comment. The argument definition list will be trimmed from the '#' characters and the remaining string will be used as section comment.</p>
<p>Section comments can be used to structure visually the argument definition code. Section comments are also used to structure the generated help texts and the interactive argument definition forms.</p>
<pre class="doctools_example">tepam::procedure {complex_multiply} {
-description "This function perform a complex multiplication"
-args {
<b class="cmd">{#### First complex number ####}</b>
{-r0 -type double -description "First number real part"}
{-i0 -type double -description "First number imaginary part"}
<b class="cmd">{#### Second complex number ####}</b>
{-r1 -type double -description "Second number real part"}
{-i1 -type double -description "Second number imaginary part"}
}
} {
return [expr $r0*$r1 - $i0*$i1]
}</pre>
</dd>
</dl></dd>
<dt>Argument attributes (<em><arg_attr_name_<mn>> <arg_attr_value_<mn>></em>)</dt>
<dd><p>The following argument attributes are supported:</p>
<dl class="doctools_definitions">
<dt>-description <i class="arg">string</i></dt>
<dd><p>The description argument attribute is used for documentation purpose. Interactive argument definition forms use this attribute to provide explanations for an argument.</p></dd>
<dt>-type <i class="arg">type</i></dt>
<dd><p>The type argument attribute allows assigning the argument either to a predefined data type, or to an application specific data type. The argument values that are provided during a procedure call are automatically checked with respect to the defined argument type.</p>
<p>The section <span class="sectref"><a href="#section5">ARGUMENT TYPES</a></span> provides a list of predefined data types and explains how application specific types can be specified.</p>
<p>The argument type <em>none</em> has a special meaning. An argument that has the type <em>none</em> is handled as a <i class="arg">flag</i>. A flag is always optional and its related variable contains the logical value <b class="const">1</b> if the flag has been defined during the procedure call, or otherwise <b class="const">0</b>.</p></dd>
<dt>-default <i class="arg">value</i></dt>
<dd><p>Eventual default values can be defined with the -default argument attribute. Arguments with default values are automatically optional arguments.</p></dd>
<dt>-optional|-mandatory</dt>
<dd><p>Arguments are by default mandatory, unless a default value is defined. The flag <i class="arg">-optional</i> transforms an argument into an optional argument.</p>
<p>In case an optional argument is not defined during a procedure call, the corresponding variable will not be defined.
The flag <i class="arg">-mandatory</i> is the opposite to <i class="arg">-optional</i>. This flag exists only for completion reason, since an argument is anyway mandatory by default.</p></dd>
<dt>-multiple</dt>
<dd><p>Arguments that have the <i class="arg">-multiple</i> attribute can be defined multiple times during a procedure call. The values that are provided during a procedure call for such an argument are stored in a list variable. This is even the case if such an argument is only defined once during a procedure call.</p>
<p>The <i class="arg">-multiple</i> attribute can be attributed to unnamed arguments and to named arguments. The pair of argument name/argument value has to be repeated for each provided value in case of a named argument.
In case the argument with the <i class="arg">-multiple</i> attribute is an unnamed argument, this one has to be the absolute last one of all unnamed arguments.</p></dd>
<dt>-choices <i class="arg">list</i></dt>
<dd><p>A possible set of valid argument values can be attributed to an argument via the <i class="arg">-choices</i> attribute. The argument value provided during a procedure call will be checked against the provided choice values.</p></dd>
<dt>-choicelabels <i class="arg">list</i></dt>
<dd><p>An eventual short description can be attributed to each choice option with the <i class="arg">-choicelabels</i> attribute. These descriptions will be used in the generated help texts and as radio and check box labels for the interactive calls.</p>
<p>The <i class="arg">-choicelabels</i> attribute is optional, but if it is defined, its list needs to have the identical size as the <i class="arg">-choices</i> argument list.</p></dd>
<dt>-range <i class="arg">{double double}</i></dt>
<dd><p>Another argument constraint can be defined with the <i class="arg">-range</i> attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value. The <i class="arg">-range</i> attribute has to be used only for numerical arguments, like integers and doubles.</p></dd>
<dt>-validatecommand <i class="arg">script</i></dt>
<dd><p>Custom argument value validations can be performed via specific validation commands that are defined with the <i class="arg">-validatecommand</i> attribute. The provided validation command can be a complete script in which the pattern <em>%P</em> is replaced by the argument value that has to be validated.</p>
<p>Validation command declaration example:</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args {
{text -type string -description "Message text" \
<b class="cmd">-validatecommand {IllegalWordDetector %P}</b>}
} {
}</pre>
<p>While the purpose of this custom argument validation attribute is the validation of a specific argument, there is also a global attribute <i class="arg">-validatecommand</i> that allows performing validation that involves multiple arguments.</p></dd>
<dt>-validatecommand_error_text <i class="arg">string</i></dt>
<dd><p>This attribute allows overriding the default error message for a custom argument validation (defined by <i class="arg">-validatecommand</i>).</p></dd>
<dt>-widget <i class="arg">string</i></dt>
<dd><p>The widgets that allow defining the different arguments in case of an interactive procedure call are normally selected automatically in function of the argument type. The <i class="arg">-widget</i> attribute allows specifying explicitly a certain widget type for an argument.</p></dd>
<dt>-auxargs <i class="arg">list</i></dt>
<dd><p>In case a procedure is called interactively, additional argument attributes can be provided to the interactive argument definition form via the <em>-auxargs</em> attribute that is itself a list of attribute name/attribute value pairs:</p>
<pre class="doctools_example">-auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
-<arg_attr_name_1b> <arg_attr_value_1b>
...
}</pre>
<p>For example, if a procedure takes as argument a file name it may be beneficial to specify the required file type for the interactive argument definition form. This information can be provided via the <em>-auxargs</em> attribute to the argument definition form:</p>
<pre class="doctools_example">tepam::procedure LoadPicture {
-args {
{FileName -type existingfile -description "Picture file" \
<b class="cmd">-auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}</b>}
}
} {
}</pre>
</dd>
<dt>-auxargs_commands <i class="arg">script</i></dt>
<dd><p>If the auxiliary argument attributes are not static but have to be dynamically adaptable, the <em>-auxargs_commands</em> allows defining them via commands that are executed during a procedure call. A list of pairs of auxiliary attribute names and commands has to be provided to the <em>-auxargs_commands</em> attribute. The provided commands are executed in the context of the calling procedure.</p>
<pre class="doctools_example">-auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
-<arg_attr_name_1b> <arg_attr_command_1b>
...
}</pre>
</dd>
</dl></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">VARIABLES</a></h2>
<p>Several variables defined inside the <b class="namespace">::tepam</b> namespace impact the mode of operation of the procedures that have been declared with the TEPAM <b class="function">procedure</b> command.</p>
<dl class="doctools_definitions">
<dt><b class="variable">named_arguments_first</b></dt>
<dd><p>This variable defines the general calling style of the procedures. It is by default set to <b class="const">1</b> which selects the <em>named arguments first, unnamed arguments later</em> style (Tcl style).</p>
<p>By setting this variable to <b class="const">0</b>, the <em>named arguments first, unnamed arguments later</em> style is globally selected (Tk style):</p>
<pre class="doctools_example">set tepam::named_arguments_first 0</pre>
<p>While this variable defines the general calling style, the procedure attribute <i class="arg">-named_arguments_first</i> can adapt this style individually for each declared procedure.</p></dd>
<dt><b class="variable">auto_argument_name_completion</b></dt>
<dd><p>This variable controls the general automatic argument name matching mode. By default it is set to <b class="const">1</b>, meaning that the called procedures are trying to match eventually abbreviated argument names with the declared argument names.</p>
<p>By setting this variable to <b class="const">0</b> the automatic argument name matching mode is disabled:</p>
<pre class="doctools_example">set tepam::auto_argument_name_completion 0</pre>
<p>While this variable defines the general matching mode, the procedure attribute <i class="arg">-auto_argument_name_completion</i> can adapt this mode individually for each declared procedure.</p></dd>
<dt><b class="variable">interactive_display_format</b></dt>
<dd><p>A procedure declared via the TEPAM <b class="function">procedure</b> command can always be called with the <b class="variable">-interactive</b> switch. By doing so, a graphical form will be generated that allows entering interactively all procedure arguments.</p>
<p>There are two display modes for these interactive forms. The <em>extended</em> mode which is the default mode is more adapted for small procedure argument sets. The <b class="const">short</b> form is more adequate for huge procedure argument sets:</p>
<pre class="doctools_example">set tepam::interactive_display_format "short"</pre>
<p>The choice to use short or extended forms can be globally configured via the variable <b class="variable">interactive_display_format</b>.
This global setting can be changed individually for a procedure with the procedure attribute <i class="arg">-interactive_display_format</i>.</p></dd>
<dt><b class="variable">help_line_length</b></dt>
<dd><p>The maximum line length used by the procedure help text generator can be specified with this variable. The default length which is set to 80 (characters) can easily be adapted to the need of an application:</p>
<pre class="doctools_example">set tepam::help_line_length 120</pre>
<p>Since this variable is applied directly during the help text generation, its value can continuously be adapted to the current need.</p></dd>
<dt><b class="variable">command_log</b></dt>
<dd><p>Procedure calls can be logged inside the list variable <b class="variable">tepam::ProcedureCallLogList</b>. The variable <b class="variable">tepam::command_log</b> controls the default logging settings for any procedures. The following configurations are supported:</p>
<ul class="doctools_itemized">
<li><p><em>0</em>: Disables any procedure call loggings</p></li>
<li><p><em>1</em>: Enables any procedure call loggings</p></li>
<li><p><em>"interactive"</em>: Will log any procedures called interactively (e.g. procedures called with the -interactive flag). This is the default configuration.</p></li>
</ul>
<p>This default logging configuration can be changed individually for each procedure with the <i class="arg">-command_log</i> attribute.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">ARGUMENT TYPES</a></h2>
<p>TEPAM provides a comprehensive set of procedure argument types. They can easily be completed with application specific types if necessary.</p>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Predefined Argument Types</a></h3>
<p>To remember, a type can be assigned to each specified procedure argument:</p>
<pre class="doctools_example">tepam::procedure {warning} {
-args {
{-font <b class="cmd">-type font</b> -default {Arial 10 italic}}
{-severity_level <b class="cmd">-type integer</b> -optional -range {1 10}}
{-fg <b class="cmd">-type color</b> -optional -description "Message color"}
{text <b class="cmd">-type string</b> -multiple -description "Multiple text lines to display"}
}
} {
...
}</pre>
<p>There are some <em>special purpose types</em> that are building the first category of predefined argument types:</p>
<ul class="doctools_itemized">
<li><p><b class="type">none</b></p>
<p>A <em>flag</em>, also called <em>switch</em>, is defined as a named argument that has the type <b class="type">none</b>. Flags are always optional and the default value of the assigned variable is set to <b class="const">0</b>. In contrast to the (normal) named arguments, no argument value has to be provided to a flag.</p>
<pre class="doctools_example">tepam::procedure flag_test {
-args {
<b class="cmd">{-flag -type none -description "This is a flag"}</b>
}
} {
puts <b class="cmd">$flag</b>
}
flag_test
<em>-> 0</em>
flag_test -flag
<em>-> 1</em></pre>
<p>Since no argument value has to be provided to a flag, also no data check is performed for this argument type.</p></li>
<li><p><b class="type">string</b></p>
<p><b class="type">String</b> is a generic argument data type. Any data string can be provided to a string type argument and no data type checks are therefore performed. The string type allows defining single line strings during the interactive procedure calls.</p></li>
<li><p><b class="type">text</b></p>
<p><b class="type">Text</b> is identical to <b class="type">string</b> with the only difference that it allows entering multi line strings during interactive procedure calls.</p></li>
<li><p><b class="type">{}</b></p>
<p>A <b class="type">blank</b> argument type signifies an undefined argument type. This is the default argument type that will be used if no type has been explicitly specified. An argument that has a <b class="type">blank</b> type behaves identically than an argument that has a <b class="type">string</b> type, e.g. no argument data checks are performed. The only difference is that the data type <b class="type">string</b> is mentioned in the generated help documentation, while this is not the case for the <b class="type">blank</b> type.</p></li>
</ul>
<p>Several <em>numerical types</em> are defined by TEPAM. The type validation procedures are using the <b class="cmd">string is <type> -strict</b> commands to check the validity of the provided arguments, which assures that no empty strings are accepted as argument value. The type validation expression for the numerical types and the argument types to which this expression is applied are:</p>
<pre class="doctools_example">string is <b class="type"><type_to_check></b> -strict <i class="arg"><argument_value></i></pre>
<ul class="doctools_itemized">
<li><p><em>boolean</em></p></li>
<li><p><em>integer</em></p></li>
<li><p><em>double</em></p></li>
</ul>
<p>Empty strings are accepted as argument value for all the alpha numeric argument types. The argument types that are falling into this category and validation expression used for them are:</p>
<pre class="doctools_example">string is <em><type_to_check></em> <i class="arg"><argument_value></i></pre>
<ul class="doctools_itemized">
<li><p><em>alnum</em></p></li>
<li><p><em>alpha</em></p></li>
<li><p><em>ascii</em></p></li>
<li><p><em>control</em></p></li>
<li><p><em>digit</em></p></li>
<li><p><em>graph</em></p></li>
<li><p><em>lower</em></p></li>
<li><p><em>print</em></p></li>
<li><p><em>punct</em></p></li>
<li><p><em>space</em></p></li>
<li><p><em>upper</em></p></li>
<li><p><em>wordchar</em></p></li>
<li><p><em>xdigit</em></p></li>
</ul>
<p>In addition to the data types checked with the <b class="cmd">string is <type></b> commands, TEPAM specifies some other useful data types:</p>
<ul class="doctools_itemized">
<li><p><em>char</em></p>
<p>Each string that has a length of 1 character meets the <em>character</em> type. The type check is made with the following expression:</p>
<pre class="doctools_example">expr [string length <i class="arg"><argument_value></i>]==1</pre>
</li>
<li><p><em>color</em></p>
<p>Any character strings that are accepted by Tk as a color are considered as valid color argument. Please note that the Tk package has to be loaded to use the type <em>color</em>. TEPAM is using the following command to validate the color type:</p>
<pre class="doctools_example">expr ![catch {winfo rgb . <i class="arg"><argument_value></i>}]</pre>
</li>
<li><p><em>font</em></p>
<p>Any character strings that are accepted by Tk as a font are considered as valid font argument. Please note that the Tk package has to be loaded to use the <em>font</em> type. TEPAM is using the following command to validate the color type:</p>
<pre class="doctools_example">expr ![catch {font measure <argument_value> ""}]</pre>
</li>
<li><p><em>file</em></p>
<p>Any strings that are not containing one of the following characters are considered as valid file names: * ? " < >. It is not necessary that the file and its containing directory exist. Zero-length strings are not considered as valid file names.</p>
<p>The following expression is used to validate the file names:</p>
<pre class="doctools_example">expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]</pre>
</li>
<li><p><em>existingfile</em></p>
<p>The argument is valid if it matches with an existing file. The following check is performed to validate the arguments of this type:</p>
<pre class="doctools_example">file exists <argument_value></pre>
</li>
<li><p><em>directory</em></p>
<p>The directory argument is validated exactly in the same way as the file arguments.</p></li>
<li><p><em>existingdirectory</em></p>
<p>The argument is valid if it matches with an existing directory. The following check is performed to validate the arguments of this type:</p>
<pre class="doctools_example">file isdirectory <argument_value></pre>
</li>
</ul>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Defining Application Specific Argument Types</a></h3>
<p>To add support for a new application specific argument type it is just necessary to add into the namespace <b class="namespace">tepam</b> a validation function <b class="function">Validation(<type>)</b>. This function requires one argument. It has to returns <b class="const">1</b> if the provided argument matches with the relevant data type. The function has to return otherwise <b class="const">0</b>.</p>
<p>The validation command section of the "<b class="file">tepam.tcl</b>" package provides sufficient examples of validation functions, since it implements the ones for the standard TEPAM types.</p>
<p>The following additional code snippet shows the validation function for a custom argument type that requires values that have a character string length of exactly 2:</p>
<pre class="doctools_example">proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}}</pre>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">PROCEDURE CALLS</a></h2>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Help</a></h3>
<p>Each procedure can be called with the <i class="arg">-help</i> flag. The procedure will then print a generated help text to <em>stdout</em> and will then return without performing any additional actions.</p>
<p>Taking the first procedure declared in <span class="sectref"><a href="#section6">PROCEDURE CALLS</a></span>, the help request and the printed help text would be:</p>
<pre class="doctools_example"><b class="cmd">display message -help</b>
<em>->
NAME
display message - Displays a simple message box
SYNOPSIS
display message
[-mtype <mtype>]
Message type, default: "Warning", choices: {Info, Warning, Error}
<text>
Multiple text lines to display, type: string
DESCRIPTION
This procedure allows displaying a configurable message box. The default
message type that is created is a warning, but also errors and info can
be generated.
The procedure accepts multiple text lines.
EXAMPLE
display message -mtype Warning "Save first your job"</em></pre>
<p>The argument manager is checking if the last provided argument is <em>-help</em> and generates the requested help message if this is the case. So, also the following example will print the help message:</p>
<pre class="doctools_example"><b class="cmd">display message -mtype Info "It is 7:00" -help</b></pre>
<p>On the other hand, the following call will result in an error:</p>
<pre class="doctools_example"><b class="cmd">display message -help -mtype Info "It is 7:00"</b>
<em>->
display message: Argument '-help' not known</em></pre>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Interactive Procedure Call</a></h3>
<p>If Tk has been loaded a procedure can be called with the <i class="arg">-interactive</i> flag to open a graphical form that allows specifying interactively all procedure arguments. The following example assures that the Tk library is loaded and shows the command line to call interactively the procedure declared in <span class="sectref"><a href="#section6">PROCEDURE CALLS</a></span>:</p>
<pre class="doctools_example">package require Tk
<b class="cmd">display message -interactive</b></pre>
<p>Also the <i class="arg">-interactive</i> flag has to be placed at the last argument position as this is also required for the <i class="arg">-help</i> flag. Arguments defined before the <i class="arg">-interactive</i> flag will be ignored. The following example is therefore also a valid interactive procedure call:</p>
<pre class="doctools_example"><b class="cmd">display message</b> -mtype Info "It is 7:00" <b class="cmd">-interactive</b></pre>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Unnamed Arguments</a></h3>
<p>Unnamed arguments are typically provided to the called procedure as simple parameters. This procedure calling form requires that the provided arguments are strictly following the order of the specified arguments. Several parameters can be assigned to the last argument if this one has the <em>-multiple</em> attribute. So, the following declared procedure ...</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args {
{mtype -choices {Info Warning Error}}
{text -type string -multiple}
}
} {
puts "$mtype: [join $text]"
}</pre>
<p>... can for example be called in the following ways:</p>
<pre class="doctools_example"><b class="cmd">display_message Info "It is PM 7:00."</b>
<em>-> Info: It is PM 7:00.</em>
<b class="cmd">display_message Info "It is PM 7:00." "You should go home."</b>
<em>-> Info: It is PM 7:00. You should go home.</em></pre>
<p>The nice thing is that unnamed arguments can also be called as named arguments, which can be handy, for example if the exact specified argument order is not known to a user:</p>
<pre class="doctools_example"><b class="cmd">display_message -mtype Info -text "It is PM 7:00."</b>
<em>-> Info: It is PM 7:00.</em>
<b class="cmd">display_message -text "It is PM 7:00." -mtype Info</b>
<em>-> Info: It is PM 7:00.</em>
<b class="cmd">display_message -mtype Info -text "It is PM 7:00." -text "You should go home."</b>
<em>-> Info: It is PM 7:00. You should go home.</em>
<b class="cmd">display_message -text "It is PM 7:00." -text "You should go home." -mtype Info</b>
<em>-> Info: It is PM 7:00. You should go home.</em></pre>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Named Arguments</a></h3>
<p>Named arguments have to be provided to a procedure in form of a parameter pairs composed by the argument names and the argument values. The order how they are provided during a procedure call is irrelevant and has not to match with the argument specification order.</p>
<p>The following declared procedure ...</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args {
{-mtype -choices {Info Warning Error}}
{-text -type string -multiple}
}
} {
puts "$mtype: [join $text]"
}</pre>
<p>... can be called in the following ways:</p>
<pre class="doctools_example"><b class="cmd">display_message -mtype Info -text "It is PM 7:00."</b>
<em>-> Info: It is PM 7:00.</em>
<b class="cmd">display_message -text "It is PM 7:00." -mtype Info</b>
<em>-> Info: It is PM 7:00.</em>
<b class="cmd">display_message -mtype Info -text "It is PM 7:00." -text "You should go home."</b>
<em>-> Info: It is PM 7:00. You should go home.</em>
<b class="cmd">display_message -text "It is PM 7:00." -text "You should go home." -mtype Info</b>
<em>-> Info: It is PM 7:00. You should go home.</em></pre>
<p>Also named arguments that have not the <em>-multiple</em> attribute can be provided multiple times. Only the last provided argument will be retained in such a case:</p>
<pre class="doctools_example"><b class="cmd">display_message -mtype Info -text "It is PM 7:00." -mtype Warning</b>
<em>-> Warning: It is PM 7:00.</em></pre>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Unnamed Arguments First, Named Arguments Later (Tk Style)</a></h3>
<p>A procedure that has been defined while the variable <b class="variable">tepam::named_arguments_first</b> was set to 1, or with the procedure attribute <i class="arg">-named_arguments_first</i> set to 1 has to be called in the Tcl style. The following procedure declaration will be used in this section to illustrate the meaning of this calling style:</p>
<pre class="doctools_example"><b class="cmd">set tepam::named_arguments_first 1</b>
tepam::procedure my_proc {
-args {
{-n1 -default ""}
{-n2 -default ""}
{u1 -default ""}
{u2 -default ""}
}
} {
puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
}</pre>
<p>The unnamed arguments are placed at the end of procedure call, after the named arguments:</p>
<pre class="doctools_example">my_proc <b class="cmd">-n1 N1 -n2 N2 U1 U2</b>
<em>-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'</em></pre>
<p>The argument parser considers the first argument that doesn't start with the '-' character as well as all following arguments as unnamed argument:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 U2</b>
<em>-> n1:'', n2:'', u1:'U1', u2:'U2'</em></pre>
<p>Named arguments can be defined multiple times. If the named argument has the <em>-multiply</em> attribute, all argument values will be collected in a list. Otherwise, only the last provided attribute value will be retained:</p>
<pre class="doctools_example">my_proc <b class="cmd">-n1 N1 -n2 N2 -n1 M1 U1 U2</b>
<em>-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'</em></pre>
<p>The name of the first unnamed argument has therefore not to start with the '-' character. The unnamed argument is otherwise considered as name of another named argument. This is especially important if the first unnamed argument is given by a variable that can contain any character strings:</p>
<pre class="doctools_example">my_proc <b class="cmd">-n1 N1 -n2 N2 "->" "<-"</b>
<em>-> my_proc: Argument '->' not known</em>
set U1 "->"
my_proc <b class="cmd">-n1 N1 -n2 N2 $U1 U2</b>
my_proc: Argument '->' not known</pre>
<p>The '--' flag allows separating unambiguously the unnamed arguments from the named arguments. All data after the '--' flag will be considered as unnamed argument:</p>
<pre class="doctools_example">my_proc <b class="cmd">-n1 N1 -n2 N2 -- "->" "<-"</b>
<em>-> n1:'N1', n2:'N2', u1:'->', u2:'<-'</em>
set U1 "->"
my_proc <b class="cmd">-n1 N1 -n2 N2 -- $U1 U2</b>
<em>-> n1:'N1', n2:'N2', u1:'->', u2:'<-'</em></pre>
</div>
<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Named Arguments First, Unnamed Arguments Later (Tcl Style)</a></h3>
<p>The Tk calling style will be chosen if a procedure is defined while the variable <b class="variable">tepam::named_arguments_first</b> is set to 0, or if the procedure attribute <i class="arg">-named_arguments_first</i> has been set to 0. The following procedure will be used in this section to illustrate this calling style:</p>
<pre class="doctools_example"><b class="cmd">set tepam::named_arguments_first 0</b>
tepam::procedure my_proc {
-args {
{-n1 -default ""}
{-n2 -default ""}
{u1}
{u2 -default "" -multiple}
}
} {
puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
}</pre>
<p>The unnamed arguments have to be provided first in this case. The named arguments are provided afterwards:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 U2 -n1 N1 -n2 N2</b>
<em>-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'</em></pre>
<p>The argument parser will assign to each defined unnamed argument a value before it switches to read the named arguments. This default behavior changes a bit if there are unnamed arguments that are optional or that can take multiple values.</p>
<p>An argument value will only be assigned to an unnamed argument that is optional (that has either the <i class="arg">-optional</i> attribute or that has a default value), if the value is not beginning with the '-' character or if no named arguments are defined. The value that starts with '-' is otherwise considered as the name of a named argument.</p>
<p>Argument values are assigned to an argument that has the <i class="arg">-multiple</i> attribute as long as the parameter value doesn't starts with the '-' character.</p>
<p>Values that start with the '-' character can therefore not be assigned to optional unnamed arguments, which restricts the usage of the Tcl procedure calling style. The Tk style may be preferable in some cases, since it allows separating unambiguously the named arguments from the unnamed ones with the '--' flag.</p>
<p>Let's explore in a bit less theoretically the ways how the previously defined procedure can be called: The first example calls the procedure without any parameters, which leads to an error since <i class="arg">u1</i> is a mandatory argument:</p>
<pre class="doctools_example">my_proc
<em>-> my_proc: Required argument is missing: u1</em></pre>
<p>The procedure call is valid if one parameter is provided for <i class="arg">u1</i>:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1</b>
<em>-> n1:'', n2:'', u1:'U1', u2:''</em></pre>
<p>If more parameters are provided that are not starting with the '-' character, they will be attributed to the unnamed arguments. <i class="arg">U2</i> will receive 3 of these parameters, since it accepts multiple values:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 U2 U3 U4</b>
<em>-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'</em></pre>
<p>As soon as one parameter starts with '-' and all unnamed arguments have been assigned, the argument manager tries to interpret the parameter as name of a named argument. The procedure call will fail if a value beginning with '-' is assigned to an unnamed argument:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 U2 U3 U4 -U5</b>
<em>-> my_proc: Argument '-U5' not known</em></pre>
<p>The attribution of a parameter to a named argument will fail if there are undefined unnamed (non optional) arguments. The name specification will in this case simply be considered as a parameter value that is attributed to the <em>next</em> unnamed argument. This was certainly not the intention in the following example:</p>
<pre class="doctools_example">my_proc <b class="cmd">-n1 N1</b>
<em>-> n1:'', n2:'', u1:'-n1', u2:'N1'</em></pre>
<p>The situation is completely different if values have already been assigned to all mandatory unnamed arguments. A parameter beginning with the '-' character will in this case be considered as a name identifier for a named argument:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 -n1 N1</b>
<em>-> n1:'N1', n2:'', u1:'U1', u2:''</em></pre>
<p>No unnamed arguments are allowed behind the named arguments:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 -n1 N1 U2</b>
<em>-> my_proc: Argument 'U2' is not an option</em></pre>
<p>The '--' flag has no special meaning if not all mandatory arguments have got assigned a value. This flag will simply be attributed to one of the unnamed arguments:</p>
<pre class="doctools_example">my_proc <b class="cmd">-- -n1 N1</b>
<em>-> n1:'N1', n2:'', u1:'--', u2:''</em></pre>
<p>But the '--' flag is simply ignored if the argument parser has started to handle the named arguments:</p>
<pre class="doctools_example">my_proc <b class="cmd">U1 -- -n1 N1</b>
<em>-> n1:'N1', n2:'', u1:'U1', u2:''</em>
my_proc <b class="cmd">U1 -n1 N1 -- -n2 N2</b>
<em>-> n1:'N1', n2:'N2', u1:'U1', u2:''</em></pre>
</div>
<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Raw Argument List</a></h3>
<p>It may be necessary sometimes that the procedure body is able to access the entire list of arguments provided during a procedure call. This can happen via the <b class="variable">args</b> variable that contains always the unprocessed argument list:</p>
<pre class="doctools_example">tepam::procedure {display_message} {
-args {
{-mtype -choices {Warning Error} -default Warning}
{text -type string -multiple}
}
} {
puts "args: <b class="cmd">$args</b>"
}
display_message -mtype Warning "It is 7:00"
<em>-> args: -mtype Warning {It is 7:00}</em></pre>
</div>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="tepam_introduction.html">tepam(n)</a>, <a href="tepam_argument_dialogbox.html">tepam::argument_dialogbox(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#argument_integrity">argument integrity</a>, <a href="../../../../index.html#argument_validation">argument validation</a>, <a href="../../../../index.html#arguments">arguments</a>, <a href="../../../../index.html#procedure">procedure</a>, <a href="../../../../index.html#subcommand">subcommand</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Procedures, arguments, parameters, options</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2013, Andreas Drollinger</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ansi_cattr.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
<div class='fossil-doc' data-title='term::ansi::code::attr - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::ansi::code::attr(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::ansi::code::attr - ANSI attribute sequences</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Introspection</a></li>
<li class="doctools_subsection"><a href="#subsection2">Attributes</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::ansi::code <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">term::ansi::code::attr <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::ansi::code::attr::names</b></a></li>
<li><a href="#2"><b class="cmd">::term::ansi::code::attr::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">::term::ansi::code::attr::fgblack</b></a></li>
<li><a href="#4"><b class="cmd">::term::ansi::code::attr::fgred</b></a></li>
<li><a href="#5"><b class="cmd">::term::ansi::code::attr::fggreen</b></a></li>
<li><a href="#6"><b class="cmd">::term::ansi::code::attr::fgyellow</b></a></li>
<li><a href="#7"><b class="cmd">::term::ansi::code::attr::fgblue</b></a></li>
<li><a href="#8"><b class="cmd">::term::ansi::code::attr::fgmagenta</b></a></li>
<li><a href="#9"><b class="cmd">::term::ansi::code::attr::fgcyan</b></a></li>
<li><a href="#10"><b class="cmd">::term::ansi::code::attr::fgwhite</b></a></li>
<li><a href="#11"><b class="cmd">::term::ansi::code::attr::fgdefault</b></a></li>
<li><a href="#12"><b class="cmd">::term::ansi::code::attr::bgblack</b></a></li>
<li><a href="#13"><b class="cmd">::term::ansi::code::attr::bgred</b></a></li>
<li><a href="#14"><b class="cmd">::term::ansi::code::attr::bggreen</b></a></li>
<li><a href="#15"><b class="cmd">::term::ansi::code::attr::bgyellow</b></a></li>
<li><a href="#16"><b class="cmd">::term::ansi::code::attr::bgblue</b></a></li>
<li><a href="#17"><b class="cmd">::term::ansi::code::attr::bgmagenta</b></a></li>
<li><a href="#18"><b class="cmd">::term::ansi::code::attr::bgcyan</b></a></li>
<li><a href="#19"><b class="cmd">::term::ansi::code::attr::bgwhite</b></a></li>
<li><a href="#20"><b class="cmd">::term::ansi::code::attr::bgdefault</b></a></li>
<li><a href="#21"><b class="cmd">::term::ansi::code::attr::bold</b></a></li>
<li><a href="#22"><b class="cmd">::term::ansi::code::attr::dim</b></a></li>
<li><a href="#23"><b class="cmd">::term::ansi::code::attr::italic</b></a></li>
<li><a href="#24"><b class="cmd">::term::ansi::code::attr::underline</b></a></li>
<li><a href="#25"><b class="cmd">::term::ansi::code::attr::blink</b></a></li>
<li><a href="#26"><b class="cmd">::term::ansi::code::attr::revers</b></a></li>
<li><a href="#27"><b class="cmd">::term::ansi::code::attr::hidden</b></a></li>
<li><a href="#28"><b class="cmd">::term::ansi::code::attr::strike</b></a></li>
<li><a href="#29"><b class="cmd">::term::ansi::code::attr::nobold</b></a></li>
<li><a href="#30"><b class="cmd">::term::ansi::code::attr::noitalic</b></a></li>
<li><a href="#31"><b class="cmd">::term::ansi::code::attr::nounderline</b></a></li>
<li><a href="#32"><b class="cmd">::term::ansi::code::attr::noblink</b></a></li>
<li><a href="#33"><b class="cmd">::term::ansi::code::attr::norevers</b></a></li>
<li><a href="#34"><b class="cmd">::term::ansi::code::attr::nohidden</b></a></li>
<li><a href="#35"><b class="cmd">::term::ansi::code::attr::nostrike</b></a></li>
<li><a href="#36"><b class="cmd">::term::ansi::code::attr::reset</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides symbolic names for the ANSI attribute control
codes. For each control code a single command is provided which
returns this code as its result. None of the commands of this package
write to a channel; that is handled by higher level packages, like
<b class="package"><a href="ansi_send.html">term::ansi::send</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Introspection</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::ansi::code::attr::names</b></a></dt>
<dd><p>This command is for introspection. It returns as its result a list
containing the names of all attribute commands.</p></dd>
<dt><a name="2"><b class="cmd">::term::ansi::code::attr::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command imports some or all attribute commands into the namespace
<i class="arg">ns</i>. This is by default the namespace <em>attr</em>. Note that this
is relative namespace name, placing the imported command into a child
of the current namespace. By default all commands are imported, this
can howver be restricted by listing the names of the wanted commands
after the namespace argument.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Attributes</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::term::ansi::code::attr::fgblack</b></a></dt>
<dd><p>Set text color to <em>Black</em>.</p></dd>
<dt><a name="4"><b class="cmd">::term::ansi::code::attr::fgred</b></a></dt>
<dd><p>Set text color to <em>Red</em>.</p></dd>
<dt><a name="5"><b class="cmd">::term::ansi::code::attr::fggreen</b></a></dt>
<dd><p>Set text color to <em>Green</em>.</p></dd>
<dt><a name="6"><b class="cmd">::term::ansi::code::attr::fgyellow</b></a></dt>
<dd><p>Set text color to <em>Yellow</em>.</p></dd>
<dt><a name="7"><b class="cmd">::term::ansi::code::attr::fgblue</b></a></dt>
<dd><p>Set text color to <em>Blue</em>.</p></dd>
<dt><a name="8"><b class="cmd">::term::ansi::code::attr::fgmagenta</b></a></dt>
<dd><p>Set text color to <em>Magenta</em>.</p></dd>
<dt><a name="9"><b class="cmd">::term::ansi::code::attr::fgcyan</b></a></dt>
<dd><p>Set text color to <em>Cyan</em>.</p></dd>
<dt><a name="10"><b class="cmd">::term::ansi::code::attr::fgwhite</b></a></dt>
<dd><p>Set text color to <em>White</em>.</p></dd>
<dt><a name="11"><b class="cmd">::term::ansi::code::attr::fgdefault</b></a></dt>
<dd><p>Set default text color (<em>Black</em>).</p></dd>
<dt><a name="12"><b class="cmd">::term::ansi::code::attr::bgblack</b></a></dt>
<dd><p>Set background to <em>Black</em>.</p></dd>
<dt><a name="13"><b class="cmd">::term::ansi::code::attr::bgred</b></a></dt>
<dd><p>Set background to <em>Red</em>.</p></dd>
<dt><a name="14"><b class="cmd">::term::ansi::code::attr::bggreen</b></a></dt>
<dd><p>Set background to <em>Green</em>.</p></dd>
<dt><a name="15"><b class="cmd">::term::ansi::code::attr::bgyellow</b></a></dt>
<dd><p>Set background to <em>Yellow</em>.</p></dd>
<dt><a name="16"><b class="cmd">::term::ansi::code::attr::bgblue</b></a></dt>
<dd><p>Set background to <em>Blue</em>.</p></dd>
<dt><a name="17"><b class="cmd">::term::ansi::code::attr::bgmagenta</b></a></dt>
<dd><p>Set background to <em>Magenta</em>.</p></dd>
<dt><a name="18"><b class="cmd">::term::ansi::code::attr::bgcyan</b></a></dt>
<dd><p>Set background to <em>Cyan</em>.</p></dd>
<dt><a name="19"><b class="cmd">::term::ansi::code::attr::bgwhite</b></a></dt>
<dd><p>Set background to <em>White</em>.</p></dd>
<dt><a name="20"><b class="cmd">::term::ansi::code::attr::bgdefault</b></a></dt>
<dd><p>Set default background (Transparent).</p></dd>
<dt><a name="21"><b class="cmd">::term::ansi::code::attr::bold</b></a></dt>
<dd><p>Bold on.</p></dd>
<dt><a name="22"><b class="cmd">::term::ansi::code::attr::dim</b></a></dt>
<dd><p>Dim on.</p></dd>
<dt><a name="23"><b class="cmd">::term::ansi::code::attr::italic</b></a></dt>
<dd><p>Italics on.</p></dd>
<dt><a name="24"><b class="cmd">::term::ansi::code::attr::underline</b></a></dt>
<dd><p>Underscore on.</p></dd>
<dt><a name="25"><b class="cmd">::term::ansi::code::attr::blink</b></a></dt>
<dd><p>Blink on.</p></dd>
<dt><a name="26"><b class="cmd">::term::ansi::code::attr::revers</b></a></dt>
<dd><p>Reverse on.</p></dd>
<dt><a name="27"><b class="cmd">::term::ansi::code::attr::hidden</b></a></dt>
<dd><p>Hidden on.</p></dd>
<dt><a name="28"><b class="cmd">::term::ansi::code::attr::strike</b></a></dt>
<dd><p>Strike-through on.</p></dd>
<dt><a name="29"><b class="cmd">::term::ansi::code::attr::nobold</b></a></dt>
<dd><p>Bold off.</p></dd>
<dt><a name="30"><b class="cmd">::term::ansi::code::attr::noitalic</b></a></dt>
<dd><p>Italics off.</p></dd>
<dt><a name="31"><b class="cmd">::term::ansi::code::attr::nounderline</b></a></dt>
<dd><p>Underscore off.</p></dd>
<dt><a name="32"><b class="cmd">::term::ansi::code::attr::noblink</b></a></dt>
<dd><p>Blink off.</p></dd>
<dt><a name="33"><b class="cmd">::term::ansi::code::attr::norevers</b></a></dt>
<dd><p>Reverse off.</p></dd>
<dt><a name="34"><b class="cmd">::term::ansi::code::attr::nohidden</b></a></dt>
<dd><p>Hidden off.</p></dd>
<dt><a name="35"><b class="cmd">::term::ansi::code::attr::nostrike</b></a></dt>
<dd><p>Strike-through off.</p></dd>
<dt><a name="36"><b class="cmd">::term::ansi::code::attr::reset</b></a></dt>
<dd><p>Reset all attributes to their default values.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ansi">ansi</a>, <a href="../../../../index.html#attribute_control">attribute control</a>, <a href="../../../../index.html#color_control">color control</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ansi_cctrl.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
|
<div class='fossil-doc' data-title='term::ansi::code::ctrl - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::ansi::code::ctrl(n) 0.2 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::ansi::code::ctrl - ANSI control sequences</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Introspection</a></li>
<li class="doctools_subsection"><a href="#subsection2">Sequences</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::ansi::code <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">term::ansi::code::ctrl <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::ansi::code::ctrl::names</b></a></li>
<li><a href="#2"><b class="cmd">::term::ansi::code::ctrl::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">::term::ansi::code::ctrl::eeol</b></a></li>
<li><a href="#4"><b class="cmd">::term::ansi::code::ctrl::esol</b></a></li>
<li><a href="#5"><b class="cmd">::term::ansi::code::ctrl::el</b></a></li>
<li><a href="#6"><b class="cmd">::term::ansi::code::ctrl::ed</b></a></li>
<li><a href="#7"><b class="cmd">::term::ansi::code::ctrl::eu</b></a></li>
<li><a href="#8"><b class="cmd">::term::ansi::code::ctrl::es</b></a></li>
<li><a href="#9"><b class="cmd">::term::ansi::code::ctrl::sd</b></a></li>
<li><a href="#10"><b class="cmd">::term::ansi::code::ctrl::su</b></a></li>
<li><a href="#11"><b class="cmd">::term::ansi::code::ctrl::ch</b></a></li>
<li><a href="#12"><b class="cmd">::term::ansi::code::ctrl::sc</b></a></li>
<li><a href="#13"><b class="cmd">::term::ansi::code::ctrl::rc</b></a></li>
<li><a href="#14"><b class="cmd">::term::ansi::code::ctrl::sca</b></a></li>
<li><a href="#15"><b class="cmd">::term::ansi::code::ctrl::rca</b></a></li>
<li><a href="#16"><b class="cmd">::term::ansi::code::ctrl::st</b></a></li>
<li><a href="#17"><b class="cmd">::term::ansi::code::ctrl::ct</b></a></li>
<li><a href="#18"><b class="cmd">::term::ansi::code::ctrl::cat</b></a></li>
<li><a href="#19"><b class="cmd">::term::ansi::code::ctrl::qdc</b></a></li>
<li><a href="#20"><b class="cmd">::term::ansi::code::ctrl::qds</b></a></li>
<li><a href="#21"><b class="cmd">::term::ansi::code::ctrl::qcp</b></a></li>
<li><a href="#22"><b class="cmd">::term::ansi::code::ctrl::rd</b></a></li>
<li><a href="#23"><b class="cmd">::term::ansi::code::ctrl::elw</b></a></li>
<li><a href="#24"><b class="cmd">::term::ansi::code::ctrl::dlw</b></a></li>
<li><a href="#25"><b class="cmd">::term::ansi::code::ctrl::eg</b></a></li>
<li><a href="#26"><b class="cmd">::term::ansi::code::ctrl::lg</b></a></li>
<li><a href="#27"><b class="cmd">::term::ansi::code::ctrl::scs0</b> <i class="arg">tag</i></a></li>
<li><a href="#28"><b class="cmd">::term::ansi::code::ctrl::scs1</b> <i class="arg">tag</i></a></li>
<li><a href="#29"><b class="cmd">::term::ansi::code::ctrl::sda</b> <i class="arg">arg</i>...</a></li>
<li><a href="#30"><b class="cmd">::term::ansi::code::ctrl::sda_fgblack</b></a></li>
<li><a href="#31"><b class="cmd">::term::ansi::code::ctrl::sda_fgred</b></a></li>
<li><a href="#32"><b class="cmd">::term::ansi::code::ctrl::sda_fggreen</b></a></li>
<li><a href="#33"><b class="cmd">::term::ansi::code::ctrl::sda_fgyellow</b></a></li>
<li><a href="#34"><b class="cmd">::term::ansi::code::ctrl::sda_fgblue</b></a></li>
<li><a href="#35"><b class="cmd">::term::ansi::code::ctrl::sda_fgmagenta</b></a></li>
<li><a href="#36"><b class="cmd">::term::ansi::code::ctrl::sda_fgcyan</b></a></li>
<li><a href="#37"><b class="cmd">::term::ansi::code::ctrl::sda_fgwhite</b></a></li>
<li><a href="#38"><b class="cmd">::term::ansi::code::ctrl::sda_fgdefault</b></a></li>
<li><a href="#39"><b class="cmd">::term::ansi::code::ctrl::sda_bgblack</b></a></li>
<li><a href="#40"><b class="cmd">::term::ansi::code::ctrl::sda_bgred</b></a></li>
<li><a href="#41"><b class="cmd">::term::ansi::code::ctrl::sda_bggreen</b></a></li>
<li><a href="#42"><b class="cmd">::term::ansi::code::ctrl::sda_bgyellow</b></a></li>
<li><a href="#43"><b class="cmd">::term::ansi::code::ctrl::sda_bgblue</b></a></li>
<li><a href="#44"><b class="cmd">::term::ansi::code::ctrl::sda_bgmagenta</b></a></li>
<li><a href="#45"><b class="cmd">::term::ansi::code::ctrl::sda_bgcyan</b></a></li>
<li><a href="#46"><b class="cmd">::term::ansi::code::ctrl::sda_bgwhite</b></a></li>
<li><a href="#47"><b class="cmd">::term::ansi::code::ctrl::sda_bgdefault</b></a></li>
<li><a href="#48"><b class="cmd">::term::ansi::code::ctrl::sda_bold</b></a></li>
<li><a href="#49"><b class="cmd">::term::ansi::code::ctrl::sda_dim</b></a></li>
<li><a href="#50"><b class="cmd">::term::ansi::code::ctrl::sda_italic</b></a></li>
<li><a href="#51"><b class="cmd">::term::ansi::code::ctrl::sda_underline</b></a></li>
<li><a href="#52"><b class="cmd">::term::ansi::code::ctrl::sda_blink</b></a></li>
<li><a href="#53"><b class="cmd">::term::ansi::code::ctrl::sda_revers</b></a></li>
<li><a href="#54"><b class="cmd">::term::ansi::code::ctrl::sda_hidden</b></a></li>
<li><a href="#55"><b class="cmd">::term::ansi::code::ctrl::sda_strike</b></a></li>
<li><a href="#56"><b class="cmd">::term::ansi::code::ctrl::sda_nobold</b></a></li>
<li><a href="#57"><b class="cmd">::term::ansi::code::ctrl::sda_noitalic</b></a></li>
<li><a href="#58"><b class="cmd">::term::ansi::code::ctrl::sda_nounderline</b></a></li>
<li><a href="#59"><b class="cmd">::term::ansi::code::ctrl::sda_noblink</b></a></li>
<li><a href="#60"><b class="cmd">::term::ansi::code::ctrl::sda_norevers</b></a></li>
<li><a href="#61"><b class="cmd">::term::ansi::code::ctrl::sda_nohidden</b></a></li>
<li><a href="#62"><b class="cmd">::term::ansi::code::ctrl::sda_nostrike</b></a></li>
<li><a href="#63"><b class="cmd">::term::ansi::code::ctrl::sda_reset</b></a></li>
<li><a href="#64"><b class="cmd">::term::ansi::send::fcp</b> <i class="arg">row</i> <i class="arg">col</i></a></li>
<li><a href="#65"><b class="cmd">::term::ansi::code::ctrl::cu</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#66"><b class="cmd">::term::ansi::code::ctrl::cd</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#67"><b class="cmd">::term::ansi::code::ctrl::cf</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#68"><b class="cmd">::term::ansi::code::ctrl::cb</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#69"><b class="cmd">::term::ansi::code::ctrl::ss</b> <span class="opt">?<i class="arg">s</i> <i class="arg">e</i>?</span></a></li>
<li><a href="#70"><b class="cmd">::term::ansi::code::ctrl::skd</b> <i class="arg">code</i> <i class="arg">str</i></a></li>
<li><a href="#71"><b class="cmd">::term::ansi::code::ctrl::title</b> <i class="arg">str</i></a></li>
<li><a href="#72"><b class="cmd">::term::ansi::code::ctrl::gron</b></a></li>
<li><a href="#73"><b class="cmd">::term::ansi::code::ctrl::groff</b></a></li>
<li><a href="#74"><b class="cmd">::term::ansi::code::ctrl::tlc</b></a></li>
<li><a href="#75"><b class="cmd">::term::ansi::code::ctrl::trc</b></a></li>
<li><a href="#76"><b class="cmd">::term::ansi::code::ctrl::brc</b></a></li>
<li><a href="#77"><b class="cmd">::term::ansi::code::ctrl::blc</b></a></li>
<li><a href="#78"><b class="cmd">::term::ansi::code::ctrl::ltj</b></a></li>
<li><a href="#79"><b class="cmd">::term::ansi::code::ctrl::ttj</b></a></li>
<li><a href="#80"><b class="cmd">::term::ansi::code::ctrl::rtj</b></a></li>
<li><a href="#81"><b class="cmd">::term::ansi::code::ctrl::btj</b></a></li>
<li><a href="#82"><b class="cmd">::term::ansi::code::ctrl::fwj</b></a></li>
<li><a href="#83"><b class="cmd">::term::ansi::code::ctrl::hl</b></a></li>
<li><a href="#84"><b class="cmd">::term::ansi::code::ctrl::vl</b></a></li>
<li><a href="#85"><b class="cmd">::term::ansi::code::ctrl::groptim</b> <i class="arg">str</i></a></li>
<li><a href="#86"><b class="cmd">::term::ansi::code::ctrl::clear</b></a></li>
<li><a href="#87"><b class="cmd">::term::ansi::code::ctrl::init</b></a></li>
<li><a href="#88"><b class="cmd">::term::ansi::code::ctrl::showat</b> <i class="arg">row</i> <i class="arg">col</i> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides symbolic names for the ANSI control
sequences. For each sequence a single command is provided which
returns the sequence as its result. None of the commands of this
package write to a channel; that is handled by higher level packages,
like <b class="package"><a href="ansi_send.html">term::ansi::send</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Introspection</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::ansi::code::ctrl::names</b></a></dt>
<dd><p>This command is for introspection. It returns as its result a list
containing the names of all attribute commands.</p></dd>
<dt><a name="2"><b class="cmd">::term::ansi::code::ctrl::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command imports some or all attribute commands into the namespace
<i class="arg">ns</i>. This is by default the namespace <em>ctrl</em>. Note that this
is relative namespace name, placing the imported command into a child
of the current namespace. By default all commands are imported, this
can howver be restricted by listing the names of the wanted commands
after the namespace argument.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Sequences</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::term::ansi::code::ctrl::eeol</b></a></dt>
<dd><p>Erase (to) End Of Line</p></dd>
<dt><a name="4"><b class="cmd">::term::ansi::code::ctrl::esol</b></a></dt>
<dd><p>Erase (to) Start Of Line</p></dd>
<dt><a name="5"><b class="cmd">::term::ansi::code::ctrl::el</b></a></dt>
<dd><p>Erase (current) Line</p></dd>
<dt><a name="6"><b class="cmd">::term::ansi::code::ctrl::ed</b></a></dt>
<dd><p>Erase Down (to bottom)</p></dd>
<dt><a name="7"><b class="cmd">::term::ansi::code::ctrl::eu</b></a></dt>
<dd><p>Erase Up (to top)</p></dd>
<dt><a name="8"><b class="cmd">::term::ansi::code::ctrl::es</b></a></dt>
<dd><p>Erase Screen</p></dd>
<dt><a name="9"><b class="cmd">::term::ansi::code::ctrl::sd</b></a></dt>
<dd><p>Scroll Down</p></dd>
<dt><a name="10"><b class="cmd">::term::ansi::code::ctrl::su</b></a></dt>
<dd><p>Scroll Up</p></dd>
<dt><a name="11"><b class="cmd">::term::ansi::code::ctrl::ch</b></a></dt>
<dd><p>Cursor Home</p></dd>
<dt><a name="12"><b class="cmd">::term::ansi::code::ctrl::sc</b></a></dt>
<dd><p>Save Cursor</p></dd>
<dt><a name="13"><b class="cmd">::term::ansi::code::ctrl::rc</b></a></dt>
<dd><p>Restore Cursor (Unsave)</p></dd>
<dt><a name="14"><b class="cmd">::term::ansi::code::ctrl::sca</b></a></dt>
<dd><p>Save Cursor + Attributes</p></dd>
<dt><a name="15"><b class="cmd">::term::ansi::code::ctrl::rca</b></a></dt>
<dd><p>Restore Cursor + Attributes</p></dd>
<dt><a name="16"><b class="cmd">::term::ansi::code::ctrl::st</b></a></dt>
<dd><p>Set Tab (@ current position)</p></dd>
<dt><a name="17"><b class="cmd">::term::ansi::code::ctrl::ct</b></a></dt>
<dd><p>Clear Tab (@ current position)</p></dd>
<dt><a name="18"><b class="cmd">::term::ansi::code::ctrl::cat</b></a></dt>
<dd><p>Clear All Tabs</p></dd>
<dt><a name="19"><b class="cmd">::term::ansi::code::ctrl::qdc</b></a></dt>
<dd><p>Query Device Code</p></dd>
<dt><a name="20"><b class="cmd">::term::ansi::code::ctrl::qds</b></a></dt>
<dd><p>Query Device Status</p></dd>
<dt><a name="21"><b class="cmd">::term::ansi::code::ctrl::qcp</b></a></dt>
<dd><p>Query Cursor Position</p></dd>
<dt><a name="22"><b class="cmd">::term::ansi::code::ctrl::rd</b></a></dt>
<dd><p>Reset Device</p></dd>
<dt><a name="23"><b class="cmd">::term::ansi::code::ctrl::elw</b></a></dt>
<dd><p>Enable Line Wrap</p></dd>
<dt><a name="24"><b class="cmd">::term::ansi::code::ctrl::dlw</b></a></dt>
<dd><p>Disable Line Wrap</p></dd>
<dt><a name="25"><b class="cmd">::term::ansi::code::ctrl::eg</b></a></dt>
<dd><p>Enter Graphics Mode</p></dd>
<dt><a name="26"><b class="cmd">::term::ansi::code::ctrl::lg</b></a></dt>
<dd><p>Exit Graphics Mode</p></dd>
<dt><a name="27"><b class="cmd">::term::ansi::code::ctrl::scs0</b> <i class="arg">tag</i></a></dt>
<dd><p>Set default character set</p></dd>
<dt><a name="28"><b class="cmd">::term::ansi::code::ctrl::scs1</b> <i class="arg">tag</i></a></dt>
<dd><p>Set alternate character set
Select Character Set.</p>
<p>Choose which character set is used for either default (scs0) or
alternate font (scs1). This does not change whether default or
alternate font are used, only their definition.</p>
<p>The legal tags, and their meanings, are:</p>
<dl class="doctools_definitions">
<dt>A</dt>
<dd><p>United Kingdom Set</p></dd>
<dt>B</dt>
<dd><p>ASCII Set</p></dd>
<dt>0</dt>
<dd><p>Special Graphics</p></dd>
<dt>1</dt>
<dd><p>Alternate Character ROM Standard Character Set</p></dd>
<dt>2</dt>
<dd><p>Alternate Character ROM Special Graphics</p></dd>
</dl></dd>
<dt><a name="29"><b class="cmd">::term::ansi::code::ctrl::sda</b> <i class="arg">arg</i>...</a></dt>
<dd><p>Set Display Attributes. The arguments are the code sequences for the possible
attributes, as provided by the package <b class="package"><a href="ansi_cattr.html">term::ansi::code::attr</a></b>. For
convenience this package also provides additional commands each setting a single
specific attribute.</p></dd>
<dt><a name="30"><b class="cmd">::term::ansi::code::ctrl::sda_fgblack</b></a></dt>
<dd><p>Set text color to <em>Black</em>.</p></dd>
<dt><a name="31"><b class="cmd">::term::ansi::code::ctrl::sda_fgred</b></a></dt>
<dd><p>Set text color to <em>Red</em>.</p></dd>
<dt><a name="32"><b class="cmd">::term::ansi::code::ctrl::sda_fggreen</b></a></dt>
<dd><p>Set text color to <em>Green</em>.</p></dd>
<dt><a name="33"><b class="cmd">::term::ansi::code::ctrl::sda_fgyellow</b></a></dt>
<dd><p>Set text color to <em>Yellow</em>.</p></dd>
<dt><a name="34"><b class="cmd">::term::ansi::code::ctrl::sda_fgblue</b></a></dt>
<dd><p>Set text color to <em>Blue</em>.</p></dd>
<dt><a name="35"><b class="cmd">::term::ansi::code::ctrl::sda_fgmagenta</b></a></dt>
<dd><p>Set text color to <em>Magenta</em>.</p></dd>
<dt><a name="36"><b class="cmd">::term::ansi::code::ctrl::sda_fgcyan</b></a></dt>
<dd><p>Set text color to <em>Cyan</em>.</p></dd>
<dt><a name="37"><b class="cmd">::term::ansi::code::ctrl::sda_fgwhite</b></a></dt>
<dd><p>Set text color to <em>White</em>.</p></dd>
<dt><a name="38"><b class="cmd">::term::ansi::code::ctrl::sda_fgdefault</b></a></dt>
<dd><p>Set default text color (<em>Black</em>).</p></dd>
<dt><a name="39"><b class="cmd">::term::ansi::code::ctrl::sda_bgblack</b></a></dt>
<dd><p>Set background to <em>Black</em>.</p></dd>
<dt><a name="40"><b class="cmd">::term::ansi::code::ctrl::sda_bgred</b></a></dt>
<dd><p>Set background to <em>Red</em>.</p></dd>
<dt><a name="41"><b class="cmd">::term::ansi::code::ctrl::sda_bggreen</b></a></dt>
<dd><p>Set background to <em>Green</em>.</p></dd>
<dt><a name="42"><b class="cmd">::term::ansi::code::ctrl::sda_bgyellow</b></a></dt>
<dd><p>Set background to <em>Yellow</em>.</p></dd>
<dt><a name="43"><b class="cmd">::term::ansi::code::ctrl::sda_bgblue</b></a></dt>
<dd><p>Set background to <em>Blue</em>.</p></dd>
<dt><a name="44"><b class="cmd">::term::ansi::code::ctrl::sda_bgmagenta</b></a></dt>
<dd><p>Set background to <em>Magenta</em>.</p></dd>
<dt><a name="45"><b class="cmd">::term::ansi::code::ctrl::sda_bgcyan</b></a></dt>
<dd><p>Set background to <em>Cyan</em>.</p></dd>
<dt><a name="46"><b class="cmd">::term::ansi::code::ctrl::sda_bgwhite</b></a></dt>
<dd><p>Set background to <em>White</em>.</p></dd>
<dt><a name="47"><b class="cmd">::term::ansi::code::ctrl::sda_bgdefault</b></a></dt>
<dd><p>Set default background (Transparent).</p></dd>
<dt><a name="48"><b class="cmd">::term::ansi::code::ctrl::sda_bold</b></a></dt>
<dd><p>Bold on.</p></dd>
<dt><a name="49"><b class="cmd">::term::ansi::code::ctrl::sda_dim</b></a></dt>
<dd><p>Dim on.</p></dd>
<dt><a name="50"><b class="cmd">::term::ansi::code::ctrl::sda_italic</b></a></dt>
<dd><p>Italics on.</p></dd>
<dt><a name="51"><b class="cmd">::term::ansi::code::ctrl::sda_underline</b></a></dt>
<dd><p>Underscore on.</p></dd>
<dt><a name="52"><b class="cmd">::term::ansi::code::ctrl::sda_blink</b></a></dt>
<dd><p>Blink on.</p></dd>
<dt><a name="53"><b class="cmd">::term::ansi::code::ctrl::sda_revers</b></a></dt>
<dd><p>Reverse on.</p></dd>
<dt><a name="54"><b class="cmd">::term::ansi::code::ctrl::sda_hidden</b></a></dt>
<dd><p>Hidden on.</p></dd>
<dt><a name="55"><b class="cmd">::term::ansi::code::ctrl::sda_strike</b></a></dt>
<dd><p>Strike-through on.</p></dd>
<dt><a name="56"><b class="cmd">::term::ansi::code::ctrl::sda_nobold</b></a></dt>
<dd><p>Bold off.</p></dd>
<dt><a name="57"><b class="cmd">::term::ansi::code::ctrl::sda_noitalic</b></a></dt>
<dd><p>Italics off.</p></dd>
<dt><a name="58"><b class="cmd">::term::ansi::code::ctrl::sda_nounderline</b></a></dt>
<dd><p>Underscore off.</p></dd>
<dt><a name="59"><b class="cmd">::term::ansi::code::ctrl::sda_noblink</b></a></dt>
<dd><p>Blink off.</p></dd>
<dt><a name="60"><b class="cmd">::term::ansi::code::ctrl::sda_norevers</b></a></dt>
<dd><p>Reverse off.</p></dd>
<dt><a name="61"><b class="cmd">::term::ansi::code::ctrl::sda_nohidden</b></a></dt>
<dd><p>Hidden off.</p></dd>
<dt><a name="62"><b class="cmd">::term::ansi::code::ctrl::sda_nostrike</b></a></dt>
<dd><p>Strike-through off.</p></dd>
<dt><a name="63"><b class="cmd">::term::ansi::code::ctrl::sda_reset</b></a></dt>
<dd><p>Reset all attributes to their default values.</p></dd>
<dt><a name="64"><b class="cmd">::term::ansi::send::fcp</b> <i class="arg">row</i> <i class="arg">col</i></a></dt>
<dd><p>Force Cursor Position (aka Go To).</p></dd>
<dt><a name="65"><b class="cmd">::term::ansi::code::ctrl::cu</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Up. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="66"><b class="cmd">::term::ansi::code::ctrl::cd</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Down. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="67"><b class="cmd">::term::ansi::code::ctrl::cf</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Forward. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="68"><b class="cmd">::term::ansi::code::ctrl::cb</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Backward. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="69"><b class="cmd">::term::ansi::code::ctrl::ss</b> <span class="opt">?<i class="arg">s</i> <i class="arg">e</i>?</span></a></dt>
<dd><p>Scroll Screen (entire display, or between rows start end, inclusive).</p></dd>
<dt><a name="70"><b class="cmd">::term::ansi::code::ctrl::skd</b> <i class="arg">code</i> <i class="arg">str</i></a></dt>
<dd><p>Set Key Definition.</p></dd>
<dt><a name="71"><b class="cmd">::term::ansi::code::ctrl::title</b> <i class="arg">str</i></a></dt>
<dd><p>Set the terminal title.</p></dd>
<dt><a name="72"><b class="cmd">::term::ansi::code::ctrl::gron</b></a></dt>
<dd><p>Switch to character/box graphics. I.e. switch to the alternate font.</p></dd>
<dt><a name="73"><b class="cmd">::term::ansi::code::ctrl::groff</b></a></dt>
<dd><p>Switch to regular characters. I.e. switch to the default font.</p></dd>
<dt><a name="74"><b class="cmd">::term::ansi::code::ctrl::tlc</b></a></dt>
<dd><p>Character graphics, Top Left Corner.</p></dd>
<dt><a name="75"><b class="cmd">::term::ansi::code::ctrl::trc</b></a></dt>
<dd><p>Character graphics, Top Right Corner.</p></dd>
<dt><a name="76"><b class="cmd">::term::ansi::code::ctrl::brc</b></a></dt>
<dd><p>Character graphics, Bottom Right Corner.</p></dd>
<dt><a name="77"><b class="cmd">::term::ansi::code::ctrl::blc</b></a></dt>
<dd><p>Character graphics, Bottom Left Corner.</p></dd>
<dt><a name="78"><b class="cmd">::term::ansi::code::ctrl::ltj</b></a></dt>
<dd><p>Character graphics, Left T Junction.</p></dd>
<dt><a name="79"><b class="cmd">::term::ansi::code::ctrl::ttj</b></a></dt>
<dd><p>Character graphics, Top T Junction.</p></dd>
<dt><a name="80"><b class="cmd">::term::ansi::code::ctrl::rtj</b></a></dt>
<dd><p>Character graphics, Right T Junction.</p></dd>
<dt><a name="81"><b class="cmd">::term::ansi::code::ctrl::btj</b></a></dt>
<dd><p>Character graphics, Bottom T Junction.</p></dd>
<dt><a name="82"><b class="cmd">::term::ansi::code::ctrl::fwj</b></a></dt>
<dd><p>Character graphics, Four-Way Junction.</p></dd>
<dt><a name="83"><b class="cmd">::term::ansi::code::ctrl::hl</b></a></dt>
<dd><p>Character graphics, Horizontal Line.</p></dd>
<dt><a name="84"><b class="cmd">::term::ansi::code::ctrl::vl</b></a></dt>
<dd><p>Character graphics, Vertical Line.</p></dd>
<dt><a name="85"><b class="cmd">::term::ansi::code::ctrl::groptim</b> <i class="arg">str</i></a></dt>
<dd><p>Optimize character graphics. The generator commands above create way to many
superfluous commands shifting into and out of the graphics mode. This command
removes all shifts which are not needed. To this end it also knows which
characters will look the same in both modes, to handle strings created outside
of this package.</p></dd>
<dt><a name="86"><b class="cmd">::term::ansi::code::ctrl::clear</b></a></dt>
<dd><p>Clear screen. In essence a sequence of CursorHome + EraseDown.</p></dd>
<dt><a name="87"><b class="cmd">::term::ansi::code::ctrl::init</b></a></dt>
<dd><p>Initialize default and alternate fonts to ASCII and box graphics.</p></dd>
<dt><a name="88"><b class="cmd">::term::ansi::code::ctrl::showat</b> <i class="arg">row</i> <i class="arg">col</i> <i class="arg">text</i></a></dt>
<dd><p>Format the block of text for display at the specified location.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ansi">ansi</a>, <a href="../../../../index.html#attribute_control">attribute control</a>, <a href="../../../../index.html#color_control">color control</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ansi_cmacros.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<div class='fossil-doc' data-title='term::ansi::code::macros - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::ansi::code::macros(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::ansi::code::macros - Macro sequences</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Introspection</a></li>
<li class="doctools_subsection"><a href="#subsection2">Sequences</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">textutil::repeat</b></li>
<li>package require <b class="pkgname">textutil::tabify</b></li>
<li>package require <b class="pkgname">term::ansi::code::macros <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::ansi::code::macros::names</b></a></li>
<li><a href="#2"><b class="cmd">::term::ansi::code::macros::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">::term::ansi::code::macros::menu</b> <i class="arg">menu</i></a></li>
<li><a href="#4"><b class="cmd">::term::ansi::code::macros::frame</b> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides higher level control sequences for more complex
shapes.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Introspection</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::ansi::code::macros::names</b></a></dt>
<dd><p>This command is for introspection. It returns as its result a list
containing the names of all attribute commands.</p></dd>
<dt><a name="2"><b class="cmd">::term::ansi::code::macros::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command imports some or all attribute commands into the namespace
<i class="arg">ns</i>. This is by default the namespace <em>macros</em>. Note that
this is relative namespace name, placing the imported command into a
child of the current namespace. By default all commands are imported,
this can howver be restricted by listing the names of the wanted
commands after the namespace argument.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Sequences</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><b class="cmd">::term::ansi::code::macros::menu</b> <i class="arg">menu</i></a></dt>
<dd><p>The description of a menu is converted into a formatted rectangular
block of text, with the menu command characters highlighted using bold
red text. The result is returned as the result of the command.</p>
<p>The description, <i class="arg">menu</i>, is a dictionary mapping from menu label
to command character.</p></dd>
<dt><a name="4"><b class="cmd">::term::ansi::code::macros::frame</b> <i class="arg">string</i></a></dt>
<dd><p>The paragraph of text contained in the string is padded with spaces at
the right margin, after normalizing internal tabs, and then put into a
frame made of box-graphics. The result is returned as the result of
the command.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ansi">ansi</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#frame">frame</a>, <a href="../../../../index.html#menu">menu</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ansi_code.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<div class='fossil-doc' data-title='term::ansi::code - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::ansi::code(n) 0.2 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::ansi::code - Helper for control sequences</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::ansi::code <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::ansi::code::esc</b> <i class="arg">str</i></a></li>
<li><a href="#2"><b class="cmd">::term::ansi::code::escb</b> <i class="arg">str</i></a></li>
<li><a href="#3"><b class="cmd">::term::ansi::code::define</b> <i class="arg">name</i> <i class="arg">escape</i> <i class="arg">code</i></a></li>
<li><a href="#4"><b class="cmd">::term::ansi::code::const</b> <i class="arg">name</i> <i class="arg">code</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands enabling the definition of control
sequences in an easy manner.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::ansi::code::esc</b> <i class="arg">str</i></a></dt>
<dd><p>This command returns the argument string, prefixed with the ANSI
escape character, "\033."</p></dd>
<dt><a name="2"><b class="cmd">::term::ansi::code::escb</b> <i class="arg">str</i></a></dt>
<dd><p>This command returns the argument string, prefixed with a common ANSI
escape sequence, "\033[".</p></dd>
<dt><a name="3"><b class="cmd">::term::ansi::code::define</b> <i class="arg">name</i> <i class="arg">escape</i> <i class="arg">code</i></a></dt>
<dd><p>This command defines a procedure <i class="arg">name</i> which returns the control
sequence <i class="arg">code</i>, beginning with the specified escape sequence,
either <b class="const">esc</b>, or <b class="const">escb</b>.</p></dd>
<dt><a name="4"><b class="cmd">::term::ansi::code::const</b> <i class="arg">name</i> <i class="arg">code</i></a></dt>
<dd><p>This command defines a procedure <i class="arg">name</i> which returns the control
sequence <i class="arg">code</i>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#declare">declare</a>, <a href="../../../../index.html#define">define</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ansi_ctrlu.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<div class='fossil-doc' data-title='term::ansi::ctrl::unix - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::ansi::ctrl::unix(n) 0.1.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::ansi::ctrl::unix - Control operations and queries</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Introspection</a></li>
<li class="doctools_subsection"><a href="#subsection2">Operations</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::ansi::ctrl::unix <span class="opt">?0.1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::ansi::ctrl::unix::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">::term::ansi::ctrl::unix::raw</b></a></li>
<li><a href="#3"><b class="cmd">::term::ansi::ctrl::unix::cooked</b></a></li>
<li><a href="#4"><b class="cmd">::term::ansi::ctrl::unix::columns</b></a></li>
<li><a href="#5"><b class="cmd">::term::ansi::ctrl::unix::rows</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><em>WARNING</em>: This package is unix-specific and depends on the
availability of two unix system commands for terminal control,
i.e. <b class="syscmd">stty</b> and <b class="syscmd">tput</b>, both of which have to be found
in the <b class="variable">$PATH</b>. If any of these two commands is missing the
loading of the package will fail.</p>
<p>The package provides commands to switch the standard input of the
current process between <i class="term"><a href="../../../../index.html#raw">raw</a></i> and <i class="term"><a href="../../../../index.html#cooked">cooked</a></i> input modes, and
to query the size of terminals, i.e. the available number of columns
and lines.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Introspection</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::ansi::ctrl::unix::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command imports some or all attribute commands into the namespace
<i class="arg">ns</i>. This is by default the namespace <em>ctrl</em>. Note that this
is relative namespace name, placing the imported command into a child
of the current namespace. By default all commands are imported, this
can howver be restricted by listing the names of the wanted commands
after the namespace argument.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Operations</a></h3>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">::term::ansi::ctrl::unix::raw</b></a></dt>
<dd><p>This command switches the standard input of the current process to
<i class="term"><a href="../../../../index.html#raw">raw</a></i> input mode. This means that from then on all characters
typed by the user are immediately reported to the application instead
of waiting in the OS buffer until the Enter/Return key is received.</p></dd>
<dt><a name="3"><b class="cmd">::term::ansi::ctrl::unix::cooked</b></a></dt>
<dd><p>This command switches the standard input of the current process to
<i class="term"><a href="../../../../index.html#cooked">cooked</a></i> input mode. This means that from then on all characters
typed by the user are kept in OS buffers for editing until the
Enter/Return key is received.</p></dd>
<dt><a name="4"><b class="cmd">::term::ansi::ctrl::unix::columns</b></a></dt>
<dd><p>This command queries the terminal connected to the standard input for
the number of columns available for display.</p></dd>
<dt><a name="5"><b class="cmd">::term::ansi::ctrl::unix::rows</b></a></dt>
<dd><p>This command queries the terminal connected to the standard input for
the number of rows (aka lines) available for display.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#ansi">ansi</a>, <a href="../../../../index.html#columns">columns</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#cooked">cooked</a>, <a href="../../../../index.html#input_mode">input mode</a>, <a href="../../../../index.html#lines">lines</a>, <a href="../../../../index.html#raw">raw</a>, <a href="../../../../index.html#rows">rows</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ansi_send.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
|
<div class='fossil-doc' data-title='term::ansi::send - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::ansi::send(n) 0.2 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::ansi::send - Output of ANSI control sequences to terminals</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::ansi::send <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::ansi::send::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <i class="arg">...</i></a></li>
<li><a href="#2"><b class="cmd">::term::ansi::send::eeol</b></a></li>
<li><a href="#3"><b class="cmd">::term::ansi::send::esol</b></a></li>
<li><a href="#4"><b class="cmd">::term::ansi::send::el</b></a></li>
<li><a href="#5"><b class="cmd">::term::ansi::send::ed</b></a></li>
<li><a href="#6"><b class="cmd">::term::ansi::send::eu</b></a></li>
<li><a href="#7"><b class="cmd">::term::ansi::send::es</b></a></li>
<li><a href="#8"><b class="cmd">::term::ansi::send::sd</b></a></li>
<li><a href="#9"><b class="cmd">::term::ansi::send::su</b></a></li>
<li><a href="#10"><b class="cmd">::term::ansi::send::ch</b></a></li>
<li><a href="#11"><b class="cmd">::term::ansi::send::sc</b></a></li>
<li><a href="#12"><b class="cmd">::term::ansi::send::rc</b></a></li>
<li><a href="#13"><b class="cmd">::term::ansi::send::sca</b></a></li>
<li><a href="#14"><b class="cmd">::term::ansi::send::rca</b></a></li>
<li><a href="#15"><b class="cmd">::term::ansi::send::st</b></a></li>
<li><a href="#16"><b class="cmd">::term::ansi::send::ct</b></a></li>
<li><a href="#17"><b class="cmd">::term::ansi::send::cat</b></a></li>
<li><a href="#18"><b class="cmd">::term::ansi::send::qdc</b></a></li>
<li><a href="#19"><b class="cmd">::term::ansi::send::qds</b></a></li>
<li><a href="#20"><b class="cmd">::term::ansi::send::qcp</b></a></li>
<li><a href="#21"><b class="cmd">::term::ansi::send::rd</b></a></li>
<li><a href="#22"><b class="cmd">::term::ansi::send::elw</b></a></li>
<li><a href="#23"><b class="cmd">::term::ansi::send::dlw</b></a></li>
<li><a href="#24"><b class="cmd">::term::ansi::send::eg</b></a></li>
<li><a href="#25"><b class="cmd">::term::ansi::send::lg</b></a></li>
<li><a href="#26"><b class="cmd">::term::ansi::send::scs0</b> <i class="arg">tag</i></a></li>
<li><a href="#27"><b class="cmd">::term::ansi::send::scs1</b> <i class="arg">tag</i></a></li>
<li><a href="#28"><b class="cmd">::term::ansi::send::sda</b> <i class="arg">arg</i>...</a></li>
<li><a href="#29"><b class="cmd">::term::ansi::send::sda_fgblack</b></a></li>
<li><a href="#30"><b class="cmd">::term::ansi::send::sda_fgred</b></a></li>
<li><a href="#31"><b class="cmd">::term::ansi::send::sda_fggreen</b></a></li>
<li><a href="#32"><b class="cmd">::term::ansi::send::sda_fgyellow</b></a></li>
<li><a href="#33"><b class="cmd">::term::ansi::send::sda_fgblue</b></a></li>
<li><a href="#34"><b class="cmd">::term::ansi::send::sda_fgmagenta</b></a></li>
<li><a href="#35"><b class="cmd">::term::ansi::send::sda_fgcyan</b></a></li>
<li><a href="#36"><b class="cmd">::term::ansi::send::sda_fgwhite</b></a></li>
<li><a href="#37"><b class="cmd">::term::ansi::send::sda_fgdefault</b></a></li>
<li><a href="#38"><b class="cmd">::term::ansi::send::sda_bgblack</b></a></li>
<li><a href="#39"><b class="cmd">::term::ansi::send::sda_bgred</b></a></li>
<li><a href="#40"><b class="cmd">::term::ansi::send::sda_bggreen</b></a></li>
<li><a href="#41"><b class="cmd">::term::ansi::send::sda_bgyellow</b></a></li>
<li><a href="#42"><b class="cmd">::term::ansi::send::sda_bgblue</b></a></li>
<li><a href="#43"><b class="cmd">::term::ansi::send::sda_bgmagenta</b></a></li>
<li><a href="#44"><b class="cmd">::term::ansi::send::sda_bgcyan</b></a></li>
<li><a href="#45"><b class="cmd">::term::ansi::send::sda_bgwhite</b></a></li>
<li><a href="#46"><b class="cmd">::term::ansi::send::sda_bgdefault</b></a></li>
<li><a href="#47"><b class="cmd">::term::ansi::send::sda_bold</b></a></li>
<li><a href="#48"><b class="cmd">::term::ansi::send::sda_dim</b></a></li>
<li><a href="#49"><b class="cmd">::term::ansi::send::sda_italic</b></a></li>
<li><a href="#50"><b class="cmd">::term::ansi::send::sda_underline</b></a></li>
<li><a href="#51"><b class="cmd">::term::ansi::send::sda_blink</b></a></li>
<li><a href="#52"><b class="cmd">::term::ansi::send::sda_revers</b></a></li>
<li><a href="#53"><b class="cmd">::term::ansi::send::sda_hidden</b></a></li>
<li><a href="#54"><b class="cmd">::term::ansi::send::sda_strike</b></a></li>
<li><a href="#55"><b class="cmd">::term::ansi::send::sda_nobold</b></a></li>
<li><a href="#56"><b class="cmd">::term::ansi::send::sda_noitalic</b></a></li>
<li><a href="#57"><b class="cmd">::term::ansi::send::sda_nounderline</b></a></li>
<li><a href="#58"><b class="cmd">::term::ansi::send::sda_noblink</b></a></li>
<li><a href="#59"><b class="cmd">::term::ansi::send::sda_norevers</b></a></li>
<li><a href="#60"><b class="cmd">::term::ansi::send::sda_nohidden</b></a></li>
<li><a href="#61"><b class="cmd">::term::ansi::send::sda_nostrike</b></a></li>
<li><a href="#62"><b class="cmd">::term::ansi::send::sda_reset</b></a></li>
<li><a href="#63"><b class="cmd">::term::ansi::send::fcp</b> <i class="arg">row</i> <i class="arg">col</i></a></li>
<li><a href="#64"><b class="cmd">::term::ansi::send::cu</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#65"><b class="cmd">::term::ansi::send::cd</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#66"><b class="cmd">::term::ansi::send::cf</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#67"><b class="cmd">::term::ansi::send::cb</b> <span class="opt">?<i class="arg">n</i>?</span></a></li>
<li><a href="#68"><b class="cmd">::term::ansi::send::ss</b> <span class="opt">?<i class="arg">s</i> <i class="arg">e</i>?</span></a></li>
<li><a href="#69"><b class="cmd">::term::ansi::send::skd</b> <i class="arg">code</i> <i class="arg">str</i></a></li>
<li><a href="#70"><b class="cmd">::term::ansi::send::title</b> <i class="arg">str</i></a></li>
<li><a href="#71"><b class="cmd">::term::ansi::send::gron</b></a></li>
<li><a href="#72"><b class="cmd">::term::ansi::send::groff</b></a></li>
<li><a href="#73"><b class="cmd">::term::ansi::send::tlc</b></a></li>
<li><a href="#74"><b class="cmd">::term::ansi::send::trc</b></a></li>
<li><a href="#75"><b class="cmd">::term::ansi::send::brc</b></a></li>
<li><a href="#76"><b class="cmd">::term::ansi::send::blc</b></a></li>
<li><a href="#77"><b class="cmd">::term::ansi::send::ltj</b></a></li>
<li><a href="#78"><b class="cmd">::term::ansi::send::ttj</b></a></li>
<li><a href="#79"><b class="cmd">::term::ansi::send::rtj</b></a></li>
<li><a href="#80"><b class="cmd">::term::ansi::send::btj</b></a></li>
<li><a href="#81"><b class="cmd">::term::ansi::send::fwj</b></a></li>
<li><a href="#82"><b class="cmd">::term::ansi::send::hl</b></a></li>
<li><a href="#83"><b class="cmd">::term::ansi::send::vl</b></a></li>
<li><a href="#84"><b class="cmd">::term::ansi::send::groptim</b> <i class="arg">str</i></a></li>
<li><a href="#85"><b class="cmd">::term::ansi::send::clear</b></a></li>
<li><a href="#86"><b class="cmd">::term::ansi::send::init</b></a></li>
<li><a href="#87"><b class="cmd">::term::ansi::send::showat</b> <i class="arg">row</i> <i class="arg">col</i> <i class="arg">text</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to send ANSI terminal control sequences to a
terminal. All commands come in two variants, one for sending to any channel,
the other for sending to <em>stdout</em>.</p>
<p>The commands are defined using the control sequences provided by the package
<b class="package"><a href="ansi_cctrl.html">term::ansi::code::ctrl</a></b>. They have the same arguments as the commands
they are based on, with the exception of the variant for sending to any channel.
Their first argument is always a channel handle, then followed by the original
arguments. Below we will list only the variant sending to <em>stdout</em>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::ansi::send::import</b> <span class="opt">?<i class="arg">ns</i>?</span> <i class="arg">...</i></a></dt>
<dd><p>Imports the commands of this package into the namespace <i class="arg">ns</i>. If not specified
it defaults to <em>send</em>. Note that this default is a relative namespace name,
i.e. the actual namespace will be created under the current namespace.</p>
<p>By default all commands will be imported, this can however be restricted to specific
commands, by listing them after the namespace to import them into.</p></dd>
<dt><a name="2"><b class="cmd">::term::ansi::send::eeol</b></a></dt>
<dd><p>Erase (to) End Of Line.</p></dd>
<dt><a name="3"><b class="cmd">::term::ansi::send::esol</b></a></dt>
<dd><p>Erase (to) Start Of Line.</p></dd>
<dt><a name="4"><b class="cmd">::term::ansi::send::el</b></a></dt>
<dd><p>Erase (current) Line.</p></dd>
<dt><a name="5"><b class="cmd">::term::ansi::send::ed</b></a></dt>
<dd><p>Erase Down (to bottom).</p></dd>
<dt><a name="6"><b class="cmd">::term::ansi::send::eu</b></a></dt>
<dd><p>Erase Up (to top).</p></dd>
<dt><a name="7"><b class="cmd">::term::ansi::send::es</b></a></dt>
<dd><p>Erase Screen.</p></dd>
<dt><a name="8"><b class="cmd">::term::ansi::send::sd</b></a></dt>
<dd><p>Scroll Down.</p></dd>
<dt><a name="9"><b class="cmd">::term::ansi::send::su</b></a></dt>
<dd><p>Scroll Up.</p></dd>
<dt><a name="10"><b class="cmd">::term::ansi::send::ch</b></a></dt>
<dd><p>Cursor Home.</p></dd>
<dt><a name="11"><b class="cmd">::term::ansi::send::sc</b></a></dt>
<dd><p>Save Cursor. Note: Only one saved position can be handled.
This is no unlimited stack. Saving before restoring will
overwrite the saved data.</p></dd>
<dt><a name="12"><b class="cmd">::term::ansi::send::rc</b></a></dt>
<dd><p>Restore Cursor (Unsave).</p></dd>
<dt><a name="13"><b class="cmd">::term::ansi::send::sca</b></a></dt>
<dd><p>Save Cursor + Attributes.</p></dd>
<dt><a name="14"><b class="cmd">::term::ansi::send::rca</b></a></dt>
<dd><p>Restore Cursor + Attributes.</p></dd>
<dt><a name="15"><b class="cmd">::term::ansi::send::st</b></a></dt>
<dd><p>Set Tab (@ current position).</p></dd>
<dt><a name="16"><b class="cmd">::term::ansi::send::ct</b></a></dt>
<dd><p>Clear Tab (@ current position).</p></dd>
<dt><a name="17"><b class="cmd">::term::ansi::send::cat</b></a></dt>
<dd><p>Clear All Tabs.</p></dd>
<dt><a name="18"><b class="cmd">::term::ansi::send::qdc</b></a></dt>
<dd><p>Query Device Code.</p></dd>
<dt><a name="19"><b class="cmd">::term::ansi::send::qds</b></a></dt>
<dd><p>Query Device Status.</p></dd>
<dt><a name="20"><b class="cmd">::term::ansi::send::qcp</b></a></dt>
<dd><p>Query Cursor Position.</p></dd>
<dt><a name="21"><b class="cmd">::term::ansi::send::rd</b></a></dt>
<dd><p>Reset Device.</p></dd>
<dt><a name="22"><b class="cmd">::term::ansi::send::elw</b></a></dt>
<dd><p>Enable Line Wrap.</p></dd>
<dt><a name="23"><b class="cmd">::term::ansi::send::dlw</b></a></dt>
<dd><p>Disable Line Wrap.</p></dd>
<dt><a name="24"><b class="cmd">::term::ansi::send::eg</b></a></dt>
<dd><p>Enter Graphics Mode.</p></dd>
<dt><a name="25"><b class="cmd">::term::ansi::send::lg</b></a></dt>
<dd><p>Exit Graphics Mode.</p></dd>
<dt><a name="26"><b class="cmd">::term::ansi::send::scs0</b> <i class="arg">tag</i></a></dt>
<dd></dd>
<dt><a name="27"><b class="cmd">::term::ansi::send::scs1</b> <i class="arg">tag</i></a></dt>
<dd><p>Select Character Set.</p>
<p>Choose which character set is used for default (scs0) and alternate font (scs1).
This does not change whether default or alternate font are used, just their
definitions.</p>
<p>The legal tags, and their meanings, are:</p>
<dl class="doctools_definitions">
<dt>A</dt>
<dd><p>United Kingdom Set</p></dd>
<dt>B</dt>
<dd><p>ASCII Set</p></dd>
<dt>0</dt>
<dd><p>Special Graphics</p></dd>
<dt>1</dt>
<dd><p>Alternate Character ROM Standard Character Set</p></dd>
<dt>2</dt>
<dd><p>Alternate Character ROM Special Graphics</p></dd>
</dl></dd>
<dt><a name="28"><b class="cmd">::term::ansi::send::sda</b> <i class="arg">arg</i>...</a></dt>
<dd><p>Set Display Attributes. The arguments are the code sequences for the possible
attributes, as provided by the package <b class="package"><a href="ansi_cattr.html">term::ansi::code::attr</a></b>. For
convenience this package also provides additional commands each setting a single
specific attribute.</p></dd>
<dt><a name="29"><b class="cmd">::term::ansi::send::sda_fgblack</b></a></dt>
<dd><p>Set text color to <em>Black</em>.</p></dd>
<dt><a name="30"><b class="cmd">::term::ansi::send::sda_fgred</b></a></dt>
<dd><p>Set text color to <em>Red</em>.</p></dd>
<dt><a name="31"><b class="cmd">::term::ansi::send::sda_fggreen</b></a></dt>
<dd><p>Set text color to <em>Green</em>.</p></dd>
<dt><a name="32"><b class="cmd">::term::ansi::send::sda_fgyellow</b></a></dt>
<dd><p>Set text color to <em>Yellow</em>.</p></dd>
<dt><a name="33"><b class="cmd">::term::ansi::send::sda_fgblue</b></a></dt>
<dd><p>Set text color to <em>Blue</em>.</p></dd>
<dt><a name="34"><b class="cmd">::term::ansi::send::sda_fgmagenta</b></a></dt>
<dd><p>Set text color to <em>Magenta</em>.</p></dd>
<dt><a name="35"><b class="cmd">::term::ansi::send::sda_fgcyan</b></a></dt>
<dd><p>Set text color to <em>Cyan</em>.</p></dd>
<dt><a name="36"><b class="cmd">::term::ansi::send::sda_fgwhite</b></a></dt>
<dd><p>Set text color to <em>White</em>.</p></dd>
<dt><a name="37"><b class="cmd">::term::ansi::send::sda_fgdefault</b></a></dt>
<dd><p>Set default text color (<em>Black</em>).</p></dd>
<dt><a name="38"><b class="cmd">::term::ansi::send::sda_bgblack</b></a></dt>
<dd><p>Set background to <em>Black</em>.</p></dd>
<dt><a name="39"><b class="cmd">::term::ansi::send::sda_bgred</b></a></dt>
<dd><p>Set background to <em>Red</em>.</p></dd>
<dt><a name="40"><b class="cmd">::term::ansi::send::sda_bggreen</b></a></dt>
<dd><p>Set background to <em>Green</em>.</p></dd>
<dt><a name="41"><b class="cmd">::term::ansi::send::sda_bgyellow</b></a></dt>
<dd><p>Set background to <em>Yellow</em>.</p></dd>
<dt><a name="42"><b class="cmd">::term::ansi::send::sda_bgblue</b></a></dt>
<dd><p>Set background to <em>Blue</em>.</p></dd>
<dt><a name="43"><b class="cmd">::term::ansi::send::sda_bgmagenta</b></a></dt>
<dd><p>Set background to <em>Magenta</em>.</p></dd>
<dt><a name="44"><b class="cmd">::term::ansi::send::sda_bgcyan</b></a></dt>
<dd><p>Set background to <em>Cyan</em>.</p></dd>
<dt><a name="45"><b class="cmd">::term::ansi::send::sda_bgwhite</b></a></dt>
<dd><p>Set background to <em>White</em>.</p></dd>
<dt><a name="46"><b class="cmd">::term::ansi::send::sda_bgdefault</b></a></dt>
<dd><p>Set default background (Transparent).</p></dd>
<dt><a name="47"><b class="cmd">::term::ansi::send::sda_bold</b></a></dt>
<dd><p>Bold on.</p></dd>
<dt><a name="48"><b class="cmd">::term::ansi::send::sda_dim</b></a></dt>
<dd><p>Dim on.</p></dd>
<dt><a name="49"><b class="cmd">::term::ansi::send::sda_italic</b></a></dt>
<dd><p>Italics on.</p></dd>
<dt><a name="50"><b class="cmd">::term::ansi::send::sda_underline</b></a></dt>
<dd><p>Underscore on.</p></dd>
<dt><a name="51"><b class="cmd">::term::ansi::send::sda_blink</b></a></dt>
<dd><p>Blink on.</p></dd>
<dt><a name="52"><b class="cmd">::term::ansi::send::sda_revers</b></a></dt>
<dd><p>Reverse on.</p></dd>
<dt><a name="53"><b class="cmd">::term::ansi::send::sda_hidden</b></a></dt>
<dd><p>Hidden on.</p></dd>
<dt><a name="54"><b class="cmd">::term::ansi::send::sda_strike</b></a></dt>
<dd><p>Strike-through on.</p></dd>
<dt><a name="55"><b class="cmd">::term::ansi::send::sda_nobold</b></a></dt>
<dd><p>Bold off.</p></dd>
<dt><a name="56"><b class="cmd">::term::ansi::send::sda_noitalic</b></a></dt>
<dd><p>Italics off.</p></dd>
<dt><a name="57"><b class="cmd">::term::ansi::send::sda_nounderline</b></a></dt>
<dd><p>Underscore off.</p></dd>
<dt><a name="58"><b class="cmd">::term::ansi::send::sda_noblink</b></a></dt>
<dd><p>Blink off.</p></dd>
<dt><a name="59"><b class="cmd">::term::ansi::send::sda_norevers</b></a></dt>
<dd><p>Reverse off.</p></dd>
<dt><a name="60"><b class="cmd">::term::ansi::send::sda_nohidden</b></a></dt>
<dd><p>Hidden off.</p></dd>
<dt><a name="61"><b class="cmd">::term::ansi::send::sda_nostrike</b></a></dt>
<dd><p>Strike-through off.</p></dd>
<dt><a name="62"><b class="cmd">::term::ansi::send::sda_reset</b></a></dt>
<dd><p>Reset all attributes to their default values.</p></dd>
<dt><a name="63"><b class="cmd">::term::ansi::send::fcp</b> <i class="arg">row</i> <i class="arg">col</i></a></dt>
<dd><p>Force Cursor Position (aka Go To).</p></dd>
<dt><a name="64"><b class="cmd">::term::ansi::send::cu</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Up. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="65"><b class="cmd">::term::ansi::send::cd</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Down. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="66"><b class="cmd">::term::ansi::send::cf</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Forward. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="67"><b class="cmd">::term::ansi::send::cb</b> <span class="opt">?<i class="arg">n</i>?</span></a></dt>
<dd><p>Cursor Backward. <i class="arg">n</i> defaults to 1.</p></dd>
<dt><a name="68"><b class="cmd">::term::ansi::send::ss</b> <span class="opt">?<i class="arg">s</i> <i class="arg">e</i>?</span></a></dt>
<dd><p>Scroll Screen (entire display, or between rows start end, inclusive).</p></dd>
<dt><a name="69"><b class="cmd">::term::ansi::send::skd</b> <i class="arg">code</i> <i class="arg">str</i></a></dt>
<dd><p>Set Key Definition.</p></dd>
<dt><a name="70"><b class="cmd">::term::ansi::send::title</b> <i class="arg">str</i></a></dt>
<dd><p>Set the terminal title.</p></dd>
<dt><a name="71"><b class="cmd">::term::ansi::send::gron</b></a></dt>
<dd><p>Switch to character/box graphics. I.e. switch to the alternate font.</p></dd>
<dt><a name="72"><b class="cmd">::term::ansi::send::groff</b></a></dt>
<dd><p>Switch to regular characters. I.e. switch to the default font.</p></dd>
<dt><a name="73"><b class="cmd">::term::ansi::send::tlc</b></a></dt>
<dd><p>Character graphics, Top Left Corner.</p></dd>
<dt><a name="74"><b class="cmd">::term::ansi::send::trc</b></a></dt>
<dd><p>Character graphics, Top Right Corner.</p></dd>
<dt><a name="75"><b class="cmd">::term::ansi::send::brc</b></a></dt>
<dd><p>Character graphics, Bottom Right Corner.</p></dd>
<dt><a name="76"><b class="cmd">::term::ansi::send::blc</b></a></dt>
<dd><p>Character graphics, Bottom Left Corner.</p></dd>
<dt><a name="77"><b class="cmd">::term::ansi::send::ltj</b></a></dt>
<dd><p>Character graphics, Left T Junction.</p></dd>
<dt><a name="78"><b class="cmd">::term::ansi::send::ttj</b></a></dt>
<dd><p>Character graphics, Top T Junction.</p></dd>
<dt><a name="79"><b class="cmd">::term::ansi::send::rtj</b></a></dt>
<dd><p>Character graphics, Right T Junction.</p></dd>
<dt><a name="80"><b class="cmd">::term::ansi::send::btj</b></a></dt>
<dd><p>Character graphics, Bottom T Junction.</p></dd>
<dt><a name="81"><b class="cmd">::term::ansi::send::fwj</b></a></dt>
<dd><p>Character graphics, Four-Way Junction.</p></dd>
<dt><a name="82"><b class="cmd">::term::ansi::send::hl</b></a></dt>
<dd><p>Character graphics, Horizontal Line.</p></dd>
<dt><a name="83"><b class="cmd">::term::ansi::send::vl</b></a></dt>
<dd><p>Character graphics, Vertical Line.</p></dd>
<dt><a name="84"><b class="cmd">::term::ansi::send::groptim</b> <i class="arg">str</i></a></dt>
<dd><p>Optimize character graphics. The generator commands above create way to many
superfluous commands shifting into and out of the graphics mode. This command
removes all shifts which are not needed. To this end it also knows which
characters will look the same in both modes, to handle strings created outside
of this package.</p></dd>
<dt><a name="85"><b class="cmd">::term::ansi::send::clear</b></a></dt>
<dd><p>Clear screen. In essence a sequence of CursorHome + EraseDown.</p></dd>
<dt><a name="86"><b class="cmd">::term::ansi::send::init</b></a></dt>
<dd><p>Initialize default and alternate fonts to ASCII and box graphics.</p></dd>
<dt><a name="87"><b class="cmd">::term::ansi::send::showat</b> <i class="arg">row</i> <i class="arg">col</i> <i class="arg">text</i></a></dt>
<dd><p>Show the block of text at the specified location.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#character_output">character output</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/imenu.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
<div class='fossil-doc' data-title='term::interact::menu - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::interact::menu(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::interact::menu - Terminal widget, menu</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Object API</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">Interaction</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::interact::menu <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">term::interact::menu</b> <i class="arg">object</i> <i class="arg">dict</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">object</i> <b class="method">interact</b></a></li>
<li><a href="#3"><i class="arg">object</i> <b class="method">done</b></a></li>
<li><a href="#4"><i class="arg">object</i> <b class="method">clear</b></a></li>
<li><a href="#5"><i class="arg">object</i> <b class="method">configure</b></a></li>
<li><a href="#6"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#7"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#8"><i class="arg">object</i> <b class="method">cget</b> <i class="arg">option</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the creation of a simple menu
control.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<p>The package exports a single command, the class command, enabling the
creation of menu instances. Its API is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">term::interact::menu</b> <i class="arg">object</i> <i class="arg">dict</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new menu object with the name <i class="arg">object</i>,
initializes it, and returns the fully qualified name of the object
command as its result.</p>
<p>The argument is the menu to show, possibly followed by configuration
options and their values. The options are explained in the section
<span class="sectref"><a href="#section4">Configuration</a></span>. The menu is a dictionary maping labels
to symbolic action codes.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Object API</a></h2>
<p>The objects created by the class command provide the methods listed
below:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">object</i> <b class="method">interact</b></a></dt>
<dd><p>Shows the menu in the screen at the configured location and starts
interacting with it. This opens its own event loop for the processing
of incoming characters. The method returns when the interaction has
completed. See section <span class="sectref"><a href="#section5">Interaction</a></span> for a description of the
possible interaction.</p>
<p>The method returns the symbolic action of the menu item selected by
the user at the end of the interaction.</p></dd>
<dt><a name="3"><i class="arg">object</i> <b class="method">done</b></a></dt>
<dd><p>This method can be used by user supplied actions to terminate the
interaction with the object.</p></dd>
<dt><a name="4"><i class="arg">object</i> <b class="method">clear</b></a></dt>
<dd><p>This method can be used by user supplied actions to remove the menu
from the terminal.</p></dd>
<dt><a name="5"><i class="arg">object</i> <b class="method">configure</b></a></dt>
<dd></dd>
<dt><a name="6"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd></dd>
<dt><a name="7"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd></dd>
<dt><a name="8"><i class="arg">object</i> <b class="method">cget</b> <i class="arg">option</i></a></dt>
<dd><p>Standard methods to retrieve and configure the options of the menu.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>A menu instance recognizes the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-in</b> chan</dt>
<dd><p>Specifies the channel to read character sequences from. Defaults to
<b class="const">stdin</b>.</p></dd>
<dt><b class="option">-out</b> chan</dt>
<dd><p>Specifies the channel to write the menu contents to. Defaults to
<b class="const">stdout</b>.</p></dd>
<dt><b class="option">-column</b> int</dt>
<dd><p>Specifies the column of the terminal where the left margin of the
menu display should appear. Defaults to 0, i.e. the left-most
column.</p></dd>
<dt><b class="option">-line</b> int</dt>
<dd><p>Specifies the line of the terminal where the top margin of the menu
display should appear. Defaults to 0, i.e. the top-most line.</p></dd>
<dt><b class="option">-height</b> int</dt>
<dd><p>Specifies the number of lines of text to show at most in the
display. Defaults to 25.</p></dd>
<dt><b class="option">-actions</b> dict</dt>
<dd><p>Specifies a dictionary containing additional actions, using character
sequences as keys. Note that these sequences cannot override the
hardwired sequences described in section <span class="sectref"><a href="#section5">Interaction</a></span>.</p></dd>
<dt><b class="option">-hilitleft</b> int</dt>
<dd></dd>
<dt><b class="option">-hilitright</b> int</dt>
<dd><p>By default the entire selected menu entry is highlighted in revers
output. However, when present these two options restrict revers dispay
to the specified sub-range of the entry.</p></dd>
<dt><b class="option">-framed</b> bool</dt>
<dd><p>By default the menu is shown using only header and footer out of
characters box graphics. If this flag is set the menu is fully
enclosed in a box.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Interaction</a></h2>
<p>A menu object recognizes the control sequences listed below and acts
as described. The user can supply more control sequences to act on via
the configuration, but is not able to overide these defaults.</p>
<dl class="doctools_definitions">
<dt>Cursor Up</dt>
<dd><p>The selection is moved up one entry, except if the first entry of the
menu is already selected.</p></dd>
<dt>Cursor Down</dt>
<dd><p>The selection is moved down one entry, except if the last entry of the
menu is already selected.</p></dd>
<dt>Enter/Return</dt>
<dd><p>The interaction with the object is terminated.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#menu">menu</a>, <a href="../../../../index.html#terminal">terminal</a>, <a href="../../../../index.html#text_display">text display</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/ipager.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
<div class='fossil-doc' data-title='term::interact::pager - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::interact::pager(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::interact::pager - Terminal widget, paging</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Object API</a></li>
<li class="doctools_section"><a href="#section4">Configuration</a></li>
<li class="doctools_section"><a href="#section5">Interaction</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::interact::pager <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">term::interact::pager</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">object</i> <b class="method">interact</b></a></li>
<li><a href="#3"><i class="arg">object</i> <b class="method">done</b></a></li>
<li><a href="#4"><i class="arg">object</i> <b class="method">clear</b></a></li>
<li><a href="#5"><i class="arg">object</i> <b class="method">text</b> <i class="arg">text</i></a></li>
<li><a href="#6"><i class="arg">object</i> <b class="method">configure</b></a></li>
<li><a href="#7"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i></a></li>
<li><a href="#8"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></li>
<li><a href="#9"><i class="arg">object</i> <b class="method">cget</b> <i class="arg">option</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the creation of a simple paging
text display.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<p>The package exports a single command, the class command, enabling the
creation of pager instances. Its API is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">term::interact::pager</b> <i class="arg">object</i> <i class="arg">text</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new pager object with the name <i class="arg">object</i>,
initializes it, and returns the fully qualified name of the object
command as its result.</p>
<p>The argument is the text to show, possibly followed by configuration
options and their values. The options are explained in the section
<span class="sectref"><a href="#section4">Configuration</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Object API</a></h2>
<p>The objects created by the class command provide the methods listed
below:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">object</i> <b class="method">interact</b></a></dt>
<dd><p>Show the pager in the screen at the configured location and start
interacting with it. This opens its own event loop for the processing
of incoming characters. The method returns when the interaction has
completed. See section <span class="sectref"><a href="#section5">Interaction</a></span> for a description of the
possible interaction.</p></dd>
<dt><a name="3"><i class="arg">object</i> <b class="method">done</b></a></dt>
<dd><p>This method can be used by user supplied actions to terminate the
interaction with the object.</p></dd>
<dt><a name="4"><i class="arg">object</i> <b class="method">clear</b></a></dt>
<dd><p>This method can be used by user supplied actions to remove the pager
from the terminal.</p></dd>
<dt><a name="5"><i class="arg">object</i> <b class="method">text</b> <i class="arg">text</i></a></dt>
<dd><p>This method can be used to change the text shown by the pager.
The pager will reset the dispay to show the first line of the
text at the top.</p></dd>
<dt><a name="6"><i class="arg">object</i> <b class="method">configure</b></a></dt>
<dd></dd>
<dt><a name="7"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i></a></dt>
<dd></dd>
<dt><a name="8"><i class="arg">object</i> <b class="method">configure</b> <i class="arg">option</i> <i class="arg">value</i>...</a></dt>
<dd></dd>
<dt><a name="9"><i class="arg">object</i> <b class="method">cget</b> <i class="arg">option</i></a></dt>
<dd><p>Standard methods to retrieve and configure the options of the pager.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Configuration</a></h2>
<p>A pager instance recognizes the following options:</p>
<dl class="doctools_options">
<dt><b class="option">-in</b> chan</dt>
<dd><p>Specifies the channel to read character sequences from. Defaults to
<b class="const">stdin</b>.</p></dd>
<dt><b class="option">-out</b> chan</dt>
<dd><p>Specifies the channel to write the pager contents to. Defaults to
<b class="const">stdout</b>.</p></dd>
<dt><b class="option">-column</b> int</dt>
<dd><p>Specifies the column of the terminal where the left margin of the
pager display should appear. Defaults to 0, i.e. the left-most
column.</p></dd>
<dt><b class="option">-line</b> int</dt>
<dd><p>Specifies the line of the terminal where the top margin of the pager
display should appear. Defaults to 0, i.e. the top-most line.</p></dd>
<dt><b class="option">-height</b> int</dt>
<dd><p>Specifies the number of lines of text to show at most in the
display. Defaults to 25.</p></dd>
<dt><b class="option">-actions</b> dict</dt>
<dd><p>Specifies a dictionary containing additional actions, using character
sequences as keys. Note that these sequences cannot override the
hardwired sequences described in section <span class="sectref"><a href="#section5">Interaction</a></span>.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Interaction</a></h2>
<p>A pager object recognizes the control sequences listed below and acts
as described. The user can supply more control sequences to act on via
the configuration, but is not able to overide these defaults.</p>
<dl class="doctools_definitions">
<dt>Cursor Up</dt>
<dd><p>The text is scrolled down a single line, making one more line visible
at the top. The pager will not react if the first line of the text is
already shown.</p></dd>
<dt>Cursor Down</dt>
<dd><p>The text is scrolled up a single line, making one more line visible at
the bottom. The pager will not react if the last line of the text is
already shown.</p></dd>
<dt>Page Up</dt>
<dd><p>The text is scrolled down a page. The pager will not react if the
first line of the text is already shown.</p></dd>
<dt>Page Down</dt>
<dd><p>The text is scrolled up a page. The pager will not react if the last
line of the text is already shown.</p></dd>
<dt>Enter/Return</dt>
<dd><p>The interaction with the object is terminated.</p></dd>
</dl>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#pager">pager</a>, <a href="../../../../index.html#terminal">terminal</a>, <a href="../../../../index.html#text_display">text display</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/receive.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
<div class='fossil-doc' data-title='term::receive - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::receive(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::receive - General input from terminals</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::receive <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::receive::getch</b> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::term::receive::listen</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
<li><a href="#3"><i class="arg">cmd</i> <b class="method">process</b> <i class="arg">string</i></a></li>
<li><a href="#4"><i class="arg">cmd</i> <b class="method">eof</b></a></li>
<li><a href="#5"><b class="cmd">::term::receive::unlisten</b> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the most primitive commands for receiving
characters to a terminal. They are in essence convenient wrappers
around the builtin commands <b class="cmd"><a href="../../../../index.html#read">read</a></b> and <b class="cmd">fileevent</b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::receive::getch</b> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>This command reads a single character from the channel with handle
<i class="arg">chan</i> and returns it as the result of the command.</p>
<p>If not specified <i class="arg">chan</i> defaults to <b class="const">stdin</b>.</p>
<p>It is the responsibility of the caller to make sure that the channel
can provide single characters. On unix this can be done, for example,
by using the command of package <b class="package"><a href="ansi_ctrlu.html">term::ansi::ctrl::unix</a></b>.</p></dd>
<dt><a name="2"><b class="cmd">::term::receive::listen</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>This command sets up a filevent listener for the channel with handle
<i class="arg">chan</i> and invokes the command prefix <i class="arg">cmd</i> whenever
characters have been received, or EOF was reached.</p>
<p>If not specified <i class="arg">chan</i> defaults to <b class="const">stdin</b>.</p>
<p>The signature of the command prefix is</p>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">cmd</i> <b class="method">process</b> <i class="arg">string</i></a></dt>
<dd><p>This method is invoked when characters were received, and <i class="arg">string</i>
holds them for processing.</p></dd>
<dt><a name="4"><i class="arg">cmd</i> <b class="method">eof</b></a></dt>
<dd><p>This method is invoked when EOF was reached on the channel we listen
on. It will be the last call to be received by the callback.</p></dd>
</dl></dd>
<dt><a name="5"><b class="cmd">::term::receive::unlisten</b> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>This command disables the filevent listener for the channel with handle
<i class="arg">chan</i>.</p>
<p>If not specified <i class="arg">chan</i> defaults to <b class="const">stdin</b>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#character_input">character input</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#get_character">get character</a>, <a href="../../../../index.html#listener">listener</a>, <a href="../../../../index.html#receiver">receiver</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/term.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
<div class='fossil-doc' data-title='term - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term - General terminal control</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term <span class="opt">?0.1?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>It is planned to have this package provide highlevel general terminal control
commands, in the vein of ncurses or similar packages. Currently nothing has
been implemented however. I.e. this package is empty. It can be loaded, yet
provides nothing.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/term_bind.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
<div class='fossil-doc' data-title='term::receive::bind - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::receive::bind(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::receive::bind - Keyboard dispatch from terminals</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Object API</a></li>
<li class="doctools_section"><a href="#section4">Notes</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::receive::bind <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">term::receive::bind</b> <i class="arg">object</i> <span class="opt">?<i class="arg">map</i>?</span></a></li>
<li><a href="#2"><i class="arg">object</i> <b class="method">map</b> <i class="arg">str</i> <i class="arg">cmd</i></a></li>
<li><a href="#3"><i class="arg">object</i> <b class="method">default</b> <i class="arg">cmd</i></a></li>
<li><a href="#4"><i class="arg">object</i> <b class="method">listen</b> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
<li><a href="#5"><i class="arg">object</i> <b class="method">unlisten</b> <span class="opt">?<i class="arg">chan</i>?</span></a></li>
<li><a href="#6"><i class="arg">object</i> <b class="method">reset</b></a></li>
<li><a href="#7"><i class="arg">object</i> <b class="method">next</b> <i class="arg">char</i></a></li>
<li><a href="#8"><i class="arg">object</i> <b class="method">process</b> <i class="arg">str</i></a></li>
<li><a href="#9"><i class="arg">object</i> <b class="method">eof</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the creation of simple dispatchers
from character sequences to actions. Internally each dispatcher is in
essence a deterministic finite automaton with tree structure.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<p>The package exports a single command, the
class command, enabling the creation of
dispatcher instances. Its API
is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">term::receive::bind</b> <i class="arg">object</i> <span class="opt">?<i class="arg">map</i>?</span></a></dt>
<dd><p>This command creates a new dispatcher object with the name
<i class="arg">object</i>, initializes it, and returns the fully qualified name of
the object command as its result.</p>
<p>The argument is a dictionary mapping from strings, i.e. character
sequences to the command prefices to invoke when the sequence is found
in the input stream.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Object API</a></h2>
<p>The objects created by the class command provide the methods listed
below:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">object</i> <b class="method">map</b> <i class="arg">str</i> <i class="arg">cmd</i></a></dt>
<dd><p>This method adds an additional mapping from the string <i class="arg">str</i> to
the action <i class="arg">cmd</i>. The mapping will take effect immediately
should the processor be in a prefix of <i class="arg">str</i>, or at the next
reset operation. The action is a command prefix and will be invoked
with one argument appended to it, the character sequence causing
the invokation. It is executed in the global namespace.</p></dd>
<dt><a name="3"><i class="arg">object</i> <b class="method">default</b> <i class="arg">cmd</i></a></dt>
<dd><p>This method defines a default action <i class="arg">cmd</i> which will be invoked
whenever an unknown character sequence is encountered. The command
prefix is handled in the same as the regular action defined via
method <b class="method">map</b>.</p></dd>
<dt><a name="4"><i class="arg">object</i> <b class="method">listen</b> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>This methods sets up a filevent listener for the channel with handle
<i class="arg">chan</i> and invokes the dispatcher object whenever characters have
been received, or EOF was reached.</p>
<p>If not specified <i class="arg">chan</i> defaults to <b class="const">stdin</b>.</p></dd>
<dt><a name="5"><i class="arg">object</i> <b class="method">unlisten</b> <span class="opt">?<i class="arg">chan</i>?</span></a></dt>
<dd><p>This methods removes the filevent listener for the channel with handle
<i class="arg">chan</i>.</p>
<p>If not specified <i class="arg">chan</i> defaults to <b class="const">stdin</b>.</p></dd>
<dt><a name="6"><i class="arg">object</i> <b class="method">reset</b></a></dt>
<dd><p>This method resets the character processor
to the beginning of the tree.</p></dd>
<dt><a name="7"><i class="arg">object</i> <b class="method">next</b> <i class="arg">char</i></a></dt>
<dd><p>This method causes the character processor to process the character
<i class="arg">c</i>. This may simply advance the internal state, or invoke an
associated action for a recognized sequence.</p></dd>
<dt><a name="8"><i class="arg">object</i> <b class="method">process</b> <i class="arg">str</i></a></dt>
<dd><p>This method causes the character processor to process the character
sequence <i class="arg">str</i>, advancing the internal state and invoking action
as necessary. This is a callback for <b class="method">listen</b>.</p></dd>
<dt><a name="9"><i class="arg">object</i> <b class="method">eof</b></a></dt>
<dd><p>This method causes the character processor to handle EOF on the
input. This is currently no-op.
This is a callback for <b class="method">listen</b>.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Notes</a></h2>
<p>The simplicity of the DFA means that it is not possible to recognize a
character sequence with has a another recognized character sequence as
its prefix.</p>
<p>In other words, the set of recognized strings has to form a
<i class="term">prefix code</i>.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#character_input">character input</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#dispatcher">dispatcher</a>, <a href="../../../../index.html#listener">listener</a>, <a href="../../../../index.html#receiver">receiver</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/term/term_send.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<div class='fossil-doc' data-title='term::send - Terminal control'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">term::send(n) 0.1 tcllib "Terminal control"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>term::send - General output to terminals</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">term::send <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::term::send::wrch</b> <i class="arg">chan</i> <i class="arg">str</i></a></li>
<li><a href="#2"><b class="cmd">::term::send::wr</b> <i class="arg">str</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides the most primitive commands for sending characters
to a terminal. They are in essence convenient wrappers around the
builtin command <b class="cmd">puts</b>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::term::send::wrch</b> <i class="arg">chan</i> <i class="arg">str</i></a></dt>
<dd><p>Send the text <i class="arg">str</i> to the channel specified by the handle <i class="arg">chan</i>.
In contrast to the builtin command <b class="cmd">puts</b> this command does not
terminate the string with a line terminator. It also forces an flush of
Tcl internal and OS buffers to ensure that the characters are processed
immediately.</p></dd>
<dt><a name="2"><b class="cmd">::term::send::wr</b> <i class="arg">str</i></a></dt>
<dd><p>This convenience command is like <b class="cmd">::term::send::wrch</b>, except that the
destination channel is fixed to <em>stdout</em>.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>term</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#character_output">character output</a>, <a href="../../../../index.html#control">control</a>, <a href="../../../../index.html#terminal">terminal</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Terminal control</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/adjust.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
|
<div class='fossil-doc' data-title='textutil::adjust - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::adjust(n) 0.7.3 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::adjust - Procedures to adjust, indent, and undent paragraphs</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::adjust <span class="opt">?0.7.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::adjust::adjust</b> <i class="arg">string</i> <span class="opt">?<i class="arg">option value...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::textutil::adjust::readPatterns</b> <i class="arg">filename</i></a></li>
<li><a href="#3"><b class="cmd">::textutil::adjust::listPredefined</b></a></li>
<li><a href="#4"><b class="cmd">::textutil::adjust::getPredefined</b> <i class="arg">filename</i></a></li>
<li><a href="#5"><b class="cmd">::textutil::adjust::indent</b> <i class="arg">string</i> <i class="arg">prefix</i> <span class="opt">?<i class="arg">skip</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::textutil::adjust::undent</b> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil::adjust</b> provides commands that manipulate
strings or texts (a.k.a. long strings or string with embedded newlines
or paragraphs), adjusting, or indenting them.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::adjust::adjust</b> <i class="arg">string</i> <span class="opt">?<i class="arg">option value...</i>?</span></a></dt>
<dd><p>Do a justification on the <i class="arg">string</i> according to the options. The
string is taken as one big paragraph, ignoring any newlines. Then the
line is formatted according to the options used, and the command
returns a new string with enough lines to contain all the printable
chars in the input string. A line is a set of characters between the
beginning of the string and a newline, or between 2 newlines, or
between a newline and the end of the string. If the input string is
small enough, the returned string won't contain any newlines.</p>
<p>Together with <b class="cmd">::textutil::adjust::indent</b> it is possible to
create properly wrapped paragraphs with arbitrary indentations.</p>
<p>By default, any occurrence of space or tabulation characters are
replaced by a single space so that each word in a line is separated
from the next one by exactly one space character, and this forms a
<em>real</em> line.
Each <em>real</em> line is placed in a <em>logical</em> line, which has
exactly a given length (see the option <b class="option">-length</b> below).
The <em>real</em> line may be shorter. Again by default, trailing spaces
are ignored before returning the string (see the option <b class="option">-full</b>
below).</p>
<p>The following options may be used after the <i class="arg">string</i> parameter,
and change the way the command places a <em>real</em> line in a
<em>logical</em> line.</p>
<dl class="doctools_options">
<dt><b class="option">-full</b> <i class="arg">boolean</i></dt>
<dd><p>If set to <b class="const">false</b> (default), trailing space characters are
deleted before returning the string. If set to <b class="const">true</b>, any
trailing space characters are left in the string.</p></dd>
<dt><b class="option">-hyphenate</b> <i class="arg">boolean</i></dt>
<dd><p>If set to <b class="const">false</b> (default), no hyphenation will be done. If set
to <b class="const">true</b>, the command will try to hyphenate the last word of a
line. <em>Note</em>: Hyphenation patterns must be loaded prior, using
the command <b class="cmd">::textutil::adjust::readPatterns</b>.</p></dd>
<dt><b class="option">-justify</b> <b class="const">center|left|plain|right</b></dt>
<dd><p>Sets the justification of the returned string to either <b class="const">left</b>
(default), <b class="const">center</b>, <b class="const">plain</b> or <b class="const">right</b>. The
justification means that any line in the returned string but the last
one is build according to the value.
If the justification is set to <b class="const">plain</b> and the number of
printable chars in the last line is less than 90% of the length of a
line (see the option <b class="option">-length</b>), then this line is justified
with the <b class="const">left</b> value, avoiding the expansion of this line when
it is too small. The meaning of each value is:</p>
<dl class="doctools_definitions">
<dt><b class="const">center</b></dt>
<dd><p>The real line is centered in the logical line. If needed, a set of
space characters are added at the beginning (half of the needed set)
and at the end (half of the needed set) of the line if required (see
the option <b class="option">-full</b>).</p></dd>
<dt><b class="const">left</b></dt>
<dd><p>The real line is set on the left of the logical line. It means that
there are no space chars at the beginning of this line. If required,
all needed space chars are added at the end of the line (see the
option <b class="option">-full</b>).</p></dd>
<dt><b class="const">plain</b></dt>
<dd><p>The real line is exactly set in the logical line. It means that there
are no leading or trailing space chars. All the needed space chars are
added in the <em>real</em> line, between 2 (or more) words.</p></dd>
<dt><b class="const">right</b></dt>
<dd><p>The real line is set on the right of the logical line. It means that
there are no space chars at the end of this line, and there may be
some space chars at the beginning, despite of the <b class="option">-full</b> option.</p></dd>
</dl></dd>
<dt><b class="option">-length</b> <i class="arg">integer</i></dt>
<dd><p>Set the length of the <em>logical</em> line in the string to
<i class="arg">integer</i>. <i class="arg">integer</i> must be a positive integer
value. Defaults to <b class="const">72</b>.</p></dd>
<dt><b class="option">-strictlength</b> <i class="arg">boolean</i></dt>
<dd><p>If set to <b class="const">false</b> (default), a line can exceed the specified
<b class="option">-length</b> if a single word is longer than <b class="option">-length</b>. If
set to <b class="const">true</b>, words that are longer than <b class="option">-length</b> are
split so that no line exceeds the specified <b class="option">-length</b>.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::textutil::adjust::readPatterns</b> <i class="arg">filename</i></a></dt>
<dd><p>Loads the internal storage for hyphenation patterns with the contents
of the file <i class="arg">filename</i>. This has to be done prior to calling
command <b class="cmd">::textutil::adjust::adjust</b> with "<b class="option">-hyphenate</b>
<b class="const">true</b>", or the hyphenation process will not work correctly.</p>
<p>The package comes with a number of predefined pattern files, and the
command <b class="cmd">::textutil::adjust::listPredefined</b> can be used to find
out their names.</p></dd>
<dt><a name="3"><b class="cmd">::textutil::adjust::listPredefined</b></a></dt>
<dd><p>This command returns a list containing the names of the hyphenation
files coming with this package.</p></dd>
<dt><a name="4"><b class="cmd">::textutil::adjust::getPredefined</b> <i class="arg">filename</i></a></dt>
<dd><p>Use this command to query the package for the full path name of the
hyphenation file <i class="arg">filename</i> coming with the package. Only the
filenames found in the list returned by
<b class="cmd">::textutil::adjust::listPredefined</b> are legal arguments for this
command.</p></dd>
<dt><a name="5"><b class="cmd">::textutil::adjust::indent</b> <i class="arg">string</i> <i class="arg">prefix</i> <span class="opt">?<i class="arg">skip</i>?</span></a></dt>
<dd><p>Each line in the <i class="arg">string</i> is indented by adding the string
<i class="arg">prefix</i> at its beginning. The modified string is returned
as the result of the command.</p>
<p>If <i class="arg">skip</i> is specified the first <i class="arg">skip</i> lines are left
untouched. The default for <i class="arg">skip</i> is <b class="const">0</b>, causing the
modification of all lines. Negative values for <i class="arg">skip</i> are treated
like <b class="const">0</b>. In other words, <i class="arg">skip</i> > <b class="const">0</b> creates a
hanging indentation.</p>
<p>Together with <b class="cmd">::textutil::adjust::adjust</b> it is possible to
create properly wrapped paragraphs with arbitrary indentations.</p></dd>
<dt><a name="6"><b class="cmd">::textutil::adjust::undent</b> <i class="arg">string</i></a></dt>
<dd><p>The command computes the common prefix for all lines in <i class="arg">string</i>
consisting solely out of whitespace, removes this from each line and
returns the modified string.</p>
<p>Lines containing only whitespace are always reduced to completely
empty lines. They and empty lines are also ignored when computing the
prefix to remove.</p>
<p>Together with <b class="cmd">::textutil::adjust::adjust</b> it is possible to
create properly wrapped paragraphs with arbitrary indentations.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tex">TeX</a>, <a href="../../../../index.html#adjusting">adjusting</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#hyphenation">hyphenation</a>, <a href="../../../../index.html#indenting">indenting</a>, <a href="../../../../index.html#justification">justification</a>, <a href="../../../../index.html#paragraph">paragraph</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#undenting">undenting</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/expander.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
|
<div class='fossil-doc' data-title='textutil::expander - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::expander(n) 1.3.1 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::expander - Procedures to process templates and expand text.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXPANDER API</a></li>
<li class="doctools_section"><a href="#section3">TUTORIAL</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Basics</a></li>
<li class="doctools_subsection"><a href="#subsection2">Embedding Macros</a></li>
<li class="doctools_subsection"><a href="#subsection3">Writing Macro Commands</a></li>
<li class="doctools_subsection"><a href="#subsection4">Changing the Expansion Brackets</a></li>
<li class="doctools_subsection"><a href="#subsection5">Customized Macro Expansion</a></li>
<li class="doctools_subsection"><a href="#subsection6">Using the Context Stack</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">HISTORY</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::expander <span class="opt">?1.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::expander</b> <i class="arg">expanderName</i></a></li>
<li><a href="#2"><i class="arg">expanderName</i> <b class="method">cappend</b> <i class="arg">text</i></a></li>
<li><a href="#3"><i class="arg">expanderName</i> <b class="method">cget</b> <i class="arg">varname</i></a></li>
<li><a href="#4"><i class="arg">expanderName</i> <b class="method">cis</b> <i class="arg">cname</i></a></li>
<li><a href="#5"><i class="arg">expanderName</i> <b class="method">cname</b></a></li>
<li><a href="#6"><i class="arg">expanderName</i> <b class="method">cpop</b> <i class="arg">cname</i></a></li>
<li><a href="#7"><i class="arg">expanderName</i> <b class="method">ctopandclear</b></a></li>
<li><a href="#8"><i class="arg">expanderName</i> <b class="method">cpush</b> <i class="arg">cname</i></a></li>
<li><a href="#9"><i class="arg">expanderName</i> <b class="method">cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></li>
<li><a href="#10"><i class="arg">expanderName</i> <b class="method">cvar</b> <i class="arg">varname</i></a></li>
<li><a href="#11"><i class="arg">expanderName</i> <b class="method">errmode</b> <i class="arg">newErrmode</i></a></li>
<li><a href="#12"><i class="arg">expanderName</i> <b class="method">evalcmd</b> <span class="opt">?<i class="arg">newEvalCmd</i>?</span></a></li>
<li><a href="#13"><i class="arg">expanderName</i> <b class="method">expand</b> <i class="arg">string</i> <span class="opt">?<i class="arg">brackets</i>?</span></a></li>
<li><a href="#14"><i class="arg">expanderName</i> <b class="method">lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#15"><i class="arg">expanderName</i> <b class="method">rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></li>
<li><a href="#16"><i class="arg">expanderName</i> <b class="method">reset</b></a></li>
<li><a href="#17"><i class="arg">expanderName</i> <b class="method">setbrackets</b> <i class="arg">lbrack rbrack</i></a></li>
<li><a href="#18"><i class="arg">expanderName</i> <b class="method">textcmd</b> <span class="opt">?<i class="arg">newTextCmd</i>?</span></a></li>
<li><a href="#19"><i class="arg">expanderName</i> <b class="method">where</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The Tcl <b class="cmd"><a href="../../../../index.html#subst">subst</a></b> command is often used to support a kind of
template processing. Given a string with embedded variables or
function calls, <b class="cmd"><a href="../../../../index.html#subst">subst</a></b> will interpolate the variable and function
values, returning the new string:</p>
<pre class="doctools_example">
% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% subst {$greeting, [place]!}
Howdy, World!
%
</pre>
<p>By defining a suitable set of Tcl commands, <b class="cmd"><a href="../../../../index.html#subst">subst</a></b> can be used to
implement a markup language similar to HTML.</p>
<p>The <b class="cmd"><a href="../../../../index.html#subst">subst</a></b> command is efficient, but it has three drawbacks for
this kind of template processing:</p>
<ul class="doctools_itemized">
<li><p>There's no way to identify and process the plain text between two
embedded Tcl commands; that makes it difficult to handle plain text in
a context-sensitive way.</p></li>
<li><p>Embedded commands are necessarily bracketed by <b class="const">[</b> and
<b class="const">]</b>; it's convenient to be able to choose different brackets
in special cases. Someone producing web pages that include a large
quantity of Tcl code examples might easily prefer to use <b class="const"><<</b>
and <b class="const">>></b> as the embedded code delimiters instead.</p></li>
<li><p>There's no easy way to handle incremental input, as one might wish to
do when reading data from a socket.</p></li>
</ul>
<p>At present, expander solves the first two problems; eventually it will
solve the third problem as well.</p>
<p>The following section describes the command API to the expander; this
is followed by the tutorial sections, see <span class="sectref"><a href="#section3">TUTORIAL</a></span>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXPANDER API</a></h2>
<p>The <b class="package">textutil::expander</b> package provides only one command,
described below. The rest of the section is taken by a description of
the methods for the expander objects created by this command.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::expander</b> <i class="arg">expanderName</i></a></dt>
<dd><p>The command creates a new expander object with an associated Tcl
command whose name is <i class="arg">expanderName</i>. This command may be used to
invoke various operations on the graph. If the <i class="arg">expanderName</i> is
not fully qualified it is interpreted as relative to the current
namespace. The command has the following general form:</p>
<pre class="doctools_example">
<i class="arg">expanderName</i> option <span class="opt">?<i class="arg">arg arg ...</i>?</span>
</pre>
<p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl>
<p>The following commands are possible for expander objects:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">expanderName</i> <b class="method">cappend</b> <i class="arg">text</i></a></dt>
<dd><p>Appends a string to the output in the current context. This command
should rarely be used by macros or application code.</p></dd>
<dt><a name="3"><i class="arg">expanderName</i> <b class="method">cget</b> <i class="arg">varname</i></a></dt>
<dd><p>Retrieves the value of variable <i class="arg">varname</i>, defined in the current
context.</p></dd>
<dt><a name="4"><i class="arg">expanderName</i> <b class="method">cis</b> <i class="arg">cname</i></a></dt>
<dd><p>Determines whether or not the name of the current context is
<i class="arg">cname</i>.</p></dd>
<dt><a name="5"><i class="arg">expanderName</i> <b class="method">cname</b></a></dt>
<dd><p>Returns the name of the current context.</p></dd>
<dt><a name="6"><i class="arg">expanderName</i> <b class="method">cpop</b> <i class="arg">cname</i></a></dt>
<dd><p>Pops a context from the context stack, returning all accumulated
output in that context. The context must be named <i class="arg">cname</i>, or an
error results.</p></dd>
<dt><a name="7"><i class="arg">expanderName</i> <b class="method">ctopandclear</b></a></dt>
<dd><p>Returns the output currently captured in the topmost context and
clears that buffer. This is similar to a combination of <b class="method">cpop</b>
followed by <b class="method">cpush</b>, except that internal state (brackets) is
preserved here.</p></dd>
<dt><a name="8"><i class="arg">expanderName</i> <b class="method">cpush</b> <i class="arg">cname</i></a></dt>
<dd><p>Pushes a context named <i class="arg">cname</i> onto the context stack. The
context must be popped by <b class="method">cpop</b> before expansion ends or an
error results.</p></dd>
<dt><a name="9"><i class="arg">expanderName</i> <b class="method">cset</b> <i class="arg">varname</i> <i class="arg">value</i></a></dt>
<dd><p>Sets variable <i class="arg">varname</i> to <i class="arg">value</i> in the current context.</p></dd>
<dt><a name="10"><i class="arg">expanderName</i> <b class="method">cvar</b> <i class="arg">varname</i></a></dt>
<dd><p>Retrieves the internal variable name of context variable
<i class="arg">varname</i>; this allows the variable to be passed to commands like
<b class="cmd">lappend</b>.</p></dd>
<dt><a name="11"><i class="arg">expanderName</i> <b class="method">errmode</b> <i class="arg">newErrmode</i></a></dt>
<dd><p>Sets the macro expansion error mode to one of <b class="const">nothing</b>,
<b class="const">macro</b>, <b class="const">error</b>, or <b class="const">fail</b>; the default value is
<b class="const">fail</b>. The value determines what the expander does if an
error is detected during expansion of a macro.</p>
<dl class="doctools_definitions">
<dt><b class="const">fail</b></dt>
<dd><p>The error propagates normally and can be caught or ignored by the
application.</p></dd>
<dt><b class="const">error</b></dt>
<dd><p>The macro expands into a detailed error message, and expansion
continues.</p></dd>
<dt><b class="const">macro</b></dt>
<dd><p>The macro expands to itself; that is, it is passed along to the output
unchanged.</p></dd>
<dt><b class="const">nothing</b></dt>
<dd><p>The macro expands to the empty string, and is effectively ignored.</p></dd>
</dl></dd>
<dt><a name="12"><i class="arg">expanderName</i> <b class="method">evalcmd</b> <span class="opt">?<i class="arg">newEvalCmd</i>?</span></a></dt>
<dd><p>Returns the current evaluation command, which defaults to
<b class="cmd">uplevel #0</b>. If specified, <i class="arg">newEvalCmd</i> will be saved for
future use and then returned; it must be a Tcl command expecting one
additional argument: the macro to evaluate.</p></dd>
<dt><a name="13"><i class="arg">expanderName</i> <b class="method">expand</b> <i class="arg">string</i> <span class="opt">?<i class="arg">brackets</i>?</span></a></dt>
<dd><p>Expands the input string, replacing embedded macros with their
expanded values, and returns the expanded string.</p>
<p>Note that this method pushes a new (empty) context on the stack of
contexts while it is running, and removes it on return.</p>
<p>If <i class="arg">brackets</i> is given, it must be a list of two strings; the
items will be used as the left and right macro expansion bracket
sequences for this expansion only.</p></dd>
<dt><a name="14"><i class="arg">expanderName</i> <b class="method">lb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the left macro expansion bracket; this is
for use as or within a macro, when the bracket needs to be included in
the output text. If <i class="arg">newbracket</i> is specified, it becomes the new
bracket, and is returned.</p></dd>
<dt><a name="15"><i class="arg">expanderName</i> <b class="method">rb</b> <span class="opt">?<i class="arg">newbracket</i>?</span></a></dt>
<dd><p>Returns the current value of the right macro expansion bracket; this
is for use as or within a macro, when the bracket needs to be included
in the output text. If <i class="arg">newbracket</i> is specified, it becomes the
new bracket, and is returned.</p></dd>
<dt><a name="16"><i class="arg">expanderName</i> <b class="method">reset</b></a></dt>
<dd><p>Resets all expander settings to their initial values. Unusual results
are likely if this command is called from within a call to
<b class="method">expand</b>.</p></dd>
<dt><a name="17"><i class="arg">expanderName</i> <b class="method">setbrackets</b> <i class="arg">lbrack rbrack</i></a></dt>
<dd><p>Sets the left and right macro expansion brackets. This command is for
use as or within a macro, or to permanently change the bracket
definitions. By default, the brackets are <b class="const">[</b> and
<b class="const">]</b>, but any non-empty string can be used; for example,
<b class="const"><</b> and <b class="const">></b> or <b class="const">(*</b> and <b class="const">*)</b> or even
<b class="const">Hello,</b> and <b class="const">World!</b>.</p></dd>
<dt><a name="18"><i class="arg">expanderName</i> <b class="method">textcmd</b> <span class="opt">?<i class="arg">newTextCmd</i>?</span></a></dt>
<dd><p>Returns the current command for processing plain text, which defaults
to the empty string, meaning <em>identity</em>. If specified,
<i class="arg">newTextCmd</i> will be saved for future use and then returned; it
must be a Tcl command expecting one additional argument: the text to
process. The expander object will this command for all plain text it
encounters, giving the user of the object the ability to process all
plain text in some standard way before writing it to the output. The
object expects that the command returns the processed plain text.</p>
<p><em>Note</em> that the combination of "<b class="cmd">textcmd</b> <i class="arg">plaintext</i>"
is run through the <i class="arg">evalcmd</i> for the actual evaluation. In other
words, the <i class="arg">textcmd</i> is treated as a special macro implicitly
surrounding all plain text in the template.</p></dd>
<dt><a name="19"><i class="arg">expanderName</i> <b class="method">where</b></a></dt>
<dd><p>Returns a three-element list containing the current character
position, line, and column the expander is at in the processing of the
current input string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TUTORIAL</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Basics</a></h3>
<p>To begin, create an expander object:</p>
<pre class="doctools_example">
% package require textutil::expander
1.2
% ::textutil::expander myexp
::myexp
%
</pre>
<p>The created <b class="cmd">::myexp</b> object can be used to expand text strings
containing embedded Tcl commands. By default, embedded commands are
delimited by square brackets. Note that expander doesn't attempt to
interpolate variables, since variables can be referenced by embedded
commands:</p>
<pre class="doctools_example">
% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% ::myexp expand {[set greeting], [place]!}
Howdy, World!
%
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Embedding Macros</a></h3>
<p>An expander macro is simply a Tcl script embedded within a text
string. Expander evaluates the script in the global context, and
replaces it with its result string. For example,</p>
<pre class="doctools_example">
% set greetings {Howdy Hi "What's up"}
Howdy Hi "What's up"
% ::myexp expand {There are many ways to say "Hello, World!":
[set result {}
foreach greeting $greetings {
append result "$greeting, World!\\n"
}
set result]
And that's just a small sample!}
There are many ways to say "Hello, World!":
Howdy, World!
Hi, World!
What's up, World!
And that's just a small sample!
%
</pre>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Writing Macro Commands</a></h3>
<p>More typically, <em>macro commands</em> are used to create a markup
language. A macro command is just a Tcl command that returns an
output string. For example, expand can be used to implement a generic
document markup language that can be retargeted to HTML or any other
output format:</p>
<pre class="doctools_example">
% proc bold {} {return "<b>"}
% proc /bold {} {return "</b>"}
% ::myexp expand {Some of this text is in [bold]boldface[/bold]}
Some of this text is in <b>boldface</b>
%
</pre>
<p>The above definitions of <b class="cmd">bold</b> and <b class="cmd">/bold</b> returns HTML, but
such commands can be as complicated as needed; they could, for
example, decide what to return based on the desired output format.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Changing the Expansion Brackets</a></h3>
<p>By default, embedded macros are enclosed in square brackets,
<b class="const">[</b> and <b class="const">]</b>. If square brackets need to be
included in the output, the input can contain the <b class="cmd">lb</b> and
<b class="cmd">rb</b> commands. Alternatively, or if square brackets are
objectionable for some other reason, the macro expansion brackets can
be changed to any pair of non-empty strings.</p>
<p>The <b class="method">setbrackets</b> command changes the brackets permanently.
For example, you can write pseudo-html by change them to <b class="const"><</b>
and <b class="const">></b>:</p>
<pre class="doctools_example">
% ::myexp setbrackets < >
% ::myexp expand {<bold>This is boldface</bold>}
<b>This is boldface</b>
</pre>
<p>Alternatively, you can change the expansion brackets temporarily by
passing the desired brackets to the <b class="method">expand</b> command:</p>
<pre class="doctools_example">
% ::myexp setbrackets "\\[" "\\]"
% ::myexp expand {<bold>This is boldface</bold>} {< >}
<b>This is boldface</b>
%
</pre>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Customized Macro Expansion</a></h3>
<p>By default, macros are evaluated using the Tcl <b class="cmd">uplevel #0</b>
command, so that the embedded code executes in the global context.
The application can provide a different evaluation command using
<b class="method">evalcmd</b>; this allows the application to use a safe
interpreter, for example, or even to evaluated something other than
Tcl code. There is one caveat: to be recognized as valid, a macro
must return 1 when passed to Tcl's "info complete" command.</p>
<p>For example, the following code "evaluates" each macro by returning
the macro text itself.</p>
<pre class="doctools_example">
proc identity {macro} {return $macro}
::myexp evalcmd identity
</pre>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Using the Context Stack</a></h3>
<p>Often it's desirable to define a pair of macros which operate in some
way on the plain text between them. Consider a set of macros for
adding footnotes to a web page: one could have implement something
like this:</p>
<pre class="doctools_example">
Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote "See Candide, by Voltaire"]
</pre>
<p>The <b class="cmd">footnote</b> macro would, presumably, assign a number to this
footnote and save the text to be formatted later on. However, this
solution is ugly if the footnote text is long or should contain
additional markup. Consider the following instead:</p>
<pre class="doctools_example">
Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote]See [bookTitle "Candide"], by
[authorsName "Voltaire"], for more information.[/footnote]
</pre>
<p>Here the footnote text is contained between <b class="cmd">footnote</b> and
<b class="cmd">/footnote</b> macros, continues onto a second line, and contains
several macros of its own. This is both clearer and more flexible;
however, with the features presented so far there's no easy way to do
it. That's the purpose of the context stack.</p>
<p>All macro expansion takes place in a particular context. Here, the
<b class="cmd">footnote</b> macro pushes a new context onto the context stack.
Then, all expanded text gets placed in that new context.
<b class="cmd">/footnote</b> retrieves it by popping the context. Here's a
skeleton implementation of these two macros:</p>
<pre class="doctools_example">
proc footnote {} {
::myexp cpush footnote
}
proc /footnote {} {
set footnoteText [::myexp cpop footnote]
# Save the footnote text, and return an appropriate footnote
# number and link.
}
</pre>
<p>The <b class="method">cpush</b> command pushes a new context onto the stack; the
argument is the context's name. It can be any string, but would
typically be the name of the macro itself. Then, <b class="method">cpop</b>
verifies that the current context has the expected name, pops it off
of the stack, and returns the accumulated text.</p>
<p>Expand provides several other tools related to the context stack.
Suppose the first macro in a context pair takes arguments or computes
values which the second macro in the pair needs. After calling
<b class="method">cpush</b>, the first macro can define one or more context
variables; the second macro can retrieve their values any time before
calling <b class="method">cpop</b>. For example, suppose the document must specify
the footnote number explicitly:</p>
<pre class="doctools_example">
proc footnote {footnoteNumber} {
::myexp cpush footnote
::myexp csave num $footnoteNumber
# Return an appropriate link
}
proc /footnote {} {
set footnoteNumber [::myexp cget num]
set footnoteText [::myexp cpop footnote]
# Save the footnote text and its footnoteNumber for future
# output.
}
</pre>
<p>At times, it might be desirable to define macros that are valid only
within a particular context pair; such macros should verify that they
are only called within the correct context using either <b class="method">cis</b>
or <b class="method">cname</b>.</p>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">HISTORY</a></h2>
<p><b class="cmd">expander</b> was written by William H. Duquette; it is a repackaging
of the central algorithm of the expand macro processing tool.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>[uri, http://www.wjduquette.com/expand, regexp, <a href="../../../../index.html#split">split</a>, <a href="../../../../index.html#string">string</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#template_processing">template processing</a>, <a href="../../../../index.html#text_expansion">text expansion</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © William H. Duquette, http://www.wjduquette.com/expand</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/repeat.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<div class='fossil-doc' data-title='textutil::repeat - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::repeat(n) 0.7.1 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::repeat - Procedures to repeat strings.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::repeat <span class="opt">?0.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::repeat::strRepeat</b> <i class="arg">text</i> <i class="arg">num</i></a></li>
<li><a href="#2"><b class="cmd">::textutil::repeat::blank</b> <i class="arg">num</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil::repeat</b> provides commands to generate
long strings by repeating a shorter string many times.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::repeat::strRepeat</b> <i class="arg">text</i> <i class="arg">num</i></a></dt>
<dd><p>This command returns a string containing the <i class="arg">text</i> repeated
<i class="arg">num</i> times. The repetitions are joined without characters between
them. A value of <i class="arg">num</i> <= 0 causes the command to return an empty
string.</p>
<p><em>Note</em>: If the Tcl core the package is loaded in provides the
command <b class="cmd">string repeat</b> then this command will be implemented in
its terms, for maximum possible speed. Otherwise a fast implementation
in Tcl will be used.</p></dd>
<dt><a name="2"><b class="cmd">::textutil::repeat::blank</b> <i class="arg">num</i></a></dt>
<dd><p>A convenience command. Returns a string of <i class="arg">num</i> spaces.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#blanks">blanks</a>, <a href="../../../../index.html#repetition">repetition</a>, <a href="../../../../index.html#string">string</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/tabify.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<div class='fossil-doc' data-title='textutil::tabify - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::tabify(n) 0.7 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::tabify - Procedures to (un)tabify strings</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::tabify <span class="opt">?0.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::tabify::tabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::textutil::tabify::tabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::textutil::tabify::untabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::textutil::tabify::untabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil::tabify</b> provides commands that convert
between tabulation and ordinary whitespace in strings.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::tabify::tabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Tabify the <i class="arg">string</i> by replacing any substring of <i class="arg">num</i> space
chars by a tabulation and return the result as a new string. <i class="arg">num</i>
defaults to 8.</p></dd>
<dt><a name="2"><b class="cmd">::textutil::tabify::tabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Similar to <b class="cmd">::textutil::tabify</b> this command tabifies the
<i class="arg">string</i> and returns the result as a new string. A different
algorithm is used however. Instead of replacing any substring of
<i class="arg">num</i> spaces this command works more like an editor. <i class="arg">num</i>
defaults to 8.</p>
<p>Each line of the text in <i class="arg">string</i> is treated as if there are
tabstops every <i class="arg">num</i> columns. Only sequences of space characters
containing more than one space character and found immediately before
a tabstop are replaced with tabs.</p></dd>
<dt><a name="3"><b class="cmd">::textutil::tabify::untabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Untabify the <i class="arg">string</i> by replacing any tabulation char by a
substring of <i class="arg">num</i> space chars and return the result as a new
string. <i class="arg">num</i> defaults to 8.</p></dd>
<dt><a name="4"><b class="cmd">::textutil::tabify::untabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Untabify the <i class="arg">string</i> by replacing any tabulation char by a
substring of at most <i class="arg">num</i> space chars and return the result as a
new string. Unlike <b class="cmd">textutil::tabify::untabify</b> each tab is not
replaced by a fixed number of space characters. The command overlays
each line in the <i class="arg">string</i> with tabstops every <i class="arg">num</i> columns
instead and replaces tabs with just enough space characters to reach
the next tabstop. This is the complement of the actions taken by
<b class="cmd">::textutil::tabify::tabify2</b>. <i class="arg">num</i> defaults to 8.</p>
<p>There is one asymmetry though: A tab can be replaced with a single
space, but not the other way around.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#tabstops">tabstops</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/textutil.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
<div class='fossil-doc' data-title='textutil - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil(n) 0.8 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil - Procedures to manipulate texts and strings.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil <span class="opt">?0.8?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::adjust</b> <i class="arg">string args</i></a></li>
<li><a href="#2"><b class="cmd">::textutil::adjust::readPatterns</b> <i class="arg">filename</i></a></li>
<li><a href="#3"><b class="cmd">::textutil::adjust::listPredefined</b></a></li>
<li><a href="#4"><b class="cmd">::textutil::adjust::getPredefined</b> <i class="arg">filename</i></a></li>
<li><a href="#5"><b class="cmd">::textutil::indent</b> <i class="arg">string</i> <i class="arg">prefix</i> <span class="opt">?<i class="arg">skip</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::textutil::undent</b> <i class="arg">string</i></a></li>
<li><a href="#7"><b class="cmd">::textutil::splitn</b> <i class="arg">string</i> <span class="opt">?<i class="arg">len</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::textutil::splitx</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#9"><b class="cmd">::textutil::tabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::textutil::tabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#11"><b class="cmd">::textutil::trim</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::textutil::trimleft</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#13"><b class="cmd">::textutil::trimright</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#14"><b class="cmd">::textutil::trimPrefix</b> <i class="arg">string</i> <i class="arg">prefix</i></a></li>
<li><a href="#15"><b class="cmd">::textutil::trimEmptyHeading</b> <i class="arg">string</i></a></li>
<li><a href="#16"><b class="cmd">::textutil::untabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#17"><b class="cmd">::textutil::untabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></li>
<li><a href="#18"><b class="cmd">::textutil::strRepeat</b> <i class="arg">text num</i></a></li>
<li><a href="#19"><b class="cmd">::textutil::blank</b> <i class="arg">num</i></a></li>
<li><a href="#20"><b class="cmd">::textutil::chop</b> <i class="arg">string</i></a></li>
<li><a href="#21"><b class="cmd">::textutil::tail</b> <i class="arg">string</i></a></li>
<li><a href="#22"><b class="cmd">::textutil::cap</b> <i class="arg">string</i></a></li>
<li><a href="#23"><b class="cmd">::textutil::uncap</b> <i class="arg">string</i></a></li>
<li><a href="#24"><b class="cmd">::textutil::longestCommonPrefixList</b> <i class="arg">list</i></a></li>
<li><a href="#25"><b class="cmd">::textutil::longestCommonPrefix</b> <span class="opt">?<i class="arg">string</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil</b> provides commands that manipulate
strings or texts (a.k.a. long strings or string with embedded newlines
or paragraphs).
It is actually a bundle providing the commands of the six packages</p>
<dl class="doctools_definitions">
<dt><b class="package"><a href="adjust.html">textutil::adjust</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="repeat.html">textutil::repeat</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="textutil_split.html">textutil::split</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="textutil_string.html">textutil::string</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="tabify.html">textutil::tabify</a></b></dt>
<dd></dd>
<dt><b class="package"><a href="trim.html">textutil::trim</a></b></dt>
<dd></dd>
</dl>
<p>in the namespace <b class="namespace">textutil</b>.</p>
<p>The bundle is <em>deprecated</em>, and it will be removed in a future
release of Tcllib, after the next release. It is recommended to use the
relevant sub packages instead for whatever functionality is needed by
the using package or application.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::adjust</b> <i class="arg">string args</i></a></dt>
<dd><p>Do a justification on the <i class="arg">string</i> according to <i class="arg">args</i>. The
string is taken as one big paragraph, ignoring any newlines. Then the
line is formatted according to the options used, and the command
return a new string with enough lines to contain all the printable
chars in the input string. A line is a set of chars between the
beginning of the string and a newline, or between 2 newlines, or
between a newline and the end of the string. If the input string is
small enough, the returned string won't contain any newlines.</p>
<p>Together with <b class="cmd">::textutil::indent</b> it is possible to create
properly wrapped paragraphs with arbitrary indentations.</p>
<p>By default, any occurrence of spaces characters or tabulation are
replaced by a single space so each word in a line is separated from
the next one by exactly one space char, and this forms a <em>real</em>
line. Each <em>real</em> line is placed in a <em>logical</em> line, which
have exactly a given length (see <b class="option">-length</b> option below). The
<em>real</em> line may have a lesser length. Again by default, any
trailing spaces are ignored before returning the string (see
<b class="option">-full</b> option below). The following options may be used after the
<i class="arg">string</i> parameter, and change the way the command place a
<em>real</em> line in a <em>logical</em> line.</p>
<dl class="doctools_definitions">
<dt>-full <i class="arg">boolean</i></dt>
<dd><p>If set to <b class="const">false</b>, any trailing space chars are deleted before
returning the string. If set to <b class="const">true</b>, any trailing space
chars are left in the string. Default to <b class="const">false</b>.</p></dd>
<dt><b class="option">-hyphenate</b> <i class="arg">boolean</i></dt>
<dd><p>if set to <b class="const">false</b>, no hyphenation will be done. If set to
<b class="const">true</b>, the last word of a line is tried to be hyphenated.
Defaults to <b class="const">false</b>. Note: hyphenation patterns must be loaded
prior, using the command <b class="cmd">::textutil::adjust::readPatterns</b>.</p></dd>
<dt><b class="option">-justify</b> <b class="const">center|left|plain|right</b></dt>
<dd><p>Set the justification of the returned string to <b class="const">center</b>,
<b class="const">left</b>, <b class="const">plain</b> or <b class="const">right</b>. By default, it is set to
<b class="const">left</b>. The justification means that any line in the returned
string but the last one is build according to the value. If the
justification is set to <b class="const">plain</b> and the number of printable
chars in the last line is less than 90% of the length of a line (see
<b class="option">-length</b>), then this line is justified with the <b class="const">left</b>
value, avoiding the expansion of this line when it is too small. The
meaning of each value is:</p>
<dl class="doctools_definitions">
<dt><b class="const">center</b></dt>
<dd><p>The real line is centered in the logical line. If needed, a set of
space characters are added at the beginning (half of the needed set)
and at the end (half of the needed set) of the line if required (see
the option <b class="option">-full</b>).</p></dd>
<dt><b class="const">left</b></dt>
<dd><p>The real line is set on the left of the logical line. It means that
there are no space chars at the beginning of this line. If required,
all needed space chars are added at the end of the line (see the
option <b class="option">-full</b>).</p></dd>
<dt><b class="const">plain</b></dt>
<dd><p>The real line is exactly set in the logical line. It means that there
are no leading or trailing space chars. All the needed space chars are
added in the <em>real</em> line, between 2 (or more) words.</p></dd>
<dt><b class="const">right</b></dt>
<dd><p>The real line is set on the right of the logical line. It means that
there are no space chars at the end of this line, and there may be
some space chars at the beginning, despite of the <b class="option">-full</b> option.</p></dd>
</dl></dd>
<dt><b class="option">-length</b> <i class="arg">integer</i></dt>
<dd><p>Set the length of the <em>logical</em> line in the string to
<i class="arg">integer</i>. <i class="arg">integer</i> must be a positive integer
value. Defaults to <b class="const">72</b>.</p></dd>
<dt><b class="option">-strictlength</b> <i class="arg">boolean</i></dt>
<dd><p>If set to <b class="const">false</b>, a line can exceed the specified
<b class="option">-length</b> if a single word is longer than <b class="option">-length</b>. If
set to <b class="const">true</b>, words that are longer than <b class="option">-length</b> are
split so that no line exceeds the specified <b class="option">-length</b>. Defaults
to <b class="const">false</b>.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::textutil::adjust::readPatterns</b> <i class="arg">filename</i></a></dt>
<dd><p>Loads the internal storage for hyphenation patterns with the contents
of the file <i class="arg">filename</i>. This has to be done prior to calling
command <b class="cmd">::textutil::adjust</b> with
"<b class="option">-hyphenate</b> <b class="const">true</b>", or the hyphenation process will
not work correctly.</p>
<p>The package comes with a number of predefined pattern files, and the
command <b class="cmd">::textutil::adjust::listPredefined</b> can be used to find
out their names.</p></dd>
<dt><a name="3"><b class="cmd">::textutil::adjust::listPredefined</b></a></dt>
<dd><p>This command returns a list containing the names of the hyphenation
files coming with this package.</p></dd>
<dt><a name="4"><b class="cmd">::textutil::adjust::getPredefined</b> <i class="arg">filename</i></a></dt>
<dd><p>Use this command to query the package for the full path name of the
hyphenation file <i class="arg">filename</i> coming with the package. Only the
filenames found in the list returned by
<b class="cmd">::textutil::adjust::listPredefined</b> are legal arguments for this
command.</p></dd>
<dt><a name="5"><b class="cmd">::textutil::indent</b> <i class="arg">string</i> <i class="arg">prefix</i> <span class="opt">?<i class="arg">skip</i>?</span></a></dt>
<dd><p>Each line in the <i class="arg">string</i> indented by adding the string
<i class="arg">prefix</i> at its beginning. The modified string is returned
as the result of the command.</p>
<p>If <i class="arg">skip</i> is specified the first <i class="arg">skip</i> lines are left
untouched. The default for <i class="arg">skip</i> is <b class="const">0</b>, causing the
modification of all lines. Negative values for <i class="arg">skip</i> are treated
like <b class="const">0</b>. In other words, <i class="arg">skip</i> > <b class="const">0</b> creates a
hanging indentation.</p>
<p>Together with <b class="cmd">::textutil::adjust</b> it is possible to create
properly wrapped paragraphs with arbitrary indentations.</p></dd>
<dt><a name="6"><b class="cmd">::textutil::undent</b> <i class="arg">string</i></a></dt>
<dd><p>The command computes the common prefix for all
lines in <i class="arg">string</i> consisting solely out of whitespace,
removes this from each line and returns the modified string.</p>
<p>Lines containing only whitespace are always reduced to completely
empty lines. They and empty lines are also ignored when computing the
prefix to remove.</p>
<p>Together with <b class="cmd">::textutil::adjust</b> it is possible to create
properly wrapped paragraphs with arbitrary indentations.</p></dd>
<dt><a name="7"><b class="cmd">::textutil::splitn</b> <i class="arg">string</i> <span class="opt">?<i class="arg">len</i>?</span></a></dt>
<dd><p>This command splits the given <i class="arg">string</i> into chunks of <i class="arg">len</i>
characters and returns a list containing these chunks. The argument
<i class="arg">len</i> defaults to <b class="const">1</b> if none is specified. A negative
length is not allowed and will cause the command to throw an
error. Providing an empty string as input is allowed, the command will
then return an empty list. If the length of the <i class="arg">string</i> is not an
entire multiple of the chunk length, then the last chunk in the
generated list will be shorter than <i class="arg">len</i>.</p></dd>
<dt><a name="8"><b class="cmd">::textutil::splitx</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Split the <i class="arg">string</i> and return a list. The string is split
according to the regular expression <i class="arg">regexp</i> instead of a simple
list of chars. Note that if you add parenthesis into the <i class="arg">regexp</i>,
the parentheses part of separator would be added into list as
additional element. If the <i class="arg">string</i> is empty the result is the
empty list, like for <b class="cmd"><a href="../../../../index.html#split">split</a></b>. If <i class="arg">regexp</i> is empty the
<i class="arg">string</i> is split at every character, like <b class="cmd"><a href="../../../../index.html#split">split</a></b> does.
The regular expression <i class="arg">regexp</i> defaults to "[\\t \\r\\n]+".</p></dd>
<dt><a name="9"><b class="cmd">::textutil::tabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Tabify the <i class="arg">string</i> by replacing any substring of <i class="arg">num</i> space
chars by a tabulation and return the result as a new string. <i class="arg">num</i>
defaults to 8.</p></dd>
<dt><a name="10"><b class="cmd">::textutil::tabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Similar to <b class="cmd">::textutil::tabify</b> this command tabifies the
<i class="arg">string</i> and returns the result as a new string. A different
algorithm is used however. Instead of replacing any substring of
<i class="arg">num</i> spaces this command works more like an editor. <i class="arg">num</i>
defaults to 8.</p>
<p>Each line of the text in <i class="arg">string</i> is treated as if there are
tabstops every <i class="arg">num</i> columns. Only sequences of space characters
containing more than one space character and found immediately before
a tabstop are replaced with tabs.</p></dd>
<dt><a name="11"><b class="cmd">::textutil::trim</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Remove in <i class="arg">string</i> any leading and trailing substring according to
the regular expression <i class="arg">regexp</i> and return the result as a new
string. This apply on any <em>line</em> in the string, that is any
substring between 2 newline chars, or between the beginning of the
string and a newline, or between a newline and the end of the string,
or, if the string contain no newline, between the beginning and the
end of the string.
The regular expression <i class="arg">regexp</i> defaults to "[ \\t]+".</p></dd>
<dt><a name="12"><b class="cmd">::textutil::trimleft</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Remove in <i class="arg">string</i> any leading substring according to the regular
expression <i class="arg">regexp</i> and return the result as a new string. This
apply on any <em>line</em> in the string, that is any substring between
2 newline chars, or between the beginning of the string and a newline,
or between a newline and the end of the string, or, if the string
contain no newline, between the beginning and the end of the string.
The regular expression <i class="arg">regexp</i> defaults to "[ \\t]+".</p></dd>
<dt><a name="13"><b class="cmd">::textutil::trimright</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Remove in <i class="arg">string</i> any trailing substring according to the regular
expression <i class="arg">regexp</i> and return the result as a new string. This
apply on any <em>line</em> in the string, that is any substring between
2 newline chars, or between the beginning of the string and a newline,
or between a newline and the end of the string, or, if the string
contain no newline, between the beginning and the end of the string.
The regular expression <i class="arg">regexp</i> defaults to "[ \\t]+".</p></dd>
<dt><a name="14"><b class="cmd">::textutil::trimPrefix</b> <i class="arg">string</i> <i class="arg">prefix</i></a></dt>
<dd><p>Removes the <i class="arg">prefix</i> from the beginning of <i class="arg">string</i> and
returns the result. The <i class="arg">string</i> is left unchanged if it doesn't
have <i class="arg">prefix</i> at its beginning.</p></dd>
<dt><a name="15"><b class="cmd">::textutil::trimEmptyHeading</b> <i class="arg">string</i></a></dt>
<dd><p>Looks for empty lines (including lines consisting of only whitespace)
at the beginning of the <i class="arg">string</i> and removes it. The modified
string is returned as the result of the command.</p></dd>
<dt><a name="16"><b class="cmd">::textutil::untabify</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Untabify the <i class="arg">string</i> by replacing any tabulation char by a
substring of <i class="arg">num</i> space chars and return the result as a new
string. <i class="arg">num</i> defaults to 8.</p></dd>
<dt><a name="17"><b class="cmd">::textutil::untabify2</b> <i class="arg">string</i> <span class="opt">?<i class="arg">num</i>?</span></a></dt>
<dd><p>Untabify the <i class="arg">string</i> by replacing any tabulation char by a
substring of at most <i class="arg">num</i> space chars and return the result as a
new string. Unlike <b class="cmd">textutil::untabify</b> each tab is not replaced
by a fixed number of space characters. The command overlays each line
in the <i class="arg">string</i> with tabstops every <i class="arg">num</i> columns instead and
replaces tabs with just enough space characters to reach the next
tabstop. This is the complement of the actions taken by
<b class="cmd">::textutil::tabify2</b>. <i class="arg">num</i> defaults to 8.</p>
<p>There is one asymmetry though: A tab can be replaced with a single
space, but not the other way around.</p></dd>
<dt><a name="18"><b class="cmd">::textutil::strRepeat</b> <i class="arg">text num</i></a></dt>
<dd><p>The implementation depends on the core executing the package. Used
<b class="cmd">string repeat</b> if it is present, or a fast tcl implementation
if it is not. Returns a string containing the <i class="arg">text</i> repeated
<i class="arg">num</i> times. The repetitions are joined without characters between
them. A value of <i class="arg">num</i> <= 0 causes the command to return an empty
string.</p></dd>
<dt><a name="19"><b class="cmd">::textutil::blank</b> <i class="arg">num</i></a></dt>
<dd><p>A convenience command. Returns a string of <i class="arg">num</i> spaces.</p></dd>
<dt><a name="20"><b class="cmd">::textutil::chop</b> <i class="arg">string</i></a></dt>
<dd><p>A convenience command. Removes the last character of <i class="arg">string</i> and
returns the shortened string.</p></dd>
<dt><a name="21"><b class="cmd">::textutil::tail</b> <i class="arg">string</i></a></dt>
<dd><p>A convenience command. Removes the first character of <i class="arg">string</i> and
returns the shortened string.</p></dd>
<dt><a name="22"><b class="cmd">::textutil::cap</b> <i class="arg">string</i></a></dt>
<dd><p>Capitalizes the first character of <i class="arg">string</i> and returns the modified string.</p></dd>
<dt><a name="23"><b class="cmd">::textutil::uncap</b> <i class="arg">string</i></a></dt>
<dd><p>The complementary operation to <b class="cmd">::textutil::cap</b>. Forces the first
character of <i class="arg">string</i> to lower case and returns the modified
string.</p></dd>
<dt><a name="24"><b class="cmd">::textutil::longestCommonPrefixList</b> <i class="arg">list</i></a></dt>
<dd></dd>
<dt><a name="25"><b class="cmd">::textutil::longestCommonPrefix</b> <span class="opt">?<i class="arg">string</i>...?</span></a></dt>
<dd><p>Computes the longest common prefix for either the <i class="arg">string</i>s given
to the command, or the strings specified in the single <i class="arg">list</i>, and
returns it as the result of the command.</p>
<p>If no strings were specified the result is the empty string. If only
one string was specified, the string itself is returned, as it is its
own longest common prefix.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tex">TeX</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#hyphenation">hyphenation</a>, <a href="../../../../index.html#indenting">indenting</a>, <a href="../../../../index.html#paragraph">paragraph</a>, <a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#trimming">trimming</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/textutil_split.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<div class='fossil-doc' data-title='textutil::split - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::split(n) 0.8 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::split - Procedures to split texts</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::split <span class="opt">?0.8?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::split::splitn</b> <i class="arg">string</i> <span class="opt">?<i class="arg">len</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::textutil::split::splitx</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil::split</b> provides commands that split
strings by size and arbitrary regular expressions.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::split::splitn</b> <i class="arg">string</i> <span class="opt">?<i class="arg">len</i>?</span></a></dt>
<dd><p>This command splits the given <i class="arg">string</i> into chunks of <i class="arg">len</i>
characters and returns a list containing these chunks. The argument
<i class="arg">len</i> defaults to <b class="const">1</b> if none is specified. A negative
length is not allowed and will cause the command to throw an
error. Providing an empty string as input is allowed, the command will
then return an empty list. If the length of the <i class="arg">string</i> is not an
entire multiple of the chunk length, then the last chunk in the
generated list will be shorter than <i class="arg">len</i>.</p></dd>
<dt><a name="2"><b class="cmd">::textutil::split::splitx</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>This command splits the <i class="arg">string</i> and return a list. The string is
split according to the regular expression <i class="arg">regexp</i> instead of a
simple list of chars.
<em>Note</em>: When parentheses are used in the <i class="arg">regexp</i>, i.e. regex
capture groups, then these groups will be added into the result list
as additional elements. If the <i class="arg">string</i> is empty the result is the
empty list, like for <b class="cmd"><a href="../../../../index.html#split">split</a></b>.
If <i class="arg">regexp</i> is empty the <i class="arg">string</i> is split at every character,
like <b class="cmd"><a href="../../../../index.html#split">split</a></b> does.
The regular expression <i class="arg">regexp</i> defaults to "[\\t \\r\\n]+".</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#split">split</a>, <a href="../../../../index.html#string">string</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/textutil_string.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<div class='fossil-doc' data-title='textutil::string - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::string(n) 0.8 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::string - Procedures to manipulate texts and strings.</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::string <span class="opt">?0.8?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::string::chop</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::textutil::string::tail</b> <i class="arg">string</i></a></li>
<li><a href="#3"><b class="cmd">::textutil::string::cap</b> <i class="arg">string</i></a></li>
<li><a href="#4"><b class="cmd">::textutil::string::capEachWord</b> <i class="arg">string</i></a></li>
<li><a href="#5"><b class="cmd">::textutil::string::uncap</b> <i class="arg">string</i></a></li>
<li><a href="#6"><b class="cmd">::textutil::string::longestCommonPrefixList</b> <i class="arg">list</i></a></li>
<li><a href="#7"><b class="cmd">::textutil::string::longestCommonPrefix</b> <span class="opt">?<i class="arg">string</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil::string</b> provides miscellaneous string
manipulation commands.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::string::chop</b> <i class="arg">string</i></a></dt>
<dd><p>A convenience command. Removes the last character of <i class="arg">string</i> and
returns the shortened string.</p></dd>
<dt><a name="2"><b class="cmd">::textutil::string::tail</b> <i class="arg">string</i></a></dt>
<dd><p>A convenience command. Removes the first character of <i class="arg">string</i> and
returns the shortened string.</p></dd>
<dt><a name="3"><b class="cmd">::textutil::string::cap</b> <i class="arg">string</i></a></dt>
<dd><p>Capitalizes the first character of <i class="arg">string</i> and returns the
modified string.</p></dd>
<dt><a name="4"><b class="cmd">::textutil::string::capEachWord</b> <i class="arg">string</i></a></dt>
<dd><p>Capitalizes the first character of word of the <i class="arg">string</i> and
returns the modified string. Words quoted with either backslash or
dollar-sign are left untouched.</p></dd>
<dt><a name="5"><b class="cmd">::textutil::string::uncap</b> <i class="arg">string</i></a></dt>
<dd><p>The complementary operation to <b class="cmd">::textutil::string::cap</b>. Forces
the first character of <i class="arg">string</i> to lower case and returns the
modified string.</p></dd>
<dt><a name="6"><b class="cmd">::textutil::string::longestCommonPrefixList</b> <i class="arg">list</i></a></dt>
<dd></dd>
<dt><a name="7"><b class="cmd">::textutil::string::longestCommonPrefix</b> <span class="opt">?<i class="arg">string</i>...?</span></a></dt>
<dd><p>Computes the longest common prefix for either the <i class="arg">string</i>s given
to the command, or the strings specified in the single <i class="arg">list</i>, and
returns it as the result of the command.</p>
<p>If no strings were specified the result is the empty string. If only
one string was specified, the string itself is returned, as it is its
own longest common prefix.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#capitalize">capitalize</a>, <a href="../../../../index.html#chop">chop</a>, <a href="../../../../index.html#common_prefix">common prefix</a>, <a href="../../../../index.html#formatting">formatting</a>, <a href="../../../../index.html#prefix">prefix</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#uncapitalize">uncapitalize</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/textutil/trim.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
<div class='fossil-doc' data-title='textutil::trim - Text and string utilities, macro processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">textutil::trim(n) 0.7 tcllib "Text and string utilities, macro processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>textutil::trim - Procedures to trim strings</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">textutil::trim <span class="opt">?0.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::textutil::trim::trim</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::textutil::trim::trimleft</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::textutil::trim::trimright</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::textutil::trim::trimPrefix</b> <i class="arg">string</i> <i class="arg">prefix</i></a></li>
<li><a href="#5"><b class="cmd">::textutil::trim::trimEmptyHeading</b> <i class="arg">string</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The package <b class="package">textutil::trim</b> provides commands that trim
strings using arbitrary regular expressions.</p>
<p>The complete set of procedures is described below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::textutil::trim::trim</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Remove in <i class="arg">string</i> any leading and trailing substring according to
the regular expression <i class="arg">regexp</i> and return the result as a new
string. This is done for all <em>lines</em> in the string, that is any
substring between 2 newline chars, or between the beginning of the
string and a newline, or between a newline and the end of the string,
or, if the string contain no newline, between the beginning and the
end of the string.
The regular expression <i class="arg">regexp</i> defaults to "[ \\t]+".</p></dd>
<dt><a name="2"><b class="cmd">::textutil::trim::trimleft</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Remove in <i class="arg">string</i> any leading substring according to the regular
expression <i class="arg">regexp</i> and return the result as a new string. This
apply on any <em>line</em> in the string, that is any substring between
2 newline chars, or between the beginning of the string and a newline,
or between a newline and the end of the string, or, if the string
contain no newline, between the beginning and the end of the string.
The regular expression <i class="arg">regexp</i> defaults to "[ \\t]+".</p></dd>
<dt><a name="3"><b class="cmd">::textutil::trim::trimright</b> <i class="arg">string</i> <span class="opt">?<i class="arg">regexp</i>?</span></a></dt>
<dd><p>Remove in <i class="arg">string</i> any trailing substring according to the regular
expression <i class="arg">regexp</i> and return the result as a new string. This
apply on any <em>line</em> in the string, that is any substring between
2 newline chars, or between the beginning of the string and a newline,
or between a newline and the end of the string, or, if the string
contain no newline, between the beginning and the end of the string.
The regular expression <i class="arg">regexp</i> defaults to "[ \\t]+".</p></dd>
<dt><a name="4"><b class="cmd">::textutil::trim::trimPrefix</b> <i class="arg">string</i> <i class="arg">prefix</i></a></dt>
<dd><p>Removes the <i class="arg">prefix</i> from the beginning of <i class="arg">string</i> and
returns the result. The <i class="arg">string</i> is left unchanged if it doesn't
have <i class="arg">prefix</i> at its beginning.</p></dd>
<dt><a name="5"><b class="cmd">::textutil::trim::trimEmptyHeading</b> <i class="arg">string</i></a></dt>
<dd><p>Looks for empty lines (including lines consisting of only whitespace)
at the beginning of the <i class="arg">string</i> and removes it. The modified
string is returned as the result of the command.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>textutil</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>regexp(n), split(n), string(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#prefix">prefix</a>, <a href="../../../../index.html#regular_expression">regular expression</a>, <a href="../../../../index.html#string">string</a>, <a href="../../../../index.html#trimming">trimming</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Text processing</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tie/tie.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
|
<div class='fossil-doc' data-title='tie - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tie(n) 1.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tie - Array persistence</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">USING TIES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">TIE API</a></li>
<li class="doctools_subsection"><a href="#subsection2">STANDARD DATA SOURCE TYPES</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">CREATING NEW DATA SOURCES</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">DATA SOURCE OBJECTS</a></li>
<li class="doctools_subsection"><a href="#subsection4">REGISTERING A NEW DATA SOURCE CLASS</a></li>
<li class="doctools_subsection"><a href="#subsection5">DATA SOURCE CLASS</a></li>
<li class="doctools_subsection"><a href="#subsection6">DATA SOURCE OBJECT API</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">tie <span class="opt">?1.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tie::tie</b> <i class="arg">arrayvarname</i> <i class="arg">options</i>... <i class="arg">dstype</i> <i class="arg">dsname</i>...</a></li>
<li><a href="#2"><b class="cmd">::tie::untie</b> <i class="arg">arrayvarname</i> <span class="opt">?<i class="arg">token</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::tie::info</b> <b class="method">ties</b> <i class="arg">arrayvarname</i></a></li>
<li><a href="#4"><b class="cmd">::tie::info</b> <b class="method">types</b></a></li>
<li><a href="#5"><b class="cmd">::tie::info</b> <b class="method">type</b> <i class="arg">dstype</i></a></li>
<li><a href="#6"><b class="cmd">::tie::register</b> <i class="arg">dsclasscmd</i> <b class="const">as</b> <i class="arg">dstype</i></a></li>
<li><a href="#7"><b class="cmd">dsclasscmd</b> <i class="arg">objname</i> <span class="opt">?<i class="arg">dsname</i>...?</span></a></li>
<li><a href="#8"><b class="cmd">ds</b> <b class="method">destroy</b></a></li>
<li><a href="#9"><b class="cmd">ds</b> <b class="method">names</b></a></li>
<li><a href="#10"><b class="cmd">ds</b> <b class="method">size</b></a></li>
<li><a href="#11"><b class="cmd">ds</b> <b class="method">get</b></a></li>
<li><a href="#12"><b class="cmd">ds</b> <b class="method">set</b> <i class="arg">dict</i></a></li>
<li><a href="#13"><b class="cmd">ds</b> <b class="method">unset</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></li>
<li><a href="#14"><b class="cmd">ds</b> <b class="method">setv</b> <i class="arg">index</i> <i class="arg">value</i></a></li>
<li><a href="#15"><b class="cmd">ds</b> <b class="method">unsetv</b> <i class="arg">index</i></a></li>
<li><a href="#16"><b class="cmd">ds</b> <b class="method">getv</b> <i class="arg">index</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tie</b> package provides a framework for the creation of
persistent Tcl array variables. It should be noted that the provided
mechanism is generic enough to also allow its usage for the
distribution of the contents of Tcl arrays over multiple threads and
processes, i.e. communication.</p>
<p>This, persistence and communication, is accomplished by <i class="term">tying</i>)
a Tcl array variable to a <i class="term"><a href="../../../../index.html#data_source">data source</a></i>. Examples of data
sources are other Tcl arrays and files.</p>
<p>It should be noted that a single Tcl array variable can be tied to
more than one <i class="term"><a href="../../../../index.html#data_source">data source</a></i>. It is this feature which allows
the framework to be used for communication as well. Just tie several
Tcl arrays in many client processes to a Tcl array in a server and all
changes to any of them will be distributed to all. Less centralized
variants of this are of course possible as well.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">USING TIES</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">TIE API</a></h3>
<p>This section describes the basic API used to establish and remove ties
between Tcl array variables and data sources. This interface is the
only one a casual user has to be concerned about. The following
sections about the various internal interfaces can be safely skipped.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tie::tie</b> <i class="arg">arrayvarname</i> <i class="arg">options</i>... <i class="arg">dstype</i> <i class="arg">dsname</i>...</a></dt>
<dd><p>This command establishes a tie between the Tcl array whose name is
provided by the argument <i class="arg">arrayvarname</i> and the
<i class="term"><a href="../../../../index.html#data_source">data source</a></i> identified by the <i class="arg">dstype</i> and its series of
<i class="arg">dsname</i> arguments. All changes made to the Tcl array after this
command returns will be saved to the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> for
safekeeping (or distribution).</p>
<p>The result of the command is always a token which identifies the new
tie. This token can be used later to destroy this specific tie.</p>
<dl class="doctools_arguments">
<dt>varname <i class="arg">arrayvarname</i> (in)</dt>
<dd><p>The name of the Tcl array variable to connect the new tie to.</p></dd>
<dt>name|command <i class="arg">dstype</i> (in)</dt>
<dd><p>This argument specifies the type of the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> we wish
to access.
The <i class="arg">dstype</i> can be one of <b class="const">log</b>, <b class="const">array</b>,
<b class="const">remotearray</b>, <b class="const">file</b>, <b class="const">growfile</b>, or
<b class="const">dsource</b>; in addition, the programmer can register additional
data source types.
Each <i class="arg">dstype</i> is followed by one or more arguments that identify
the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> to which the array is to be tied.</p></dd>
<dt>string <i class="arg">dsname</i> (in)</dt>
<dd><p>The series of <i class="arg">dsname</i> arguments coming after the <i class="arg">dstype</i>
identifies the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> we wish to connect to, and has to
be appropriate for the chosen type.</p></dd>
</dl>
<p>The command understands a number of additional options which guide the
process of setting up the connection between Tcl array and
<i class="term"><a href="../../../../index.html#data_source">data source</a></i>.</p>
<dl class="doctools_options">
<dt><b class="option">-open</b></dt>
<dd><p>The Tcl array for the new tie is <i class="term">loaded</i> from the
<i class="term"><a href="../../../../index.html#data_source">data source</a></i>, and the previously existing contents of the Tcl
array are erased. Care is taken to <em>not</em> erase the previous
contents should the creation of the tie fail.</p>
<p>This option and the option <b class="option">-save</b> exclude each other. If
neither this nor option <b class="option">-save</b> are specified then this option
is assumed as default.</p></dd>
<dt><b class="option">-save</b></dt>
<dd><p>The Tcl array for the new tie is <i class="term">saved</i> to the
<i class="term"><a href="../../../../index.html#data_source">data source</a></i>, and the previously existing contents of the
<i class="term"><a href="../../../../index.html#data_source">data source</a></i> are erased.</p>
<p>This option and the option <b class="option">-open</b> exclude each other. If
neither this nor option <b class="option">-open</b> are specified then option
<b class="option">-open</b> is assumed as default.</p></dd>
<dt><b class="option">-merge</b></dt>
<dd><p>Using this option prevents the erasure of any previously existing
content and merges the data instead. It can be specified in
conjunction with either <b class="option">-open</b> or <b class="option">-save</b>. They
determine how data existing in both Tcl array and
<i class="term"><a href="../../../../index.html#data_source">data source</a></i>, i.e duplicates, are dealt with.</p>
<p>When used with <b class="option">-open</b> data in the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> has
precedence.
In other words, for duplicates the data in the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> is
loaded into the Tcl array.</p>
<p>When used with <b class="option">-save</b> data in the Tcl array has precedence. In
other words, for duplicates the data in the Tcl array is saved into
the <i class="term"><a href="../../../../index.html#data_source">data source</a></i>.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::tie::untie</b> <i class="arg">arrayvarname</i> <span class="opt">?<i class="arg">token</i>?</span></a></dt>
<dd><p>This command dissolves one or more ties associated with the Tcl array
named by <i class="arg">arrayvarname</i>. If no <i class="arg">token</i> is specified then all
ties to that Tcl array are dissolved. Otherwise only the tie the token
stands for is removed, if it is actually connected to the
array. Trying to remove a specific tie not belonging to the provided
array will cause an error.</p>
<p>It should be noted that while severing a tie will destroy management
information internal to the package the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> which was
handled by the tie will not be touched, only closed.</p>
<p>After the command returns none of changes made to the array will be
saved to the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> anymore.</p>
<p>The result of the command is an empty string.</p>
<dl class="doctools_arguments">
<dt>varname <i class="arg">arrayname</i> (in)</dt>
<dd><p>The name of a Tcl array variable which may have ties.</p></dd>
<dt>handle <i class="arg">token</i> (in)</dt>
<dd><p>A handle representing a specific tie. This argument is optional.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::tie::info</b> <b class="method">ties</b> <i class="arg">arrayvarname</i></a></dt>
<dd><p>This command returns a list of ties associated with the Tcl array
variable named by <i class="arg">arrayvarname</i>. The result list will be empty if
the variable has no ties associated with it.</p></dd>
<dt><a name="4"><b class="cmd">::tie::info</b> <b class="method">types</b></a></dt>
<dd><p>This command returns a dictionary of registered types, and the class
commands they are associated with.</p></dd>
<dt><a name="5"><b class="cmd">::tie::info</b> <b class="method">type</b> <i class="arg">dstype</i></a></dt>
<dd><p>This command returns the fully resolved class command for a type
name. This means that the command will follow a chain of type
definitions ot its end.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">STANDARD DATA SOURCE TYPES</a></h3>
<p>This package provides the six following types as examples and standard
data sources.</p>
<dl class="doctools_definitions">
<dt><b class="const">log</b></dt>
<dd><p>This <i class="term"><a href="../../../../index.html#data_source">data source</a></i> does not maintain any actual data, nor
persistence. It does not accept any identifying arguments. All changes
are simply logged to <b class="const">stdout</b>.</p></dd>
<dt><b class="const">array</b></dt>
<dd><p>This <i class="term"><a href="../../../../index.html#data_source">data source</a></i> uses a regular Tcl array as the origin of
the persistent data. It accepts a single identifying argument, the
name of this Tcl array. All changes are mirrored to that array.</p></dd>
<dt><b class="const">remotearray</b></dt>
<dd><p>This <i class="term"><a href="../../../../index.html#data_source">data source</a></i> is similar to <b class="const">array</b>. The difference
is that the Tcl array to which we are mirroring is not directly
accessible, but through a <b class="cmd"><a href="../../../../index.html#send">send</a></b>-like command.</p>
<p>It accepts three identifying arguments, the name of the other Tcl
array, the command prefix for the <b class="cmd"><a href="../../../../index.html#send">send</a></b>-like accessor command,
and an identifier for the remote entity hosting the array, in this
order. All changes are mirrored to that array, via the command
prefix. All commands will be executed in the context of the global
namespace.</p>
<p><b class="cmd"><a href="../../../../index.html#send">send</a></b>-like means that the command prefix has to have <b class="cmd"><a href="../../../../index.html#send">send</a></b>
syntax and semantics. I.e. it is a channel over which we can send
arbitrary commands to some other entity.
The remote array <i class="term"><a href="../../../../index.html#data_source">data source</a></i> however uses only the commands
<b class="cmd"><a href="../../../../index.html#set">set</a></b>, <b class="cmd">unset</b>, <b class="cmd">array exists</b>, <b class="cmd">array names</b>, <b class="cmd">array set</b>, and
<b class="cmd">array get</b> to retrieve and set values in the remote array.</p>
<p>The command prefix and the entity id are separate to allow the data
source to use options like <b class="option">-async</b> when assembling the actual
commands.</p>
<p>Examples of command prefixes, listed with the id of the remote entity,
without options. In reality only the part before the id is the command
prefix:</p>
<dl class="doctools_definitions">
<dt><b class="cmd"><a href="../../../../index.html#send">send</a></b> <i class="arg">tkname</i></dt>
<dd><p>The Tcl array is in a remote interpreter and is accessed via Tk's X
communication.</p></dd>
<dt><b class="cmd">comm::comm send</b> <i class="arg">hostportid</i></dt>
<dd><p>The Tcl array is in a remote interpreter and is accessed through a
socket.</p></dd>
<dt><b class="cmd">thread::send</b> <i class="arg">threadid</i></dt>
<dd><p>The Tcl array is in a remote interpreter in a different thread of this
process.</p></dd>
</dl></dd>
<dt><b class="const">file</b></dt>
<dd><p>This <i class="term"><a href="../../../../index.html#data_source">data source</a></i> uses a single file as origin of the
persistent data. It accepts a single identifying argument, the path to
this file. The file has to be both readable and writable. It may not
exist, the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> will create it in that case. This (and
only this) situation will require that the directory for the file
exists and is writable as well.</p>
<p>All changes are saved in the file, as proper Tcl commands, one command
per operation. In other words, the file will always contain a proper
Tcl script.</p>
<p>If the file exists when the tie using it is set up, then it will be
compacted, i.e. superfluous operations are removed, if the operations
log stored in it contains either at least one operation clearing the
whole array, or at least 1.5 times more operations than entries in the
loaded array.</p></dd>
<dt><b class="const">growfile</b></dt>
<dd><p>This <i class="term"><a href="../../../../index.html#data_source">data source</a></i> is like <b class="const">file</b> in terms of the storage
medium for the array data, and how it is configured. In constrast to
the former it however assumes and ensures that the tied array will
never shrink. I.e. the creation of new array entries, and the
modification of existing entries is allowed, but the deletion of
entries is not, and causes the data source to throw errors.</p>
<p>This restriction allows us to simplify both file format and access to
the file radically. For one, the file is read only once and the
internal cache cannot be invalidated. Second, writing data is reduced
to a simple append, and no compaction step is necessary. The format of
the contents is the string representation of a dictionary which can be
incrementally extended forever at the end.</p></dd>
<dt><b class="const">dsource</b></dt>
<dd><p>This <i class="term"><a href="../../../../index.html#data_source">data source</a></i> uses an explicitly specified
<i class="term">data source object</i> as the source for the persistent
data. It accepts a single identifying argument, the command prefix,
i.e. object command.</p>
<p>To use this type it is necessary to know how the framework manages
ties and what <span class="sectref"><a href="#subsection3">data source objects</a></span> are.</p>
<p>All changes are delegated to the specified object.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CREATING NEW DATA SOURCES</a></h2>
<p>This section is of no interest to the casual user of ties. Only
developers wishing to create new data sources have to know the
information provided herein.</p>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">DATA SOURCE OBJECTS</a></h3>
<p>All ties are represented internally by an in-memory object which
mediates between the tie framework and the specific
<i class="term"><a href="../../../../index.html#data_source">data source</a></i>, like an array, file, etc.
This is the <i class="term">data source object</i>.</p>
<p>Its class, the <span class="sectref"><a href="#subsection5">data source class</a></span> is <em>not</em> generic,
but specific to the type of the <i class="term"><a href="../../../../index.html#data_source">data source</a></i>. Writing a new
<i class="term"><a href="../../../../index.html#data_source">data source</a></i> requires us to write such a class, and then
registering it with the framework as a new type.</p>
<p>The following subsections describe the various APIs a
<span class="sectref"><a href="#subsection5">data source class</a></span> and the objects it generates will have
to follow to be compatible with the tie framework.</p>
<p>Data source objects are normally automatically created and destroyed
by the framework when a tie is created, or removed. This management
can be explicitly bypassed through the usage of the "dsource" type.
The <i class="term"><a href="../../../../index.html#data_source">data source</a></i> for this type is a
<i class="term">data source object</i> itself, and this object is outside of the
scope of the tie framework and not managed by it.
In other words, this type allows the creation of ties which talk to
pre-existing <i class="term">data source object</i>s, and these objects will
survive the removal of the ties using them as well.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">REGISTERING A NEW DATA SOURCE CLASS</a></h3>
<p>After a <span class="sectref"><a href="#subsection5">data source class</a></span> has been written it is necessary
to register it as a new type with the framework.</p>
<dl class="doctools_definitions">
<dt><a name="6"><b class="cmd">::tie::register</b> <i class="arg">dsclasscmd</i> <b class="const">as</b> <i class="arg">dstype</i></a></dt>
<dd><p>Using this command causes the tie framework to remember the class
command <i class="arg">dsclasscmd</i> of a <span class="sectref"><a href="#subsection5">data source class</a></span> under the
type name <i class="arg">dstype</i>.</p>
<p>After the call the argument <i class="arg">dstype</i> of the basic user command
<b class="cmd">::tie::tie</b> will accept <i class="arg">dstype</i> as a type name and translate
it internally to the appropriate class command for the creation of
<span class="sectref"><a href="#subsection3">data source objects</a></span> for the new <i class="term"><a href="../../../../index.html#data_source">data source</a></i>.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">DATA SOURCE CLASS</a></h3>
<p>Each data source class is represented by a single command, also called
the <i class="term">class command</i>, or <i class="term">object creation command</i>. Its
syntax is</p>
<dl class="doctools_definitions">
<dt><a name="7"><b class="cmd">dsclasscmd</b> <i class="arg">objname</i> <span class="opt">?<i class="arg">dsname</i>...?</span></a></dt>
<dd><p>The first argument of the class command is the name of the
<i class="term">data source object</i> to create.
The framework itself will always supply the string <b class="const">%AUTO%</b>, to
signal that the class command has to generate not only the object, but
the object name as well.</p>
<p>This is followed by a series of arguments identifying the data source
the new object is for. These are the same <i class="arg">dsname</i> arguments which
are given to the basic user command <b class="cmd">::tie::tie</b>. Their actual
meaning is dependent on the <i class="term">data source class</i>.</p>
<p>The result of the class command has to be the fully-qualified name of
the new <i class="term">data source object</i>, i.e. the name of the
<i class="term">object command</i>.
The interface this command has to follow is described in the section
<span class="sectref"><a href="#subsection6">DATA SOURCE OBJECT API</a></span></p></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">DATA SOURCE OBJECT API</a></h3>
<p>Please read the section <span class="sectref"><a href="#subsection5">DATA SOURCE CLASS</a></span> first, to know
how to generate new <i class="term">object commands</i>.</p>
<p>Each <i class="term">object command</i> for a <i class="term"><a href="../../../../index.html#data_source">data source</a></i> object has to
provide at least the methods listed below for proper inter-operation
with the tie framework. Note that the names of most of the methods
match the subcommands of the builtin <b class="cmd"><a href="../../../../index.html#array">array</a></b> command.</p>
<dl class="doctools_definitions">
<dt><a name="8"><b class="cmd">ds</b> <b class="method">destroy</b></a></dt>
<dd><p>This method is called when the object <b class="cmd">ds</b> is destroyed. It now
has to release all its internal resources associated with the external
data source.</p></dd>
<dt><a name="9"><b class="cmd">ds</b> <b class="method">names</b></a></dt>
<dd><p>This command has to return a list containing the names of all keys
found in the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> the object talks to. This is
equivalent to <b class="cmd">array names</b>.</p></dd>
<dt><a name="10"><b class="cmd">ds</b> <b class="method">size</b></a></dt>
<dd><p>This command has to return an integer number specifying the number of
keys found in the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> the object talks to. This is
equivalent to <b class="cmd">array size</b>.</p></dd>
<dt><a name="11"><b class="cmd">ds</b> <b class="method">get</b></a></dt>
<dd><p>This command has to return a dictionary containing the data found in
the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> the object talks to. This is equivalent to
<b class="cmd">array get</b>.</p></dd>
<dt><a name="12"><b class="cmd">ds</b> <b class="method">set</b> <i class="arg">dict</i></a></dt>
<dd><p>This command takes a dictionary and adds its contents to the data
source the object talks to. This is equivalent to <b class="cmd">array set</b>.</p></dd>
<dt><a name="13"><b class="cmd">ds</b> <b class="method">unset</b> <span class="opt">?<i class="arg">pattern</i>?</span></a></dt>
<dd><p>This command takes a pattern and removes all elements whose keys
matching it from the <i class="term"><a href="../../../../index.html#data_source">data source</a></i>. If no pattern is specified
it defaults to <b class="const">*</b>, causing the removal of all elements. This
is nearly equivalent to <b class="cmd">array unset</b>.</p></dd>
<dt><a name="14"><b class="cmd">ds</b> <b class="method">setv</b> <i class="arg">index</i> <i class="arg">value</i></a></dt>
<dd><p>This command has to save the <i class="arg">value</i> in the <i class="term"><a href="../../../../index.html#data_source">data source</a></i>
the object talks to, under the key <i class="arg">index</i>.</p>
<p>The result of the command is ignored. If an error is thrown then this
error will show up as error of the set operation which caused the
method call.</p></dd>
<dt><a name="15"><b class="cmd">ds</b> <b class="method">unsetv</b> <i class="arg">index</i></a></dt>
<dd><p>This command has to remove the value under the key <i class="arg">index</i> from
the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> the object talks to.</p>
<p>The result of the command is ignored. If an error is thrown then this
error will show up as error of the unset operation which caused the
method call.</p></dd>
<dt><a name="16"><b class="cmd">ds</b> <b class="method">getv</b> <i class="arg">index</i></a></dt>
<dd><p>This command has to return the value for the key <i class="arg">index</i> in the
<i class="term"><a href="../../../../index.html#data_source">data source</a></i> the object talks to.</p></dd>
</dl>
<p>And here a small table comparing the <i class="term"><a href="../../../../index.html#data_source">data source</a></i> methods to
the regular Tcl commands for accessing an array.</p>
<pre class="doctools_example">
Regular Tcl Data source
----------- -----------
array names a ds names
array size a ds size
array get a ds get
array set a dict ds set dict
array unset a pattern ds unset ?pattern?
----------- -----------
set a($idx) $val ds setv idx val
unset a($idx) ds unsetv idx
$a($idx) ds getv idx
----------- -----------
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tie</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#array">array</a>, <a href="../../../../index.html#database">database</a>, <a href="../../../../index.html#file">file</a>, <a href="../../../../index.html#metakit">metakit</a>, <a href="../../../../index.html#persistence">persistence</a>, <a href="../../../../index.html#tie">tie</a>, <a href="../../../../index.html#untie">untie</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004-2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tie/tie_std.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<div class='fossil-doc' data-title='tie - Tcl Data Structures'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tie(n) 1.1 tcllib "Tcl Data Structures"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tie - Array persistence, standard data sources</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">tie::std::log <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">tie::std::array <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">tie::std::rarray <span class="opt">?1.0.1?</span></b></li>
<li>package require <b class="pkgname">tie::std::file <span class="opt">?1.0.4?</span></b></li>
<li>package require <b class="pkgname">tie::std::growfile <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">tie::std::dsource <span class="opt">?1.0?</span></b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The packages listed as requirements for this document are internal
packages providing the standard data sources of package <b class="package"><a href="tie.html">tie</a></b>,
as described in section <i class="term">STANDARD DATA SOURCE TYPES</i> of
<b class="package"><a href="tie.html">tie</a></b>'s documentation.</p>
<p>They are automatically loaded and registered by <b class="package"><a href="tie.html">tie</a></b> when it
itself is requested, and as such there is no need to request them on
their own, although it is possible to do so.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tie</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#array">array</a>, <a href="../../../../index.html#database">database</a>, <a href="../../../../index.html#file">file</a>, <a href="../../../../index.html#metakit">metakit</a>, <a href="../../../../index.html#persistence">persistence</a>, <a href="../../../../index.html#tie">tie</a>, <a href="../../../../index.html#untie">untie</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008-2015 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tiff/tiff.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<div class='fossil-doc' data-title='tiff - TIFF image manipulation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tiff(n) 0.2.1 tcllib "TIFF image manipulation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tiff - TIFF reading, writing, and querying and manipulation of meta data</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">VARIABLES</a></li>
<li class="doctools_section"><a href="#section4">LIMITATIONS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">tiff <span class="opt">?0.2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tiff::isTIFF</b> <i class="arg">file</i></a></li>
<li><a href="#2"><b class="cmd">::tiff::byteOrder</b> <i class="arg">file</i></a></li>
<li><a href="#3"><b class="cmd">::tiff::numImages</b> <i class="arg">file</i></a></li>
<li><a href="#4"><b class="cmd">::tiff::dimensions</b> <i class="arg">file</i> <span class="opt">?image?</span></a></li>
<li><a href="#5"><b class="cmd">::tiff::imageInfo</b> <i class="arg">file</i> <span class="opt">?image?</span></a></li>
<li><a href="#6"><b class="cmd">::tiff::entries</b> <i class="arg">file</i> <span class="opt">?image?</span></a></li>
<li><a href="#7"><b class="cmd">::tiff::getEntry</b> <i class="arg">file</i> <i class="arg">entry</i> <span class="opt">?image?</span></a></li>
<li><a href="#8"><b class="cmd">::tiff::addEntry</b> <i class="arg">file</i> <i class="arg">entry</i> <span class="opt">?image?</span></a></li>
<li><a href="#9"><b class="cmd">::tiff::deleteEntry</b> <i class="arg">file</i> <i class="arg">entry</i> <span class="opt">?image?</span></a></li>
<li><a href="#10"><b class="cmd">::tiff::getImage</b> <i class="arg">file</i> <span class="opt">?image?</span></a></li>
<li><a href="#11"><b class="cmd">::tiff::writeImage</b> <i class="arg">image</i> <i class="arg">file</i> <span class="opt">?entry?</span></a></li>
<li><a href="#12"><b class="cmd">::tiff::nametotag</b> <i class="arg">names</i></a></li>
<li><a href="#13"><b class="cmd">::tiff::tagtoname</b> <i class="arg">tags</i></a></li>
<li><a href="#14"><b class="cmd">::tiff::debug</b> <i class="arg">file</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to query, modify, read, and write TIFF images.
TIFF stands for <i class="term">Tagged Image File Format</i> and is a standard
for lossless storage of photographical images and associated metadata.
It is specified at <a href="http://partners.adobe.com/public/developer/tiff/index.html">http://partners.adobe.com/public/developer/tiff/index.html</a>.</p>
<p>Multiple images may be stored in a single TIFF file. The <span class="opt">?image?</span> options to the functions
in this package are for accessing images other than the first. Data in a TIFF image is
stored as a series of tags having a numerical value, which are represented in either a 4 digit
hexadecimal format or a string name. For a reference on defined tags and their meanings see
<a href="http://www.awaresystems.be/imaging/tiff/tifftags.html">http://www.awaresystems.be/imaging/tiff/tifftags.html</a></p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tiff::isTIFF</b> <i class="arg">file</i></a></dt>
<dd><p>Returns a boolean value indicating if <i class="arg">file</i> is a
TIFF image.</p></dd>
<dt><a name="2"><b class="cmd">::tiff::byteOrder</b> <i class="arg">file</i></a></dt>
<dd><p>Returns either <b class="const">big</b> or <b class="const">little</b>.
Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="3"><b class="cmd">::tiff::numImages</b> <i class="arg">file</i></a></dt>
<dd><p>Returns the number of images in <i class="arg">file</i>.
Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="4"><b class="cmd">::tiff::dimensions</b> <i class="arg">file</i> <span class="opt">?image?</span></a></dt>
<dd><p>Returns the dimensions of image number <span class="opt">?image?</span> in <i class="arg">file</i> as a list of the
horizontal and vertical pixel count.
Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="5"><b class="cmd">::tiff::imageInfo</b> <i class="arg">file</i> <span class="opt">?image?</span></a></dt>
<dd><p>Returns a dictionary with keys <b class="const">ImageWidth</b>, <b class="const">ImageLength</b>,
<b class="const">BitsPerSample</b>, <b class="const">Compression</b>, <b class="const">PhotometricInterpretation</b>,
<b class="const">ImageDescription</b>, <b class="const">Orientation</b>, <b class="const">XResolution</b>,
<b class="const">YResolution</b>, <b class="const">ResolutionUnit</b>, <b class="const">DateTime</b>, <b class="const">Artist</b>,
and <b class="const">HostComputer</b>. The values are the associated properties of
the TIFF <span class="opt">?image?</span> in <i class="arg">file</i>. Values may be empty if the associated tag is not
present in the file.</p>
<pre class="doctools_example">
puts [::tiff::imageInfo photo.tif]
ImageWidth 686 ImageLength 1024 BitsPerSample {8 8 8} Compression 1
PhotometricInterpretation 2 ImageDescription {} Orientation 1
XResolution 170.667 YResolution 170.667 ResolutionUnit 2 DateTime {2005:12:28 19:44:45}
Artist {} HostComputer {}
</pre>
<p>There is nothing special about these tags, this is simply a convience procedure which calls
<b class="cmd">getEntry</b> with common entries.
Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="6"><b class="cmd">::tiff::entries</b> <i class="arg">file</i> <span class="opt">?image?</span></a></dt>
<dd><p>Returns a list of all entries in the given <i class="arg">file</i> and <span class="opt">?image?</span>
in hexadecimal format.
Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="7"><b class="cmd">::tiff::getEntry</b> <i class="arg">file</i> <i class="arg">entry</i> <span class="opt">?image?</span></a></dt>
<dd><p>Returns the value of <i class="arg">entry</i> from image <span class="opt">?image?</span> in the TIFF <i class="arg">file</i>.
<i class="arg">entry</i> may be a list of multiple entries. If an entry does not exist, an
empty string is returned</p>
<pre class="doctools_example">
set data [::tiff::getEntry photo.tif {0131 0132}]
puts "file was written at [lindex $data 0] with software [lindex $data 1]"
</pre>
<p>Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="8"><b class="cmd">::tiff::addEntry</b> <i class="arg">file</i> <i class="arg">entry</i> <span class="opt">?image?</span></a></dt>
<dd><p>Adds the specified entries to the image named by <span class="opt">?image?</span> (default 0), or optionally <b class="const">all</b>.
<i class="arg">entry</i> must be a list where each element is a list of tag, type, and value. If a tag already
exists, it is overwritten.</p>
<pre class="doctools_example">
::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}}
</pre>
<p>The data types are defined as follows</p>
<dl class="doctools_definitions">
<dt><b class="const">1</b></dt>
<dd><p>BYTE (8 bit unsigned integer)</p></dd>
<dt><b class="const">2</b></dt>
<dd><p>ASCII</p></dd>
<dt><b class="const">3</b></dt>
<dd><p>SHORT (16 bit unsigned integer)</p></dd>
<dt><b class="const">4</b></dt>
<dd><p>LONG (32 bit unsigned integer)</p></dd>
<dt><b class="const">5</b></dt>
<dd><p>RATIONAL</p></dd>
<dt><b class="const">6</b></dt>
<dd><p>SBYTE (8 bit signed byte)</p></dd>
<dt><b class="const">7</b></dt>
<dd><p>UNDEFINED (uninterpreted binary data)</p></dd>
<dt><b class="const">8</b></dt>
<dd><p>SSHORT (signed 16 bit integer)</p></dd>
<dt><b class="const">9</b></dt>
<dd><p>SLONG (signed 32 bit integer)</p></dd>
<dt><b class="const">10</b></dt>
<dd><p>SRATIONAL</p></dd>
<dt><b class="const">11</b></dt>
<dd><p>FLOAT (32 bit floating point number)</p></dd>
<dt><b class="const">12</b></dt>
<dd><p>DOUBLE (64 bit floating point number)</p></dd>
</dl>
<p>Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="9"><b class="cmd">::tiff::deleteEntry</b> <i class="arg">file</i> <i class="arg">entry</i> <span class="opt">?image?</span></a></dt>
<dd><p>Deletes the specified entries from the image named by <span class="opt">?image?</span> (default 0), or optionally <b class="const">all</b>.
Throws an error if <i class="arg">file</i> is not a TIFF image.</p></dd>
<dt><a name="10"><b class="cmd">::tiff::getImage</b> <i class="arg">file</i> <span class="opt">?image?</span></a></dt>
<dd><p>Returns the name of a Tk image containing the image at index <span class="opt">?image?</span> from <i class="arg">file</i>
Throws an error if <i class="arg">file</i> is not a TIFF image, or if image is an unsupported format.
Supported formats are uncompressed 24 bit RGB and uncompressed 8 bit palette.</p></dd>
<dt><a name="11"><b class="cmd">::tiff::writeImage</b> <i class="arg">image</i> <i class="arg">file</i> <span class="opt">?entry?</span></a></dt>
<dd><p>Writes the contents of the Tk image <i class="arg">image</i> to a tiff file <i class="arg">file</i>. Files are
written in the 24 bit uncompressed format, with big endian byte order. Additional entries
to be added to the image may be specified, in the same format as <b class="cmd">tiff::addEntry</b></p></dd>
<dt><a name="12"><b class="cmd">::tiff::nametotag</b> <i class="arg">names</i></a></dt>
<dd><p>Returns a list with <i class="arg">names</i> translated from string to 4 digit format. 4 digit names
in the input are passed through unchanged. Strings without a defined tag name will throw
an error.</p></dd>
<dt><a name="13"><b class="cmd">::tiff::tagtoname</b> <i class="arg">tags</i></a></dt>
<dd><p>Returns a list with <i class="arg">tags</i> translated from 4 digit to string format. If a tag does
not have a defined name it is passed through unchanged.</p></dd>
<dt><a name="14"><b class="cmd">::tiff::debug</b> <i class="arg">file</i></a></dt>
<dd><p>Prints everything we know about the given file in a nice format.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">VARIABLES</a></h2>
<p>The mapping of 4 digit tag names to string names uses the array ::tiff::tiff_tags. The reverse
mapping uses the array ::tiff::tiff_sgat.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">LIMITATIONS</a></h2>
<ol class="doctools_enumerated">
<li><p>Cannot write exif ifd</p></li>
<li><p>Reading limited to uncompressed 8 bit rgb and 8 bit palletized images</p></li>
<li><p>Writing limited to uncompressed 8 bit rgb</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tiff</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#image">image</a>, <a href="../../../../index.html#tif">tif</a>, <a href="../../../../index.html#tiff">tiff</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File formats</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2005-2006, Aaron Faupell <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tool/meta.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
<div class='fossil-doc' data-title='oo::util - Utility commands for TclOO'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">oo::util(n) 1.2.2 tcllib "Utility commands for TclOO"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>oo::util - Utility commands for TclOO</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">AUTHORS</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">oo::util <span class="opt">?1.2.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">mymethod</b> <i class="arg">method</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">classmethod</b> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">body</i></a></li>
<li><a href="#3"><b class="cmd">classvariable</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#4"><b class="cmd">link</b> <i class="arg">method</i>...</a></li>
<li><a href="#5"><b class="cmd">link</b> {<i class="arg">alias</i> <i class="arg">method</i>}...</a></li>
<li><a href="#6"><b class="cmd">ooutil::singleton</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a convenience command for the easy specification
of instance methods as callback commands, like timers, file events, Tk
bindings, etc.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">mymethod</b> <i class="arg">method</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command is available within instance methods. It takes a method
name and, possibly, arguments for the method and returns a command
prefix which, when executed, will invoke the named method of the
object we are in, with the provided arguments, and any others supplied
at the time of actual invokation.</p>
<p>Note: The command is equivalent to and named after the command
provided by the OO package <b class="package"><a href="../snit/snit.html">snit</a></b> for the same purpose.</p></dd>
<dt><a name="2"><b class="cmd">classmethod</b> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">body</i></a></dt>
<dd><p>This command is available within class definitions. It takes a method
name and, possibly, arguments for the method and creates a method on the
class, available to a user of the class and of derived classes.</p>
<p>Note: The command is equivalent to the command <b class="cmd">typemethod</b>
provided by the OO package <b class="package"><a href="../snit/snit.html">snit</a></b> for the same purpose.</p>
<p>Example</p>
<pre class="doctools_example">
oo::class create ActiveRecord {
classmethod find args { puts "[self] called with arguments: $args" }
}
oo::class create Table {
superclass ActiveRecord
}
puts [Table find foo bar]
# ======
# which will write
# ======
# ::Table called with arguments: foo bar
</pre>
</dd>
<dt><a name="3"><b class="cmd">classvariable</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command is available within instance methods. It takes a series
of variable names and makes them available in the method's scope. The
originating scope for the variables is the class (instance) the object
instance belongs to. In other words, the referenced variables are shared
between all instances of their class.</p>
<p>Note: The command is roughly equivalent to the command
<b class="cmd">typevariable</b> provided by the OO package <b class="package"><a href="../snit/snit.html">snit</a></b> for the
same purpose. The difference is that it cannot be used in the class
definition itself.</p>
<p>Example:</p>
<pre class="doctools_example">
% oo::class create Foo {
method bar {z} {
classvariable x y
return [incr x $z],[incr y]
}
}
::Foo
% Foo create a
::a
% Foo create b
::b
% a bar 2
2,1
% a bar 3
5,2
% b bar 7
12,3
% b bar -1
11,4
% a bar 0
11,5
</pre>
</dd>
<dt><a name="4"><b class="cmd">link</b> <i class="arg">method</i>...</a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">link</b> {<i class="arg">alias</i> <i class="arg">method</i>}...</a></dt>
<dd><p>This command is available within instance methods. It takes a list of
method names and/or pairs of alias- and method-name and makes the
named methods available to all instance methods without requiring the
<b class="cmd">my</b> command.</p>
<p>The alias name under which the method becomes available defaults
to the method name, except where explicitly specified through an
alias/method pair.</p>
<p>Examples:</p>
<pre class="doctools_example">
link foo
# The method foo is now directly accessible as foo instead of my foo.
link {bar foo}
# The method foo is now directly accessible as bar.
link a b c
# The methods a, b, and c all become directly acessible under their
# own names.
</pre>
<p>The main use of this command is expected to be in instance constructors,
for convenience, or to set up some methods for use in a mini DSL.</p></dd>
<dt><a name="6"><b class="cmd">ooutil::singleton</b> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This command is a meta-class, i.e. a variant of the builtin
<b class="cmd">oo::class</b> which ensures that it creates only a single
instance of the classes defined with it.</p>
<p>Syntax and results are like for <b class="cmd">oo::class</b>.</p>
<p>Example:</p>
<pre class="doctools_example">
% oo::class create example {
self mixin singleton
method foo {} {self}
}
::example
% [example new] foo
::oo::Obj22
% [example new] foo
::oo::Obj22
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">AUTHORS</a></h2>
<p>Donal Fellows, Andreas Kupries</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>oo::util</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../snit/snit.html">snit(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tcloo">TclOO</a>, <a href="../../../../index.html#callback">callback</a>, <a href="../../../../index.html#class_methods">class methods</a>, <a href="../../../../index.html#class_variables">class variables</a>, <a href="../../../../index.html#command_prefix">command prefix</a>, <a href="../../../../index.html#currying">currying</a>, <a href="../../../../index.html#method_reference">method reference</a>, <a href="../../../../index.html#my_method">my method</a>, <a href="../../../../index.html#singleton">singleton</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011-2015 Andreas Kupries, BSD licensed</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tool/tool.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
<div class='fossil-doc' data-title='tool - Standardized OO Framework for development'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tool(n) 0.4.2 tcllib "Standardized OO Framework for development"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tool - TclOO Library (TOOL) Framework</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Keywords</a></li>
<li class="doctools_section"><a href="#section3">Public Object Methods</a></li>
<li class="doctools_section"><a href="#section4">Private Object Methods</a></li>
<li class="doctools_section"><a href="#section5">AUTHORS</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">sha1</b></li>
<li>package require <b class="pkgname">dicttool</b></li>
<li>package require <b class="pkgname">oo::meta</b></li>
<li>package require <b class="pkgname">oo::dialect</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1">tool::define <b class="cmd">class_method</b> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#2">tool::define <b class="cmd"><a href="../../../../index.html#array">array</a></b> <i class="arg">name</i> <i class="arg">contents</i></a></li>
<li><a href="#3">tool::define <b class="cmd">array_ensemble</b> <i class="arg">methodname</i> <i class="arg">varname</i> <span class="opt">?cases?</span></a></li>
<li><a href="#4">tool::define <b class="cmd">dict_ensemble</b> <i class="arg">methodname</i> <i class="arg">varname</i> <span class="opt">?cases?</span></a></li>
<li><a href="#5">tool::define <b class="cmd"><a href="../../../../index.html#method">method</a></b> <i class="arg">methodname</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#6">tool::define <b class="cmd">option</b> <i class="arg">name</i> <i class="arg">dictopts</i></a></li>
<li><a href="#7">tool::define <b class="cmd">property</b> <span class="opt">?branch?</span> <i class="arg">field</i> <i class="arg">value</i></a></li>
<li><a href="#8">tool::define <b class="cmd">variable</b> <i class="arg">name</i> <i class="arg">value</i></a></li>
<li><a href="#9"><em>object</em> <b class="cmd">cget</b> <i class="arg">option</i></a></li>
<li><a href="#10"><em>object</em> <b class="cmd">configure</b> <span class="opt">?keyvaluelist?</span></a></li>
<li><a href="#11"><em>object</em> <b class="cmd">configure</b> <i class="arg">field</i> <i class="arg">value</i> <span class="opt">?field?</span> <span class="opt">?value?</span> <span class="opt">?...?</span></a></li>
<li><a href="#12"><em>object</em> <b class="cmd">configurelist</b> <span class="opt">?keyvaluelist?</span></a></li>
<li><a href="#13"><em>object</em> <b class="cmd">forward</b> <i class="arg">stub</i> <i class="arg">forward</i></a></li>
<li><a href="#14"><em>object</em> <b class="cmd">graft</b> <i class="arg">stub</i> <i class="arg">forward</i></a></li>
<li><a href="#15"><em>object</em> <b class="cmd">InitializePublic</b></a></li>
<li><a href="#16"><em>object</em> <b class="cmd">Eval_Script</b> <span class="opt">?script?</span></a></li>
<li><a href="#17"><em>object</em> <b class="cmd">Option_Default</b> <i class="arg">field</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This module implements the Tcl Object Oriented Library framework, or <em>TOOL</em>. It is
intended to be a general purpose framework that is useable in its own right, and
easily extensible.</p>
<p>TOOL defines a metaclass with provides several additional keywords to the TclOO
description langauge, default behaviors for its consituent objects, and
top-down integration with the capabilities provided by the <b class="package">oo::meta</b> package.</p>
<p>The TOOL metaclass was build with the <b class="package">oo::dialect</b> package, and thus can
be used as the basis for additional metaclasses. As a metaclass, TOOL has it's own
"class" class, "object" class, and define namespace.</p>
<pre class="doctools_example">
package require tool
# tool::class workds just like oo::class
tool::class create myclass {
}
# tool::define works just like oo::define
tool::define myclass method noop {} {}
# tool::define and tool::class understand additional keywords
tool::define myclass array_ensemble mysettings mysettings {}
# And tool interoperates with oo::define
oo::define myclass method do_something {} { return something }
# TOOL and TclOO objects are interchangeable
oo::class create myooclass {
superclass myclass
}
</pre>
<p>Several manual pages go into more detail about specific keywords and methods.</p>
<dl class="doctools_definitions">
<dt><b class="package">tool::array_ensemble</b></dt>
<dd></dd>
<dt><b class="package"><a href="tool_dict_ensemble.html">tool::dict_ensemble</a></b></dt>
<dd></dd>
<dt><b class="package">tool::method_ensemble</b></dt>
<dd></dd>
<dt><b class="package">tool::object</b></dt>
<dd></dd>
<dt><b class="package">tool::option_handling</b></dt>
<dd></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Keywords</a></h2>
<p>TOOL adds new (or modifies) keywords used in the definitions of classes. However,
the new keywords are only available via calls to <em>tool::class create</em> or <em>tool::define</em></p>
<dl class="doctools_definitions">
<dt><a name="1">tool::define <b class="cmd">class_method</b> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Defines a method for the class object itself. This method will be passed on to descendents of the class,
unlike <b class="cmd">self method</b>.</p></dd>
<dt><a name="2">tool::define <b class="cmd"><a href="../../../../index.html#array">array</a></b> <i class="arg">name</i> <i class="arg">contents</i></a></dt>
<dd><p>Declares a variable <i class="arg">name</i> which will be initialized as an array, populated with <i class="arg">contents</i> for objects of this class, as well as any
objects for classes which are descendents of this class.</p></dd>
<dt><a name="3">tool::define <b class="cmd">array_ensemble</b> <i class="arg">methodname</i> <i class="arg">varname</i> <span class="opt">?cases?</span></a></dt>
<dd><p>Declares a method ensemble <i class="arg">methodname</i> which will control access to variable
<i class="arg">varname</i>. Cases are a key/value list of method names and bodies which will be
overlaid on top of the standard template. See <b class="package">tool::array_ensemble</b>.</p>
<p>One method name is reserved: <b class="cmd">initialize</b>. <b class="cmd">initialize</b> Declares the initial values to be populated in the array, as a key/value list,
and will not be expressed as a method for the ensemble.</p></dd>
<dt><a name="4">tool::define <b class="cmd">dict_ensemble</b> <i class="arg">methodname</i> <i class="arg">varname</i> <span class="opt">?cases?</span></a></dt>
<dd><p>Declares a method ensemble <i class="arg">methodname</i> which will control access to variable
<i class="arg">varname</i>. Cases are a key/value list of method names and bodies which will be
overlaid on top of the standard template. See <b class="package"><a href="tool_dict_ensemble.html">tool::dict_ensemble</a></b>.</p>
<p>One method name is reserved: <b class="cmd">initialize</b>. <b class="cmd">initialize</b> Declares the initial values to be populated in the array, as a key/value list,
and will not be expressed as a method for the ensemble.</p></dd>
<dt><a name="5">tool::define <b class="cmd"><a href="../../../../index.html#method">method</a></b> <i class="arg">methodname</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>If <i class="arg">methodname</i> contains ::, the method is considered to be
part of a method ensemble. See <b class="package">tool::method_ensembles</b>. Otherwise
this command behaves exactly like the standard <b class="namespace">oo::define</b> <b class="cmd"><a href="../../../../index.html#method">method</a></b>
command.</p></dd>
<dt><a name="6">tool::define <b class="cmd">option</b> <i class="arg">name</i> <i class="arg">dictopts</i></a></dt>
<dd><p>Declares an option. <i class="arg">dictopts</i> is a key/value list defining parameters for the option. See <b class="package">tool::option_handling</b>.</p>
<pre class="doctools_example">
tool::class create myclass {
option color {
post-command: {puts [list %self%'s %field% is now %value%]}
default: green
}
}
myclass create foo
foo configure color purple
> foo's color is now purple
</pre>
</dd>
<dt><a name="7">tool::define <b class="cmd">property</b> <span class="opt">?branch?</span> <i class="arg">field</i> <i class="arg">value</i></a></dt>
<dd><p>Defines a new leaf in the class metadata tree. With no branch, the
leaf will appear in the <em>const</em> section, accessible by either the
object's <b class="cmd">property</b> method, or via <b class="cmd">oo::meta::info</b> <em>class</em> <b class="cmd">get const</b> <em>field</em>:</p></dd>
<dt><a name="8">tool::define <b class="cmd">variable</b> <i class="arg">name</i> <i class="arg">value</i></a></dt>
<dd><p>Declares a variable <i class="arg">name</i> which will be initialized with the value <i class="arg">value</i> for objects of this class, as well as any
objects for classes which are descendents of this class.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Public Object Methods</a></h2>
<p>The TOOL object mother of all classes defines several methods to enforces consistent
behavior throughout the framework.</p>
<dl class="doctools_definitions">
<dt><a name="9"><em>object</em> <b class="cmd">cget</b> <i class="arg">option</i></a></dt>
<dd><p>Return the value of this object's option <i class="arg">option</i>. If the <b class="cmd">property options_strict</b> is true
for this class, calling an option which was not declared by the <b class="cmd">option</b> keyword will throw
an error. In all other cases if the value is present in the object's <em>options</em> array that
value is returned. If it does not exist, the object will attempt to retrieve a property of the same
name.</p></dd>
<dt><a name="10"><em>object</em> <b class="cmd">configure</b> <span class="opt">?keyvaluelist?</span></a></dt>
<dd></dd>
<dt><a name="11"><em>object</em> <b class="cmd">configure</b> <i class="arg">field</i> <i class="arg">value</i> <span class="opt">?field?</span> <span class="opt">?value?</span> <span class="opt">?...?</span></a></dt>
<dd><p>This command will inject new values into the objects <em>options</em> array, according to the rules
as set forth by the option descriptions. See <b class="package">tool::option_handling</b> for details.
<b class="cmd">configure</b> will strip leading -'s off of field names, allowing it to behave in a quasi-backward
compatible manner to tk options.</p></dd>
<dt><a name="12"><em>object</em> <b class="cmd">configurelist</b> <span class="opt">?keyvaluelist?</span></a></dt>
<dd><p>This command will inject new values into the objects <em>options</em> array, according to the rules
as set forth by the option descriptions. This command will perform validation and alternate storage
rules. It will not invoke trigger rules. See <b class="package">tool::option_handling</b> for details.</p></dd>
<dt><a name="13"><em>object</em> <b class="cmd">forward</b> <i class="arg">stub</i> <i class="arg">forward</i></a></dt>
<dd><p>A passthrough to <b class="cmd">oo:objdefine [self] forward</b></p></dd>
<dt><a name="14"><em>object</em> <b class="cmd">graft</b> <i class="arg">stub</i> <i class="arg">forward</i></a></dt>
<dd><p>Delegates the <i class="arg"><stub></i> method to the object or command designated by <i class="arg">forward</i></p>
<pre class="doctools_example">
tool::object create A
tool::object create B
A graft buddy B
A configure color red
B configure color blue
A cget color
> red
A <buddy> cget color
> blue
</pre>
</dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Private Object Methods</a></h2>
<dl class="doctools_definitions">
<dt><a name="15"><em>object</em> <b class="cmd">InitializePublic</b></a></dt>
<dd><p>Consults the metadata for the class to ensure every array, option, and variable
which has been declared but not initialized is initialized with the default value.
This method is called by the constructor and the morph method. It is safe to
invoke multiple times.</p></dd>
<dt><a name="16"><em>object</em> <b class="cmd">Eval_Script</b> <span class="opt">?script?</span></a></dt>
<dd><p>Executes a block of text within the namespace of the object. Lines that
begin with a # are ignored as comments. Commands
that begin with :: are interpreted as calling a global command. All other
Tcl commands that lack a "my" prefix are given one, to allow the script
to exercise internal methods. This method is intended for configuration scripts,
where the object's methods are intepreting a domain specific language.</p>
<pre class="doctools_example">
tool::class myclass {
constructor script {
my Eval_Script $script
}
method node {nodename info} {
my variable node
dict set node $nodename $info
}
method get {args} {
my variable node
return [dict get $node $args]
}
}
myclass create movies {
# This block of code is executed by the object
node {The Day the Earth Stood Still} {
date: 1952
characters: {GORT Klatoo}
}
}
movies get {The Day the Earth Stood Still} date:
> 1952
</pre>
</dd>
<dt><a name="17"><em>object</em> <b class="cmd">Option_Default</b> <i class="arg">field</i></a></dt>
<dd><p>Computes the default value for an option. See <b class="package">tool::option_handling</b>.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">AUTHORS</a></h2>
<p>Sean Woods</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tcloo</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tool">TOOL</a>, <a href="../../../../index.html#tcloo">TclOO</a>, <a href="../../../../index.html#framework">framework</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>TclOO</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/tool/tool_dict_ensemble.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
<div class='fossil-doc' data-title='tool::dict_ensemble - Standardized OO Framework for development'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tool::dict_ensemble(n) 0.4.2 tcllib "Standardized OO Framework for development"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tool::dict_ensemble - Dictionary Tools</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">AUTHORS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">tool <span class="opt">?0.4.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><em>object</em> <i class="arg">ensemble</i> <b class="cmd">add</b> <i class="arg">field</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="cmd">dict_ensemble</b> command is a keyword added by <b class="package"><a href="tool.html">tool</a></b>. It defines
a public variable (stored as a dict), and an access function to manipulated and
access the values stored in that dict.</p>
<dl class="doctools_definitions">
<dt><a name="1"><em>object</em> <i class="arg">ensemble</i> <b class="cmd">add</b> <i class="arg">field</i></a></dt>
<dd><p>] <i class="arg">value</i> <i class="arg">value ...</i>]
Adds elements to a list maintained with the <i class="arg">field</i> leaf of the dict maintained
my this ensemble.
Declares a variable <i class="arg">name</i> which will be initialized as an array, populated with <i class="arg">contents</i> for objects of this class, as well as any
objects for classes which are descendents of this class.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">AUTHORS</a></h2>
<p>Sean Woods</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>tool</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tool">TOOL</a>, <a href="../../../../index.html#tcloo">TclOO</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/connect.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
|
<div class='fossil-doc' data-title='transfer::connect - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::connect(n) 0.2 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::connect - Connection setup</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
<li class="doctools_subsection"><a href="#subsection4">Options</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Secure connections</a></li>
<li class="doctools_section"><a href="#section4">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">transfer::connect <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::connect</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">connect</b> <i class="arg">command</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects holding enough information to enable
them to either actively connect to a counterpart, or to passively wait
for a connection from said counterpart.
I.e. any object created by this packages is always in one of two
complementary modes, called <i class="term"><a href="../../../../index.html#active">active</a></i> (the object initiates the
connection) and <i class="term"><a href="../../../../index.html#passive">passive</a></i> (the object receives the connection).</p>
<p>Of the two objects in a connecting pair one has to be configured for
<i class="term"><a href="../../../../index.html#active">active</a></i> mode, and the other then has to be configured for
<i class="term"><a href="../../../../index.html#passive">passive</a></i> mode. This establishes which of the two partners
connects to whom (the <i class="term"><a href="../../../../index.html#active">active</a></i> to the other), or, who is waiting
on whom (the <i class="term"><a href="../../../../index.html#passive">passive</a></i> on the other).
Note that this is completely independent of the direction of any data
transmission using the connection after it has been established.
An active object can, after establishing the connection, either
transmit or receive data. Equivalently the passive object can do the
same after the waiting for its partner has ended.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::connect</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new connection object with an associated Tcl
command whose name is <i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection2">Object command</a></span> and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#subsection4">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::connect</b> command have the
following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object.
This is safe to do for an <i class="term"><a href="../../../../index.html#active">active</a></i> object when a connection has
been started, as the completion callback is synchronous.
For a <i class="term"><a href="../../../../index.html#passive">passive</a></i> object currently waiting for its partner to
establish the connection however this is not safe and will cause
errors later on, when the connection setup completes and tries to
access the now missing data structures of the destroyed object.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">connect</b> <i class="arg">command</i></a></dt>
<dd><p>This method starts the connection setup per the configuration of the
object. When the connection is established the callback <i class="arg">command</i>
will be invoked with one additional argument, the channel handle of
the socket over which data can be transfered.</p>
<p>The detailed behaviour of the method depends on the configured
mode.</p>
<dl class="doctools_definitions">
<dt><i class="term"><a href="../../../../index.html#active">active</a></i></dt>
<dd><p>The connection setup is done synchronously. The object waits until the
connection is established. The method returns the empty string as its
result.</p></dd>
<dt><i class="term"><a href="../../../../index.html#passive">passive</a></i></dt>
<dd><p>The connection setup is done asynchronously. The method returns
immediately after a listening socket has been set up. The connection
will be established in the background.
The method returns the port number of the listening socket, for use by
the caller. One important use is the transfer of this information to
the counterpart so that it knows where it has to connect to.</p>
<p>This is necessary as the object might have been configured for port
<b class="const">0</b>, allowing the operating system to choose the actual port it
will listen on.</p>
<p>The listening port is closed immediately when the connection was
established by the partner, to keep the time interval small within
which a third party can connect to the port too.
Even so it is recommended to use additional measures in the protocol
outside of the connect and transfer object to ensure that a connection
is not used with an unidentified/unauthorized partner
One possibility for this is the use of SSL/TLS.
See the option <b class="option">-socketcmd</b> and section
<span class="sectref"><a href="#section3">Secure connections</a></span> for information on how to do this.</p></dd>
</dl></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Options</a></h3>
<p>Connection objects support the set of options listed below.</p>
<dl class="doctools_options">
<dt><b class="option">-mode</b> <i class="arg">mode</i></dt>
<dd><p>This option specifies the mode the object is in. It is optional and
defaults to <b class="const">active</b> mode. The two possible modes are:</p>
<dl class="doctools_definitions">
<dt><b class="const">active</b></dt>
<dd><p>In this mode the two options <b class="option">-host</b> and <b class="option">-port</b> are
relevant and specify the host and TCP port the object has to connect
to. The host is given by either name or IP address.</p></dd>
<dt><b class="const">passive</b></dt>
<dd><p>In this mode the option <b class="option">-host</b> has no relevance and is ignored
should it be configured.
The only option the object needs is <b class="option">-port</b>, and it specifies
the TCP port on which the listening socket is opened to await the
connection from the partner.</p></dd>
</dl></dd>
<dt><b class="option">-host</b> <i class="arg">hostname-or-ipaddr</i></dt>
<dd><p>This option specifies the host to connect to in <i class="term"><a href="../../../../index.html#active">active</a></i> mode,
either by name or ip-address. An object configured for <i class="term"><a href="../../../../index.html#passive">passive</a></i>
mode ignores this option.</p></dd>
<dt><b class="option">-port</b> <i class="arg">int</i></dt>
<dd><p>For <i class="term"><a href="../../../../index.html#active">active</a></i> mode this option specifies the port the object is
expected to connect to. For <i class="term"><a href="../../../../index.html#passive">passive</a></i> mode however it is the port
where the object creates the listening socket waiting for a
connection. It defaults to <b class="const">0</b>, which allows the OS to choose
the actual port to listen on.</p></dd>
<dt><b class="option">-socketcmd</b> <i class="arg">command</i></dt>
<dd><p>This option allows the user to specify which command to use to open a
socket. The default is to use the builtin <b class="cmd">::socket</b>. Any
compatible with that command is allowed.</p>
<p>The envisioned main use is the specfication of <b class="cmd">tls::socket</b>. I.e.
this option allows the creation of secure transfer channels, without
making this package explicitly dependent on the <b class="package"><a href="../../../../index.html#tls">tls</a></b> package.</p>
<p>See also section <span class="sectref"><a href="#section3">Secure connections</a></span>.</p></dd>
<dt><b class="option">-encoding</b> encodingname</dt>
<dd></dd>
<dt><b class="option">-eofchar</b> eofspec</dt>
<dd></dd>
<dt><b class="option">-translation</b> transspec</dt>
<dd><p>These options are the same as are recognized by the builtin command
<b class="cmd">fconfigure</b>. They provide the configuration to be set for the
channel between the two partners after it has been established, but
before the callback is invoked (See method <b class="method">connect</b>).</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Secure connections</a></h2>
<p>One way to secure connections made by objects of this package is to
require the package <b class="package"><a href="../../../../index.html#tls">tls</a></b> and then configure the option
<b class="option">-socketcmd</b> to force the use of command <b class="cmd">tls::socket</b> to
open the socket.</p>
<pre class="doctools_example">
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create a connector with secure socket setup,
transfer::connect C -socketcmd tls::socket ...
...
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#active">active</a>, <a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#connection">connection</a>, <a href="../../../../index.html#passive">passive</a>, <a href="../../../../index.html#secure">secure</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/copyops.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<div class='fossil-doc' data-title='transfer::copy - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::copy(n) 0.2 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::copy - Data transfer foundation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">transfer::copy <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::copy::do</b> <b class="const">chan</b>|<b class="const">string</b> <i class="arg">data</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">transfer::copy::chan</b> <i class="arg">channel</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">transfer::copy::string</b> <i class="arg">string</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#4"><b class="cmd">transfer::copy::doChan</b> <i class="arg">channel</i> <i class="arg">outchannel</i> <i class="arg">optvar</i></a></li>
<li><a href="#5"><b class="cmd">transfer::copy::doString</b> <i class="arg">string</i> <i class="arg">outchannel</i> <i class="arg">optvar</i></a></li>
<li><a href="#6"><b class="cmd">transfer::copy::options</b> <i class="arg">outchannel</i> <i class="arg">optionlist</i> <i class="arg">optvar</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a number of commands for the asynchronous of
information contained in either a string or channel. The main point of
this package is that the commands here provide a nicer callback API
than the builtin command <b class="cmd">fcopy</b>, making the use of these
facilities simpler than the builtin.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::copy::do</b> <b class="const">chan</b>|<b class="const">string</b> <i class="arg">data</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command transfers the information in <i class="arg">data</i> to the
<i class="arg">outchannel</i>, according to the <i class="arg">options</i>. The type of the
information in <i class="arg">data</i> is determined by the first argument.</p>
<p>The options available to this command are the same as are available to
the command <b class="cmd">transfer::copy::options</b>, and explained there.</p>
<dl class="doctools_definitions">
<dt><b class="const">chan</b></dt>
<dd><p>The argument <i class="arg">data</i> contains the handle of a channel and the
actual infomration to transfer is read from that channel.</p></dd>
<dt><b class="const">string</b></dt>
<dd><p>The argument <i class="arg">data</i> contains a string and this is the information
to be transfered.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">transfer::copy::chan</b> <i class="arg">channel</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command is a shorter and more direct form for the command
<b class="cmd">transfer::copy::do chan</b>.</p></dd>
<dt><a name="3"><b class="cmd">transfer::copy::string</b> <i class="arg">string</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command is a shorter and more direct form for the command
<b class="cmd">transfer::copy::do string</b>.</p></dd>
<dt><a name="4"><b class="cmd">transfer::copy::doChan</b> <i class="arg">channel</i> <i class="arg">outchannel</i> <i class="arg">optvar</i></a></dt>
<dd><p>This command is an alternate form of <b class="cmd">transfer::copy::chan</b> which
reads its options out of the array variable named by <i class="arg">optvar</i>
instead of from a variable length argument list.</p></dd>
<dt><a name="5"><b class="cmd">transfer::copy::doString</b> <i class="arg">string</i> <i class="arg">outchannel</i> <i class="arg">optvar</i></a></dt>
<dd><p>This command is an alternate form of <b class="cmd">transfer::copy::string</b> which
reads its options out of the array variable named by <i class="arg">optvar</i>
instead of from a variable length argument list.</p></dd>
<dt><a name="6"><b class="cmd">transfer::copy::options</b> <i class="arg">outchannel</i> <i class="arg">optionlist</i> <i class="arg">optvar</i></a></dt>
<dd><p>This command is the option processor used by all the commands above
which read their options from a variable length argument list. It
first reads default settings from the channel handle <i class="arg">outchannel</i>,
then processes the list of options in <i class="arg">optionlist</i>, at last stores
the results in the array variable named by <i class="arg">optvar</i>. The contents
of that variable are in a format which is directly understood by all
the commands above which read their options out of an array variable.</p>
<p>The recognized options are:</p>
<dl class="doctools_options">
<dt><b class="option">-blocksize</b> <i class="arg">int</i></dt>
<dd><p>This option specifies the size of the chunks to transfer in one
operation. It is optional and defaults to the value of
<b class="option">-buffersize</b> as configured for the output channel.</p>
<p>If specified its value has to be an integer number greater than zero.</p></dd>
<dt><b class="option">-command</b> <i class="arg">commandprefix</i></dt>
<dd><p>This option specifies the completion callback of the operation. This
option has to be specified. An error will be thrown if it is not, or
if the empty list was specified as argument to it.</p>
<p>Its value has to be a command prefix, i.e. a list whose first word is
the command to execute, followed by words containing fixed
arguments. When the callback is invoked one or two additional
arguments are appended to the prefix. The first argument is the number
of bytes which were transfered. The optional second argument is an
error message and added if and only if an error occured during the the
transfer.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">commandprefix</i></dt>
<dd><p>This option specifies the progress callback of the operation. It is
optional and defaults to the empty list. This last possibility signals
that no feedback was asked for and disabled it.</p>
<p>Its value has to be a command prefix, see above, <b class="option">-command</b> for
a more detailed explanation. When the callback is invoked a single
additional arguments is appended to the prefix. This argument is the
number of bytes which were transfered so far.</p></dd>
<dt><b class="option">-size</b> <i class="arg">int</i></dt>
<dd><p>This option specifies the number of bytes to read from the input data
and transfer. It is optional and defaults to "Transfer everything".
Its value has to be an integer number and any value less than zero has
the same meaning, i.e. to transfer all available data. Any other value
is the amount of bytes to transfer.</p>
<p>All transfer commands will throw error an when their user tries to
transfer more data than is available in the input. This happens
immediately, before the transfer is actually started, should the input
be a string. Otherwise the, i.e. for a channel as input, the error is
thrown the moment the underflow condition is actually detected.</p></dd>
<dt><b class="option">-encoding</b> <i class="arg">encodingname</i></dt>
<dd></dd>
<dt><b class="option">-eofchar</b> <i class="arg">eofspec</i></dt>
<dd></dd>
<dt><b class="option">-translation</b> <i class="arg">transspec</i></dt>
<dd><p>These options are the same as are recognized by the builtin command
<b class="cmd">fconfigure</b> and provide the settings for the output channel which
are to be active during the transfer, and only then. I.e. the settings
of the output channel before the transfer are saved, and restored at
the end of a transfer, regardless of its success or failure. None of
these options are required, and they default to the settings of the
output channel if not specified.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/ddest.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<div class='fossil-doc' data-title='transfer::data::destination - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::data::destination(n) 0.2 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::data::destination - Data destination</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object methods</a></li>
<li class="doctools_subsection"><a href="#subsection3">Options</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">transfer::data::destination <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::data::destination</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">put</b> <i class="arg">chunk</i></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">done</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">valid</b> <i class="arg">msgvar</i></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">receive</b> <i class="arg">channel</i> <i class="arg">done</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects mainly describing the destination of a
data transfer. They are also able to initiate the reception of
information from a channel into the described destination.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::data::destination</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new data destination object with an associated
Tcl command whose name is <i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection1">Object command</a></span> and <span class="sectref"><a href="#subsection2">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#subsection3">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::data::destination</b> command
have the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection2">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object. Doing so while the object is busy
with the reception of information from a channel will cause errors
later on, when the reception completes and tries to access the now
missing data structures of the destroyed object.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">put</b> <i class="arg">chunk</i></a></dt>
<dd><p>The main receptor method. Saves the received <i class="arg">chunk</i> of data into
the configured destination. It has to be called for each piece of data
received.</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">done</b></a></dt>
<dd><p>The secondary receptor method. Finalizes the receiver. It has to be
called when the receiving channel signals EOF. Afterward neither
itself nor method <b class="method">put</b> can be called anymore.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">valid</b> <i class="arg">msgvar</i></a></dt>
<dd><p>This method checks the configuration of the object for validity. It
returns a boolean flag as result, whose value is <b class="const">True</b> if the
object is valid, and <b class="const">False</b> otherwise. In the latter case the
variable whose name is stored in <i class="arg">msgvar</i> is set to an error
message describing the problem found with the configuration. Otherwise
this variable is not touched.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">receive</b> <i class="arg">channel</i> <i class="arg">done</i></a></dt>
<dd><p>This method initiates the reception of data from the specified
<i class="arg">channel</i>. The received data will be stored into the configured
destination, via calls to the methods <b class="method">put</b> and <b class="method">done</b>.
When the reception completes the command prefix <i class="arg">done</i> is invoked,
with the number of received characters appended to it as the sole
additional argument.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Options</a></h3>
<p>All data destinations support the options listed below. It should be
noted that all are semi-exclusive, each specifying a different type of
destination and associated information. If these options are specified
more than once then the last option specified is used to actually
configure the object.</p>
<dl class="doctools_options">
<dt><b class="option">-channel</b> <i class="arg">handle</i></dt>
<dd><p>This option specifies that the destination of the data is a channel,
and its associated argument is the handle of the channel to write the
received data to.</p></dd>
<dt><b class="option">-file</b> <i class="arg">path</i></dt>
<dd><p>This option specifies that the destination of the data is a file, and
its associated argument is the path of the file to write the received
data to.</p></dd>
<dt><b class="option">-variable</b> <i class="arg">varname</i></dt>
<dd><p>This option specifies that the destination of the data is a variable,
and its associated argument contains the name of the variable to write
the received data to. The variable is assumed to be global or
namespaced, anchored at the global namespace.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">command</i></dt>
<dd><p>This option, if specified, defines a command to be invoked for each
chunk of bytes received, allowing the user to monitor the progress of
the reception of the data. The callback is always invoked with one
additional argument, the number of bytes received so far.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#data_destination">data destination</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/dsource.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
<div class='fossil-doc' data-title='transfer::data::source - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::data::source(n) 0.2 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::data::source - Data source</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
<li class="doctools_subsection"><a href="#subsection4">Options</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">transfer::copy <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::data::source <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::data::source</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">type</b></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">data</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">size</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">valid</b> <i class="arg">msgvar</i></a></li>
<li><a href="#8"><i class="arg">objectName</i> <b class="method">transmit</b> <i class="arg">channel</i> <i class="arg">blocksize</i> <i class="arg">done</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects mainly describing the origin of some
data to transfer. They are also able to initiate transfers of the
described information to a channel using the foundation package
<b class="package"><a href="copyops.html">transfer::copy</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::data::source</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new data source object with an associated Tcl
command whose name is <i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection2">Object command</a></span> and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#subsection4">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::data::source</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object. Doing so while a transfer initiated
by the object is active is safe as all data required for the transfer
itself was copied, and the completion of the transfer will not try to
access the initiating object anymore. i.e. the transfer is completely
separate from the source object itself.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">type</b></a></dt>
<dd><p>This method returns a string describing the type of the data the
object is refering to. The possible values and their meanings are:</p>
<dl class="doctools_definitions">
<dt><b class="const">undefined</b></dt>
<dd><p>No data was specified at all, or it was specified incompletely. The
object does not know the type.</p></dd>
<dt><b class="const">string</b></dt>
<dd><p>The data to transfer is contained in a string.</p></dd>
<dt><b class="const">channel</b></dt>
<dd><p>The data to transfer is contained in a channel.</p></dd>
</dl></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">data</b></a></dt>
<dd><p>This method returns a value depending on the type of the data the
object refers to, through which the data can be accessed.
The method throws an error if the type is <b class="const">undefined</b>. For type
<b class="const">string</b> the returned result is the data itself, whereas for
type <b class="const">channel</b> the returned result is the handle of the channel
containing the data.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">size</b></a></dt>
<dd><p>This method returns a value depending on the type of the data the
object refers to, the size of the data.
The method throws an error if the type is <b class="const">undefined</b>. Return of
a negative value signals that the object is unable to determine an
absolute size upfront (like for data in a channel).</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">valid</b> <i class="arg">msgvar</i></a></dt>
<dd><p>This method checks the configuration of the object for validity. It
returns a boolean flag as result, whose value is <b class="const">True</b> if the
object is valid, and <b class="const">False</b> otherwise. In the latter case the
variable whose name is stored in <i class="arg">msgvar</i> is set to an error
message describing the problem found with the configuration. Otherwise
this variable is not touched.</p></dd>
<dt><a name="8"><i class="arg">objectName</i> <b class="method">transmit</b> <i class="arg">channel</i> <i class="arg">blocksize</i> <i class="arg">done</i></a></dt>
<dd><p>This method initiates a transfer of the referenced data to the
specified <i class="arg">channel</i>.
When the transfer completes the command prefix <i class="arg">done</i> is invoked,
per the rules for the option <b class="option">-command</b> of command
<b class="cmd">transfer::copy::do</b> in the package <b class="package"><a href="copyops.html">transfer::copy</a></b>.
The <i class="arg">blocksize</i> specifies the size of the chunks to transfer in
one go. See the option <b class="option">-blocksize</b> of command
<b class="cmd">transfer::copy::do</b> in the package <b class="package"><a href="copyops.html">transfer::copy</a></b>.</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Options</a></h3>
<p>All data sources support the options listed below. It should be noted
that the first four options are semi-exclusive, each specifying a
different type of data source and associated content. If these options
are specified more than once then the last option specified is used to
actually configure the object.</p>
<dl class="doctools_options">
<dt><b class="option">-string</b> <i class="arg">text</i></dt>
<dd><p>This option specifies that the source of the data is an immediate
string, and its associated argument contains the string in question.</p></dd>
<dt><b class="option">-channel</b> <i class="arg">handle</i></dt>
<dd><p>This option specifies that the source of the data is a channel, and
its associated argument is the handle of the channel containing the
data.</p></dd>
<dt><b class="option">-file</b> <i class="arg">path</i></dt>
<dd><p>This option specifies that the source of the data is a file, and its
associated argument is the path of the file containing the data.</p></dd>
<dt><b class="option">-variable</b> <i class="arg">varname</i></dt>
<dd><p>This option specifies that the source of the data is a string stored
in a variable, and its associated argument contains the name of the
variable in question. The variable is assumed to be global or
namespaced, anchored at the global namespace.</p></dd>
<dt><b class="option">-size</b> <i class="arg">int</i></dt>
<dd><p>This option specifies the size of the data transfer. It is optional
and defaults to -1. This value, and any other value less than zero
signals to transfer all the data from the source.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">command</i></dt>
<dd><p>This option, if specified, defines a command to be invoked for each
chunk of bytes transmitted, allowing the user to monitor the progress
of the transmission of the data. The callback is always invoked with
one additional argument, the number of bytes transmitted so far.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#data_source">data source</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/receiver.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
|
<div class='fossil-doc' data-title='transfer::receiver - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::receiver(n) 0.2 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::receiver - Data source</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
<li class="doctools_subsection"><a href="#subsection4">Options</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Secure connections</a></li>
<li class="doctools_section"><a href="#section4">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">transfer::data::destination <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::connect <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::receiver <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::receiver</b> <i class="arg">object</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">transfer::receiver</b> <b class="method">stream channel</b> <i class="arg">chan</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">transfer::receiver</b> <b class="method">stream file</b> <i class="arg">path</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">start</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">busy</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package pulls data destinations and connection setup together
into a combined object for the reception of information coming in over
a socket.
These objects understand all the options from objects created by the
packages <b class="package"><a href="ddest.html">transfer::data::destination</a></b> and
<b class="package"><a href="connect.html">transfer::connect</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::receiver</b> <i class="arg">object</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new receiver object with an associated Tcl
command whose name is <i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection2">Object command</a></span> and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#subsection4">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
<dt><a name="2"><b class="cmd">transfer::receiver</b> <b class="method">stream channel</b> <i class="arg">chan</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This method creates a fire-and-forget transfer for the data coming
from the source at host/port (details below) and writing to the
channel <i class="arg">chan</i>, starting at the current seek location. The channel
is configured to use binary translation and encoding for the transfer.
The channel is <em>not</em> closed when the transfer has completed. This
is left to the completion callback.</p>
<p>If both <i class="arg">host</i> and <i class="arg">port</i> are provided an <b class="const">active</b>
connection to the data source is made. If only a <i class="arg">port</i> is
specified (with <i class="arg">host</i> the empty string) then a <b class="const">passive</b>
connection is made instead, i.e. the receiver then waits for a
conneciton by the transmitter.</p>
<p>Any arguments after the port are treated as options and are used to
configure the internal receiver object.
See the section <span class="sectref"><a href="#subsection4">Options</a></span> for a list of the supported options
and their meaning.
<em>Note</em> however that the signature of the command prefix specified
for the <b class="option">-command</b> callback differs from the signature for the
same option of the receiver object.
This callback is only given the number of bytes and transfered, and
possibly an error message. No reference to the internally used
receiver object is made.</p>
<p>The result returned by the command is the empty string
if it was set to make an <i class="term"><a href="../../../../index.html#active">active</a></i> connection, and the port the
internal receiver object is listening on otherwise, i.e when it is
configured to connect <i class="term"><a href="../../../../index.html#passive">passive</a></i>ly.
See also the package <b class="package"><a href="connect.html">transfer::connect</a></b> and the description
of the method <b class="method">connect</b> for where this behaviour comes from.</p></dd>
<dt><a name="3"><b class="cmd">transfer::receiver</b> <b class="method">stream file</b> <i class="arg">path</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This method is like <b class="method">stream channel</b>, except that the
received data is written to the file <i class="arg">path</i>, replacing any prior
content.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::receiver</b> command have the
following general form:</p>
<dl class="doctools_definitions">
<dt><a name="4"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="5"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object. Doing so while a reception is on
progress will cause errors later on, when the reception completes
and tries to access the now missing data structures of the destroyed
object.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">start</b></a></dt>
<dd><p>This method initiates the data reception, setting up the connection
first and then copying the received information into the
destination.
The method will throw an error if a reception is already/still in
progress.
I.e. it is not possible to run two receptions in parallel, only in
sequence.
Errors will also be thrown if the configuration of the data
destination is invalid, or if no completion callback was specified.</p>
<p>The result returned by the method is the empty string
for an object configured to make an <i class="term"><a href="../../../../index.html#active">active</a></i> connection, and the port the
object is listening on otherwise, i.e when it is
configured to connect <i class="term"><a href="../../../../index.html#passive">passive</a></i>ly.
See also the package <b class="package"><a href="connect.html">transfer::connect</a></b> and the description
of the method <b class="method">connect</b> for where this behaviour comes from.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">busy</b></a></dt>
<dd><p>This method returns a boolean value telling us whether a reception
is in progress (<b class="const">True</b>), or not (<b class="const">False</b>).</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Options</a></h3>
<p>All receiver objects support the union of the options supported by
their connect and data destination components, plus one of their own.
See also the documentation for the packages
<b class="package"><a href="ddest.html">transfer::data::destination</a></b> and <b class="package"><a href="connect.html">transfer::connect</a></b>.</p>
<dl class="doctools_options">
<dt><b class="option">-command</b> <i class="arg">cmdprefix</i></dt>
<dd><p>This option specifies the command to invoke when the reception of
the information has been completed.
The arguments given to this command are the same as given to the
completion callback of the command <b class="cmd">transfer::copy::do</b> provided
by the package <b class="package"><a href="copyops.html">transfer::copy</a></b>.</p></dd>
<dt><b class="option">-mode</b> <i class="arg">mode</i></dt>
<dd><p>This option specifies the mode the object is in. It is optional and
defaults to <b class="const">active</b> mode. The two possible modes are:</p>
<dl class="doctools_definitions">
<dt><b class="const">active</b></dt>
<dd><p>In this mode the two options <b class="option">-host</b> and <b class="option">-port</b> are
relevant and specify the host and TCP port the object has to connect
to. The host is given by either name or IP address.</p></dd>
<dt><b class="const">passive</b></dt>
<dd><p>In this mode the option <b class="option">-host</b> has no relevance and is ignored
should it be configured.
The only option the object needs is <b class="option">-port</b>, and it specifies
the TCP port on which the listening socket is opened to await the
connection from the partner.</p></dd>
</dl></dd>
<dt><b class="option">-host</b> <i class="arg">hostname-or-ipaddr</i></dt>
<dd><p>This option specifies the host to connect to in <i class="term"><a href="../../../../index.html#active">active</a></i> mode,
either by name or ip-address. An object configured for <i class="term"><a href="../../../../index.html#passive">passive</a></i>
mode ignores this option.</p></dd>
<dt><b class="option">-port</b> <i class="arg">int</i></dt>
<dd><p>For <i class="term"><a href="../../../../index.html#active">active</a></i> mode this option specifies the port the object is
expected to connect to. For <i class="term"><a href="../../../../index.html#passive">passive</a></i> mode however it is the port
where the object creates the listening socket waiting for a
connection. It defaults to <b class="const">0</b>, which allows the OS to choose
the actual port to listen on.</p></dd>
<dt><b class="option">-socketcmd</b> <i class="arg">command</i></dt>
<dd><p>This option allows the user to specify which command to use to open a
socket. The default is to use the builtin <b class="cmd">::socket</b>. Any
compatible with that command is allowed.</p>
<p>The envisioned main use is the specfication of <b class="cmd">tls::socket</b>. I.e.
this option allows the creation of secure transfer channels, without
making this package explicitly dependent on the <b class="package"><a href="../../../../index.html#tls">tls</a></b> package.</p>
<p>See also section <span class="sectref"><a href="#section3">Secure connections</a></span>.</p></dd>
<dt><b class="option">-encoding</b> encodingname</dt>
<dd></dd>
<dt><b class="option">-eofchar</b> eofspec</dt>
<dd></dd>
<dt><b class="option">-translation</b> transspec</dt>
<dd><p>These options are the same as are recognized by the builtin command
<b class="cmd">fconfigure</b>. They provide the configuration to be set for the
channel between the two partners after it has been established, but
before the callback is invoked (See method <b class="method">connect</b>).</p></dd>
<dt><b class="option">-channel</b> <i class="arg">handle</i></dt>
<dd><p>This option specifies that the destination of the data is a channel,
and its associated argument is the handle of the channel to write the
received data to.</p></dd>
<dt><b class="option">-file</b> <i class="arg">path</i></dt>
<dd><p>This option specifies that the destination of the data is a file, and
its associated argument is the path of the file to write the received
data to.</p></dd>
<dt><b class="option">-variable</b> <i class="arg">varname</i></dt>
<dd><p>This option specifies that the destination of the data is a variable,
and its associated argument contains the name of the variable to write
the received data to. The variable is assumed to be global or
namespaced, anchored at the global namespace.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">command</i></dt>
<dd><p>This option, if specified, defines a command to be invoked for each
chunk of bytes received, allowing the user to monitor the progress of
the reception of the data. The callback is always invoked with one
additional argument, the number of bytes received so far.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Secure connections</a></h2>
<p>One way to secure connections made by objects of this package is to
require the package <b class="package"><a href="../../../../index.html#tls">tls</a></b> and then configure the option
<b class="option">-socketcmd</b> to force the use of command <b class="cmd">tls::socket</b> to
open the socket.</p>
<pre class="doctools_example">
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create a connector with secure socket setup,
transfer::receiver R -socketcmd tls::socket ...
...
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#data_destination">data destination</a>, <a href="../../../../index.html#receiver">receiver</a>, <a href="../../../../index.html#secure">secure</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/tqueue.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
|
<div class='fossil-doc' data-title='transfer::copy::queue - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::copy::queue(n) 0.1 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::copy::queue - Queued transfers</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">Use</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">struct::queue <span class="opt">?1.4?</span></b></li>
<li>package require <b class="pkgname">transfer::copy <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::copy::queue <span class="opt">?0.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::copy::queue</b> <i class="arg">objectName</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">busy</b></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">pending</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">put</b> <i class="arg">request</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects which serialize transfer requests for a
single channel by means of a fifo queue. Accumulated requests are
executed in order of entrance, with the first request reaching an idle
object starting the execution in general. New requests can be added
while the object is active and are defered until all requests entered
before them have been completed successfully.</p>
<p>When a request causes a transfer error execution stops and all
requests coming after it are not served. Currently this means that
their completion callbacks are never triggered at all.</p>
<p><em>NOTE</em>:
Not triggering the completion callbacks of the unserved
requests after an error stops the queue object is something I
am not fully sure that it makes sense. It forces the user of
the queue to remember the callbacks as well and run
them. Because otherwise everything in the system which depends
on getting a notification about the status of a request will
hang in the air. I am slowly convincing myself that it is more
sensible to trigger the relevant completion callbacks with an
error message about the queue abort, and 0 bytes transfered.</p>
<p>All transfer requests are of the form</p>
<pre class="doctools_example">
{type data options...}
</pre>
<p>where <i class="arg">type</i> is in {<b class="const">chan</b>, <b class="const">string</b>}, and <i class="arg">data</i>
specifies the information to transfer.
For <b class="const">chan</b> the data is the handle of the channel containing the
actual information to transfer, whereas for <b class="const">string</b> <i class="arg">data</i>
contains directly the information to transfer.
The <i class="arg">options</i> are a list of them and their values, and are the
same as are accepted by the low-level copy operations of the package
<b class="package"><a href="copyops.html">transfer::copy</a></b>.
Note how just prepending the request with <b class="cmd">transfer::copy::do</b> and
inserting a channel handle in between <i class="arg">data</i> and <i class="arg">options</i>
easily transforms it from a pure data structure into a command whose
evaluation will perform the request.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::copy::queue</b> <i class="arg">objectName</i> <i class="arg">outchannel</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new queue object for the management of the
channel <i class="arg">outchannel</i>, with an associated Tcl command whose name is
<i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection2">Object command</a></span> and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#section3">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::copy::queue</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="3"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object. Doing so while the object is busy
will cause errors later on, when the currently executed request
completes and tries to access the now missing data structures of the
destroyed object.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">busy</b></a></dt>
<dd><p>This method returns a boolean value telling us if the object is
currently serving a request (i.e. <i class="term">busy</i>, value <b class="const">True</b>), or
not (i.e. <i class="term"><a href="../../../../index.html#idle">idle</a></i>, value <b class="const">False</b>).</p></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">pending</b></a></dt>
<dd><p>This method returns the number of requests currently waiting in the
queue for their execution. A request currently served is not counted
as waiting.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">put</b> <i class="arg">request</i></a></dt>
<dd><p>This method enters the transfer <i class="arg">request</i> into the object's queue
of waiting requests.
If the object is <i class="term"><a href="../../../../index.html#idle">idle</a></i> it will become <i class="term">busy</i>, immediately
servicing the request. Otherwise servicing the new request will be
defered until all preceding requests have been served.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<p>The only option known is <b class="option">-on-status-change</b>. It is optional
and defaults to the empty list, disabling the reporting of status
changes. Otherwise its argument is a command prefix which is invoked
whenever the internal status of the object changed. The callback is
invoked with two additional arguments, the result of the methods
<b class="method">pending</b> and <b class="method">busy</b>, in this order. This allows any
user to easily know, for example, when the object has processed all
outstanding requests.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Use</a></h2>
<p>A possible application of this package and class is within a HTTP 1.1
server, managing the results waiting for transfer to the client.</p>
<p>It should be noted that in this application the system also needs an
additional data structure which keeps track of outstanding results as
they may come back in a different order than the requests from the
client, and releases them to the actual queue in the proper order.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#queue">queue</a>, <a href="../../../../index.html#transfer">transfer</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/transfer/transmitter.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
|
<div class='fossil-doc' data-title='transfer::transmitter - Data transfer facilities'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">transfer::transmitter(n) 0.2 tcllib "Data transfer facilities"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>transfer::transmitter - Data source</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Package commands</a></li>
<li class="doctools_subsection"><a href="#subsection2">Object command</a></li>
<li class="doctools_subsection"><a href="#subsection3">Object methods</a></li>
<li class="doctools_subsection"><a href="#subsection4">Options</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Secure connections</a></li>
<li class="doctools_section"><a href="#section4">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.0?</span></b></li>
<li>package require <b class="pkgname">transfer::copy <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::data::source <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::connect <span class="opt">?0.2?</span></b></li>
<li>package require <b class="pkgname">transfer::transmitter <span class="opt">?0.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">transfer::transmitter</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#2"><b class="cmd">transfer::transmitter</b> <b class="method">stream channel</b> <i class="arg">chan</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#3"><b class="cmd">transfer::transmitter</b> <b class="method">stream file</b> <i class="arg">path</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
<li><a href="#6"><i class="arg">objectName</i> <b class="method">start</b></a></li>
<li><a href="#7"><i class="arg">objectName</i> <b class="method">busy</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package pulls data sources and connection setup together into a
combined object for the transmission of information over a socket.
These objects understand all the options from objects created
by the packages <b class="package"><a href="dsource.html">transfer::data::source</a></b> and
<b class="package"><a href="connect.html">transfer::connect</a></b>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Package commands</a></h3>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">transfer::transmitter</b> <i class="arg">objectName</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p>This command creates a new transmitter object with an associated Tcl
command whose name is <i class="arg">objectName</i>.
This <i class="term"><a href="../../../../index.html#object">object</a></i> command is explained in full detail in the sections
<span class="sectref"><a href="#subsection2">Object command</a></span> and <span class="sectref"><a href="#subsection3">Object methods</a></span>. The set of
supported <i class="arg">options</i> is explained in section <span class="sectref"><a href="#subsection4">Options</a></span>.</p>
<p>The object command will be created under the current namespace if the
<i class="arg">objectName</i> is not fully qualified, and in the specified
namespace otherwise.
The fully qualified name of the object command is returned as the
result of the command.</p></dd>
<dt><a name="2"><b class="cmd">transfer::transmitter</b> <b class="method">stream channel</b> <i class="arg">chan</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This method creates a fire-and-forget transfer for the data contained
in the channel <i class="arg">chan</i>, starting at the current seek location. The
channel is configured to use binary translation and encoding for the
transfer.
The channel is automatically closed when the transfer has completed.</p>
<p>If both <i class="arg">host</i> and <i class="arg">port</i> are provided an <b class="const">active</b>
connection to the destination is made. If only a <i class="arg">port</i> is
specified (with <i class="arg">host</i> the empty string) then a <b class="const">passive</b>
connection is made instead.</p>
<p>Any arguments after the port are treated as options and are used to
configure the internal transmitter object.
See the section <span class="sectref"><a href="#subsection4">Options</a></span> for a list of the supported options
and their meaning.
<em>Note</em> however that the signature of the command prefix specified
for the <b class="option">-command</b> callback differs from the signature for the
same option of the transmitter object.
This callback is only given the number of bytes and transfered, and
possibly an error message. No reference to the internally used
transmitter object is made.</p>
<p>The result returned by the command is the empty string
if it was set to make an <i class="term"><a href="../../../../index.html#active">active</a></i> connection, and the port the
internal transmitter object is listening on otherwise, i.e when it is
configured to connect <i class="term"><a href="../../../../index.html#passive">passive</a></i>ly.
See also the package <b class="package"><a href="connect.html">transfer::connect</a></b> and the description
of the method <b class="method">connect</b> for where this behaviour comes from.</p></dd>
<dt><a name="3"><b class="cmd">transfer::transmitter</b> <b class="method">stream file</b> <i class="arg">path</i> <i class="arg">host</i> <i class="arg">port</i> <span class="opt">?<i class="arg">arg</i>...?</span></a></dt>
<dd><p>This method is like <b class="method">stream channel</b>, except that the data
contained in the file <i class="arg">path</i> is transfered.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Object command</a></h3>
<p>All objects created by the <b class="cmd">::transfer::transmitter</b> command have
the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="4"><i class="arg">objectName</i> <b class="method">method</b> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p>The method <b class="method">method</b> and its <i class="arg">arg</i>'uments determine the
exact behavior of the command.
See section <span class="sectref"><a href="#subsection3">Object methods</a></span> for the detailed
specifications.</p></dd>
</dl>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Object methods</a></h3>
<dl class="doctools_definitions">
<dt><a name="5"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>This method destroys the object. Doing so while a transmission is in
progress will cause errors later on, when the transmission completes
and tries to access the now missing data structures of the destroyed
object.</p></dd>
<dt><a name="6"><i class="arg">objectName</i> <b class="method">start</b></a></dt>
<dd><p>This method initiates the data transmission, setting up the connection
first and then copying the information.
The method will throw an error if a transmission is already/still in
progress.
I.e. it is not possible to run two transmissions in parallel on a
single object, only in sequence. Multiple transmitter objects are
needed to manage parallel transfers, one per transmission.
Errors will also be thrown if the configuration of the data source is
invalid, or if no completion callback was specified.</p>
<p>The result returned by the method is the empty string
for an object configured to make an <i class="term"><a href="../../../../index.html#active">active</a></i> connection, and the port the
object is listening on otherwise, i.e when it is
configured to connect <i class="term"><a href="../../../../index.html#passive">passive</a></i>ly.
See also the package <b class="package"><a href="connect.html">transfer::connect</a></b> and the description
of the method <b class="method">connect</b> for where this behaviour comes from.</p></dd>
<dt><a name="7"><i class="arg">objectName</i> <b class="method">busy</b></a></dt>
<dd><p>This method returns a boolean value telling us whether a transmission
is in progress (<b class="const">True</b>), or not (<b class="const">False</b>).</p></dd>
</dl>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Options</a></h3>
<p>All transmitter objects support the union of the options supported
by their connect and data source components, plus two of their own.
See also the documentation for the packages
<b class="package"><a href="dsource.html">transfer::data::source</a></b> and <b class="package"><a href="connect.html">transfer::connect</a></b>.</p>
<dl class="doctools_options">
<dt><b class="option">-blocksize</b> <i class="arg">int</i></dt>
<dd><p>This option specifies the size of the chunks to be transmitted in one
block. Usage is optional, its default value is <b class="const">1024</b>.</p></dd>
<dt><b class="option">-command</b> <i class="arg">cmdprefix</i></dt>
<dd><p>This option specifies the command to invoke when the transmission of
the information has been completed.
The arguments given to this command are the same as given to the
completion callback of the command <b class="cmd">transfer::copy::do</b> provided
by the package <b class="package"><a href="copyops.html">transfer::copy</a></b>.</p></dd>
<dt><b class="option">-mode</b> <i class="arg">mode</i></dt>
<dd><p>This option specifies the mode the object is in. It is optional and
defaults to <b class="const">active</b> mode. The two possible modes are:</p>
<dl class="doctools_definitions">
<dt><b class="const">active</b></dt>
<dd><p>In this mode the two options <b class="option">-host</b> and <b class="option">-port</b> are
relevant and specify the host and TCP port the object has to connect
to. The host is given by either name or IP address.</p></dd>
<dt><b class="const">passive</b></dt>
<dd><p>In this mode the option <b class="option">-host</b> has no relevance and is ignored
should it be configured.
The only option the object needs is <b class="option">-port</b>, and it specifies
the TCP port on which the listening socket is opened to await the
connection from the partner.</p></dd>
</dl></dd>
<dt><b class="option">-host</b> <i class="arg">hostname-or-ipaddr</i></dt>
<dd><p>This option specifies the host to connect to in <i class="term"><a href="../../../../index.html#active">active</a></i> mode,
either by name or ip-address. An object configured for <i class="term"><a href="../../../../index.html#passive">passive</a></i>
mode ignores this option.</p></dd>
<dt><b class="option">-port</b> <i class="arg">int</i></dt>
<dd><p>For <i class="term"><a href="../../../../index.html#active">active</a></i> mode this option specifies the port the object is
expected to connect to. For <i class="term"><a href="../../../../index.html#passive">passive</a></i> mode however it is the port
where the object creates the listening socket waiting for a
connection. It defaults to <b class="const">0</b>, which allows the OS to choose
the actual port to listen on.</p></dd>
<dt><b class="option">-socketcmd</b> <i class="arg">command</i></dt>
<dd><p>This option allows the user to specify which command to use to open a
socket. The default is to use the builtin <b class="cmd">::socket</b>. Any
compatible with that command is allowed.</p>
<p>The envisioned main use is the specfication of <b class="cmd">tls::socket</b>. I.e.
this option allows the creation of secure transfer channels, without
making this package explicitly dependent on the <b class="package"><a href="../../../../index.html#tls">tls</a></b> package.</p>
<p>See also section <span class="sectref"><a href="#section3">Secure connections</a></span>.</p></dd>
<dt><b class="option">-encoding</b> encodingname</dt>
<dd></dd>
<dt><b class="option">-eofchar</b> eofspec</dt>
<dd></dd>
<dt><b class="option">-translation</b> transspec</dt>
<dd><p>These options are the same as are recognized by the builtin command
<b class="cmd">fconfigure</b>. They provide the configuration to be set for the
channel between the two partners after it has been established, but
before the callback is invoked (See method <b class="method">connect</b>).</p></dd>
<dt><b class="option">-string</b> <i class="arg">text</i></dt>
<dd><p>This option specifies that the source of the data is an immediate
string, and its associated argument contains the string in question.</p></dd>
<dt><b class="option">-channel</b> <i class="arg">handle</i></dt>
<dd><p>This option specifies that the source of the data is a channel, and
its associated argument is the handle of the channel containing the
data.</p></dd>
<dt><b class="option">-file</b> <i class="arg">path</i></dt>
<dd><p>This option specifies that the source of the data is a file, and its
associated argument is the path of the file containing the data.</p></dd>
<dt><b class="option">-variable</b> <i class="arg">varname</i></dt>
<dd><p>This option specifies that the source of the data is a string stored
in a variable, and its associated argument contains the name of the
variable in question. The variable is assumed to be global or
namespaced, anchored at the global namespace.</p></dd>
<dt><b class="option">-size</b> <i class="arg">int</i></dt>
<dd><p>This option specifies the size of the data transfer. It is optional
and defaults to -1. This value, and any other value less than zero
signals to transfer all the data from the source.</p></dd>
<dt><b class="option">-progress</b> <i class="arg">command</i></dt>
<dd><p>This option, if specified, defines a command to be invoked for each
chunk of bytes transmitted, allowing the user to monitor the progress
of the transmission of the data. The callback is always invoked with
one additional argument, the number of bytes transmitted so far.</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Secure connections</a></h2>
<p>One way to secure connections made by objects of this package is to
require the package <b class="package"><a href="../../../../index.html#tls">tls</a></b> and then configure the option
<b class="option">-socketcmd</b> to force the use of command <b class="cmd">tls::socket</b> to
open the socket.</p>
<pre class="doctools_example">
# Load and initialize tls
package require tls
tls::init -cafile /path/to/ca/cert -keyfile ...
# Create a connector with secure socket setup,
transfer::transmitter T -socketcmd tls::socket ...
...
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>transfer</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel">channel</a>, <a href="../../../../index.html#copy">copy</a>, <a href="../../../../index.html#data_source">data source</a>, <a href="../../../../index.html#secure">secure</a>, <a href="../../../../index.html#ssl">ssl</a>, <a href="../../../../index.html#tls">tls</a>, <a href="../../../../index.html#transfer">transfer</a>, <a href="../../../../index.html#transmitter">transmitter</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Transfer module</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2006-2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/treeql/treeql.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
|
<div class='fossil-doc' data-title='treeql - Tree Query Language'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">treeql(n) 1.3.1 tcllib "Tree Query Language"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>treeql - Query tree objects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">TreeQL CLASS API</a></li>
<li class="doctools_subsection"><a href="#subsection2">TreeQL OBJECT API</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">The Tree Query Language</a>
<ul>
<li class="doctools_subsection"><a href="#subsection3">TreeQL Concepts</a></li>
<li class="doctools_subsection"><a href="#subsection4">Structural generators</a></li>
<li class="doctools_subsection"><a href="#subsection5">Attribute Filters</a></li>
<li class="doctools_subsection"><a href="#subsection6">Attribute Mutators</a></li>
<li class="doctools_subsection"><a href="#subsection7">Attribute String Accessors</a></li>
<li class="doctools_subsection"><a href="#subsection8">Sub-queries</a></li>
<li class="doctools_subsection"><a href="#subsection9">Node Set Operators</a></li>
<li class="doctools_subsection"><a href="#subsection10">Node Set Iterators</a></li>
<li class="doctools_subsection"><a href="#subsection11">Typed node support</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Examples</a></li>
<li class="doctools_section"><a href="#section5">References</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">struct::list</b></li>
<li>package require <b class="pkgname">struct::set</b></li>
<li>package require <b class="pkgname">treeql <span class="opt">?1.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">treeql</b> <i class="arg">objectname</i> <b class="option">-tree</b> <i class="arg">tree</i> <span class="opt">?<b class="option">-query</b> <i class="arg">query</i>?</span> <span class="opt">?<b class="option">-nodes</b> <i class="arg">nodes</i>?</span> <span class="opt">?<i class="arg">args</i>...?</span></a></li>
<li><a href="#2"><i class="arg">qo</i> <b class="method">query</b> <i class="arg">args</i>...</a></li>
<li><a href="#3"><i class="arg">qo</i> <b class="method">result</b></a></li>
<li><a href="#4"><i class="arg">qo</i> <b class="method">discard</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects which can be used to query and transform
tree objects following the API of tree objects created by the package
<b class="package"><a href="../struct/struct_tree.html">struct::tree</a></b>.</p>
<p>The tree query and manipulation language used here, TreeQL, is
inspired by Cost (See section <span class="sectref"><a href="#section5">References</a></span> for more
information).</p>
<p><b class="package">treeql</b>, the package, is a fairly thin query facility over
tree-structured data types. It implements an ordered set of nodes
(really a list) which are generated and filtered through the
application of TreeQL operators to each node in turn.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">TreeQL CLASS API</a></h3>
<p>The command <b class="cmd">treeql</b> is a <b class="package"><a href="../snit/snit.html">snit</a></b>::type which implements
the Treeql Query Language. This means that it follows the API for
class commands as specified by the package <b class="package"><a href="../snit/snit.html">snit</a></b>.
Its general syntax is</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">treeql</b> <i class="arg">objectname</i> <b class="option">-tree</b> <i class="arg">tree</i> <span class="opt">?<b class="option">-query</b> <i class="arg">query</i>?</span> <span class="opt">?<b class="option">-nodes</b> <i class="arg">nodes</i>?</span> <span class="opt">?<i class="arg">args</i>...?</span></a></dt>
<dd><p>The command creates a new tree query object and returns the fully
qualified name of the object command as its result.
The API the returned command is following is described in the section
<span class="sectref"><a href="#subsection2">TreeQL OBJECT API</a></span></p>
<p>Each query object is associated with a single <i class="arg">tree</i> object. This
is the object all queries will be run against.</p>
<p>If the option <b class="option">-nodes</b> was specified then its argument is
treated as a list of nodes. This list is used to initialize the node
set. It defaults to the empty list.</p>
<p>If the option <b class="option">-query</b> was specified then its argument will be
interpreted as an object, the <i class="term">parent query</i> of this query. It
defaults to the object itself. All queries will be interpreted in the
environment of this object.</p>
<p>Any arguments coming after the options are treated as a query and run
immediately, after the <i class="term">node set</i> has been initialized. This
uses the same syntax for the query as the method <b class="method">query</b>.</p>
<p>The operations of the TreeQL available for this are explained in the
section about <span class="sectref"><a href="#section3">The Tree Query Language</a></span>. This section also
explains the term <i class="term">node set</i> used above.</p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">TreeQL OBJECT API</a></h3>
<p>As <b class="package">treeql</b> has been implemented in <b class="package"><a href="../snit/snit.html">snit</a></b> all the
standard methods of <b class="package"><a href="../snit/snit.html">snit</a></b>-based classes are available to the
user and therefore not listed here. Please read the documentation for
<b class="package"><a href="../snit/snit.html">snit</a></b> for what they are and what functionality they provide</p>
<p>The methods provided by the package <b class="package">treeql</b> itself are listed
and explained below.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">qo</i> <b class="method">query</b> <i class="arg">args</i>...</a></dt>
<dd><p>This method interprets its arguments as a series of TreeQL operators
and interpretes them from the left to right (i.e. first to last).
Note that the first operator uses the <i class="term">node set</i> currently
known to the object to perform its actions.
In other words, the <i class="term">node set</i> is <em>not</em> cleared, or
modified in other ways, before the query is run. This allows the user
to run several queries one after the other and have each use the
results of the last. Any initialization has to be done by any query
itself, using TreeQL operators.
The result of the method is the <i class="term">node set</i> after the last
operator of the query has been executed.</p>
<p><em>Note</em> that uncaught errors will leave the <i class="term">node set</i> of
the object in an intermediate state, per the TreeQL operators which
were executed successfully before the error occurred.</p>
<p>The above means in detail that:</p>
<ol class="doctools_enumerated">
<li><p>The first argument is interpreted as the name of a query operator, the
number of arguments required by that operator is then determined, and
taken from the immediately following arguments.</p>
<p>Because of this operators cannot have optional arguments, all
arguments have to be present as defined. Failure to do this will, at
least, confuse the query interpreter, but more likely cause errors.</p></li>
<li><p>The operator is applied to the current node set, yielding a new node
set, and/or manipulating the tree object the query object is connected
to.</p></li>
<li><p>The arguments used (i.e. operator name and arguments) are removed from
the list of method arguments, and then the whole process is repeated
from step [1], until the list of arguments is empty or an error
occurred.</p></li>
</ol>
<pre class="doctools_example">
# q is the query object.
q query root children get data
# The above query
# - Resets the node set to the root node - root
# - Adds the children of root to the set - children
# - Replaces the node set with the - get data
# values for the attribute 'data',
# for all nodes in the set which
# have such an attribute.
# - And returns this information.
# Below we can see the same query, but rewritten
# to show the structure as it is seen by the query
# interpreter.
q query \\
root \\
children \\
get data
</pre>
<p>The operators of the TreeQL language available for this are explained
in the section about <span class="sectref"><a href="#section3">The Tree Query Language</a></span>. This section
also explains the term <i class="term">node set</i> used above.</p></dd>
<dt><a name="3"><i class="arg">qo</i> <b class="method">result</b></a></dt>
<dd><p>This method returns a list containing the current node set.</p></dd>
<dt><a name="4"><i class="arg">qo</i> <b class="method">discard</b></a></dt>
<dd><p>This method returns the current node set (like method
<b class="method">result</b>), but also destroys the query object (<i class="arg">qo</i>).
This is useful when constructing and using sub-queries (%AUTO% objects
immediately destroyed after use).</p></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">The Tree Query Language</a></h2>
<p>This and the following sections specify the Tree Query Language used
by the query objects of this package in detail.</p>
<p>First we explain the general concepts underneath the language which
are required to comprehend it. This is followed by the specifications
for all the available query operators. They fall into eight
categories, and each category has its own section.</p>
<ol class="doctools_enumerated">
<li><p><span class="sectref"><a href="#subsection3">TreeQL Concepts</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection4">Structural generators</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection5">Attribute Filters</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection6">Attribute Mutators</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection7">Attribute String Accessors</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection8">Sub-queries</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection9">Node Set Operators</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection10">Node Set Iterators</a></span></p></li>
<li><p><span class="sectref"><a href="#subsection11">Typed node support</a></span></p></li>
</ol>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">TreeQL Concepts</a></h3>
<p>The main concept which has to be understood is that of the
<i class="term">node set</i>.
Each query object maintains exactly one such <i class="term">node set</i>, and
essentially all operators use it and input argument and for their
result.
This structure simply contains the handles of all nodes which are
currently of interest to the query object.
To name it a <i class="term"><a href="../../../../index.html#set">set</a></i> is a bit of a misnomer, because</p>
<ol class="doctools_enumerated">
<li><p>A node (handle) can occur in the structure more than once, and</p></li>
<li><p>the order of nodes in the structure is important as well.
Whenever an operator processes all nodes in the node set it will do so
in the order they occur in the structure.</p></li>
</ol>
<p>Regarding the possible multiple occurrence of a node, consider a node
set containing two nodes A and B, both having node P as their
immediate parent. Application of the TreeQL operator "parent" will
then add P to the new node set twice, once per node it was parent
of. I.e. the new node set will then be {P P}.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Structural generators</a></h3>
<p>All tree-structural operators locate nodes in the tree based on a
structural relation ship to the nodes currently in the set and then
replace the current node set with the set of nodes found
Nodes which fulfill such a relationship multiple times are added to
the result as often as they fulfill the relationship.</p>
<p>It is important to note that the found nodes are collected in a
separate storage area while processing the node set, and are added to
(or replacing) the current node set only after the current node set
has been processed completely.
In other words, the new nodes are <em>not</em> processed by the operator
as well and do not affect the iteration.</p>
<p>When describing an operator the variable <b class="variable">N</b> will be used to refer
to any node in the node set.</p>
<dl class="doctools_definitions">
<dt><b class="method">ancestors</b></dt>
<dd><p>Replaces the current node set with the ancestors for all nodes <b class="variable">N</b>
in the node set, should <b class="variable">N</b> have a parent. In other words, nodes
without a parent do not contribute to the new node set. In other
words, uses all nodes on the path from node <b class="variable">N</b> to root, in this
order (root last), for all nodes <b class="variable">N</b> in the node set. This
includes the root, but not the node itself.</p></dd>
<dt><b class="method">rootpath</b></dt>
<dd><p>Replaces the current node set with the ancestors for all nodes <b class="variable">N</b>
in the node set, should <b class="variable">N</b> have a parent. In other words, nodes
without a parent do not contribute to the new node set.
In contrast to the operator <b class="method">ancestors</b> the nodes are added in
reverse order however, i.e. the root node first.</p></dd>
<dt><b class="method">parent</b></dt>
<dd><p>Replaces the current node set with the parent of node <b class="variable">N</b>, for all
nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have a parent. In other
words, nodes without a parent do not contribute to the new node set.</p></dd>
<dt><b class="method">children</b></dt>
<dd><p>Replaces the current node set with the immediate children of node
<b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have
children. In other words, nodes without children do not contribute to
the new node set.</p></dd>
<dt><b class="method">left</b></dt>
<dd><p>Replaces the current node set with the previous/left sibling for all
nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have siblings to the
left. In other words, nodes without left siblings do not contribute to
the new node set.</p></dd>
<dt><b class="method">right</b></dt>
<dd><p>Replaces the current node set with the next/right sibling for all
nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have siblings to the
right. In other words, nodes without right siblings do not contribute
to the new node set.</p></dd>
<dt><b class="method">prev</b></dt>
<dd><p>Replaces the current node set with all previous/left siblings of node
<b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have
siblings to the left. In other words, nodes without left siblings are
ignored. The left sibling adjacent to the node is added first, and the
leftmost sibling last (reverse tree order).</p></dd>
<dt><b class="method">esib</b></dt>
<dd><p>Replaces the current node set with all previous/left siblings of node
<b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have
siblings to the left. In other words, nodes without left siblings are
ignored. The leftmost sibling is added first, and the left sibling
adjacent to the node last (tree order).</p>
<p>The method name is a shorthand for <i class="term">Earlier SIBling</i>.</p></dd>
<dt><b class="method">next</b></dt>
<dd><p>Replaces the current node set with all next/right siblings of node
<b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have
siblings to the right. In other words, nodes without right siblings do
not contribute to the new node set. The right sibling adjacent to the
node is added first, and the rightmost sibling last (tree order).</p></dd>
<dt><b class="method">root</b></dt>
<dd><p>Replaces the current node set with a node set containing a single
node, the root of the tree.</p></dd>
<dt><b class="method">tree</b></dt>
<dd><p>Replaces the current node set with a node set containing all nodes
found in the tree. The nodes are added in pre-order (parent first,
then children, the latter from left to right, first to last).</p></dd>
<dt><b class="method">descendants</b></dt>
<dd><p>Replaces the current node set with the nodes in all subtrees rooted at
node <b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b>
have children. In other words, nodes without children do not
contribute to the new node set.</p>
<p>This is like the operator <b class="method">children</b>, but covers the children
of children as well, i.e. all the <i class="term">proper descendants</i>. "Rooted
at <b class="variable">N</b>" means that <b class="variable">N</b> itself is not added to the new set,
which is also implied by <i class="term">proper descendants</i>.</p></dd>
<dt><b class="method">subtree</b></dt>
<dd><p>Like operator <b class="method">descendants</b>, but includes the node <b class="variable">N</b>. In
other words:</p>
<p>Replaces the current node set with the nodes of the subtree of node
<b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node set, should <b class="variable">N</b> have
children. In other words, nodes without children do not contribute to
the new node set. I.e this is like the operator <b class="method">children</b>, but
covers the children of children, etc. as well. "Of <b class="variable">N</b>" means that
<b class="variable">N</b> itself is added to the new set.</p></dd>
<dt><b class="method">forward</b></dt>
<dd><p>Replaces the current node set with the nodes in the subtrees rooted at
the right siblings of node <b class="variable">N</b>, for all nodes <b class="variable">N</b> in the node
set, should <b class="variable">N</b> have right siblings, and they children. In other
words, nodes without right siblings, and them without children are
ignored.</p>
<p>This is equivalent to the operator sequence</p>
<pre class="doctools_example">next descendants</pre>
</dd>
<dt><b class="method">later</b></dt>
<dd><p>This is an alias for the operator <b class="method">forward</b>.</p></dd>
<dt><b class="method">backward</b></dt>
<dd><p>Replaces the current node set with the nodes in the flattened previous
subtrees, in reverse tree order.</p>
<p>This is nearly equivalent to the operator sequence</p>
<pre class="doctools_example">prev descendants</pre>
<p>The only difference is that this uses the nodes in reverse order.</p></dd>
<dt><b class="method">earlier</b></dt>
<dd><p>Replaces the current node set with the nodes in the flattened previous
subtrees, in tree order.</p>
<p>This is equivalent to the operator sequence</p>
<pre class="doctools_example">prev subtree</pre>
</dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Attribute Filters</a></h3>
<p>These operators filter the node set by reference to attributes of
nodes and their properties. Filter means that all nodes not fulfilling
the criteria are removed from the node set. In other words, the node
set is replaced by the set of nodes fulfilling the filter criteria.</p>
<dl class="doctools_definitions">
<dt><b class="method">hasatt</b> <i class="arg">attr</i></dt>
<dd><p>Reduces the node set to nodes which have an attribute named
<i class="arg">attr</i>.</p></dd>
<dt><b class="method">withatt</b> <i class="arg">attr</i> <i class="arg">value</i></dt>
<dd><p>Reduces the node set to nodes which have an attribute named
<i class="arg">attr</i>, and where the value of that attribute is equal to
<i class="arg">value</i> (The "==" operator is <b class="cmd">string equal -nocase</b>).</p></dd>
<dt><b class="method">withatt!</b> <i class="arg">attr</i> <i class="arg">val</i></dt>
<dd><p>This is the same as <b class="method">withatt</b>, but all nodes in the node set
have to have the attribute, and the "==" operator is
<b class="cmd">string equal</b>, i.e. no <b class="option">-nocase</b>.
The operator will fail with an error if they don't have the attribute.</p></dd>
<dt><b class="method">attof</b> <i class="arg">attr</i> <i class="arg">vals</i></dt>
<dd><p>Reduces the node set to nodes which which have an attribute named
<i class="arg">attr</i> and where the value of that attribute is contained in the
list <i class="arg">vals</i> of legal values. The contained-in operator used here
does glob matching (using the attribute value as pattern) and ignores
the case of the attribute value, <em>but not</em> for the elements of
<i class="arg">vals</i>.</p></dd>
<dt><b class="method">attmatch</b> <i class="arg">attr</i> <i class="arg">match</i></dt>
<dd><p>Same as <b class="method">withatt</b>, but <b class="cmd">string match</b> is used as the "=="
operator, and <i class="arg">match</i> is the pattern checked for.</p>
<p><em>Note</em> that <i class="arg">match</i> is a interpreted as a partial argument
<em>list</em> for <b class="cmd">string match</b>. This means that it is
interpreted as a list containing the pattern, and the pattern element
can be preceded by options understand by <b class="cmd">string match</b>, like
<b class="option">-nocase</b>.
This is especially important should the pattern contain spaces. It has
to be wrapped into a list for correct interpretation by this operator</p></dd>
</dl>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Attribute Mutators</a></h3>
<p>These operators change node attributes within the underlying tree. In
other words, all these operators have <i class="term">side effects</i>.</p>
<dl class="doctools_definitions">
<dt><b class="method">set</b> <i class="arg">attr</i> <i class="arg">val</i></dt>
<dd><p>Sets the attribute <i class="arg">attr</i> to the value <i class="arg">val</i>, for all nodes
<b class="variable">N</b> in the node set.
The operator will fail if a node does not have an attribute named
<i class="arg">attr</i>. The tree will be left in a partially modified state.</p></dd>
<dt><b class="method">unset</b> <i class="arg">attr</i></dt>
<dd><p>Unsets the attribute <i class="arg">attr</i>, for all nodes <b class="variable">N</b> in the node
set.
The operator will fail if a node does not have an attribute named
<i class="arg">attr</i>. The tree will be left in a partially modified state.</p></dd>
</dl>
</div>
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Attribute String Accessors</a></h3>
<p>These operators retrieve the values of node attributes from the
underlying tree. The collected results are stored in the node set, but
are not actually nodes.</p>
<p>In other words, they redefine the semantics of the node set stored by
the query object to contain non-node data after their completion.</p>
<p>The query interpreter will terminate after it has finished processing
one of these operators, silently discarding any later query elements.
It also means that our talk about maintenance of a node set is not
quite true. It is a node set while the interpreter is processing
commands, but can be left as an attribute value set at the end of
query processing.</p>
<dl class="doctools_definitions">
<dt><b class="method">string</b> <i class="arg">op</i> <i class="arg">attr</i></dt>
<dd><p>Applies the string operator <i class="arg">op</i> to the attribute named
<i class="arg">attr</i>, for all nodes <b class="variable">N</b> in the node set, collects the
results of that application and places them into the node set.</p>
<p>The operator will fail if a node does not have an attribute named
<i class="arg">attr</i>.</p>
<p>The argument <i class="arg">op</i> is interpreted as partial argument list for the
builtin command <b class="cmd"><a href="../../../../index.html#string">string</a></b>. Its first word has to be any of the
sub-commands understood by <b class="cmd"><a href="../../../../index.html#string">string</a></b>. This has to be followed by
all arguments required for the subcommand, except the last. that last
argument is supplied by the attribute value.</p></dd>
<dt><b class="method">get</b> <i class="arg">pattern</i></dt>
<dd><p>For all nodes <b class="variable">N</b> in the node set it determines all their
attributes with names matching the glob <i class="arg">pattern</i>, then the values
of these attributes, at last it replaces the node set with the list of
these attribute values.</p></dd>
<dt><b class="method">attlist</b></dt>
<dd><p>This is a convenience definition for the operator
<b class="method">getvals *</b>. In other words, it replaces the node set with a
list of the attribute values for all attributes for all nodes <b class="variable">N</b>
in the node set.</p></dd>
<dt><b class="method">attrs</b> <i class="arg">glob</i></dt>
<dd><p>Replaces the current node set with a list of attribute lists, one
attribute list per for all nodes <b class="variable">N</b> in the node set.</p></dd>
<dt><b class="method">attval</b> <i class="arg">attname</i></dt>
<dd><p>Reduces the current node set with the operator <b class="method">hasatt</b>, and
then replaces it with a list containing the values of the attribute
named <i class="arg">attname</i> for all nodes <b class="variable">N</b> in the node set.</p></dd>
</dl>
</div>
<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Sub-queries</a></h3>
<p>Sub-queries yield node sets which are then used to augment, reduce or
replace the current node set.</p>
<dl class="doctools_definitions">
<dt><b class="method">andq</b> <i class="arg">query</i></dt>
<dd><p>Replaces the node set with the set-intersection of the node set
generated by the sub-query <i class="arg">query</i> and itself.</p>
<p>The execution of the sub-query uses the current node set as its own
initial node set.</p></dd>
<dt><b class="method">orq</b> <i class="arg">query</i></dt>
<dd><p>Replaces the node set with the set-union of the node set generated by
the sub-query <i class="arg">query</i> and itself. Duplicate nodes are removed.</p>
<p>The execution of the sub-query uses the current node set as its own
initial node set.</p></dd>
<dt><b class="method">notq</b> <i class="arg">query</i></dt>
<dd><p>Replaces the node set with the set of nodes generated by the sub-query
<i class="arg">query</i> which are also not in the current node set. In other word
the set difference of itself and the node set generated by the
sub-query.</p>
<p>The execution of the sub-query uses the current node set as its own
initial node set.</p></dd>
</dl>
</div>
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Node Set Operators</a></h3>
<p>These operators change the node set directly, without referring to the
tree.</p>
<dl class="doctools_definitions">
<dt><b class="method">unique</b></dt>
<dd><p>Removes duplicate nodes from the node set, preserving order. In other
words, the earliest occurrence of a node handle is preserved, every
other occurrence is removed.</p></dd>
<dt><b class="method">select</b></dt>
<dd><p>Replaces the current node set with a node set containing only the
first node from the current node set</p></dd>
<dt><b class="method">transform</b> <i class="arg">query</i> <i class="arg">var</i> <i class="arg">body</i></dt>
<dd><p>First it interprets the sub-query <i class="arg">query</i>, using the current node
set as its initial node set.
Then it iterates over the result of that query, binding the handle of
each node to the variable named in <i class="arg">var</i>, and executing the script
<i class="arg">body</i>.
The collected results of these executions is made the new node set,
replacing the current one.</p>
<p>The script <i class="arg">body</i> is executed in the context of the caller.</p></dd>
<dt><b class="method">map</b> <i class="arg">var</i> <i class="arg">body</i></dt>
<dd><p>Iterates over the current node set, binding the handle of each node to
the variable named in <i class="arg">var</i>, and executing the script <i class="arg">body</i>.
The collected results of these executions is made the new node set,
replacing the current one.</p>
<p>The script <i class="arg">body</i> is executed in the context of the caller.</p></dd>
<dt><b class="method">quote</b> <i class="arg">val</i></dt>
<dd><p>Appends the literal value <i class="arg">val</i> to the current node set.</p></dd>
<dt><b class="method">replace</b> <i class="arg">val</i></dt>
<dd><p>Replaces the current node set with the literal list value <i class="arg">val</i>.</p></dd>
</dl>
</div>
<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Node Set Iterators</a></h3>
<dl class="doctools_definitions">
<dt><b class="method">foreach</b> <i class="arg">query</i> <i class="arg">var</i> <i class="arg">body</i></dt>
<dd><p>Interprets the sub-query <i class="arg">query</i>, then performs the equivalent of
operator <b class="method">over</b> on the nodes in the node set created by that
query. The current node set is not changed, except through side
effects from the script <i class="arg">body</i>.</p>
<p>The script <i class="arg">body</i> is executed in the context of the caller.</p></dd>
<dt><b class="method">with</b> <i class="arg">query</i> <i class="arg">body</i></dt>
<dd><p>Interprets the <i class="arg">query</i>, then runs the script <i class="arg">body</i> on the
node set generated by the query. At last it restores the current node
set as it was before the execution of the query.</p>
<p>The script <i class="arg">body</i> is executed in the context of the caller.</p></dd>
<dt><b class="method">over</b> <i class="arg">var</i> <i class="arg">body</i></dt>
<dd><p>Executes the script <i class="arg">body</i> for each node in the node set, with the
variable named by <i class="arg">var</i> bound to the name of the current node.
The script <i class="arg">body</i> is executed in the context of the caller.</p>
<p>This is like the builtin <b class="cmd"><a href="../../../../index.html#foreach">foreach</a></b>, with the node set as the
source of the list to iterate over.</p>
<p>The results of executing the <i class="arg">body</i> are ignored.</p></dd>
<dt><b class="method">delete</b></dt>
<dd><p>Deletes all the nodes contained in the current node set from the tree.</p></dd>
</dl>
</div>
<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Typed node support</a></h3>
<p>These filters and accessors assume the existence of an attribute
called <b class="const">@type</b>, and are short-hand forms useful for cost-like
tree query, html tree editing, and so on.</p>
<dl class="doctools_definitions">
<dt><b class="method">nodetype</b></dt>
<dd><p>Returns the node type of nodes.
Attribute string accessor. This is equivalent to</p>
<pre class="doctools_example">get @type</pre>
</dd>
<dt><b class="method">oftype</b> <i class="arg">t</i></dt>
<dd><p>Reduces the node set to nodes whose type is equal to <i class="arg">t</i>, with
letter case ignored.</p></dd>
<dt><b class="method">nottype</b> <i class="arg">t</i></dt>
<dd><p>Reduces the node set to nodes whose type is not equal to <i class="arg">t</i>, with
letter case ignored.</p></dd>
<dt><b class="method">oftypes</b> <i class="arg">attrs</i></dt>
<dd><p>Reduces set to nodes whose @type is an element in the list <i class="arg">attrs</i>
of types. The value of @type is used as a glob pattern, and letter
case is relevant.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Examples</a></h2>
<p>... TODO ...</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">References</a></h2>
<ol class="doctools_enumerated">
<li><p><a href="http://wiki.tcl.tk/COST">COST</a> on the Tcler's Wiki.</p></li>
<li><p><a href="http://wiki.tcl.tk/treeql">TreeQL</a> on the Tcler's Wiki. Discuss
this package there.</p></li>
</ol>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>treeql</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cost">Cost</a>, <a href="../../../../index.html#dom">DOM</a>, <a href="../../../../index.html#treeql">TreeQL</a>, <a href="../../../../index.html#xpath">XPath</a>, <a href="../../../../index.html#xslt">XSLT</a>, <a href="../../../../index.html#structured_queries">structured queries</a>, <a href="../../../../index.html#tree">tree</a>, <a href="../../../../index.html#tree_query_language">tree query language</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Data structures</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004 Colin McCormack <[email protected]><br>
Copyright © 2004 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/try/tcllib_throw.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<div class='fossil-doc' data-title='throw - Forward compatibility implementation of [throw]'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">throw(n) 1 tcllib "Forward compatibility implementation of [throw]"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>throw - throw - Throw an error exception with a message</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">throw <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::throw</b> <i class="arg">error_code</i> <i class="arg">error_message</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a forward-compatibility implementation of Tcl
8.6's throw command (TIP 329), for Tcl 8.5. The code was
directly pulled from Tcl 8.6 revision ?, when try/finally was
implemented as Tcl procedure instead of in C.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::throw</b> <i class="arg">error_code</i> <i class="arg">error_message</i></a></dt>
<dd><p>throw is merely a reordering of the arguments of the error command. It throws an error with the indicated
error code and error message.</p></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<pre class="doctools_example">
<b class="cmd">throw</b> {MYERROR CODE} "My error message"
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>try</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>error(n)</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#error">error</a>, <a href="../../../../index.html#return">return</a>, <a href="../../../../index.html#throw">throw</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2015 Miguel Martínez López, BSD licensed</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/try/tcllib_try.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
<div class='fossil-doc' data-title='try - Forward compatibility implementation of [try]'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">try(n) 1 tcllib "Forward compatibility implementation of [try]"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>try - try - Trap and process errors and exceptions</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">try <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::try</b> <i class="arg">body</i> <span class="opt">?<i class="arg">handler...</i>?</span> <span class="opt">?<b class="method">finally</b> <i class="arg">script</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a forward-compatibility implementation of Tcl
8.6's try/finally command (TIP 329), for Tcl 8.5. The code was
directly pulled from Tcl 8.6 revision ?, when try/finally was
implemented as Tcl procedure instead of in C.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::try</b> <i class="arg">body</i> <span class="opt">?<i class="arg">handler...</i>?</span> <span class="opt">?<b class="method">finally</b> <i class="arg">script</i>?</span></a></dt>
<dd><p>This command executes the script <i class="arg">body</i> and, depending on what the
outcome of that script is (normal exit, error, or some other
exceptional result), runs a handler script to deal with the case. Once
that has all happened, if the <b class="method">finally</b> clause is present, the
<i class="arg">script</i> it includes will be run and the result of the handler (or
the <i class="arg">body</i> if no handler matched) is allowed to continue to
propagate. Note that the <b class="method">finally</b> clause is processed even if
an error occurs and irrespective of which, if any, <i class="arg">handler</i> is
used.</p>
<p>The <i class="arg">handler</i> clauses are each expressed as several words,
and must have one of the following forms:</p>
<dl class="doctools_definitions">
<dt><b class="method">on</b> <i class="arg">code variableList script</i></dt>
<dd><p>This clause matches if the evaluation of <i class="arg">body</i> completed with the
exception code <i class="arg">code</i>. The <i class="arg">code</i> may be expressed as an
integer or one of the following literal words:
<b class="const">ok</b>, <b class="const">error</b>, <b class="const">return</b>, <b class="const">break</b>, or
<b class="const">continue</b>. Those literals correspond to the integers 0 through
4 respectively.</p></dd>
<dt><b class="method">trap</b> <i class="arg">pattern variableList script</i></dt>
<dd><p>This clause matches if the evaluation of <i class="arg">body</i> resulted in an
error and the prefix of the <b class="option">-errorcode</b> from the interpreter's
status dictionary is equal to the <i class="arg">pattern</i>. The number of prefix
words taken from the <b class="option">-errorcode</b> is equal to the list-length
of <i class="arg">pattern</i>, and inter-word spaces are normalized in both the
<b class="option">-errorcode</b> and <i class="arg">pattern</i> before comparison.</p>
<p>The <i class="arg">variableList</i> word in each <i class="arg">handler</i> is always
interpreted as a list of variable names. If the first word of the list
is present and non-empty, it names a variable into which the result of
the evaluation of <i class="arg">body</i> (from the main <b class="cmd">try</b>) will be placed;
this will contain the human-readable form of any errors. If the second
word of the list is present and non-empty, it names a variable into
which the options dictionary of the interpreter at the moment of
completion of execution of <i class="arg">body</i> will be placed.</p>
<p>The <i class="arg">script</i> word of each <i class="arg">handler</i> is also always
interpreted the same: as a Tcl script to evaluate if the clause is
matched. If <i class="arg">script</i> is a literal <b class="const">-</b> and the <i class="arg">handler</i>
is not the last one, the <i class="arg">script</i> of the following <i class="arg">handler</i>
is invoked instead (just like with the <b class="cmd">switch</b> command).</p>
<p>Note that <i class="arg">handler</i> clauses are matched against in order,
and that the first matching one is always selected.
At most one <i class="arg">handler</i> clause will selected.
As a consequence, an <b class="method">on error</b> will mask any subsequent
<b class="method">trap</b> in the <b class="cmd">try</b>. Also note that <b class="method">on error</b> is
equivalent to <b class="method">trap {}</b>.</p>
<p>If an exception (i.e. any non-<b class="const">ok</b> result) occurs during
the evaluation of either the <i class="arg">handler</i> or the <b class="method">finally</b>
clause, the original exception's status dictionary will be added to
the new exception's status dictionary under the <b class="option">-during</b> key.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>Ensure that a file is closed no matter what:</p>
<pre class="doctools_example">
set f [open /some/file/name a]
<b class="cmd">try</b> {
puts \$f "some message"
# ...
} <b class="cmd">finally</b> {
close \$f
}
</pre>
<p>Handle different reasons for a file to not be openable for reading:</p>
<pre class="doctools_example">
<b class="cmd">try</b> {
set f [open /some/file/name]
} <b class="method">trap</b> {POSIX EISDIR} {} {
puts "failed to open /some/file/name: it's a directory"
} <b class="method">trap</b> {POSIX ENOENT} {} {
puts "failed to open /some/file/name: it doesn't exist"
}
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>try</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p>catch(n), error(n), return(n), <a href="tcllib_throw.html">throw(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#cleanup">cleanup</a>, <a href="../../../../index.html#error">error</a>, <a href="../../../../index.html#exception">exception</a>, <a href="../../../../index.html#final">final</a>, <a href="../../../../index.html#resource_management">resource management</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Utility</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Donal K. Fellows, BSD licensed</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/udpcluster/udpcluster.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<div class='fossil-doc' data-title='udpcluster - Lightweight UDP based tool for cluster node discovery'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">udpcluster(n) 0.3.3 tcllib "Lightweight UDP based tool for cluster node discovery"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>udpcluster - UDP Peer-to-Peer cluster</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">udpcluster <span class="opt">?0.3.3?</span></b></li>
<li>package require <b class="pkgname">ip</b></li>
<li>package require <b class="pkgname">nettool</b></li>
<li>package require <b class="pkgname">comm</b></li>
<li>package require <b class="pkgname">interp</b></li>
<li>package require <b class="pkgname">dicttool</b></li>
<li>package require <b class="pkgname">cron</b></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package is a lightweight alternative to Zeroconf. It utilizes UDP packets to
populate a table of services provided by each node on a local network. Each participant
broadcasts a key/value list in plain UTF-8 which lists what ports are open, and what
protocols are expected on those ports. Developers are free to add any additional key/value
pairs beyond those.</p>
<p>Using udpcluster.</p>
<p>For every service you wish to publish invoke:</p>
<pre class="doctools_example">
cluster::publish echo@[cluster::macid] {port 10000 protocol echo}
</pre>
<p>To query what services are available on the local network:</p>
<pre class="doctools_example">
set results [cluster::search PATTERN]
# And inside that result...
echo@LOCALMACID {
port 10000
protocol echo
}
</pre>
<p>To unpublish a service:</p>
<pre class="doctools_example">
cluster::unpublish echo@[cluster::macid]
</pre>
<p>Results will
Historical Notes:</p>
<p>This tool was originally known as nns::cluster, but as development progressed, it was
clear that it wasn't interacting with any of the other facilities in NNS.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>nameserv</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#name_service">name service</a>, <a href="../../../../index.html#server">server</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2016-2018 Sean Woods <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/uev/uevent.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
<div class='fossil-doc' data-title='uevent - User events'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">uevent(n) 0.3.1 tcllib "User events"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>uevent - User events</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">uevent <span class="opt">?0.3.1?</span></b></li>
<li>package require <b class="pkgname">logger</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::uevent::bind</b> <i class="arg">tag</i> <i class="arg">event</i> <i class="arg">command</i></a></li>
<li><a href="#2"><b class="cmd"><a href="../../../../index.html#command">command</a></b> <i class="arg">tag</i> <i class="arg">event</i> <i class="arg">details</i></a></li>
<li><a href="#3"><b class="cmd">::uevent::unbind</b> <i class="arg">token</i></a></li>
<li><a href="#4"><b class="cmd">::uevent::generate</b> <i class="arg">tag</i> <i class="arg">event</i> <span class="opt">?<i class="arg">details</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::uevent::list</b></a></li>
<li><a href="#6"><b class="cmd">::uevent::list</b> <i class="arg">tag</i></a></li>
<li><a href="#7"><b class="cmd">::uevent::list</b> <i class="arg">tag</i> <i class="arg">event</i></a></li>
<li><a href="#8"><b class="cmd">::uevent::watch::tag::add</b> <i class="arg">pattern</i> <i class="arg">command</i></a></li>
<li><a href="#9"><b class="cmd">{*}command</b> <b class="const">bound</b> <i class="arg">tag</i></a></li>
<li><a href="#10"><b class="cmd">{*}command</b> <b class="const">unbound</b> <i class="arg">tag</i></a></li>
<li><a href="#11"><b class="cmd">::uevent::watch::tag::remove</b> <i class="arg">token</i></a></li>
<li><a href="#12"><b class="cmd">::uevent::watch::event::add</b> <i class="arg">tag_pattern</i> <i class="arg">event_pattern</i> <i class="arg">command</i></a></li>
<li><a href="#13"><b class="cmd">{*}command</b> <b class="const">bound</b> <i class="arg">tag</i> <i class="arg">event</i></a></li>
<li><a href="#14"><b class="cmd">{*}command</b> <b class="const">unbound</b> <i class="arg">tag</i> <i class="arg">event</i></a></li>
<li><a href="#15"><b class="cmd">::uevent::watch::event::remove</b> <i class="arg">token</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a general facility for the handling of user
events. Allows the binding of arbitrary commands to arbitrary events
on arbitrary tags, removal of bindings, and event generation.</p>
<p>The main difference to the event system built into the Tcl/Tk core is
that the latter can generate only virtual events, and only for
widgets. It is not possible to use the builtin facilities to bind to
events on arbitrary (pseudo-)objects, nor is it able to generate
events for such.</p>
<p>Here we can, by assuming that each object in question is represented
by its own tag. Which is possible as we allow arbitrary tags.</p>
<p>More differences:</p>
<ol class="doctools_enumerated">
<li><p>The package uses only a two-level hierarchy, tags and events, to
handle everything, whereas the Tcl/Tk system uses three levels, i.e.
objects, tags, and events, with a n:m relationship between objects and
tags.</p></li>
<li><p>This package triggers all bound commands for a tag/event combination,
and they are independent of each other. A bound command cannot force
the event processing core to abort the processing of command coming
after it.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports eight commands, as specified below. Note that when
the package is used from within Tcl 8.5+ all the higher commands are
ensembles, i.e. the :: separators can be replaceed by spaces.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::uevent::bind</b> <i class="arg">tag</i> <i class="arg">event</i> <i class="arg">command</i></a></dt>
<dd><p>Using this command registers the <i class="arg">command</i> prefix to be triggered
when the <i class="arg">event</i> occurs for the <i class="arg">tag</i>. The result of the
command is an opaque token representing the binding. Note that if the
same combination of <<i class="arg">tag</i>,<i class="arg">event</i>,<i class="arg">command</i>> is used
multiple times the same token is returned by every call.</p>
<p>The signature of the <i class="arg">command</i> prefix is</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd"><a href="../../../../index.html#command">command</a></b> <i class="arg">tag</i> <i class="arg">event</i> <i class="arg">details</i></a></dt>
<dd></dd>
</dl>
<p>where <i class="arg">details</i> contains the argument(s) of the event. Its
contents are event specific and have to be agreed upon between actual
event generator and consumer. This package simply transfers the
information and does not perform any processing beyond that.</p></dd>
<dt><a name="3"><b class="cmd">::uevent::unbind</b> <i class="arg">token</i></a></dt>
<dd><p>This command releases the event binding represented by the
<i class="arg">token</i>. The token has to be the result of a call to
<b class="cmd">::uevent::bind</b>. The result of the command is the empty string.</p></dd>
<dt><a name="4"><b class="cmd">::uevent::generate</b> <i class="arg">tag</i> <i class="arg">event</i> <span class="opt">?<i class="arg">details</i>?</span></a></dt>
<dd><p>This command generates an <i class="arg">event</i> for the <i class="arg">tag</i>, triggering
all commands bound to that combination. The <i class="arg">details</i> argument is
simply passed unchanged to all event handlers. It is the
responsibility of the code generating and consuming the event to have
an agreement about the format and contents of the information carried
therein. The result of the command is the empty string.</p>
<p>Note that all bound commands are triggered, independently of each
other. The event handlers cannot assume a specific order. They are
also <em>not</em> called synchronously with the invokation of this
command, but simply put into the event queue for processing when the
system returns to the event loop.</p>
<p>Generating an event for an unknown tag, or for a
<<i class="arg">tag</i>,<i class="arg">event</i>> combination which has no commands bound to it
is allowed, such calls will be ignored.</p></dd>
<dt><a name="5"><b class="cmd">::uevent::list</b></a></dt>
<dd><p>In this form the command returns a list containing the names of all
tags which have events with commands bound to them.</p></dd>
<dt><a name="6"><b class="cmd">::uevent::list</b> <i class="arg">tag</i></a></dt>
<dd><p>In this format the command returns a list containing the names of all
events for the <i class="arg">tag</i> with commands bound to them. Specifying an
unknown tag, i.e. a tag without event and commands, will cause the
command to throw an error.</p></dd>
<dt><a name="7"><b class="cmd">::uevent::list</b> <i class="arg">tag</i> <i class="arg">event</i></a></dt>
<dd><p>In this format the command returns a list containing all commands
bound to the <i class="arg">event</i> for the <i class="arg">tag</i>. Specifying an unknown tag
or unknown event, will cause the command to throw an error.</p></dd>
<dt><a name="8"><b class="cmd">::uevent::watch::tag::add</b> <i class="arg">pattern</i> <i class="arg">command</i></a></dt>
<dd><p>This command sets up a sort of reverse events. Events generated,
i.e. the <i class="arg">command</i> prefix invoked, when observers bind to and
unbind from specific tags.</p>
<p>Note that the command prefix is only invoked twice per tag,
first when the first command is bound to any event of the tag, and
second when the last command bound to the tag is removed.</p>
<p>The signature of the <i class="arg">command</i> prefix is</p>
<dl class="doctools_definitions">
<dt><a name="9"><b class="cmd">{*}command</b> <b class="const">bound</b> <i class="arg">tag</i></a></dt>
<dd></dd>
<dt><a name="10"><b class="cmd">{*}command</b> <b class="const">unbound</b> <i class="arg">tag</i></a></dt>
<dd></dd>
</dl>
<p>The result of the command is a token representing the watcher.</p></dd>
<dt><a name="11"><b class="cmd">::uevent::watch::tag::remove</b> <i class="arg">token</i></a></dt>
<dd><p>This command removes a watcher for (un)bind events on tags.</p>
<p>The result of the command is the empty string.</p></dd>
<dt><a name="12"><b class="cmd">::uevent::watch::event::add</b> <i class="arg">tag_pattern</i> <i class="arg">event_pattern</i> <i class="arg">command</i></a></dt>
<dd><p>This command sets up a sort of reverse events. Events generated,
i.e. the <i class="arg">command</i> prefix invoked, when observers bind to and
unbind from specific combinations of tags and events.</p>
<p>Note that the command prefix is only invoked twice per
tag/event combination, first when the first command is bound to it,
and second when the last command bound to the it is removed.</p>
<p>The signature of the <i class="arg">command</i> prefix is</p>
<dl class="doctools_definitions">
<dt><a name="13"><b class="cmd">{*}command</b> <b class="const">bound</b> <i class="arg">tag</i> <i class="arg">event</i></a></dt>
<dd></dd>
<dt><a name="14"><b class="cmd">{*}command</b> <b class="const">unbound</b> <i class="arg">tag</i> <i class="arg">event</i></a></dt>
<dd></dd>
</dl>
<p>The result of the command is a token representing the watcher.</p></dd>
<dt><a name="15"><b class="cmd">::uevent::watch::event::remove</b> <i class="arg">token</i></a></dt>
<dd><p>This command removes a watcher for (un)bind events on tag/event
combinations.</p>
<p>The result of the command is the empty string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>uevent</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../hook/hook.html">hook(n)</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#bind">bind</a>, <a href="../../../../index.html#event">event</a>, <a href="../../../../index.html#generate_event">generate event</a>, <a href="../../../../index.html#hook">hook</a>, <a href="../../../../index.html#unbind">unbind</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2012 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/uev/uevent_onidle.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<div class='fossil-doc' data-title='uevent::onidle - User events'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">uevent::onidle(n) 0.1 tcllib "User events"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>uevent::onidle - Request merging and deferal to idle time</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Examples</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">uevent::onidle <span class="opt">?0.1?</span></b></li>
<li>package require <b class="pkgname">logger</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::uevent::onidle</b> <i class="arg">objectName</i> <i class="arg">commandprefix</i></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">request</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides objects which can merge multiple requestes for
an action and execute the action the moment the system (event loop)
becomes idle. The action to be run is configured during object
construction.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The package exports a class, <b class="class">uevent::onidle</b>, as specified
below.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::uevent::onidle</b> <i class="arg">objectName</i> <i class="arg">commandprefix</i></a></dt>
<dd><p>The command creates a new <i class="term">onidle</i> object with an associated
global Tcl command whose name is <i class="arg">objectName</i>. This command may
be used to invoke various operations on the object.</p>
<p>The <i class="arg">commandprefix</i> is the action to perform when the event loop
is idle and the user asked for it using the method <b class="method">request</b>
(See below).</p></dd>
</dl>
<p>The object commands created by the class commands above have
the form:</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">request</b></a></dt>
<dd><p>This method requests the execution of the command prefix specified
during the construction of <i class="arg">objectName</i> the next time the event
loop is idle. Multiple requests are merged and cause only one
execution of the command prefix.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Examples</a></h2>
<p>Examples of this type of deferal are buried in the (C-level)
implementations all the Tk widgets, defering geometry calculations and
window redraw activity in this manner.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>uevent</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#callback">callback</a>, <a href="../../../../index.html#deferal">deferal</a>, <a href="../../../../index.html#event">event</a>, <a href="../../../../index.html#idle">idle</a>, <a href="../../../../index.html#merge">merge</a>, <a href="../../../../index.html#on_idle">on-idle</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/units/units.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
|
<div class='fossil-doc' data-title='units - Convert and manipulate quantities with units'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">units(n) 1.2 tcllib "Convert and manipulate quantities with units"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>units - unit conversion</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">UNIT STRING FORMAT</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Example Valid Unit Strings</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">SI UNITS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection2">SI Base Units</a></li>
<li class="doctools_subsection"><a href="#subsection3">SI Derived Units with Special Names</a></li>
<li class="doctools_subsection"><a href="#subsection4">SI Prefixes</a></li>
<li class="doctools_subsection"><a href="#subsection5">Non-SI Units</a></li>
<li class="doctools_subsection"><a href="#subsection6">Quantities and Derived Units with Special Names</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section5">REFERENCES</a></li>
<li class="doctools_section"><a href="#section6">AUTHORS</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.1</b></li>
<li>package require <b class="pkgname">units <span class="opt">?2.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::units::convert</b> <i class="arg">value</i> <i class="arg">targetUnits</i></a></li>
<li><a href="#2"><b class="cmd">::units::reduce</b> <i class="arg">unitString</i></a></li>
<li><a href="#3"><b class="cmd">::units::new</b> <i class="arg">name</i> <i class="arg">baseUnits</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This library provides a conversion facility from a variety of
scientific and engineering shorthand notations into floating point
numbers. This allows application developers to easily convert
values with different units into uniformly scaled numbers.</p>
<p>The units conversion facility is also able to convert between
compatible units. If, for example, a application is expecting a value
in <em>ohms</em> (Resistance), and the user specifies units of
<em>milliwebers/femtocoulomb</em>, the conversion routine will
handle it appropriately. An error will be generated if an incorrect
conversion is attempted.</p>
<p>Values are scaled from one set of units to another by dimensional
analysis. Both the value units and the target units are reduced into
primitive units and a scale factor. Units are checked for
compatibility, and the scale factors are applied by multiplication and
division. This technique is extremely flexible and quite robust.</p>
<p>New units and new unit abbreviations can be defined in terms of
existing units and abbreviations. It is also possible to define a new
primitive unit, although that will probably be unnecessary. New units
will most commonly be defined to accommodate non-SI measurement
systems, such as defining the unit <em>inch</em> as <em>2.54 cm</em>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::units::convert</b> <i class="arg">value</i> <i class="arg">targetUnits</i></a></dt>
<dd><p>Converts the <i class="arg">value</i> string into a floating point number, scaled to the
specified <i class="arg">targetUnits</i>. The <i class="arg">value</i> string may contain a
number and units. If units are specified, then they must be
compatible with the <i class="arg">targetUnits</i>. If units are not specified
for the <i class="arg">value</i>, then it will be scaled to the target units. For
example,</p>
<pre class="doctools_example">
% ::units::convert "2.3 miles" km
3.7014912
% ::units::convert 300m/s miles/hour
671.080887616
% ::units::convert "1.0 m kg/s^2" newton
1.0
% ::units::convert 1.0 millimeter
1000.0
</pre>
</dd>
<dt><a name="2"><b class="cmd">::units::reduce</b> <i class="arg">unitString</i></a></dt>
<dd><p>Returns a unit string consisting of a scale factor followed by a space
separated list of sorted and reduced primitive units. The reduced
unit string may include a forward-slash (separated from the
surrounding primitive subunits by spaces) indicating that the
remaining subunits are in the denominator. Generates an error if the
<i class="arg">unitString</i> is invalid.</p>
<pre class="doctools_example">
% ::units::reduce pascal
1000.0 gram / meter second second
</pre>
</dd>
<dt><a name="3"><b class="cmd">::units::new</b> <i class="arg">name</i> <i class="arg">baseUnits</i></a></dt>
<dd><p>Creates a new unit conversion with the specified name. The new unit
<i class="arg">name</i> must be only alphabetic (upper or lower case) letters.
The <i class="arg">baseUnits</i> string can consist of any valid units conversion
string, including constant factors, numerator and denominator parts,
units with prefixes, and exponents. The baseUnits may contain any
number of subunits, but it must reduce to primitive units. BaseUnits
could also be the string <em>-primitive</em> to represent a new
kind of quantity which cannot be derived from other units. But you
probably would not do that unless you have discovered some kind of new
universal property.</p>
<pre class="doctools_example">
% ::units::new furlong "220 yards"
% ::units::new fortnight "14 days"
% ::units::convert 100m/s furlongs/fortnight
601288.475303
</pre>
</dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">UNIT STRING FORMAT</a></h2>
<p>Value and unit string format is quite flexible. It is possible to
define virtually any combination of units, prefixes, and powers.
Valid unit strings must conform to these rules.</p>
<ul class="doctools_itemized">
<li><p>A unit string consists of an optional scale factor followed by zero or
more subunits. The scale factor must be a valid floating point
number, and may or may not be separated from the subunits. The scale
factor could be negative.</p></li>
<li><p>Subunits are separated form each other by one or more separator
characters, which are space (" "), hyphen ("-"), asterisk ("*"), and
forward-slash ("/"). Sure, go ahead and complain about using a minus
sign ("-") to represent multiplication. It just isn't sound
mathematics, and, by rights, we should require everyone to use the
asterisk ("*") to separate all units. But the bottom line is that
complex unit strings like <em>m-kg/s^2</em> are pleasantly
readable.</p></li>
<li><p>The forward-slash seperator ("/") indicates that following subunits are
in the denominator. There can be at most one forward-slash separator.</p></li>
<li><p>Subunits can be floating point scale factors, but with the exception
of the leading scale factor, they must be surrounded by valid
separators. Subunit scale factors cannot be negative. (Remember that
the hyphen is a unit separator.)</p></li>
<li><p>Subunits can be valid units or abbreviations. They may include a
prefix. They may include a plural suffix "s" or "es". They may also
include a power string denoted by a circumflex ("^"), followed by a
integer, after the unit name (or plural suffix, if there is one).
Negative exponents are not allowed. (Remember that the hyphen is a
unit separator.)</p></li>
</ul>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Example Valid Unit Strings</a></h3>
<pre class="doctools_example">
Unit String Reduced Unit String
------------------------------------------------------------
meter 1.0 meter
kilometer 1000.0 meter
km 1000.0 meter
km/s 1000.0 meter / second
/microsecond 1000000.0 / second
/us 1000000.0 / second
kg-m/s^2 1000.0 gram meter / second second
30second 30.0 second
30 second 30.0 second
30 seconds 30.0 second
200*meter/20.5*second 9.75609756098 meter / second
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">SI UNITS</a></h2>
<p>The standard SI units are predefined according to <em>NIST Special
Publication 330</em>. Standard units for both SI Base Units (Table
1) and SI Derived Units with Special Names (Tables 3a and 3b) are
included here for reference. Each standard unit name and abbreviation
are included in this package.</p>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">SI Base Units</a></h3>
<pre class="doctools_example">
Quantity Unit Name Abbr.
---------------------------------------------
Length meter m
Mass kilogram kg
Time second s
Current ampere A
Temperature kelvin K
Amount mole mol
Luminous Intensity candela cd
</pre>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">SI Derived Units with Special Names</a></h3>
<pre class="doctools_example">
Quantity Unit Name Abbr. Units Base Units
--------------------------------------------------------------------
plane angle radian rad m/m m/m
solid angle steradian sr m^2/m^2 m^2/m^2
frequency hertz Hz /s
force newton N m-kg/s^2
pressure pascal Pa N/m^2 kg/m-s^2
energy, work joule J N-m m^2-kg/s^2
power, radiant flux watt W J/s m^2-kg/s^3
electric charge coulomb C s-A
electric potential volt V W/A m^2-kg/s^3-A
capacitance farad F C/V s^4-A^2/m^2-kg
electric resistance ohm V/A m^2-kg/s^3-A^2
electric conductance siemens S A/V s^3-A^2/m^2-kg
magnetic flux weber Wb V-s m^2-kg/s^2-A
magnetic flux density tesla T Wb/m^2 kg/s^2-A
inductance henry H Wb/A m^2-kg/s^2-A^2
luminous flux lumen lm cd-sr
illuminance lux lx lm/m^2 cd-sr/m^2
activity (of a
radionuclide) becquerel Bq /s
absorbed dose gray Gy J/kg m^2/s^2
dose equivalent sievert Sv J/kg m^2/s^2
</pre>
<p>Note that the SI unit kilograms is actually implemented as grams
because 1e-6 kilogram = 1 milligram, not 1 microkilogram. The
abbreviation for Electric Resistance (ohms), which is the omega
character, is not supported.</p>
<p>Also note that there is no support for Celsius or Farenheit
temperature. The units conversion routines can only scale values
with multiplication and division, so it is not possible to convert
from thermodynamic temperature (kelvins) to absolute degrees Celsius
or Farenheit. Conversion of thermodynamic quantities, such as
thermal expansion (per unit temperature), however, are easy to add
to the units library.</p>
<p>SI Units can have a multiple or sub-multiple prefix. The prefix or its
abbreviation should appear before the unit, without spaces. Compound
prefixes are not allowed, and a prefix should never be used alone.
These prefixes are defined in Table 5 of <em>Special Publication
330</em>.</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">SI Prefixes</a></h3>
<pre class="doctools_example">
Prefix Name Abbr. Factor
---------------------------------------
yotta Y 1e24
zetta Z 1e21
exa E 1e18
peta P 1e15
tera T 1e12
giga G 1e9
mega M 1e6
kilo k 1e3
hecto h 1e2
deka da 1e1
deca 1e1
deci d 1e-1
centi c 1e-2
milli m 1e-3
micro u 1e-6
nano n 1e-9
pico p 1e-12
femto f 1e-15
atto a 1e-18
zepto z 1e-21
yocto y 1e-24
</pre>
<p>Note that we define the same prefix with both the USA ("deka") and
non-USA ("deca") spellings. Also note that we take the liberty of
allowing "micro" to be typed as a "u" instead of the Greek character
mu.</p>
<p>Many non-SI units are commonly used in applications. Appendix B.8 of
<em>NIST Special Publication 811</em> lists many non-SI conversion
factors. It is not possible to include all possible unit definitions
in this package. In some cases, many different conversion factors
exist for a given unit, depending on the context. (The appendix lists
over 40 conversions for British thermal units!) Application specific
conversions can always be added using the <b class="cmd">new</b>
command, but some well known and often used conversions are included
in this package.</p>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Non-SI Units</a></h3>
<pre class="doctools_example">
Unit Name Abbr. Base Units
--------------------------------------------------
angstrom 1.0E-10 m
astronomicalUnit AU 1.495979E11 m
atmosphere 1.01325E5 Pa
bar 1.0E5 Pa
calorie 4.1868 J
curie 3.7E10 Bq
day 8.64E4 s
degree 1.745329E-2 rad
erg 1.0E-7 J
faraday 9.648531 C
fermi 1.0E-15 m
foot ft 3.048E-1 m
gauss 1.0E-4 T
gilbert 7.957747E-1 A
grain gr 6.479891E-5 kg
hectare ha 1.0E4 m^2
hour h 3.6E3 s
inch in 2.54E-2 m
lightYear 9.46073E15 m
liter L 1.0E-3 m^3
maxwell Mx 1.0E-8 Wb
mho 1.0 S
micron 1.0E-6 m
mil 2.54E-5 m
mile mi 1.609344E3 m
minute min 6.0E1 s
parsec pc 3.085E16 m
pica 4.233333E-3 m
pound lb 4.535924E-1 kg
revolution 6.283185 rad
revolutionPerMinute rpm 1.047198E-1 rad/s
yard yd 9.144E-1 m
year 3.1536E7 s
</pre>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Quantities and Derived Units with Special Names</a></h3>
<p>This units conversion package is limited specifically to unit
reduction, comparison, and scaling. This package does not consider
any of the quantity names for either base or derived units. A similar
implementation or an extension in a typed or object-oriented language
might introduce user defined types for the quantities. Quantity type
checking could be used, for example, to ensure that all
<em>length</em> values properly reduced to <em>meters</em>, or
that all <em>velocity</em> values properly reduced to
<em>meters/second</em>.</p>
<p>A C implementation of this package has been created to work in
conjunction with the Simplified Wrapper Interface Generator
(<a href="http://www.swig.org/">http://www.swig.org/</a>). That package (units.i) exploits SWIG's typemap
system to automatically convert script quantity strings into floating
point quantities. Function arguments are specified as quantity types
(e.g., <em>typedef float Length</em>), and target units (expected
by the C application code) are specified in an associative array.
Default units are also defined for each quantity type, and are applied
to any unit-less quantity strings.</p>
<p>A units system enhanced with quantity type checking might benefit from
inclusion of other derived types which are expressed in terms of
special units, as illustrated in Table 2 of <em>NIST Publication
330</em>. The quantity <em>area</em>, for example, could be
defined as units properly reducing to <em>meter^2</em>, although
the utility of defining a unit named <em>square meter</em> is
arguable.</p>
</div>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">REFERENCES</a></h2>
<p>The unit names, abbreviations, and conversion values are derived from
those published by the United States Department of Commerce Technology
Administration, National Institute of Standards and Technology (NIST)
in <em>NIST Special Publication 330: The International System of
Units (SI)</em> and <em>NIST Special Publication 811: Guide for
the Use of the International System of Units (SI)</em>. Both of
these publications are available (as of December 2000) from
<a href="http://physics.nist.gov/cuu/Reference/contents.html">http://physics.nist.gov/cuu/Reference/contents.html</a></p>
<p>The ideas behind implementation of this package is based in part on
code written in 1993 by Adrian Mariano which performed dimensional
analysis of unit strings using fixed size tables of C structs. After
going missing in the late 1990's, Adrian's code has reappeared in the
GNU Units program at <a href="http://www.gnu.org/software/units/">http://www.gnu.org/software/units/</a></p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">AUTHORS</a></h2>
<p>Robert W. Techentin</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>units</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#angle">angle</a>, <a href="../../../../index.html#constants">constants</a>, <a href="../../../../index.html#conversion">conversion</a>, <a href="../../../../index.html#distance">distance</a>, <a href="../../../../index.html#radians">radians</a>, <a href="../../../../index.html#unit">unit</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2000-2005 Mayo Foundation</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/uri/uri.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
|
<div class='fossil-doc' data-title='uri - Tcl Uniform Resource Identifier Management'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">uri(n) 1.2.7 tcllib "Tcl Uniform Resource Identifier Management"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>uri - URI utilities</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">SCHEMES</a></li>
<li class="doctools_section"><a href="#section4">EXTENDING</a></li>
<li class="doctools_section"><a href="#section5">QUIRK OPTIONS</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">BACKWARD COMPATIBILITY</a></li>
<li class="doctools_subsection"><a href="#subsection2">NEW DESIGNS</a></li>
<li class="doctools_subsection"><a href="#subsection3">DEFAULT VALUES</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section6">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section7">CREDITS</a></li>
<li class="doctools_section"><a href="#section8">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">uri <span class="opt">?1.2.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">uri::setQuirkOption</b> <i class="arg">option</i> <span class="opt">?<i class="arg">value</i>?</span></a></li>
<li><a href="#2"><b class="cmd">uri::split</b> <i class="arg">url</i> <span class="opt">?<i class="arg">defaultscheme</i>?</span></a></li>
<li><a href="#3"><b class="cmd">uri::join</b> <span class="opt">?<i class="arg">key</i> <i class="arg">value</i>?</span>...</a></li>
<li><a href="#4"><b class="cmd">uri::resolve</b> <i class="arg">base</i> <i class="arg">url</i></a></li>
<li><a href="#5"><b class="cmd">uri::isrelative</b> <i class="arg">url</i></a></li>
<li><a href="#6"><b class="cmd">uri::geturl</b> <i class="arg">url</i> <span class="opt">?<i class="arg">options</i>...?</span></a></li>
<li><a href="#7"><b class="cmd">uri::canonicalize</b> <i class="arg">uri</i></a></li>
<li><a href="#8"><b class="cmd">uri::register</b> <i class="arg">schemeList</i> <i class="arg">script</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package does two things.</p>
<p>First, it provides a number of
commands for manipulating URLs/URIs and fetching data specified by
them. For fetching data this package analyses the requested URL/URI and
then dispatches it to the appropriate package (<b class="package"><a href="../../../../index.html#http">http</a></b>, <b class="package"><a href="../ftp/ftp.html">ftp</a></b>, ...) for
actual retrieval. Currently these commands are defined for the schemes
<i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, <i class="term"><a href="../../../../index.html#mailto">mailto</a></i>, <i class="term"><a href="../../../../index.html#news">news</a></i>,
<i class="term"><a href="../../../../index.html#ldap">ldap</a></i>, <i class="term">ldaps</i> and <i class="term"><a href="../../../../index.html#file">file</a></i>. The package <b class="package">uri::urn</b> adds scheme <i class="term"><a href="../../../../index.html#urn">urn</a></i>.</p>
<p>Second, it provides regular expressions
for a number of <b class="const">registered</b> URL/URI schemes. Registered
schemes are currently <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, <i class="term"><a href="../../../../index.html#ldap">ldap</a></i>, <i class="term">ldaps</i>, <i class="term"><a href="../../../../index.html#file">file</a></i>,
<i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, <i class="term"><a href="../../../../index.html#gopher">gopher</a></i>, <i class="term"><a href="../../../../index.html#mailto">mailto</a></i>, <i class="term"><a href="../../../../index.html#news">news</a></i>,
<i class="term"><a href="../../../../index.html#wais">wais</a></i> and <i class="term"><a href="../../../../index.html#prospero">prospero</a></i>. The package <b class="package">uri::urn</b> adds scheme
<i class="term"><a href="../../../../index.html#urn">urn</a></i>.</p>
<p>The commands of the package conform to
RFC 3986 (<a href="https://www.rfc-editor.org/rfc/rfc3986.txt">https://www.rfc-editor.org/rfc/rfc3986.txt</a>),
with the exception of a loophole arising from RFC 1630 and described
in RFC 3986 Sections 5.2.2 and 5.4.2. The loophole allows a relative
URI to include a scheme if it is the same as the scheme of the base
URI against which it is resolved. RFC 3986 recommends avoiding this usage.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">uri::setQuirkOption</b> <i class="arg">option</i> <span class="opt">?<i class="arg">value</i>?</span></a></dt>
<dd><p><b class="cmd">uri::setQuirkOption</b> is an accessor command for a number of "quirk options".
The command has the same semantics as the command <b class="cmd"><a href="../../../../index.html#set">set</a></b>: when called with one argument it reads an existing value; with two arguments it writes a new value. The value of a "quirk option" is boolean: the value <b class="const">false</b> requests conformance with RFC 3986, while <b class="const">true</b> requests use of the quirk. See section <span class="sectref"><a href="#section5">QUIRK OPTIONS</a></span> for discussion of the different options and their purpose.</p></dd>
<dt><a name="2"><b class="cmd">uri::split</b> <i class="arg">url</i> <span class="opt">?<i class="arg">defaultscheme</i>?</span></a></dt>
<dd><p><b class="cmd">uri::split</b> takes a <i class="arg">url</i>, decodes it and then returns a
list of key/value pairs suitable for <b class="cmd">array set</b> containing the
constituents of the <i class="arg">url</i>. If the scheme is missing from the <i class="arg">url</i>
it defaults to the value of <i class="arg">defaultscheme</i> if it was specified,
or <i class="term"><a href="../../../../index.html#http">http</a></i> else. Currently the schemes <i class="term"><a href="../../../../index.html#http">http</a></i>,
<i class="term"><a href="../../../../index.html#https">https</a></i>, <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, <i class="term"><a href="../../../../index.html#mailto">mailto</a></i>, <i class="term"><a href="../../../../index.html#news">news</a></i>, <i class="term"><a href="../../../../index.html#ldap">ldap</a></i>, <i class="term">ldaps</i> and
<i class="term"><a href="../../../../index.html#file">file</a></i> are supported by the package itself.
See section <span class="sectref"><a href="#section4">EXTENDING</a></span> on how to expand that range.</p>
<p>The set of constituents of a URL (= the set of keys in the returned
dictionary) is dependent on the scheme of the URL. The only key which
is therefore always present is <b class="const">scheme</b>. For the following
schemes the constituents and their keys are known:</p>
<dl class="doctools_definitions">
<dt>ftp</dt>
<dd><p><b class="const">user</b>, <b class="const">pwd</b>, <b class="const">host</b>, <b class="const">port</b>,
<b class="const">path</b>, <b class="const">type</b>, <b class="const">pbare</b>. The pbare is optional.</p></dd>
<dt>http(s)</dt>
<dd><p><b class="const">user</b>, <b class="const">pwd</b>, <b class="const">host</b>, <b class="const">port</b>,
<b class="const">path</b>, <b class="const">query</b>, <b class="const">fragment</b>, <b class="const">pbare</b>. The pbare is optional.</p></dd>
<dt>file</dt>
<dd><p><b class="const">path</b>, <b class="const">host</b>. The host is optional.</p></dd>
<dt>mailto</dt>
<dd><p><b class="const">user</b>, <b class="const">host</b>. The host is optional.</p></dd>
<dt>ldap(s)</dt>
<dd><p><b class="const">host</b>, <b class="const">port</b>, <b class="const">dn</b>, <b class="const">attrs</b>, <b class="const">scope</b>, <b class="const">filter</b>, <b class="const">extensions</b></p></dd>
<dt>news</dt>
<dd><p>Either <b class="const">message-id</b> or <b class="const">newsgroup-name</b>.</p></dd>
</dl>
<p>For discussion of the boolean <b class="const">pbare</b> see options <em>NoInitialSlash</em> and <em>NoExtraKeys</em> in <span class="sectref"><a href="#section5">QUIRK OPTIONS</a></span>.</p>
<p>The constituents are returned as slices of the argument <i class="arg">url</i>, without removal of percent-encoding ("url-encoding") or other adaptations. Notably, on Windows® the <b class="const">path</b> in scheme <i class="term"><a href="../../../../index.html#file">file</a></i> is not a valid local filename. See <span class="sectref"><a href="#section6">EXAMPLES</a></span> for more information.</p></dd>
<dt><a name="3"><b class="cmd">uri::join</b> <span class="opt">?<i class="arg">key</i> <i class="arg">value</i>?</span>...</a></dt>
<dd><p><b class="cmd">uri::join</b> takes a list of key/value pairs (generated by
<b class="cmd">uri::split</b>, for example) and returns the canonical URL they
represent. Currently the schemes <i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>,
<i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, <i class="term"><a href="../../../../index.html#mailto">mailto</a></i>, <i class="term"><a href="../../../../index.html#news">news</a></i>, <i class="term"><a href="../../../../index.html#ldap">ldap</a></i>, <i class="term">ldaps</i> and <i class="term"><a href="../../../../index.html#file">file</a></i>
are supported by the package itself. See section <span class="sectref"><a href="#section4">EXTENDING</a></span> on how to expand that range.</p>
<p>The arguments are expected to be slices of a valid URL, with percent-encoding ("url-encoding") and any other necessary adaptations. Notably, on Windows the <b class="const">path</b> in scheme <i class="term"><a href="../../../../index.html#file">file</a></i> is not a valid local filename. See <span class="sectref"><a href="#section6">EXAMPLES</a></span> for more information.</p></dd>
<dt><a name="4"><b class="cmd">uri::resolve</b> <i class="arg">base</i> <i class="arg">url</i></a></dt>
<dd><p><b class="cmd">uri::resolve</b> resolves the specified <i class="arg">url</i> relative to
<i class="arg">base</i>, in conformance with RFC 3986. In other words: a
non-relative <i class="arg">url</i> is returned
unchanged, whereas for a relative <i class="arg">url</i> the missing parts are
taken from <i class="arg">base</i> and prepended to it. The result of this
operation is returned. For an empty <i class="arg">url</i> the result is
<i class="arg">base</i>, without its URI fragment (if any). The command is available for schemes <i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, and <i class="term"><a href="../../../../index.html#file">file</a></i>.</p></dd>
<dt><a name="5"><b class="cmd">uri::isrelative</b> <i class="arg">url</i></a></dt>
<dd><p><b class="cmd">uri::isrelative</b> determines whether the specified <i class="arg">url</i> is
absolute or relative. The command is available for a <i class="arg">url</i> of any scheme.</p></dd>
<dt><a name="6"><b class="cmd">uri::geturl</b> <i class="arg">url</i> <span class="opt">?<i class="arg">options</i>...?</span></a></dt>
<dd><p><b class="cmd">uri::geturl</b> decodes the specified <i class="arg">url</i> and then dispatches
the request to the package appropriate for the scheme found in the
URL. The command assumes that the package to handle the given scheme
either has the same name as the scheme itself (including possible
capitalization) followed by <b class="cmd">::geturl</b>, or, in case of this
failing, has the same name as the scheme itself (including possible
capitalization). It further assumes that whatever package was loaded
provides a <b class="cmd">geturl</b>-command in the namespace of the same name as
the package itself. This command is called with the given <i class="arg">url</i>
and all given <i class="arg">options</i>. Currently <b class="cmd">geturl</b> does not handle
any options itself.</p>
<p><em>Note:</em> <i class="term"><a href="../../../../index.html#file">file</a></i>-URLs are an exception to the rule
described above. They are handled internally.</p>
<p>It is not possible to specify results of the command. They depend on
the <b class="cmd">geturl</b>-command for the scheme the request was dispatched to.</p></dd>
<dt><a name="7"><b class="cmd">uri::canonicalize</b> <i class="arg">uri</i></a></dt>
<dd><p><b class="cmd">uri::canonicalize</b> returns the canonical form of a URI. The
canonical form of a URI is one where relative path specifications,
i.e. "." and "..", have been resolved. The command is available for all
URI schemes that have <b class="cmd">uri::split</b> and <b class="cmd">uri::join</b> commands. The command
returns a canonicalized URI if the URI scheme has a <b class="const">path</b> component (i.e. <i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, and <i class="term"><a href="../../../../index.html#file">file</a></i>). For schemes that have <b class="cmd">uri::split</b> and <b class="cmd">uri::join</b> commands but no <b class="const">path</b> component (i.e. <i class="term"><a href="../../../../index.html#mailto">mailto</a></i>, <i class="term"><a href="../../../../index.html#news">news</a></i>, <i class="term"><a href="../../../../index.html#ldap">ldap</a></i>, and <i class="term">ldaps</i>), the command returns the <i class="arg">uri</i> unchanged.</p></dd>
<dt><a name="8"><b class="cmd">uri::register</b> <i class="arg">schemeList</i> <i class="arg">script</i></a></dt>
<dd><p><b class="cmd">uri::register</b> registers the first element of <i class="arg">schemeList</i> as
a new scheme and the remaining elements as aliases for this scheme. It
creates the namespace for the scheme and executes the <i class="arg">script</i> in
the new namespace. The script has to declare variables containing
regular expressions relevant to the scheme. At least the variable
<b class="variable">schemepart</b> has to be declared as that one is used to extend
the variables keeping track of the registered schemes.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">SCHEMES</a></h2>
<p>In addition to the commands mentioned above this package provides
regular expression to recognize URLs for a number of URL schemes.</p>
<p>For each supported scheme a namespace of the same name as the scheme
itself is provided inside of the namespace <em>uri</em> containing the
variable <b class="variable">url</b> whose contents are a regular expression to
recognize URLs of that scheme. Additional variables may contain
regular expressions for parts of URLs for that scheme.</p>
<p>The variable <b class="variable">uri::schemes</b> contains a list of all registered
schemes. Currently these are <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, <i class="term"><a href="../../../../index.html#ldap">ldap</a></i>, <i class="term">ldaps</i>, <i class="term"><a href="../../../../index.html#file">file</a></i>,
<i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, <i class="term"><a href="../../../../index.html#gopher">gopher</a></i>, <i class="term"><a href="../../../../index.html#mailto">mailto</a></i>, <i class="term"><a href="../../../../index.html#news">news</a></i>,
<i class="term"><a href="../../../../index.html#wais">wais</a></i> and <i class="term"><a href="../../../../index.html#prospero">prospero</a></i>.</p>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">EXTENDING</a></h2>
<p>Extending the range of schemes supported by <b class="cmd">uri::split</b> and
<b class="cmd">uri::join</b> is easy because both commands do not handle the
request by themselves but dispatch it to another command in the
<em>uri</em> namespace using the scheme of the URL as criterion.</p>
<p><b class="cmd">uri::split</b> and <b class="cmd">uri::join</b>
call <b class="cmd">Split[string totitle <scheme>]</b>
and <b class="cmd">Join[string totitle <scheme>]</b> respectively.</p>
<p>The provision of split and join commands is sufficient to extend the commands <b class="cmd">uri::canonicalize</b> and <b class="cmd">uri::geturl</b>
(the latter subject to the availability of a suitable package with a <b class="cmd">geturl</b> command). In contrast, to extend the command <b class="cmd">uri::resolve</b> to a new scheme, the command itself must be modified.</p>
<p>To extend the range of schemes for which pattern information is
available, use the command <b class="cmd">uri::register</b>.</p>
<p>An example of a package that provides both commands and pattern information for a new scheme is <b class="package">uri::urn</b>, which adds scheme <i class="term"><a href="../../../../index.html#urn">urn</a></i>.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">QUIRK OPTIONS</a></h2>
<p>The value of a "quirk option" is boolean: the value <b class="const">false</b> requests conformance with RFC 3986, while <b class="const">true</b> requests use of the quirk. Use command <b class="cmd">uri::setQuirkOption</b> to access the values of quirk options.</p>
<p>Quirk options are useful both for allowing backwards compatibility when a command
specification changes, and for adding useful features that are not included
in RFC specifications. The following quirk options are currently defined:</p>
<dl class="doctools_definitions">
<dt><em>NoInitialSlash</em></dt>
<dd><p>This quirk option concerns the leading character of <b class="const">path</b> (if non-empty) in the schemes <i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, and <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>.</p>
<p>RFC 3986 defines <b class="const">path</b> in an absolute URI to have an initial "/", unless the value of <b class="const">path</b> is the empty string. For the scheme <i class="term"><a href="../../../../index.html#file">file</a></i>, all versions of package <b class="package">uri</b> follow this rule. The quirk option <em>NoInitialSlash</em> does not apply to scheme <i class="term"><a href="../../../../index.html#file">file</a></i>.</p>
<p>For the schemes <i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, and <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, versions of <b class="package">uri</b> before 1.2.7 define the <b class="const">path</b> <em>NOT</em> to include an initial "/". When the quirk option <em>NoInitialSlash</em> is <b class="const">true</b> (the default), this behavior is also used in version 1.2.7. To use instead values of <b class="const">path</b> as defined by RFC 3986, set this quirk option to <b class="const">false</b>.</p>
<p>This setting does not affect RFC 3986 conformance. If <em>NoInitialSlash</em> is <b class="const">true</b>, then the value of <b class="const">path</b> in the schemes <i class="term"><a href="../../../../index.html#http">http</a></i>, <i class="term"><a href="../../../../index.html#https">https</a></i>, or <i class="term"><a href="../../../../index.html#ftp">ftp</a></i>, cannot distinguish between URIs in which the full "RFC 3986 path" is the empty string "" or a single slash "/" respectively. The missing information is recorded in an additional <b class="cmd">uri::split</b> key <b class="const">pbare</b>.</p>
<p>The boolean <b class="const">pbare</b> is defined when quirk options <em>NoInitialSlash</em> and <em>NoExtraKeys</em> have values <b class="const">true</b> and <b class="const">false</b> respectively. In this case, if the value of <b class="const">path</b> is the empty string "", <b class="const">pbare</b> is <b class="const">true</b> if the full "RFC 3986 path" is "", and <b class="const">pbare</b> is <b class="const">false</b> if the full "RFC 3986 path" is "/".</p>
<p>Using this quirk option <em>NoInitialSlash</em> is a matter of preference.</p></dd>
<dt><em>NoExtraKeys</em></dt>
<dd><p>This quirk option permits full backward compatibility with versions of <b class="package">uri</b> before 1.2.7, by omitting the <b class="cmd">uri::split</b> key <b class="const">pbare</b> described above (see quirk option <em>NoInitialSlash</em>). The outcome is greater backward compatibility of the <b class="cmd">uri::split</b> command, but an inability to distinguish between URIs in which the full "RFC 3986 path" is the empty string "" or a single slash "/" respectively - i.e. a minor non-conformance with RFC 3986.</p>
<p>If the quirk option <em>NoExtraKeys</em> is <b class="const">false</b> (the default), command <b class="cmd">uri::split</b> returns an additional key <b class="const">pbare</b>, and the commands comply with RFC 3986. If the quirk option <em>NoExtraKeys</em> is <b class="const">true</b>, the key <b class="const">pbare</b> is not defined and there is not full conformance with RFC 3986.</p>
<p>Using the quirk option <em>NoExtraKeys</em> is <em>NOT</em> recommended, because if set to <b class="const">true</b> it will reduce conformance with RFC 3986. The option is included only for compatibility with code, written for earlier versions of <b class="package">uri</b>, that needs values of <b class="const">path</b> without a leading "/", <em>AND ALSO</em> cannot tolerate unexpected keys in the results of <b class="cmd">uri::split</b>.</p></dd>
<dt><em>HostAsDriveLetter</em></dt>
<dd><p>When handling the scheme <i class="term"><a href="../../../../index.html#file">file</a></i> on the
Windows platform, versions of <b class="package">uri</b> before 1.2.7
use the <b class="const">host</b> field to represent a Windows drive letter and the colon that follows it, and the <b class="const">path</b> field to represent the filename path after the colon. Such URIs are invalid, and are not recognized by any RFC. When the quirk option <em>HostAsDriveLetter</em> is <b class="const">true</b>, this behavior is also used in version 1.2.7. To use <i class="term"><a href="../../../../index.html#file">file</a></i> URIs on Windows that conform to RFC 3986, set this quirk option to <b class="const">false</b> (the default).</p>
<p>Using this quirk is <em>NOT</em> recommended, because if set to <b class="const">true</b> it will cause the <b class="package">uri</b> commands to expect and produce invalid URIs. The option is included only for compatibility with legacy code.</p></dd>
<dt><em>RemoveDoubleSlashes</em></dt>
<dd><p>When a URI is canonicalized by <b class="cmd">uri::canonicalize</b>, its <b class="const">path</b> is normalized by removal of segments "." and "..". RFC 3986 does not mandate
the removal of empty segments "" (i.e. the merger of double slashes, which is a feature of filename normalization but not of URI <b class="const">path</b> normalization): it treats URIs with excess slashes as referring to different resources. When the quirk option <em>RemoveDoubleSlashes</em> is <b class="const">true</b> (the default), empty segments will be removed from <b class="const">path</b>. To prevent removal, and thereby conform to RFC 3986, set this quirk option to <b class="const">false</b>.</p>
<p>Using this quirk is a matter of preference. A URI with double slashes in its path was most likely generated by error, certainly so if it has a straightforward mapping to a file on a server. In some cases it may be better to sanitize the URI; in others, to keep the URI and let the server handle the possible error.</p></dd>
</dl>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">BACKWARD COMPATIBILITY</a></h3>
<p>To behave as similarly as possible to versions of <b class="package">uri</b> earlier than 1.2.7, set the following quirk options:</p>
<ul class="doctools_itemized">
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoInitialSlash</i> 1</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoExtraKeys</i> 1</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">HostAsDriveLetter</i> 1</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">RemoveDoubleSlashes</i> 0</p></li>
</ul>
<p>In code that can tolerate the return by <b class="cmd">uri::split</b> of an additional key <b class="const">pbare</b>, set</p>
<ul class="doctools_itemized">
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoExtraKeys</i> 0</p></li>
</ul>
<p>in order to achieve greater compliance with RFC 3986.</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">NEW DESIGNS</a></h3>
<p>For new projects, the following settings are recommended:</p>
<ul class="doctools_itemized">
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoInitialSlash</i> 0</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoExtraKeys</i> 0</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">HostAsDriveLetter</i> 0</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">RemoveDoubleSlashes</i> 0|1</p></li>
</ul>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">DEFAULT VALUES</a></h3>
<p>The default values for package <b class="package">uri</b> version 1.2.7 are intended to be a compromise between backwards compatibility and improved features. Different default values may be chosen in future versions of package <b class="package">uri</b>.</p>
<ul class="doctools_itemized">
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoInitialSlash</i> 1</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">NoExtraKeys</i> 0</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">HostAsDriveLetter</i> 0</p></li>
<li><p><b class="cmd">uri::setQuirkOption</b> <i class="arg">RemoveDoubleSlashes</i> 1</p></li>
</ul>
</div>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">EXAMPLES</a></h2>
<p>A Windows® local filename such as "<b class="const">C:\Other Files\startup.txt</b>" is not suitable for use as the <b class="const">path</b> element of a URI in the scheme <i class="term"><a href="../../../../index.html#file">file</a></i>.</p>
<p>The Tcl command <b class="cmd">file normalize</b> will convert the backslashes to forward slashes. To generate a valid <b class="const">path</b> for the scheme <i class="term"><a href="../../../../index.html#file">file</a></i>, the normalized filename must be prepended with "<b class="const">/</b>", and then any characters that do not match the <b class="cmd">regexp</b> bracket expression</p>
<pre class="doctools_example">
[a-zA-Z0-9$_.+!*'(,)?:@&=-]
</pre>
<p>must be percent-encoded.</p>
<p>The result in this example is "<b class="const">/C:/Other%20Files/startup.txt</b>" which is a valid value for <b class="const">path</b>.</p>
<pre class="doctools_example">
% uri::join path /C:/Other%20Files/startup.txt scheme file
file:///C:/Other%20Files/startup.txt
% uri::split file:///C:/Other%20Files/startup.txt
path /C:/Other%20Files/startup.txt scheme file
</pre>
<p>On UNIX® systems filenames begin with "<b class="const">/</b>" which is also used as the directory separator. The only action needed to convert a filename to a valid <b class="const">path</b> is percent-encoding.</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">CREDITS</a></h2>
<p>Original code (regular expressions) by Andreas Kupries.
Modularisation by Steve Ball, also the split/join/resolve
functionality. RFC 3986 conformance by Keith Nash.</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>uri</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fetching_information">fetching information</a>, <a href="../../../../index.html#file">file</a>, <a href="../../../../index.html#ftp">ftp</a>, <a href="../../../../index.html#gopher">gopher</a>, <a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#https">https</a>, <a href="../../../../index.html#ldap">ldap</a>, <a href="../../../../index.html#mailto">mailto</a>, <a href="../../../../index.html#news">news</a>, <a href="../../../../index.html#prospero">prospero</a>, <a href="../../../../index.html#rfc_1630">rfc 1630</a>, <a href="../../../../index.html#rfc_2255">rfc 2255</a>, <a href="../../../../index.html#rfc_2396">rfc 2396</a>, <a href="../../../../index.html#rfc_3986">rfc 3986</a>, <a href="../../../../index.html#uri">uri</a>, <a href="../../../../index.html#url">url</a>, <a href="../../../../index.html#wais">wais</a>, <a href="../../../../index.html#www">www</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/uri/urn-scheme.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<div class='fossil-doc' data-title='uri_urn - Tcl Uniform Resource Identifier Management'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">uri_urn(n) 1.0.3 tcllib "Tcl Uniform Resource Identifier Management"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>uri_urn - URI utilities, URN scheme</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.2</b></li>
<li>package require <b class="pkgname">uri::urn <span class="opt">?1.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">uri::urn::quote</b> <i class="arg">url</i></a></li>
<li><a href="#2"><b class="cmd">uri::urn::unquote</b> <i class="arg">url</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides two commands to quote and unquote the disallowed
characters for url using the <i class="term"><a href="../../../../index.html#urn">urn</a></i> scheme, registers the scheme
with the package <b class="package"><a href="uri.html">uri</a></b>, and provides internal helpers which
will be automatically used by the commands <b class="cmd">uri::split</b> and
<b class="cmd">uri::join</b> of package <b class="package"><a href="uri.html">uri</a></b> to handle urls using the
<i class="term"><a href="../../../../index.html#urn">urn</a></i> scheme.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">uri::urn::quote</b> <i class="arg">url</i></a></dt>
<dd><p>This command quotes the characters disallowed by the <i class="term"><a href="../../../../index.html#urn">urn</a></i> scheme
(per RFC 2141 sec2.2) in the <i class="arg">url</i> and returns the modified url as
its result.</p></dd>
<dt><a name="2"><b class="cmd">uri::urn::unquote</b> <i class="arg">url</i></a></dt>
<dd><p>This commands performs the reverse of <b class="cmd">::uri::urn::quote</b>. It
takes an <i class="term"><a href="../../../../index.html#urn">urn</a></i> url, removes the quoting from all disallowed
characters, and returns the modified urls as its result.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>uri</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#rfc_2141">rfc 2141</a>, <a href="../../../../index.html#uri">uri</a>, <a href="../../../../index.html#url">url</a>, <a href="../../../../index.html#urn">urn</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/uuid/uuid.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<div class='fossil-doc' data-title='uuid - uuid'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">uuid(n) 1.0.6 tcllib "uuid"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>uuid - UUID generation and comparison</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">REFERENCES</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">uuid <span class="opt">?1.0.6?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::uuid::uuid generate</b></a></li>
<li><a href="#2"><b class="cmd">::uuid::uuid equal</b> <i class="arg">id1</i> <i class="arg">id2</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a generator of universally unique identifiers
(UUID) also known as globally unique identifiers (GUID). This
implementation follows the draft specification from (1) although this
is actually an expired draft document.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::uuid::uuid generate</b></a></dt>
<dd><p>Creates a type 4 uuid by MD5 hashing a number of bits of variant data
including the time and hostname.
Returns the string representation of the new uuid.</p></dd>
<dt><a name="2"><b class="cmd">::uuid::uuid equal</b> <i class="arg">id1</i> <i class="arg">id2</i></a></dt>
<dd><p>Compares two uuids and returns true if both arguments are the same uuid.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<pre class="doctools_example">
% uuid::uuid generate
b12dc22c-5c36-41d2-57da-e29d0ef5839c
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">REFERENCES</a></h2>
<ol class="doctools_enumerated">
<li><p>Paul J. Leach, "UUIDs and GUIDs", February 1998.
(<a href="http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt">http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt</a>)</p></li>
</ol>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>uuid</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#guid">GUID</a>, <a href="../../../../index.html#uuid">UUID</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Hashes, checksums, and encryption</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2004, Pat Thoyts <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/cc_amex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<div class='fossil-doc' data-title='valtype::creditcard::amex - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::creditcard::amex(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::creditcard::amex - Validation for AMEX creditcard number</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn</b></li>
<li>package require <b class="pkgname">valtype::creditcard::amex <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::creditcard::amex</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::creditcard::amex</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for an AMEX creditcard number.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::creditcard::amex validate .... ;# Does nothing
valtype::creditcard::amex validate .... ;# Throws an error (bad American Expresss creditcard number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::creditcard::amex</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::creditcard::amex</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">CREDITCARD AMEX</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID CREDITCARD AMEX CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be an AMEX creditcard number.</p></dd>
<dt>INVALID CREDITCARD AMEX CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID CREDITCARD AMEX LENGTH</dt>
<dd><p>The input value is of the wrong length to be an AMEX creditcard number.</p></dd>
<dt>INVALID CREDITCARD AMEX PREFIX</dt>
<dd><p>The input value does not start with the magic value(s) required for it
to be an AMEX creditcard number.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#amex">AMEX</a>, <a href="../../../../index.html#american_express">American Express</a>, <a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#bank">bank</a>, <a href="../../../../index.html#card_for_credit">card for credit</a>, <a href="../../../../index.html#credit_card">credit card</a>, <a href="../../../../index.html#finance">finance</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/cc_discover.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<div class='fossil-doc' data-title='valtype::creditcard::discover - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::creditcard::discover(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::creditcard::discover - Validation for Discover creditcard number</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn</b></li>
<li>package require <b class="pkgname">valtype::creditcard::discover <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::creditcard::discover</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::creditcard::discover</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for a Discover creditcard number.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::creditcard::discover validate .... ;# Does nothing
valtype::creditcard::discover validate .... ;# Throws an error (bad Discover creditcard number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::creditcard::discover</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::creditcard::discover</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">CREDITCARD DISCOVER</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID CREDITCARD DISCOVER CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a Discover creditcard number.</p></dd>
<dt>INVALID CREDITCARD DISCOVER CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID CREDITCARD DISCOVER LENGTH</dt>
<dd><p>The input value is of the wrong length to be a Discover creditcard number.</p></dd>
<dt>INVALID CREDITCARD DISCOVER PREFIX</dt>
<dd><p>The input value does not start with the magic value(s) required for it
to be a Discover creditcard number.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#discover">Discover</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#bank">bank</a>, <a href="../../../../index.html#card_for_credit">card for credit</a>, <a href="../../../../index.html#credit_card">credit card</a>, <a href="../../../../index.html#finance">finance</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/cc_mastercard.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<div class='fossil-doc' data-title='valtype::creditcard::mastercard - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::creditcard::mastercard(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::creditcard::mastercard - Validation for Mastercard creditcard number</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn</b></li>
<li>package require <b class="pkgname">valtype::creditcard::mastercard <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::creditcard::mastercard</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::creditcard::mastercard</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for a Mastercard creditcard number.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::creditcard::mastercard validate .... ;# Does nothing
valtype::creditcard::mastercard validate .... ;# Throws an error (bad Mastercard creditcard number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::creditcard::mastercard</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::creditcard::mastercard</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">CREDITCARD MASTERCARD</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID CREDITCARD MASTERCARD CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a Mastercard creditcard number.</p></dd>
<dt>INVALID CREDITCARD MASTERCARD CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID CREDITCARD MASTERCARD LENGTH</dt>
<dd><p>The input value is of the wrong length to be a Mastercard creditcard number.</p></dd>
<dt>INVALID CREDITCARD MASTERCARD PREFIX</dt>
<dd><p>The input value does not start with the magic value(s) required for it
to be a Mastercard creditcard number.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#mastercard">MasterCard</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#bank">bank</a>, <a href="../../../../index.html#card_for_credit">card for credit</a>, <a href="../../../../index.html#credit_card">credit card</a>, <a href="../../../../index.html#finance">finance</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/cc_visa.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<div class='fossil-doc' data-title='valtype::creditcard::visa - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::creditcard::visa(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::creditcard::visa - Validation for VISA creditcard number</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn</b></li>
<li>package require <b class="pkgname">valtype::creditcard::visa <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::creditcard::visa</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::creditcard::visa</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for a VISA creditcard number.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::creditcard::visa validate .... ;# Does nothing
valtype::creditcard::visa validate .... ;# Throws an error (bad VISA creditcard number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::creditcard::visa</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::creditcard::visa</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">CREDITCARD VISA</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID CREDITCARD VISA CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a VISA creditcard number.</p></dd>
<dt>INVALID CREDITCARD VISA CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID CREDITCARD VISA LENGTH</dt>
<dd><p>The input value is of the wrong length to be a VISA creditcard number.</p></dd>
<dt>INVALID CREDITCARD VISA PREFIX</dt>
<dd><p>The input value does not start with the magic value(s) required for it
to be a VISA creditcard number.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#visa">VISA</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#bank">bank</a>, <a href="../../../../index.html#card_for_credit">card for credit</a>, <a href="../../../../index.html#credit_card">credit card</a>, <a href="../../../../index.html#finance">finance</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/ean13.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<div class='fossil-doc' data-title='valtype::gs1::ean13 - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::gs1::ean13(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::gs1::ean13 - Validation for EAN13</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::gs1::ean13 <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::gs1::ean13</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::gs1::ean13</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for an EAN13.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::gs1::ean13 validate .... ;# Does nothing
valtype::gs1::ean13 validate .... ;# Throws an error (bad EAN13).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::gs1::ean13</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::gs1::ean13</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">EAN13</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID EAN13 CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be an EAN13.</p></dd>
<dt>INVALID EAN13 CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID EAN13 LENGTH</dt>
<dd><p>The input value is of the wrong length to be an EAN13.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#ean">EAN</a>, <a href="../../../../index.html#ean13">EAN13</a>, <a href="../../../../index.html#european_article_number">European Article Number</a>, <a href="../../../../index.html#international_article_number">International Article Number</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/iban.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<div class='fossil-doc' data-title='valtype::iban - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::iban(n) 1.7 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::iban - Validation for IBAN</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::iban <span class="opt">?1.7?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::iban</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::iban</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for an IBAN.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::iban validate .... ;# Does nothing
valtype::iban validate .... ;# Throws an error (bad International Bank Account Number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::iban</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::iban</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">IBAN</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID IBAN CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be an IBAN.</p></dd>
<dt>INVALID IBAN CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#iban">IBAN</a>, <a href="../../../../index.html#international_bank_account_number">International Bank Account Number</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#bank">bank</a>, <a href="../../../../index.html#finance">finance</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/imei.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<div class='fossil-doc' data-title='valtype::imei - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::imei(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::imei - Validation for IMEI</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn</b></li>
<li>package require <b class="pkgname">valtype::imei <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::imei</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::imei</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for an IMEI.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::imei validate .... ;# Does nothing
valtype::imei validate .... ;# Throws an error (bad International Mobile Equipment Identity (IMEI) number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::imei</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::imei</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">IMEI</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID IMEI CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be an IMEI.</p></dd>
<dt>INVALID IMEI CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID IMEI LENGTH</dt>
<dd><p>The input value is of the wrong length to be an IMEI.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#imei">IMEI</a>, <a href="../../../../index.html#international_mobile_equipment_identity">International Mobile Equipment Identity</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#cell_phone">cell-phone</a>, <a href="../../../../index.html#isa">isA</a>, <a href="../../../../index.html#mobile_phone">mobile phone</a>, <a href="../../../../index.html#phone">phone</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/isbn.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
<div class='fossil-doc' data-title='valtype::isbn - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::isbn(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::isbn - Validation for ISBN</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::isbn <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::isbn</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::isbn</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
<li><a href="#3"><b class="cmd">valtype::isbn</b> <b class="method">13of</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for an ISBN.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::isbn validate .... ;# Does nothing
valtype::isbn validate .... ;# Throws an error (bad ISBN).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::isbn</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::isbn</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
<dt><a name="3"><b class="cmd">valtype::isbn</b> <b class="method">13of</b> <i class="arg">value</i></a></dt>
<dd><p>This method expects an old-style 10-digit ISBN and returns the
canonical modern 13-digit ISBN.
This is used by <b class="method">validate</b> to canonicalize the input, so that
all parts of the system after the validation can expect to work with
modern 13-digit ISBNs.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">ISBN</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID ISBN CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be an ISBN.</p></dd>
<dt>INVALID ISBN CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID ISBN LENGTH</dt>
<dd><p>The input value is of the wrong length to be an ISBN.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#book_number">Book Number</a>, <a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#ean">EAN</a>, <a href="../../../../index.html#ean13">EAN13</a>, <a href="../../../../index.html#european_article_number">European Article Number</a>, <a href="../../../../index.html#isbn">ISBN</a>, <a href="../../../../index.html#international_article_number">International Article Number</a>, <a href="../../../../index.html#international_standard_book_number">International Standard Book Number</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/luhn.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<div class='fossil-doc' data-title='valtype::luhn - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::luhn(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::luhn - Validation for plain number with a LUHN checkdigit</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::luhn</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::luhn</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for a plain number with a LUHN checkdigit.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::luhn validate .... ;# Does nothing
valtype::luhn validate .... ;# Throws an error (bad luhn checkdigit).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::luhn</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::luhn</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">LUHN</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID LUHN CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a plain number with a LUHN checkdigit.</p></dd>
<dt>INVALID LUHN CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a>, <a href="../../../../index.html#luhn">luhn</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/luhn5.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<div class='fossil-doc' data-title='valtype::luhn5 - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::luhn5(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::luhn5 - Validation for plain number with a LUHN5 checkdigit</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn5 <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::luhn5</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::luhn5</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for a plain number with a LUHN5 checkdigit.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::luhn5 validate .... ;# Does nothing
valtype::luhn5 validate .... ;# Throws an error (bad luhn5 checkdigit).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::luhn5</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::luhn5</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">LUHN5</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID LUHN5 CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a plain number with a LUHN5 checkdigit.</p></dd>
<dt>INVALID LUHN5 CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a>, <a href="../../../../index.html#luhn">luhn</a>, <a href="../../../../index.html#luhn_5">luhn-5</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/usnpi.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<div class='fossil-doc' data-title='valtype::usnpi - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::usnpi(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::usnpi - Validation for USNPI</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::luhn</b></li>
<li>package require <b class="pkgname">valtype::usnpi <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::usnpi</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::usnpi</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for an USNPI.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::usnpi validate .... ;# Does nothing
valtype::usnpi validate .... ;# Throws an error (bad US National Provider Identifier (US-NPI) number).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::usnpi</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::usnpi</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">USNPI</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID USNPI CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be an USNPI.</p></dd>
<dt>INVALID USNPI CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID USNPI LENGTH</dt>
<dd><p>The input value is of the wrong length to be an USNPI.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#npi">NPI</a>, <a href="../../../../index.html#national_provider_identifier">National Provider Identifier</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#us_npi">US-NPI</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a>, <a href="../../../../index.html#medicare">medicare</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/valtype_common.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<div class='fossil-doc' data-title='valtype::common - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::common(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::common - Validation, common code</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">valtype::common <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::common::reject</b> <i class="arg">code</i> <i class="arg">text</i></a></li>
<li><a href="#2"><b class="cmd">valtype::common::badchar</b> <i class="arg">code</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#3"><b class="cmd">valtype::common::badcheck</b> <i class="arg">code</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#4"><b class="cmd">valtype::common::badlength</b> <i class="arg">code</i> <i class="arg">lengths</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
<li><a href="#5"><b class="cmd">valtype::common::badprefix</b> <i class="arg">code</i> <i class="arg">prefixes</i> <span class="opt">?<i class="arg">text</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a number of common commands used by the
validation types in this module. These commands essentially
encapsulate the throwing of validation errors, ensuring that a proper
<b class="cmd">-errorcode</b> is used. See section <span class="sectref"><a href="#section3">Error Codes</a></span>.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::common::reject</b> <i class="arg">code</i> <i class="arg">text</i></a></dt>
<dd><p>The core command of this package it throws an <b class="const">INVALID</b> error
with the specified <i class="arg">text</i>. The first argument is a list of codes
extending the <b class="const">INVALID</b> with detail information.</p></dd>
<dt><a name="2"><b class="cmd">valtype::common::badchar</b> <i class="arg">code</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This command throws an <b class="const">INVALID CHAR</b> error with the specified
<i class="arg">text</i>. The first argument is a list of codes providing
details. These are inserted between the codes <b class="const">INVALID</b> and
<b class="const">CHARACTER</b>.</p></dd>
<dt><a name="3"><b class="cmd">valtype::common::badcheck</b> <i class="arg">code</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This command throws an <b class="const">INVALID CHECK-DIGIT</b> error with the
specified <i class="arg">text</i>, if any, extended by the standard text "the check
digit is incorrect". The first argument is a list of codes providing
details. These are inserted between the codes <b class="const">INVALID</b> and
<b class="const">CHECK_DIGIT</b>.</p></dd>
<dt><a name="4"><b class="cmd">valtype::common::badlength</b> <i class="arg">code</i> <i class="arg">lengths</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This command throws an <b class="const">INVALID LENGTH</b> error with the
specified <i class="arg">text</i>, if any, extended by the standard text "incorrect
length, expected ... character(s)". The first argument is a list of
codes providing details.
These are inserted between the codes <b class="const">INVALID</b> and
<b class="const">LENGTH</b>. The argument <i class="arg">lengths</i> is a list of the input
lengths which had been expected, i.e. these are the valid lengths.</p></dd>
<dt><a name="5"><b class="cmd">valtype::common::badprefix</b> <i class="arg">code</i> <i class="arg">prefixes</i> <span class="opt">?<i class="arg">text</i>?</span></a></dt>
<dd><p>This command throws an <b class="const">INVALID PREFIX</b> error with the
specified <i class="arg">text</i>, if any, extended by the standard text "incorrect
prefix, expected ...". The first argument is a list of codes providing
details.
These are inserted between the codes <b class="const">INVALID</b> and
<b class="const">PREFIX</b>. The argument <i class="arg">prefixes</i> is a list of the input
prefixes which had been expected, i.e. these are the valid prefixes.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>The errors thrown by the commands of this package all use the
<b class="cmd">-errorcode</b> <b class="const">INVALID</b> to distinguish the input validation
failures they represent from package internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. This is
supplied by the caller. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can be
thrown by this package are shown below, with <b class="const"><></b> a placeholder
for both the caller-supplied type-information, the type description.</p>
<dl class="doctools_definitions">
<dt>INVALID <b class="const"><></b> CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a <b class="const"><></b>.</p></dd>
<dt>INVALID <b class="const"><></b> CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
<dt>INVALID <b class="const"><></b> LENGTH</dt>
<dd><p>The input value is of the wrong length to be a <b class="const"><></b>.</p></dd>
<dt>INVALID <b class="const"><></b> PREFIX</dt>
<dd><p>The input value does not start with the magic value(s) required for it
to be a <b class="const"><></b>.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/valtype/verhoeff.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<div class='fossil-doc' data-title='valtype::verhoeff - Validation types'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">valtype::verhoeff(n) 1 tcllib "Validation types"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>valtype::verhoeff - Validation for plain number with a VERHOEFF checkdigit</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Error Codes</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">snit 2</b></li>
<li>package require <b class="pkgname">valtype::common</b></li>
<li>package require <b class="pkgname">valtype::verhoeff <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">valtype::verhoeff</b> <b class="method">validate</b> <i class="arg">value</i></a></li>
<li><a href="#2"><b class="cmd">valtype::verhoeff</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package implements a snit validation type for a plain number with a VERHOEFF checkdigit.</p>
<p>A validation type is an object that can be used to validate Tcl values
of a particular kind. For example, <b class="cmd">snit::integer</b>, a validation
type defined by the <b class="package"><a href="../snit/snit.html">snit</a></b> package is used to validate that a
Tcl value is an integer.</p>
<p>Every validation type has a <b class="method">validate</b> method which is used to
do the validation. This method must take a single argument, the value
to be validated; further, it must do nothing if the value is valid,
but throw an error if the value is invalid:</p>
<pre class="doctools_example">
valtype::verhoeff validate .... ;# Does nothing
valtype::verhoeff validate .... ;# Throws an error (bad verhoeff checkdigit).
</pre>
<p>The <b class="method">validate</b> method will always return the validated value on
success, and throw the <b class="cmd">-errorcode</b> INVALID on error, possibly
with additional elements which provide more details about the problem.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<p>The API provided by this package satisfies the specification
of snit validation types found in the documentation of
<i class="term"><a href="../snit/snit.html">Snit's Not Incr Tcl</a></i>.</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">valtype::verhoeff</b> <b class="method">validate</b> <i class="arg">value</i></a></dt>
<dd><p>This method validates the <i class="arg">value</i> and returns it, possibly in a
canonical form, if it passes. If the value does not pass the
validation an error is thrown.</p></dd>
<dt><a name="2"><b class="cmd">valtype::verhoeff</b> <b class="method">checkdigit</b> <i class="arg">value</i></a></dt>
<dd><p>This method computes a check digit for the <i class="arg">value</i>. Before doing
so it is validated, except for a checkdigit. If the value does not
pass the validation no check digit is calculated and an error is
thrown instead.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Error Codes</a></h2>
<p>As said in the package description, the errors thrown by the commands
of this package in response to input validation failures use the
<b class="cmd">-errorcode</b> INVALID to distinguish themselves from package
internal errors.</p>
<p>To provide more detailed information about why the validation
failed the <b class="cmd">-errorCode</b> goes actually beyond that.
First, it will contain a code detailing the type itself. Here this is
<b class="const">VERHOEFF</b>. This is then followed by values detailing the
reason for the failure. The full set of <b class="cmd">-errorCode</b>s which can
be thrown by this package are:</p>
<dl class="doctools_definitions">
<dt>INVALID VERHOEFF CHARACTER</dt>
<dd><p>The input value contained one or more bad characters, i.e. characters
which must not occur in the input for it to be a plain number with a VERHOEFF checkdigit.</p></dd>
<dt>INVALID VERHOEFF CHECK-DIGIT</dt>
<dd><p>The check digit of the input value is wrong. This usually signals a
data-entry error, with digits transposed, forgotten, etc. Of course,
th input may be an outright fake too.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>valtype</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#checking">Checking</a>, <a href="../../../../index.html#testing">Testing</a>, <a href="../../../../index.html#type_checking">Type checking</a>, <a href="../../../../index.html#validation">Validation</a>, <a href="../../../../index.html#value_checking">Value checking</a>, <a href="../../../../index.html#isa">isA</a>, <a href="../../../../index.html#verhoeff">verhoeff</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Validation, Type checking</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/cat.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<div class='fossil-doc' data-title='tcl::chan::cat - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::cat(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::cat - Concatenation channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::cat <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::cat</b> <i class="arg">chan</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::cat</b> package provides a command creating
concatenation channels. These are non-seekable channels owning a list
of subordinate channels whose contents they return in order, until all
are exhausted. In this manner the channel is the concatentation of the
contents of all the sub-ordinate channels.</p>
<p>Note that the created channels take ownership of the channels
they were constructed with. Whenever they have exhausted one of their
channel it will be closed. Similarly, closing the cat channel will
close all the sub-ordinates it still has.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/core.html">tcl::chan::core</a></b> framework.</p>
<p>Event handling is delegated to the currently active sub-channel.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::cat</b> <i class="arg">chan</i>...</a></dt>
<dd><p>This command creates the concatenation channel using all the provided
channels, and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#concatenation_channel">concatenation channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/facade.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<div class='fossil-doc' data-title='tcl::chan::facade - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::facade(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::facade - Facade channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">tcl::chan::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::facade <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::facade</b> <i class="arg">chan</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::facade</b> package provides a command creating
facades to other channels. These are channels which own a single
subordinate channel and delegate all operations to.</p>
<p>The main use for facades is the debugging of actions on a
channel. While most of the information could be tracked by a virtual
channel transformation it does not have access to the event-related
operation, and furthermore they are only available in Tcl 8.6.</p>
<p>Therefore this channel, usable with Tcl 8.5, and having access
to everything going on for a channel.</p>
<p>The intercepted actions on channel are logged through package
<b class="package"><a href="../log/logger.html">logger</a></b>.</p>
<p>Beyond that facades provide the following additional channel
configuration options:</p>
<dl class="doctools_options">
<dt><b class="option">-self</b></dt>
<dd><p>The TclOO object handling the facade.</p></dd>
<dt><b class="option">-fd</b></dt>
<dd><p>The handle of the subordinate, i.e. wrapped channel.</p></dd>
<dt><b class="option">-used</b></dt>
<dd><p>The last time the wrapped channel was read from or written to by
the facade, as per <b class="cmd">clock milliseconds</b>. A value of <b class="const">0</b>
indicates that the subordinate channel was not accessed at all, yet.</p></dd>
<dt><b class="option">-created</b></dt>
<dd><p>The time the facade was created, as per <b class="cmd">clock milliseconds</b>.</p></dd>
<dt><b class="option">-user</b></dt>
<dd><p>A free-form value identifying the user of the facade and its
wrapped channel.</p></dd>
</dl>
<p>Of these only option <b class="option">-user</b> is writable.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::facade</b> <i class="arg">chan</i></a></dt>
<dd><p>This command creates the facade channel around the provided
channel <i class="arg">chan</i>, and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#concatenation_channel">concatenation channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<div class='fossil-doc' data-title='tcl::chan::halfpipe - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::halfpipe(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::halfpipe - In-memory channel, half of a fifo2</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Options</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::halfpipe <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::halfpipe <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::halfpipe</b> <span class="opt">?<b class="option">-option</b> <i class="arg">value</i>...?</span></a></li>
<li><a href="#2"><i class="arg">objectCmd</i> <b class="method">put</b> <i class="arg">bytes</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::halfpipe</b> package provides a command creating
one half of a <b class="package"><a href="tcllib_fifo2.html">tcl::chan::fifo2</a></b> pair. Writing into such a
channel invokes a set of callbacks which then handle the data. This is
similar to a channel handler, except having a much simpler API.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::halfpipe</b> <span class="opt">?<b class="option">-option</b> <i class="arg">value</i>...?</span></a></dt>
<dd><p>This command creates a halfpipe channel and configures it with the
callbacks to run when the channel is closed, data was written to it,
or ran empty. See the section <span class="sectref"><a href="#section3">Options</a></span> for the list of
options and associated semantics.
The result of the command is a list containing two elements, the
handle of the new channel, and the object command of the channel
handler, in this order.
The latter is supplied to the caller to provide her with access to the
<b class="method">put</b> method for adding data to the channel.</p>
<p>Two halfpipes with a bit of glue logic in the callbacks make
for one <b class="package"><a href="tcllib_fifo2.html">tcl::chan::fifo2</a></b>.</p></dd>
<dt><a name="2"><i class="arg">objectCmd</i> <b class="method">put</b> <i class="arg">bytes</i></a></dt>
<dd><p>This method of the channel handler object puts the data <i class="arg">bytes</i>
into the channel so that it can be read from it.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Options</a></h2>
<dl class="doctools_options">
<dt><b class="option">-close-command</b> cmdprefix</dt>
<dd><p>This callback is invoked when the channel is closed.
A single argument is supplied, the handle of the channel being closed.
The result of the callback is ignored.</p></dd>
<dt><b class="option">-write-command</b> cmdprefix</dt>
<dd><p>This callback is invoked when data is written to the channel.
Two arguments are supplied, the handle of the channel written to, and the data written.
The result of the callback is ignored.</p></dd>
<dt><b class="option">-empty-command</b> cmdprefix</dt>
<dd><p>This callback is invoked when the channel has run out of data to read.
A single argument is supplied, the handle of the channel.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#callbacks">callbacks</a>, <a href="../../../../index.html#fifo">fifo</a>, <a href="../../../../index.html#in_memory_channel">in-memory channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='tcl::chan::nullzero - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::nullzero(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::nullzero - Null/Zero channel combination</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::nullzero <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::nullzero</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::nullzero</b> package provides a command creating channels,
which are a combination of null and zero devices. They immediately forget
whatever is written to them, and on reading return an infinite stream of null
characters.</p>
<p>Packages related to this are <b class="package"><a href="tcllib_null.html">tcl::chan::null</a></b> and
<b class="package"><a href="tcllib_zero.html">tcl::chan::zero</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel handler
is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::nullzero</b></a></dt>
<dd><p>This command creates a new nullzero channel and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_dev_null">/dev/null</a>, <a href="../../../../index.html#_dev_zero">/dev/zero</a>, <a href="../../../../index.html#null">null</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a>, <a href="../../../../index.html#zero">zero</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/randseed.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='tcl::randomseed - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::randomseed(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::randomseed - Utilities for random channels</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::randomseed <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::randomseed</b></a></li>
<li><a href="#2"><b class="cmd">::tcl::combine</b> <i class="arg">seed1</i> <i class="arg">seed2</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::randomseed</b> package provides a a few utility commands
to help with the seeding of <b class="package"><a href="tcllib_random.html">tcl::chan::random</a></b> channels.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::randomseed</b></a></dt>
<dd><p>This command creates returns a list of seed integers suitable as seed
argument for random channels. The numbers are derived from the process
id, current time, and Tcl random number generator.</p></dd>
<dt><a name="2"><b class="cmd">::tcl::combine</b> <i class="arg">seed1</i> <i class="arg">seed2</i></a></dt>
<dd><p>This command takes to seed lists and combines them into a single list
by XORing them elementwise, modulo 256. If the lists are not of equial
length the shorter of the two is padded with 0s before merging.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_dev_random">/dev/random</a>, <a href="../../../../index.html#merge">merge</a>, <a href="../../../../index.html#random">random</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#seed">seed</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/std.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='tcl::chan::std - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::std(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::std - Standard I/O, unification of stdin and stdout</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::std <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::std</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::std</b> package provides a command creating
a standard channel which unifies stdin and stdout into a single
read- and writable channel. The result is not seek-able, like
the original standard channels.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/core.html">tcl::chan::core</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::std</b></a></dt>
<dd><p>This command creates the std channel and returns its handle.</p>
<p>The channel is created only once, on the first call, and all
future calls simply return this handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#standard_io">standard io</a>, <a href="../../../../index.html#stdin">stdin</a>, <a href="../../../../index.html#stdout">stdout</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
<div class='fossil-doc' data-title='tcl::chan::fifo - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::fifo(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::fifo - In-memory fifo channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::fifo <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::fifo</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::fifo</b> package provides a command creating
channels which live purely in memory. Access is fifo-like, i.e. things
are read out of the channel in the order they were written to it.
This is equivalent to the fifo channels provided by the package
<b class="package">Memchan</b>, except that this is written in pure Tcl, not C. On
the other hand, <b class="package">Memchan</b> is usable with Tcl 8.4 and before,
whereas this package requires Tcl 8.5 or higher, and <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::fifo</b></a></dt>
<dd><p>This command creates a new fifo channel and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#fifo">fifo</a>, <a href="../../../../index.html#in_memory_channel">in-memory channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo2.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<div class='fossil-doc' data-title='tcl::chan::fifo2 - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::fifo2(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::fifo2 - In-memory interconnected fifo channels</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::halfpipe <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::fifo2 <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::fifo2</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::fifo2</b> package provides a command creating
pairs of channels which live purely in memory and are connected to
each other in a fifo manner. What is written to one half of the pair
can be read from the other half, in the same order. One particular
application for this is communication between threads, with one half
of the pair moved to the thread to talk to.
This is equivalent to the fifo2 channels provided by the package
<b class="package">Memchan</b>, except that this is written in pure Tcl, not C. On
the other hand, <b class="package">Memchan</b> is usable with Tcl 8.4 and before,
whereas this package requires Tcl 8.5 or higher, and <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::fifo2</b></a></dt>
<dd><p>This command creates a new connected pair of fifo channels and returns
their handles, as a list containing two elements.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#connected_fifos">connected fifos</a>, <a href="../../../../index.html#fifo">fifo</a>, <a href="../../../../index.html#in_memory_channel">in-memory channel</a>, <a href="../../../../index.html#inter_thread_communication">inter-thread communication</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_memchan.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<div class='fossil-doc' data-title='tcl::chan::memchan - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::memchan(n) 1.0.4 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::memchan - In-memory channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::memchan <span class="opt">?1.0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::memchan</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::memchan</b> package provides a command creating
channels which live purely in memory. They provide random-access,
i.e. are seekable. This is equivalent to the memchan channels provided by
the package <b class="package">Memchan</b>, except that this is written in pure Tcl,
not C. On the other hand, <b class="package">Memchan</b> is usable with Tcl 8.4 and
before, whereas this package requires Tcl 8.5 or higher, and
<b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>.</p>
<p>Packages related to this are <b class="package"><a href="tcllib_string.html">tcl::chan::string</a></b> and
<b class="package"><a href="tcllib_variable.html">tcl::chan::variable</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::memchan</b></a></dt>
<dd><p>This command creates a new memchan channel and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#in_memory_channel">in-memory channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009-2017 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_null.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<div class='fossil-doc' data-title='tcl::chan::null - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::null(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::null - Null channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::null <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::null</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::null</b> package provides a command creating null
channels, i.e. write-only channels which immediately forget whatever
is written to them. This is equivalent to the null channels provided by
the package <b class="package">Memchan</b>, except that this is written in pure Tcl,
not C. On the other hand, <b class="package">Memchan</b> is usable with Tcl 8.4 and
before, whereas this package requires Tcl 8.5 or higher, and
<b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>.</p>
<p>Packages related to this are <b class="package"><a href="tcllib_zero.html">tcl::chan::zero</a></b> and
<b class="package"><a href="nullzero.html">tcl::chan::nullzero</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::null</b></a></dt>
<dd><p>This command creates a new null channel and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_dev_null">/dev/null</a>, <a href="../../../../index.html#null">null</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_random.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<div class='fossil-doc' data-title='tcl::chan::random - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::random(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::random - Random channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::random <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::random</b> <i class="arg">seed</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::random</b> package provides a command creating
random channels, i.e. read-only channels which return an infinite
stream of pseudo-random characters upon reading. This is similar to
the random channels provided by the package <b class="package">Memchan</b>, except
that this is written in pure Tcl, not C, and uses a much simpler
generator as well. On the other hand, <b class="package">Memchan</b> is usable with
Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher,
and TclOO.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::random</b> <i class="arg">seed</i></a></dt>
<dd><p>This command creates a new random channel and returns its handle.
The seed is a list of integer numbers used to initialize the
internal feedback shift register of the generator.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_dev_random">/dev/random</a>, <a href="../../../../index.html#random">random</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_string.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<div class='fossil-doc' data-title='tcl::chan::string - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::string(n) 1.0.3 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::string - Read-only in-memory channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::string <span class="opt">?1.0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::string</b> <i class="arg">content</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::string</b> package provides a command creating
channels which live purely in memory. They provide random-access,
i.e. are seekable.
In contrast to the channels created by <b class="package"><a href="tcllib_memchan.html">tcl::chan::memchan</a></b>
they are read-only however, their content is provided at the time of
construction and immutable afterward.</p>
<p>Packages related to this are <b class="package"><a href="tcllib_memchan.html">tcl::chan::memchan</a></b> and
<b class="package"><a href="tcllib_variable.html">tcl::chan::variable</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::string</b> <i class="arg">content</i></a></dt>
<dd><p>This command creates a new string channel and returns its handle. The
channel provides random read-only access to the <i class="arg">content</i> string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#in_memory_channel">in-memory channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_variable.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<div class='fossil-doc' data-title='tcl::chan::variable - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::variable(n) 1.0.4 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::variable - In-memory channel using variable for storage</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::variable <span class="opt">?1.0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::variable</b> <i class="arg">varname</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::variable</b> package provides a command creating
channels which live purely in memory. They provide random-access,
i.e. are seekable.
In contrast to the channels created by <b class="package"><a href="tcllib_memchan.html">tcl::chan::memchan</a></b>
the data is not hidden in the channel however, but stored in an
associated variable, specified at the time of construction.</p>
<p>Packages related to this are <b class="package"><a href="tcllib_memchan.html">tcl::chan::memchan</a></b> and
<b class="package"><a href="tcllib_string.html">tcl::chan::string</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::variable</b> <i class="arg">varname</i></a></dt>
<dd><p>This command creates a new variable channel and returns its handle.
The content of the channel is stored in the associated namespace
variable <i class="arg">varname</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#in_memory_channel">in-memory channel</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/tcllib_zero.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<div class='fossil-doc' data-title='tcl::chan::zero - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::zero(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::zero - Zero channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::zero <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::zero</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::zero</b> package provides a command creating zero
channels, i.e. read-only channels which return an infinite stream of null
characters upon reading. This is equivalent to the zero channels
provided by the package <b class="package">Memchan</b>, except that this is written
in pure Tcl, not C. On the other hand, <b class="package">Memchan</b> is usable with
Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher,
and TclOO.</p>
<p>Packages related to this are <b class="package"><a href="tcllib_null.html">tcl::chan::null</a></b> and
<b class="package"><a href="nullzero.html">tcl::chan::nullzero</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::zero</b></a></dt>
<dd><p>This command creates a new zero channel and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#_dev_zero">/dev/zero</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a>, <a href="../../../../index.html#zero">zero</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<div class='fossil-doc' data-title='tcl::chan::textwindow - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::textwindow(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::textwindow - Textwindow channel</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::textwindow <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::textwindow</b> <i class="arg">widget</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::textwindow</b> package provides a command creating
write-only channels connected to text widgets. Anything written to the
channel is printed into the associated widget.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the channel
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/events.html">tcl::chan::events</a></b> framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::textwindow</b> <i class="arg">widget</i></a></dt>
<dd><p>This command creates a new textwindow channel and returns its handle.
Data written to this channel will appear in the associated <i class="arg">widget</i>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tk">Tk</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#text_widget">text widget</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_core/core.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<div class='fossil-doc' data-title='tcl::chan::core - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::core(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::core - Basic reflected/virtual channel support</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Instance API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::core <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::core</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">initialize</b> <i class="arg">thechannel</i> <i class="arg">mode</i></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">finalize</b> <i class="arg">thechannel</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::core</b> package provides a <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>
class implementing common behaviour needed by virtually every
reflected or virtual channel (initialization, finalization).</p>
<p>This class expects to be used as either superclass of a concrete
channel class, or to be mixed into such a class.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::core</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new channel core object with an associated
global Tcl command whose name is <em>objectName</em>. This command may
be used to invoke various operations on the object, as described in
the section for the <span class="sectref"><a href="#section3">Instance API</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instance API</a></h2>
<p>The API of channel core instances provides only two methods, both
corresponding to channel handler commands (For reference see
<a href="http:/tip.tcl.tk/219">TIP 219</a>). They expect to be called
from whichever object instance the channel core was made a part of.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">initialize</b> <i class="arg">thechannel</i> <i class="arg">mode</i></a></dt>
<dd><p>This method implements standard behaviour for the <b class="method">initialize</b>
method of channel handlers. Using introspection it finds the handler
methods supported by the instance and returns a list containing their
names, as expected by the support for reflected channels in the Tcl
core.</p>
<p>It further remembers the channel handle in an instance variable
for access by sub-classes.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">finalize</b> <i class="arg">thechannel</i></a></dt>
<dd><p>This method implements standard behaviour for the <b class="method">finalize</b>
method of channel handlers. It simply destroys itself.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroying the channel core instance closes the channel it was
initialized for, see the method <b class="method">initialize</b>. When destroyed
from within a call of <b class="method">finalize</b> this does not happen, under
the assumption that the channel is being destroyed by Tcl.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_core/events.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<div class='fossil-doc' data-title='tcl::chan::events - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::chan::events(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::chan::events - Event support for reflected/virtual channels</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Instance API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::chan::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::chan::events <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::chan::events</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">finalize</b> <i class="arg">thechannel</i></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">watch</b> <i class="arg">thechannel</i> <i class="arg">eventmask</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">allow</b> <i class="arg">eventname</i>...</a></li>
<li><a href="#5"><i class="arg">objectName</i> <b class="method">disallow</b> <i class="arg">eventname</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::chan::events</b> package provides a <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>
class implementing common behaviour needed by virtually every
reflected or virtual channel supporting event driven IO. It is a
sub-class of <b class="package"><a href="core.html">tcl::chan::core</a></b>, inheriting all of its behaviour.</p>
<p>This class expects to be used as either superclass of a concrete
channel class, or to be mixed into such a class.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::chan::events</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new channel event core object with an associated
global Tcl command whose name is <em>objectName</em>. This command may
be used to invoke various operations on the object, as described in
the section for the <span class="sectref"><a href="#section3">Instance API</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instance API</a></h2>
<p>The API of channel event core instances provides only four methods, two
corresponding to channel handler commands (For reference see
<a href="http:/tip.tcl.tk/219">TIP 219</a>), and the other two for use by
sub-classes to control event generation. They former expect to be called
from whichever object instance the channel event core was made a part of.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">finalize</b> <i class="arg">thechannel</i></a></dt>
<dd><p>This method implements standard behaviour for the <b class="method">finalize</b>
method of channel handlers. It overrides the behaviour inherited from
<b class="package"><a href="core.html">tcl::chan::core</a></b> and additionally disables any and all event
generation before destroying itself.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">watch</b> <i class="arg">thechannel</i> <i class="arg">eventmask</i></a></dt>
<dd><p>This method implements standard behaviour for the <b class="method">watch</b>
method of channel handlers. Called by the IO system whenever the
interest in event changes it updates the instance state to activate
and/or suppress the generation of the events of (non-)interest.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">allow</b> <i class="arg">eventname</i>...</a></dt>
<dd></dd>
<dt><a name="5"><i class="arg">objectName</i> <b class="method">disallow</b> <i class="arg">eventname</i>...</a></dt>
<dd><p>These two methods are exported to sub-classes, so that their instances
can notify their event core of the events the channel they implement
can (allow) or cannot (disallow) generate.
Together with the information about the events requested by Tcl's IO
system coming in through the <b class="method">watch</b> method the event core is
able to determine which events it should (not) generate and act
accordingly.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#event_management">event management</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<div class='fossil-doc' data-title='tcl::transform::core - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::core(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::core - Basic reflected/virtual channel transform support</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Instance API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.5</b></li>
<li>package require <b class="pkgname">TclOO</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::core</b> <i class="arg">objectName</i></a></li>
<li><a href="#2"><i class="arg">objectName</i> <b class="method">initialize</b> <i class="arg">thechannel</i> <i class="arg">mode</i></a></li>
<li><a href="#3"><i class="arg">objectName</i> <b class="method">finalize</b> <i class="arg">thechannel</i></a></li>
<li><a href="#4"><i class="arg">objectName</i> <b class="method">destroy</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::core</b> package provides a <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b>
class implementing common behaviour needed by virtually every
reflected or virtual channel transformation (initialization, finalization).</p>
<p>This class expects to be used as either superclass of a concrete
channel class, or to be mixed into such a class.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::core</b> <i class="arg">objectName</i></a></dt>
<dd><p>This command creates a new transform core object with an associated
global Tcl command whose name is <em>objectName</em>. This command may
be used to invoke various operations on the object, as described in
the section for the <span class="sectref"><a href="#section3">Instance API</a></span>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instance API</a></h2>
<p>The API of transform core instances provides only two methods, both
corresponding to transform handler commands (For reference see
<a href="http:/tip.tcl.tk/230">TIP 230</a>). They expect to be called
from whichever object instance the transform core was made a part of.</p>
<dl class="doctools_definitions">
<dt><a name="2"><i class="arg">objectName</i> <b class="method">initialize</b> <i class="arg">thechannel</i> <i class="arg">mode</i></a></dt>
<dd><p>This method implements standard behaviour for the <b class="method">initialize</b>
method of transform handlers. Using introspection it finds the handler
methods supported by the instance and returns a list containing their
names, as expected by the support for reflected transformation in the
Tcl core.</p>
<p>It further remembers the channel handle in an instance variable
for access by sub-classes.</p></dd>
<dt><a name="3"><i class="arg">objectName</i> <b class="method">finalize</b> <i class="arg">thechannel</i></a></dt>
<dd><p>This method implements standard behaviour for the <b class="method">finalize</b>
method of channel handlers. It simply destroys itself.</p></dd>
<dt><a name="4"><i class="arg">objectName</i> <b class="method">destroy</b></a></dt>
<dd><p>Destroying the transform core instance closes the channel and transform
it was initialized for, see the method <b class="method">initialize</b>. When destroyed
from within a call of <b class="method">finalize</b> this does not happen, under
the assumption that the channel and transform are being destroyed by Tcl.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_219">tip 219</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<div class='fossil-doc' data-title='tcl::transform::adler32 - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::adler32(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::adler32 - Adler32 transformation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::adler32 <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::adler32</b> <i class="arg">chan</i> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::adler32</b> package provides a command
creating a channel transformation which passes the read and written
bytes through unchanged (like <b class="package"><a href="identity.html">tcl::transform::identity</a></b>), but
additionally continuously computes the adler32 checksums of the data
it has seen for each direction and stores them in Tcl variables
specified at construction time.</p>
<p>Related transformations in this module are
<b class="package"><a href="vt_counter.html">tcl::transform::counter</a></b>,
<b class="package"><a href="vt_crc32.html">tcl::transform::crc32</a></b>,
<b class="package"><a href="identity.html">tcl::transform::identity</a></b>, and
<b class="package"><a href="observe.html">tcl::transform::observe</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::adler32</b> <i class="arg">chan</i> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>This command creates an adler32 checksumming transformation on top of
the channel <i class="arg">chan</i> and returns its handle. The accepted options are</p>
<dl class="doctools_options">
<dt><b class="option">-read-variable</b> varname</dt>
<dd><p>The value of the option is the name of a global or namespaced
variable, the location where the transformation has to store the
adler32 checksum of the data read from the channel.</p>
<p>If not specified, or the empty string, the checksum of the read
direction is not saved.</p></dd>
<dt><b class="option">-write-variable</b> varname</dt>
<dd><p>The value of the option is the name of a global or namespaced
variable, the location where the transformation has to store the
adler32 checksum of the data written to the channel.</p>
<p>If not specified, or the empty string, the checksum of the
write direction is not saved.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#adler32">adler32</a>, <a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#checksum">checksum</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/hex.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='tcl::transform::hex - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::hex(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::hex - Hexadecimal encoding transformation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::hex <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::hex</b> <i class="arg">chan</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::hex</b> package provides a command creating
a channel transformation which hex encodes data written to it, and
decodes the data read from it.</p>
<p>A related transformations in this module is
<b class="package"><a href="vt_base64.html">tcl::transform::base64</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::hex</b> <i class="arg">chan</i></a></dt>
<dd><p>This command creates a hex transformation on top of the channel
<i class="arg">chan</i> and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#hexadecimal">hexadecimal</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/identity.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<div class='fossil-doc' data-title='tcl::transform::identity - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::identity(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::identity - Identity transformation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::identity <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::identity</b> <i class="arg">chan</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::identity</b> package provides a command
creating an identity channel transformation, which does nothing but
pass the read and written bytes through it unchanged. Not really
useful in an application, however as the prototypical observer
transformation its code is a useful starting point for any other
observers people may wish to write.</p>
<p>The transformations in this module which derived from
identity's code are
<b class="package"><a href="adler32.html">tcl::transform::adler32</a></b>,
<b class="package"><a href="vt_counter.html">tcl::transform::counter</a></b>,
<b class="package"><a href="vt_crc32.html">tcl::transform::crc32</a></b>, and
<b class="package"><a href="observe.html">tcl::transform::observe</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::identity</b> <i class="arg">chan</i></a></dt>
<dd><p>This command creates an identity transformation on top of the channel
<i class="arg">chan</i> and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#identity">identity</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<div class='fossil-doc' data-title='tcl::transform::limitsize - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::limitsize(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::limitsize - limiting input</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::limitsize <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::limitsize</b> <i class="arg">chan</i> <i class="arg">max</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::limitsize</b> package provides a command
creating a channel transformation which limits the number of
characters which can be read from the channel. A generator for an
artificial EOF.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::limitsize</b> <i class="arg">chan</i> <i class="arg">max</i></a></dt>
<dd><p>This command creates a size limiting transformation on top of the
channel <i class="arg">chan</i> and returns its handle.</p>
<p><i class="arg">max</i> is the number of bytes which can be read from the
channel before EOF is signaled by the transformation. Note that
popping the transformation clears the EOF it generated as well.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#limitsize">limitsize</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#size_limit">size limit</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/observe.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<div class='fossil-doc' data-title='tcl::transform::observe - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::observe(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::observe - Observer transformation, stream copy</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::observe <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::observe</b> <i class="arg">chan</i> <i class="arg">logw</i> <i class="arg">logr</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::observer</b> package provides a command
creating a channel transformation which passes the read and written
bytes through unchanged (like <b class="package"><a href="identity.html">tcl::transform::identity</a></b>), but
additionally copies the data it has seen for each direction into
channels specified at construction time.</p>
<p>Related transformations in this module are
<b class="package"><a href="adler32.html">tcl::transform::adler32</a></b>,
<b class="package"><a href="vt_counter.html">tcl::transform::counter</a></b>,
<b class="package"><a href="vt_crc32.html">tcl::transform::crc32</a></b>, and
<b class="package"><a href="identity.html">tcl::transform::identity</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::observe</b> <i class="arg">chan</i> <i class="arg">logw</i> <i class="arg">logr</i></a></dt>
<dd><p>This command creates an observer transformation on top of the channel
<i class="arg">chan</i> and returns its handle. The channel handles <i class="arg">logr</i> and
<i class="arg">logw</i> are there the data is copied to.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#observer">observer</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#stream_copy">stream copy</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/rot.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<div class='fossil-doc' data-title='tcl::transform::rot - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::rot(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::rot - rot-encryption</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::rot <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::rot</b> <i class="arg">chan</i> <i class="arg">key</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::rot</b> package provides a command creating
a channel transformation which performs primitive encryption (on
writing) and decryption (on reading) on the alphabetic characters. The
algorithm is the Caesar-cipher, a specific variant of which is rot13.</p>
<p>A related transformations in this module is
<b class="package"><a href="vt_otp.html">tcl::transform::otp</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::rot</b> <i class="arg">chan</i> <i class="arg">key</i></a></dt>
<dd><p>This command creates a rot encryption transformation on top of the
channel <i class="arg">chan</i> and returns its handle.</p>
<p>The "<i class="arg">key</i>" specifies how far characters are rotated in the
alphabet, and is wrapped to the range "0...25".</p>
<p>Note that this transformation affects only bytes in the ranges
ASCII 65...90, and 97...122, i.e. the upper- and lower-case alphabetic
characters, i.e. "A...Z" and "a...z". All other bytes are passed
through unchanged.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#caesar_cipher">caesar cipher</a>, <a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#cipher">cipher</a>, <a href="../../../../index.html#decryption">decryption</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#rot">rot</a>, <a href="../../../../index.html#rot13">rot13</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<div class='fossil-doc' data-title='tcl::transform::spacer - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::spacer(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::spacer - Space insertation and removal</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::spacer <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::spacer</b> <i class="arg">chan</i> <i class="arg">n</i> <span class="opt">?<i class="arg">space</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::spacer</b> package provides a command
creating a channel transformation which adds spacing to the data
written to it, and removes such spacing from the data read from it.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::spacer</b> <i class="arg">chan</i> <i class="arg">n</i> <span class="opt">?<i class="arg">space</i>?</span></a></dt>
<dd><p>This command creates a spacer transformation on top of the channel
<i class="arg">chan</i> and returns its handle.</p>
<p>The <i class="arg">space</i> character sequence will be added every <i class="arg">n</i>
bytes of data written, and on the read side the same is done in
reverse, removing the spacing. If <i class="arg">space</i> is not specified it
defaults to a single space character (ASCII 32).</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#spacing">spacing</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/tcllib_zlib.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='tcl::transform::zlib - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::zlib(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::zlib - zlib (de)compression</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::zlib <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::zlib</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">level</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::zlib</b> package provides a command creating
a channel transformation which zlib compresses the written data, and
decompresses on reading.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::zlib</b> <i class="arg">chan</i> <span class="opt">?<i class="arg">level</i>?</span></a></dt>
<dd><p>This command creates a zlib compressor transformation on top of the
channel <i class="arg">chan</i> and returns its handle.</p>
<p>The <i class="arg">level</i> specifies how much effort is put into the
compression, from <b class="const">0</b> to <b class="const">9</b>, and defaults to <b class="const">4</b>.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#compression">compression</a>, <a href="../../../../index.html#decompression">decompression</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#tip_234">tip 234</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a>, <a href="../../../../index.html#zlib">zlib</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/vt_base64.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<div class='fossil-doc' data-title='tcl::transform::base64 - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::base64(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::base64 - Base64 encoding transformation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::base64 <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::base64</b> <i class="arg">chan</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::base64</b> package provides a command
creating a channel transformation which base64 encodes data written to
it, and decodes the data read from it.</p>
<p>A related transformations in this module is
<b class="package"><a href="hex.html">tcl::transform::hex</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::base64</b> <i class="arg">chan</i></a></dt>
<dd><p>This command creates a base64 transformation on top of the channel
<i class="arg">chan</i> and returns its handle.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#base64">base64</a>, <a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#tip_317">tip 317</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/vt_counter.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<div class='fossil-doc' data-title='tcl::transform::counter - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::counter(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::counter - Counter transformation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::counter <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::counter</b> <i class="arg">chan</i> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::counterr</b> package provides a command
creating a channel transformation which passes the read and written
bytes through unchanged (like <b class="package"><a href="identity.html">tcl::transform::identity</a></b>), but
additionally counts the bytes it has seen for each direction and
stores these counts in Tcl variables specified at construction time.</p>
<p>Related transformations in this module are
<b class="package"><a href="adler32.html">tcl::transform::adler32</a></b>,
<b class="package"><a href="vt_crc32.html">tcl::transform::crc32</a></b>,
<b class="package"><a href="identity.html">tcl::transform::identity</a></b>, and
<b class="package"><a href="observe.html">tcl::transform::observe</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::counter</b> <i class="arg">chan</i> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>This command creates a counter transformation on top of the channel
<i class="arg">chan</i> and returns its handle. The accepted options are</p>
<dl class="doctools_options">
<dt><b class="option">-read-variable</b> varname</dt>
<dd><p>The value of the option is the name of a global or namespaced
variable, the location where the transformation has to store the
byte count of the data read from the channel.</p>
<p>If not specified, or the empty string, the counter of the read
direction is not saved.</p></dd>
<dt><b class="option">-write-variable</b> varname</dt>
<dd><p>The value of the option is the name of a global or namespaced
variable, the location where the transformation has to store the
byte count of the data written to the channel.</p>
<p>If not specified, or the empty string, the counter of the
write direction is not saved.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#counter">counter</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/vt_crc32.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<div class='fossil-doc' data-title='tcl::transform::crc32 - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::crc32(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::crc32 - Crc32 transformation</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::crc32 <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::crc32</b> <i class="arg">chan</i> <b class="option">-option</b> <i class="arg">value</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::crc32</b> package provides a command
creating a channel transformation which passes the read and written
bytes through unchanged (like <b class="package"><a href="identity.html">tcl::transform::identity</a></b>), but
additionally continuously computes the crc32 checksums of the data it
has seen for each direction and stores them in Tcl variables specified
at construction time. The checksum in question is zlib's crc32.</p>
<p>Related transformations in this module are
<b class="package"><a href="adler32.html">tcl::transform::adler32</a></b>,
<b class="package"><a href="vt_counter.html">tcl::transform::counter</a></b>,
<b class="package"><a href="identity.html">tcl::transform::identity</a></b>, and
<b class="package"><a href="observe.html">tcl::transform::observe</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::crc32</b> <i class="arg">chan</i> <b class="option">-option</b> <i class="arg">value</i>...</a></dt>
<dd><p>This command creates a crc32 checksumming transformation on top of
the channel <i class="arg">chan</i> and returns its handle. The accepted options are</p>
<dl class="doctools_options">
<dt><b class="option">-read-variable</b> varname</dt>
<dd><p>The value of the option is the name of a global or namespaced
variable, the location where the transformation has to store the
crc32 checksum of the data read from the channel.</p>
<p>If not specified, or the empty string, the checksum of the read
direction is not saved.</p></dd>
<dt><b class="option">-write-variable</b> varname</dt>
<dd><p>The value of the option is the name of a global or namespaced
variable, the location where the transformation has to store the
crc32 checksum of the data written to the channel.</p>
<p>If not specified, or the empty string, the checksum of the
write direction is not saved.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#checksum">checksum</a>, <a href="../../../../index.html#crc32">crc32</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/virtchannel_transform/vt_otp.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<div class='fossil-doc' data-title='tcl::transform::otp - Reflected/virtual channel support'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">tcl::transform::otp(n) 1 tcllib "Reflected/virtual channel support"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcl::transform::otp - Encryption via one-time pad</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">tcl::transform::core <span class="opt">?1?</span></b></li>
<li>package require <b class="pkgname">tcl::transform::otp <span class="opt">?1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::tcl::transform::otp</b> <i class="arg">chan</i> <i class="arg">keychanw</i> <i class="arg">keychanr</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">tcl::transform::otp</b> package provides a command creating
a channel transformation which uses externally provided one-time pads
to perform encryption (on writing) and decryption (on reading).</p>
<p>A related transformations in this module is
<b class="package"><a href="rot.html">tcl::transform::rot</a></b>.</p>
<p>The internal <b class="package"><a href="../../../../index.html#tcloo">TclOO</a></b> class implementing the transform
handler is a sub-class of the <b class="package"><a href="../virtchannel_core/transformcore.html">tcl::transform::core</a></b>
framework.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::tcl::transform::otp</b> <i class="arg">chan</i> <i class="arg">keychanw</i> <i class="arg">keychanr</i></a></dt>
<dd><p>This command creates a one-time pad based encryption transformation on
top of the channel <i class="arg">chan</i> and returns its handle.</p>
<p>The two channels <i class="arg">keychanw</i> and <i class="arg">keychanr</i> contain the
one-time pads for the write and read directions, respectively. Their
contents are reads and xored with the bytes written to and read from
the channel.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>virtchannel</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#channel_transformation">channel transformation</a>, <a href="../../../../index.html#cipher">cipher</a>, <a href="../../../../index.html#decryption">decryption</a>, <a href="../../../../index.html#encryption">encryption</a>, <a href="../../../../index.html#one_time_pad">one time pad</a>, <a href="../../../../index.html#otp">otp</a>, <a href="../../../../index.html#reflected_channel">reflected channel</a>, <a href="../../../../index.html#tip_230">tip 230</a>, <a href="../../../../index.html#transformation">transformation</a>, <a href="../../../../index.html#virtual_channel">virtual channel</a>, <a href="../../../../index.html#xor">xor</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Channels</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/websocket/websocket.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
|
<div class='fossil-doc' data-title='websocket - websocket client and server'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">websocket(n) 1.3.1 tcllib "websocket client and server"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>websocket - Tcl implementation of the websocket protocol</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Callbacks</a></li>
<li class="doctools_section"><a href="#section3">API</a></li>
<li class="doctools_section"><a href="#section4">Examples</a></li>
<li class="doctools_section"><a href="#section5">TLS Security Considerations</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">http 2.7</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">sha1</b></li>
<li>package require <b class="pkgname">base64</b></li>
<li>package require <b class="pkgname">websocket <span class="opt">?1.3.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::websocket::open</b> <i class="arg">url</i> <i class="arg">handler</i> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#2"><b class="cmd">::websocket::send</b> <i class="arg">sock</i> <i class="arg">type</i> <span class="opt">?<i class="arg">msg</i>?</span> <span class="opt">?<i class="arg">final</i>?</span></a></li>
<li><a href="#3"><b class="cmd">::websocket::server</b> <i class="arg">sock</i></a></li>
<li><a href="#4"><b class="cmd">::websocket::live</b> <i class="arg">sock</i> <i class="arg">path</i> <i class="arg">cb</i> <span class="opt">?<i class="arg">proto</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::websocket::test</b> <i class="arg">srvSock</i> <i class="arg">cliSock</i> <i class="arg">path</i> <span class="opt">?<i class="arg">hdrs</i>?</span> <span class="opt">?<i class="arg">qry</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::websocket::upgrade</b> <i class="arg">sock</i></a></li>
<li><a href="#7"><b class="cmd">::websocket::takeover</b> <i class="arg">sock</i> <i class="arg">handler</i> <span class="opt">?<i class="arg">server</i>?</span></a></li>
<li><a href="#8"><b class="cmd">::websocket::conninfo</b> <i class="arg">sock</i> <i class="arg">what</i></a></li>
<li><a href="#9"><b class="cmd">::websocket::find</b> <span class="opt">?<i class="arg">host</i>?</span> <span class="opt">?<i class="arg">port</i>?</span></a></li>
<li><a href="#10"><b class="cmd">::websocket::configure</b> <i class="arg">sock</i> <i class="arg">args</i></a></li>
<li><a href="#11"><b class="cmd">::websocket::loglevel</b> <span class="opt">?<i class="arg">loglvl</i>?</span></a></li>
<li><a href="#12"><b class="cmd">::websocket::close</b> <i class="arg">sock</i> <span class="opt">?<i class="arg">code</i>?</span> <span class="opt">?<i class="arg">reason</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>NOTE: THIS DOCUMENTATION IS WORK IN PROGRESS...</p>
<p>The websocket library is a pure Tcl implementation of the WebSocket
specification covering the needs of both clients and servers.
Websockets provide a way to upgrade a regular HTTP connection into a
long-lived and continuous binary or text communication between the
client and the server. The library offers a high-level interface to
receive and send data as specified in RFC 6455 (v. 13 of the
protocol), relieving callers from all necessary protocol framing and
reassembly. It implements the ping facility specified by the
standard, together with levers to control it. Pings are server-driven
and ensure the liveness of the connection across home (NAT) networks.
The library has a number of introspection facilities to inquire about
the current state of the connection, but also to receive notifications
of incoming pings, if necessary. Finally, the library contains a
number of helper procedures to facilitate the upgrading handshaking in
existing web servers.</p>
<p>Central to the library is the procedure <b class="cmd">websocket::takeover</b> that
will take over a regular socket and treat it as a WebSocket, thus
performing all necessary protocol framing, packetisation and
reassembly in servers and clients. The procedure also takes a
handler, a command that will be called back each time a (possibly
reassembled) packet from the remote end is ready for delivery at the
original caller. While exported by the package, the command
<b class="cmd">websocket::takeover</b> is seldom called in applications, since the
package provides other commands that are specifically tuned for the
needs of clients and servers.</p>
<p>Typically, clients will open a connection to a remote server by
providing a WebSocket URL (<i class="term">ws:</i> or <i class="term">wss:</i> schemes) and the
handler described above to the command <b class="cmd">websocket::open</b>. The
opening procedure is a wrapper around the latest http::geturl
implementations: it arranges to keep the socket created within the
http library opened for reuse, but confiscates it from its (internal)
map of known sockets for its own use.</p>
<p>Servers will start by registering themselves through the command
<b class="cmd">::websocket::server</b> and a number of handlers for paths using the
command <b class="cmd">::websocket::live</b>. Then for each incoming client
connection, they should test the incoming request to detect if it is
an upgrade request using <b class="cmd">::websocket::test</b> and perform the final
handshake to place the socket connection under the control of the
websocket library and its central procedure using <b class="cmd">::websocket::upgrade</b>.</p>
<p>Apart from these main commands, the package provides a number of
commands for introspection and basic operations on the websockets that
it has under its control. As WebSockets connections are long-lived,
most remaining communication with the library will be by way of
callbacks, i.e. commands that are triggered whenever important events
within the library have occur, but mostly whenever data has been
received on a WebSocket.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Callbacks</a></h2>
<p>A number of commands of the library take a handler handler command as
an argument, a command which will be called back upon reception of
data, but also upon important events within the library or events
resulting from control messages sent by the remote end. For each
callback being performed, the following arguments will be appended:</p>
<dl class="doctools_definitions">
<dt><i class="arg">sock</i></dt>
<dd><p>The identifier of the WebSocket, as returned for example by
<b class="cmd">::websocket::open</b></p></dd>
<dt><i class="arg">type</i></dt>
<dd><p>A textual type describing the event or message content, can be one of
the following</p>
<dl class="doctools_definitions">
<dt><b class="const">text</b></dt>
<dd><p>Complete text message</p></dd>
<dt><b class="const">binary</b></dt>
<dd><p>Complete binary message</p></dd>
<dt><b class="const">ping</b></dt>
<dd><p>Incoming ping message</p></dd>
<dt><b class="const">connect</b></dt>
<dd><p>Notification of successful connection to server</p></dd>
<dt><b class="const">disconnect</b></dt>
<dd><p>Disconnection from remote end</p></dd>
<dt><b class="const">close</b></dt>
<dd><p>Pending closure of connection</p></dd>
</dl></dd>
<dt><i class="arg">msg</i></dt>
<dd><p>Will contain the data of the message, whenever this is relevant,
i.e. when the <i class="arg">type</i> is <b class="const">text</b>, <b class="const">binary</b> or
<b class="const">ping</b> and whenever there is data available.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::websocket::open</b> <i class="arg">url</i> <i class="arg">handler</i> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>This command is used in clients to open a WebSocket to a remote
websocket-enabled HTTP server. The URL provided as an argument in
<i class="arg">url</i> should start with ws: or wss:, which are the WebSockets
counterpart of http: and https:. The <i class="arg">handler</i> is a command that
will be called back on data reception or whenever important events
occur during the life of the websocket.
<b class="cmd">::websocket::open</b> will return a socket which serves as both the
identifier of the websocket and of the physical low-level socket to
the server. This socket can be used in a number of other commands for
introspection or for controlling the behaviour of the library.
Being essentially a wrapper around the <b class="cmd">::http::geturl</b> command,
this command provides mostly the same set of dash-led options than
<b class="cmd">::http::geturl</b>. Documented below are the options that differ
from <b class="cmd">::http::geturl</b> and which are specific to the WebSocket
library.</p>
<dl class="doctools_definitions">
<dt>-headers</dt>
<dd><p>This option is supported, knowing that a number of headers will be
automatically added internally in the library in order to be able to
handshake the upgrading of the socket from a regular HTTP socket to a
WebSocket with the server.</p></dd>
<dt>-validate</dt>
<dd><p>This option is not supported as it has no real point for WebSockets.</p></dd>
<dt>-handler</dt>
<dd><p>This option is used internally by the websocket library and cannot be
used.</p></dd>
<dt>-command</dt>
<dd><p>This option is used internally by the websocket library and cannot be
used.</p></dd>
<dt>-protocol</dt>
<dd><p>This option specifies a list of application protocols to handshake
with the server. This protocols might help the server triggering
application specific features.</p></dd>
<dt>-timeout</dt>
<dd><p>This option is supported, but will implemented as part of the library
to enable a number of finalising cleanups.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">::websocket::send</b> <i class="arg">sock</i> <i class="arg">type</i> <span class="opt">?<i class="arg">msg</i>?</span> <span class="opt">?<i class="arg">final</i>?</span></a></dt>
<dd><p>This command will send a fragment or a control message to the remote
end of the WebSocket identified by <i class="arg">sock</i>. The type of the
message specified in <i class="arg">type</i> can either be an integer according to
the specification or (preferrably) one of the following case
insensitive strings: "text", "binary" or "ping". The content of the
message to send to the remote end is contained in <i class="arg">msg</i> and
message fragmentation is made possible by the setting the argument
<i class="arg">final</i> to non-true, knowing that the type of each fragment has
then to be the same.
The command returns the number of bytes that were effectively sent, or
-1 on errors. Serious errors, such as when <i class="arg">sock</i> does not
identify a known WebSocket or when the connection is not stable yet
will generate errors that must be catched.</p></dd>
<dt><a name="3"><b class="cmd">::websocket::server</b> <i class="arg">sock</i></a></dt>
<dd><p>This command registers the (accept) socket <i class="arg">sock</i> as the
identifier fo an HTTP server that is capable of doing WebSockets.
Paths onto which this server will listen for incoming connections
should be declared using <b class="cmd">::websocket::live</b>.</p></dd>
<dt><a name="4"><b class="cmd">::websocket::live</b> <i class="arg">sock</i> <i class="arg">path</i> <i class="arg">cb</i> <span class="opt">?<i class="arg">proto</i>?</span></a></dt>
<dd><p>This procedure registers callbacks that will be performed on a
WebSocket compliant server registered with <b class="cmd">::websocket::server</b>
whenever a client connects to a matching path and protocol.
<i class="arg">sock</i> is the listening socket of the websocket compliant server
declared using <b class="cmd">::websocket::server</b>. <i class="arg">path</i> is a glob-style
path to match in client request, whenever this will occur. <i class="arg">cb</i>
is the command to callback (see Callbacks). <i class="arg">proto</i> is a
glob-style protocol name matcher.</p></dd>
<dt><a name="5"><b class="cmd">::websocket::test</b> <i class="arg">srvSock</i> <i class="arg">cliSock</i> <i class="arg">path</i> <span class="opt">?<i class="arg">hdrs</i>?</span> <span class="opt">?<i class="arg">qry</i>?</span></a></dt>
<dd><p>This procedure will test if the connection from an incoming client on
socket <i class="arg">cliSock</i> and on the path <i class="arg">path</i> is the opening of a
WebSocket stream within a known server <i class="arg">srvSock</i>. The incoming
request is not upgraded at once, instead a (temporary) context for the
incoming connection is created. This allows server code to perform a
number of actions, if necessary, before the WebSocket stream
connection goes live. The text is made by analysing the content of
the headers <i class="arg">hdrs</i> which should contain a dictionary list of the
HTTP headers of the incoming client connection.
The command will return <b class="const">1</b> if this is an incoming WebSocket
upgrade request and <b class="const">0</b> otherwise.</p></dd>
<dt><a name="6"><b class="cmd">::websocket::upgrade</b> <i class="arg">sock</i></a></dt>
<dd><p>Upgrade the socket <i class="arg">sock</i> that had been deemed by
<b class="cmd">::websocket::test</b> to be a WebSocket connection request to a true
WebSocket as recognised by this library. As a result, the necessary
connection handshake will be sent to the client, and the command will
arrange for relevant callbacks to be made during the life of the
WebSocket, notably using the specifications described by
<b class="cmd">::websocket::live</b>.</p></dd>
<dt><a name="7"><b class="cmd">::websocket::takeover</b> <i class="arg">sock</i> <i class="arg">handler</i> <span class="opt">?<i class="arg">server</i>?</span></a></dt>
<dd><p>Take over the existing opened socket <i class="arg">sock</i> to implement sending
and receiving WebSocket framing on top of the socket. The procedure
arranges for <i class="arg">handler</i> to be called back whenever messages,
control messages or other important internal events are received or
occured. <i class="arg">server</i> defaults to <b class="const">0</b> and can be set to
<b class="const">1</b> (or a boolean that evaluates to true) to specify that this is a
WebSocket within a server. Apart from specificities in the protocol,
servers should ping their clients at regular intervals in order to
keep the connection opened at all time. When <i class="arg">server</i> is set to
true, the library will arrange to send these pings automatically.</p></dd>
<dt><a name="8"><b class="cmd">::websocket::conninfo</b> <i class="arg">sock</i> <i class="arg">what</i></a></dt>
<dd><p>Provides callers with some introspection facilities in order to get
some semi-internal information about an existing websocket
connection. Depending on the value of the <i class="arg">what</i> argument, the
procedure returns the following piece of information:</p>
<dl class="doctools_definitions">
<dt><b class="const">peername</b></dt>
<dd><p>Name (preferred) or IP of remote end.</p></dd>
<dt><b class="const">sockname</b></dt>
<dd><p>or <b class="const">name</b> Name or IP of local end.</p></dd>
<dt><b class="const">closed</b></dt>
<dd><p><b class="const">1</b> if the connection is closed, <b class="const">0</b> otherwise</p></dd>
<dt><b class="const">client</b></dt>
<dd><p><b class="const">1</b> if the connection is a client websocket, <b class="const">0</b> otherwise</p></dd>
<dt><b class="const">server</b></dt>
<dd><p><b class="const">1</b> if the connection is a server websocket, <b class="const">0</b> otherwise</p></dd>
<dt><b class="const">type</b></dt>
<dd><p><b class="const">server</b> if the connection is a server websocket, <b class="const">client</b> otherwise.</p></dd>
<dt><b class="const">handler</b></dt>
<dd><p>The handler command associated to the websocket</p></dd>
<dt><b class="const">state</b></dt>
<dd><p>The state of the websocket, which can be one of:</p>
<dl class="doctools_definitions">
<dt><b class="const">CONNECTING</b></dt>
<dd><p>Connection to remote end is in progress.</p></dd>
<dt><b class="const">CONNECTED</b></dt>
<dd><p>Connection is connected to remote end.</p></dd>
<dt><b class="const">CLOSED</b></dt>
<dd><p>Connection is closed.</p></dd>
</dl></dd>
</dl></dd>
<dt><a name="9"><b class="cmd">::websocket::find</b> <span class="opt">?<i class="arg">host</i>?</span> <span class="opt">?<i class="arg">port</i>?</span></a></dt>
<dd><p>Look among existing websocket connections for the ones that match the
hostname and port number filters passed as parameters. This lookup
takes the remote end into account and the <i class="arg">host</i> argument is
matched both against the hostname (whenever available) and the IP
address of the remote end. Both the <i class="arg">host</i> and <i class="arg">port</i>
arguments are glob-style string matching filters and default to
<b class="const">*</b>, i.e. will match any host and/or port number.</p></dd>
<dt><a name="10"><b class="cmd">::websocket::configure</b> <i class="arg">sock</i> <i class="arg">args</i></a></dt>
<dd><p>This command takes a number of dash-led options (and their values) to
configure the behaviour of an existing websocket connection. The
recognised options are the following (they can be shortened to the
lowest common denominator):</p>
<dl class="doctools_definitions">
<dt><b class="const">-keepalive</b></dt>
<dd><p>is the number of seconds between each
keepalive pings being sent along the connection. A zero or negative
number will effectively turn off the feature. In servers,
<b class="const">-keepalive</b> defaults to 30 seconds, and in clients, no pings
are initiated.</p></dd>
<dt><b class="const">-ping</b></dt>
<dd><p>is the text that is used during the automated
pings. This text defaults to the empty string, leading to an empty ping.</p></dd>
</dl></dd>
<dt><a name="11"><b class="cmd">::websocket::loglevel</b> <span class="opt">?<i class="arg">loglvl</i>?</span></a></dt>
<dd><p>Set or query the log level of the library, which defaults to error.
Logging is built on top of the logger module, and the library makes
use of the following levels: <b class="const">debug</b>, <b class="const">info</b>, <b class="const">notice</b>,
<b class="const">warn</b> and <b class="const">error</b>. When called with no argument, this procedure will
simply return the current log level. Otherwise <i class="arg">loglvl</i> should contain
the desired log level.</p></dd>
<dt><a name="12"><b class="cmd">::websocket::close</b> <i class="arg">sock</i> <span class="opt">?<i class="arg">code</i>?</span> <span class="opt">?<i class="arg">reason</i>?</span></a></dt>
<dd><p>Gracefully close a websocket that was directly or indirectly passed to
<b class="cmd">::websocket::takeover</b>. The procedure will optionally send the
<i class="arg">code</i> and describing <i class="arg">reason</i> as part of the closure handshake.
Good defaults are provided, so that reasons for a number of known codes will
be sent back. Only the first 125 characters of a reason string will be kept and
sent as part of the handshake. The known codes are:</p>
<dl class="doctools_definitions">
<dt><b class="const">1000</b></dt>
<dd><p>Normal closure (the default <i class="arg">code</i> when none provided).</p></dd>
<dt><b class="const">1001</b></dt>
<dd><p>Endpoint going away</p></dd>
<dt><b class="const">1002</b></dt>
<dd><p>Protocol Error</p></dd>
<dt><b class="const">1003</b></dt>
<dd><p>Received incompatible data type</p></dd>
<dt><b class="const">1006</b></dt>
<dd><p>Abnormal closure</p></dd>
<dt><b class="const">1007</b></dt>
<dd><p>Received data not consistent with type</p></dd>
<dt><b class="const">1008</b></dt>
<dd><p>Policy violation</p></dd>
<dt><b class="const">1009</b></dt>
<dd><p>Received message too big</p></dd>
<dt><b class="const">1010</b></dt>
<dd><p>Missing extension</p></dd>
<dt><b class="const">1011</b></dt>
<dd><p>Unexpected condition</p></dd>
<dt><b class="const">1015</b></dt>
<dd><p>TLS handshake error</p></dd>
</dl></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Examples</a></h2>
<p>The following example opens a websocket connection to the echo
service, waits 400ms to ensure that the connection is really
established and sends a single textual message which should be echoed
back by the echo service. A real example would probably use the
<b class="const">connect</b> callback to know when connection to the remote
server has been establish and would only send data at that time.</p>
<pre class="doctools_example">
package require websocket
::websocket::loglevel debug
proc handler { sock type msg } {
switch -glob -nocase -- $type {
co* {
puts "Connected on $sock"
}
te* {
puts "RECEIVED: $msg"
}
cl* -
dis* {
}
}
}
proc test { sock } {
puts "[::websocket::conninfo $sock type] from [::websocket::conninfo $sock sockname] to [::websocket::conninfo $sock peername]"
::websocket::send $sock text "Testing, testing..."
}
set sock [::websocket::open ws://echo.websocket.org/ handler]
after 400 test $sock
vwait forever
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">TLS Security Considerations</a></h2>
<p>This package uses the <b class="package"><a href="../../../../index.html#tls">TLS</a></b> package to handle the
security for <b class="const">https</b> urls and other socket connections.</p>
<p>Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of <b class="package"><a href="../../../../index.html#tls">TLS</a></b>, nor of
this package itself however.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well.</p>
<p>For example, in light of the recent
<a href="http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html">POODLE attack</a> discovered by Google many servers will disable support
for the SSLv3 protocol.
To handle this change the applications using <b class="package"><a href="../../../../index.html#tls">TLS</a></b> must be
patched, and not this package, nor <b class="package"><a href="../../../../index.html#tls">TLS</a></b> itself.
Such a patch may be as simple as generally activating <b class="const">tls1</b>
support, as shown in the example below.</p>
<pre class="doctools_example">
package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
... your own application code ...
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>websocket</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../../../../index.html#http">http</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#http">http</a>, <a href="../../../../index.html#internet">internet</a>, <a href="../../../../index.html#net">net</a>, <a href="../../../../index.html#rfc_6455">rfc 6455</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Networking</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/wip/wip.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
<div class='fossil-doc' data-title='wip - Word Interpreter'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">wip(n) 2.2 tcllib "Word Interpreter"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>wip - Word Interpreter</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">GENERAL BEHAVIOUR</a></li>
<li class="doctools_section"><a href="#section3">CLASS API</a></li>
<li class="doctools_section"><a href="#section4">OBJECT API</a></li>
<li class="doctools_section"><a href="#section5">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section6">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">wip <span class="opt">?2.2?</span></b></li>
<li>package require <b class="pkgname">snit <span class="opt">?1.3?</span></b></li>
<li>package require <b class="pkgname">struct::set</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::wip</b> <i class="arg">wipName</i> <i class="arg">engine</i> <i class="arg">arg</i>...</a></li>
<li><a href="#2"><b class="cmd">def</b> <i class="arg">name</i></a></li>
<li><a href="#3"><b class="cmd">def</b> <i class="arg">name</i> <i class="arg">method_prefix</i></a></li>
<li><a href="#4"><b class="cmd">wipName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></li>
<li><a href="#5"><b class="cmd">wip::dsl</b> <span class="opt">?<i class="arg">suffix</i>?</span></a></li>
<li><a href="#6"><i class="arg">wipName</i> <b class="method">def</b> <i class="arg">name</i> <span class="opt">?<i class="arg">method_prefix</i>?</span></a></li>
<li><a href="#7"><i class="arg">wipName</i> <b class="method">defl</b> <i class="arg">names</i></a></li>
<li><a href="#8"><i class="arg">wipName</i> <b class="method">defd</b> <i class="arg">dict</i></a></li>
<li><a href="#9"><i class="arg">wipName</i> <b class="method">deflva</b> <i class="arg">name</i>...</a></li>
<li><a href="#10"><i class="arg">wipName</i> <b class="method">defdva</b> (<i class="arg">name</i> <i class="arg">method_prefix</i>)...</a></li>
<li><a href="#11"><i class="arg">wipName</i> <b class="method">undefl</b> <i class="arg">names</i></a></li>
<li><a href="#12"><i class="arg">wipName</i> <b class="method">undefva</b> <i class="arg">name</i>...</a></li>
<li><a href="#13"><i class="arg">wipName</i> <b class="method">unknown</b> <i class="arg">cmdprefix</i></a></li>
<li><a href="#14"><i class="arg">wipName</i> <b class="method">runl</b> <i class="arg">wordlist</i></a></li>
<li><a href="#15"><i class="arg">wipName</i> <b class="method">run</b> <i class="arg">word</i>...</a></li>
<li><a href="#16"><i class="arg">wipName</i> <b class="method">run_next</b></a></li>
<li><a href="#17"><i class="arg">wipName</i> <b class="method">run_next_while</b> <i class="arg">acceptable</i></a></li>
<li><a href="#18"><i class="arg">wipName</i> <b class="method">run_next_until</b> <i class="arg">rejected</i></a></li>
<li><a href="#19"><i class="arg">wipName</i> <b class="method">run_next_if</b> <i class="arg">acceptable</i></a></li>
<li><a href="#20"><i class="arg">wipName</i> <b class="method">run_next_ifnot</b> <i class="arg">rejected</i></a></li>
<li><a href="#21"><i class="arg">wipName</i> <b class="method">next</b></a></li>
<li><a href="#22"><i class="arg">wipName</i> <b class="method">peek</b></a></li>
<li><a href="#23"><i class="arg">wipName</i> <b class="method">peekall</b></a></li>
<li><a href="#24"><i class="arg">wipName</i> <b class="method">insertl</b> <i class="arg">at</i> <i class="arg">wordlist</i></a></li>
<li><a href="#25"><i class="arg">wipName</i> <b class="method">replacel</b> <i class="arg">wordlist</i></a></li>
<li><a href="#26"><i class="arg">wipName</i> <b class="method">pushl</b> <i class="arg">wordlist</i></a></li>
<li><a href="#27"><i class="arg">wipName</i> <b class="method">addl</b> <i class="arg">wordlist</i></a></li>
<li><a href="#28"><i class="arg">wipName</i> <b class="method">insert</b> <i class="arg">at</i> <i class="arg">word</i>...</a></li>
<li><a href="#29"><i class="arg">wipName</i> <b class="method">replace</b> <i class="arg">word</i>...</a></li>
<li><a href="#30"><i class="arg">wipName</i> <b class="method">push</b> <i class="arg">word</i>...</a></li>
<li><a href="#31"><i class="arg">wipName</i> <b class="method">add</b> <i class="arg">word</i>...</a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a micro interpreter for lists of words. Domain
specific languages based on this will have a bit of a Forth feel, with
the input stream segmented into words and any other structuring left
to whatever the language desired. Note that we have here in essence
only the core dispatch loop, and no actual commands whatsoever, making
this definitely only a Forth feel and not an actual Forth.</p>
<p>The idea is derived from Colin McCormack's <b class="package"><a href="../treeql/treeql.html">treeql</a></b> processor,
modified to require less boiler plate within the command
implementations, at the expense of, likely, execution speed. In
addition the interface between processor core and commands is more
complex too.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">GENERAL BEHAVIOUR</a></h2>
<p>Word interpreters have a mappping from the names of the language
commands they shall recognize to the methods in the engine to invoke
for them, and possibly fixed arguments for these methods. This mapping
is largely static, however it is possible to change it during the
execution of a word list (= program).</p>
<p>At the time a language command is defined the word interpreter will
use <b class="package"><a href="../snit/snit.html">snit</a></b>'s introspection capabilities to determine the
number of arguments expected by the method of the egnine, and together
with the number of fixed arguments supplied in the method prefix of
the mapping it then knows how many arguments the language command is
expecting. This is the command's <i class="term">arity</i>. Variable-argument
methods (i.e. with the last argument named <i class="arg">args</i>) are <em>not</em>
allowed and will cause the word interpreter to throw an error at
definition time.</p>
<p>Note that while I said <b class="package"><a href="../snit/snit.html">snit</a></b>'s abilities the engine object
can be written in any way, as long as it understands the method
<b class="method">info args</b>, which takes a method name and returns the list
of arguments for that method.</p>
<p>When executing a list of words (aka program) the first word is always
taken as the name of a language command, and the next words as its
arguments, per the <i class="term">arity</i> of the command. Command and argument
words are removed from the list and then associated method of the
engine is executed with the argument words. The process then repeats
using the then-first word of the list.</p>
<p>Note that the methods implementing the language commands may have full
access to the list of words and are allowed to manipulate as they see
fit.</p>
<ol class="doctools_enumerated">
<li><p>This means, for example, that while we cannot specify
variable-argument methods directly they can consume words after their
fixed arguments before returning to the execution loop. This may be
under the control of their fixed arguments.</p></li>
<li><p>Another possibility is the use of method <b class="method">run_next</b> and its
variants to execute commands coming after the current command,
changing the order of execution.</p></li>
<li><p>Execution can be further changed by use of the program accessor
methods which allow a command implementation to modify the remaining
list of words (insert, replace, prepend, append words) without
executing them immediately.</p></li>
<li><p>At last the basic <b class="method">run</b> methods save and restore an existing
list of words when used, enabling recursive use from within command
implementations.</p></li>
</ol>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">CLASS API</a></h2>
<p>The main command of the package is:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::wip</b> <i class="arg">wipName</i> <i class="arg">engine</i> <i class="arg">arg</i>...</a></dt>
<dd><p>The command creates a new word interpreter object with an associated
global Tcl command whose name is <i class="arg">wipName</i>. If however the string
<b class="const">%AUTO%</b> was used as object name the package will generate its
own unique name for the object.</p>
<p>The <i class="arg">engine</i> is the object the word interpreter will dispatch all
recognized commands to, and the <i class="arg">arg</i>uments are a word list which
defines an initial mapping from language words to engine methods.</p>
<p>The recognized language of this word list is</p>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd">def</b> <i class="arg">name</i></a></dt>
<dd><p>Defines <i class="arg">name</i> as command of the language, to be mapped to a
method of the <i class="arg">engine</i> having the same name.</p></dd>
<dt><a name="3"><b class="cmd">def</b> <i class="arg">name</i> <i class="arg">method_prefix</i></a></dt>
<dd><p>Defines <i class="arg">name</i> as command of the language, to be mapped to the
method of the <i class="arg">engine</i> named in the <i class="arg">method_prefix</i>.</p></dd>
</dl>
<p>The returned command may be used to invoke various operations on the
object. It has the following general form:</p>
<dl class="doctools_definitions">
<dt><a name="4"><b class="cmd">wipName</b> <i class="arg">option</i> <span class="opt">?<i class="arg">arg arg ...</i>?</span></a></dt>
<dd><p><i class="arg">Option</i> and the <i class="arg">arg</i>s determine the exact behavior of the
command.</p></dd>
</dl></dd>
</dl>
<p>The package additionally exports the command:</p>
<dl class="doctools_definitions">
<dt><a name="5"><b class="cmd">wip::dsl</b> <span class="opt">?<i class="arg">suffix</i>?</span></a></dt>
<dd><p>This command is for use within snit types which wish to use one or
more wip interpreters as a component. Use within the type definition
installs most of the boilerplate needed to setup and use a word
interpreter.</p>
<p>It installs a component named <em>wip</em>, and a method
<b class="method">wip_setup</b> for initializing it. This method has to be called
from within the constructor of the type using the word interpreter.
If further installs a series of procedures which make the object API
of the word interpreter directly available to the type's methods,
without having to specify the component.</p>
<p><em>Note</em> that this does and cannot install the language to
interpret, i.e. the mapping from words to engine methods.</p>
<p>It is possible to instantiate multiple word interpreter components
within a type by using different suffices as arguments to the command.
In that case the name of the component changes to
'wip_<b class="variable">$suffix</b>', the setup command becomes
'wip_<b class="variable">$suffix</b>_setup' and all the procedures also get the suffix
'_<b class="variable">$suffix</b>'.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">OBJECT API</a></h2>
<p>The following commands are possible for word interpreter objects:</p>
<dl class="doctools_definitions">
<dt><a name="6"><i class="arg">wipName</i> <b class="method">def</b> <i class="arg">name</i> <span class="opt">?<i class="arg">method_prefix</i>?</span></a></dt>
<dd><p>Defines a language command <i class="arg">name</i> and maps it to the method named
in the engine's <i class="arg">method_prefix</i>. If the <i class="arg">method_prefix</i> name
is not specified it is simply the name of the language command.</p></dd>
<dt><a name="7"><i class="arg">wipName</i> <b class="method">defl</b> <i class="arg">names</i></a></dt>
<dd><p>Defines a series of language commands, specified through the list of
<i class="arg">names</i>, all of which are mapped to engine methods of the same
name.</p></dd>
<dt><a name="8"><i class="arg">wipName</i> <b class="method">defd</b> <i class="arg">dict</i></a></dt>
<dd><p>Defines a series of language commands, specified through the
dictionary <i class="arg">dict</i> of names and method prefixes.</p></dd>
<dt><a name="9"><i class="arg">wipName</i> <b class="method">deflva</b> <i class="arg">name</i>...</a></dt>
<dd><p>As method <b class="method">defl</b>, however the list of names is specified
through multiple arguments.</p></dd>
<dt><a name="10"><i class="arg">wipName</i> <b class="method">defdva</b> (<i class="arg">name</i> <i class="arg">method_prefix</i>)...</a></dt>
<dd><p>As method <b class="method">defd</b>, however the dictionary of names and method
prefixes is specified through multiple arguments.</p></dd>
<dt><a name="11"><i class="arg">wipName</i> <b class="method">undefl</b> <i class="arg">names</i></a></dt>
<dd><p>Removes the named series of language commands from the mapping.</p></dd>
<dt><a name="12"><i class="arg">wipName</i> <b class="method">undefva</b> <i class="arg">name</i>...</a></dt>
<dd><p>As method <b class="method">undefl</b>, however the list of names is specified
through multiple arguments.</p></dd>
<dt><a name="13"><i class="arg">wipName</i> <b class="method">unknown</b> <i class="arg">cmdprefix</i></a></dt>
<dd><p>Sets the handler for unknown words to <i class="arg">cmdprefix</i>. This command
prefix takes one argument, the current word, and either throws some
error, or returns the result of executing the word, as defined by the
handler. The default handler simply throws an error.</p></dd>
<dt><a name="14"><i class="arg">wipName</i> <b class="method">runl</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Treats the list of words in <i class="arg">wordlist</i> as a program and executes
the contained command one by one. The result of the command executed
last is returned as the result of this command.</p>
<p>The <i class="arg">wordlist</i> is stored in the object for access by the other
<i class="term">run</i>-methods, and the general program accessor methods (see
below). A previously stored wordlist is saved during the execution of
this method and restored before it returns. This enables the recursive
execution of word lists within word lists.</p></dd>
<dt><a name="15"><i class="arg">wipName</i> <b class="method">run</b> <i class="arg">word</i>...</a></dt>
<dd><p>As method <b class="method">runl</b>, however the list of words to execute is
specified through multiple arguments.</p></dd>
<dt><a name="16"><i class="arg">wipName</i> <b class="method">run_next</b></a></dt>
<dd><p>Low-level method. Determines the next word in the list of words, and
its arguments, and then executes it. The result of the executed word
is the result of this method.</p>
<p>Exposed for use within command implementations.
The methods <b class="method">run</b> and <b class="method">runl</b> use it to execute words
until their word list is exhausted.</p></dd>
<dt><a name="17"><i class="arg">wipName</i> <b class="method">run_next_while</b> <i class="arg">acceptable</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> as long as the
next word is in the set of <i class="arg">acceptable</i> words, and the program is
not empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="18"><i class="arg">wipName</i> <b class="method">run_next_until</b> <i class="arg">rejected</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> until the next
word is in the set of <i class="arg">rejected</i> words, and the program is not
empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="19"><i class="arg">wipName</i> <b class="method">run_next_if</b> <i class="arg">acceptable</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> if the next
word is in the set of <i class="arg">acceptable</i> words, and the program is not
empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="20"><i class="arg">wipName</i> <b class="method">run_next_ifnot</b> <i class="arg">rejected</i></a></dt>
<dd><p>Low-level method. Invokes the method <b class="method">run_next</b> if the next
word is not in the set of <i class="arg">rejected</i> words, and the program is not
empty. The result of the command executed last is returned as the
result of this command.</p>
<p>Exposed for use within command implementations to change the order of
execution.</p></dd>
<dt><a name="21"><i class="arg">wipName</i> <b class="method">next</b></a></dt>
<dd><p>Returns the next word in the programm. The word is also removed.</p></dd>
<dt><a name="22"><i class="arg">wipName</i> <b class="method">peek</b></a></dt>
<dd><p>Returns the next word in the programm without removing it</p></dd>
<dt><a name="23"><i class="arg">wipName</i> <b class="method">peekall</b></a></dt>
<dd><p>Returns the remaining programm in toto.</p></dd>
<dt><a name="24"><i class="arg">wipName</i> <b class="method">insertl</b> <i class="arg">at</i> <i class="arg">wordlist</i></a></dt>
<dd><p>Basic programm accessor method. Inserts the specified <i class="arg">wordlist</i>
into the program, just before the word at position <i class="arg">at</i>. Positions
are counted from <b class="const">zero</b>.</p></dd>
<dt><a name="25"><i class="arg">wipName</i> <b class="method">replacel</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Basic programm accessor method. Replaces the whole stored program with
the specified <i class="arg">wordlist</i>.</p></dd>
<dt><a name="26"><i class="arg">wipName</i> <b class="method">pushl</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Program accessor method. The specified <i class="arg">wordlist</i> is added to the
front of the remaining program. Equivalent to</p>
<pre class="doctools_example">$wip insertl 0 $wordlist</pre>
</dd>
<dt><a name="27"><i class="arg">wipName</i> <b class="method">addl</b> <i class="arg">wordlist</i></a></dt>
<dd><p>Program accessor method. The specified <i class="arg">wordlist</i> is appended at
the end of the remaining program. Equivalent to</p>
<pre class="doctools_example">$wip insertl end $wordlist</pre>
</dd>
<dt><a name="28"><i class="arg">wipName</i> <b class="method">insert</b> <i class="arg">at</i> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">insertl</b>, except the words are specified through
multiple arguments.</p></dd>
<dt><a name="29"><i class="arg">wipName</i> <b class="method">replace</b> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">setl</b>, except the words are specified through
multiple arguments.</p></dd>
<dt><a name="30"><i class="arg">wipName</i> <b class="method">push</b> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">pushl</b>, except the words are specified through
multiple arguments.</p></dd>
<dt><a name="31"><i class="arg">wipName</i> <b class="method">add</b> <i class="arg">word</i>...</a></dt>
<dd><p>Like method <b class="method">addl</b>, except the words are specified through
multiple arguments.</p></dd>
</dl>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">EXAMPLES</a></h2>
<p>No examples yet.</p>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>wip</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#interpreter">interpreter</a>, <a href="../../../../index.html#list">list</a>, <a href="../../../../index.html#word">word</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007-2010 Andreas Kupries <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/yaml/huddle.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
|
<div class='fossil-doc' data-title='huddle - HUDDLE'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">huddle(n) 0.3 tcllib "HUDDLE"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>huddle - Create and manipulate huddle object</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">TYPE CALLBACK</a></li>
<li class="doctools_section"><a href="#section4">How to add type</a></li>
<li class="doctools_section"><a href="#section5">WORKING SAMPLE</a></li>
<li class="doctools_section"><a href="#section6">LIMITATIONS</a></li>
<li class="doctools_section"><a href="#section7">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">huddle <span class="opt">?0.3?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">huddle create</b> <i class="arg">key</i> <i class="arg">value</i> <span class="opt">?<i class="arg">key value ...</i>?</span></a></li>
<li><a href="#2"><b class="cmd">huddle list</b> <span class="opt">?<i class="arg">value value ...</i>?</span></a></li>
<li><a href="#3"><b class="cmd">huddle number</b> <i class="arg">number</i></a></li>
<li><a href="#4"><b class="cmd">huddle string</b> <i class="arg">string</i></a></li>
<li><a href="#5"><b class="cmd">huddle boolean</b> <i class="arg">expression to evaluate as true or false</i></a></li>
<li><a href="#6"><b class="cmd">huddle true</b></a></li>
<li><a href="#7"><b class="cmd">huddle false</b></a></li>
<li><a href="#8"><b class="cmd">huddle null</b></a></li>
<li><a href="#9"><b class="cmd">huddle get</b> <i class="arg">object</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span></a></li>
<li><a href="#10"><b class="cmd">huddle gets</b> <i class="arg">object</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span></a></li>
<li><a href="#11"><b class="cmd">huddle set</b> <i class="arg">objectVar</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span> <i class="arg">value</i></a></li>
<li><a href="#12"><b class="cmd">huddle remove</b> <i class="arg">object</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span></a></li>
<li><a href="#13"><b class="cmd">huddle combine</b> <i class="arg">object1</i> <i class="arg">object2</i> <span class="opt">?<i class="arg">object3 ...</i>?</span></a></li>
<li><a href="#14"><b class="cmd">huddle equal</b> <i class="arg">object1</i> <i class="arg">object2</i></a></li>
<li><a href="#15"><b class="cmd">huddle append</b> <i class="arg">objectVar</i> <i class="arg">key</i> <i class="arg">value</i> <span class="opt">?<i class="arg">key value ...</i>?</span></a></li>
<li><a href="#16"><b class="cmd">huddle append</b> <i class="arg">objectVar</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></li>
<li><a href="#17"><b class="cmd">huddle keys</b> <i class="arg">object</i></a></li>
<li><a href="#18"><b class="cmd">huddle llength</b> <i class="arg">object</i></a></li>
<li><a href="#19"><b class="cmd">huddle type</b> <i class="arg">object</i> <span class="opt">?<i class="arg">key key...</i>?</span></a></li>
<li><a href="#20"><b class="cmd">huddle strip</b> <i class="arg">object</i></a></li>
<li><a href="#21"><b class="cmd">huddle jsondump</b> <i class="arg">object</i> <span class="opt">?<i class="arg">offset</i>?</span> <span class="opt">?<i class="arg">newline</i>?</span> <span class="opt">?<i class="arg">begin_offset</i>?</span></a></li>
<li><a href="#22"><b class="cmd">huddle compile</b> <i class="arg">spec</i> <i class="arg">data</i></a></li>
<li><a href="#23"><b class="cmd">huddle isHuddle</b> <i class="arg">object</i></a></li>
<li><a href="#24"><b class="cmd">huddle checkHuddle</b> <i class="arg">object</i></a></li>
<li><a href="#25"><b class="cmd">huddle to_node</b> <i class="arg">object</i> <span class="opt">?<i class="arg">tag</i>?</span></a></li>
<li><a href="#26"><b class="cmd">huddle wrap</b> <i class="arg">tag</i> <i class="arg">src</i></a></li>
<li><a href="#27"><b class="cmd">huddle call</b> <i class="arg">tag</i> <i class="arg">command</i> <i class="arg">args</i></a></li>
<li><a href="#28"><b class="cmd">huddle addType</b> <i class="arg">callback</i></a></li>
<li><a href="#29"><b class="cmd"><a href="../../../../index.html#callback">callback</a></b> <i class="arg">command</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#30"><b class="cmd">setting</b></a></li>
<li><a href="#31"><b class="cmd">get_sub</b> <i class="arg">src</i> <i class="arg">key</i></a></li>
<li><a href="#32"><b class="cmd">strip</b> <i class="arg">src</i></a></li>
<li><a href="#33"><b class="cmd"><a href="../../../../index.html#set">set</a></b> <i class="arg">src</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
<li><a href="#34"><b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <i class="arg">src</i> <i class="arg">key</i> <i class="arg">value</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Huddle provides a generic Tcl-based serialization/intermediary format.
Currently, each node is wrapped in a tag with simple type information.</p>
<p>When converting huddle-notation to other serialization formats like
JSON or YAML this type information is used to select the proper notation.
And when going from JSON/YAML/... to huddle their notation can be used
to select the proper huddle type.</p>
<p>In that manner huddle can serve as a common intermediary format.</p>
<pre class="doctools_example">
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.
</pre>
<p>The <b class="package">huddle</b> package returns
data as a Tcl <b class="cmd"><a href="../../../../index.html#dict">dict</a></b>. Either the <b class="package"><a href="../../../../index.html#dict">dict</a></b> package or Tcl 8.5 is
required for use.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">huddle create</b> <i class="arg">key</i> <i class="arg">value</i> <span class="opt">?<i class="arg">key value ...</i>?</span></a></dt>
<dd><p>Create a huddle object as a dict. It can contain other huddle objects.</p></dd>
<dt><a name="2"><b class="cmd">huddle list</b> <span class="opt">?<i class="arg">value value ...</i>?</span></a></dt>
<dd><p>Create a huddle object as a list. It can contain other huddle objects.</p></dd>
<dt><a name="3"><b class="cmd">huddle number</b> <i class="arg">number</i></a></dt>
<dd><p>Create a huddle object as a number.</p></dd>
<dt><a name="4"><b class="cmd">huddle string</b> <i class="arg">string</i></a></dt>
<dd><p>Create a huddle object as a string.</p></dd>
<dt><a name="5"><b class="cmd">huddle boolean</b> <i class="arg">expression to evaluate as true or false</i></a></dt>
<dd><p>Create a huddle object as a boolean evaluating an expression as true or false-</p></dd>
<dt><a name="6"><b class="cmd">huddle true</b></a></dt>
<dd><p>Create a huddle object as a boolean true.</p></dd>
<dt><a name="7"><b class="cmd">huddle false</b></a></dt>
<dd><p>Create a huddle object as a boolean false.</p></dd>
<dt><a name="8"><b class="cmd">huddle null</b></a></dt>
<dd><p>Create a huddle object as a null.</p></dd>
<dt><a name="9"><b class="cmd">huddle get</b> <i class="arg">object</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span></a></dt>
<dd><p>Almost the same as <b class="cmd">dict get</b>.
Get a sub-object from the huddle object.
<i class="arg">key</i> can be used to huddle-list's index.</p></dd>
<dt><a name="10"><b class="cmd">huddle gets</b> <i class="arg">object</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span></a></dt>
<dd><p>Get a sub-object from the huddle object, stripped.</p></dd>
<dt><a name="11"><b class="cmd">huddle set</b> <i class="arg">objectVar</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span> <i class="arg">value</i></a></dt>
<dd><p>Almost the same as <b class="cmd">dict set</b>.
Set a sub-object from the huddle object.
<i class="arg">key</i> can be used to huddle-list's index.</p></dd>
<dt><a name="12"><b class="cmd">huddle remove</b> <i class="arg">object</i> <i class="arg">key</i> <span class="opt">?<i class="arg">key ...</i>?</span></a></dt>
<dd><p>Almost the same as <b class="cmd">dict remove</b>.
Remove a sub-object from the huddle object.
<i class="arg">key</i> can be used to huddle-list's index.</p></dd>
<dt><a name="13"><b class="cmd">huddle combine</b> <i class="arg">object1</i> <i class="arg">object2</i> <span class="opt">?<i class="arg">object3 ...</i>?</span></a></dt>
<dd><p>Merging huddle objects given.</p>
<pre class="doctools_example">
% 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}}}
</pre>
</dd>
<dt><a name="14"><b class="cmd">huddle equal</b> <i class="arg">object1</i> <i class="arg">object2</i></a></dt>
<dd><p>Comparing two huddle objects recursively.
When to equal, returns 1, otherwise 0.</p>
<pre class="doctools_example">
% 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
</pre>
</dd>
<dt><a name="15"><b class="cmd">huddle append</b> <i class="arg">objectVar</i> <i class="arg">key</i> <i class="arg">value</i> <span class="opt">?<i class="arg">key value ...</i>?</span></a></dt>
<dd></dd>
<dt><a name="16"><b class="cmd">huddle append</b> <i class="arg">objectVar</i> <i class="arg">value</i> <span class="opt">?<i class="arg">value ...</i>?</span></a></dt>
<dd><p>Appending child elements. When for dicts, giving key/value. When for lists, giving values.</p>
<pre class="doctools_example">
% 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}}}
</pre>
</dd>
<dt><a name="17"><b class="cmd">huddle keys</b> <i class="arg">object</i></a></dt>
<dd><p>The same as <b class="cmd">dict keys</b>.</p></dd>
<dt><a name="18"><b class="cmd">huddle llength</b> <i class="arg">object</i></a></dt>
<dd><p>The same as <b class="cmd">llength</b>.</p></dd>
<dt><a name="19"><b class="cmd">huddle type</b> <i class="arg">object</i> <span class="opt">?<i class="arg">key key...</i>?</span></a></dt>
<dd><p>Return the element type of specified by keys.
if <span class="opt">?key?</span> is not given, returns the type of root node.</p>
<dl class="doctools_options">
<dt><b class="option"><b class="const">string</b></b></dt>
<dd><p>the node is a tcl's string.</p></dd>
<dt><b class="option"><b class="const">dict</b></b></dt>
<dd><p>the node is a dict.</p></dd>
<dt><b class="option"><b class="const">list</b></b></dt>
<dd><p>the node is a list.</p></dd>
<dt><b class="option"><b class="const">number</b></b></dt>
<dd><p>the node is a number.</p></dd>
<dt><b class="option"><b class="const">boolean</b></b></dt>
<dd><p>the node is a boolean.</p></dd>
<dt><b class="option"><b class="const">null</b></b></dt>
<dd><p>the node is a null.</p></dd>
</dl>
<pre class="doctools_example">
% 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
</pre>
</dd>
<dt><a name="20"><b class="cmd">huddle strip</b> <i class="arg">object</i></a></dt>
<dd><p>Stripped all tags. Converted to normal Tcl's list/dict.</p></dd>
<dt><a name="21"><b class="cmd">huddle jsondump</b> <i class="arg">object</i> <span class="opt">?<i class="arg">offset</i>?</span> <span class="opt">?<i class="arg">newline</i>?</span> <span class="opt">?<i class="arg">begin_offset</i>?</span></a></dt>
<dd><p>dump a json-stream from the huddle-object.</p>
<dl class="doctools_options">
<dt><b class="option"><b class="const">offset</b> ""</b></dt>
<dd><p>begin offset as spaces " ".</p></dd>
</dl>
<pre class="doctools_example"># 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"}}
</pre>
</dd>
<dt><a name="22"><b class="cmd">huddle compile</b> <i class="arg">spec</i> <i class="arg">data</i></a></dt>
<dd><p>construct a huddle object from plain old tcl values.
<i class="arg">spec</i> is defined as follows:</p>
<dl class="doctools_definitions">
<dt><b class="const">string</b></dt>
<dd><p>data is simply a string</p></dd>
<dt><b class="const">list</b></dt>
<dd><p>data is a tcl list of strings</p></dd>
<dt><b class="const">dict</b></dt>
<dd><p>data is a tcl dict of strings</p></dd>
<dt>list list</dt>
<dd><p>data is a tcl list of lists</p></dd>
<dt>list dict</dt>
<dd><p>data is a tcl list of dicts</p></dd>
<dt>dict xx list</dt>
<dd><p>data is a tcl dict where the value of key xx is a tcl list</p></dd>
<dt>dict * list</dt>
<dd><p>data is a tcl dict of lists
<i class="arg">data</i> is plain old tcl values</p></dd>
</dl>
<pre class="doctools_example">% 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}}}}}}}
</pre>
</dd>
<dt><a name="23"><b class="cmd">huddle isHuddle</b> <i class="arg">object</i></a></dt>
<dd><p>if <i class="arg">object</i> is a huddle, returns 1. the other, returns 0.</p></dd>
<dt><a name="24"><b class="cmd">huddle checkHuddle</b> <i class="arg">object</i></a></dt>
<dd><p>if <i class="arg">object</i> is not a huddle, rises an error.</p></dd>
<dt><a name="25"><b class="cmd">huddle to_node</b> <i class="arg">object</i> <span class="opt">?<i class="arg">tag</i>?</span></a></dt>
<dd><p>for type-callbacks.</p>
<p>if <i class="arg">object</i> is a huddle, returns root-node. the other, returns <b class="cmd">[list s $object]</b>.</p>
<pre class="doctools_example">
% 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}
</pre>
</dd>
<dt><a name="26"><b class="cmd">huddle wrap</b> <i class="arg">tag</i> <i class="arg">src</i></a></dt>
<dd><p>for type-callbacks.</p>
<p>Create a huddle object from <i class="arg">src</i> with specified <i class="arg">tag</i>.</p>
<pre class="doctools_example">
% huddle wrap "" str
HUDDLE str
% huddle wrap s str
HUDDLE {s str}
</pre>
</dd>
<dt><a name="27"><b class="cmd">huddle call</b> <i class="arg">tag</i> <i class="arg">command</i> <i class="arg">args</i></a></dt>
<dd><p>for type-callbacks.</p>
<p>devolving <i class="arg">command</i> to default <i class="arg">tag</i>-callback</p></dd>
<dt><a name="28"><b class="cmd">huddle addType</b> <i class="arg">callback</i></a></dt>
<dd><p>add a user-specified-type/tag to the huddle library.
To see "Additional Type".</p>
<dl class="doctools_options">
<dt><b class="option">callback</b></dt>
<dd><p>callback function name for additional type.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">TYPE CALLBACK</a></h2>
<p>The definition of callback for user-type.</p>
<dl class="doctools_definitions">
<dt><a name="29"><b class="cmd"><a href="../../../../index.html#callback">callback</a></b> <i class="arg">command</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><dl class="doctools_options">
<dt><b class="option">command</b></dt>
<dd><p>huddle subcomand which is needed to reply by the callback.</p></dd>
<dt><b class="option">args</b></dt>
<dd><p>arguments of subcommand. The number of list of arguments is different for each subcommand.</p></dd>
</dl></dd>
</dl>
<p>The callback procedure shuould reply the following subcommands.</p>
<dl class="doctools_definitions">
<dt><a name="30"><b class="cmd">setting</b></a></dt>
<dd><p>only returns a fixed dict of the type infomation for setting the user-tag.</p>
<dl class="doctools_definitions">
<dt><b class="const">type</b> typename</dt>
<dd><p>typename of the type</p></dd>
<dt><b class="const">method</b> {method1 method2 method3 ...}</dt>
<dd><p>method list as huddle subcommand. Then, you can call <b class="cmd">[huddle method1 ...]</b></p></dd>
<dt><b class="const">tag</b> {tag1 child/parent tag2 child/parent ...}</dt>
<dd><p>tag list for huddle-node as a dict. if the type has child-nodes, use "parent", otherwise use "child".</p></dd>
</dl></dd>
<dt><a name="31"><b class="cmd">get_sub</b> <i class="arg">src</i> <i class="arg">key</i></a></dt>
<dd><p>returns a sub node specified by <i class="arg">key</i>.</p>
<dl class="doctools_options">
<dt><b class="option">src</b></dt>
<dd><p>a node content in huddle object.</p></dd>
</dl></dd>
<dt><a name="32"><b class="cmd">strip</b> <i class="arg">src</i></a></dt>
<dd><p>returns stripped node contents. if the type has child nodes, every node must be stripped.</p></dd>
<dt><a name="33"><b class="cmd"><a href="../../../../index.html#set">set</a></b> <i class="arg">src</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>sets a sub-node from the tagged-content, and returns self.</p></dd>
<dt><a name="34"><b class="cmd"><a href="../../../../index.html#remove">remove</a></b> <i class="arg">src</i> <i class="arg">key</i> <i class="arg">value</i></a></dt>
<dd><p>removes a sub-node from the tagged-content, and returns self.</p></dd>
</dl>
<p><b class="cmd">strip</b> must be defined at all types.
<b class="cmd">get_sub</b> must be defined at container types.
<b class="cmd">set/remove</b> shuould be defined, if you call them.</p>
<pre class="doctools_example">
# 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"
}
}
}
</pre>
<pre class="doctools_example">
# 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]
}
}
}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">How to add type</a></h2>
<p>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 <i class="arg">command</i> and <span class="opt">?<i class="arg">args</i>?</span>. It has some switch-sections.</p>
<p>And, addType subcommand will called.</p>
<pre class="doctools_example">
huddle addType my_dict_setting
</pre>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">WORKING SAMPLE</a></h2>
<pre class="doctools_example">
# 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"
]
</pre>
</div>
<div id="section6" class="doctools_section"><h2><a name="section6">LIMITATIONS</a></h2>
<p>now printing.</p>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>huddle</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="yaml.html">yaml</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_exchange">data exchange</a>, <a href="../../../../index.html#exchange_format">exchange format</a>, <a href="../../../../index.html#huddle">huddle</a>, <a href="../../../../index.html#json">json</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#text_processing">text processing</a>, <a href="../../../../index.html#yaml">yaml</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008-2011 KATO Kanryu <[email protected]><br>
Copyright © 2015 Miguel Martínez López <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/yaml/yaml.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
<div class='fossil-doc' data-title='yaml - YAML processing'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">yaml(n) 0.4.1 tcllib "YAML processing"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>yaml - YAML Format Encoder/Decoder</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">COMMANDS</a></li>
<li class="doctools_section"><a href="#section3">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section4">LIMITATIONS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">yaml <span class="opt">?0.4.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::yaml::yaml2dict</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">txt</i></a></li>
<li><a href="#2"><b class="cmd">::yaml::yaml2huddle</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">txt</i></a></li>
<li><a href="#3"><b class="cmd">::yaml::setOption</b> <span class="opt">?<i class="arg">options</i>?</span></a></li>
<li><a href="#4"><b class="cmd">::yaml::dict2yaml</b> <i class="arg">dict</i> <span class="opt">?<i class="arg">indent</i>?</span> <span class="opt">?<i class="arg">wordwrap</i>?</span></a></li>
<li><a href="#5"><b class="cmd">::yaml::list2yaml</b> <i class="arg">list</i> <span class="opt">?<i class="arg">indent</i>?</span> <span class="opt">?<i class="arg">wordwrap</i>?</span></a></li>
<li><a href="#6"><b class="cmd">::yaml::huddle2yaml</b> <i class="arg">huddle</i> <span class="opt">?<i class="arg">indent</i>?</span> <span class="opt">?<i class="arg">wordwrap</i>?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The <b class="package">yaml</b> package provides a simple Tcl-only library for parsing the
YAML <a href="http://www.yaml.org/">http://www.yaml.org/</a> data exchange format as specified in
<a href="http://www.yaml.org/spec/1.1/">http://www.yaml.org/spec/1.1/</a>.</p>
<p>The <b class="package">yaml</b> package returns
data as a Tcl <b class="cmd"><a href="../../../../index.html#dict">dict</a></b>. Either the <b class="package"><a href="../../../../index.html#dict">dict</a></b> package or Tcl 8.5 is
required for use.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">COMMANDS</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::yaml::yaml2dict</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">txt</i></a></dt>
<dd></dd>
<dt><a name="2"><b class="cmd">::yaml::yaml2huddle</b> <span class="opt">?<i class="arg">options</i>?</span> <i class="arg">txt</i></a></dt>
<dd><p>Parse yaml formatted text <i class="arg">txt</i> into a Tcl dict/huddle and return the value.</p>
<dl class="doctools_options">
<dt><b class="option"><b class="const">-file</b></b></dt>
<dd><p><i class="arg">txt</i> is a filename of YAML-stream.</p></dd>
<dt><b class="option"><b class="const">-stream</b></b></dt>
<dd><p><i class="arg">txt</i> is just a YAML-stream.</p></dd>
<dt><b class="option"><b class="const">-types</b> <i class="arg">list</i></b></dt>
<dd><p>The <i class="arg">list</i> is a type list for the yaml-scalar types.(e.g. !!str !!timestamp !!integer !!true ...)</p>
<pre class="doctools_example"> -types {timestamp integer null true false}</pre>
<p>In this case, if a string matched "timestamp", converted to the TCL internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183)</p></dd>
<dt><b class="option"><b class="const">-m:true</b> <i class="arg">param</i></b></dt>
<dd><p>The <i class="arg">param</i> is two elements of list for the value of true, and considered strings.</p>
<pre class="doctools_example"> -m:true {1 {true on + yes y}}</pre>
<p>In this case, the string "yes" found in YAML Stream, automatically converted 1.</p></dd>
<dt><b class="option"><b class="const">-m:false</b> <i class="arg">param</i></b></dt>
<dd><p>The <i class="arg">param</i> is two elements of list for the value of false, and considered strings.</p>
<pre class="doctools_example"> -m:false {0 {false off - no n}}</pre>
</dd>
<dt><b class="option"><b class="const">-m:null</b> <i class="arg">param</i></b></dt>
<dd><p>The <i class="arg">param</i> is two elements of list for the value of null, and considered strings.</p>
<pre class="doctools_example"> -m:null {"" {null nil "" ~}}</pre>
</dd>
<dt><b class="option"><b class="const">-validate</b></b></dt>
<dd><p>Experiment,old: Output stream contains YAML's-tag, each node.</p>
<pre class="doctools_example">% puts [::yaml::load -validate {[aaa, bbb]}]
=>
!!seq {{!!str aaa} {!!str bbb}}
</pre>
</dd>
</dl></dd>
<dt><a name="3"><b class="cmd">::yaml::setOption</b> <span class="opt">?<i class="arg">options</i>?</span></a></dt>
<dd><p>Change implicit options for the library.
Now, the params are the same as <b class="cmd">::yaml::yaml2dict</b>.
Arguments of<b class="cmd">::yaml::yaml2dict</b> is more priority than this setting.</p></dd>
<dt><a name="4"><b class="cmd">::yaml::dict2yaml</b> <i class="arg">dict</i> <span class="opt">?<i class="arg">indent</i>?</span> <span class="opt">?<i class="arg">wordwrap</i>?</span></a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">::yaml::list2yaml</b> <i class="arg">list</i> <span class="opt">?<i class="arg">indent</i>?</span> <span class="opt">?<i class="arg">wordwrap</i>?</span></a></dt>
<dd></dd>
<dt><a name="6"><b class="cmd">::yaml::huddle2yaml</b> <i class="arg">huddle</i> <span class="opt">?<i class="arg">indent</i>?</span> <span class="opt">?<i class="arg">wordwrap</i>?</span></a></dt>
<dd><p>Convert a dict/list/huddle object into YAML stream.</p>
<dl class="doctools_definitions">
<dt>indent</dt>
<dd><p>spaces indent of each block node.
currently default is 2.</p></dd>
<dt>wordwrap</dt>
<dd><p>word wrap for YAML stream.
currently default is 40.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">EXAMPLES</a></h2>
<p>An example of a yaml stream converted to Tcl. A yaml stream is returned as a
single item with multiple elements.</p>
<pre class="doctools_example">{
--- !<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.}</pre>
<p>An example of a yaml object converted to Tcl. A yaml object is returned as a
multi-element list (a dict).</p>
<pre class="doctools_example">{
---
- [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}}
</pre>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">LIMITATIONS</a></h2>
<p>tag parser not implemented. currentry, tags are merely ignored.</p>
<p>Only Anchor => Aliases ordering. back alias-referring is not supported.</p>
<p>Too many braces, or too few braces.</p>
<p>Not enough character set of line feeds. Please use only "\n" as line breaks.</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>yaml</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="../base64/base64.html">base64</a>, <a href="huddle.html">huddle</a>, <a href="../json/json.html">json</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#data_exchange">data exchange</a>, <a href="../../../../index.html#huddle">huddle</a>, <a href="../../../../index.html#parsing">parsing</a>, <a href="../../../../index.html#text_processing">text processing</a>, <a href="../../../../index.html#yaml">yaml</a></p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008 KATO Kanryu <[email protected]></p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/zip/decode.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
<div class='fossil-doc' data-title='zipfile::decode - Zip archive handling'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">zipfile::decode(n) 0.7.1 tcllib "Zip archive handling"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>zipfile::decode - Access to zip archives</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">fileutil::magic::mimetype</b></li>
<li>package require <b class="pkgname">fileutil::decode 0.2.1</b></li>
<li>package require <b class="pkgname">Trf</b></li>
<li>package require <b class="pkgname">zlibtcl</b></li>
<li>package require <b class="pkgname">zipfile::decode <span class="opt">?0.7.1?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::zipfile::decode::archive</b></a></li>
<li><a href="#2"><b class="cmd">::zipfile::decode::close</b></a></li>
<li><a href="#3"><b class="cmd">::zipfile::decode::comment</b> <i class="arg">adict</i></a></li>
<li><a href="#4"><b class="cmd">::zipfile::decode::content</b> <i class="arg">archive</i></a></li>
<li><a href="#5"><b class="cmd">::zipfile::decode::copyfile</b> <i class="arg">adict</i> <i class="arg">path</i> <i class="arg">dst</i></a></li>
<li><a href="#6"><b class="cmd">::zipfile::decode::files</b> <i class="arg">adict</i></a></li>
<li><a href="#7"><b class="cmd">::zipfile::decode::getfile</b> <i class="arg">zdict</i> <i class="arg">path</i></a></li>
<li><a href="#8"><b class="cmd">::zipfile::decode::hasfile</b> <i class="arg">adict</i> <i class="arg">path</i></a></li>
<li><a href="#9"><b class="cmd">::zipfile::decode::iszip</b> <i class="arg">archive</i></a></li>
<li><a href="#10"><b class="cmd">::zipfile::decode::open</b> <i class="arg">archive</i></a></li>
<li><a href="#11"><b class="cmd">::zipfile::decode::unzip</b> <i class="arg">adict</i> <i class="arg">dstdir</i></a></li>
<li><a href="#12"><b class="cmd">::zipfile::decode::unzipfile</b> <i class="arg">archive</i> <i class="arg">dstdir</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides commands to decompress and access the contents
of zip archives.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::zipfile::decode::archive</b></a></dt>
<dd><p>This command decodes the last opened (and not yet closed) zip archive
file.
The result of the command is a dictionary describing the contents of
the archive. The structure of this dictionary is not public. Proper
access should be made through the provided accessor command of this
package.</p></dd>
<dt><a name="2"><b class="cmd">::zipfile::decode::close</b></a></dt>
<dd><p>This command releases all state associated with the last call of
<b class="cmd">::zipfile::decode::open</b>.
The result of the command is the empty string.</p></dd>
<dt><a name="3"><b class="cmd">::zipfile::decode::comment</b> <i class="arg">adict</i></a></dt>
<dd><p>This command takes a dictionary describing the currently open zip
archive file, as returned by <b class="cmd">::zipfile::decode::archive</b>, and
returns the global comment of the archive.</p></dd>
<dt><a name="4"><b class="cmd">::zipfile::decode::content</b> <i class="arg">archive</i></a></dt>
<dd><p>This is a convenience command which decodes the specified zip
<i class="arg">archive</i> file and returns the list of paths found in it as its
result.</p></dd>
<dt><a name="5"><b class="cmd">::zipfile::decode::copyfile</b> <i class="arg">adict</i> <i class="arg">path</i> <i class="arg">dst</i></a></dt>
<dd><p>This command takes a dictionary describing the currently open zip
archive file, as returned by <b class="cmd">::zipfile::decode::archive</b>, and
copies the decompressed contents of the file <i class="arg">path</i> in the archive
to the the file <i class="arg">dst</i>.
An error is thrown if the file is not found in the archive.</p></dd>
<dt><a name="6"><b class="cmd">::zipfile::decode::files</b> <i class="arg">adict</i></a></dt>
<dd><p>This command takes a dictionary describing the currently open zip
archive file, as returned by <b class="cmd">::zipfile::decode::archive</b>, and
returns the list of files found in the archive.</p></dd>
<dt><a name="7"><b class="cmd">::zipfile::decode::getfile</b> <i class="arg">zdict</i> <i class="arg">path</i></a></dt>
<dd><p>This command takes a dictionary describing the currently open zip
archive file, as returned by <b class="cmd">::zipfile::decode::archive</b>, and
returns the decompressed contents of the file <i class="arg">path</i> in the archive.
An error is thrown if the file is not found in the archive.</p></dd>
<dt><a name="8"><b class="cmd">::zipfile::decode::hasfile</b> <i class="arg">adict</i> <i class="arg">path</i></a></dt>
<dd><p>This command takes a dictionary describing the currently open zip
archive file, as returned by <b class="cmd">::zipfile::decode::archive</b>, and
check if the specified <i class="arg">path</i> is found in the archive.
The result of the command is a boolean flag, <b class="const">true</b> if the path
is found, and <b class="const">false</b> otherwise.</p></dd>
<dt><a name="9"><b class="cmd">::zipfile::decode::iszip</b> <i class="arg">archive</i></a></dt>
<dd><p>This command takes the path of a presumed zip <i class="arg">archive</i> file and
returns a boolean flag as the result of the command telling us if it
actually is a zip archive (<b class="const">true</b>), or not (<b class="const">false</b>).</p></dd>
<dt><a name="10"><b class="cmd">::zipfile::decode::open</b> <i class="arg">archive</i></a></dt>
<dd><p>This command takes the path of a zip <i class="arg">archive</i> file and prepares
it for decoding.
The result of the command is the empty string.
All important information is stored in global state. If multiple open
calls are made one after the other only the state of the last call is
available to the other commands.</p></dd>
<dt><a name="11"><b class="cmd">::zipfile::decode::unzip</b> <i class="arg">adict</i> <i class="arg">dstdir</i></a></dt>
<dd><p>This command takes a dictionary describing the currently open zip
archive file, as returned by <b class="cmd">::zipfile::decode::archive</b>, and
unpacks the archive in the given destination directory <i class="arg">dstdir</i>.
The result of the command is the empty string.</p></dd>
<dt><a name="12"><b class="cmd">::zipfile::decode::unzipfile</b> <i class="arg">archive</i> <i class="arg">dstdir</i></a></dt>
<dd><p>This is a convenience command which unpacks the specified zip
<i class="arg">archive</i> file in the given destination directory <i class="arg">dstdir</i>.</p>
<p>The result of the command is the empty string.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>zipfile</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#decompression">decompression</a>, <a href="../../../../index.html#zip">zip</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008-2016 Andreas Kupries</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/zip/encode.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<div class='fossil-doc' data-title='zipfile::encode - Zip archive handling'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">zipfile::encode(n) 0.4 tcllib "Zip archive handling"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>zipfile::encode - Generation of zip archives</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Class API</a></li>
<li class="doctools_section"><a href="#section3">Instance API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.4</b></li>
<li>package require <b class="pkgname">logger</b></li>
<li>package require <b class="pkgname">Trf</b></li>
<li>package require <b class="pkgname">crc32</b></li>
<li>package require <b class="pkgname">snit</b></li>
<li>package require <b class="pkgname">zlibtcl</b></li>
<li>package require <b class="pkgname">fileutil</b></li>
<li>package require <b class="pkgname">zipfile::encode <span class="opt">?0.4?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::zipfile::encode</b> <span class="opt">?<i class="arg">objectName</i>?</span></a></li>
<li><a href="#2"><b class="cmd"><encoder></b> <b class="method">comment:</b> <i class="arg">text</i></a></li>
<li><a href="#3"><b class="cmd"><encoder></b> <b class="method">file:</b> <i class="arg">dst</i> <i class="arg">owned</i> <i class="arg">src</i> <span class="opt">?<i class="arg">noCompress</i>?</span></a></li>
<li><a href="#4"><b class="cmd"><encoder></b> <b class="method">write</b> <i class="arg">archive</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package provides a class for the generation of zip archives.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Class API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::zipfile::encode</b> <span class="opt">?<i class="arg">objectName</i>?</span></a></dt>
<dd><p>The class command constructs encoder instances, i.e. objects. The
result of the command is the fully-qualified name of the instance
command.</p>
<p>If no <i class="arg">objectName</i> is specified the class will generate and use an
automatic name. If the <i class="arg">objectName</i> was specified, but is not
fully qualified the command will be created in the current namespace.</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Instance API</a></h2>
<dl class="doctools_definitions">
<dt><a name="2"><b class="cmd"><encoder></b> <b class="method">comment:</b> <i class="arg">text</i></a></dt>
<dd><p>This method specifies the text of the global comment for the archive.
The result of the method is the empty string.
In case of multiple calls to this method for the same encoder the data
from the last call prevails over all previous texts.</p></dd>
<dt><a name="3"><b class="cmd"><encoder></b> <b class="method">file:</b> <i class="arg">dst</i> <i class="arg">owned</i> <i class="arg">src</i> <span class="opt">?<i class="arg">noCompress</i>?</span></a></dt>
<dd><p>This method adds a new file to the archive.
The contents of the file are found in the filesystem at <i class="arg">src</i>, and
will be stored in the archive under path <i class="arg">dst</i>.
If the file is declared as <i class="arg">owned</i> by the archive the original
file will be deleted when the archive is constructed and written.
If <i class="arg">noCompress</i> is set to <b class="const">true</b> the file will not be
compressed on writing. Otherwise (the default) the file is compressed
if it is advantageous.
The result of the method is an empty string.</p></dd>
<dt><a name="4"><b class="cmd"><encoder></b> <b class="method">write</b> <i class="arg">archive</i></a></dt>
<dd><p>This method takes the global comment and all added files, encodes them
as a zip archive and stores the result at path <i class="arg">archive</i> in the
filesystem.
All added files which were owned by the archive are deleted at this
point.
On the issue of ordering, the files are added to the archive in the
same order as they were specified via <b class="method">file:</b>. <em>Note</em> that
this behaviour is new for version 0.4 and higher. Before 0.4 no
specific order was documented. It was lexicographically sorted. The
change was made to support <b class="cmd"><a href="../../../../index.html#zip">zip</a></b>-based file formats which require
a specific order of files in the archive, for example "<b class="file">.epub</b>".</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>zipfile</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#compression">compression</a>, <a href="../../../../index.html#zip">zip</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2008-2009 Andreas Kupries</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/files/modules/zip/mkzip.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
<div class='fossil-doc' data-title='zipfile::mkzip - Zip archive creation'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">zipfile::mkzip(n) 1.2 tcllib "Zip archive creation"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>zipfile::mkzip - Build a zip archive</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">API</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">zipfile::mkzip <span class="opt">?1.2?</span></b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::zipfile::mkzip::mkzip</b> <i class="arg">zipfile</i> <span class="opt">?<b class="option">-zipkit</b>?</span> <span class="opt">?<b class="option">-runtime</b> <i class="arg">prefix</i>?</span> <span class="opt">?<b class="option">-comment</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-directory</b> <i class="arg">rootpath</i>?</span> <span class="opt">?<b class="option">-exclude</b> <i class="arg">exclude</i>?</span> <span class="opt">?<b class="option">--</b>?</span> <span class="opt">?<i class="arg">path</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>This package utilizes the zlib functions in Tcl 8.6 to build zip
archives.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::zipfile::mkzip::mkzip</b> <i class="arg">zipfile</i> <span class="opt">?<b class="option">-zipkit</b>?</span> <span class="opt">?<b class="option">-runtime</b> <i class="arg">prefix</i>?</span> <span class="opt">?<b class="option">-comment</b> <i class="arg">string</i>?</span> <span class="opt">?<b class="option">-directory</b> <i class="arg">rootpath</i>?</span> <span class="opt">?<b class="option">-exclude</b> <i class="arg">exclude</i>?</span> <span class="opt">?<b class="option">--</b>?</span> <span class="opt">?<i class="arg">path</i>...?</span></a></dt>
<dd><p>From <a href="http://wiki.tcl.tk/15158">http://wiki.tcl.tk/15158</a></p>
<p>This command constructs a zip archive from a directory tree
using nothing but Tcl 8.6 core features. The resulting zip file should
be compatible with other <b class="syscmd"><a href="../../../../index.html#zip">zip</a></b> programs - with the possible
exception of unicode support. The files generated by this command use
utf-8 encoding for all filenames and comments and it has been noticed
particularly on Windows the <b class="syscmd">info-zip</b> and the Windows built-in
zip view have rather poor support for this part of the ZIP file
specification. The <b class="syscmd">7-Zip</b> program does correctly display utf8
filenames however and the <b class="package">vfs::zip</b> package will use these of
course.</p>
<p>If you use</p>
<pre class="doctools_example"><b class="cmd">::mkzip::mkzip</b> mystuff.tm -zipkit -directory mystuff.vfs</pre>
<p>it will pack your "<b class="file">mystuff.vfs/</b>" virtual filesystem tree into a
zip archive with a suitable header such that on unix you may mark it
executable and it should run with tclkit. Or you can run it with
<b class="syscmd">tclsh</b> or <b class="syscmd">wish</b> 8.6 if you like.</p>
<p>To change the executable header, specify the <b class="option">-runtime</b>
"<b class="file">preface</b>" where preface is a file containing code you want
prefixed. For instance, on Windows you can create a self-extracting
zip archive using</p>
<pre class="doctools_example">
mkzip mystuff.exe -directory mystuff.vfs -runtime unzipsfx.exe
</pre>
<p>The "<b class="file">unzipsfx.exe</b>" is the Info-Zip self-extracting stub.</p>
<p>Accepted options:</p>
<dl class="doctools_options">
<dt><b class="option">-runtime</b> path</dt>
<dd><p>This option specifies a file to use as prefix to the actual zip
archive. If specified <b class="option">-zipkit</b> will be ignored.</p></dd>
<dt><b class="option">-zipkit</b></dt>
<dd><p>Instructs the command to generate a prefix which makes the archive a
zip-based starkit. Ignored if <b class="option">-runtime</b> is present.</p></dd>
<dt><b class="option">-comment</b> string</dt>
<dd><p>This options specifies a global comment to place into the generated
archive.</p></dd>
<dt><b class="option">-directory</b> path</dt>
<dd><p>This option specifies the directory to place into the generated
archive. If specified any argument <i class="arg">path</i>s are <em>ignored</em>.</p></dd>
<dt><b class="option">-exclude</b> list</dt>
<dd><p>This option specifies a list of glob patterns. All paths matching at
least one of the patterns are not placed into the generated archive.
This option defaults to</p>
<pre class="doctools_example">
CVS/* */CVS/* *~ ".#*" "*/.#*"
</pre>
</dd>
<dt><b class="option">--</b></dt>
<dd><p>This option signals the end of the options, forcing processing of all
further words as arguments, even if they begin with a dash character.</p></dd>
</dl>
<p>Accepted arguments:</p>
<dl class="doctools_arguments">
<dt>path <i class="arg">path</i></dt>
<dd><p>Each path is a directory or file to place into the generated archive.
Note however that these will be ignored when option <b class="option">-directory</b>
is specified.</p></dd>
</dl></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>zipfile</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#decompression">decompression</a>, <a href="../../../../index.html#zip">zip</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>File</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2009 Pat Thoyts</p>
</div>
</div>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/tcllib/toc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
|
<div class='fossil-doc' data-title='Table Of Contents'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="../index.html">Keyword Index</a>
| <a href="../toc0.html">Categories</a>
| <a href="../toc1.html">Modules</a>
| <a href="../toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> tcllib </h2><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench'><a href="files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="files/modules/bench/bench_read.html">bench::in</a></td>
<td class="#doctools_tocright">bench::in - Reading benchmark results</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_out_csv'><a href="files/modules/bench/bench_wcsv.html">bench::out::csv</a></td>
<td class="#doctools_tocright">bench::out::csv - Formatting benchmark results as CSV</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_out_text'><a href="files/modules/bench/bench_wtext.html">bench::out::text</a></td>
<td class="#doctools_tocright">bench::out::text - Formatting benchmark results as human readable text</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_intro'><a href="files/modules/bench/bench_intro.html">bench_intro</a></td>
<td class="#doctools_tocright">bench introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_intro'><a href="files/modules/bench/bench_lang_intro.html">bench_lang_intro</a></td>
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='control'><a href="files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='cron'><a href="files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug'><a href="files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='defer'><a href="files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
<td class="#doctools_tocright">docidx language command reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_faq'><a href="files/modules/doctools/docidx_lang_faq.html">docidx_lang_faq</a></td>
<td class="#doctools_tocright">docidx language faq</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_intro'><a href="files/modules/doctools/docidx_lang_intro.html">docidx_lang_intro</a></td>
<td class="#doctools_tocright">docidx language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_syntax'><a href="files/modules/doctools/docidx_lang_syntax.html">docidx_lang_syntax</a></td>
<td class="#doctools_tocright">docidx language syntax</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_plugin_apiref'><a href="files/modules/doctools/docidx_plugin_apiref.html">docidx_plugin_apiref</a></td>
<td class="#doctools_tocright">docidx plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_intro'><a href="files/modules/doctools/doctoc_intro.html">doctoc_intro</a></td>
<td class="#doctools_tocright">doctoc introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_cmdref'><a href="files/modules/doctools/doctoc_lang_cmdref.html">doctoc_lang_cmdref</a></td>
<td class="#doctools_tocright">doctoc language command reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_faq'><a href="files/modules/doctools/doctoc_lang_faq.html">doctoc_lang_faq</a></td>
<td class="#doctools_tocright">doctoc language faq</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_intro'><a href="files/modules/doctools/doctoc_lang_intro.html">doctoc_lang_intro</a></td>
<td class="#doctools_tocright">doctoc language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_syntax'><a href="files/modules/doctools/doctoc_lang_syntax.html">doctoc_lang_syntax</a></td>
<td class="#doctools_tocright">doctoc language syntax</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_plugin_apiref'><a href="files/modules/doctools/doctoc_plugin_apiref.html">doctoc_plugin_apiref</a></td>
<td class="#doctools_tocright">doctoc plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools'><a href="files/modules/doctools/doctools.html">doctools</a></td>
<td class="#doctools_tocright">doctools - Processing documents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_changelog'><a href="files/modules/doctools/changelog.html">doctools::changelog</a></td>
<td class="#doctools_tocright">Processing text in Emacs ChangeLog format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_cvs'><a href="files/modules/doctools/cvs.html">doctools::cvs</a></td>
<td class="#doctools_tocright">Processing text in 'cvs log' format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="files/modules/doctools/docidx.html">doctools::idx</a></td>
<td class="#doctools_tocright">docidx - Processing indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
<td class="#doctools_tocright">Holding keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export'><a href="files/modules/doctools2idx/idx_export.html">doctools::idx::export</a></td>
<td class="#doctools_tocright">Exporting keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_json'><a href="files/modules/doctools2idx/idx_export_json.html">doctools::idx::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_nroff'><a href="files/modules/doctools2idx/idx_export_nroff.html">doctools::idx::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_text'><a href="files/modules/doctools2idx/idx_export_text.html">doctools::idx::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_wiki'><a href="files/modules/doctools2idx/idx_export_wiki.html">doctools::idx::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import'><a href="files/modules/doctools2idx/idx_import.html">doctools::idx::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_docidx'><a href="files/modules/doctools2idx/import_docidx.html">doctools::idx::import::docidx</a></td>
<td class="#doctools_tocright">docidx import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_json'><a href="files/modules/doctools2idx/idx_import_json.html">doctools::idx::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_parse'><a href="files/modules/doctools2idx/idx_parse.html">doctools::idx::parse</a></td>
<td class="#doctools_tocright">Parsing text in docidx format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_structure'><a href="files/modules/doctools2idx/idx_structure.html">doctools::idx::structure</a></td>
<td class="#doctools_tocright">Docidx serialization utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_c'><a href="files/modules/doctools2idx/idx_msgcat_c.html">doctools::msgcat::idx::c</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (C)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_de'><a href="files/modules/doctools2idx/idx_msgcat_de.html">doctools::msgcat::idx::de</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (DE)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_en'><a href="files/modules/doctools2idx/idx_msgcat_en.html">doctools::msgcat::idx::en</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (C)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_de'><a href="files/modules/doctools2toc/toc_msgcat_de.html">doctools::msgcat::toc::de</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (DE)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_en'><a href="files/modules/doctools2toc/toc_msgcat_en.html">doctools::msgcat::toc::en</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_fr'><a href="files/modules/doctools2toc/toc_msgcat_fr.html">doctools::msgcat::toc::fr</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (FR)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="files/modules/doctools2toc/toc_container.html">doctools::toc</a></td>
<td class="#doctools_tocright">Holding tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="files/modules/doctools/doctoc.html">doctools::toc</a></td>
<td class="#doctools_tocright">doctoc - Processing tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export'><a href="files/modules/doctools2toc/toc_export.html">doctools::toc::export</a></td>
<td class="#doctools_tocright">Exporting tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_doctoc'><a href="files/modules/doctools2toc/export_doctoc.html">doctools::toc::export::doctoc</a></td>
<td class="#doctools_tocright">doctoc export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_html'><a href="files/modules/doctools2toc/toc_export_html.html">doctools::toc::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_json'><a href="files/modules/doctools2toc/toc_export_json.html">doctools::toc::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_nroff'><a href="files/modules/doctools2toc/toc_export_nroff.html">doctools::toc::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_text'><a href="files/modules/doctools2toc/toc_export_text.html">doctools::toc::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_wiki'><a href="files/modules/doctools2toc/toc_export_wiki.html">doctools::toc::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import'><a href="files/modules/doctools2toc/toc_import.html">doctools::toc::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_doctoc'><a href="files/modules/doctools2toc/import_doctoc.html">doctools::toc::import::doctoc</a></td>
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_parse'><a href="files/modules/doctools2toc/toc_parse.html">doctools::toc::parse</a></td>
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_intro'><a href="files/modules/doctools/doctools_intro.html">doctools_intro</a></td>
<td class="#doctools_tocright">doctools introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_cmdref'><a href="files/modules/doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a></td>
<td class="#doctools_tocright">doctools language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_faq'><a href="files/modules/doctools/doctools_lang_faq.html">doctools_lang_faq</a></td>
<td class="#doctools_tocright">doctools language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_intro'><a href="files/modules/doctools/doctools_lang_intro.html">doctools_lang_intro</a></td>
<td class="#doctools_tocright">doctools language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_syntax'><a href="files/modules/doctools/doctools_lang_syntax.html">doctools_lang_syntax</a></td>
<td class="#doctools_tocright">doctools language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_plugin_apiref'><a href="files/modules/doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></td>
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
<td class="#doctools_tocright">ME virtual machine state manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_gasm'><a href="files/modules/grammar_me/gasm.html">grammar::me::cpu::gasm</a></td>
<td class="#doctools_tocright">ME assembler</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_tcl'><a href="files/modules/grammar_me/me_tcl.html">grammar::me::tcl</a></td>
<td class="#doctools_tocright">Virtual machine implementation I for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_util'><a href="files/modules/grammar_me/me_util.html">grammar::me::util</a></td>
<td class="#doctools_tocright">AST utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_ast'><a href="files/modules/grammar_me/me_ast.html">grammar::me_ast</a></td>
<td class="#doctools_tocright">Various representations of ASTs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_intro'><a href="files/modules/grammar_me/me_intro.html">grammar::me_intro</a></td>
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='html'><a href="files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='interp'><a href="files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json'><a href="files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='log'><a href="files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger'><a href="files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math'><a href="files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="files/modules/math/bigfloat.html">math::bigfloat</a></td>
<td class="#doctools_tocright">Arbitrary precision floating-point numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bignum'><a href="files/modules/math/bignum.html">math::bignum</a></td>
<td class="#doctools_tocright">Arbitrary precision integer numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_calculus'><a href="files/modules/math/calculus.html">math::calculus</a></td>
<td class="#doctools_tocright">Integration and ordinary differential equations</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus_romberg'><a href="files/modules/math/romberg.html">math::calculus::romberg</a></td>
<td class="#doctools_tocright">Romberg integration</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_calculus_symdiff'><a href="files/modules/math/symdiff.html">math::calculus::symdiff</a></td>
<td class="#doctools_tocright">Symbolic differentiation for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_combinatorics'><a href="files/modules/math/combinatorics.html">math::combinatorics</a></td>
<td class="#doctools_tocright">Combinatorial functions in the Tcl Math Library</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_complexnumbers'><a href="files/modules/math/qcomplex.html">math::complexnumbers</a></td>
<td class="#doctools_tocright">Straightforward complex number package</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_constants'><a href="files/modules/math/constants.html">math::constants</a></td>
<td class="#doctools_tocright">Mathematical and numerical constants</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_decimal'><a href="files/modules/math/decimal.html">math::decimal</a></td>
<td class="#doctools_tocright">General decimal arithmetic</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_exact'><a href="files/modules/math/exact.html">math::exact</a></td>
<td class="#doctools_tocright">Exact Real Arithmetic</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_fourier'><a href="files/modules/math/fourier.html">math::fourier</a></td>
<td class="#doctools_tocright">Discrete and fast fourier transforms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_fuzzy'><a href="files/modules/math/fuzzy.html">math::fuzzy</a></td>
<td class="#doctools_tocright">Fuzzy comparison of floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_geometry'><a href="files/modules/math/math_geometry.html">math::geometry</a></td>
<td class="#doctools_tocright">Geometrical computations</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_interpolate'><a href="files/modules/math/interpolate.html">math::interpolate</a></td>
<td class="#doctools_tocright">Interpolation routines</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_linearalgebra'><a href="files/modules/math/linalg.html">math::linearalgebra</a></td>
<td class="#doctools_tocright">Linear Algebra</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_numtheory'><a href="files/modules/math/numtheory.html">math::numtheory</a></td>
<td class="#doctools_tocright">Number Theory</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_optimize'><a href="files/modules/math/optimize.html">math::optimize</a></td>
<td class="#doctools_tocright">Optimisation routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_pca'><a href="files/modules/math/pca.html">math::PCA</a></td>
<td class="#doctools_tocright">Package for Principal Component Analysis</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_polynomials'><a href="files/modules/math/polynomials.html">math::polynomials</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_rationalfunctions'><a href="files/modules/math/rational_funcs.html">math::rationalfunctions</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_roman'><a href="files/modules/math/roman.html">math::roman</a></td>
<td class="#doctools_tocright">Tools for creating and manipulating roman numerals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_special'><a href="files/modules/math/special.html">math::special</a></td>
<td class="#doctools_tocright">Special mathematical functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_statistics'><a href="files/modules/math/statistics.html">math::statistics</a></td>
<td class="#doctools_tocright">Basic statistical functions and procedures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_trig'><a href="files/modules/math/trig.html">math::trig</a></td>
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='md5'><a href="files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mime'><a href="files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="files/modules/nns/nns_auto.html">nameserv::auto</a></td>
<td class="#doctools_tocright">Name service facility, Client Extension</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_common'><a href="files/modules/nns/nns_common.html">nameserv::common</a></td>
<td class="#doctools_tocright">Name service facility, shared definitions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_protocol'><a href="files/modules/nns/nns_protocol.html">nameserv::protocol</a></td>
<td class="#doctools_tocright">Name service facility, client/server protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_server'><a href="files/modules/nns/nns_server.html">nameserv::server</a></td>
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="files/apps/nns.html">nns</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nnsd'><a href="files/apps/nnsd.html">nnsd</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Server Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nnslog'><a href="files/apps/nnslog.html">nnslog</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Logging Client Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='otp'><a href="files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
<td class="#doctools_tocright">page plugin manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_flow'><a href="files/modules/page/page_util_flow.html">page_util_flow</a></td>
<td class="#doctools_tocright">page dataflow/treewalker utility</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_norm_lemon'><a href="files/modules/page/page_util_norm_lemon.html">page_util_norm_lemon</a></td>
<td class="#doctools_tocright">page AST normalization, LEMON</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_norm_peg'><a href="files/modules/page/page_util_norm_peg.html">page_util_norm_peg</a></td>
<td class="#doctools_tocright">page AST normalization, PEG</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_peg'><a href="files/modules/page/page_util_peg.html">page_util_peg</a></td>
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pki'><a href="files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='png'><a href="files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='processman'><a href="files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt'><a href="files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, Critcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_tea'><a href="files/modules/pt/pt_cparam_config_tea.html">pt::cparam::configuration::tea</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, TEA</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_json_language'><a href="files/modules/pt/pt_json_language.html">pt::json_language</a></td>
<td class="#doctools_tocright">The JSON Grammar Exchange Format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_param'><a href="files/modules/pt/pt_param.html">pt::param</a></td>
<td class="#doctools_tocright">PackRat Machine Specification</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pe'><a href="files/modules/pt/pt_pexpression.html">pt::pe</a></td>
<td class="#doctools_tocright">Parsing Expression Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pe_op'><a href="files/modules/pt/pt_pexpr_op.html">pt::pe::op</a></td>
<td class="#doctools_tocright">Parsing Expression Utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg'><a href="files/modules/pt/pt_pegrammar.html">pt::peg</a></td>
<td class="#doctools_tocright">Parsing Expression Grammar Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_container'><a href="files/modules/pt/pt_peg_container.html">pt::peg::container</a></td>
<td class="#doctools_tocright">PEG Storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_container_peg'><a href="files/modules/pt/pt_peg_container_peg.html">pt::peg::container::peg</a></td>
<td class="#doctools_tocright">PEG Storage. Canned PEG grammar specification</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export'><a href="files/modules/pt/pt_peg_export.html">pt::peg::export</a></td>
<td class="#doctools_tocright">PEG Export</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_container'><a href="files/modules/pt/pt_peg_export_container.html">pt::peg::export::container</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_json'><a href="files/modules/pt/pt_peg_export_json.html">pt::peg::export::json</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_peg'><a href="files/modules/pt/pt_peg_export_peg.html">pt::peg::export::peg</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_container'><a href="files/modules/pt/pt_peg_from_container.html">pt::peg::from::container</a></td>
<td class="#doctools_tocright">PEG Conversion. From CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_json'><a href="files/modules/pt/pt_peg_from_json.html">pt::peg::from::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Read JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_peg'><a href="files/modules/pt/pt_peg_from_peg.html">pt::peg::from::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Read PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import'><a href="files/modules/pt/pt_peg_import.html">pt::peg::import</a></td>
<td class="#doctools_tocright">PEG Import</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_container'><a href="files/modules/pt/pt_peg_import_container.html">pt::peg::import::container</a></td>
<td class="#doctools_tocright">PEG Import Plugin. From CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_json'><a href="files/modules/pt/pt_peg_import_json.html">pt::peg::import::json</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_peg'><a href="files/modules/pt/pt_peg_import_peg.html">pt::peg::import::peg</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_interp'><a href="files/modules/pt/pt_peg_interp.html">pt::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_container'><a href="files/modules/pt/pt_peg_to_container.html">pt::peg::to::container</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_cparam'><a href="files/modules/pt/pt_peg_to_cparam.html">pt::peg::to::cparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CPARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_json'><a href="files/modules/pt/pt_peg_to_json.html">pt::peg::to::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Write JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_param'><a href="files/modules/pt/pt_peg_to_param.html">pt::peg::to::param</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_peg'><a href="files/modules/pt/pt_peg_to_peg.html">pt::peg::to::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_tclparam'><a href="files/modules/pt/pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write TCLPARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_language'><a href="files/modules/pt/pt_peg_language.html">pt::peg_language</a></td>
<td class="#doctools_tocright">PEG Language Tutorial</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pegrammar'><a href="files/modules/pt/pt_peg_introduction.html">pt::pegrammar</a></td>
<td class="#doctools_tocright">Introduction to Parsing Expression Grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pgen'><a href="files/modules/pt/pt_pgen.html">pt::pgen</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_rde'><a href="files/modules/pt/pt_rdengine.html">pt::rde</a></td>
<td class="#doctools_tocright">Parsing Runtime Support, PARAM based</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_nx'><a href="files/modules/pt/pt_tclparam_config_nx.html">pt::tclparam::configuration::nx</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, NX</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_snit'><a href="files/modules/pt/pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Snit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_tcloo'><a href="files/modules/pt/pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Tcloo</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_util'><a href="files/modules/pt/pt_util.html">pt::util</a></td>
<td class="#doctools_tocright">General utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_export_api'><a href="files/modules/pt/pt_to_api.html">pt_export_api</a></td>
<td class="#doctools_tocright">Parser Tools Export API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_import_api'><a href="files/modules/pt/pt_from_api.html">pt_import_api</a></td>
<td class="#doctools_tocright">Parser Tools Import API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_introduction'><a href="files/modules/pt/pt_introduction.html">pt_introduction</a></td>
<td class="#doctools_tocright">Introduction to Parser Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_parse_peg'><a href="files/modules/pt/pt_parse_peg.html">pt_parse_peg</a></td>
<td class="#doctools_tocright">Parser Tools PEG Parser</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_parser_api'><a href="files/modules/pt/pt_parser_api.html">pt_parser_api</a></td>
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rest'><a href="files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="files/modules/struct/graph.html">struct::graph</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_graph_op'><a href="files/modules/struct/graphops.html">struct::graph::op</a></td>
<td class="#doctools_tocright">Operation for (un)directed graph objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph_v1'><a href="files/modules/struct/graph1.html">struct::graph_v1</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_list'><a href="files/modules/struct/struct_list.html">struct::list</a></td>
<td class="#doctools_tocright">Procedures for manipulating lists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_matrix'><a href="files/modules/struct/matrix.html">struct::matrix</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_matrix_v1'><a href="files/modules/struct/matrix1.html">struct::matrix_v1</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_pool'><a href="files/modules/struct/pool.html">struct::pool</a></td>
<td class="#doctools_tocright">Create and manipulate pool objects (of discrete items)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_prioqueue'><a href="files/modules/struct/prioqueue.html">struct::prioqueue</a></td>
<td class="#doctools_tocright">Create and manipulate prioqueue objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_queue'><a href="files/modules/struct/queue.html">struct::queue</a></td>
<td class="#doctools_tocright">Create and manipulate queue objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_record'><a href="files/modules/struct/record.html">struct::record</a></td>
<td class="#doctools_tocright">Define and create records (similar to 'C' structures)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_set'><a href="files/modules/struct/struct_set.html">struct::set</a></td>
<td class="#doctools_tocright">Procedures for manipulating sets</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_skiplist'><a href="files/modules/struct/skiplist.html">struct::skiplist</a></td>
<td class="#doctools_tocright">Create and manipulate skiplists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_stack'><a href="files/modules/struct/stack.html">struct::stack</a></td>
<td class="#doctools_tocright">Create and manipulate stack objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_tree'><a href="files/modules/struct/struct_tree.html">struct::tree</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sum'><a href="files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
<td class="#doctools_tocright">Facade channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo'><a href="files/modules/virtchannel_base/tcllib_fifo.html">tcl::chan::fifo</a></td>
<td class="#doctools_tocright">In-memory fifo channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo2'><a href="files/modules/virtchannel_base/tcllib_fifo2.html">tcl::chan::fifo2</a></td>
<td class="#doctools_tocright">In-memory interconnected fifo channels</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_halfpipe'><a href="files/modules/virtchannel_base/halfpipe.html">tcl::chan::halfpipe</a></td>
<td class="#doctools_tocright">In-memory channel, half of a fifo2</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_memchan'><a href="files/modules/virtchannel_base/tcllib_memchan.html">tcl::chan::memchan</a></td>
<td class="#doctools_tocright">In-memory channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_null'><a href="files/modules/virtchannel_base/tcllib_null.html">tcl::chan::null</a></td>
<td class="#doctools_tocright">Null channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_nullzero'><a href="files/modules/virtchannel_base/nullzero.html">tcl::chan::nullzero</a></td>
<td class="#doctools_tocright">Null/Zero channel combination</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_random'><a href="files/modules/virtchannel_base/tcllib_random.html">tcl::chan::random</a></td>
<td class="#doctools_tocright">Random channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_std'><a href="files/modules/virtchannel_base/std.html">tcl::chan::std</a></td>
<td class="#doctools_tocright">Standard I/O, unification of stdin and stdout</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_string'><a href="files/modules/virtchannel_base/tcllib_string.html">tcl::chan::string</a></td>
<td class="#doctools_tocright">Read-only in-memory channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_textwindow'><a href="files/modules/virtchannel_base/textwindow.html">tcl::chan::textwindow</a></td>
<td class="#doctools_tocright">Textwindow channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_variable'><a href="files/modules/virtchannel_base/tcllib_variable.html">tcl::chan::variable</a></td>
<td class="#doctools_tocright">In-memory channel using variable for storage</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_zero'><a href="files/modules/virtchannel_base/tcllib_zero.html">tcl::chan::zero</a></td>
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
<td class="#doctools_tocright">Base64 encoding transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_counter'><a href="files/modules/virtchannel_transform/vt_counter.html">tcl::transform::counter</a></td>
<td class="#doctools_tocright">Counter transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_crc32'><a href="files/modules/virtchannel_transform/vt_crc32.html">tcl::transform::crc32</a></td>
<td class="#doctools_tocright">Crc32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_hex'><a href="files/modules/virtchannel_transform/hex.html">tcl::transform::hex</a></td>
<td class="#doctools_tocright">Hexadecimal encoding transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_identity'><a href="files/modules/virtchannel_transform/identity.html">tcl::transform::identity</a></td>
<td class="#doctools_tocright">Identity transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_limitsize'><a href="files/modules/virtchannel_transform/limitsize.html">tcl::transform::limitsize</a></td>
<td class="#doctools_tocright">limiting input</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_observe'><a href="files/modules/virtchannel_transform/observe.html">tcl::transform::observe</a></td>
<td class="#doctools_tocright">Observer transformation, stream copy</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_otp'><a href="files/modules/virtchannel_transform/vt_otp.html">tcl::transform::otp</a></td>
<td class="#doctools_tocright">Encryption via one-time pad</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_rot'><a href="files/modules/virtchannel_transform/rot.html">tcl::transform::rot</a></td>
<td class="#doctools_tocright">rot-encryption</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_spacer'><a href="files/modules/virtchannel_transform/spacer.html">tcl::transform::spacer</a></td>
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="files/modules/term/ansi_code.html">term::ansi::code</a></td>
<td class="#doctools_tocright">Helper for control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_attr'><a href="files/modules/term/ansi_cattr.html">term::ansi::code::attr</a></td>
<td class="#doctools_tocright">ANSI attribute sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_ctrl'><a href="files/modules/term/ansi_cctrl.html">term::ansi::code::ctrl</a></td>
<td class="#doctools_tocright">ANSI control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_macros'><a href="files/modules/term/ansi_cmacros.html">term::ansi::code::macros</a></td>
<td class="#doctools_tocright">Macro sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_ctrl_unix'><a href="files/modules/term/ansi_ctrlu.html">term::ansi::ctrl::unix</a></td>
<td class="#doctools_tocright">Control operations and queries</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_send'><a href="files/modules/term/ansi_send.html">term::ansi::send</a></td>
<td class="#doctools_tocright">Output of ANSI control sequences to terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_interact_menu'><a href="files/modules/term/imenu.html">term::interact::menu</a></td>
<td class="#doctools_tocright">Terminal widget, menu</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_interact_pager'><a href="files/modules/term/ipager.html">term::interact::pager</a></td>
<td class="#doctools_tocright">Terminal widget, paging</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_receive'><a href="files/modules/term/receive.html">term::receive</a></td>
<td class="#doctools_tocright">General input from terminals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_receive_bind'><a href="files/modules/term/term_bind.html">term::receive::bind</a></td>
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="files/modules/textutil/adjust.html">textutil::adjust</a></td>
<td class="#doctools_tocright">Procedures to adjust, indent, and undent paragraphs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_repeat'><a href="files/modules/textutil/repeat.html">textutil::repeat</a></td>
<td class="#doctools_tocright">Procedures to repeat strings.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_split'><a href="files/modules/textutil/textutil_split.html">textutil::split</a></td>
<td class="#doctools_tocright">Procedures to split texts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_string'><a href="files/modules/textutil/textutil_string.html">textutil::string</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_tabify'><a href="files/modules/textutil/tabify.html">textutil::tabify</a></td>
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="files/modules/transfer/copyops.html">transfer::copy</a></td>
<td class="#doctools_tocright">Data transfer foundation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy_queue'><a href="files/modules/transfer/tqueue.html">transfer::copy::queue</a></td>
<td class="#doctools_tocright">Queued transfers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_data_destination'><a href="files/modules/transfer/ddest.html">transfer::data::destination</a></td>
<td class="#doctools_tocright">Data destination</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_data_source'><a href="files/modules/transfer/dsource.html">transfer::data::source</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_receiver'><a href="files/modules/transfer/receiver.html">transfer::receiver</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='units'><a href="files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
<td class="#doctools_tocright">Validation for AMEX creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_discover'><a href="files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></td>
<td class="#doctools_tocright">Validation for Discover creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_mastercard'><a href="files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></td>
<td class="#doctools_tocright">Validation for Mastercard creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_visa'><a href="files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></td>
<td class="#doctools_tocright">Validation for VISA creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_gs1_ean13'><a href="files/modules/valtype/ean13.html">valtype::gs1::ean13</a></td>
<td class="#doctools_tocright">Validation for EAN13</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_iban'><a href="files/modules/valtype/iban.html">valtype::iban</a></td>
<td class="#doctools_tocright">Validation for IBAN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_imei'><a href="files/modules/valtype/imei.html">valtype::imei</a></td>
<td class="#doctools_tocright">Validation for IMEI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_isbn'><a href="files/modules/valtype/isbn.html">valtype::isbn</a></td>
<td class="#doctools_tocright">Validation for ISBN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_luhn'><a href="files/modules/valtype/luhn.html">valtype::luhn</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN checkdigit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_luhn5'><a href="files/modules/valtype/luhn5.html">valtype::luhn5</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN5 checkdigit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table>
</dl><hr>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/toc.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
|
<div class='fossil-doc' data-title='Table Of Contents'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='by_categories'>By Categories<dd>
<dl><dt><a name='argument_entry_form_mega_widget'>Argument entry form, mega widget<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='benchmark_tools'>Benchmark tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
<td class="#doctools_tocright">bench::in - Reading benchmark results</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_out_csv'><a href="tcllib/files/modules/bench/bench_wcsv.html">bench::out::csv</a></td>
<td class="#doctools_tocright">bench::out::csv - Formatting benchmark results as CSV</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_out_text'><a href="tcllib/files/modules/bench/bench_wtext.html">bench::out::text</a></td>
<td class="#doctools_tocright">bench::out::text - Formatting benchmark results as human readable text</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_intro'><a href="tcllib/files/modules/bench/bench_intro.html">bench_intro</a></td>
<td class="#doctools_tocright">bench introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_lang_intro'><a href="tcllib/files/modules/bench/bench_lang_intro.html">bench_lang_intro</a></td>
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='cgi_programming'>CGI programming<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='channels'>Channels<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
<td class="#doctools_tocright">Facade channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html">tcl::chan::fifo</a></td>
<td class="#doctools_tocright">In-memory fifo channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo2'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html">tcl::chan::fifo2</a></td>
<td class="#doctools_tocright">In-memory interconnected fifo channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_halfpipe'><a href="tcllib/files/modules/virtchannel_base/halfpipe.html">tcl::chan::halfpipe</a></td>
<td class="#doctools_tocright">In-memory channel, half of a fifo2</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_memchan'><a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html">tcl::chan::memchan</a></td>
<td class="#doctools_tocright">In-memory channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_null'><a href="tcllib/files/modules/virtchannel_base/tcllib_null.html">tcl::chan::null</a></td>
<td class="#doctools_tocright">Null channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_nullzero'><a href="tcllib/files/modules/virtchannel_base/nullzero.html">tcl::chan::nullzero</a></td>
<td class="#doctools_tocright">Null/Zero channel combination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_random'><a href="tcllib/files/modules/virtchannel_base/tcllib_random.html">tcl::chan::random</a></td>
<td class="#doctools_tocright">Random channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_std'><a href="tcllib/files/modules/virtchannel_base/std.html">tcl::chan::std</a></td>
<td class="#doctools_tocright">Standard I/O, unification of stdin and stdout</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_string'><a href="tcllib/files/modules/virtchannel_base/tcllib_string.html">tcl::chan::string</a></td>
<td class="#doctools_tocright">Read-only in-memory channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_textwindow'><a href="tcllib/files/modules/virtchannel_base/textwindow.html">tcl::chan::textwindow</a></td>
<td class="#doctools_tocright">Textwindow channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_variable'><a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html">tcl::chan::variable</a></td>
<td class="#doctools_tocright">In-memory channel using variable for storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_zero'><a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html">tcl::chan::zero</a></td>
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
<td class="#doctools_tocright">Base64 encoding transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_counter'><a href="tcllib/files/modules/virtchannel_transform/vt_counter.html">tcl::transform::counter</a></td>
<td class="#doctools_tocright">Counter transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_crc32'><a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html">tcl::transform::crc32</a></td>
<td class="#doctools_tocright">Crc32 transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_hex'><a href="tcllib/files/modules/virtchannel_transform/hex.html">tcl::transform::hex</a></td>
<td class="#doctools_tocright">Hexadecimal encoding transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_identity'><a href="tcllib/files/modules/virtchannel_transform/identity.html">tcl::transform::identity</a></td>
<td class="#doctools_tocright">Identity transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_limitsize'><a href="tcllib/files/modules/virtchannel_transform/limitsize.html">tcl::transform::limitsize</a></td>
<td class="#doctools_tocright">limiting input</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_observe'><a href="tcllib/files/modules/virtchannel_transform/observe.html">tcl::transform::observe</a></td>
<td class="#doctools_tocright">Observer transformation, stream copy</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_otp'><a href="tcllib/files/modules/virtchannel_transform/vt_otp.html">tcl::transform::otp</a></td>
<td class="#doctools_tocright">Encryption via one-time pad</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_rot'><a href="tcllib/files/modules/virtchannel_transform/rot.html">tcl::transform::rot</a></td>
<td class="#doctools_tocright">rot-encryption</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_spacer'><a href="tcllib/files/modules/virtchannel_transform/spacer.html">tcl::transform::spacer</a></td>
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>Coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='data_structures'>Data structures<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_graph_op'><a href="tcllib/files/modules/struct/graphops.html">struct::graph::op</a></td>
<td class="#doctools_tocright">Operation for (un)directed graph objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph_v1'><a href="tcllib/files/modules/struct/graph1.html">struct::graph_v1</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_list'><a href="tcllib/files/modules/struct/struct_list.html">struct::list</a></td>
<td class="#doctools_tocright">Procedures for manipulating lists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_matrix'><a href="tcllib/files/modules/struct/matrix.html">struct::matrix</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_matrix_v1'><a href="tcllib/files/modules/struct/matrix1.html">struct::matrix_v1</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_pool'><a href="tcllib/files/modules/struct/pool.html">struct::pool</a></td>
<td class="#doctools_tocright">Create and manipulate pool objects (of discrete items)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_prioqueue'><a href="tcllib/files/modules/struct/prioqueue.html">struct::prioqueue</a></td>
<td class="#doctools_tocright">Create and manipulate prioqueue objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_queue'><a href="tcllib/files/modules/struct/queue.html">struct::queue</a></td>
<td class="#doctools_tocright">Create and manipulate queue objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_record'><a href="tcllib/files/modules/struct/record.html">struct::record</a></td>
<td class="#doctools_tocright">Define and create records (similar to 'C' structures)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_set'><a href="tcllib/files/modules/struct/struct_set.html">struct::set</a></td>
<td class="#doctools_tocright">Procedures for manipulating sets</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_skiplist'><a href="tcllib/files/modules/struct/skiplist.html">struct::skiplist</a></td>
<td class="#doctools_tocright">Create and manipulate skiplists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_stack'><a href="tcllib/files/modules/struct/stack.html">struct::stack</a></td>
<td class="#doctools_tocright">Create and manipulate stack objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_tree'><a href="tcllib/files/modules/struct/struct_tree.html">struct::tree</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='debugging_tracing_and_logging'>debugging, tracing, and logging<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='documentation_tools'>Documentation tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
<td class="#doctools_tocright">docidx language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_faq'><a href="tcllib/files/modules/doctools/docidx_lang_faq.html">docidx_lang_faq</a></td>
<td class="#doctools_tocright">docidx language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_intro'><a href="tcllib/files/modules/doctools/docidx_lang_intro.html">docidx_lang_intro</a></td>
<td class="#doctools_tocright">docidx language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_syntax'><a href="tcllib/files/modules/doctools/docidx_lang_syntax.html">docidx_lang_syntax</a></td>
<td class="#doctools_tocright">docidx language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_plugin_apiref'><a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html">docidx_plugin_apiref</a></td>
<td class="#doctools_tocright">docidx plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_intro'><a href="tcllib/files/modules/doctools/doctoc_intro.html">doctoc_intro</a></td>
<td class="#doctools_tocright">doctoc introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_cmdref'><a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html">doctoc_lang_cmdref</a></td>
<td class="#doctools_tocright">doctoc language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_faq'><a href="tcllib/files/modules/doctools/doctoc_lang_faq.html">doctoc_lang_faq</a></td>
<td class="#doctools_tocright">doctoc language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_intro'><a href="tcllib/files/modules/doctools/doctoc_lang_intro.html">doctoc_lang_intro</a></td>
<td class="#doctools_tocright">doctoc language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_syntax'><a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html">doctoc_lang_syntax</a></td>
<td class="#doctools_tocright">doctoc language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_plugin_apiref'><a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html">doctoc_plugin_apiref</a></td>
<td class="#doctools_tocright">doctoc plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools'><a href="tcllib/files/modules/doctools/doctools.html">doctools</a></td>
<td class="#doctools_tocright">doctools - Processing documents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_changelog'><a href="tcllib/files/modules/doctools/changelog.html">doctools::changelog</a></td>
<td class="#doctools_tocright">Processing text in Emacs ChangeLog format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_cvs'><a href="tcllib/files/modules/doctools/cvs.html">doctools::cvs</a></td>
<td class="#doctools_tocright">Processing text in 'cvs log' format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
<td class="#doctools_tocright">Holding keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools/docidx.html">doctools::idx</a></td>
<td class="#doctools_tocright">docidx - Processing indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export'><a href="tcllib/files/modules/doctools2idx/idx_export.html">doctools::idx::export</a></td>
<td class="#doctools_tocright">Exporting keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import'><a href="tcllib/files/modules/doctools2idx/idx_import.html">doctools::idx::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_parse'><a href="tcllib/files/modules/doctools2idx/idx_parse.html">doctools::idx::parse</a></td>
<td class="#doctools_tocright">Parsing text in docidx format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_structure'><a href="tcllib/files/modules/doctools2idx/idx_structure.html">doctools::idx::structure</a></td>
<td class="#doctools_tocright">Docidx serialization utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_c'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html">doctools::msgcat::idx::c</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (C)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_de'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html">doctools::msgcat::idx::de</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (DE)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_en'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html">doctools::msgcat::idx::en</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (C)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_de'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html">doctools::msgcat::toc::de</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (DE)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_en'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html">doctools::msgcat::toc::en</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (EN)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_fr'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html">doctools::msgcat::toc::fr</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (FR)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools2toc/toc_container.html">doctools::toc</a></td>
<td class="#doctools_tocright">Holding tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools/doctoc.html">doctools::toc</a></td>
<td class="#doctools_tocright">doctoc - Processing tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export'><a href="tcllib/files/modules/doctools2toc/toc_export.html">doctools::toc::export</a></td>
<td class="#doctools_tocright">Exporting tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import'><a href="tcllib/files/modules/doctools2toc/toc_import.html">doctools::toc::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_parse'><a href="tcllib/files/modules/doctools2toc/toc_parse.html">doctools::toc::parse</a></td>
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_intro'><a href="tcllib/files/modules/doctools/doctools_intro.html">doctools_intro</a></td>
<td class="#doctools_tocright">doctools introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_cmdref'><a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a></td>
<td class="#doctools_tocright">doctools language command reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_faq'><a href="tcllib/files/modules/doctools/doctools_lang_faq.html">doctools_lang_faq</a></td>
<td class="#doctools_tocright">doctools language faq</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_intro'><a href="tcllib/files/modules/doctools/doctools_lang_intro.html">doctools_lang_intro</a></td>
<td class="#doctools_tocright">doctools language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_syntax'><a href="tcllib/files/modules/doctools/doctools_lang_syntax.html">doctools_lang_syntax</a></td>
<td class="#doctools_tocright">doctools language syntax</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_plugin_apiref'><a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></td>
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
</table></dl>
<dl><dt><a name='file'>File<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
<dl><dt><a name='file_formats'>File formats<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='grammars_and_finite_automata'>Grammars and finite automata<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
<td class="#doctools_tocright">ME virtual machine state manipulation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_gasm'><a href="tcllib/files/modules/grammar_me/gasm.html">grammar::me::cpu::gasm</a></td>
<td class="#doctools_tocright">ME assembler</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_tcl'><a href="tcllib/files/modules/grammar_me/me_tcl.html">grammar::me::tcl</a></td>
<td class="#doctools_tocright">Virtual machine implementation I for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_util'><a href="tcllib/files/modules/grammar_me/me_util.html">grammar::me::util</a></td>
<td class="#doctools_tocright">AST utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_ast'><a href="tcllib/files/modules/grammar_me/me_ast.html">grammar::me_ast</a></td>
<td class="#doctools_tocright">Various representations of ASTs</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_intro'><a href="tcllib/files/modules/grammar_me/me_intro.html">grammar::me_intro</a></td>
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hashes_checksums_and_encryption'>Hashes, checksums, and encryption<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='mathematics'>Mathematics<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
<td class="#doctools_tocright">Arbitrary precision floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_bignum'><a href="tcllib/files/modules/math/bignum.html">math::bignum</a></td>
<td class="#doctools_tocright">Arbitrary precision integer numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus'><a href="tcllib/files/modules/math/calculus.html">math::calculus</a></td>
<td class="#doctools_tocright">Integration and ordinary differential equations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_calculus_romberg'><a href="tcllib/files/modules/math/romberg.html">math::calculus::romberg</a></td>
<td class="#doctools_tocright">Romberg integration</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_combinatorics'><a href="tcllib/files/modules/math/combinatorics.html">math::combinatorics</a></td>
<td class="#doctools_tocright">Combinatorial functions in the Tcl Math Library</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_complexnumbers'><a href="tcllib/files/modules/math/qcomplex.html">math::complexnumbers</a></td>
<td class="#doctools_tocright">Straightforward complex number package</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_constants'><a href="tcllib/files/modules/math/constants.html">math::constants</a></td>
<td class="#doctools_tocright">Mathematical and numerical constants</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_decimal'><a href="tcllib/files/modules/math/decimal.html">math::decimal</a></td>
<td class="#doctools_tocright">General decimal arithmetic</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_exact'><a href="tcllib/files/modules/math/exact.html">math::exact</a></td>
<td class="#doctools_tocright">Exact Real Arithmetic</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_fourier'><a href="tcllib/files/modules/math/fourier.html">math::fourier</a></td>
<td class="#doctools_tocright">Discrete and fast fourier transforms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_fuzzy'><a href="tcllib/files/modules/math/fuzzy.html">math::fuzzy</a></td>
<td class="#doctools_tocright">Fuzzy comparison of floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_geometry'><a href="tcllib/files/modules/math/math_geometry.html">math::geometry</a></td>
<td class="#doctools_tocright">Geometrical computations</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_interpolate'><a href="tcllib/files/modules/math/interpolate.html">math::interpolate</a></td>
<td class="#doctools_tocright">Interpolation routines</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_linearalgebra'><a href="tcllib/files/modules/math/linalg.html">math::linearalgebra</a></td>
<td class="#doctools_tocright">Linear Algebra</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_numtheory'><a href="tcllib/files/modules/math/numtheory.html">math::numtheory</a></td>
<td class="#doctools_tocright">Number Theory</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_optimize'><a href="tcllib/files/modules/math/optimize.html">math::optimize</a></td>
<td class="#doctools_tocright">Optimisation routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_pca'><a href="tcllib/files/modules/math/pca.html">math::PCA</a></td>
<td class="#doctools_tocright">Package for Principal Component Analysis</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_polynomials'><a href="tcllib/files/modules/math/polynomials.html">math::polynomials</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_rationalfunctions'><a href="tcllib/files/modules/math/rational_funcs.html">math::rationalfunctions</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_roman'><a href="tcllib/files/modules/math/roman.html">math::roman</a></td>
<td class="#doctools_tocright">Tools for creating and manipulating roman numerals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_special'><a href="tcllib/files/modules/math/special.html">math::special</a></td>
<td class="#doctools_tocright">Special mathematical functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_statistics'><a href="tcllib/files/modules/math/statistics.html">math::statistics</a></td>
<td class="#doctools_tocright">Basic statistical functions and procedures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_trig'><a href="tcllib/files/modules/math/trig.html">math::trig</a></td>
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='networking'>Networking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
<td class="#doctools_tocright">Name service facility, Client Extension</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_common'><a href="tcllib/files/modules/nns/nns_common.html">nameserv::common</a></td>
<td class="#doctools_tocright">Name service facility, shared definitions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_protocol'><a href="tcllib/files/modules/nns/nns_protocol.html">nameserv::protocol</a></td>
<td class="#doctools_tocright">Name service facility, client/server protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_server'><a href="tcllib/files/modules/nns/nns_server.html">nameserv::server</a></td>
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nnsd'><a href="tcllib/files/apps/nnsd.html">nnsd</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Server Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nnslog'><a href="tcllib/files/apps/nnslog.html">nnslog</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Logging Client Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='page_parser_generator'>Page Parser Generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
<td class="#doctools_tocright">page plugin manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_flow'><a href="tcllib/files/modules/page/page_util_flow.html">page_util_flow</a></td>
<td class="#doctools_tocright">page dataflow/treewalker utility</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_norm_lemon'><a href="tcllib/files/modules/page/page_util_norm_lemon.html">page_util_norm_lemon</a></td>
<td class="#doctools_tocright">page AST normalization, LEMON</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_norm_peg'><a href="tcllib/files/modules/page/page_util_norm_peg.html">page_util_norm_peg</a></td>
<td class="#doctools_tocright">page AST normalization, PEG</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_peg'><a href="tcllib/files/modules/page/page_util_peg.html">page_util_peg</a></td>
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='parsing_and_grammars'>Parsing and Grammars<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, Critcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_tea'><a href="tcllib/files/modules/pt/pt_cparam_config_tea.html">pt::cparam::configuration::tea</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, TEA</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_json_language'><a href="tcllib/files/modules/pt/pt_json_language.html">pt::json_language</a></td>
<td class="#doctools_tocright">The JSON Grammar Exchange Format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_param'><a href="tcllib/files/modules/pt/pt_param.html">pt::param</a></td>
<td class="#doctools_tocright">PackRat Machine Specification</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pe'><a href="tcllib/files/modules/pt/pt_pexpression.html">pt::pe</a></td>
<td class="#doctools_tocright">Parsing Expression Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pe_op'><a href="tcllib/files/modules/pt/pt_pexpr_op.html">pt::pe::op</a></td>
<td class="#doctools_tocright">Parsing Expression Utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg'><a href="tcllib/files/modules/pt/pt_pegrammar.html">pt::peg</a></td>
<td class="#doctools_tocright">Parsing Expression Grammar Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_container'><a href="tcllib/files/modules/pt/pt_peg_container.html">pt::peg::container</a></td>
<td class="#doctools_tocright">PEG Storage</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_container_peg'><a href="tcllib/files/modules/pt/pt_peg_container_peg.html">pt::peg::container::peg</a></td>
<td class="#doctools_tocright">PEG Storage. Canned PEG grammar specification</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export'><a href="tcllib/files/modules/pt/pt_peg_export.html">pt::peg::export</a></td>
<td class="#doctools_tocright">PEG Export</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_container'><a href="tcllib/files/modules/pt/pt_peg_export_container.html">pt::peg::export::container</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_json'><a href="tcllib/files/modules/pt/pt_peg_export_json.html">pt::peg::export::json</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_peg'><a href="tcllib/files/modules/pt/pt_peg_export_peg.html">pt::peg::export::peg</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_container'><a href="tcllib/files/modules/pt/pt_peg_from_container.html">pt::peg::from::container</a></td>
<td class="#doctools_tocright">PEG Conversion. From CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_json'><a href="tcllib/files/modules/pt/pt_peg_from_json.html">pt::peg::from::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Read JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_peg'><a href="tcllib/files/modules/pt/pt_peg_from_peg.html">pt::peg::from::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Read PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import'><a href="tcllib/files/modules/pt/pt_peg_import.html">pt::peg::import</a></td>
<td class="#doctools_tocright">PEG Import</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_container'><a href="tcllib/files/modules/pt/pt_peg_import_container.html">pt::peg::import::container</a></td>
<td class="#doctools_tocright">PEG Import Plugin. From CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_json'><a href="tcllib/files/modules/pt/pt_peg_import_json.html">pt::peg::import::json</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_peg'><a href="tcllib/files/modules/pt/pt_peg_import_peg.html">pt::peg::import::peg</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_interp'><a href="tcllib/files/modules/pt/pt_peg_interp.html">pt::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_container'><a href="tcllib/files/modules/pt/pt_peg_to_container.html">pt::peg::to::container</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_cparam'><a href="tcllib/files/modules/pt/pt_peg_to_cparam.html">pt::peg::to::cparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CPARAM format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_json'><a href="tcllib/files/modules/pt/pt_peg_to_json.html">pt::peg::to::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Write JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_param'><a href="tcllib/files/modules/pt/pt_peg_to_param.html">pt::peg::to::param</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PARAM format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_peg'><a href="tcllib/files/modules/pt/pt_peg_to_peg.html">pt::peg::to::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_tclparam'><a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write TCLPARAM format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_language'><a href="tcllib/files/modules/pt/pt_peg_language.html">pt::peg_language</a></td>
<td class="#doctools_tocright">PEG Language Tutorial</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pegrammar'><a href="tcllib/files/modules/pt/pt_peg_introduction.html">pt::pegrammar</a></td>
<td class="#doctools_tocright">Introduction to Parsing Expression Grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pgen'><a href="tcllib/files/modules/pt/pt_pgen.html">pt::pgen</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_rde'><a href="tcllib/files/modules/pt/pt_rdengine.html">pt::rde</a></td>
<td class="#doctools_tocright">Parsing Runtime Support, PARAM based</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_nx'><a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html">pt::tclparam::configuration::nx</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, NX</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_snit'><a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Snit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_tcloo'><a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Tcloo</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_util'><a href="tcllib/files/modules/pt/pt_util.html">pt::util</a></td>
<td class="#doctools_tocright">General utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_export_api'><a href="tcllib/files/modules/pt/pt_to_api.html">pt_export_api</a></td>
<td class="#doctools_tocright">Parser Tools Export API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_import_api'><a href="tcllib/files/modules/pt/pt_from_api.html">pt_import_api</a></td>
<td class="#doctools_tocright">Parser Tools Import API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_introduction'><a href="tcllib/files/modules/pt/pt_introduction.html">pt_introduction</a></td>
<td class="#doctools_tocright">Introduction to Parser Tools</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_parse_peg'><a href="tcllib/files/modules/pt/pt_parse_peg.html">pt_parse_peg</a></td>
<td class="#doctools_tocright">Parser Tools PEG Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_parser_api'><a href="tcllib/files/modules/pt/pt_parser_api.html">pt_parser_api</a></td>
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='procedures_arguments_parameters_options'>Procedures, arguments, parameters, options<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='programming_tools'>Programming tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='system'>System<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='tcloo'>TclOO<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
</table></dl>
<dl><dt><a name='terminal_control'>Terminal control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
<td class="#doctools_tocright">Helper for control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_attr'><a href="tcllib/files/modules/term/ansi_cattr.html">term::ansi::code::attr</a></td>
<td class="#doctools_tocright">ANSI attribute sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_ctrl'><a href="tcllib/files/modules/term/ansi_cctrl.html">term::ansi::code::ctrl</a></td>
<td class="#doctools_tocright">ANSI control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_macros'><a href="tcllib/files/modules/term/ansi_cmacros.html">term::ansi::code::macros</a></td>
<td class="#doctools_tocright">Macro sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_ctrl_unix'><a href="tcllib/files/modules/term/ansi_ctrlu.html">term::ansi::ctrl::unix</a></td>
<td class="#doctools_tocright">Control operations and queries</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_send'><a href="tcllib/files/modules/term/ansi_send.html">term::ansi::send</a></td>
<td class="#doctools_tocright">Output of ANSI control sequences to terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_interact_menu'><a href="tcllib/files/modules/term/imenu.html">term::interact::menu</a></td>
<td class="#doctools_tocright">Terminal widget, menu</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_interact_pager'><a href="tcllib/files/modules/term/ipager.html">term::interact::pager</a></td>
<td class="#doctools_tocright">Terminal widget, paging</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_receive'><a href="tcllib/files/modules/term/receive.html">term::receive</a></td>
<td class="#doctools_tocright">General input from terminals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_receive_bind'><a href="tcllib/files/modules/term/term_bind.html">term::receive::bind</a></td>
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='text_formatter_plugin'>Text formatter plugin<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_json'><a href="tcllib/files/modules/doctools2idx/idx_export_json.html">doctools::idx::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_nroff'><a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html">doctools::idx::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_text'><a href="tcllib/files/modules/doctools2idx/idx_export_text.html">doctools::idx::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_wiki'><a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html">doctools::idx::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_docidx'><a href="tcllib/files/modules/doctools2idx/import_docidx.html">doctools::idx::import::docidx</a></td>
<td class="#doctools_tocright">docidx import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_json'><a href="tcllib/files/modules/doctools2idx/idx_import_json.html">doctools::idx::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_doctoc'><a href="tcllib/files/modules/doctools2toc/export_doctoc.html">doctools::toc::export::doctoc</a></td>
<td class="#doctools_tocright">doctoc export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_html'><a href="tcllib/files/modules/doctools2toc/toc_export_html.html">doctools::toc::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_json'><a href="tcllib/files/modules/doctools2toc/toc_export_json.html">doctools::toc::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_nroff'><a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html">doctools::toc::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_text'><a href="tcllib/files/modules/doctools2toc/toc_export_text.html">doctools::toc::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_wiki'><a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html">doctools::toc::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_doctoc'><a href="tcllib/files/modules/doctools2toc/import_doctoc.html">doctools::toc::import::doctoc</a></td>
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
</table></dl>
<dl><dt><a name='text_processing'>Text processing<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
<td class="#doctools_tocright">Procedures to adjust, indent, and undent paragraphs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_repeat'><a href="tcllib/files/modules/textutil/repeat.html">textutil::repeat</a></td>
<td class="#doctools_tocright">Procedures to repeat strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_split'><a href="tcllib/files/modules/textutil/textutil_split.html">textutil::split</a></td>
<td class="#doctools_tocright">Procedures to split texts</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_string'><a href="tcllib/files/modules/textutil/textutil_string.html">textutil::string</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_tabify'><a href="tcllib/files/modules/textutil/tabify.html">textutil::tabify</a></td>
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='transfer_module'>Transfer module<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
<td class="#doctools_tocright">Data transfer foundation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_copy_queue'><a href="tcllib/files/modules/transfer/tqueue.html">transfer::copy::queue</a></td>
<td class="#doctools_tocright">Queued transfers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_data_destination'><a href="tcllib/files/modules/transfer/ddest.html">transfer::data::destination</a></td>
<td class="#doctools_tocright">Data destination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_data_source'><a href="tcllib/files/modules/transfer/dsource.html">transfer::data::source</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_receiver'><a href="tcllib/files/modules/transfer/receiver.html">transfer::receiver</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='unfiled'>Unfiled<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus_symdiff'><a href="tcllib/files/modules/math/symdiff.html">math::calculus::symdiff</a></td>
<td class="#doctools_tocright">Symbolic differentiation for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='utilities'>Utilities<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='utility'>Utility<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='validation_type_checking'>Validation, Type checking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
<td class="#doctools_tocright">Validation for AMEX creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_discover'><a href="tcllib/files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></td>
<td class="#doctools_tocright">Validation for Discover creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_mastercard'><a href="tcllib/files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></td>
<td class="#doctools_tocright">Validation for Mastercard creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_visa'><a href="tcllib/files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></td>
<td class="#doctools_tocright">Validation for VISA creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_gs1_ean13'><a href="tcllib/files/modules/valtype/ean13.html">valtype::gs1::ean13</a></td>
<td class="#doctools_tocright">Validation for EAN13</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_iban'><a href="tcllib/files/modules/valtype/iban.html">valtype::iban</a></td>
<td class="#doctools_tocright">Validation for IBAN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_imei'><a href="tcllib/files/modules/valtype/imei.html">valtype::imei</a></td>
<td class="#doctools_tocright">Validation for IMEI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_isbn'><a href="tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></td>
<td class="#doctools_tocright">Validation for ISBN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_luhn'><a href="tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN checkdigit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_luhn5'><a href="tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN5 checkdigit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl></table></dl>
<dl><dt><a name='by_type'>By Type<dd>
<dl><dt><a name='applications'>Applications<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nnsd'><a href="tcllib/files/apps/nnsd.html">nnsd</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Server Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nnslog'><a href="tcllib/files/apps/nnslog.html">nnslog</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Logging Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
</table></dl>
<dl><dt><a name='modules'>Modules<dd>
<dl><dt><a name='aes'>aes<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='amazon_s3'>amazon-s3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
</table></dl>
<dl><dt><a name='asn'>asn<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
</table></dl>
<dl><dt><a name='base32'>base32<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
</table></dl>
<dl><dt><a name='base64'>base64<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='bee'>bee<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='bench'>bench<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
<td class="#doctools_tocright">bench::in - Reading benchmark results</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_out_csv'><a href="tcllib/files/modules/bench/bench_wcsv.html">bench::out::csv</a></td>
<td class="#doctools_tocright">bench::out::csv - Formatting benchmark results as CSV</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_out_text'><a href="tcllib/files/modules/bench/bench_wtext.html">bench::out::text</a></td>
<td class="#doctools_tocright">bench::out::text - Formatting benchmark results as human readable text</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_intro'><a href="tcllib/files/modules/bench/bench_intro.html">bench_intro</a></td>
<td class="#doctools_tocright">bench introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_lang_intro'><a href="tcllib/files/modules/bench/bench_lang_intro.html">bench_lang_intro</a></td>
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='bibtex'>bibtex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
</table></dl>
<dl><dt><a name='blowfish'>blowfish<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='cache'>cache<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
</table></dl>
<dl><dt><a name='clock'>clock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
</table></dl>
<dl><dt><a name='cmdline'>cmdline<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
</table></dl>
<dl><dt><a name='comm'>comm<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
</table></dl>
<dl><dt><a name='control'>control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='counter'>counter<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
</table></dl>
<dl><dt><a name='crc'>crc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
</table></dl>
<dl><dt><a name='cron'>cron<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='csv'>csv<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
</table></dl>
<dl><dt><a name='debug'>debug<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='defer'>defer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
</table></dl>
<dl><dt><a name='des'>des<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
</table></dl>
<dl><dt><a name='dicttool'>dicttool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='dns'>dns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='docstrip'>docstrip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
</table></dl>
<dl><dt><a name='doctools'>doctools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
<td class="#doctools_tocright">docidx language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_faq'><a href="tcllib/files/modules/doctools/docidx_lang_faq.html">docidx_lang_faq</a></td>
<td class="#doctools_tocright">docidx language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_intro'><a href="tcllib/files/modules/doctools/docidx_lang_intro.html">docidx_lang_intro</a></td>
<td class="#doctools_tocright">docidx language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_syntax'><a href="tcllib/files/modules/doctools/docidx_lang_syntax.html">docidx_lang_syntax</a></td>
<td class="#doctools_tocright">docidx language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_plugin_apiref'><a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html">docidx_plugin_apiref</a></td>
<td class="#doctools_tocright">docidx plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_intro'><a href="tcllib/files/modules/doctools/doctoc_intro.html">doctoc_intro</a></td>
<td class="#doctools_tocright">doctoc introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_cmdref'><a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html">doctoc_lang_cmdref</a></td>
<td class="#doctools_tocright">doctoc language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_faq'><a href="tcllib/files/modules/doctools/doctoc_lang_faq.html">doctoc_lang_faq</a></td>
<td class="#doctools_tocright">doctoc language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_intro'><a href="tcllib/files/modules/doctools/doctoc_lang_intro.html">doctoc_lang_intro</a></td>
<td class="#doctools_tocright">doctoc language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_syntax'><a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html">doctoc_lang_syntax</a></td>
<td class="#doctools_tocright">doctoc language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_plugin_apiref'><a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html">doctoc_plugin_apiref</a></td>
<td class="#doctools_tocright">doctoc plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools'><a href="tcllib/files/modules/doctools/doctools.html">doctools</a></td>
<td class="#doctools_tocright">doctools - Processing documents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_changelog'><a href="tcllib/files/modules/doctools/changelog.html">doctools::changelog</a></td>
<td class="#doctools_tocright">Processing text in Emacs ChangeLog format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_cvs'><a href="tcllib/files/modules/doctools/cvs.html">doctools::cvs</a></td>
<td class="#doctools_tocright">Processing text in 'cvs log' format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools/docidx.html">doctools::idx</a></td>
<td class="#doctools_tocright">docidx - Processing indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools/doctoc.html">doctools::toc</a></td>
<td class="#doctools_tocright">doctoc - Processing tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_intro'><a href="tcllib/files/modules/doctools/doctools_intro.html">doctools_intro</a></td>
<td class="#doctools_tocright">doctools introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_cmdref'><a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a></td>
<td class="#doctools_tocright">doctools language command reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_faq'><a href="tcllib/files/modules/doctools/doctools_lang_faq.html">doctools_lang_faq</a></td>
<td class="#doctools_tocright">doctools language faq</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_intro'><a href="tcllib/files/modules/doctools/doctools_lang_intro.html">doctools_lang_intro</a></td>
<td class="#doctools_tocright">doctools language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_syntax'><a href="tcllib/files/modules/doctools/doctools_lang_syntax.html">doctools_lang_syntax</a></td>
<td class="#doctools_tocright">doctools language syntax</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_plugin_apiref'><a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></td>
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2base'>doctools2base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2idx'>doctools2idx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
<td class="#doctools_tocright">Holding keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export'><a href="tcllib/files/modules/doctools2idx/idx_export.html">doctools::idx::export</a></td>
<td class="#doctools_tocright">Exporting keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_json'><a href="tcllib/files/modules/doctools2idx/idx_export_json.html">doctools::idx::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_nroff'><a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html">doctools::idx::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_text'><a href="tcllib/files/modules/doctools2idx/idx_export_text.html">doctools::idx::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_wiki'><a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html">doctools::idx::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import'><a href="tcllib/files/modules/doctools2idx/idx_import.html">doctools::idx::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_docidx'><a href="tcllib/files/modules/doctools2idx/import_docidx.html">doctools::idx::import::docidx</a></td>
<td class="#doctools_tocright">docidx import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_json'><a href="tcllib/files/modules/doctools2idx/idx_import_json.html">doctools::idx::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_parse'><a href="tcllib/files/modules/doctools2idx/idx_parse.html">doctools::idx::parse</a></td>
<td class="#doctools_tocright">Parsing text in docidx format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_structure'><a href="tcllib/files/modules/doctools2idx/idx_structure.html">doctools::idx::structure</a></td>
<td class="#doctools_tocright">Docidx serialization utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_c'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html">doctools::msgcat::idx::c</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (C)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_de'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html">doctools::msgcat::idx::de</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (DE)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_en'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html">doctools::msgcat::idx::en</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2toc'>doctools2toc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (C)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_de'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html">doctools::msgcat::toc::de</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (DE)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_en'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html">doctools::msgcat::toc::en</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (EN)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_fr'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html">doctools::msgcat::toc::fr</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (FR)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools2toc/toc_container.html">doctools::toc</a></td>
<td class="#doctools_tocright">Holding tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export'><a href="tcllib/files/modules/doctools2toc/toc_export.html">doctools::toc::export</a></td>
<td class="#doctools_tocright">Exporting tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_doctoc'><a href="tcllib/files/modules/doctools2toc/export_doctoc.html">doctools::toc::export::doctoc</a></td>
<td class="#doctools_tocright">doctoc export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_html'><a href="tcllib/files/modules/doctools2toc/toc_export_html.html">doctools::toc::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_json'><a href="tcllib/files/modules/doctools2toc/toc_export_json.html">doctools::toc::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_nroff'><a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html">doctools::toc::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_text'><a href="tcllib/files/modules/doctools2toc/toc_export_text.html">doctools::toc::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_wiki'><a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html">doctools::toc::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import'><a href="tcllib/files/modules/doctools2toc/toc_import.html">doctools::toc::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_doctoc'><a href="tcllib/files/modules/doctools2toc/import_doctoc.html">doctools::toc::import::doctoc</a></td>
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_parse'><a href="tcllib/files/modules/doctools2toc/toc_parse.html">doctools::toc::parse</a></td>
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
</table></dl>
<dl><dt><a name='dtplite'>dtplite<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
</table></dl>
<dl><dt><a name='fileutil'>fileutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
</table></dl>
<dl><dt><a name='ftp'>ftp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
</table></dl>
<dl><dt><a name='ftpd'>ftpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='fumagic'>fumagic<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='generator'>generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
</table></dl>
<dl><dt><a name='gpx'>gpx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_aycock'>grammar_aycock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_fa'>grammar_fa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_me'>grammar_me<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
<td class="#doctools_tocright">ME virtual machine state manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_gasm'><a href="tcllib/files/modules/grammar_me/gasm.html">grammar::me::cpu::gasm</a></td>
<td class="#doctools_tocright">ME assembler</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_tcl'><a href="tcllib/files/modules/grammar_me/me_tcl.html">grammar::me::tcl</a></td>
<td class="#doctools_tocright">Virtual machine implementation I for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_util'><a href="tcllib/files/modules/grammar_me/me_util.html">grammar::me::util</a></td>
<td class="#doctools_tocright">AST utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_ast'><a href="tcllib/files/modules/grammar_me/me_ast.html">grammar::me_ast</a></td>
<td class="#doctools_tocright">Various representations of ASTs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_intro'><a href="tcllib/files/modules/grammar_me/me_intro.html">grammar::me_intro</a></td>
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_peg'>grammar_peg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hook'>hook<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
</table></dl>
<dl><dt><a name='html'>html<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
</table></dl>
<dl><dt><a name='htmlparse'>htmlparse<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
</table></dl>
<dl><dt><a name='http'>http<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
</table></dl>
<dl><dt><a name='httpd'>httpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
</table></dl>
<dl><dt><a name='ident'>ident<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
</table></dl>
<dl><dt><a name='imap4'>imap4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
</table></dl>
<dl><dt><a name='inifile'>inifile<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
</table></dl>
<dl><dt><a name='interp'>interp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
</table></dl>
<dl><dt><a name='irc'>irc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
</table></dl>
<dl><dt><a name='javascript'>javascript<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
</table></dl>
<dl><dt><a name='jpeg'>jpeg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='json'>json<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
</table></dl>
<dl><dt><a name='lambda'>lambda<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
</table></dl>
<dl><dt><a name='lazyset'>lazyset<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
</table></dl>
<dl><dt><a name='ldap'>ldap<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
</table></dl>
<dl><dt><a name='log'>log<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
</table></dl>
<dl><dt><a name='map'>map<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
</table></dl>
<dl><dt><a name='mapproj'>mapproj<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
</table></dl>
<dl><dt><a name='markdown'>markdown<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
</table></dl>
<dl><dt><a name='math'>math<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
<td class="#doctools_tocright">Arbitrary precision floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_bignum'><a href="tcllib/files/modules/math/bignum.html">math::bignum</a></td>
<td class="#doctools_tocright">Arbitrary precision integer numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus'><a href="tcllib/files/modules/math/calculus.html">math::calculus</a></td>
<td class="#doctools_tocright">Integration and ordinary differential equations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_calculus_romberg'><a href="tcllib/files/modules/math/romberg.html">math::calculus::romberg</a></td>
<td class="#doctools_tocright">Romberg integration</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus_symdiff'><a href="tcllib/files/modules/math/symdiff.html">math::calculus::symdiff</a></td>
<td class="#doctools_tocright">Symbolic differentiation for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_combinatorics'><a href="tcllib/files/modules/math/combinatorics.html">math::combinatorics</a></td>
<td class="#doctools_tocright">Combinatorial functions in the Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_complexnumbers'><a href="tcllib/files/modules/math/qcomplex.html">math::complexnumbers</a></td>
<td class="#doctools_tocright">Straightforward complex number package</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_constants'><a href="tcllib/files/modules/math/constants.html">math::constants</a></td>
<td class="#doctools_tocright">Mathematical and numerical constants</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_decimal'><a href="tcllib/files/modules/math/decimal.html">math::decimal</a></td>
<td class="#doctools_tocright">General decimal arithmetic</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_exact'><a href="tcllib/files/modules/math/exact.html">math::exact</a></td>
<td class="#doctools_tocright">Exact Real Arithmetic</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_fourier'><a href="tcllib/files/modules/math/fourier.html">math::fourier</a></td>
<td class="#doctools_tocright">Discrete and fast fourier transforms</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_fuzzy'><a href="tcllib/files/modules/math/fuzzy.html">math::fuzzy</a></td>
<td class="#doctools_tocright">Fuzzy comparison of floating-point numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_geometry'><a href="tcllib/files/modules/math/math_geometry.html">math::geometry</a></td>
<td class="#doctools_tocright">Geometrical computations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_interpolate'><a href="tcllib/files/modules/math/interpolate.html">math::interpolate</a></td>
<td class="#doctools_tocright">Interpolation routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_linearalgebra'><a href="tcllib/files/modules/math/linalg.html">math::linearalgebra</a></td>
<td class="#doctools_tocright">Linear Algebra</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_numtheory'><a href="tcllib/files/modules/math/numtheory.html">math::numtheory</a></td>
<td class="#doctools_tocright">Number Theory</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_optimize'><a href="tcllib/files/modules/math/optimize.html">math::optimize</a></td>
<td class="#doctools_tocright">Optimisation routines</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_pca'><a href="tcllib/files/modules/math/pca.html">math::PCA</a></td>
<td class="#doctools_tocright">Package for Principal Component Analysis</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_polynomials'><a href="tcllib/files/modules/math/polynomials.html">math::polynomials</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_rationalfunctions'><a href="tcllib/files/modules/math/rational_funcs.html">math::rationalfunctions</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_roman'><a href="tcllib/files/modules/math/roman.html">math::roman</a></td>
<td class="#doctools_tocright">Tools for creating and manipulating roman numerals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_special'><a href="tcllib/files/modules/math/special.html">math::special</a></td>
<td class="#doctools_tocright">Special mathematical functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_statistics'><a href="tcllib/files/modules/math/statistics.html">math::statistics</a></td>
<td class="#doctools_tocright">Basic statistical functions and procedures</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_trig'><a href="tcllib/files/modules/math/trig.html">math::trig</a></td>
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
</table></dl>
<dl><dt><a name='md4'>md4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5'>md5<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5crypt'>md5crypt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
</table></dl>
<dl><dt><a name='mime'>mime<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
</table></dl>
<dl><dt><a name='multiplexer'>multiplexer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
</table></dl>
<dl><dt><a name='namespacex'>namespacex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
</table></dl>
<dl><dt><a name='ncgi'>ncgi<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='nettool'>nettool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
</table></dl>
<dl><dt><a name='nmea'>nmea<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
</table></dl>
<dl><dt><a name='nns'>nns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
<td class="#doctools_tocright">Name service facility, Client Extension</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_common'><a href="tcllib/files/modules/nns/nns_common.html">nameserv::common</a></td>
<td class="#doctools_tocright">Name service facility, shared definitions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_protocol'><a href="tcllib/files/modules/nns/nns_protocol.html">nameserv::protocol</a></td>
<td class="#doctools_tocright">Name service facility, client/server protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_server'><a href="tcllib/files/modules/nns/nns_server.html">nameserv::server</a></td>
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
</table></dl>
<dl><dt><a name='nntp'>nntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
</table></dl>
<dl><dt><a name='ntp'>ntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
</table></dl>
<dl><dt><a name='oauth'>oauth<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
</table></dl>
<dl><dt><a name='oometa'>oometa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
</table></dl>
<dl><dt><a name='ooutil'>ooutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
</table></dl>
<dl><dt><a name='otp'>otp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
</table></dl>
<dl><dt><a name='page'>page<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
<td class="#doctools_tocright">page plugin manager</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_flow'><a href="tcllib/files/modules/page/page_util_flow.html">page_util_flow</a></td>
<td class="#doctools_tocright">page dataflow/treewalker utility</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_norm_lemon'><a href="tcllib/files/modules/page/page_util_norm_lemon.html">page_util_norm_lemon</a></td>
<td class="#doctools_tocright">page AST normalization, LEMON</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_norm_peg'><a href="tcllib/files/modules/page/page_util_norm_peg.html">page_util_norm_peg</a></td>
<td class="#doctools_tocright">page AST normalization, PEG</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_peg'><a href="tcllib/files/modules/page/page_util_peg.html">page_util_peg</a></td>
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='pki'>pki<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
</table></dl>
<dl><dt><a name='pluginmgr'>pluginmgr<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
</table></dl>
<dl><dt><a name='png'>png<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='pop3'>pop3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
</table></dl>
<dl><dt><a name='pop3d'>pop3d<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
</table></dl>
<dl><dt><a name='practcl'>practcl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
</table></dl>
<dl><dt><a name='processman'>processman<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='profiler'>profiler<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
</table></dl>
<dl><dt><a name='pt'>pt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, Critcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_tea'><a href="tcllib/files/modules/pt/pt_cparam_config_tea.html">pt::cparam::configuration::tea</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, TEA</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_json_language'><a href="tcllib/files/modules/pt/pt_json_language.html">pt::json_language</a></td>
<td class="#doctools_tocright">The JSON Grammar Exchange Format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_param'><a href="tcllib/files/modules/pt/pt_param.html">pt::param</a></td>
<td class="#doctools_tocright">PackRat Machine Specification</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pe'><a href="tcllib/files/modules/pt/pt_pexpression.html">pt::pe</a></td>
<td class="#doctools_tocright">Parsing Expression Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pe_op'><a href="tcllib/files/modules/pt/pt_pexpr_op.html">pt::pe::op</a></td>
<td class="#doctools_tocright">Parsing Expression Utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg'><a href="tcllib/files/modules/pt/pt_pegrammar.html">pt::peg</a></td>
<td class="#doctools_tocright">Parsing Expression Grammar Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_container'><a href="tcllib/files/modules/pt/pt_peg_container.html">pt::peg::container</a></td>
<td class="#doctools_tocright">PEG Storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_container_peg'><a href="tcllib/files/modules/pt/pt_peg_container_peg.html">pt::peg::container::peg</a></td>
<td class="#doctools_tocright">PEG Storage. Canned PEG grammar specification</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export'><a href="tcllib/files/modules/pt/pt_peg_export.html">pt::peg::export</a></td>
<td class="#doctools_tocright">PEG Export</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_container'><a href="tcllib/files/modules/pt/pt_peg_export_container.html">pt::peg::export::container</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_json'><a href="tcllib/files/modules/pt/pt_peg_export_json.html">pt::peg::export::json</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_peg'><a href="tcllib/files/modules/pt/pt_peg_export_peg.html">pt::peg::export::peg</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_container'><a href="tcllib/files/modules/pt/pt_peg_from_container.html">pt::peg::from::container</a></td>
<td class="#doctools_tocright">PEG Conversion. From CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_json'><a href="tcllib/files/modules/pt/pt_peg_from_json.html">pt::peg::from::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Read JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_peg'><a href="tcllib/files/modules/pt/pt_peg_from_peg.html">pt::peg::from::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Read PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import'><a href="tcllib/files/modules/pt/pt_peg_import.html">pt::peg::import</a></td>
<td class="#doctools_tocright">PEG Import</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_container'><a href="tcllib/files/modules/pt/pt_peg_import_container.html">pt::peg::import::container</a></td>
<td class="#doctools_tocright">PEG Import Plugin. From CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_json'><a href="tcllib/files/modules/pt/pt_peg_import_json.html">pt::peg::import::json</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_peg'><a href="tcllib/files/modules/pt/pt_peg_import_peg.html">pt::peg::import::peg</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_interp'><a href="tcllib/files/modules/pt/pt_peg_interp.html">pt::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_container'><a href="tcllib/files/modules/pt/pt_peg_to_container.html">pt::peg::to::container</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_cparam'><a href="tcllib/files/modules/pt/pt_peg_to_cparam.html">pt::peg::to::cparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CPARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_json'><a href="tcllib/files/modules/pt/pt_peg_to_json.html">pt::peg::to::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Write JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_param'><a href="tcllib/files/modules/pt/pt_peg_to_param.html">pt::peg::to::param</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_peg'><a href="tcllib/files/modules/pt/pt_peg_to_peg.html">pt::peg::to::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_tclparam'><a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write TCLPARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_language'><a href="tcllib/files/modules/pt/pt_peg_language.html">pt::peg_language</a></td>
<td class="#doctools_tocright">PEG Language Tutorial</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pegrammar'><a href="tcllib/files/modules/pt/pt_peg_introduction.html">pt::pegrammar</a></td>
<td class="#doctools_tocright">Introduction to Parsing Expression Grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pgen'><a href="tcllib/files/modules/pt/pt_pgen.html">pt::pgen</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_rde'><a href="tcllib/files/modules/pt/pt_rdengine.html">pt::rde</a></td>
<td class="#doctools_tocright">Parsing Runtime Support, PARAM based</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_nx'><a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html">pt::tclparam::configuration::nx</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, NX</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_snit'><a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Snit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_tcloo'><a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Tcloo</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_util'><a href="tcllib/files/modules/pt/pt_util.html">pt::util</a></td>
<td class="#doctools_tocright">General utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_export_api'><a href="tcllib/files/modules/pt/pt_to_api.html">pt_export_api</a></td>
<td class="#doctools_tocright">Parser Tools Export API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_import_api'><a href="tcllib/files/modules/pt/pt_from_api.html">pt_import_api</a></td>
<td class="#doctools_tocright">Parser Tools Import API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_introduction'><a href="tcllib/files/modules/pt/pt_introduction.html">pt_introduction</a></td>
<td class="#doctools_tocright">Introduction to Parser Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_parse_peg'><a href="tcllib/files/modules/pt/pt_parse_peg.html">pt_parse_peg</a></td>
<td class="#doctools_tocright">Parser Tools PEG Parser</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_parser_api'><a href="tcllib/files/modules/pt/pt_parser_api.html">pt_parser_api</a></td>
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='rc4'>rc4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
</table></dl>
<dl><dt><a name='rcs'>rcs<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
</table></dl>
<dl><dt><a name='report'>report<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
</table></dl>
<dl><dt><a name='rest'>rest<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
</table></dl>
<dl><dt><a name='ripemd'>ripemd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='sasl'>sasl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='sha1'>sha1<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='simulation'>simulation<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='smtpd'>smtpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='snit'>snit<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
</table></dl>
<dl><dt><a name='soundex'>soundex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
</table></dl>
<dl><dt><a name='stooop'>stooop<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
</table></dl>
<dl><dt><a name='string'>string<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
</table></dl>
<dl><dt><a name='stringprep'>stringprep<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
</table></dl>
<dl><dt><a name='struct'>struct<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_graph_op'><a href="tcllib/files/modules/struct/graphops.html">struct::graph::op</a></td>
<td class="#doctools_tocright">Operation for (un)directed graph objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph_v1'><a href="tcllib/files/modules/struct/graph1.html">struct::graph_v1</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_list'><a href="tcllib/files/modules/struct/struct_list.html">struct::list</a></td>
<td class="#doctools_tocright">Procedures for manipulating lists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_matrix'><a href="tcllib/files/modules/struct/matrix.html">struct::matrix</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_matrix_v1'><a href="tcllib/files/modules/struct/matrix1.html">struct::matrix_v1</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_pool'><a href="tcllib/files/modules/struct/pool.html">struct::pool</a></td>
<td class="#doctools_tocright">Create and manipulate pool objects (of discrete items)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_prioqueue'><a href="tcllib/files/modules/struct/prioqueue.html">struct::prioqueue</a></td>
<td class="#doctools_tocright">Create and manipulate prioqueue objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_queue'><a href="tcllib/files/modules/struct/queue.html">struct::queue</a></td>
<td class="#doctools_tocright">Create and manipulate queue objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_record'><a href="tcllib/files/modules/struct/record.html">struct::record</a></td>
<td class="#doctools_tocright">Define and create records (similar to 'C' structures)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_set'><a href="tcllib/files/modules/struct/struct_set.html">struct::set</a></td>
<td class="#doctools_tocright">Procedures for manipulating sets</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_skiplist'><a href="tcllib/files/modules/struct/skiplist.html">struct::skiplist</a></td>
<td class="#doctools_tocright">Create and manipulate skiplists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_stack'><a href="tcllib/files/modules/struct/stack.html">struct::stack</a></td>
<td class="#doctools_tocright">Create and manipulate stack objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_tree'><a href="tcllib/files/modules/struct/struct_tree.html">struct::tree</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='tar'>tar<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='tepam'>tepam<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='term'>term<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
<td class="#doctools_tocright">Helper for control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_attr'><a href="tcllib/files/modules/term/ansi_cattr.html">term::ansi::code::attr</a></td>
<td class="#doctools_tocright">ANSI attribute sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_ctrl'><a href="tcllib/files/modules/term/ansi_cctrl.html">term::ansi::code::ctrl</a></td>
<td class="#doctools_tocright">ANSI control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_macros'><a href="tcllib/files/modules/term/ansi_cmacros.html">term::ansi::code::macros</a></td>
<td class="#doctools_tocright">Macro sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_ctrl_unix'><a href="tcllib/files/modules/term/ansi_ctrlu.html">term::ansi::ctrl::unix</a></td>
<td class="#doctools_tocright">Control operations and queries</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_send'><a href="tcllib/files/modules/term/ansi_send.html">term::ansi::send</a></td>
<td class="#doctools_tocright">Output of ANSI control sequences to terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_interact_menu'><a href="tcllib/files/modules/term/imenu.html">term::interact::menu</a></td>
<td class="#doctools_tocright">Terminal widget, menu</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_interact_pager'><a href="tcllib/files/modules/term/ipager.html">term::interact::pager</a></td>
<td class="#doctools_tocright">Terminal widget, paging</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_receive'><a href="tcllib/files/modules/term/receive.html">term::receive</a></td>
<td class="#doctools_tocright">General input from terminals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_receive_bind'><a href="tcllib/files/modules/term/term_bind.html">term::receive::bind</a></td>
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='textutil'>textutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
<td class="#doctools_tocright">Procedures to adjust, indent, and undent paragraphs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_repeat'><a href="tcllib/files/modules/textutil/repeat.html">textutil::repeat</a></td>
<td class="#doctools_tocright">Procedures to repeat strings.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_split'><a href="tcllib/files/modules/textutil/textutil_split.html">textutil::split</a></td>
<td class="#doctools_tocright">Procedures to split texts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_string'><a href="tcllib/files/modules/textutil/textutil_string.html">textutil::string</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_tabify'><a href="tcllib/files/modules/textutil/tabify.html">textutil::tabify</a></td>
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
</table></dl>
<dl><dt><a name='tie'>tie<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
</table></dl>
<dl><dt><a name='tiff'>tiff<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='tool'>tool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='transfer'>transfer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
<td class="#doctools_tocright">Data transfer foundation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_copy_queue'><a href="tcllib/files/modules/transfer/tqueue.html">transfer::copy::queue</a></td>
<td class="#doctools_tocright">Queued transfers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_data_destination'><a href="tcllib/files/modules/transfer/ddest.html">transfer::data::destination</a></td>
<td class="#doctools_tocright">Data destination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_data_source'><a href="tcllib/files/modules/transfer/dsource.html">transfer::data::source</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_receiver'><a href="tcllib/files/modules/transfer/receiver.html">transfer::receiver</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='treeql'>treeql<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='try'>try<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='udpcluster'>udpcluster<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
</table></dl>
<dl><dt><a name='uev'>uev<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
</table></dl>
<dl><dt><a name='units'>units<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
</table></dl>
<dl><dt><a name='uri'>uri<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
</table></dl>
<dl><dt><a name='uuid'>uuid<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='valtype'>valtype<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
<td class="#doctools_tocright">Validation for AMEX creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_discover'><a href="tcllib/files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></td>
<td class="#doctools_tocright">Validation for Discover creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_mastercard'><a href="tcllib/files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></td>
<td class="#doctools_tocright">Validation for Mastercard creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_visa'><a href="tcllib/files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></td>
<td class="#doctools_tocright">Validation for VISA creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_gs1_ean13'><a href="tcllib/files/modules/valtype/ean13.html">valtype::gs1::ean13</a></td>
<td class="#doctools_tocright">Validation for EAN13</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_iban'><a href="tcllib/files/modules/valtype/iban.html">valtype::iban</a></td>
<td class="#doctools_tocright">Validation for IBAN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_imei'><a href="tcllib/files/modules/valtype/imei.html">valtype::imei</a></td>
<td class="#doctools_tocright">Validation for IMEI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_isbn'><a href="tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></td>
<td class="#doctools_tocright">Validation for ISBN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_luhn'><a href="tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN checkdigit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_luhn5'><a href="tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN5 checkdigit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_base'>virtchannel_base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
<td class="#doctools_tocright">Facade channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html">tcl::chan::fifo</a></td>
<td class="#doctools_tocright">In-memory fifo channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo2'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html">tcl::chan::fifo2</a></td>
<td class="#doctools_tocright">In-memory interconnected fifo channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_halfpipe'><a href="tcllib/files/modules/virtchannel_base/halfpipe.html">tcl::chan::halfpipe</a></td>
<td class="#doctools_tocright">In-memory channel, half of a fifo2</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_memchan'><a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html">tcl::chan::memchan</a></td>
<td class="#doctools_tocright">In-memory channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_null'><a href="tcllib/files/modules/virtchannel_base/tcllib_null.html">tcl::chan::null</a></td>
<td class="#doctools_tocright">Null channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_nullzero'><a href="tcllib/files/modules/virtchannel_base/nullzero.html">tcl::chan::nullzero</a></td>
<td class="#doctools_tocright">Null/Zero channel combination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_random'><a href="tcllib/files/modules/virtchannel_base/tcllib_random.html">tcl::chan::random</a></td>
<td class="#doctools_tocright">Random channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_std'><a href="tcllib/files/modules/virtchannel_base/std.html">tcl::chan::std</a></td>
<td class="#doctools_tocright">Standard I/O, unification of stdin and stdout</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_string'><a href="tcllib/files/modules/virtchannel_base/tcllib_string.html">tcl::chan::string</a></td>
<td class="#doctools_tocright">Read-only in-memory channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_textwindow'><a href="tcllib/files/modules/virtchannel_base/textwindow.html">tcl::chan::textwindow</a></td>
<td class="#doctools_tocright">Textwindow channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_variable'><a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html">tcl::chan::variable</a></td>
<td class="#doctools_tocright">In-memory channel using variable for storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_zero'><a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html">tcl::chan::zero</a></td>
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_core'>virtchannel_core<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_transform'>virtchannel_transform<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
<td class="#doctools_tocright">Base64 encoding transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_counter'><a href="tcllib/files/modules/virtchannel_transform/vt_counter.html">tcl::transform::counter</a></td>
<td class="#doctools_tocright">Counter transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_crc32'><a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html">tcl::transform::crc32</a></td>
<td class="#doctools_tocright">Crc32 transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_hex'><a href="tcllib/files/modules/virtchannel_transform/hex.html">tcl::transform::hex</a></td>
<td class="#doctools_tocright">Hexadecimal encoding transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_identity'><a href="tcllib/files/modules/virtchannel_transform/identity.html">tcl::transform::identity</a></td>
<td class="#doctools_tocright">Identity transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_limitsize'><a href="tcllib/files/modules/virtchannel_transform/limitsize.html">tcl::transform::limitsize</a></td>
<td class="#doctools_tocright">limiting input</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_observe'><a href="tcllib/files/modules/virtchannel_transform/observe.html">tcl::transform::observe</a></td>
<td class="#doctools_tocright">Observer transformation, stream copy</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_otp'><a href="tcllib/files/modules/virtchannel_transform/vt_otp.html">tcl::transform::otp</a></td>
<td class="#doctools_tocright">Encryption via one-time pad</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_rot'><a href="tcllib/files/modules/virtchannel_transform/rot.html">tcl::transform::rot</a></td>
<td class="#doctools_tocright">rot-encryption</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_spacer'><a href="tcllib/files/modules/virtchannel_transform/spacer.html">tcl::transform::spacer</a></td>
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='websocket'>websocket<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='wip'>wip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='yaml'>yaml<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='zip'>zip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl></table></dl></table></dl>
</dl><hr>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/toc0.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
|
<div class='fossil-doc' data-title='Table Of Contents'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='by_categories'>By Categories<dd>
<dl><dt><a name='argument_entry_form_mega_widget'>Argument entry form, mega widget<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='benchmark_tools'>Benchmark tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
<td class="#doctools_tocright">bench::in - Reading benchmark results</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_out_csv'><a href="tcllib/files/modules/bench/bench_wcsv.html">bench::out::csv</a></td>
<td class="#doctools_tocright">bench::out::csv - Formatting benchmark results as CSV</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_out_text'><a href="tcllib/files/modules/bench/bench_wtext.html">bench::out::text</a></td>
<td class="#doctools_tocright">bench::out::text - Formatting benchmark results as human readable text</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_intro'><a href="tcllib/files/modules/bench/bench_intro.html">bench_intro</a></td>
<td class="#doctools_tocright">bench introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_lang_intro'><a href="tcllib/files/modules/bench/bench_lang_intro.html">bench_lang_intro</a></td>
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='cgi_programming'>CGI programming<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='channels'>Channels<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
<td class="#doctools_tocright">Facade channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html">tcl::chan::fifo</a></td>
<td class="#doctools_tocright">In-memory fifo channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo2'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html">tcl::chan::fifo2</a></td>
<td class="#doctools_tocright">In-memory interconnected fifo channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_halfpipe'><a href="tcllib/files/modules/virtchannel_base/halfpipe.html">tcl::chan::halfpipe</a></td>
<td class="#doctools_tocright">In-memory channel, half of a fifo2</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_memchan'><a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html">tcl::chan::memchan</a></td>
<td class="#doctools_tocright">In-memory channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_null'><a href="tcllib/files/modules/virtchannel_base/tcllib_null.html">tcl::chan::null</a></td>
<td class="#doctools_tocright">Null channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_nullzero'><a href="tcllib/files/modules/virtchannel_base/nullzero.html">tcl::chan::nullzero</a></td>
<td class="#doctools_tocright">Null/Zero channel combination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_random'><a href="tcllib/files/modules/virtchannel_base/tcllib_random.html">tcl::chan::random</a></td>
<td class="#doctools_tocright">Random channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_std'><a href="tcllib/files/modules/virtchannel_base/std.html">tcl::chan::std</a></td>
<td class="#doctools_tocright">Standard I/O, unification of stdin and stdout</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_string'><a href="tcllib/files/modules/virtchannel_base/tcllib_string.html">tcl::chan::string</a></td>
<td class="#doctools_tocright">Read-only in-memory channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_textwindow'><a href="tcllib/files/modules/virtchannel_base/textwindow.html">tcl::chan::textwindow</a></td>
<td class="#doctools_tocright">Textwindow channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_variable'><a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html">tcl::chan::variable</a></td>
<td class="#doctools_tocright">In-memory channel using variable for storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_zero'><a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html">tcl::chan::zero</a></td>
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
<td class="#doctools_tocright">Base64 encoding transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_counter'><a href="tcllib/files/modules/virtchannel_transform/vt_counter.html">tcl::transform::counter</a></td>
<td class="#doctools_tocright">Counter transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_crc32'><a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html">tcl::transform::crc32</a></td>
<td class="#doctools_tocright">Crc32 transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_hex'><a href="tcllib/files/modules/virtchannel_transform/hex.html">tcl::transform::hex</a></td>
<td class="#doctools_tocright">Hexadecimal encoding transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_identity'><a href="tcllib/files/modules/virtchannel_transform/identity.html">tcl::transform::identity</a></td>
<td class="#doctools_tocright">Identity transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_limitsize'><a href="tcllib/files/modules/virtchannel_transform/limitsize.html">tcl::transform::limitsize</a></td>
<td class="#doctools_tocright">limiting input</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_observe'><a href="tcllib/files/modules/virtchannel_transform/observe.html">tcl::transform::observe</a></td>
<td class="#doctools_tocright">Observer transformation, stream copy</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_otp'><a href="tcllib/files/modules/virtchannel_transform/vt_otp.html">tcl::transform::otp</a></td>
<td class="#doctools_tocright">Encryption via one-time pad</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_rot'><a href="tcllib/files/modules/virtchannel_transform/rot.html">tcl::transform::rot</a></td>
<td class="#doctools_tocright">rot-encryption</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_spacer'><a href="tcllib/files/modules/virtchannel_transform/spacer.html">tcl::transform::spacer</a></td>
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>Coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='data_structures'>Data structures<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_graph_op'><a href="tcllib/files/modules/struct/graphops.html">struct::graph::op</a></td>
<td class="#doctools_tocright">Operation for (un)directed graph objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph_v1'><a href="tcllib/files/modules/struct/graph1.html">struct::graph_v1</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_list'><a href="tcllib/files/modules/struct/struct_list.html">struct::list</a></td>
<td class="#doctools_tocright">Procedures for manipulating lists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_matrix'><a href="tcllib/files/modules/struct/matrix.html">struct::matrix</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_matrix_v1'><a href="tcllib/files/modules/struct/matrix1.html">struct::matrix_v1</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_pool'><a href="tcllib/files/modules/struct/pool.html">struct::pool</a></td>
<td class="#doctools_tocright">Create and manipulate pool objects (of discrete items)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_prioqueue'><a href="tcllib/files/modules/struct/prioqueue.html">struct::prioqueue</a></td>
<td class="#doctools_tocright">Create and manipulate prioqueue objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_queue'><a href="tcllib/files/modules/struct/queue.html">struct::queue</a></td>
<td class="#doctools_tocright">Create and manipulate queue objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_record'><a href="tcllib/files/modules/struct/record.html">struct::record</a></td>
<td class="#doctools_tocright">Define and create records (similar to 'C' structures)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_set'><a href="tcllib/files/modules/struct/struct_set.html">struct::set</a></td>
<td class="#doctools_tocright">Procedures for manipulating sets</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_skiplist'><a href="tcllib/files/modules/struct/skiplist.html">struct::skiplist</a></td>
<td class="#doctools_tocright">Create and manipulate skiplists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_stack'><a href="tcllib/files/modules/struct/stack.html">struct::stack</a></td>
<td class="#doctools_tocright">Create and manipulate stack objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_tree'><a href="tcllib/files/modules/struct/struct_tree.html">struct::tree</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='debugging_tracing_and_logging'>debugging, tracing, and logging<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='documentation_tools'>Documentation tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
<td class="#doctools_tocright">docidx language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_faq'><a href="tcllib/files/modules/doctools/docidx_lang_faq.html">docidx_lang_faq</a></td>
<td class="#doctools_tocright">docidx language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_intro'><a href="tcllib/files/modules/doctools/docidx_lang_intro.html">docidx_lang_intro</a></td>
<td class="#doctools_tocright">docidx language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_syntax'><a href="tcllib/files/modules/doctools/docidx_lang_syntax.html">docidx_lang_syntax</a></td>
<td class="#doctools_tocright">docidx language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_plugin_apiref'><a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html">docidx_plugin_apiref</a></td>
<td class="#doctools_tocright">docidx plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_intro'><a href="tcllib/files/modules/doctools/doctoc_intro.html">doctoc_intro</a></td>
<td class="#doctools_tocright">doctoc introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_cmdref'><a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html">doctoc_lang_cmdref</a></td>
<td class="#doctools_tocright">doctoc language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_faq'><a href="tcllib/files/modules/doctools/doctoc_lang_faq.html">doctoc_lang_faq</a></td>
<td class="#doctools_tocright">doctoc language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_intro'><a href="tcllib/files/modules/doctools/doctoc_lang_intro.html">doctoc_lang_intro</a></td>
<td class="#doctools_tocright">doctoc language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_syntax'><a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html">doctoc_lang_syntax</a></td>
<td class="#doctools_tocright">doctoc language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_plugin_apiref'><a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html">doctoc_plugin_apiref</a></td>
<td class="#doctools_tocright">doctoc plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools'><a href="tcllib/files/modules/doctools/doctools.html">doctools</a></td>
<td class="#doctools_tocright">doctools - Processing documents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_changelog'><a href="tcllib/files/modules/doctools/changelog.html">doctools::changelog</a></td>
<td class="#doctools_tocright">Processing text in Emacs ChangeLog format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_cvs'><a href="tcllib/files/modules/doctools/cvs.html">doctools::cvs</a></td>
<td class="#doctools_tocright">Processing text in 'cvs log' format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
<td class="#doctools_tocright">Holding keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools/docidx.html">doctools::idx</a></td>
<td class="#doctools_tocright">docidx - Processing indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export'><a href="tcllib/files/modules/doctools2idx/idx_export.html">doctools::idx::export</a></td>
<td class="#doctools_tocright">Exporting keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import'><a href="tcllib/files/modules/doctools2idx/idx_import.html">doctools::idx::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_parse'><a href="tcllib/files/modules/doctools2idx/idx_parse.html">doctools::idx::parse</a></td>
<td class="#doctools_tocright">Parsing text in docidx format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_structure'><a href="tcllib/files/modules/doctools2idx/idx_structure.html">doctools::idx::structure</a></td>
<td class="#doctools_tocright">Docidx serialization utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_c'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html">doctools::msgcat::idx::c</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (C)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_de'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html">doctools::msgcat::idx::de</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (DE)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_en'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html">doctools::msgcat::idx::en</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (C)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_de'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html">doctools::msgcat::toc::de</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (DE)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_en'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html">doctools::msgcat::toc::en</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (EN)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_fr'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html">doctools::msgcat::toc::fr</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (FR)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools2toc/toc_container.html">doctools::toc</a></td>
<td class="#doctools_tocright">Holding tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools/doctoc.html">doctools::toc</a></td>
<td class="#doctools_tocright">doctoc - Processing tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export'><a href="tcllib/files/modules/doctools2toc/toc_export.html">doctools::toc::export</a></td>
<td class="#doctools_tocright">Exporting tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import'><a href="tcllib/files/modules/doctools2toc/toc_import.html">doctools::toc::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_parse'><a href="tcllib/files/modules/doctools2toc/toc_parse.html">doctools::toc::parse</a></td>
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_intro'><a href="tcllib/files/modules/doctools/doctools_intro.html">doctools_intro</a></td>
<td class="#doctools_tocright">doctools introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_cmdref'><a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a></td>
<td class="#doctools_tocright">doctools language command reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_faq'><a href="tcllib/files/modules/doctools/doctools_lang_faq.html">doctools_lang_faq</a></td>
<td class="#doctools_tocright">doctools language faq</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_intro'><a href="tcllib/files/modules/doctools/doctools_lang_intro.html">doctools_lang_intro</a></td>
<td class="#doctools_tocright">doctools language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_syntax'><a href="tcllib/files/modules/doctools/doctools_lang_syntax.html">doctools_lang_syntax</a></td>
<td class="#doctools_tocright">doctools language syntax</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_plugin_apiref'><a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></td>
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
</table></dl>
<dl><dt><a name='file'>File<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
<dl><dt><a name='file_formats'>File formats<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='grammars_and_finite_automata'>Grammars and finite automata<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
<td class="#doctools_tocright">ME virtual machine state manipulation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_gasm'><a href="tcllib/files/modules/grammar_me/gasm.html">grammar::me::cpu::gasm</a></td>
<td class="#doctools_tocright">ME assembler</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_tcl'><a href="tcllib/files/modules/grammar_me/me_tcl.html">grammar::me::tcl</a></td>
<td class="#doctools_tocright">Virtual machine implementation I for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_util'><a href="tcllib/files/modules/grammar_me/me_util.html">grammar::me::util</a></td>
<td class="#doctools_tocright">AST utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_ast'><a href="tcllib/files/modules/grammar_me/me_ast.html">grammar::me_ast</a></td>
<td class="#doctools_tocright">Various representations of ASTs</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_intro'><a href="tcllib/files/modules/grammar_me/me_intro.html">grammar::me_intro</a></td>
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hashes_checksums_and_encryption'>Hashes, checksums, and encryption<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='mathematics'>Mathematics<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
<td class="#doctools_tocright">Arbitrary precision floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_bignum'><a href="tcllib/files/modules/math/bignum.html">math::bignum</a></td>
<td class="#doctools_tocright">Arbitrary precision integer numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus'><a href="tcllib/files/modules/math/calculus.html">math::calculus</a></td>
<td class="#doctools_tocright">Integration and ordinary differential equations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_calculus_romberg'><a href="tcllib/files/modules/math/romberg.html">math::calculus::romberg</a></td>
<td class="#doctools_tocright">Romberg integration</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_combinatorics'><a href="tcllib/files/modules/math/combinatorics.html">math::combinatorics</a></td>
<td class="#doctools_tocright">Combinatorial functions in the Tcl Math Library</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_complexnumbers'><a href="tcllib/files/modules/math/qcomplex.html">math::complexnumbers</a></td>
<td class="#doctools_tocright">Straightforward complex number package</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_constants'><a href="tcllib/files/modules/math/constants.html">math::constants</a></td>
<td class="#doctools_tocright">Mathematical and numerical constants</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_decimal'><a href="tcllib/files/modules/math/decimal.html">math::decimal</a></td>
<td class="#doctools_tocright">General decimal arithmetic</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_exact'><a href="tcllib/files/modules/math/exact.html">math::exact</a></td>
<td class="#doctools_tocright">Exact Real Arithmetic</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_fourier'><a href="tcllib/files/modules/math/fourier.html">math::fourier</a></td>
<td class="#doctools_tocright">Discrete and fast fourier transforms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_fuzzy'><a href="tcllib/files/modules/math/fuzzy.html">math::fuzzy</a></td>
<td class="#doctools_tocright">Fuzzy comparison of floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_geometry'><a href="tcllib/files/modules/math/math_geometry.html">math::geometry</a></td>
<td class="#doctools_tocright">Geometrical computations</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_interpolate'><a href="tcllib/files/modules/math/interpolate.html">math::interpolate</a></td>
<td class="#doctools_tocright">Interpolation routines</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_linearalgebra'><a href="tcllib/files/modules/math/linalg.html">math::linearalgebra</a></td>
<td class="#doctools_tocright">Linear Algebra</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_numtheory'><a href="tcllib/files/modules/math/numtheory.html">math::numtheory</a></td>
<td class="#doctools_tocright">Number Theory</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_optimize'><a href="tcllib/files/modules/math/optimize.html">math::optimize</a></td>
<td class="#doctools_tocright">Optimisation routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_pca'><a href="tcllib/files/modules/math/pca.html">math::PCA</a></td>
<td class="#doctools_tocright">Package for Principal Component Analysis</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_polynomials'><a href="tcllib/files/modules/math/polynomials.html">math::polynomials</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_rationalfunctions'><a href="tcllib/files/modules/math/rational_funcs.html">math::rationalfunctions</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_roman'><a href="tcllib/files/modules/math/roman.html">math::roman</a></td>
<td class="#doctools_tocright">Tools for creating and manipulating roman numerals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_special'><a href="tcllib/files/modules/math/special.html">math::special</a></td>
<td class="#doctools_tocright">Special mathematical functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_statistics'><a href="tcllib/files/modules/math/statistics.html">math::statistics</a></td>
<td class="#doctools_tocright">Basic statistical functions and procedures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_trig'><a href="tcllib/files/modules/math/trig.html">math::trig</a></td>
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='networking'>Networking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
<td class="#doctools_tocright">Name service facility, Client Extension</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_common'><a href="tcllib/files/modules/nns/nns_common.html">nameserv::common</a></td>
<td class="#doctools_tocright">Name service facility, shared definitions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_protocol'><a href="tcllib/files/modules/nns/nns_protocol.html">nameserv::protocol</a></td>
<td class="#doctools_tocright">Name service facility, client/server protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_server'><a href="tcllib/files/modules/nns/nns_server.html">nameserv::server</a></td>
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nnsd'><a href="tcllib/files/apps/nnsd.html">nnsd</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Server Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nnslog'><a href="tcllib/files/apps/nnslog.html">nnslog</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Logging Client Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='page_parser_generator'>Page Parser Generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
<td class="#doctools_tocright">page plugin manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_flow'><a href="tcllib/files/modules/page/page_util_flow.html">page_util_flow</a></td>
<td class="#doctools_tocright">page dataflow/treewalker utility</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_norm_lemon'><a href="tcllib/files/modules/page/page_util_norm_lemon.html">page_util_norm_lemon</a></td>
<td class="#doctools_tocright">page AST normalization, LEMON</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_norm_peg'><a href="tcllib/files/modules/page/page_util_norm_peg.html">page_util_norm_peg</a></td>
<td class="#doctools_tocright">page AST normalization, PEG</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_peg'><a href="tcllib/files/modules/page/page_util_peg.html">page_util_peg</a></td>
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='parsing_and_grammars'>Parsing and Grammars<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, Critcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_tea'><a href="tcllib/files/modules/pt/pt_cparam_config_tea.html">pt::cparam::configuration::tea</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, TEA</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_json_language'><a href="tcllib/files/modules/pt/pt_json_language.html">pt::json_language</a></td>
<td class="#doctools_tocright">The JSON Grammar Exchange Format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_param'><a href="tcllib/files/modules/pt/pt_param.html">pt::param</a></td>
<td class="#doctools_tocright">PackRat Machine Specification</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pe'><a href="tcllib/files/modules/pt/pt_pexpression.html">pt::pe</a></td>
<td class="#doctools_tocright">Parsing Expression Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pe_op'><a href="tcllib/files/modules/pt/pt_pexpr_op.html">pt::pe::op</a></td>
<td class="#doctools_tocright">Parsing Expression Utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg'><a href="tcllib/files/modules/pt/pt_pegrammar.html">pt::peg</a></td>
<td class="#doctools_tocright">Parsing Expression Grammar Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_container'><a href="tcllib/files/modules/pt/pt_peg_container.html">pt::peg::container</a></td>
<td class="#doctools_tocright">PEG Storage</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_container_peg'><a href="tcllib/files/modules/pt/pt_peg_container_peg.html">pt::peg::container::peg</a></td>
<td class="#doctools_tocright">PEG Storage. Canned PEG grammar specification</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export'><a href="tcllib/files/modules/pt/pt_peg_export.html">pt::peg::export</a></td>
<td class="#doctools_tocright">PEG Export</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_container'><a href="tcllib/files/modules/pt/pt_peg_export_container.html">pt::peg::export::container</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_json'><a href="tcllib/files/modules/pt/pt_peg_export_json.html">pt::peg::export::json</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_peg'><a href="tcllib/files/modules/pt/pt_peg_export_peg.html">pt::peg::export::peg</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_container'><a href="tcllib/files/modules/pt/pt_peg_from_container.html">pt::peg::from::container</a></td>
<td class="#doctools_tocright">PEG Conversion. From CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_json'><a href="tcllib/files/modules/pt/pt_peg_from_json.html">pt::peg::from::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Read JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_peg'><a href="tcllib/files/modules/pt/pt_peg_from_peg.html">pt::peg::from::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Read PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import'><a href="tcllib/files/modules/pt/pt_peg_import.html">pt::peg::import</a></td>
<td class="#doctools_tocright">PEG Import</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_container'><a href="tcllib/files/modules/pt/pt_peg_import_container.html">pt::peg::import::container</a></td>
<td class="#doctools_tocright">PEG Import Plugin. From CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_json'><a href="tcllib/files/modules/pt/pt_peg_import_json.html">pt::peg::import::json</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_peg'><a href="tcllib/files/modules/pt/pt_peg_import_peg.html">pt::peg::import::peg</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_interp'><a href="tcllib/files/modules/pt/pt_peg_interp.html">pt::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_container'><a href="tcllib/files/modules/pt/pt_peg_to_container.html">pt::peg::to::container</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_cparam'><a href="tcllib/files/modules/pt/pt_peg_to_cparam.html">pt::peg::to::cparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CPARAM format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_json'><a href="tcllib/files/modules/pt/pt_peg_to_json.html">pt::peg::to::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Write JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_param'><a href="tcllib/files/modules/pt/pt_peg_to_param.html">pt::peg::to::param</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PARAM format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_peg'><a href="tcllib/files/modules/pt/pt_peg_to_peg.html">pt::peg::to::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_tclparam'><a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write TCLPARAM format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_language'><a href="tcllib/files/modules/pt/pt_peg_language.html">pt::peg_language</a></td>
<td class="#doctools_tocright">PEG Language Tutorial</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pegrammar'><a href="tcllib/files/modules/pt/pt_peg_introduction.html">pt::pegrammar</a></td>
<td class="#doctools_tocright">Introduction to Parsing Expression Grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pgen'><a href="tcllib/files/modules/pt/pt_pgen.html">pt::pgen</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_rde'><a href="tcllib/files/modules/pt/pt_rdengine.html">pt::rde</a></td>
<td class="#doctools_tocright">Parsing Runtime Support, PARAM based</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_nx'><a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html">pt::tclparam::configuration::nx</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, NX</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_snit'><a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Snit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_tcloo'><a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Tcloo</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_util'><a href="tcllib/files/modules/pt/pt_util.html">pt::util</a></td>
<td class="#doctools_tocright">General utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_export_api'><a href="tcllib/files/modules/pt/pt_to_api.html">pt_export_api</a></td>
<td class="#doctools_tocright">Parser Tools Export API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_import_api'><a href="tcllib/files/modules/pt/pt_from_api.html">pt_import_api</a></td>
<td class="#doctools_tocright">Parser Tools Import API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_introduction'><a href="tcllib/files/modules/pt/pt_introduction.html">pt_introduction</a></td>
<td class="#doctools_tocright">Introduction to Parser Tools</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_parse_peg'><a href="tcllib/files/modules/pt/pt_parse_peg.html">pt_parse_peg</a></td>
<td class="#doctools_tocright">Parser Tools PEG Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_parser_api'><a href="tcllib/files/modules/pt/pt_parser_api.html">pt_parser_api</a></td>
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='procedures_arguments_parameters_options'>Procedures, arguments, parameters, options<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='programming_tools'>Programming tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='system'>System<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='tcloo'>TclOO<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
</table></dl>
<dl><dt><a name='terminal_control'>Terminal control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
<td class="#doctools_tocright">Helper for control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_attr'><a href="tcllib/files/modules/term/ansi_cattr.html">term::ansi::code::attr</a></td>
<td class="#doctools_tocright">ANSI attribute sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_ctrl'><a href="tcllib/files/modules/term/ansi_cctrl.html">term::ansi::code::ctrl</a></td>
<td class="#doctools_tocright">ANSI control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_macros'><a href="tcllib/files/modules/term/ansi_cmacros.html">term::ansi::code::macros</a></td>
<td class="#doctools_tocright">Macro sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_ctrl_unix'><a href="tcllib/files/modules/term/ansi_ctrlu.html">term::ansi::ctrl::unix</a></td>
<td class="#doctools_tocright">Control operations and queries</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_send'><a href="tcllib/files/modules/term/ansi_send.html">term::ansi::send</a></td>
<td class="#doctools_tocright">Output of ANSI control sequences to terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_interact_menu'><a href="tcllib/files/modules/term/imenu.html">term::interact::menu</a></td>
<td class="#doctools_tocright">Terminal widget, menu</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_interact_pager'><a href="tcllib/files/modules/term/ipager.html">term::interact::pager</a></td>
<td class="#doctools_tocright">Terminal widget, paging</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_receive'><a href="tcllib/files/modules/term/receive.html">term::receive</a></td>
<td class="#doctools_tocright">General input from terminals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_receive_bind'><a href="tcllib/files/modules/term/term_bind.html">term::receive::bind</a></td>
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='text_formatter_plugin'>Text formatter plugin<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_json'><a href="tcllib/files/modules/doctools2idx/idx_export_json.html">doctools::idx::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_nroff'><a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html">doctools::idx::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_text'><a href="tcllib/files/modules/doctools2idx/idx_export_text.html">doctools::idx::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_wiki'><a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html">doctools::idx::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_docidx'><a href="tcllib/files/modules/doctools2idx/import_docidx.html">doctools::idx::import::docidx</a></td>
<td class="#doctools_tocright">docidx import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_json'><a href="tcllib/files/modules/doctools2idx/idx_import_json.html">doctools::idx::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_doctoc'><a href="tcllib/files/modules/doctools2toc/export_doctoc.html">doctools::toc::export::doctoc</a></td>
<td class="#doctools_tocright">doctoc export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_html'><a href="tcllib/files/modules/doctools2toc/toc_export_html.html">doctools::toc::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_json'><a href="tcllib/files/modules/doctools2toc/toc_export_json.html">doctools::toc::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_nroff'><a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html">doctools::toc::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_text'><a href="tcllib/files/modules/doctools2toc/toc_export_text.html">doctools::toc::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_wiki'><a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html">doctools::toc::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_doctoc'><a href="tcllib/files/modules/doctools2toc/import_doctoc.html">doctools::toc::import::doctoc</a></td>
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
</table></dl>
<dl><dt><a name='text_processing'>Text processing<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
<td class="#doctools_tocright">Procedures to adjust, indent, and undent paragraphs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_repeat'><a href="tcllib/files/modules/textutil/repeat.html">textutil::repeat</a></td>
<td class="#doctools_tocright">Procedures to repeat strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_split'><a href="tcllib/files/modules/textutil/textutil_split.html">textutil::split</a></td>
<td class="#doctools_tocright">Procedures to split texts</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_string'><a href="tcllib/files/modules/textutil/textutil_string.html">textutil::string</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_tabify'><a href="tcllib/files/modules/textutil/tabify.html">textutil::tabify</a></td>
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='transfer_module'>Transfer module<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
<td class="#doctools_tocright">Data transfer foundation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_copy_queue'><a href="tcllib/files/modules/transfer/tqueue.html">transfer::copy::queue</a></td>
<td class="#doctools_tocright">Queued transfers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_data_destination'><a href="tcllib/files/modules/transfer/ddest.html">transfer::data::destination</a></td>
<td class="#doctools_tocright">Data destination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_data_source'><a href="tcllib/files/modules/transfer/dsource.html">transfer::data::source</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_receiver'><a href="tcllib/files/modules/transfer/receiver.html">transfer::receiver</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='unfiled'>Unfiled<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus_symdiff'><a href="tcllib/files/modules/math/symdiff.html">math::calculus::symdiff</a></td>
<td class="#doctools_tocright">Symbolic differentiation for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='utilities'>Utilities<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='utility'>Utility<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='validation_type_checking'>Validation, Type checking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
<td class="#doctools_tocright">Validation for AMEX creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_discover'><a href="tcllib/files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></td>
<td class="#doctools_tocright">Validation for Discover creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_mastercard'><a href="tcllib/files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></td>
<td class="#doctools_tocright">Validation for Mastercard creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_visa'><a href="tcllib/files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></td>
<td class="#doctools_tocright">Validation for VISA creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_gs1_ean13'><a href="tcllib/files/modules/valtype/ean13.html">valtype::gs1::ean13</a></td>
<td class="#doctools_tocright">Validation for EAN13</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_iban'><a href="tcllib/files/modules/valtype/iban.html">valtype::iban</a></td>
<td class="#doctools_tocright">Validation for IBAN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_imei'><a href="tcllib/files/modules/valtype/imei.html">valtype::imei</a></td>
<td class="#doctools_tocright">Validation for IMEI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_isbn'><a href="tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></td>
<td class="#doctools_tocright">Validation for ISBN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_luhn'><a href="tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN checkdigit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_luhn5'><a href="tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN5 checkdigit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl></table></dl>
</dl><hr>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/toc1.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
|
<div class='fossil-doc' data-title='Table Of Contents'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='modules'>Modules<dd>
<dl><dt><a name='aes'>aes<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='amazon_s3'>amazon-s3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
</table></dl>
<dl><dt><a name='asn'>asn<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
</table></dl>
<dl><dt><a name='base32'>base32<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
</table></dl>
<dl><dt><a name='base64'>base64<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='bee'>bee<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='bench'>bench<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
<td class="#doctools_tocright">bench::in - Reading benchmark results</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_out_csv'><a href="tcllib/files/modules/bench/bench_wcsv.html">bench::out::csv</a></td>
<td class="#doctools_tocright">bench::out::csv - Formatting benchmark results as CSV</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_out_text'><a href="tcllib/files/modules/bench/bench_wtext.html">bench::out::text</a></td>
<td class="#doctools_tocright">bench::out::text - Formatting benchmark results as human readable text</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_intro'><a href="tcllib/files/modules/bench/bench_intro.html">bench_intro</a></td>
<td class="#doctools_tocright">bench introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_lang_intro'><a href="tcllib/files/modules/bench/bench_lang_intro.html">bench_lang_intro</a></td>
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='bibtex'>bibtex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
</table></dl>
<dl><dt><a name='blowfish'>blowfish<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='cache'>cache<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
</table></dl>
<dl><dt><a name='clock'>clock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
</table></dl>
<dl><dt><a name='cmdline'>cmdline<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
</table></dl>
<dl><dt><a name='comm'>comm<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
</table></dl>
<dl><dt><a name='control'>control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='counter'>counter<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
</table></dl>
<dl><dt><a name='crc'>crc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
</table></dl>
<dl><dt><a name='cron'>cron<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='csv'>csv<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
</table></dl>
<dl><dt><a name='debug'>debug<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='defer'>defer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
</table></dl>
<dl><dt><a name='des'>des<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
</table></dl>
<dl><dt><a name='dicttool'>dicttool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='dns'>dns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='docstrip'>docstrip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
</table></dl>
<dl><dt><a name='doctools'>doctools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
<td class="#doctools_tocright">docidx language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_faq'><a href="tcllib/files/modules/doctools/docidx_lang_faq.html">docidx_lang_faq</a></td>
<td class="#doctools_tocright">docidx language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_intro'><a href="tcllib/files/modules/doctools/docidx_lang_intro.html">docidx_lang_intro</a></td>
<td class="#doctools_tocright">docidx language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_lang_syntax'><a href="tcllib/files/modules/doctools/docidx_lang_syntax.html">docidx_lang_syntax</a></td>
<td class="#doctools_tocright">docidx language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_plugin_apiref'><a href="tcllib/files/modules/doctools/docidx_plugin_apiref.html">docidx_plugin_apiref</a></td>
<td class="#doctools_tocright">docidx plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_intro'><a href="tcllib/files/modules/doctools/doctoc_intro.html">doctoc_intro</a></td>
<td class="#doctools_tocright">doctoc introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_cmdref'><a href="tcllib/files/modules/doctools/doctoc_lang_cmdref.html">doctoc_lang_cmdref</a></td>
<td class="#doctools_tocright">doctoc language command reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_faq'><a href="tcllib/files/modules/doctools/doctoc_lang_faq.html">doctoc_lang_faq</a></td>
<td class="#doctools_tocright">doctoc language faq</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_intro'><a href="tcllib/files/modules/doctools/doctoc_lang_intro.html">doctoc_lang_intro</a></td>
<td class="#doctools_tocright">doctoc language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctoc_lang_syntax'><a href="tcllib/files/modules/doctools/doctoc_lang_syntax.html">doctoc_lang_syntax</a></td>
<td class="#doctools_tocright">doctoc language syntax</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctoc_plugin_apiref'><a href="tcllib/files/modules/doctools/doctoc_plugin_apiref.html">doctoc_plugin_apiref</a></td>
<td class="#doctools_tocright">doctoc plugin API reference</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools'><a href="tcllib/files/modules/doctools/doctools.html">doctools</a></td>
<td class="#doctools_tocright">doctools - Processing documents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_changelog'><a href="tcllib/files/modules/doctools/changelog.html">doctools::changelog</a></td>
<td class="#doctools_tocright">Processing text in Emacs ChangeLog format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_cvs'><a href="tcllib/files/modules/doctools/cvs.html">doctools::cvs</a></td>
<td class="#doctools_tocright">Processing text in 'cvs log' format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools/docidx.html">doctools::idx</a></td>
<td class="#doctools_tocright">docidx - Processing indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools/doctoc.html">doctools::toc</a></td>
<td class="#doctools_tocright">doctoc - Processing tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_intro'><a href="tcllib/files/modules/doctools/doctools_intro.html">doctools_intro</a></td>
<td class="#doctools_tocright">doctools introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_cmdref'><a href="tcllib/files/modules/doctools/doctools_lang_cmdref.html">doctools_lang_cmdref</a></td>
<td class="#doctools_tocright">doctools language command reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_faq'><a href="tcllib/files/modules/doctools/doctools_lang_faq.html">doctools_lang_faq</a></td>
<td class="#doctools_tocright">doctools language faq</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_lang_intro'><a href="tcllib/files/modules/doctools/doctools_lang_intro.html">doctools_lang_intro</a></td>
<td class="#doctools_tocright">doctools language introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_lang_syntax'><a href="tcllib/files/modules/doctools/doctools_lang_syntax.html">doctools_lang_syntax</a></td>
<td class="#doctools_tocright">doctools language syntax</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_plugin_apiref'><a href="tcllib/files/modules/doctools/doctools_plugin_apiref.html">doctools_plugin_apiref</a></td>
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2base'>doctools2base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2idx'>doctools2idx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
<td class="#doctools_tocright">Holding keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export'><a href="tcllib/files/modules/doctools2idx/idx_export.html">doctools::idx::export</a></td>
<td class="#doctools_tocright">Exporting keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_json'><a href="tcllib/files/modules/doctools2idx/idx_export_json.html">doctools::idx::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_nroff'><a href="tcllib/files/modules/doctools2idx/idx_export_nroff.html">doctools::idx::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_text'><a href="tcllib/files/modules/doctools2idx/idx_export_text.html">doctools::idx::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_wiki'><a href="tcllib/files/modules/doctools2idx/idx_export_wiki.html">doctools::idx::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import'><a href="tcllib/files/modules/doctools2idx/idx_import.html">doctools::idx::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_docidx'><a href="tcllib/files/modules/doctools2idx/import_docidx.html">doctools::idx::import::docidx</a></td>
<td class="#doctools_tocright">docidx import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_import_json'><a href="tcllib/files/modules/doctools2idx/idx_import_json.html">doctools::idx::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_parse'><a href="tcllib/files/modules/doctools2idx/idx_parse.html">doctools::idx::parse</a></td>
<td class="#doctools_tocright">Parsing text in docidx format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_structure'><a href="tcllib/files/modules/doctools2idx/idx_structure.html">doctools::idx::structure</a></td>
<td class="#doctools_tocright">Docidx serialization utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_c'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_c.html">doctools::msgcat::idx::c</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (C)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_de'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_de.html">doctools::msgcat::idx::de</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (DE)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_en'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_en.html">doctools::msgcat::idx::en</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2toc'>doctools2toc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (C)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_de'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_de.html">doctools::msgcat::toc::de</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (DE)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_en'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_en.html">doctools::msgcat::toc::en</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (EN)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_fr'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_fr.html">doctools::msgcat::toc::fr</a></td>
<td class="#doctools_tocright">Message catalog for the doctoc parser (FR)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc'><a href="tcllib/files/modules/doctools2toc/toc_container.html">doctools::toc</a></td>
<td class="#doctools_tocright">Holding tables of contents</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export'><a href="tcllib/files/modules/doctools2toc/toc_export.html">doctools::toc::export</a></td>
<td class="#doctools_tocright">Exporting tables of contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_doctoc'><a href="tcllib/files/modules/doctools2toc/export_doctoc.html">doctools::toc::export::doctoc</a></td>
<td class="#doctools_tocright">doctoc export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_html'><a href="tcllib/files/modules/doctools2toc/toc_export_html.html">doctools::toc::export::html</a></td>
<td class="#doctools_tocright">HTML export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_json'><a href="tcllib/files/modules/doctools2toc/toc_export_json.html">doctools::toc::export::json</a></td>
<td class="#doctools_tocright">JSON export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_nroff'><a href="tcllib/files/modules/doctools2toc/toc_export_nroff.html">doctools::toc::export::nroff</a></td>
<td class="#doctools_tocright">nroff export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_text'><a href="tcllib/files/modules/doctools2toc/toc_export_text.html">doctools::toc::export::text</a></td>
<td class="#doctools_tocright">plain text export plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_export_wiki'><a href="tcllib/files/modules/doctools2toc/toc_export_wiki.html">doctools::toc::export::wiki</a></td>
<td class="#doctools_tocright">wiki export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import'><a href="tcllib/files/modules/doctools2toc/toc_import.html">doctools::toc::import</a></td>
<td class="#doctools_tocright">Importing keyword indices</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_doctoc'><a href="tcllib/files/modules/doctools2toc/import_doctoc.html">doctools::toc::import::doctoc</a></td>
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_toc_parse'><a href="tcllib/files/modules/doctools2toc/toc_parse.html">doctools::toc::parse</a></td>
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
</table></dl>
<dl><dt><a name='dtplite'>dtplite<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
</table></dl>
<dl><dt><a name='fileutil'>fileutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
</table></dl>
<dl><dt><a name='ftp'>ftp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
</table></dl>
<dl><dt><a name='ftpd'>ftpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='fumagic'>fumagic<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='generator'>generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
</table></dl>
<dl><dt><a name='gpx'>gpx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_aycock'>grammar_aycock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_fa'>grammar_fa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_me'>grammar_me<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
<td class="#doctools_tocright">ME virtual machine state manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_gasm'><a href="tcllib/files/modules/grammar_me/gasm.html">grammar::me::cpu::gasm</a></td>
<td class="#doctools_tocright">ME assembler</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_tcl'><a href="tcllib/files/modules/grammar_me/me_tcl.html">grammar::me::tcl</a></td>
<td class="#doctools_tocright">Virtual machine implementation I for parsing token streams</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_util'><a href="tcllib/files/modules/grammar_me/me_util.html">grammar::me::util</a></td>
<td class="#doctools_tocright">AST utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_ast'><a href="tcllib/files/modules/grammar_me/me_ast.html">grammar::me_ast</a></td>
<td class="#doctools_tocright">Various representations of ASTs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_intro'><a href="tcllib/files/modules/grammar_me/me_intro.html">grammar::me_intro</a></td>
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_peg'>grammar_peg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hook'>hook<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
</table></dl>
<dl><dt><a name='html'>html<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
</table></dl>
<dl><dt><a name='htmlparse'>htmlparse<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
</table></dl>
<dl><dt><a name='http'>http<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
</table></dl>
<dl><dt><a name='httpd'>httpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
</table></dl>
<dl><dt><a name='ident'>ident<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
</table></dl>
<dl><dt><a name='imap4'>imap4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
</table></dl>
<dl><dt><a name='inifile'>inifile<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
</table></dl>
<dl><dt><a name='interp'>interp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
</table></dl>
<dl><dt><a name='irc'>irc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
</table></dl>
<dl><dt><a name='javascript'>javascript<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
</table></dl>
<dl><dt><a name='jpeg'>jpeg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='json'>json<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
</table></dl>
<dl><dt><a name='lambda'>lambda<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
</table></dl>
<dl><dt><a name='lazyset'>lazyset<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
</table></dl>
<dl><dt><a name='ldap'>ldap<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
</table></dl>
<dl><dt><a name='log'>log<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
</table></dl>
<dl><dt><a name='map'>map<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
</table></dl>
<dl><dt><a name='mapproj'>mapproj<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
</table></dl>
<dl><dt><a name='markdown'>markdown<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
</table></dl>
<dl><dt><a name='math'>math<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
<td class="#doctools_tocright">Arbitrary precision floating-point numbers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_bignum'><a href="tcllib/files/modules/math/bignum.html">math::bignum</a></td>
<td class="#doctools_tocright">Arbitrary precision integer numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus'><a href="tcllib/files/modules/math/calculus.html">math::calculus</a></td>
<td class="#doctools_tocright">Integration and ordinary differential equations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_calculus_romberg'><a href="tcllib/files/modules/math/romberg.html">math::calculus::romberg</a></td>
<td class="#doctools_tocright">Romberg integration</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_calculus_symdiff'><a href="tcllib/files/modules/math/symdiff.html">math::calculus::symdiff</a></td>
<td class="#doctools_tocright">Symbolic differentiation for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_combinatorics'><a href="tcllib/files/modules/math/combinatorics.html">math::combinatorics</a></td>
<td class="#doctools_tocright">Combinatorial functions in the Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_complexnumbers'><a href="tcllib/files/modules/math/qcomplex.html">math::complexnumbers</a></td>
<td class="#doctools_tocright">Straightforward complex number package</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_constants'><a href="tcllib/files/modules/math/constants.html">math::constants</a></td>
<td class="#doctools_tocright">Mathematical and numerical constants</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_decimal'><a href="tcllib/files/modules/math/decimal.html">math::decimal</a></td>
<td class="#doctools_tocright">General decimal arithmetic</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_exact'><a href="tcllib/files/modules/math/exact.html">math::exact</a></td>
<td class="#doctools_tocright">Exact Real Arithmetic</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_fourier'><a href="tcllib/files/modules/math/fourier.html">math::fourier</a></td>
<td class="#doctools_tocright">Discrete and fast fourier transforms</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_fuzzy'><a href="tcllib/files/modules/math/fuzzy.html">math::fuzzy</a></td>
<td class="#doctools_tocright">Fuzzy comparison of floating-point numbers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_geometry'><a href="tcllib/files/modules/math/math_geometry.html">math::geometry</a></td>
<td class="#doctools_tocright">Geometrical computations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_interpolate'><a href="tcllib/files/modules/math/interpolate.html">math::interpolate</a></td>
<td class="#doctools_tocright">Interpolation routines</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_linearalgebra'><a href="tcllib/files/modules/math/linalg.html">math::linearalgebra</a></td>
<td class="#doctools_tocright">Linear Algebra</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_numtheory'><a href="tcllib/files/modules/math/numtheory.html">math::numtheory</a></td>
<td class="#doctools_tocright">Number Theory</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_optimize'><a href="tcllib/files/modules/math/optimize.html">math::optimize</a></td>
<td class="#doctools_tocright">Optimisation routines</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_pca'><a href="tcllib/files/modules/math/pca.html">math::PCA</a></td>
<td class="#doctools_tocright">Package for Principal Component Analysis</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_polynomials'><a href="tcllib/files/modules/math/polynomials.html">math::polynomials</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_rationalfunctions'><a href="tcllib/files/modules/math/rational_funcs.html">math::rationalfunctions</a></td>
<td class="#doctools_tocright">Polynomial functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_roman'><a href="tcllib/files/modules/math/roman.html">math::roman</a></td>
<td class="#doctools_tocright">Tools for creating and manipulating roman numerals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_special'><a href="tcllib/files/modules/math/special.html">math::special</a></td>
<td class="#doctools_tocright">Special mathematical functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_statistics'><a href="tcllib/files/modules/math/statistics.html">math::statistics</a></td>
<td class="#doctools_tocright">Basic statistical functions and procedures</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math_trig'><a href="tcllib/files/modules/math/trig.html">math::trig</a></td>
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
</table></dl>
<dl><dt><a name='md4'>md4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5'>md5<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5crypt'>md5crypt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
</table></dl>
<dl><dt><a name='mime'>mime<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
</table></dl>
<dl><dt><a name='multiplexer'>multiplexer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
</table></dl>
<dl><dt><a name='namespacex'>namespacex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
</table></dl>
<dl><dt><a name='ncgi'>ncgi<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='nettool'>nettool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
</table></dl>
<dl><dt><a name='nmea'>nmea<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
</table></dl>
<dl><dt><a name='nns'>nns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
<td class="#doctools_tocright">Name service facility, Client Extension</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_common'><a href="tcllib/files/modules/nns/nns_common.html">nameserv::common</a></td>
<td class="#doctools_tocright">Name service facility, shared definitions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_protocol'><a href="tcllib/files/modules/nns/nns_protocol.html">nameserv::protocol</a></td>
<td class="#doctools_tocright">Name service facility, client/server protocol</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv_server'><a href="tcllib/files/modules/nns/nns_server.html">nameserv::server</a></td>
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
</table></dl>
<dl><dt><a name='nntp'>nntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
</table></dl>
<dl><dt><a name='ntp'>ntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
</table></dl>
<dl><dt><a name='oauth'>oauth<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
</table></dl>
<dl><dt><a name='oometa'>oometa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
</table></dl>
<dl><dt><a name='ooutil'>ooutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
</table></dl>
<dl><dt><a name='otp'>otp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
</table></dl>
<dl><dt><a name='page'>page<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
<td class="#doctools_tocright">page plugin manager</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_flow'><a href="tcllib/files/modules/page/page_util_flow.html">page_util_flow</a></td>
<td class="#doctools_tocright">page dataflow/treewalker utility</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_norm_lemon'><a href="tcllib/files/modules/page/page_util_norm_lemon.html">page_util_norm_lemon</a></td>
<td class="#doctools_tocright">page AST normalization, LEMON</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_norm_peg'><a href="tcllib/files/modules/page/page_util_norm_peg.html">page_util_norm_peg</a></td>
<td class="#doctools_tocright">page AST normalization, PEG</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_peg'><a href="tcllib/files/modules/page/page_util_peg.html">page_util_peg</a></td>
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='pki'>pki<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
</table></dl>
<dl><dt><a name='pluginmgr'>pluginmgr<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
</table></dl>
<dl><dt><a name='png'>png<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='pop3'>pop3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
</table></dl>
<dl><dt><a name='pop3d'>pop3d<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
</table></dl>
<dl><dt><a name='practcl'>practcl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
</table></dl>
<dl><dt><a name='processman'>processman<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='profiler'>profiler<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
</table></dl>
<dl><dt><a name='pt'>pt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, Critcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_tea'><a href="tcllib/files/modules/pt/pt_cparam_config_tea.html">pt::cparam::configuration::tea</a></td>
<td class="#doctools_tocright">C/PARAM, Canned configuration, TEA</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_json_language'><a href="tcllib/files/modules/pt/pt_json_language.html">pt::json_language</a></td>
<td class="#doctools_tocright">The JSON Grammar Exchange Format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_param'><a href="tcllib/files/modules/pt/pt_param.html">pt::param</a></td>
<td class="#doctools_tocright">PackRat Machine Specification</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pe'><a href="tcllib/files/modules/pt/pt_pexpression.html">pt::pe</a></td>
<td class="#doctools_tocright">Parsing Expression Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pe_op'><a href="tcllib/files/modules/pt/pt_pexpr_op.html">pt::pe::op</a></td>
<td class="#doctools_tocright">Parsing Expression Utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg'><a href="tcllib/files/modules/pt/pt_pegrammar.html">pt::peg</a></td>
<td class="#doctools_tocright">Parsing Expression Grammar Serialization</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_container'><a href="tcllib/files/modules/pt/pt_peg_container.html">pt::peg::container</a></td>
<td class="#doctools_tocright">PEG Storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_container_peg'><a href="tcllib/files/modules/pt/pt_peg_container_peg.html">pt::peg::container::peg</a></td>
<td class="#doctools_tocright">PEG Storage. Canned PEG grammar specification</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export'><a href="tcllib/files/modules/pt/pt_peg_export.html">pt::peg::export</a></td>
<td class="#doctools_tocright">PEG Export</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_container'><a href="tcllib/files/modules/pt/pt_peg_export_container.html">pt::peg::export::container</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write CONTAINER format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_json'><a href="tcllib/files/modules/pt/pt_peg_export_json.html">pt::peg::export::json</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_export_peg'><a href="tcllib/files/modules/pt/pt_peg_export_peg.html">pt::peg::export::peg</a></td>
<td class="#doctools_tocright">PEG Export Plugin. Write PEG format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_container'><a href="tcllib/files/modules/pt/pt_peg_from_container.html">pt::peg::from::container</a></td>
<td class="#doctools_tocright">PEG Conversion. From CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_json'><a href="tcllib/files/modules/pt/pt_peg_from_json.html">pt::peg::from::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Read JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_from_peg'><a href="tcllib/files/modules/pt/pt_peg_from_peg.html">pt::peg::from::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Read PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import'><a href="tcllib/files/modules/pt/pt_peg_import.html">pt::peg::import</a></td>
<td class="#doctools_tocright">PEG Import</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_container'><a href="tcllib/files/modules/pt/pt_peg_import_container.html">pt::peg::import::container</a></td>
<td class="#doctools_tocright">PEG Import Plugin. From CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_json'><a href="tcllib/files/modules/pt/pt_peg_import_json.html">pt::peg::import::json</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read JSON format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_import_peg'><a href="tcllib/files/modules/pt/pt_peg_import_peg.html">pt::peg::import::peg</a></td>
<td class="#doctools_tocright">PEG Import Plugin. Read PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_interp'><a href="tcllib/files/modules/pt/pt_peg_interp.html">pt::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_container'><a href="tcllib/files/modules/pt/pt_peg_to_container.html">pt::peg::to::container</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CONTAINER format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_cparam'><a href="tcllib/files/modules/pt/pt_peg_to_cparam.html">pt::peg::to::cparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write CPARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_json'><a href="tcllib/files/modules/pt/pt_peg_to_json.html">pt::peg::to::json</a></td>
<td class="#doctools_tocright">PEG Conversion. Write JSON format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_param'><a href="tcllib/files/modules/pt/pt_peg_to_param.html">pt::peg::to::param</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_peg'><a href="tcllib/files/modules/pt/pt_peg_to_peg.html">pt::peg::to::peg</a></td>
<td class="#doctools_tocright">PEG Conversion. Write PEG format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_to_tclparam'><a href="tcllib/files/modules/pt/pt_peg_to_tclparam.html">pt::peg::to::tclparam</a></td>
<td class="#doctools_tocright">PEG Conversion. Write TCLPARAM format</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_language'><a href="tcllib/files/modules/pt/pt_peg_language.html">pt::peg_language</a></td>
<td class="#doctools_tocright">PEG Language Tutorial</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_pegrammar'><a href="tcllib/files/modules/pt/pt_peg_introduction.html">pt::pegrammar</a></td>
<td class="#doctools_tocright">Introduction to Parsing Expression Grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_pgen'><a href="tcllib/files/modules/pt/pt_pgen.html">pt::pgen</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_rde'><a href="tcllib/files/modules/pt/pt_rdengine.html">pt::rde</a></td>
<td class="#doctools_tocright">Parsing Runtime Support, PARAM based</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_nx'><a href="tcllib/files/modules/pt/pt_tclparam_config_nx.html">pt::tclparam::configuration::nx</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, NX</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_snit'><a href="tcllib/files/modules/pt/pt_tclparam_config_snit.html">pt::tclparam::configuration::snit</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Snit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_tclparam_configuration_tcloo'><a href="tcllib/files/modules/pt/pt_tclparam_config_tcloo.html">pt::tclparam::configuration::tcloo</a></td>
<td class="#doctools_tocright">Tcl/PARAM, Canned configuration, Tcloo</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_util'><a href="tcllib/files/modules/pt/pt_util.html">pt::util</a></td>
<td class="#doctools_tocright">General utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_export_api'><a href="tcllib/files/modules/pt/pt_to_api.html">pt_export_api</a></td>
<td class="#doctools_tocright">Parser Tools Export API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_import_api'><a href="tcllib/files/modules/pt/pt_from_api.html">pt_import_api</a></td>
<td class="#doctools_tocright">Parser Tools Import API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_introduction'><a href="tcllib/files/modules/pt/pt_introduction.html">pt_introduction</a></td>
<td class="#doctools_tocright">Introduction to Parser Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_parse_peg'><a href="tcllib/files/modules/pt/pt_parse_peg.html">pt_parse_peg</a></td>
<td class="#doctools_tocright">Parser Tools PEG Parser</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_parser_api'><a href="tcllib/files/modules/pt/pt_parser_api.html">pt_parser_api</a></td>
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='rc4'>rc4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
</table></dl>
<dl><dt><a name='rcs'>rcs<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
</table></dl>
<dl><dt><a name='report'>report<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
</table></dl>
<dl><dt><a name='rest'>rest<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
</table></dl>
<dl><dt><a name='ripemd'>ripemd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='sasl'>sasl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='sha1'>sha1<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='simulation'>simulation<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='smtpd'>smtpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='snit'>snit<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
</table></dl>
<dl><dt><a name='soundex'>soundex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
</table></dl>
<dl><dt><a name='stooop'>stooop<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
</table></dl>
<dl><dt><a name='string'>string<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
</table></dl>
<dl><dt><a name='stringprep'>stringprep<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
</table></dl>
<dl><dt><a name='struct'>struct<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_graph_op'><a href="tcllib/files/modules/struct/graphops.html">struct::graph::op</a></td>
<td class="#doctools_tocright">Operation for (un)directed graph objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph_v1'><a href="tcllib/files/modules/struct/graph1.html">struct::graph_v1</a></td>
<td class="#doctools_tocright">Create and manipulate directed graph objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_list'><a href="tcllib/files/modules/struct/struct_list.html">struct::list</a></td>
<td class="#doctools_tocright">Procedures for manipulating lists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_matrix'><a href="tcllib/files/modules/struct/matrix.html">struct::matrix</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_matrix_v1'><a href="tcllib/files/modules/struct/matrix1.html">struct::matrix_v1</a></td>
<td class="#doctools_tocright">Create and manipulate matrix objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_pool'><a href="tcllib/files/modules/struct/pool.html">struct::pool</a></td>
<td class="#doctools_tocright">Create and manipulate pool objects (of discrete items)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_prioqueue'><a href="tcllib/files/modules/struct/prioqueue.html">struct::prioqueue</a></td>
<td class="#doctools_tocright">Create and manipulate prioqueue objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_queue'><a href="tcllib/files/modules/struct/queue.html">struct::queue</a></td>
<td class="#doctools_tocright">Create and manipulate queue objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_record'><a href="tcllib/files/modules/struct/record.html">struct::record</a></td>
<td class="#doctools_tocright">Define and create records (similar to 'C' structures)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_set'><a href="tcllib/files/modules/struct/struct_set.html">struct::set</a></td>
<td class="#doctools_tocright">Procedures for manipulating sets</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_skiplist'><a href="tcllib/files/modules/struct/skiplist.html">struct::skiplist</a></td>
<td class="#doctools_tocright">Create and manipulate skiplists</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_stack'><a href="tcllib/files/modules/struct/stack.html">struct::stack</a></td>
<td class="#doctools_tocright">Create and manipulate stack objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_tree'><a href="tcllib/files/modules/struct/struct_tree.html">struct::tree</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='tar'>tar<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='tepam'>tepam<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='term'>term<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
<td class="#doctools_tocright">Helper for control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_attr'><a href="tcllib/files/modules/term/ansi_cattr.html">term::ansi::code::attr</a></td>
<td class="#doctools_tocright">ANSI attribute sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_ctrl'><a href="tcllib/files/modules/term/ansi_cctrl.html">term::ansi::code::ctrl</a></td>
<td class="#doctools_tocright">ANSI control sequences</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_code_macros'><a href="tcllib/files/modules/term/ansi_cmacros.html">term::ansi::code::macros</a></td>
<td class="#doctools_tocright">Macro sequences</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_ctrl_unix'><a href="tcllib/files/modules/term/ansi_ctrlu.html">term::ansi::ctrl::unix</a></td>
<td class="#doctools_tocright">Control operations and queries</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_ansi_send'><a href="tcllib/files/modules/term/ansi_send.html">term::ansi::send</a></td>
<td class="#doctools_tocright">Output of ANSI control sequences to terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_interact_menu'><a href="tcllib/files/modules/term/imenu.html">term::interact::menu</a></td>
<td class="#doctools_tocright">Terminal widget, menu</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_interact_pager'><a href="tcllib/files/modules/term/ipager.html">term::interact::pager</a></td>
<td class="#doctools_tocright">Terminal widget, paging</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_receive'><a href="tcllib/files/modules/term/receive.html">term::receive</a></td>
<td class="#doctools_tocright">General input from terminals</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term_receive_bind'><a href="tcllib/files/modules/term/term_bind.html">term::receive::bind</a></td>
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='textutil'>textutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
<td class="#doctools_tocright">Procedures to adjust, indent, and undent paragraphs</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_repeat'><a href="tcllib/files/modules/textutil/repeat.html">textutil::repeat</a></td>
<td class="#doctools_tocright">Procedures to repeat strings.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_split'><a href="tcllib/files/modules/textutil/textutil_split.html">textutil::split</a></td>
<td class="#doctools_tocright">Procedures to split texts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_string'><a href="tcllib/files/modules/textutil/textutil_string.html">textutil::string</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_tabify'><a href="tcllib/files/modules/textutil/tabify.html">textutil::tabify</a></td>
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
</table></dl>
<dl><dt><a name='tie'>tie<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
</table></dl>
<dl><dt><a name='tiff'>tiff<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='tool'>tool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='transfer'>transfer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
<td class="#doctools_tocright">Data transfer foundation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_copy_queue'><a href="tcllib/files/modules/transfer/tqueue.html">transfer::copy::queue</a></td>
<td class="#doctools_tocright">Queued transfers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_data_destination'><a href="tcllib/files/modules/transfer/ddest.html">transfer::data::destination</a></td>
<td class="#doctools_tocright">Data destination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_data_source'><a href="tcllib/files/modules/transfer/dsource.html">transfer::data::source</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_receiver'><a href="tcllib/files/modules/transfer/receiver.html">transfer::receiver</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='treeql'>treeql<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='try'>try<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='udpcluster'>udpcluster<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
</table></dl>
<dl><dt><a name='uev'>uev<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
</table></dl>
<dl><dt><a name='units'>units<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
</table></dl>
<dl><dt><a name='uri'>uri<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
</table></dl>
<dl><dt><a name='uuid'>uuid<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='valtype'>valtype<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
<td class="#doctools_tocright">Validation for AMEX creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_discover'><a href="tcllib/files/modules/valtype/cc_discover.html">valtype::creditcard::discover</a></td>
<td class="#doctools_tocright">Validation for Discover creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_mastercard'><a href="tcllib/files/modules/valtype/cc_mastercard.html">valtype::creditcard::mastercard</a></td>
<td class="#doctools_tocright">Validation for Mastercard creditcard number</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_visa'><a href="tcllib/files/modules/valtype/cc_visa.html">valtype::creditcard::visa</a></td>
<td class="#doctools_tocright">Validation for VISA creditcard number</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_gs1_ean13'><a href="tcllib/files/modules/valtype/ean13.html">valtype::gs1::ean13</a></td>
<td class="#doctools_tocright">Validation for EAN13</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_iban'><a href="tcllib/files/modules/valtype/iban.html">valtype::iban</a></td>
<td class="#doctools_tocright">Validation for IBAN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_imei'><a href="tcllib/files/modules/valtype/imei.html">valtype::imei</a></td>
<td class="#doctools_tocright">Validation for IMEI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_isbn'><a href="tcllib/files/modules/valtype/isbn.html">valtype::isbn</a></td>
<td class="#doctools_tocright">Validation for ISBN</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_luhn'><a href="tcllib/files/modules/valtype/luhn.html">valtype::luhn</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN checkdigit</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_luhn5'><a href="tcllib/files/modules/valtype/luhn5.html">valtype::luhn5</a></td>
<td class="#doctools_tocright">Validation for plain number with a LUHN5 checkdigit</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_base'>virtchannel_base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
<td class="#doctools_tocright">Facade channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo.html">tcl::chan::fifo</a></td>
<td class="#doctools_tocright">In-memory fifo channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_fifo2'><a href="tcllib/files/modules/virtchannel_base/tcllib_fifo2.html">tcl::chan::fifo2</a></td>
<td class="#doctools_tocright">In-memory interconnected fifo channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_halfpipe'><a href="tcllib/files/modules/virtchannel_base/halfpipe.html">tcl::chan::halfpipe</a></td>
<td class="#doctools_tocright">In-memory channel, half of a fifo2</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_memchan'><a href="tcllib/files/modules/virtchannel_base/tcllib_memchan.html">tcl::chan::memchan</a></td>
<td class="#doctools_tocright">In-memory channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_null'><a href="tcllib/files/modules/virtchannel_base/tcllib_null.html">tcl::chan::null</a></td>
<td class="#doctools_tocright">Null channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_nullzero'><a href="tcllib/files/modules/virtchannel_base/nullzero.html">tcl::chan::nullzero</a></td>
<td class="#doctools_tocright">Null/Zero channel combination</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_random'><a href="tcllib/files/modules/virtchannel_base/tcllib_random.html">tcl::chan::random</a></td>
<td class="#doctools_tocright">Random channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_std'><a href="tcllib/files/modules/virtchannel_base/std.html">tcl::chan::std</a></td>
<td class="#doctools_tocright">Standard I/O, unification of stdin and stdout</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_string'><a href="tcllib/files/modules/virtchannel_base/tcllib_string.html">tcl::chan::string</a></td>
<td class="#doctools_tocright">Read-only in-memory channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_textwindow'><a href="tcllib/files/modules/virtchannel_base/textwindow.html">tcl::chan::textwindow</a></td>
<td class="#doctools_tocright">Textwindow channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_variable'><a href="tcllib/files/modules/virtchannel_base/tcllib_variable.html">tcl::chan::variable</a></td>
<td class="#doctools_tocright">In-memory channel using variable for storage</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_zero'><a href="tcllib/files/modules/virtchannel_base/tcllib_zero.html">tcl::chan::zero</a></td>
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_core'>virtchannel_core<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_transform'>virtchannel_transform<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
<td class="#doctools_tocright">Base64 encoding transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_counter'><a href="tcllib/files/modules/virtchannel_transform/vt_counter.html">tcl::transform::counter</a></td>
<td class="#doctools_tocright">Counter transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_crc32'><a href="tcllib/files/modules/virtchannel_transform/vt_crc32.html">tcl::transform::crc32</a></td>
<td class="#doctools_tocright">Crc32 transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_hex'><a href="tcllib/files/modules/virtchannel_transform/hex.html">tcl::transform::hex</a></td>
<td class="#doctools_tocright">Hexadecimal encoding transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_identity'><a href="tcllib/files/modules/virtchannel_transform/identity.html">tcl::transform::identity</a></td>
<td class="#doctools_tocright">Identity transformation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_limitsize'><a href="tcllib/files/modules/virtchannel_transform/limitsize.html">tcl::transform::limitsize</a></td>
<td class="#doctools_tocright">limiting input</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_observe'><a href="tcllib/files/modules/virtchannel_transform/observe.html">tcl::transform::observe</a></td>
<td class="#doctools_tocright">Observer transformation, stream copy</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_otp'><a href="tcllib/files/modules/virtchannel_transform/vt_otp.html">tcl::transform::otp</a></td>
<td class="#doctools_tocright">Encryption via one-time pad</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_rot'><a href="tcllib/files/modules/virtchannel_transform/rot.html">tcl::transform::rot</a></td>
<td class="#doctools_tocright">rot-encryption</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_spacer'><a href="tcllib/files/modules/virtchannel_transform/spacer.html">tcl::transform::spacer</a></td>
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='websocket'>websocket<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='wip'>wip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='yaml'>yaml<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='zip'>zip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl></table></dl>
</dl><hr>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Deleted embedded/www/toc2.html.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
<div class='fossil-doc' data-title='Table Of Contents'>
<style>
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
</style>
<hr> [
<a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='applications'>Applications<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nnsd'><a href="tcllib/files/apps/nnsd.html">nnsd</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Server Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nnslog'><a href="tcllib/files/apps/nnslog.html">nnslog</a></td>
<td class="#doctools_tocright">Name service facility, Commandline Logging Client Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
</table></dl>
</dl><hr>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
Changes to idoc/man/files/apps/dtplite.n.
Changes to idoc/man/files/apps/nns.n.
Changes to idoc/man/files/apps/nnsd.n.
Changes to idoc/man/files/apps/nnslog.n.
Changes to idoc/man/files/apps/page.n.
Changes to idoc/man/files/apps/pt.n.
Changes to idoc/man/files/apps/tcldocstrip.n.
Changes to idoc/man/files/modules/aes/aes.n.
Changes to idoc/man/files/modules/amazon-s3/S3.n.
Changes to idoc/man/files/modules/amazon-s3/xsxp.n.
Changes to idoc/man/files/modules/asn/asn.n.
Changes to idoc/man/files/modules/base32/base32.n.
Changes to idoc/man/files/modules/base32/base32core.n.
Changes to idoc/man/files/modules/base32/base32hex.n.
Changes to idoc/man/files/modules/base64/ascii85.n.
Changes to idoc/man/files/modules/base64/base64.n.
Changes to idoc/man/files/modules/base64/uuencode.n.
Changes to idoc/man/files/modules/base64/yencode.n.
Changes to idoc/man/files/modules/bee/bee.n.
Changes to idoc/man/files/modules/bench/bench.n.
Changes to idoc/man/files/modules/bench/bench_intro.n.
Changes to idoc/man/files/modules/bench/bench_lang_intro.n.
Changes to idoc/man/files/modules/bench/bench_lang_spec.n.
Changes to idoc/man/files/modules/bench/bench_read.n.
Changes to idoc/man/files/modules/bench/bench_wcsv.n.
Changes to idoc/man/files/modules/bench/bench_wtext.n.
Changes to idoc/man/files/modules/bibtex/bibtex.n.
Changes to idoc/man/files/modules/blowfish/blowfish.n.
Changes to idoc/man/files/modules/cache/async.n.
Changes to idoc/man/files/modules/clock/iso8601.n.
Changes to idoc/man/files/modules/clock/rfc2822.n.
Changes to idoc/man/files/modules/cmdline/cmdline.n.
Changes to idoc/man/files/modules/comm/comm.n.
Changes to idoc/man/files/modules/comm/comm_wire.n.
Changes to idoc/man/files/modules/control/control.n.
Changes to idoc/man/files/modules/coroutine/coro_auto.n.
Changes to idoc/man/files/modules/coroutine/tcllib_coroutine.n.
Changes to idoc/man/files/modules/counter/counter.n.
Changes to idoc/man/files/modules/crc/cksum.n.
Changes to idoc/man/files/modules/crc/crc16.n.
Changes to idoc/man/files/modules/crc/crc32.n.
Changes to idoc/man/files/modules/crc/sum.n.
Changes to idoc/man/files/modules/cron/cron.n.
Changes to idoc/man/files/modules/csv/csv.n.
Changes to idoc/man/files/modules/debug/debug.n.
Changes to idoc/man/files/modules/debug/debug_caller.n.
Changes to idoc/man/files/modules/debug/debug_heartbeat.n.
Changes to idoc/man/files/modules/debug/debug_timestamp.n.
Changes to idoc/man/files/modules/defer/defer.n.
Changes to idoc/man/files/modules/des/des.n.
Changes to idoc/man/files/modules/des/tcldes.n.
Changes to idoc/man/files/modules/des/tcldesjr.n.
Changes to idoc/man/files/modules/dicttool/dicttool.n.
Changes to idoc/man/files/modules/dns/tcllib_dns.n.
Changes to idoc/man/files/modules/dns/tcllib_ip.n.
Changes to idoc/man/files/modules/docstrip/docstrip.n.
Changes to idoc/man/files/modules/docstrip/docstrip_util.n.
Changes to idoc/man/files/modules/doctools/changelog.n.
Changes to idoc/man/files/modules/doctools/cvs.n.
Changes to idoc/man/files/modules/doctools/docidx.n.
Changes to idoc/man/files/modules/doctools/docidx_intro.n.
Changes to idoc/man/files/modules/doctools/docidx_lang_cmdref.n.
Changes to idoc/man/files/modules/doctools/docidx_lang_faq.n.
Changes to idoc/man/files/modules/doctools/docidx_lang_intro.n.
Changes to idoc/man/files/modules/doctools/docidx_lang_syntax.n.
Changes to idoc/man/files/modules/doctools/docidx_plugin_apiref.n.
Changes to idoc/man/files/modules/doctools/doctoc.n.
Changes to idoc/man/files/modules/doctools/doctoc_intro.n.
Changes to idoc/man/files/modules/doctools/doctoc_lang_cmdref.n.
Changes to idoc/man/files/modules/doctools/doctoc_lang_faq.n.
Changes to idoc/man/files/modules/doctools/doctoc_lang_intro.n.
Changes to idoc/man/files/modules/doctools/doctoc_lang_syntax.n.
Changes to idoc/man/files/modules/doctools/doctoc_plugin_apiref.n.
Changes to idoc/man/files/modules/doctools/doctools.n.
Changes to idoc/man/files/modules/doctools/doctools_intro.n.
Changes to idoc/man/files/modules/doctools/doctools_lang_cmdref.n.
Changes to idoc/man/files/modules/doctools/doctools_lang_faq.n.
Changes to idoc/man/files/modules/doctools/doctools_lang_intro.n.
Changes to idoc/man/files/modules/doctools/doctools_lang_syntax.n.
Changes to idoc/man/files/modules/doctools/doctools_plugin_apiref.n.
Changes to idoc/man/files/modules/doctools/mpexpand.n.
Changes to idoc/man/files/modules/doctools2base/html_cssdefaults.n.
Changes to idoc/man/files/modules/doctools2base/nroff_manmacros.n.
Changes to idoc/man/files/modules/doctools2base/tcl_parse.n.
Changes to idoc/man/files/modules/doctools2base/tcllib_msgcat.n.
Changes to idoc/man/files/modules/doctools2idx/export_docidx.n.
Changes to idoc/man/files/modules/doctools2idx/idx_container.n.
Changes to idoc/man/files/modules/doctools2idx/idx_export.n.
Changes to idoc/man/files/modules/doctools2idx/idx_export_html.n.
Changes to idoc/man/files/modules/doctools2idx/idx_export_json.n.
Changes to idoc/man/files/modules/doctools2idx/idx_export_nroff.n.
Changes to idoc/man/files/modules/doctools2idx/idx_export_text.n.
Changes to idoc/man/files/modules/doctools2idx/idx_export_wiki.n.
Changes to idoc/man/files/modules/doctools2idx/idx_import.n.
Changes to idoc/man/files/modules/doctools2idx/idx_import_json.n.
Changes to idoc/man/files/modules/doctools2idx/idx_introduction.n.
Changes to idoc/man/files/modules/doctools2idx/idx_msgcat_c.n.
Changes to idoc/man/files/modules/doctools2idx/idx_msgcat_de.n.
Changes to idoc/man/files/modules/doctools2idx/idx_msgcat_en.n.
Changes to idoc/man/files/modules/doctools2idx/idx_msgcat_fr.n.
Changes to idoc/man/files/modules/doctools2idx/idx_parse.n.
Changes to idoc/man/files/modules/doctools2idx/idx_structure.n.
Changes to idoc/man/files/modules/doctools2idx/import_docidx.n.
Changes to idoc/man/files/modules/doctools2toc/export_doctoc.n.
Changes to idoc/man/files/modules/doctools2toc/import_doctoc.n.
Changes to idoc/man/files/modules/doctools2toc/toc_container.n.
Changes to idoc/man/files/modules/doctools2toc/toc_export.n.
Changes to idoc/man/files/modules/doctools2toc/toc_export_html.n.
Changes to idoc/man/files/modules/doctools2toc/toc_export_json.n.
Changes to idoc/man/files/modules/doctools2toc/toc_export_nroff.n.
Changes to idoc/man/files/modules/doctools2toc/toc_export_text.n.
Changes to idoc/man/files/modules/doctools2toc/toc_export_wiki.n.
Changes to idoc/man/files/modules/doctools2toc/toc_import.n.
Changes to idoc/man/files/modules/doctools2toc/toc_import_json.n.
Changes to idoc/man/files/modules/doctools2toc/toc_introduction.n.
Changes to idoc/man/files/modules/doctools2toc/toc_msgcat_c.n.
Changes to idoc/man/files/modules/doctools2toc/toc_msgcat_de.n.
Changes to idoc/man/files/modules/doctools2toc/toc_msgcat_en.n.
Changes to idoc/man/files/modules/doctools2toc/toc_msgcat_fr.n.
Changes to idoc/man/files/modules/doctools2toc/toc_parse.n.
Changes to idoc/man/files/modules/doctools2toc/toc_structure.n.
Changes to idoc/man/files/modules/dtplite/pkg_dtplite.n.
Changes to idoc/man/files/modules/fileutil/fileutil.n.
Changes to idoc/man/files/modules/fileutil/multi.n.
Changes to idoc/man/files/modules/fileutil/multiop.n.
Changes to idoc/man/files/modules/fileutil/traverse.n.
Changes to idoc/man/files/modules/ftp/ftp.n.
Changes to idoc/man/files/modules/ftp/ftp_geturl.n.
Changes to idoc/man/files/modules/ftpd/ftpd.n.
Changes to idoc/man/files/modules/fumagic/cfront.n.
Changes to idoc/man/files/modules/fumagic/cgen.n.
Changes to idoc/man/files/modules/fumagic/filetypes.n.
Changes to idoc/man/files/modules/fumagic/rtcore.n.
Changes to idoc/man/files/modules/generator/generator.n.
Changes to idoc/man/files/modules/gpx/gpx.n.
Changes to idoc/man/files/modules/grammar_aycock/aycock.n.
Changes to idoc/man/files/modules/grammar_fa/dacceptor.n.
Changes to idoc/man/files/modules/grammar_fa/dexec.n.
Changes to idoc/man/files/modules/grammar_fa/fa.n.
Changes to idoc/man/files/modules/grammar_fa/faop.n.
Changes to idoc/man/files/modules/grammar_me/gasm.n.
Changes to idoc/man/files/modules/grammar_me/me_ast.n.
Changes to idoc/man/files/modules/grammar_me/me_cpu.n.
Changes to idoc/man/files/modules/grammar_me/me_cpucore.n.
Changes to idoc/man/files/modules/grammar_me/me_intro.n.
Changes to idoc/man/files/modules/grammar_me/me_tcl.n.
Changes to idoc/man/files/modules/grammar_me/me_util.n.
Changes to idoc/man/files/modules/grammar_me/me_vm.n.
Changes to idoc/man/files/modules/grammar_peg/peg.n.
Changes to idoc/man/files/modules/grammar_peg/peg_interp.n.
Changes to idoc/man/files/modules/hook/hook.n.
Changes to idoc/man/files/modules/html/html.n.
Changes to idoc/man/files/modules/htmlparse/htmlparse.n.
Changes to idoc/man/files/modules/http/autoproxy.n.
Changes to idoc/man/files/modules/httpd/httpd.n.
Changes to idoc/man/files/modules/ident/ident.n.
Changes to idoc/man/files/modules/imap4/imap4.n.
Changes to idoc/man/files/modules/inifile/ini.n.
Changes to idoc/man/files/modules/interp/deleg_method.n.
Changes to idoc/man/files/modules/interp/deleg_proc.n.
Changes to idoc/man/files/modules/interp/tcllib_interp.n.
Changes to idoc/man/files/modules/irc/irc.n.
Changes to idoc/man/files/modules/irc/picoirc.n.
Changes to idoc/man/files/modules/javascript/javascript.n.
Changes to idoc/man/files/modules/jpeg/jpeg.n.
Changes to idoc/man/files/modules/json/json.n.
Changes to idoc/man/files/modules/json/json_write.n.
Changes to idoc/man/files/modules/lambda/lambda.n.
Changes to idoc/man/files/modules/lazyset/lazyset.n.
Changes to idoc/man/files/modules/ldap/ldap.n.
Changes to idoc/man/files/modules/ldap/ldapx.n.
Changes to idoc/man/files/modules/log/log.n.
Changes to idoc/man/files/modules/log/logger.n.
Changes to idoc/man/files/modules/log/loggerAppender.n.
Changes to idoc/man/files/modules/log/loggerUtils.n.
Changes to idoc/man/files/modules/map/map_geocode_nominatim.n.
Changes to idoc/man/files/modules/map/map_slippy.n.
Changes to idoc/man/files/modules/map/map_slippy_cache.n.
Changes to idoc/man/files/modules/map/map_slippy_fetcher.n.
Changes to idoc/man/files/modules/mapproj/mapproj.n.
Changes to idoc/man/files/modules/markdown/markdown.n.
Changes to idoc/man/files/modules/math/bigfloat.n.
Changes to idoc/man/files/modules/math/bignum.n.
Changes to idoc/man/files/modules/math/calculus.n.
Changes to idoc/man/files/modules/math/combinatorics.n.
Changes to idoc/man/files/modules/math/constants.n.
Changes to idoc/man/files/modules/math/decimal.n.
Changes to idoc/man/files/modules/math/exact.n.
Changes to idoc/man/files/modules/math/fourier.n.
Changes to idoc/man/files/modules/math/fuzzy.n.
Changes to idoc/man/files/modules/math/interpolate.n.
Changes to idoc/man/files/modules/math/linalg.n.
Changes to idoc/man/files/modules/math/machineparameters.n.
Changes to idoc/man/files/modules/math/math.n.
Changes to idoc/man/files/modules/math/math_geometry.n.
Changes to idoc/man/files/modules/math/numtheory.n.
Changes to idoc/man/files/modules/math/optimize.n.
Changes to idoc/man/files/modules/math/pca.n.
Changes to idoc/man/files/modules/math/polynomials.n.
Changes to idoc/man/files/modules/math/qcomplex.n.
Changes to idoc/man/files/modules/math/rational_funcs.n.
Changes to idoc/man/files/modules/math/roman.n.
Changes to idoc/man/files/modules/math/romberg.n.
Changes to idoc/man/files/modules/math/special.n.
Changes to idoc/man/files/modules/math/statistics.n.
Changes to idoc/man/files/modules/math/symdiff.n.
Changes to idoc/man/files/modules/math/trig.n.
Changes to idoc/man/files/modules/md4/md4.n.
Changes to idoc/man/files/modules/md5/md5.n.
Changes to idoc/man/files/modules/md5crypt/md5crypt.n.
Changes to idoc/man/files/modules/mime/mime.n.
Changes to idoc/man/files/modules/mime/smtp.n.
Changes to idoc/man/files/modules/multiplexer/multiplexer.n.
Changes to idoc/man/files/modules/namespacex/namespacex.n.
Changes to idoc/man/files/modules/ncgi/ncgi.n.
Changes to idoc/man/files/modules/nettool/nettool.n.
Changes to idoc/man/files/modules/nmea/nmea.n.
Changes to idoc/man/files/modules/nns/nns_auto.n.
Changes to idoc/man/files/modules/nns/nns_client.n.
Changes to idoc/man/files/modules/nns/nns_common.n.
Changes to idoc/man/files/modules/nns/nns_intro.n.
Changes to idoc/man/files/modules/nns/nns_protocol.n.
Changes to idoc/man/files/modules/nns/nns_server.n.
Changes to idoc/man/files/modules/nntp/nntp.n.
Changes to idoc/man/files/modules/ntp/ntp_time.n.
Changes to idoc/man/files/modules/oauth/oauth.n.
Changes to idoc/man/files/modules/oometa/oometa.n.
Changes to idoc/man/files/modules/ooutil/ooutil.n.
Changes to idoc/man/files/modules/otp/otp.n.
Changes to idoc/man/files/modules/page/page_intro.n.
Changes to idoc/man/files/modules/page/page_pluginmgr.n.
Changes to idoc/man/files/modules/page/page_util_flow.n.
Changes to idoc/man/files/modules/page/page_util_norm_lemon.n.
Changes to idoc/man/files/modules/page/page_util_norm_peg.n.
Changes to idoc/man/files/modules/page/page_util_peg.n.
Changes to idoc/man/files/modules/page/page_util_quote.n.
Changes to idoc/man/files/modules/pki/pki.n.
Changes to idoc/man/files/modules/pluginmgr/pluginmgr.n.
Changes to idoc/man/files/modules/png/png.n.
Changes to idoc/man/files/modules/pop3/pop3.n.
Changes to idoc/man/files/modules/pop3d/pop3d.n.
Changes to idoc/man/files/modules/pop3d/pop3d_dbox.n.
Changes to idoc/man/files/modules/pop3d/pop3d_udb.n.
Changes to idoc/man/files/modules/practcl/practcl.n.
Changes to idoc/man/files/modules/processman/processman.n.
Changes to idoc/man/files/modules/profiler/profiler.n.
Changes to idoc/man/files/modules/pt/pt_astree.n.
Changes to idoc/man/files/modules/pt/pt_cparam_config_critcl.n.
Changes to idoc/man/files/modules/pt/pt_cparam_config_tea.n.
Changes to idoc/man/files/modules/pt/pt_from_api.n.
Changes to idoc/man/files/modules/pt/pt_introduction.n.
Changes to idoc/man/files/modules/pt/pt_json_language.n.
Changes to idoc/man/files/modules/pt/pt_param.n.
Changes to idoc/man/files/modules/pt/pt_parse_peg.n.
Changes to idoc/man/files/modules/pt/pt_parser_api.n.
Changes to idoc/man/files/modules/pt/pt_peg_container.n.
Changes to idoc/man/files/modules/pt/pt_peg_container_peg.n.
Changes to idoc/man/files/modules/pt/pt_peg_export.n.
Changes to idoc/man/files/modules/pt/pt_peg_export_container.n.
Changes to idoc/man/files/modules/pt/pt_peg_export_json.n.
Changes to idoc/man/files/modules/pt/pt_peg_export_peg.n.
Changes to idoc/man/files/modules/pt/pt_peg_from_container.n.
Changes to idoc/man/files/modules/pt/pt_peg_from_json.n.
Changes to idoc/man/files/modules/pt/pt_peg_from_peg.n.
Changes to idoc/man/files/modules/pt/pt_peg_import.n.
Changes to idoc/man/files/modules/pt/pt_peg_import_container.n.
Changes to idoc/man/files/modules/pt/pt_peg_import_json.n.
Changes to idoc/man/files/modules/pt/pt_peg_import_peg.n.
Changes to idoc/man/files/modules/pt/pt_peg_interp.n.
Changes to idoc/man/files/modules/pt/pt_peg_introduction.n.
Changes to idoc/man/files/modules/pt/pt_peg_language.n.
Changes to idoc/man/files/modules/pt/pt_peg_op.n.
Changes to idoc/man/files/modules/pt/pt_peg_to_container.n.
Changes to idoc/man/files/modules/pt/pt_peg_to_cparam.n.
Changes to idoc/man/files/modules/pt/pt_peg_to_json.n.
Changes to idoc/man/files/modules/pt/pt_peg_to_param.n.
Changes to idoc/man/files/modules/pt/pt_peg_to_peg.n.
Changes to idoc/man/files/modules/pt/pt_peg_to_tclparam.n.
Changes to idoc/man/files/modules/pt/pt_pegrammar.n.
Changes to idoc/man/files/modules/pt/pt_pexpr_op.n.
Changes to idoc/man/files/modules/pt/pt_pexpression.n.
Changes to idoc/man/files/modules/pt/pt_pgen.n.
Changes to idoc/man/files/modules/pt/pt_rdengine.n.
Changes to idoc/man/files/modules/pt/pt_tclparam_config_nx.n.
Changes to idoc/man/files/modules/pt/pt_tclparam_config_snit.n.
Changes to idoc/man/files/modules/pt/pt_tclparam_config_tcloo.n.
Changes to idoc/man/files/modules/pt/pt_to_api.n.
Changes to idoc/man/files/modules/pt/pt_util.n.
Changes to idoc/man/files/modules/rc4/rc4.n.
Changes to idoc/man/files/modules/rcs/rcs.n.
Changes to idoc/man/files/modules/report/report.n.
Changes to idoc/man/files/modules/rest/rest.n.
Changes to idoc/man/files/modules/ripemd/ripemd128.n.
Changes to idoc/man/files/modules/ripemd/ripemd160.n.
Changes to idoc/man/files/modules/sasl/gtoken.n.
Changes to idoc/man/files/modules/sasl/ntlm.n.
Changes to idoc/man/files/modules/sasl/sasl.n.
Changes to idoc/man/files/modules/sasl/scram.n.
Changes to idoc/man/files/modules/sha1/sha1.n.
Changes to idoc/man/files/modules/sha1/sha256.n.
Changes to idoc/man/files/modules/simulation/annealing.n.
Changes to idoc/man/files/modules/simulation/montecarlo.n.
Changes to idoc/man/files/modules/simulation/simulation_random.n.
Changes to idoc/man/files/modules/smtpd/smtpd.n.
Changes to idoc/man/files/modules/snit/snit.n.
Changes to idoc/man/files/modules/snit/snitfaq.n.
Changes to idoc/man/files/modules/soundex/soundex.n.
Changes to idoc/man/files/modules/stooop/stooop.n.
Changes to idoc/man/files/modules/stooop/switched.n.
Changes to idoc/man/files/modules/string/token.n.
Changes to idoc/man/files/modules/string/token_shell.n.
Changes to idoc/man/files/modules/stringprep/stringprep.n.
Changes to idoc/man/files/modules/stringprep/stringprep_data.n.
Changes to idoc/man/files/modules/stringprep/unicode.n.
Changes to idoc/man/files/modules/stringprep/unicode_data.n.
Changes to idoc/man/files/modules/struct/disjointset.n.
Changes to idoc/man/files/modules/struct/graph.n.
Changes to idoc/man/files/modules/struct/graph1.n.
Changes to idoc/man/files/modules/struct/graphops.n.
Changes to idoc/man/files/modules/struct/matrix.n.
Changes to idoc/man/files/modules/struct/matrix1.n.
Changes to idoc/man/files/modules/struct/pool.n.
Changes to idoc/man/files/modules/struct/prioqueue.n.
Changes to idoc/man/files/modules/struct/queue.n.
Changes to idoc/man/files/modules/struct/record.n.
Changes to idoc/man/files/modules/struct/skiplist.n.
Changes to idoc/man/files/modules/struct/stack.n.
Changes to idoc/man/files/modules/struct/struct_list.n.
Changes to idoc/man/files/modules/struct/struct_set.n.
Changes to idoc/man/files/modules/struct/struct_tree.n.
Changes to idoc/man/files/modules/struct/struct_tree1.n.
Changes to idoc/man/files/modules/tar/tar.n.
Changes to idoc/man/files/modules/tepam/tepam_argument_dialogbox.n.
Changes to idoc/man/files/modules/tepam/tepam_doc_gen.n.
Changes to idoc/man/files/modules/tepam/tepam_introduction.n.
Changes to idoc/man/files/modules/tepam/tepam_procedure.n.
Changes to idoc/man/files/modules/term/ansi_cattr.n.
Changes to idoc/man/files/modules/term/ansi_cctrl.n.
Changes to idoc/man/files/modules/term/ansi_cmacros.n.
Changes to idoc/man/files/modules/term/ansi_code.n.
Changes to idoc/man/files/modules/term/ansi_ctrlu.n.
Changes to idoc/man/files/modules/term/ansi_send.n.
Changes to idoc/man/files/modules/term/imenu.n.
Changes to idoc/man/files/modules/term/ipager.n.
Changes to idoc/man/files/modules/term/receive.n.
Changes to idoc/man/files/modules/term/term.n.
Changes to idoc/man/files/modules/term/term_bind.n.
Changes to idoc/man/files/modules/term/term_send.n.
Changes to idoc/man/files/modules/textutil/adjust.n.
Changes to idoc/man/files/modules/textutil/expander.n.
Changes to idoc/man/files/modules/textutil/repeat.n.
Changes to idoc/man/files/modules/textutil/tabify.n.
Changes to idoc/man/files/modules/textutil/textutil.n.
Changes to idoc/man/files/modules/textutil/textutil_split.n.
Changes to idoc/man/files/modules/textutil/textutil_string.n.
Changes to idoc/man/files/modules/textutil/trim.n.
Changes to idoc/man/files/modules/tie/tie.n.
Changes to idoc/man/files/modules/tie/tie_std.n.
Changes to idoc/man/files/modules/tiff/tiff.n.
Changes to idoc/man/files/modules/tool/meta.n.
Changes to idoc/man/files/modules/tool/tool.n.
Changes to idoc/man/files/modules/tool/tool_dict_ensemble.n.
Changes to idoc/man/files/modules/transfer/connect.n.
Changes to idoc/man/files/modules/transfer/copyops.n.
Changes to idoc/man/files/modules/transfer/ddest.n.
Changes to idoc/man/files/modules/transfer/dsource.n.
Changes to idoc/man/files/modules/transfer/receiver.n.
Changes to idoc/man/files/modules/transfer/tqueue.n.
Changes to idoc/man/files/modules/transfer/transmitter.n.
Changes to idoc/man/files/modules/treeql/treeql.n.
Changes to idoc/man/files/modules/try/tcllib_throw.n.
Changes to idoc/man/files/modules/try/tcllib_try.n.
Changes to idoc/man/files/modules/udpcluster/udpcluster.n.
Changes to idoc/man/files/modules/uev/uevent.n.
Changes to idoc/man/files/modules/uev/uevent_onidle.n.
Changes to idoc/man/files/modules/units/units.n.
Changes to idoc/man/files/modules/uri/uri.n.
Changes to idoc/man/files/modules/uri/urn-scheme.n.
Changes to idoc/man/files/modules/uuid/uuid.n.
Changes to idoc/man/files/modules/valtype/cc_amex.n.
Changes to idoc/man/files/modules/valtype/cc_discover.n.
Changes to idoc/man/files/modules/valtype/cc_mastercard.n.
Changes to idoc/man/files/modules/valtype/cc_visa.n.
Changes to idoc/man/files/modules/valtype/ean13.n.
Changes to idoc/man/files/modules/valtype/iban.n.
Changes to idoc/man/files/modules/valtype/imei.n.
Changes to idoc/man/files/modules/valtype/isbn.n.
Changes to idoc/man/files/modules/valtype/luhn.n.
Changes to idoc/man/files/modules/valtype/luhn5.n.
Changes to idoc/man/files/modules/valtype/usnpi.n.
Changes to idoc/man/files/modules/valtype/valtype_common.n.
Changes to idoc/man/files/modules/valtype/verhoeff.n.
Changes to idoc/man/files/modules/virtchannel_base/cat.n.
Changes to idoc/man/files/modules/virtchannel_base/facade.n.
Changes to idoc/man/files/modules/virtchannel_base/halfpipe.n.
Changes to idoc/man/files/modules/virtchannel_base/nullzero.n.
Changes to idoc/man/files/modules/virtchannel_base/randseed.n.
Changes to idoc/man/files/modules/virtchannel_base/std.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_fifo.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_fifo2.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_memchan.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_null.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_random.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_string.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_variable.n.
Changes to idoc/man/files/modules/virtchannel_base/tcllib_zero.n.
Changes to idoc/man/files/modules/virtchannel_base/textwindow.n.
Changes to idoc/man/files/modules/virtchannel_core/core.n.
Changes to idoc/man/files/modules/virtchannel_core/events.n.
Changes to idoc/man/files/modules/virtchannel_core/transformcore.n.
Changes to idoc/man/files/modules/virtchannel_transform/adler32.n.
Changes to idoc/man/files/modules/virtchannel_transform/hex.n.
Changes to idoc/man/files/modules/virtchannel_transform/identity.n.
Changes to idoc/man/files/modules/virtchannel_transform/limitsize.n.
Changes to idoc/man/files/modules/virtchannel_transform/observe.n.
Changes to idoc/man/files/modules/virtchannel_transform/rot.n.
Changes to idoc/man/files/modules/virtchannel_transform/spacer.n.
Changes to idoc/man/files/modules/virtchannel_transform/tcllib_zlib.n.
Changes to idoc/man/files/modules/virtchannel_transform/vt_base64.n.
Changes to idoc/man/files/modules/virtchannel_transform/vt_counter.n.
Changes to idoc/man/files/modules/virtchannel_transform/vt_crc32.n.
Changes to idoc/man/files/modules/virtchannel_transform/vt_otp.n.
Changes to idoc/man/files/modules/websocket/websocket.n.
Changes to idoc/man/files/modules/wip/wip.n.
Changes to idoc/man/files/modules/yaml/huddle.n.
Changes to idoc/man/files/modules/yaml/yaml.n.
Changes to idoc/man/files/modules/zip/decode.n.
Changes to idoc/man/files/modules/zip/encode.n.
Changes to idoc/man/files/modules/zip/mkzip.n.
Changes to idoc/man/index.n.
| ︙ | | | ︙ | |
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
|
.de MT
.QW ""
..
.BS
.SH INDEX
tcllib
.RS
3DES
.RS
.TP
\fBfiles/modules/des/des\&.n\fR
des
.TP
\fBfiles/modules/des/tcldes\&.n\fR
tclDES
.TP
\fBfiles/modules/des/tcldesjr\&.n\fR
tclDESjr
.RE
abstract syntax tree
.RS
.TP
\fBfiles/modules/grammar_me/me_util\&.n\fR
grammar::me::util
.TP
\fBfiles/modules/grammar_me/me_ast\&.n\fR
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
|
.de MT
.QW ""
..
.BS
.SH INDEX
tcllib
.RS
\&.ddt
.RS
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.RE
\&.dtx
.RS
.TP
\fBfiles/modules/docstrip/docstrip\&.n\fR
docstrip
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
/dev/null
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_null\&.n\fR
tcl::chan::null
.TP
\fBfiles/modules/virtchannel_base/nullzero\&.n\fR
tcl::chan::nullzero
.RE
/dev/random
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_random\&.n\fR
tcl::chan::random
.TP
\fBfiles/modules/virtchannel_base/randseed\&.n\fR
tcl::randomseed
.RE
/dev/zero
.RS
.TP
\fBfiles/modules/virtchannel_base/nullzero\&.n\fR
tcl::chan::nullzero
.TP
\fBfiles/modules/virtchannel_base/tcllib_zero\&.n\fR
tcl::chan::zero
.RE
3DES
.RS
.TP
\fBfiles/modules/des/des\&.n\fR
des
.TP
\fBfiles/modules/des/tcldes\&.n\fR
tclDES
.TP
\fBfiles/modules/des/tcldesjr\&.n\fR
tclDESjr
.RE
AMEX
.RS
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.RE
AST
.RS
.TP
\fBfiles/modules/grammar_me/me_ast\&.n\fR
grammar::me_ast
.RE
American Express
.RS
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.RE
BWidget
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.TP
\fBfiles/modules/snit/snitfaq\&.n\fR
snitfaq
.RE
Bessel functions
.RS
.TP
\fBfiles/modules/math/special\&.n\fR
math::special
.RE
BitTorrent
.RS
.TP
\fBfiles/modules/bee/bee\&.n\fR
bee
.RE
Book Number
.RS
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
C
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_c\&.n\fR
doctools::msgcat::idx::c
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_c\&.n\fR
doctools::msgcat::toc::c
.RE
C++
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.TP
\fBfiles/modules/snit/snitfaq\&.n\fR
snitfaq
.TP
\fBfiles/modules/stooop/stooop\&.n\fR
stooop
.TP
\fBfiles/modules/stooop/switched\&.n\fR
switched
.RE
CFG
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.RE
CFL
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.RE
CGI
.RS
.TP
\fBfiles/modules/ncgi/ncgi\&.n\fR
ncgi
.RE
CONTAINER
.RS
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.RE
CPARAM
.RS
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.RE
CSS
.RS
.TP
\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR
doctools::html::cssdefaults
.RE
CVS
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
Checking
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
Cost
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
DE
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_de\&.n\fR
doctools::msgcat::idx::de
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_de\&.n\fR
doctools::msgcat::toc::de
.RE
DES
.RS
.TP
\fBfiles/modules/des/des\&.n\fR
des
.TP
\fBfiles/modules/des/tcldes\&.n\fR
tclDES
.TP
\fBfiles/modules/des/tcldesjr\&.n\fR
tclDESjr
.RE
DNS
.RS
.TP
\fBfiles/modules/dns/tcllib_dns\&.n\fR
dns
.RE
DOM
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
Discover
.RS
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.RE
EAN
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
EAN13
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
EBNF
.RS
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
EN
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_en\&.n\fR
doctools::msgcat::idx::en
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_en\&.n\fR
doctools::msgcat::toc::en
.RE
European Article Number
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
FFT
.RS
.TP
\fBfiles/modules/math/fourier\&.n\fR
math::fourier
.RE
FIPS 180-1
.RS
.TP
\fBfiles/modules/sha1/sha1\&.n\fR
sha1
.TP
\fBfiles/modules/sha1/sha256\&.n\fR
sha256
.RE
FR
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_fr\&.n\fR
doctools::msgcat::idx::fr
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR
doctools::msgcat::toc::fr
.RE
Fisher-Yates
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
Fourier transform
.RS
.TP
\fBfiles/modules/math/fourier\&.n\fR
math::fourier
.RE
GUID
.RS
.TP
\fBfiles/modules/uuid/uuid\&.n\fR
uuid
.RE
HTML
.RS
.TP
\fBfiles/modules/doctools/doctools\&.n\fR
doctools
.TP
\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR
doctools::html::cssdefaults
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/docidx\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools2idx/idx_export\&.n\fR
doctools::idx::export
.TP
\fBfiles/modules/doctools2idx/idx_export_html\&.n\fR
doctools::idx::export::html
.TP
\fBfiles/modules/doctools/doctoc\&.n\fR
doctools::toc
.TP
\fBfiles/modules/doctools2toc/toc_container\&.n\fR
doctools::toc
.TP
\fBfiles/modules/doctools2toc/toc_export\&.n\fR
doctools::toc::export
.TP
\fBfiles/modules/doctools2toc/toc_export_html\&.n\fR
doctools::toc::export::html
.TP
\fBfiles/apps/dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.RE
IBAN
.RS
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.RE
IMEI
.RS
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.RE
ISBN
.RS
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
Incr Tcl
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.TP
\fBfiles/modules/snit/snitfaq\&.n\fR
snitfaq
.RE
International Article Number
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
International Bank Account Number
.RS
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.RE
International Mobile Equipment Identity
.RS
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.RE
International Standard Book Number
.RS
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
JSON
.RS
.TP
\fBfiles/modules/doctools2idx/idx_export_json\&.n\fR
doctools::idx::export::json
.TP
\fBfiles/modules/doctools2idx/idx_import_json\&.n\fR
doctools::idx::import::json
.TP
\fBfiles/modules/doctools2toc/toc_export_json\&.n\fR
doctools::toc::export::json
.TP
\fBfiles/modules/doctools2toc/toc_import_json\&.n\fR
doctools::toc::import::json
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.RE
LL(k)
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.TP
\fBfiles/modules/grammar_peg/peg\&.n\fR
grammar::peg
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
grammar::peg::interp
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
LaTeX
.RS
.TP
\fBfiles/modules/docstrip/docstrip\&.n\fR
docstrip
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
MasterCard
.RS
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.RE
NPI
.RS
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.RE
NTLM
.RS
.TP
\fBfiles/modules/sasl/ntlm\&.n\fR
SASL::NTLM
.RE
NTP
.RS
.TP
\fBfiles/modules/ntp/ntp_time\&.n\fR
ntp_time
.RE
National Provider Identifier
.RS
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.RE
PARAM
.RS
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.RE
PCA
.RS
.TP
\fBfiles/modules/math/pca\&.n\fR
math::PCA
.RE
PEG
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.TP
\fBfiles/modules/page/page_util_norm_peg\&.n\fR
page_util_norm_peg
.TP
\fBfiles/modules/page/page_util_peg\&.n\fR
page_util_peg
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
RCS
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
RCS patch
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
RFC 2718
.RS
.TP
\fBfiles/modules/oauth/oauth\&.n\fR
oauth
.RE
RFC 5849
.RS
.TP
\fBfiles/modules/oauth/oauth\&.n\fR
oauth
.RE
RIPEMD
.RS
.TP
\fBfiles/modules/ripemd/ripemd128\&.n\fR
ripemd128
.TP
\fBfiles/modules/ripemd/ripemd160\&.n\fR
ripemd160
.RE
SASL
.RS
.TP
\fBfiles/modules/sasl/sasl\&.n\fR
SASL
.TP
\fBfiles/modules/sasl/ntlm\&.n\fR
SASL::NTLM
.TP
\fBfiles/modules/sasl/scram\&.n\fR
SASL::SCRAM
.TP
\fBfiles/modules/sasl/gtoken\&.n\fR
SASL::XGoogleToken
.RE
SCCS
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
SCRAM
.RS
.TP
\fBfiles/modules/sasl/scram\&.n\fR
SASL::SCRAM
.RE
SNTP
.RS
.TP
\fBfiles/modules/ntp/ntp_time\&.n\fR
ntp_time
.RE
Snit
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.RE
TCLPARAM
.RS
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.RE
TDPL
.RS
.TP
\fBfiles/modules/grammar_peg/peg\&.n\fR
grammar::peg
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
grammar::peg::interp
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
TMML
.RS
.TP
\fBfiles/modules/doctools/doctools\&.n\fR
doctools
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/docidx\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/doctoc\&.n\fR
doctools::toc
.TP
\fBfiles/modules/doctools2toc/toc_container\&.n\fR
doctools::toc
.TP
\fBfiles/apps/dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.RE
TOOL
.RS
.TP
\fBfiles/modules/oometa/oometa\&.n\fR
oometa
.TP
\fBfiles/modules/tool/tool\&.n\fR
tool
.TP
\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR
tool::dict_ensemble
.RE
TPDL
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.RE
Tcl module
.RS
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.RE
Tcl syntax
.RS
.TP
\fBfiles/modules/doctools2base/tcl_parse\&.n\fR
doctools::tcl::parse
.RE
TclOO
.RS
.TP
\fBfiles/modules/tool/meta\&.n\fR
oo::util
.TP
\fBfiles/modules/ooutil/ooutil\&.n\fR
oo::util
.TP
\fBfiles/modules/oometa/oometa\&.n\fR
oometa
.TP
\fBfiles/modules/tool/tool\&.n\fR
tool
.TP
\fBfiles/modules/httpd/httpd\&.n\fR
tool
.TP
\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR
tool::dict_ensemble
.RE
TeX
.RS
.TP
\fBfiles/modules/textutil/textutil\&.n\fR
textutil
.TP
\fBfiles/modules/textutil/adjust\&.n\fR
textutil::adjust
.RE
Testing
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
Tk
.RS
.TP
\fBfiles/modules/virtchannel_base/textwindow\&.n\fR
tcl::chan::textwindow
.RE
TreeQL
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
Type checking
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
US-NPI
.RS
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.RE
UUID
.RS
.TP
\fBfiles/modules/uuid/uuid\&.n\fR
uuid
.RE
VISA
.RS
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.RE
Validation
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
Value checking
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
WWW
.RS
.TP
\fBfiles/modules/httpd/httpd\&.n\fR
tool
.RE
XGoogleToken
.RS
.TP
\fBfiles/modules/sasl/gtoken\&.n\fR
SASL::XGoogleToken
.RE
XPath
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
XSLT
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
abstract syntax tree
.RS
.TP
\fBfiles/modules/grammar_me/me_util\&.n\fR
grammar::me::util
.TP
\fBfiles/modules/grammar_me/me_ast\&.n\fR
|
| ︙ | | | ︙ | |
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
|
.RE
ambiguous
.RS
.TP
\fBfiles/modules/grammar_aycock/aycock\&.n\fR
grammar::aycock
.RE
American Express
.RS
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.RE
AMEX
.RS
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
|
.RE
ambiguous
.RS
.TP
\fBfiles/modules/grammar_aycock/aycock\&.n\fR
grammar::aycock
.RE
angle
.RS
.TP
\fBfiles/modules/math/math_geometry\&.n\fR
math::geometry
.TP
\fBfiles/modules/units/units\&.n\fR
|
| ︙ | | | ︙ | |
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
|
.RE
assign
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
AST
.RS
.TP
\fBfiles/modules/grammar_me/me_ast\&.n\fR
grammar::me_ast
.RE
|
<
<
<
<
<
<
|
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
|
.RE
assign
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
asynchronous
.RS
.TP
\fBfiles/modules/cache/async\&.n\fR
cache::async
.RE
attribute control
|
| ︙ | | | ︙ | |
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
|
.RE
ber
.RS
.TP
\fBfiles/modules/asn/asn\&.n\fR
asn
.RE
Bessel functions
.RS
.TP
\fBfiles/modules/math/special\&.n\fR
math::special
.RE
|
<
<
<
<
<
<
|
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
|
.RE
ber
.RS
.TP
\fBfiles/modules/asn/asn\&.n\fR
asn
.RE
bfs
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
bibliography
|
| ︙ | | | ︙ | |
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
|
uevent
.RE
bipartite
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
BitTorrent
.RS
.TP
\fBfiles/modules/bee/bee\&.n\fR
bee
|
<
<
<
<
<
<
|
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
|
uevent
.RE
bipartite
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
bittorrent
.RS
.TP
\fBfiles/modules/bee/bee\&.n\fR
bee
.RE
|
| ︙ | | | ︙ | |
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
|
.RE
blowfish
.RS
.TP
\fBfiles/modules/blowfish/blowfish\&.n\fR
blowfish
.RE
Book Number
.RS
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
BWidget
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.TP
\fBfiles/modules/snit/snitfaq\&.n\fR
snitfaq
.RE
C
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_c\&.n\fR
doctools::msgcat::idx::c
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_c\&.n\fR
doctools::msgcat::toc::c
.RE
C++
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.TP
\fBfiles/modules/snit/snitfaq\&.n\fR
snitfaq
.TP
\fBfiles/modules/stooop/stooop\&.n\fR
stooop
.TP
\fBfiles/modules/stooop/switched\&.n\fR
switched
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
|
.RE
blowfish
.RS
.TP
\fBfiles/modules/blowfish/blowfish\&.n\fR
blowfish
.RE
breadth-first
.RS
.TP
\fBfiles/modules/struct/struct_tree\&.n\fR
struct::tree
.RE
bridge
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
cache
.RS
.TP
\fBfiles/modules/cache/async\&.n\fR
cache::async
.TP
\fBfiles/modules/map/map_slippy_cache\&.n\fR
|
| ︙ | | | ︙ | |
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
|
.RE
cer
.RS
.TP
\fBfiles/modules/asn/asn\&.n\fR
asn
.RE
CFG
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.RE
CFL
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.RE
CGI
.RS
.TP
\fBfiles/modules/ncgi/ncgi\&.n\fR
ncgi
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
|
.RE
cer
.RS
.TP
\fBfiles/modules/asn/asn\&.n\fR
asn
.RE
cgraph
.RS
.TP
\fBfiles/modules/struct/graph\&.n\fR
struct::graph
.TP
\fBfiles/modules/struct/graph1\&.n\fR
|
| ︙ | | | ︙ | |
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
|
.RE
checkbutton
.RS
.TP
\fBfiles/modules/html/html\&.n\fR
html
.RE
Checking
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
|
.RE
checkbutton
.RS
.TP
\fBfiles/modules/html/html\&.n\fR
html
.RE
checksum
.RS
.TP
\fBfiles/modules/crc/cksum\&.n\fR
cksum
.TP
\fBfiles/modules/crc/crc16\&.n\fR
|
| ︙ | | | ︙ | |
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
|
.TP
\fBfiles/modules/math/constants\&.n\fR
math::constants
.TP
\fBfiles/modules/units/units\&.n\fR
units
.RE
CONTAINER
.RS
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.RE
|
<
<
<
<
<
<
<
<
<
|
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
|
.TP
\fBfiles/modules/math/constants\&.n\fR
math::constants
.TP
\fBfiles/modules/units/units\&.n\fR
units
.RE
contents
.RS
.TP
\fBfiles/modules/doctools2toc/toc_introduction\&.n\fR
doctools2toc_introduction
.RE
context-free grammar
|
| ︙ | | | ︙ | |
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
|
.TP
\fBfiles/modules/coroutine/coro_auto\&.n\fR
coroutine::auto
.TP
\fBfiles/modules/generator/generator\&.n\fR
generator
.RE
Cost
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
CPARAM
.RS
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
|
.TP
\fBfiles/modules/coroutine/coro_auto\&.n\fR
coroutine::auto
.TP
\fBfiles/modules/generator/generator\&.n\fR
generator
.RE
counter
.RS
.TP
\fBfiles/modules/virtchannel_transform/vt_counter\&.n\fR
tcl::transform::counter
.RE
counting
.RS
.TP
\fBfiles/modules/counter/counter\&.n\fR
counter
.RE
crc
.RS
.TP
\fBfiles/modules/crc/cksum\&.n\fR
cksum
.TP
\fBfiles/modules/crc/crc16\&.n\fR
|
| ︙ | | | ︙ | |
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
|
.RE
cryptography
.RS
.TP
\fBfiles/modules/blowfish/blowfish\&.n\fR
blowfish
.RE
CSS
.RS
.TP
\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR
doctools::html::cssdefaults
.RE
|
<
<
<
<
<
<
|
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
|
.RE
cryptography
.RS
.TP
\fBfiles/modules/blowfish/blowfish\&.n\fR
blowfish
.RE
csv
.RS
.TP
\fBfiles/modules/bench/bench_read\&.n\fR
bench::in
.TP
\fBfiles/modules/bench/bench_wcsv\&.n\fR
|
| ︙ | | | ︙ | |
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
|
struct::graph::op
.RE
cut vertex
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
CVS
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
|
<
<
<
<
<
<
|
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
|
struct::graph::op
.RE
cut vertex
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
cvs
.RS
.TP
\fBfiles/modules/doctools/cvs\&.n\fR
doctools::cvs
.RE
|
| ︙ | | | ︙ | |
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
|
.RE
dataflow
.RS
.TP
\fBfiles/modules/page/page_util_flow\&.n\fR
page_util_flow
.RE
\&.ddt
.RS
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.RE
DE
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_de\&.n\fR
doctools::msgcat::idx::de
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_de\&.n\fR
doctools::msgcat::toc::de
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
|
.RE
dataflow
.RS
.TP
\fBfiles/modules/page/page_util_flow\&.n\fR
page_util_flow
.RE
debug
.RS
.TP
\fBfiles/modules/debug/debug\&.n\fR
debug
.TP
\fBfiles/modules/debug/debug_caller\&.n\fR
|
| ︙ | | | ︙ | |
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
|
.RE
der
.RS
.TP
\fBfiles/modules/asn/asn\&.n\fR
asn
.RE
DES
.RS
.TP
\fBfiles/modules/des/des\&.n\fR
des
.TP
\fBfiles/modules/des/tcldes\&.n\fR
tclDES
.TP
\fBfiles/modules/des/tcldesjr\&.n\fR
tclDESjr
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
|
.RE
der
.RS
.TP
\fBfiles/modules/asn/asn\&.n\fR
asn
.RE
deserialization
.RS
.TP
\fBfiles/modules/doctools2idx/import_docidx\&.n\fR
doctools::idx::import::docidx
.TP
\fBfiles/modules/doctools2idx/idx_import_json\&.n\fR
|
| ︙ | | | ︙ | |
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
|
.TP
\fBfiles/modules/doctools2toc/toc_import_json\&.n\fR
doctools::toc::import::json
.TP
\fBfiles/modules/doctools2toc/toc_structure\&.n\fR
doctools::toc::structure
.RE
/dev/null
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_null\&.n\fR
tcl::chan::null
.TP
\fBfiles/modules/virtchannel_base/nullzero\&.n\fR
tcl::chan::nullzero
.RE
/dev/random
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_random\&.n\fR
tcl::chan::random
.TP
\fBfiles/modules/virtchannel_base/randseed\&.n\fR
tcl::randomseed
.RE
/dev/zero
.RS
.TP
\fBfiles/modules/virtchannel_base/nullzero\&.n\fR
tcl::chan::nullzero
.TP
\fBfiles/modules/virtchannel_base/tcllib_zero\&.n\fR
tcl::chan::zero
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
|
.TP
\fBfiles/modules/doctools2toc/toc_import_json\&.n\fR
doctools::toc::import::json
.TP
\fBfiles/modules/doctools2toc/toc_structure\&.n\fR
doctools::toc::structure
.RE
diameter
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
dict
|
| ︙ | | | ︙ | |
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
|
.RE
directory traversal
.RS
.TP
\fBfiles/modules/fileutil/traverse\&.n\fR
fileutil_traverse
.RE
Discover
.RS
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.RE
|
<
<
<
<
<
<
|
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
|
.RE
directory traversal
.RS
.TP
\fBfiles/modules/fileutil/traverse\&.n\fR
fileutil_traverse
.RE
discrete items
.RS
.TP
\fBfiles/modules/struct/pool\&.n\fR
struct::pool
.RE
disjoint set
|
| ︙ | | | ︙ | |
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
|
math::geometry
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.TP
\fBfiles/modules/units/units\&.n\fR
units
.RE
DNS
.RS
.TP
\fBfiles/modules/dns/tcllib_dns\&.n\fR
dns
|
<
<
<
<
<
<
|
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
|
math::geometry
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.TP
\fBfiles/modules/units/units\&.n\fR
units
.RE
do
.RS
.TP
\fBfiles/modules/control/control\&.n\fR
control
.RE
|
| ︙ | | | ︙ | |
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
|
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.TP
\fBfiles/modules/tepam/tepam_doc_gen\&.n\fR
tepam::doc_gen
.RE
DOM
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
\&.dtx
.RS
.TP
\fBfiles/modules/docstrip/docstrip\&.n\fR
docstrip
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
EAN
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
EAN13
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
EBNF
.RS
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
|
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.TP
\fBfiles/modules/tepam/tepam_doc_gen\&.n\fR
tepam::doc_gen
.RE
dom
.RS
.TP
\fBfiles/modules/amazon-s3/xsxp\&.n\fR
xsxp
.RE
domain name service
.RS
.TP
\fBfiles/modules/dns/tcllib_dns\&.n\fR
dns
.RE
e
.RS
.TP
\fBfiles/modules/math/constants\&.n\fR
math::constants
.RE
earley
.RS
.TP
\fBfiles/modules/grammar_aycock/aycock\&.n\fR
grammar::aycock
.RE
eccentricity
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
edge
|
| ︙ | | | ︙ | |
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
|
.RE
empty interpreter
.RS
.TP
\fBfiles/modules/interp/tcllib_interp\&.n\fR
interp
.RE
EN
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_en\&.n\fR
doctools::msgcat::idx::en
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_en\&.n\fR
doctools::msgcat::toc::en
.RE
|
<
<
<
<
<
<
<
<
<
|
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
|
.RE
empty interpreter
.RS
.TP
\fBfiles/modules/interp/tcllib_interp\&.n\fR
interp
.RE
encoding
.RS
.TP
\fBfiles/modules/base64/ascii85\&.n\fR
ascii85
.TP
\fBfiles/modules/base64/base64\&.n\fR
|
| ︙ | | | ︙ | |
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
|
.RE
error function
.RS
.TP
\fBfiles/modules/math/special\&.n\fR
math::special
.RE
European Article Number
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
|
<
<
<
<
<
<
<
<
<
|
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
|
.RE
error function
.RS
.TP
\fBfiles/modules/math/special\&.n\fR
math::special
.RE
event
.RS
.TP
\fBfiles/modules/hook/hook\&.n\fR
hook
.TP
\fBfiles/modules/uev/uevent\&.n\fR
|
| ︙ | | | ︙ | |
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
|
.RE
fetching information
.RS
.TP
\fBfiles/modules/uri/uri\&.n\fR
uri
.RE
FFT
.RS
.TP
\fBfiles/modules/math/fourier\&.n\fR
math::fourier
.RE
|
<
<
<
<
<
<
|
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
|
.RE
fetching information
.RS
.TP
\fBfiles/modules/uri/uri\&.n\fR
uri
.RE
fifo
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_fifo\&.n\fR
tcl::chan::fifo
.TP
\fBfiles/modules/virtchannel_base/tcllib_fifo2\&.n\fR
|
| ︙ | | | ︙ | |
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
|
.TP
\fBfiles/modules/grammar_fa/dexec\&.n\fR
grammar::fa::dexec
.TP
\fBfiles/modules/grammar_fa/faop\&.n\fR
grammar::fa::op
.RE
FIPS 180-1
.RS
.TP
\fBfiles/modules/sha1/sha1\&.n\fR
sha1
.TP
\fBfiles/modules/sha1/sha256\&.n\fR
sha256
.RE
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
Fisher-Yates
.RS
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
|
.TP
\fBfiles/modules/grammar_fa/dexec\&.n\fR
grammar::fa::dexec
.TP
\fBfiles/modules/grammar_fa/faop\&.n\fR
grammar::fa::op
.RE
first permutation
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
flatten
.RS
.TP
|
| ︙ | | | ︙ | |
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
|
.TP
\fBfiles/modules/doctools/doctoc_plugin_apiref\&.n\fR
doctoc_plugin_apiref
.TP
\fBfiles/modules/doctools/doctools_plugin_apiref\&.n\fR
doctools_plugin_apiref
.RE
Fourier transform
.RS
.TP
\fBfiles/modules/math/fourier\&.n\fR
math::fourier
.RE
FR
.RS
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_fr\&.n\fR
doctools::msgcat::idx::fr
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR
doctools::msgcat::toc::fr
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
|
.TP
\fBfiles/modules/doctools/doctoc_plugin_apiref\&.n\fR
doctoc_plugin_apiref
.TP
\fBfiles/modules/doctools/doctools_plugin_apiref\&.n\fR
doctools_plugin_apiref
.RE
frame
.RS
.TP
\fBfiles/modules/term/ansi_cmacros\&.n\fR
term::ansi::code::macros
.RE
framework
|
| ︙ | | | ︙ | |
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
|
.RE
grep
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
GUID
.RS
.TP
\fBfiles/modules/uuid/uuid\&.n\fR
uuid
.RE
|
<
<
<
<
<
<
|
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
|
.RE
grep
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
hashing
.RS
.TP
\fBfiles/modules/md4/md4\&.n\fR
md4
.TP
\fBfiles/modules/md5/md5\&.n\fR
|
| ︙ | | | ︙ | |
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
|
.RE
horspool
.RS
.TP
\fBfiles/modules/grammar_aycock/aycock\&.n\fR
grammar::aycock
.RE
HTML
.RS
.TP
\fBfiles/modules/doctools/doctools\&.n\fR
doctools
.TP
\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR
doctools::html::cssdefaults
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/docidx\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools2idx/idx_export\&.n\fR
doctools::idx::export
.TP
\fBfiles/modules/doctools2idx/idx_export_html\&.n\fR
doctools::idx::export::html
.TP
\fBfiles/modules/doctools/doctoc\&.n\fR
doctools::toc
.TP
\fBfiles/modules/doctools2toc/toc_container\&.n\fR
doctools::toc
.TP
\fBfiles/modules/doctools2toc/toc_export\&.n\fR
doctools::toc::export
.TP
\fBfiles/modules/doctools2toc/toc_export_html\&.n\fR
doctools::toc::export::html
.TP
\fBfiles/apps/dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
|
.RE
horspool
.RS
.TP
\fBfiles/modules/grammar_aycock/aycock\&.n\fR
grammar::aycock
.RE
html
.RS
.TP
\fBfiles/modules/html/html\&.n\fR
html
.TP
\fBfiles/modules/htmlparse/htmlparse\&.n\fR
|
| ︙ | | | ︙ | |
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
|
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_en\&.n\fR
doctools::msgcat::toc::en
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR
doctools::msgcat::toc::fr
.RE
IBAN
.RS
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.RE
|
<
<
<
<
<
<
|
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
|
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_en\&.n\fR
doctools::msgcat::toc::en
.TP
\fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR
doctools::msgcat::toc::fr
.RE
ident
.RS
.TP
\fBfiles/modules/ident/ident\&.n\fR
ident
.RE
identification
|
| ︙ | | | ︙ | |
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
|
.RE
imap
.RS
.TP
\fBfiles/modules/imap4/imap4\&.n\fR
imap4
.RE
IMEI
.RS
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.RE
|
<
<
<
<
<
<
|
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
|
.RE
imap
.RS
.TP
\fBfiles/modules/imap4/imap4\&.n\fR
imap4
.RE
import
.RS
.TP
\fBfiles/modules/doctools2idx/idx_import\&.n\fR
doctools::idx::import
.TP
\fBfiles/modules/doctools2idx/import_docidx\&.n\fR
|
| ︙ | | | ︙ | |
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
|
.RE
inclusion
.RS
.TP
\fBfiles/modules/struct/struct_set\&.n\fR
struct::set
.RE
Incr Tcl
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.TP
\fBfiles/modules/snit/snitfaq\&.n\fR
snitfaq
.RE
|
<
<
<
<
<
<
<
<
<
|
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
|
.RE
inclusion
.RS
.TP
\fBfiles/modules/struct/struct_set\&.n\fR
struct::set
.RE
indenting
.RS
.TP
\fBfiles/modules/textutil/textutil\&.n\fR
textutil
.TP
\fBfiles/modules/textutil/adjust\&.n\fR
|
| ︙ | | | ︙ | |
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
|
.RE
inter-thread communication
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_fifo2\&.n\fR
tcl::chan::fifo2
.RE
International Article Number
.RS
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
International Bank Account Number
.RS
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.RE
International Mobile Equipment Identity
.RS
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.RE
International Standard Book Number
.RS
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
|
.RE
inter-thread communication
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_fifo2\&.n\fR
tcl::chan::fifo2
.RE
internationalization
.RS
.TP
\fBfiles/modules/doctools2base/tcllib_msgcat\&.n\fR
doctools::msgcat
.TP
\fBfiles/modules/doctools2idx/idx_msgcat_c\&.n\fR
|
| ︙ | | | ︙ | |
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
|
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
ISBN
.RS
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.RE
|
<
<
<
<
<
<
|
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
|
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
isthmus
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
iterator
|
| ︙ | | | ︙ | |
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
|
.RE
jpeg
.RS
.TP
\fBfiles/modules/jpeg/jpeg\&.n\fR
jpeg
.RE
JSON
.RS
.TP
\fBfiles/modules/doctools2idx/idx_export_json\&.n\fR
doctools::idx::export::json
.TP
\fBfiles/modules/doctools2idx/idx_import_json\&.n\fR
doctools::idx::import::json
.TP
\fBfiles/modules/doctools2toc/toc_export_json\&.n\fR
doctools::toc::export::json
.TP
\fBfiles/modules/doctools2toc/toc_import_json\&.n\fR
doctools::toc::import::json
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
|
.RE
jpeg
.RS
.TP
\fBfiles/modules/jpeg/jpeg\&.n\fR
jpeg
.RE
json
.RS
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools2idx/idx_export\&.n\fR
|
| ︙ | | | ︙ | |
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
|
.RE
lambda
.RS
.TP
\fBfiles/modules/lambda/lambda\&.n\fR
lambda
.RE
LaTeX
.RS
.TP
\fBfiles/modules/docstrip/docstrip\&.n\fR
docstrip
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
|
.RE
lambda
.RS
.TP
\fBfiles/modules/lambda/lambda\&.n\fR
lambda
.RE
latex
.RS
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/docidx\&.n\fR
|
| ︙ | | | ︙ | |
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
|
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
LL(k)
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.TP
\fBfiles/modules/grammar_peg/peg\&.n\fR
grammar::peg
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
grammar::peg::interp
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
|
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
local searching
.RS
.TP
\fBfiles/modules/struct/graphops\&.n\fR
struct::graph::op
.RE
localization
|
| ︙ | | | ︙ | |
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
|
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
MasterCard
.RS
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.RE
|
<
<
<
<
<
<
|
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
|
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.TP
\fBfiles/apps/tcldocstrip\&.n\fR
tcldocstrip
.RE
matching
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
|
| ︙ | | | ︙ | |
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
|
.TP
\fBfiles/modules/debug/debug_heartbeat\&.n\fR
debug::heartbeat
.TP
\fBfiles/modules/debug/debug_timestamp\&.n\fR
debug::timestamp
.RE
National Provider Identifier
.RS
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.RE
|
<
<
<
<
<
<
|
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
|
.TP
\fBfiles/modules/debug/debug_heartbeat\&.n\fR
debug::heartbeat
.TP
\fBfiles/modules/debug/debug_timestamp\&.n\fR
debug::timestamp
.RE
neighbour
.RS
.TP
\fBfiles/modules/struct/graph\&.n\fR
struct::graph
.TP
\fBfiles/modules/struct/graphops\&.n\fR
|
| ︙ | | | ︙ | |
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
|
.TP
\fBfiles/modules/page/page_util_norm_peg\&.n\fR
page_util_norm_peg
.TP
\fBfiles/modules/stringprep/unicode\&.n\fR
unicode
.RE
NPI
.RS
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.RE
|
<
<
<
<
<
<
|
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
|
.TP
\fBfiles/modules/page/page_util_norm_peg\&.n\fR
page_util_norm_peg
.TP
\fBfiles/modules/stringprep/unicode\&.n\fR
unicode
.RE
nroff
.RS
.TP
\fBfiles/modules/doctools/doctools\&.n\fR
doctools
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
|
| ︙ | | | ︙ | |
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
|
.TP
\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.RE
NTLM
.RS
.TP
\fBfiles/modules/sasl/ntlm\&.n\fR
SASL::NTLM
.RE
NTP
.RS
.TP
\fBfiles/modules/ntp/ntp_time\&.n\fR
ntp_time
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
|
.TP
\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.RE
null
.RS
.TP
\fBfiles/modules/virtchannel_base/tcllib_null\&.n\fR
tcl::chan::null
.TP
\fBfiles/modules/virtchannel_base/nullzero\&.n\fR
|
| ︙ | | | ︙ | |
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
|
.TP
\fBfiles/modules/textutil/textutil\&.n\fR
textutil
.TP
\fBfiles/modules/textutil/adjust\&.n\fR
textutil::adjust
.RE
PARAM
.RS
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.RE
|
<
<
<
<
<
<
|
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
|
.TP
\fBfiles/modules/textutil/textutil\&.n\fR
textutil
.TP
\fBfiles/modules/textutil/adjust\&.n\fR
textutil::adjust
.RE
parameter entry form
.RS
.TP
\fBfiles/modules/tepam/tepam_introduction\&.n\fR
tepam
.TP
\fBfiles/modules/tepam/tepam_argument_dialogbox\&.n\fR
|
| ︙ | | | ︙ | |
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
|
.RE
patching
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
PCA
.RS
.TP
\fBfiles/modules/math/pca\&.n\fR
math::PCA
.RE
PEG
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.TP
\fBfiles/modules/page/page_util_norm_peg\&.n\fR
page_util_norm_peg
.TP
\fBfiles/modules/page/page_util_peg\&.n\fR
page_util_peg
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
7930
7931
7932
7933
7934
7935
7936
7937
7938
7939
7940
7941
7942
7943
|
.RE
patching
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
performance
.RS
.TP
\fBfiles/modules/bench/bench\&.n\fR
bench
.TP
\fBfiles/modules/bench/bench_read\&.n\fR
|
| ︙ | | | ︙ | |
7948
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
|
.RE
rc4
.RS
.TP
\fBfiles/modules/rc4/rc4\&.n\fR
rc4
.RE
RCS
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
RCS patch
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
8473
8474
8475
8476
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
|
.RE
rc4
.RS
.TP
\fBfiles/modules/rc4/rc4\&.n\fR
rc4
.RE
read
.RS
.TP
\fBfiles/modules/coroutine/tcllib_coroutine\&.n\fR
coroutine
.TP
\fBfiles/modules/coroutine/coro_auto\&.n\fR
|
| ︙ | | | ︙ | |
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458
8459
8460
8461
8462
8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
|
.RE
reverse
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
rfc 821
.RS
.TP
\fBfiles/modules/mime/mime\&.n\fR
mime
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.TP
\fBfiles/modules/smtpd/smtpd\&.n\fR
smtpd
.RE
rfc 822
.RS
.TP
\fBfiles/modules/mime/mime\&.n\fR
mime
.TP
\fBfiles/modules/pop3d/pop3d_dbox\&.n\fR
pop3d::dbox
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.RE
rfc 868
.RS
.TP
\fBfiles/modules/ntp/ntp_time\&.n\fR
ntp_time
.RE
rfc 959
.RS
.TP
\fBfiles/modules/ftp/ftp\&.n\fR
ftp
.TP
\fBfiles/modules/ftp/ftp_geturl\&.n\fR
ftp::geturl
.TP
\fBfiles/modules/ftpd/ftpd\&.n\fR
ftpd
.RE
rfc 977
.RS
.TP
\fBfiles/modules/nntp/nntp\&.n\fR
nntp
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
8929
8930
8931
8932
8933
8934
8935
8936
8937
8938
8939
8940
8941
8942
|
.RE
reverse
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
rfc 1034
.RS
.TP
\fBfiles/modules/dns/tcllib_dns\&.n\fR
dns
.RE
rfc 1035
|
| ︙ | | | ︙ | |
8623
8624
8625
8626
8627
8628
8629
8630
8631
8632
8633
8634
8635
8636
8637
8638
8639
8640
8641
8642
|
.RE
rfc 2554
.RS
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.RE
RFC 2718
.RS
.TP
\fBfiles/modules/oauth/oauth\&.n\fR
oauth
.RE
|
<
<
<
<
<
<
|
9088
9089
9090
9091
9092
9093
9094
9095
9096
9097
9098
9099
9100
9101
|
.RE
rfc 2554
.RS
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.RE
rfc 2821
.RS
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.TP
\fBfiles/modules/smtpd/smtpd\&.n\fR
|
| ︙ | | | ︙ | |
8668
8669
8670
8671
8672
8673
8674
8675
8676
8677
8678
8679
8680
8681
8682
8683
8684
8685
8686
8687
8688
8689
8690
8691
8692
8693
8694
8695
8696
8697
8698
|
.RE
rfc 4511
.RS
.TP
\fBfiles/modules/ldap/ldap\&.n\fR
ldap
.RE
RFC 5849
.RS
.TP
\fBfiles/modules/oauth/oauth\&.n\fR
oauth
.RE
|
<
<
<
<
<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
9127
9128
9129
9130
9131
9132
9133
9134
9135
9136
9137
9138
9139
9140
9141
9142
9143
9144
9145
9146
9147
9148
9149
9150
9151
9152
9153
9154
9155
9156
9157
9158
9159
9160
9161
9162
9163
9164
9165
9166
9167
9168
9169
9170
9171
9172
9173
9174
9175
9176
9177
9178
9179
9180
9181
9182
9183
9184
9185
9186
9187
9188
9189
9190
9191
9192
9193
9194
9195
9196
9197
9198
9199
|
.RE
rfc 4511
.RS
.TP
\fBfiles/modules/ldap/ldap\&.n\fR
ldap
.RE
rfc 6455
.RS
.TP
\fBfiles/modules/websocket/websocket\&.n\fR
websocket
.RE
rfc 7858
.RS
.TP
\fBfiles/modules/dns/tcllib_dns\&.n\fR
dns
.RE
rfc 821
.RS
.TP
\fBfiles/modules/mime/mime\&.n\fR
mime
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.TP
\fBfiles/modules/smtpd/smtpd\&.n\fR
smtpd
.RE
rfc 822
.RS
.TP
\fBfiles/modules/mime/mime\&.n\fR
mime
.TP
\fBfiles/modules/pop3d/pop3d_dbox\&.n\fR
pop3d::dbox
.TP
\fBfiles/modules/mime/smtp\&.n\fR
smtp
.RE
rfc 868
.RS
.TP
\fBfiles/modules/ntp/ntp_time\&.n\fR
ntp_time
.RE
rfc 959
.RS
.TP
\fBfiles/modules/ftp/ftp\&.n\fR
ftp
.TP
\fBfiles/modules/ftp/ftp_geturl\&.n\fR
ftp::geturl
.TP
\fBfiles/modules/ftpd/ftpd\&.n\fR
ftpd
.RE
rfc 977
.RS
.TP
\fBfiles/modules/nntp/nntp\&.n\fR
nntp
.RE
rfc3501
.RS
.TP
\fBfiles/modules/imap4/imap4\&.n\fR
imap4
.RE
|
| ︙ | | | ︙ | |
8707
8708
8709
8710
8711
8712
8713
8714
8715
8716
8717
8718
8719
8720
8721
8722
8723
8724
8725
8726
8727
8728
8729
|
.RE
right outer join
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
RIPEMD
.RS
.TP
\fBfiles/modules/ripemd/ripemd128\&.n\fR
ripemd128
.TP
\fBfiles/modules/ripemd/ripemd160\&.n\fR
ripemd160
.RE
|
<
<
<
<
<
<
<
<
<
|
9208
9209
9210
9211
9212
9213
9214
9215
9216
9217
9218
9219
9220
9221
|
.RE
right outer join
.RS
.TP
\fBfiles/modules/struct/struct_list\&.n\fR
struct::list
.RE
roman numeral
.RS
.TP
\fBfiles/modules/math/roman\&.n\fR
math::roman
.RE
roots
|
| ︙ | | | ︙ | |
8779
8780
8781
8782
8783
8784
8785
8786
8787
8788
8789
8790
8791
8792
8793
8794
8795
8796
8797
8798
8799
8800
8801
8802
8803
8804
8805
8806
8807
8808
8809
8810
8811
8812
8813
8814
8815
8816
8817
8818
8819
8820
8821
8822
8823
8824
8825
|
.RE
s3
.RS
.TP
\fBfiles/modules/amazon-s3/S3\&.n\fR
S3
.RE
SASL
.RS
.TP
\fBfiles/modules/sasl/sasl\&.n\fR
SASL
.TP
\fBfiles/modules/sasl/ntlm\&.n\fR
SASL::NTLM
.TP
\fBfiles/modules/sasl/scram\&.n\fR
SASL::SCRAM
.TP
\fBfiles/modules/sasl/gtoken\&.n\fR
SASL::XGoogleToken
.RE
SCCS
.RS
.TP
\fBfiles/modules/rcs/rcs\&.n\fR
rcs
.RE
SCRAM
.RS
.TP
\fBfiles/modules/sasl/scram\&.n\fR
SASL::SCRAM
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
9271
9272
9273
9274
9275
9276
9277
9278
9279
9280
9281
9282
9283
9284
9285
9286
9287
9288
9289
9290
|
.RE
s3
.RS
.TP
\fBfiles/modules/amazon-s3/S3\&.n\fR
S3
.RE
scanl
.RS
.TP
\fBfiles/modules/generator/generator\&.n\fR
generator
.RE
secure
.RS
.TP
\fBfiles/modules/comm/comm\&.n\fR
comm
.TP
\fBfiles/modules/pop3/pop3\&.n\fR
|
| ︙ | | | ︙ | |
9214
9215
9216
9217
9218
9219
9220
9221
9222
9223
9224
9225
9226
9227
9228
9229
9230
9231
9232
9233
9234
9235
9236
9237
9238
9239
9240
9241
9242
9243
9244
9245
9246
9247
9248
|
.RE
smtpd
.RS
.TP
\fBfiles/modules/smtpd/smtpd\&.n\fR
smtpd
.RE
Snit
.RS
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.RE
SNTP
.RS
.TP
\fBfiles/modules/ntp/ntp_time\&.n\fR
ntp_time
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
9679
9680
9681
9682
9683
9684
9685
9686
9687
9688
9689
9690
9691
9692
9693
9694
9695
9696
9697
9698
9699
9700
9701
|
.RE
smtpd
.RS
.TP
\fBfiles/modules/smtpd/smtpd\&.n\fR
smtpd
.RE
snit
.RS
.TP
\fBfiles/modules/interp/deleg_method\&.n\fR
deleg_method
.TP
\fBfiles/modules/interp/tcllib_interp\&.n\fR
interp
.RE
socket
.RS
.TP
\fBfiles/modules/comm/comm\&.n\fR
comm
.TP
\fBfiles/modules/comm/comm_wire\&.n\fR
|
| ︙ | | | ︙ | |
9811
9812
9813
9814
9815
9816
9817
9818
9819
9820
9821
9822
9823
9824
9825
9826
9827
9828
9829
9830
9831
9832
9833
9834
9835
9836
|
.TP
\fBfiles/modules/math/decimal\&.n\fR
math::decimal
.TP
\fBfiles/modules/math/pca\&.n\fR
math::PCA
.RE
Tcl module
.RS
.TP
\fBfiles/modules/docstrip/docstrip_util\&.n\fR
docstrip_util
.RE
Tcl syntax
.RS
.TP
\fBfiles/modules/doctools2base/tcl_parse\&.n\fR
doctools::tcl::parse
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
10264
10265
10266
10267
10268
10269
10270
10271
10272
10273
10274
10275
10276
10277
|
.TP
\fBfiles/modules/math/decimal\&.n\fR
math::decimal
.TP
\fBfiles/modules/math/pca\&.n\fR
math::PCA
.RE
tcler's wiki
.RS
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools2idx/idx_export\&.n\fR
|
| ︙ | | | ︙ | |
9844
9845
9846
9847
9848
9849
9850
9851
9852
9853
9854
9855
9856
9857
9858
9859
9860
9861
9862
9863
9864
9865
9866
9867
9868
9869
9870
9871
9872
9873
9874
9875
9876
9877
9878
9879
9880
9881
9882
9883
9884
9885
9886
9887
9888
9889
9890
9891
9892
9893
9894
9895
9896
9897
9898
9899
9900
9901
9902
9903
9904
9905
9906
9907
9908
9909
9910
9911
9912
9913
9914
9915
9916
9917
9918
9919
9920
9921
9922
9923
9924
9925
9926
9927
9928
9929
9930
9931
9932
9933
9934
9935
9936
9937
9938
9939
9940
9941
9942
9943
9944
9945
9946
9947
9948
9949
9950
9951
9952
9953
9954
9955
9956
9957
9958
9959
9960
9961
9962
9963
9964
9965
9966
9967
9968
9969
9970
9971
9972
9973
9974
9975
9976
9977
9978
9979
9980
9981
9982
9983
9984
9985
9986
9987
9988
9989
9990
9991
9992
9993
9994
9995
9996
9997
9998
9999
10000
10001
10002
10003
10004
10005
10006
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
|
.RE
tcllib
.RS
.TP
\fBfiles/modules/csv/csv\&.n\fR
csv
.RE
TclOO
.RS
.TP
\fBfiles/modules/tool/meta\&.n\fR
oo::util
.TP
\fBfiles/modules/ooutil/ooutil\&.n\fR
oo::util
.TP
\fBfiles/modules/oometa/oometa\&.n\fR
oometa
.TP
\fBfiles/modules/tool/tool\&.n\fR
tool
.TP
\fBfiles/modules/httpd/httpd\&.n\fR
tool
.TP
\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR
tool::dict_ensemble
.RE
TCLPARAM
.RS
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.RE
TDPL
.RS
.TP
\fBfiles/modules/grammar_peg/peg\&.n\fR
grammar::peg
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
grammar::peg::interp
.TP
\fBfiles/apps/pt\&.n\fR
pt
.TP
\fBfiles/modules/pt/pt_astree\&.n\fR
pt::ast
.TP
\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR
pt::cparam::configuration::critcl
.TP
\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR
pt::cparam::configuration::tea
.TP
\fBfiles/modules/pt/pt_json_language\&.n\fR
pt::json_language
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.TP
\fBfiles/modules/pt/pt_pexpression\&.n\fR
pt::pe
.TP
\fBfiles/modules/pt/pt_pexpr_op\&.n\fR
pt::pe::op
.TP
\fBfiles/modules/pt/pt_pegrammar\&.n\fR
pt::peg
.TP
\fBfiles/modules/pt/pt_peg_container\&.n\fR
pt::peg::container
.TP
\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR
pt::peg::container::peg
.TP
\fBfiles/modules/pt/pt_peg_export\&.n\fR
pt::peg::export
.TP
\fBfiles/modules/pt/pt_peg_export_container\&.n\fR
pt::peg::export::container
.TP
\fBfiles/modules/pt/pt_peg_export_json\&.n\fR
pt::peg::export::json
.TP
\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR
pt::peg::export::peg
.TP
\fBfiles/modules/pt/pt_peg_from_container\&.n\fR
pt::peg::from::container
.TP
\fBfiles/modules/pt/pt_peg_from_json\&.n\fR
pt::peg::from::json
.TP
\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR
pt::peg::from::peg
.TP
\fBfiles/modules/pt/pt_peg_import\&.n\fR
pt::peg::import
.TP
\fBfiles/modules/pt/pt_peg_import_container\&.n\fR
pt::peg::import::container
.TP
\fBfiles/modules/pt/pt_peg_import_json\&.n\fR
pt::peg::import::json
.TP
\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR
pt::peg::import::peg
.TP
\fBfiles/modules/pt/pt_peg_interp\&.n\fR
pt::peg::interp
.TP
\fBfiles/modules/pt/pt_peg_to_container\&.n\fR
pt::peg::to::container
.TP
\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR
pt::peg::to::cparam
.TP
\fBfiles/modules/pt/pt_peg_to_json\&.n\fR
pt::peg::to::json
.TP
\fBfiles/modules/pt/pt_peg_to_param\&.n\fR
pt::peg::to::param
.TP
\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR
pt::peg::to::peg
.TP
\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR
pt::peg::to::tclparam
.TP
\fBfiles/modules/pt/pt_peg_language\&.n\fR
pt::peg_language
.TP
\fBfiles/modules/pt/pt_peg_introduction\&.n\fR
pt::pegrammar
.TP
\fBfiles/modules/pt/pt_pgen\&.n\fR
pt::pgen
.TP
\fBfiles/modules/pt/pt_rdengine\&.n\fR
pt::rde
.TP
\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR
pt::tclparam::configuration::nx
.TP
\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR
pt::tclparam::configuration::snit
.TP
\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR
pt::tclparam::configuration::tcloo
.TP
\fBfiles/modules/pt/pt_util\&.n\fR
pt::util
.TP
\fBfiles/modules/pt/pt_to_api\&.n\fR
pt_export_api
.TP
\fBfiles/modules/pt/pt_from_api\&.n\fR
pt_import_api
.TP
\fBfiles/modules/pt/pt_introduction\&.n\fR
pt_introduction
.TP
\fBfiles/modules/pt/pt_parse_peg\&.n\fR
pt_parse_peg
.TP
\fBfiles/modules/pt/pt_parser_api\&.n\fR
pt_parser_api
.TP
\fBfiles/modules/pt/pt_peg_op\&.n\fR
pt_peg_op
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
10285
10286
10287
10288
10289
10290
10291
10292
10293
10294
10295
10296
10297
10298
|
.RE
tcllib
.RS
.TP
\fBfiles/modules/csv/csv\&.n\fR
csv
.RE
temp file
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
template processing
|
| ︙ | | | ︙ | |
10066
10067
10068
10069
10070
10071
10072
10073
10074
10075
10076
10077
10078
10079
10080
10081
10082
10083
10084
10085
10086
10087
10088
10089
10090
10091
10092
10093
10094
10095
10096
10097
10098
10099
10100
10101
10102
10103
10104
10105
10106
10107
10108
10109
10110
10111
10112
10113
10114
10115
10116
10117
10118
10119
10120
10121
|
.RE
test
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
Testing
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
10342
10343
10344
10345
10346
10347
10348
10349
10350
10351
10352
10353
10354
10355
|
.RE
test
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
testing
.RS
.TP
\fBfiles/modules/bench/bench\&.n\fR
bench
.TP
\fBfiles/modules/bench/bench_read\&.n\fR
|
| ︙ | | | ︙ | |
10132
10133
10134
10135
10136
10137
10138
10139
10140
10141
10142
10143
10144
10145
10146
10147
10148
10149
10150
10151
10152
10153
10154
|
.TP
\fBfiles/modules/bench/bench_lang_intro\&.n\fR
bench_lang_intro
.TP
\fBfiles/modules/bench/bench_lang_spec\&.n\fR
bench_lang_spec
.RE
TeX
.RS
.TP
\fBfiles/modules/textutil/textutil\&.n\fR
textutil
.TP
\fBfiles/modules/textutil/adjust\&.n\fR
textutil::adjust
.RE
|
<
<
<
<
<
<
<
<
<
|
10366
10367
10368
10369
10370
10371
10372
10373
10374
10375
10376
10377
10378
10379
|
.TP
\fBfiles/modules/bench/bench_lang_intro\&.n\fR
bench_lang_intro
.TP
\fBfiles/modules/bench/bench_lang_spec\&.n\fR
bench_lang_spec
.RE
text
.RS
.TP
\fBfiles/modules/bench/bench_read\&.n\fR
bench::in
.TP
\fBfiles/modules/bench/bench_wtext\&.n\fR
|
| ︙ | | | ︙ | |
10420
10421
10422
10423
10424
10425
10426
10427
10428
10429
10430
10431
10432
10433
10434
10435
10436
10437
10438
10439
|
.RE
tip 317
.RS
.TP
\fBfiles/modules/virtchannel_transform/vt_base64\&.n\fR
tcl::transform::base64
.RE
Tk
.RS
.TP
\fBfiles/modules/virtchannel_base/textwindow\&.n\fR
tcl::chan::textwindow
.RE
|
<
<
<
<
<
<
|
10645
10646
10647
10648
10649
10650
10651
10652
10653
10654
10655
10656
10657
10658
|
.RE
tip 317
.RS
.TP
\fBfiles/modules/virtchannel_transform/vt_base64\&.n\fR
tcl::transform::base64
.RE
tls
.RS
.TP
\fBfiles/modules/comm/comm\&.n\fR
comm
.TP
\fBfiles/modules/imap4/imap4\&.n\fR
|
| ︙ | | | ︙ | |
10453
10454
10455
10456
10457
10458
10459
10460
10461
10462
10463
10464
10465
10466
10467
10468
10469
10470
10471
10472
10473
10474
10475
10476
10477
10478
10479
10480
10481
10482
10483
10484
10485
10486
10487
10488
10489
10490
10491
10492
10493
|
.TP
\fBfiles/modules/transfer/receiver\&.n\fR
transfer::receiver
.TP
\fBfiles/modules/transfer/transmitter\&.n\fR
transfer::transmitter
.RE
TMML
.RS
.TP
\fBfiles/modules/doctools/doctools\&.n\fR
doctools
.TP
\fBfiles/modules/doctools2idx/idx_container\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/docidx\&.n\fR
doctools::idx
.TP
\fBfiles/modules/doctools/doctoc\&.n\fR
doctools::toc
.TP
\fBfiles/modules/doctools2toc/toc_container\&.n\fR
doctools::toc
.TP
\fBfiles/apps/dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR
dtplite
.TP
\fBfiles/modules/doctools/mpexpand\&.n\fR
mpexpand
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
10672
10673
10674
10675
10676
10677
10678
10679
10680
10681
10682
10683
10684
10685
|
.TP
\fBfiles/modules/transfer/receiver\&.n\fR
transfer::receiver
.TP
\fBfiles/modules/transfer/transmitter\&.n\fR
transfer::transmitter
.RE
toc
.RS
.TP
\fBfiles/modules/doctools/doctoc_intro\&.n\fR
doctoc_intro
.TP
\fBfiles/modules/doctools/doctoc_plugin_apiref\&.n\fR
|
| ︙ | | | ︙ | |
10531
10532
10533
10534
10535
10536
10537
10538
10539
10540
10541
10542
10543
10544
10545
10546
10547
10548
10549
10550
10551
10552
10553
10554
10555
10556
|
.TP
\fBfiles/modules/string/token\&.n\fR
string::token
.TP
\fBfiles/modules/string/token_shell\&.n\fR
string::token::shell
.RE
TOOL
.RS
.TP
\fBfiles/modules/oometa/oometa\&.n\fR
oometa
.TP
\fBfiles/modules/tool/tool\&.n\fR
tool
.TP
\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR
tool::dict_ensemble
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
|
10723
10724
10725
10726
10727
10728
10729
10730
10731
10732
10733
10734
10735
10736
|
.TP
\fBfiles/modules/string/token\&.n\fR
string::token
.TP
\fBfiles/modules/string/token_shell\&.n\fR
string::token::shell
.RE
top-down parsing languages
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.TP
\fBfiles/modules/grammar_peg/peg\&.n\fR
|
| ︙ | | | ︙ | |
10696
10697
10698
10699
10700
10701
10702
10703
10704
10705
10706
10707
10708
10709
10710
10711
10712
10713
10714
10715
|
.RE
touch
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
TPDL
.RS
.TP
\fBfiles/modules/grammar_me/me_intro\&.n\fR
grammar::me_intro
.RE
|
<
<
<
<
<
<
|
10876
10877
10878
10879
10880
10881
10882
10883
10884
10885
10886
10887
10888
10889
|
.RE
touch
.RS
.TP
\fBfiles/modules/fileutil/fileutil\&.n\fR
fileutil
.RE
trace
.RS
.TP
\fBfiles/modules/debug/debug\&.n\fR
debug
.TP
\fBfiles/modules/debug/debug_caller\&.n\fR
|
| ︙ | | | ︙ | |
11002
11003
11004
11005
11006
11007
11008
11009
11010
11011
11012
11013
11014
11015
11016
11017
11018
11019
11020
11021
|
.TP
\fBfiles/modules/page/page_util_norm_lemon\&.n\fR
page_util_norm_lemon
.TP
\fBfiles/modules/page/page_util_norm_peg\&.n\fR
page_util_norm_peg
.RE
TreeQL
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
|
<
<
<
<
<
<
|
11176
11177
11178
11179
11180
11181
11182
11183
11184
11185
11186
11187
11188
11189
|
.TP
\fBfiles/modules/page/page_util_norm_lemon\&.n\fR
page_util_norm_lemon
.TP
\fBfiles/modules/page/page_util_norm_peg\&.n\fR
page_util_norm_peg
.RE
trigonometry
.RS
.TP
\fBfiles/modules/math/trig\&.n\fR
math::trig
.RE
trimming
|
| ︙ | | | ︙ | |
11050
11051
11052
11053
11054
11055
11056
11057
11058
11059
11060
11061
11062
11063
11064
11065
11066
11067
11068
11069
11070
11071
11072
11073
11074
11075
11076
11077
11078
11079
11080
11081
11082
11083
11084
11085
11086
11087
11088
11089
11090
11091
11092
11093
11094
11095
11096
11097
11098
11099
11100
11101
11102
11103
11104
11105
|
.TP
\fBfiles/modules/fumagic/rtcore\&.n\fR
fileutil::magic::rt
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.RE
Type checking
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
11218
11219
11220
11221
11222
11223
11224
11225
11226
11227
11228
11229
11230
11231
|
.TP
\fBfiles/modules/fumagic/rtcore\&.n\fR
fileutil::magic::rt
.TP
\fBfiles/modules/snit/snit\&.n\fR
snit
.RE
uevent
.RS
.TP
\fBfiles/modules/hook/hook\&.n\fR
hook
.RE
unbind
|
| ︙ | | | ︙ | |
11215
11216
11217
11218
11219
11220
11221
11222
11223
11224
11225
11226
11227
11228
11229
11230
11231
11232
11233
11234
11235
11236
11237
11238
11239
11240
11241
11242
11243
11244
11245
11246
11247
11248
11249
11250
11251
11252
11253
11254
11255
11256
11257
11258
11259
11260
11261
11262
11263
11264
11265
11266
11267
11268
11269
11270
11271
11272
11273
11274
11275
11276
11277
11278
11279
11280
11281
11282
11283
11284
11285
11286
11287
11288
11289
11290
11291
11292
11293
11294
11295
11296
11297
11298
11299
11300
11301
11302
11303
11304
11305
11306
11307
11308
11309
11310
11311
11312
11313
11314
11315
11316
11317
11318
11319
11320
11321
11322
11323
11324
11325
11326
11327
11328
11329
11330
11331
11332
11333
11334
11335
11336
|
.RE
urn
.RS
.TP
\fBfiles/modules/uri/urn-scheme\&.n\fR
uri_urn
.RE
US-NPI
.RS
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.RE
UUID
.RS
.TP
\fBfiles/modules/uuid/uuid\&.n\fR
uuid
.RE
Validation
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
Value checking
.RS
.TP
\fBfiles/modules/valtype/valtype_common\&.n\fR
valtype::common
.TP
\fBfiles/modules/valtype/cc_amex\&.n\fR
valtype::creditcard::amex
.TP
\fBfiles/modules/valtype/cc_discover\&.n\fR
valtype::creditcard::discover
.TP
\fBfiles/modules/valtype/cc_mastercard\&.n\fR
valtype::creditcard::mastercard
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.TP
\fBfiles/modules/valtype/ean13\&.n\fR
valtype::gs1::ean13
.TP
\fBfiles/modules/valtype/iban\&.n\fR
valtype::iban
.TP
\fBfiles/modules/valtype/imei\&.n\fR
valtype::imei
.TP
\fBfiles/modules/valtype/isbn\&.n\fR
valtype::isbn
.TP
\fBfiles/modules/valtype/luhn\&.n\fR
valtype::luhn
.TP
\fBfiles/modules/valtype/luhn5\&.n\fR
valtype::luhn5
.TP
\fBfiles/modules/valtype/usnpi\&.n\fR
valtype::usnpi
.TP
\fBfiles/modules/valtype/verhoeff\&.n\fR
valtype::verhoeff
.RE
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
11341
11342
11343
11344
11345
11346
11347
11348
11349
11350
11351
11352
11353
11354
11355
11356
11357
11358
11359
11360
11361
11362
11363
11364
11365
11366
|
.RE
urn
.RS
.TP
\fBfiles/modules/uri/urn-scheme\&.n\fR
uri_urn
.RE
utilities
.RS
.TP
\fBfiles/modules/namespacex/namespacex\&.n\fR
namespacex
.RE
uuencode
.RS
.TP
\fBfiles/modules/base64/uuencode\&.n\fR
uuencode
.RE
vectors
.RS
.TP
\fBfiles/modules/math/linalg\&.n\fR
math::linearalgebra
.RE
verhoeff
|
| ︙ | | | ︙ | |
11470
11471
11472
11473
11474
11475
11476
11477
11478
11479
11480
11481
11482
11483
11484
11485
11486
11487
11488
11489
|
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
grammar::peg::interp
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.RE
VISA
.RS
.TP
\fBfiles/modules/valtype/cc_visa\&.n\fR
valtype::creditcard::visa
.RE
|
<
<
<
<
<
<
|
11500
11501
11502
11503
11504
11505
11506
11507
11508
11509
11510
11511
11512
11513
|
.TP
\fBfiles/modules/grammar_peg/peg_interp\&.n\fR
grammar::peg::interp
.TP
\fBfiles/modules/pt/pt_param\&.n\fR
pt::param
.RE
vwait
.RS
.TP
\fBfiles/modules/coroutine/tcllib_coroutine\&.n\fR
coroutine
.TP
\fBfiles/modules/coroutine/coro_auto\&.n\fR
|
| ︙ | | | ︙ | |
11548
11549
11550
11551
11552
11553
11554
11555
11556
11557
11558
11559
11560
11561
11562
11563
11564
11565
11566
11567
|
.TP
\fBfiles/modules/doctools2base/tcl_parse\&.n\fR
doctools::tcl::parse
.TP
\fBfiles/modules/wip/wip\&.n\fR
wip
.RE
WWW
.RS
.TP
\fBfiles/modules/httpd/httpd\&.n\fR
tool
.RE
|
<
<
<
<
<
<
|
11572
11573
11574
11575
11576
11577
11578
11579
11580
11581
11582
11583
11584
11585
|
.TP
\fBfiles/modules/doctools2base/tcl_parse\&.n\fR
doctools::tcl::parse
.TP
\fBfiles/modules/wip/wip\&.n\fR
wip
.RE
www
.RS
.TP
\fBfiles/modules/uri/uri\&.n\fR
uri
.RE
x\&.208
|
| ︙ | | | ︙ | |
11578
11579
11580
11581
11582
11583
11584
11585
11586
11587
11588
11589
11590
11591
11592
11593
11594
11595
11596
11597
11598
11599
11600
11601
11602
11603
11604
11605
11606
11607
11608
11609
11610
11611
11612
11613
11614
11615
11616
11617
11618
11619
11620
11621
11622
11623
11624
11625
11626
11627
11628
11629
11630
11631
11632
11633
11634
11635
11636
11637
11638
|
.RE
x\&.500
.RS
.TP
\fBfiles/modules/ldap/ldap\&.n\fR
ldap
.RE
XGoogleToken
.RS
.TP
\fBfiles/modules/sasl/gtoken\&.n\fR
SASL::XGoogleToken
.RE
XPath
.RS
.TP
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
XSLT
\fBfiles/modules/treeql/treeql\&.n\fR
treeql
.RE
yaml
.RS
.TP
\fBfiles/modules/yaml/huddle\&.n\fR
huddle
.TP
\fBfiles/modules/yaml/yaml\&.n\fR
yaml
.RE
ydecode
.RS
.TP
\fBfiles/modules/base64/yencode\&.n\fR
yencode
.RE
yEnc
.RS
|
<
<
<
<
<
<
<
<
<
<
<
|
<
|
|
<
<
<
<
<
<
|
11596
11597
11598
11599
11600
11601
11602
11603
11604
11605
11606
11607
11608
11609
11610
11611
11612
11613
11614
11615
11616
11617
11618
11619
11620
11621
11622
11623
11624
11625
11626
11627
11628
11629
11630
11631
11632
11633
11634
11635
11636
11637
11638
|
.RE
x\&.500
.RS
.TP
\fBfiles/modules/ldap/ldap\&.n\fR
ldap
.RE
xml
.RS
.TP
\fBfiles/modules/amazon-s3/xsxp\&.n\fR
xsxp
.RE
xor
.RS
.TP
\fBfiles/modules/virtchannel_transform/vt_otp\&.n\fR
tcl::transform::otp
.RE
yEnc
.RS
.TP
\fBfiles/modules/base64/yencode\&.n\fR
yencode
.RE
yaml
.RS
.TP
\fBfiles/modules/yaml/huddle\&.n\fR
huddle
.TP
\fBfiles/modules/yaml/yaml\&.n\fR
yaml
.RE
ydecode
.RS
.TP
\fBfiles/modules/base64/yencode\&.n\fR
yencode
.RE
yencode
.RS
.TP
|
| ︙ | | | ︙ | |
11673
11674
11675
11676
11677
11678
11679
11680
|
map::slippy
.TP
\fBfiles/modules/map/map_slippy_cache\&.n\fR
map::slippy::cache
.TP
\fBfiles/modules/map/map_slippy_fetcher\&.n\fR
map::slippy::fetcher
.RE
|
>
|
11673
11674
11675
11676
11677
11678
11679
11680
11681
|
map::slippy
.TP
\fBfiles/modules/map/map_slippy_cache\&.n\fR
map::slippy::cache
.TP
\fBfiles/modules/map/map_slippy_fetcher\&.n\fR
map::slippy::fetcher
.RE
.RE
|
Changes to idoc/man/toc.n.
Changes to idoc/www/tcllib/files/apps/dtplite.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>dtplite - Documentation toolbox</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/apps/nns.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>nns - Name service facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/apps/nnsd.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>nnsd - Name service facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/apps/nnslog.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>nnslog - Name service facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/apps/page.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page - Development Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/apps/pt.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/apps/tcldocstrip.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcldocstrip - Textprocessing toolbox</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/aes/aes.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>aes - Advanced Encryption Standard (AES)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/amazon-s3/S3.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>S3 - Amazon S3 Web Service Utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/asn/asn.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>asn - ASN.1 processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/base32/base32.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>base32 - Base32 encoding</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/base32/base32core.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>base32::core - Base32 encoding</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/base32/base32hex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>base32::hex - Base32 encoding</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bee/bee.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bee - BitTorrent</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench - Benchmarking/Performance tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench_intro - Benchmarking/Performance tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench_lang_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench_lang_intro - Benchmarking/Performance tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench_lang_spec.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench_lang_spec - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench_read.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench::in - Benchmarking/Performance tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench_wcsv.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench::out::csv - Benchmarking/Performance tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bench/bench_wtext.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bench::out::text - Benchmarking/Performance tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/bibtex/bibtex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>bibtex - bibtex</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/blowfish/blowfish.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>blowfish - Blowfish Block Cipher</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/cache/async.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>cache::async - In-memory caches</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/clock/iso8601.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>clock_iso8601 - Date/Time Utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/clock/rfc2822.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>clock_rfc2822 - Date/Time Utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/comm/comm.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>comm - Remote communication</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/coroutine/coro_auto.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>coroutine::auto - Coroutine utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/coroutine/tcllib_coroutine.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>coroutine - Coroutine utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/counter/counter.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>counter - Counters and Histograms</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/crc/cksum.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>cksum - Cyclic Redundancy Checks</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/crc/crc16.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>crc16 - Cyclic Redundancy Checks</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/crc/crc32.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>crc32 - Cyclic Redundancy Checks</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/crc/sum.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>sum - Cyclic Redundancy Checks</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/cron/cron.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>cron - cron</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/csv/csv.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>csv - CSV processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/debug/debug.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>debug - debug narrative</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/debug/debug_caller.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>debug::caller - debug narrative</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/debug/debug_heartbeat.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>debug::heartbeat - debug narrative</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/debug/debug_timestamp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>debug::timestamp - debug narrative</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/defer/defer.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>defer - Defered execution ala Go</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/des/des.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>des - Data Encryption Standard (DES)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/des/tcldes.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tclDES - Data Encryption Standard (DES)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/des/tcldesjr.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tclDESjr - Data Encryption Standard (DES)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/dicttool/dicttool.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>dicttool - Extensions to the standard "dict" command</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/dns/tcllib_dns.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>dns - Domain Name Service</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/dns/tcllib_ip.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcllib_ip - Domain Name Service</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/docstrip/docstrip_util.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docstrip_util - Literate programming tool</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/changelog.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::changelog - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/cvs.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::cvs - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docidx_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docidx_lang_cmdref - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx_lang_faq.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docidx_lang_faq - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx_lang_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docidx_lang_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx_lang_syntax.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docidx_lang_syntax - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>docidx_plugin_apiref - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctoc_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctoc_lang_cmdref - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc_lang_faq.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctoc_lang_faq - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc_lang_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctoc_lang_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctoc_lang_syntax - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctoc_plugin_apiref - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools_lang_cmdref - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools_lang_faq.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools_lang_faq - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools_lang_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools_lang_syntax.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools_lang_syntax - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools_plugin_apiref - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools/mpexpand.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>mpexpand - Documentation toolbox</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2base/html_cssdefaults.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::html::cssdefaults - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2base/nroff_manmacros.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::nroff::man_macros - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2base/tcl_parse.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::tcl::parse - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/export_docidx.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export::docidx - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_export.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_export_html.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export::html - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_export_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export::json - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export::nroff - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_export_text.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export::text - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::export::wiki - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_import.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::import - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_import_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::import::json - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_introduction.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools2idx_introduction - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::idx::c - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::idx::de - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::idx::en - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::idx::fr - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_parse.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::parse - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/idx_structure.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::structure - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2idx/import_docidx.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::idx::import::docidx - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/export_doctoc.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export::doctoc - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/import_doctoc.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::import::doctoc - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_export.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_export_html.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export::html - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_export_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export::json - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export::nroff - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_export_text.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export::text - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::export::wiki - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_import.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::import - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_import_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::import::json - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_introduction.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools2toc_introduction - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::toc::c - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::toc::de - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::toc::en - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::msgcat::toc::fr - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_parse.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::parse - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/doctools2toc/toc_structure.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>doctools::toc::structure - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/dtplite/pkg_dtplite.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>dtplite - Documentation toolbox</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fileutil/fileutil.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fileutil/multi.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil::multi - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fileutil/multiop.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil::multi::op - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fileutil/traverse.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil_traverse - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ftp/ftp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ftp - ftp client</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ftp/ftp_geturl.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ftp::geturl - ftp client</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ftpd/ftpd.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ftpd - Tcl FTP Server Package</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fumagic/cfront.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil::magic::cfront - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fumagic/cgen.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil::magic::cgen - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fumagic/filetypes.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil::magic::filetype - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/fumagic/rtcore.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>fileutil::magic::rt - file utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/gpx/gpx.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>gpx - GPS eXchange Format (GPX)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_aycock/aycock.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_fa/dacceptor.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::fa::dacceptor - Finite automaton operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_fa/dexec.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::fa::dexec - Finite automaton operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_fa/fa.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::fa - Finite automaton operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_fa/faop.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::fa::op - Finite automaton operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/gasm.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me::cpu::gasm - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_ast.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me_ast - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_cpu.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me::cpu - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_cpucore.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me::cpu::core - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me_intro - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_tcl.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me::tcl - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_util.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me::util - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_me/me_vm.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::me_vm - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_peg/peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::peg - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/grammar_peg/peg_interp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>grammar::peg::interp - Grammar operations and usage</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/hook/hook.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>hook - Hooks</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/html/html.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>html - HTML Generation</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/htmlparse/htmlparse.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>htmlparse - HTML Parser</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/http/autoproxy.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>autoproxy - HTTP protocol helper modules</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/httpd/httpd.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tool - Tcl Web Server</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ident/ident.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ident - Identification protocol client</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/inifile/ini.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>inifile - Parsing of Windows INI files</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/interp/deleg_method.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>deleg_method - Interpreter utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/interp/deleg_proc.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>deleg_proc - Interpreter utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/interp/tcllib_interp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>interp - Interpreter utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/irc/irc.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>irc - Low Level Tcl IRC Interface</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/irc/picoirc.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>picoirc - Simple embeddable IRC interface</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/javascript/javascript.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>javascript - HTML and Java Script Generation</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/json/json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>json - JSON</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/json/json_write.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>json::write - JSON</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/lambda/lambda.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>lambda - Utility commands for anonymous procedures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/lazyset/lazyset.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>lazyset - Lazy evaluation for variables and arrays</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ldap/ldap.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ldap - LDAP client</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ldap/ldapx.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ldapx - LDAP extended object interface</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/log/log.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>log - Logging facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/log/logger.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>logger - Object Oriented logging facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/log/loggerAppender.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>logger::appender - Object Oriented logging facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/log/loggerUtils.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>logger::utils - Object Oriented logging facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/map/map_geocode_nominatim.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>map::geocode::nominatim - Mapping utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/map/map_slippy.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>map::slippy - Mapping utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/map/map_slippy_cache.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>map::slippy::cache - Mapping utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/map/map_slippy_fetcher.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>map::slippy::fetcher - Mapping utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/mapproj/mapproj.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>mapproj - Tcl Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/markdown/markdown.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>markdown - Markdown to HTML Converter</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/bignum.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::bignum - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/calculus.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::calculus - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/combinatorics.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::combinatorics - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/constants.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::constants - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/decimal.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::decimal - Tcl Decimal Arithmetic Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/exact.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::exact - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/interpolate.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::interpolate - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/linalg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::linearalgebra - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/machineparameters.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tclrep/machineparameters - tclrep</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/math_geometry.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::geometry - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/numtheory.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::numtheory - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/optimize.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::optimize - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/pca.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::PCA - Principal Components Analysis</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/polynomials.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::polynomials - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/qcomplex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::complexnumbers - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/rational_funcs.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::rationalfunctions - Math</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/roman.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::roman - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/special.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::special - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/statistics.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::statistics - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/symdiff.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::calculus::symdiff - Symbolic differentiation for Tcl</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/math/trig.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>math::trig - Tcl Math Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/md4/md4.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>md4 - MD4 Message-Digest Algorithm</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/mime/mime.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>mime - Mime</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/mime/smtp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>smtp - smtp client</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/multiplexer/multiplexer.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>multiplexer - One-to-many communication with sockets.</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/namespacex/namespacex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>namespacex - Namespace utility commands</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ncgi/ncgi.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ncgi - CGI Support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/nettool/nettool.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>nettool - nettool</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/nns/nns_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>nns_intro - Name service facility</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/nntp/nntp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>nntp - Tcl NNTP Client Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/oauth/oauth.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>oauth - oauth</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/oometa/oometa.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>oometa - Data registry for TclOO frameworks</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ooutil/ooutil.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>oo::util - Utility commands for TclOO</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_intro.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_intro - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_pluginmgr.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_pluginmgr - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_util_flow.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_util_flow - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_util_norm_lemon.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_util_norm_lemon - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_util_norm_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_util_norm_peg - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_util_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_util_peg - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/page/page_util_quote.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>page_util_quote - Parser generator tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pki/pki.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pki - public key encryption</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pluginmgr/pluginmgr.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pluginmgr - Plugin management</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/png/png.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>png - Image manipulation</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pop3d/pop3d.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pop3d - Tcl POP3 Server Package</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pop3d/pop3d_dbox.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pop3d::dbox - Tcl POP3 Server Package</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pop3d/pop3d_udb.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pop3d::udb - Tcl POP3 Server Package</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/practcl/practcl.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>practcl - The The Proper Rational API for C to Tool Command Language Module</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/processman/processman.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>processman - processman</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/profiler/profiler.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>profiler - Tcl Profiler</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_astree.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::ast - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::cparam::configuration::critcl - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_cparam_config_tea.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::cparam::configuration::tea - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_from_api.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt_import_api - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_introduction.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt_introduction - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_json_language.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::json_language - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_param.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::param - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_parse_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt_parse_peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_parser_api.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt_parser_api - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::container - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_container_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::container::peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_export.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::export - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_export_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::export::container - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_export_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::export::json - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_export_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::export::peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_from_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::from::container - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_from_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::from::json - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_from_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::from::peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_import.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::import - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_import_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::import::container - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_import_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::import::json - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_import_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::import::peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_interp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::interp - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_introduction.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::pegrammar - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_language.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg_language - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_op.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt_peg_op - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_to_container.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::to::container - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_to_cparam.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::to::cparam - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_to_json.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::to::json - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_to_param.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::to::param - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_to_peg.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::to::peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg::to::tclparam - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_pegrammar.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::peg - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_pexpr_op.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::pe::op - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_pexpression.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::pe - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_pgen.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::pgen - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_rdengine.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::rde - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_tclparam_config_nx.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::tclparam::configuration::nx - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::tclparam::configuration::snit - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::tclparam::configuration::tcloo - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_to_api.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt_export_api - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/pt/pt_util.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>pt::util - Parser Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/rc4/rc4.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>rc4 - RC4 Stream Cipher</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/report/report.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>report - Matrix reports</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/rest/rest.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>rest - A framework for RESTful web services</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ripemd/ripemd128.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ripemd128 - RIPEMD Message-Digest Algorithm</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/ripemd/ripemd160.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>ripemd160 - RIPEMD Message-Digest Algorithm</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/sasl/gtoken.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>SASL::XGoogleToken - Simple Authentication and Security Layer (SASL)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/sasl/ntlm.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>SASL::NTLM - Simple Authentication and Security Layer (SASL)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/sasl/sasl.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>SASL - Simple Authentication and Security Layer (SASL)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/sasl/scram.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>SASL::SCRAM - Simple Authentication and Security Layer (SASL)</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/simulation/annealing.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>simulation::annealing - Tcl Simulation Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/simulation/montecarlo.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>simulation::montecarlo - Tcl Simulation Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/simulation/simulation_random.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>simulation::random - Tcl Simulation Tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/smtpd/smtpd.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>smtpd - Tcl SMTP Server Package</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/snit/snit.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>snit - Snit's Not Incr Tcl, OO system</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/snit/snitfaq.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>snitfaq - Snit's Not Incr Tcl, OO system</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/soundex/soundex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>soundex - Soundex</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/stooop/stooop.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>stooop - Simple Tcl Only Object Oriented Programming</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/stooop/switched.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>switched - Simple Tcl Only Object Oriented Programming</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/string/token_shell.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>string::token::shell - Text and string utilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/stringprep/stringprep.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>stringprep - Preparation of Internationalized Strings</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/stringprep/stringprep_data.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>stringprep::data - Preparation of Internationalized Strings</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/stringprep/unicode.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>unicode - Unicode normalization</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/stringprep/unicode_data.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>unicode::data - Preparation of Internationalized Strings</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/disjointset.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::disjointset - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/graph.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::graph - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/graph1.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::graph_v1 - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/graphops.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::graph::op - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/matrix.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::matrix - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/matrix1.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::matrix_v1 - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/pool.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::pool - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/queue.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::queue - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/record.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::record - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/skiplist.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::skiplist - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/struct_list.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::list - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/struct_set.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::set - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/struct_tree.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::tree - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/struct/struct_tree1.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>struct::tree_v1 - Tcl Data Structures</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/tar/tar.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tar - Tar file handling</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ansi_cattr.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::ansi::code::attr - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ansi_cctrl.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::ansi::code::ctrl - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ansi_cmacros.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::ansi::code::macros - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ansi_code.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::ansi::code - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ansi_ctrlu.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::ansi::ctrl::unix - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ansi_send.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::ansi::send - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/imenu.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::interact::menu - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/ipager.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::interact::pager - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/receive.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::receive - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/term.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/term_bind.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::receive::bind - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/term/term_send.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>term::send - Terminal control</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/textutil/adjust.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>textutil::adjust - Text and string utilities, macro processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/textutil/expander.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>textutil::expander - Text and string utilities, macro processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/textutil/textutil_split.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>textutil::split - Text and string utilities, macro processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/textutil/textutil_string.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>textutil::string - Text and string utilities, macro processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/tool/meta.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>oo::util - Utility commands for TclOO</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/tool/tool.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tool - Standardized OO Framework for development</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/tool/tool_dict_ensemble.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tool::dict_ensemble - Standardized OO Framework for development</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/connect.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::connect - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/copyops.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::copy - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/ddest.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::data::destination - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/dsource.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::data::source - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/receiver.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::receiver - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/tqueue.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::copy::queue - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/transfer/transmitter.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>transfer::transmitter - Data transfer facilities</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/treeql/treeql.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>treeql - Tree Query Language</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/try/tcllib_throw.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>throw - Forward compatibility implementation of [throw]</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/try/tcllib_try.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>try - Forward compatibility implementation of [try]</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/udpcluster/udpcluster.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>udpcluster - Lightweight UDP based tool for cluster node discovery</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/units/units.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>units - Convert and manipulate quantities with units</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/uri/uri.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>uri - Tcl Uniform Resource Identifier Management</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/uri/urn-scheme.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>uri_urn - Tcl Uniform Resource Identifier Management</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/uuid/uuid.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>uuid - uuid</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/cc_amex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::creditcard::amex - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/cc_discover.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::creditcard::discover - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/cc_mastercard.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::creditcard::mastercard - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/cc_visa.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::creditcard::visa - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/ean13.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::gs1::ean13 - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/iban.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::iban - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/imei.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::imei - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/isbn.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::isbn - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/luhn.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::luhn - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/luhn5.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::luhn5 - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/usnpi.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::usnpi - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/valtype_common.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::common - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/valtype/verhoeff.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>valtype::verhoeff - Validation types</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/cat.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::cat - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/facade.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::facade - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/halfpipe.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::halfpipe - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/nullzero.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::nullzero - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/randseed.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::randomseed - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/std.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::std - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_fifo.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::fifo - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_fifo2.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::fifo2 - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_memchan.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::memchan - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_null.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::null - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_random.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::random - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_string.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::string - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_variable.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::variable - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/tcllib_zero.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::zero - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_base/textwindow.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::textwindow - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_core/core.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::core - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_core/events.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::chan::events - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_core/transformcore.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::core - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/adler32.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::adler32 - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/hex.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::hex - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/identity.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::identity - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/limitsize.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::limitsize - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/observe.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::observe - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/rot.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::rot - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/spacer.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::spacer - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/tcllib_zlib.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::zlib - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/vt_base64.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::base64 - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/vt_counter.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::counter - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/vt_crc32.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::crc32 - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/virtchannel_transform/vt_otp.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>tcl::transform::otp - Reflected/virtual channel support</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/websocket/websocket.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>websocket - websocket client and server</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/wip/wip.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>wip - Word Interpreter</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/yaml/huddle.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>huddle - HUDDLE</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/yaml/yaml.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>yaml - YAML processing</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/zip/decode.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>zipfile::decode - Zip archive handling</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/zip/encode.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>zipfile::encode - Zip archive handling</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/files/modules/zip/mkzip.html.
1
2
3
4
5
6
7
8
|
|
<
|
1
2
3
4
5
6
7
|
<!DOCTYPE html><html><head>
<title>zipfile::mkzip - Zip archive creation</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
|
| ︙ | | | ︙ | |
Changes to idoc/www/tcllib/toc.html.
| ︙ | | | ︙ | |
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
<hr> [
<a href="../../../../../home">Tcllib Home</a>
| <a href="../index.html">Keyword Index</a>
| <a href="../toc0.html">Categories</a>
| <a href="../toc1.html">Modules</a>
| <a href="../toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> tcllib </h2><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="files/modules/base64/ascii85.html">ascii85</a></td>
|
|
|
|
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
<hr> [
<a href="../../../../../home">Tcllib Home</a>
| <a href="../index.html">Keyword Index</a>
| <a href="../toc0.html">Categories</a>
| <a href="../toc1.html">Modules</a>
| <a href="../toc2.html">Applications</a>
] <hr>
<h3>Table Of Contents</h3>
<hr><dl><dt><h2>tcllib</h2></dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="files/modules/base64/ascii85.html">ascii85</a></td>
|
| ︙ | | | ︙ | |
1729
1730
1731
1732
1733
1734
1735
1736
|
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table>
</dl><hr></body></html>
|
|
|
1729
1730
1731
1732
1733
1734
1735
1736
|
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table>
</dd></dl><hr></body></html>
|
Changes to idoc/www/toc.html.
| ︙ | | | ︙ | |
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='by_categories'>By Categories<dd>
<dl><dt><a name='argument_entry_form_mega_widget'>Argument entry form, mega widget<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='benchmark_tools'>Benchmark tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
|
|
|
|
|
|
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3>Table Of Contents</h3>
<hr><dl><dt><h2></h2></dt><dd>
<dl><dt><a name='by_categories'>By Categories</dt><dd>
<dl><dt><a name='argument_entry_form_mega_widget'>Argument entry form, mega widget</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='benchmark_tools'>Benchmark tools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
| ︙ | | | ︙ | |
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='cgi_programming'>CGI programming<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
|
|
|
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='cgi_programming'>CGI programming</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
|
| ︙ | | | ︙ | |
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='channels'>Channels<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
|
|
|
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='channels'>Channels</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
|
| ︙ | | | ︙ | |
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>Coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='data_structures'>Data structures<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
|
|
|
|
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>Coroutine</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='data_structures'>Data structures</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
|
| ︙ | | | ︙ | |
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='debugging_tracing_and_logging'>debugging, tracing, and logging<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='documentation_tools'>Documentation tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
|
|
|
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='debugging_tracing_and_logging'>debugging, tracing, and logging</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='documentation_tools'>Documentation tools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
| ︙ | | | ︙ | |
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
|
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
</table></dl>
<dl><dt><a name='file'>File<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
<dl><dt><a name='file_formats'>File formats<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
|
|
|
|
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
|
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
</table></dl>
<dl><dt><a name='file'>File</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
<dl><dt><a name='file_formats'>File formats</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
|
| ︙ | | | ︙ | |
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
|
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='grammars_and_finite_automata'>Grammars and finite automata<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
|
|
|
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
|
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='grammars_and_finite_automata'>Grammars and finite automata</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
|
| ︙ | | | ︙ | |
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hashes_checksums_and_encryption'>Hashes, checksums, and encryption<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
|
|
|
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hashes_checksums_and_encryption'>Hashes, checksums, and encryption</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
|
| ︙ | | | ︙ | |
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
|
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='mathematics'>Mathematics<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
|
|
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
|
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='mathematics'>Mathematics</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
| ︙ | | | ︙ | |
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
|
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='networking'>Networking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
|
|
|
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
|
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='networking'>Networking</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
|
| ︙ | | | ︙ | |
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
|
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='page_parser_generator'>Page Parser Generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
|
|
|
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
|
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='page_parser_generator'>Page Parser Generator</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
|
| ︙ | | | ︙ | |
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='parsing_and_grammars'>Parsing and Grammars<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
|
|
|
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='parsing_and_grammars'>Parsing and Grammars</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
|
| ︙ | | | ︙ | |
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='procedures_arguments_parameters_options'>Procedures, arguments, parameters, options<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='programming_tools'>Programming tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
|
|
|
|
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='procedures_arguments_parameters_options'>Procedures, arguments, parameters, options</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='programming_tools'>Programming tools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
|
| ︙ | | | ︙ | |
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
|
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='system'>System<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='tcloo'>TclOO<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
</table></dl>
<dl><dt><a name='terminal_control'>Terminal control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
|
|
|
|
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
|
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='system'>System</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='tcloo'>TclOO</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
</table></dl>
<dl><dt><a name='terminal_control'>Terminal control</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
| ︙ | | | ︙ | |
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='text_formatter_plugin'>Text formatter plugin<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
|
|
|
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='text_formatter_plugin'>Text formatter plugin</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
|
| ︙ | | | ︙ | |
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
|
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
</table></dl>
<dl><dt><a name='text_processing'>Text processing<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
|
|
|
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
|
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
</table></dl>
<dl><dt><a name='text_processing'>Text processing</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
|
| ︙ | | | ︙ | |
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
|
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='transfer_module'>Transfer module<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
|
|
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
|
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='transfer_module'>Transfer module</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
| ︙ | | | ︙ | |
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='unfiled'>Unfiled<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
|
|
|
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='unfiled'>Unfiled</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
|
| ︙ | | | ︙ | |
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
|
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='utilities'>Utilities<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='utility'>Utility<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
|
|
|
|
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
|
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='utilities'>Utilities</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='utility'>Utility</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
|
| ︙ | | | ︙ | |
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
|
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='validation_type_checking'>Validation, Type checking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
|
|
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
|
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='validation_type_checking'>Validation, Type checking</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
| ︙ | | | ︙ | |
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
|
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl></table></dl>
<dl><dt><a name='by_type'>By Type<dd>
<dl><dt><a name='applications'>Applications<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
|
|
>
|
|
|
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
|
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
</dl>
<dl><dt><a name='by_type'>By Type</dt><dd>
<dl><dt><a name='applications'>Applications</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
|
| ︙ | | | ︙ | |
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
|
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
</table></dl>
<dl><dt><a name='modules'>Modules<dd>
<dl><dt><a name='aes'>aes<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='amazon_s3'>amazon-s3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
</table></dl>
<dl><dt><a name='asn'>asn<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
</table></dl>
<dl><dt><a name='base32'>base32<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
</table></dl>
<dl><dt><a name='base64'>base64<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='bee'>bee<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='bench'>bench<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
|
|
|
|
|
|
|
|
|
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
|
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
</table></dl>
<dl><dt><a name='modules'>Modules</dt><dd>
<dl><dt><a name='aes'>aes</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='amazon_s3'>amazon-s3</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
</table></dl>
<dl><dt><a name='asn'>asn</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
</table></dl>
<dl><dt><a name='base32'>base32</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
</table></dl>
<dl><dt><a name='base64'>base64</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='bee'>bee</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='bench'>bench</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
| ︙ | | | ︙ | |
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='bibtex'>bibtex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
</table></dl>
<dl><dt><a name='blowfish'>blowfish<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='cache'>cache<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
</table></dl>
<dl><dt><a name='clock'>clock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
</table></dl>
<dl><dt><a name='cmdline'>cmdline<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
</table></dl>
<dl><dt><a name='comm'>comm<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
</table></dl>
<dl><dt><a name='control'>control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='counter'>counter<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
</table></dl>
<dl><dt><a name='crc'>crc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
</table></dl>
<dl><dt><a name='cron'>cron<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='csv'>csv<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
</table></dl>
<dl><dt><a name='debug'>debug<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='defer'>defer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
</table></dl>
<dl><dt><a name='des'>des<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
</table></dl>
<dl><dt><a name='dicttool'>dicttool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='dns'>dns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='docstrip'>docstrip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
</table></dl>
<dl><dt><a name='doctools'>doctools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='bibtex'>bibtex</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
</table></dl>
<dl><dt><a name='blowfish'>blowfish</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='cache'>cache</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
</table></dl>
<dl><dt><a name='clock'>clock</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
</table></dl>
<dl><dt><a name='cmdline'>cmdline</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
</table></dl>
<dl><dt><a name='comm'>comm</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
</table></dl>
<dl><dt><a name='control'>control</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>coroutine</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='counter'>counter</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
</table></dl>
<dl><dt><a name='crc'>crc</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
</table></dl>
<dl><dt><a name='cron'>cron</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='csv'>csv</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
</table></dl>
<dl><dt><a name='debug'>debug</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='defer'>defer</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
</table></dl>
<dl><dt><a name='des'>des</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
</table></dl>
<dl><dt><a name='dicttool'>dicttool</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='dns'>dns</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='docstrip'>docstrip</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
</table></dl>
<dl><dt><a name='doctools'>doctools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
| ︙ | | | ︙ | |
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
|
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2base'>doctools2base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2idx'>doctools2idx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
|
|
|
|
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
|
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2base'>doctools2base</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2idx'>doctools2idx</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
|
| ︙ | | | ︙ | |
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
|
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2toc'>doctools2toc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
|
|
|
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
|
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2toc'>doctools2toc</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
|
| ︙ | | | ︙ | |
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
|
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
</table></dl>
<dl><dt><a name='dtplite'>dtplite<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
</table></dl>
<dl><dt><a name='fileutil'>fileutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
</table></dl>
<dl><dt><a name='ftp'>ftp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
</table></dl>
<dl><dt><a name='ftpd'>ftpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='fumagic'>fumagic<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='generator'>generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
</table></dl>
<dl><dt><a name='gpx'>gpx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_aycock'>grammar_aycock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_fa'>grammar_fa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_me'>grammar_me<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
|
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
</table></dl>
<dl><dt><a name='dtplite'>dtplite</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
</table></dl>
<dl><dt><a name='fileutil'>fileutil</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
</table></dl>
<dl><dt><a name='ftp'>ftp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
</table></dl>
<dl><dt><a name='ftpd'>ftpd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='fumagic'>fumagic</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='generator'>generator</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
</table></dl>
<dl><dt><a name='gpx'>gpx</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_aycock'>grammar_aycock</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_fa'>grammar_fa</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_me'>grammar_me</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
|
| ︙ | | | ︙ | |
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
|
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_peg'>grammar_peg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hook'>hook<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
</table></dl>
<dl><dt><a name='html'>html<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
</table></dl>
<dl><dt><a name='htmlparse'>htmlparse<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
</table></dl>
<dl><dt><a name='http'>http<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
</table></dl>
<dl><dt><a name='httpd'>httpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
</table></dl>
<dl><dt><a name='ident'>ident<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
</table></dl>
<dl><dt><a name='imap4'>imap4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
</table></dl>
<dl><dt><a name='inifile'>inifile<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
</table></dl>
<dl><dt><a name='interp'>interp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
</table></dl>
<dl><dt><a name='irc'>irc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
</table></dl>
<dl><dt><a name='javascript'>javascript<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
</table></dl>
<dl><dt><a name='jpeg'>jpeg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='json'>json<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
</table></dl>
<dl><dt><a name='lambda'>lambda<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
</table></dl>
<dl><dt><a name='lazyset'>lazyset<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
</table></dl>
<dl><dt><a name='ldap'>ldap<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
</table></dl>
<dl><dt><a name='log'>log<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
</table></dl>
<dl><dt><a name='map'>map<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
</table></dl>
<dl><dt><a name='mapproj'>mapproj<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
</table></dl>
<dl><dt><a name='markdown'>markdown<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
</table></dl>
<dl><dt><a name='math'>math<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
|
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_peg'>grammar_peg</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hook'>hook</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
</table></dl>
<dl><dt><a name='html'>html</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
</table></dl>
<dl><dt><a name='htmlparse'>htmlparse</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
</table></dl>
<dl><dt><a name='http'>http</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
</table></dl>
<dl><dt><a name='httpd'>httpd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
</table></dl>
<dl><dt><a name='ident'>ident</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
</table></dl>
<dl><dt><a name='imap4'>imap4</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
</table></dl>
<dl><dt><a name='inifile'>inifile</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
</table></dl>
<dl><dt><a name='interp'>interp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
</table></dl>
<dl><dt><a name='irc'>irc</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
</table></dl>
<dl><dt><a name='javascript'>javascript</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
</table></dl>
<dl><dt><a name='jpeg'>jpeg</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='json'>json</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
</table></dl>
<dl><dt><a name='lambda'>lambda</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
</table></dl>
<dl><dt><a name='lazyset'>lazyset</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
</table></dl>
<dl><dt><a name='ldap'>ldap</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
</table></dl>
<dl><dt><a name='log'>log</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
</table></dl>
<dl><dt><a name='map'>map</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
</table></dl>
<dl><dt><a name='mapproj'>mapproj</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
</table></dl>
<dl><dt><a name='markdown'>markdown</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
</table></dl>
<dl><dt><a name='math'>math</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
| ︙ | | | ︙ | |
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
|
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
</table></dl>
<dl><dt><a name='md4'>md4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5'>md5<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5crypt'>md5crypt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
</table></dl>
<dl><dt><a name='mime'>mime<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
</table></dl>
<dl><dt><a name='multiplexer'>multiplexer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
</table></dl>
<dl><dt><a name='namespacex'>namespacex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
</table></dl>
<dl><dt><a name='ncgi'>ncgi<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='nettool'>nettool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
</table></dl>
<dl><dt><a name='nmea'>nmea<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
</table></dl>
<dl><dt><a name='nns'>nns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
|
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
</table></dl>
<dl><dt><a name='md4'>md4</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5'>md5</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5crypt'>md5crypt</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
</table></dl>
<dl><dt><a name='mime'>mime</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
</table></dl>
<dl><dt><a name='multiplexer'>multiplexer</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
</table></dl>
<dl><dt><a name='namespacex'>namespacex</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
</table></dl>
<dl><dt><a name='ncgi'>ncgi</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='nettool'>nettool</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
</table></dl>
<dl><dt><a name='nmea'>nmea</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
</table></dl>
<dl><dt><a name='nns'>nns</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
|
| ︙ | | | ︙ | |
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
|
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
</table></dl>
<dl><dt><a name='nntp'>nntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
</table></dl>
<dl><dt><a name='ntp'>ntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
</table></dl>
<dl><dt><a name='oauth'>oauth<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
</table></dl>
<dl><dt><a name='oometa'>oometa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
</table></dl>
<dl><dt><a name='ooutil'>ooutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
</table></dl>
<dl><dt><a name='otp'>otp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
</table></dl>
<dl><dt><a name='page'>page<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
|
|
|
|
|
|
|
|
|
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
|
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
</table></dl>
<dl><dt><a name='nntp'>nntp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
</table></dl>
<dl><dt><a name='ntp'>ntp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
</table></dl>
<dl><dt><a name='oauth'>oauth</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
</table></dl>
<dl><dt><a name='oometa'>oometa</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
</table></dl>
<dl><dt><a name='ooutil'>ooutil</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
</table></dl>
<dl><dt><a name='otp'>otp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
</table></dl>
<dl><dt><a name='page'>page</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
|
| ︙ | | | ︙ | |
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='pki'>pki<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
</table></dl>
<dl><dt><a name='pluginmgr'>pluginmgr<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
</table></dl>
<dl><dt><a name='png'>png<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='pop3'>pop3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
</table></dl>
<dl><dt><a name='pop3d'>pop3d<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
</table></dl>
<dl><dt><a name='practcl'>practcl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
</table></dl>
<dl><dt><a name='processman'>processman<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='profiler'>profiler<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
</table></dl>
<dl><dt><a name='pt'>pt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
|
|
|
|
|
|
|
|
|
|
|
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='pki'>pki</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
</table></dl>
<dl><dt><a name='pluginmgr'>pluginmgr</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
</table></dl>
<dl><dt><a name='png'>png</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='pop3'>pop3</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
</table></dl>
<dl><dt><a name='pop3d'>pop3d</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
</table></dl>
<dl><dt><a name='practcl'>practcl</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
</table></dl>
<dl><dt><a name='processman'>processman</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='profiler'>profiler</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
</table></dl>
<dl><dt><a name='pt'>pt</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
|
| ︙ | | | ︙ | |
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='rc4'>rc4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
</table></dl>
<dl><dt><a name='rcs'>rcs<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
</table></dl>
<dl><dt><a name='report'>report<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
</table></dl>
<dl><dt><a name='rest'>rest<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
</table></dl>
<dl><dt><a name='ripemd'>ripemd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='sasl'>sasl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='sha1'>sha1<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='simulation'>simulation<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='smtpd'>smtpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='snit'>snit<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
</table></dl>
<dl><dt><a name='soundex'>soundex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
</table></dl>
<dl><dt><a name='stooop'>stooop<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
</table></dl>
<dl><dt><a name='string'>string<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
</table></dl>
<dl><dt><a name='stringprep'>stringprep<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
</table></dl>
<dl><dt><a name='struct'>struct<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='rc4'>rc4</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
</table></dl>
<dl><dt><a name='rcs'>rcs</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
</table></dl>
<dl><dt><a name='report'>report</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
</table></dl>
<dl><dt><a name='rest'>rest</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
</table></dl>
<dl><dt><a name='ripemd'>ripemd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='sasl'>sasl</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='sha1'>sha1</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='simulation'>simulation</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='smtpd'>smtpd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='snit'>snit</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
</table></dl>
<dl><dt><a name='soundex'>soundex</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
</table></dl>
<dl><dt><a name='stooop'>stooop</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
</table></dl>
<dl><dt><a name='string'>string</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
</table></dl>
<dl><dt><a name='stringprep'>stringprep</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
</table></dl>
<dl><dt><a name='struct'>struct</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
|
| ︙ | | | ︙ | |
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='tar'>tar<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='tepam'>tepam<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='term'>term<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
|
|
|
|
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='tar'>tar</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='tepam'>tepam</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='term'>term</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
| ︙ | | | ︙ | |
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='textutil'>textutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
|
|
|
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='textutil'>textutil</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
|
| ︙ | | | ︙ | |
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
|
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
</table></dl>
<dl><dt><a name='tie'>tie<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
</table></dl>
<dl><dt><a name='tiff'>tiff<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='tool'>tool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='transfer'>transfer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
|
|
|
|
|
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
|
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
</table></dl>
<dl><dt><a name='tie'>tie</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
</table></dl>
<dl><dt><a name='tiff'>tiff</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='tool'>tool</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='transfer'>transfer</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
| ︙ | | | ︙ | |
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='treeql'>treeql<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='try'>try<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='udpcluster'>udpcluster<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
</table></dl>
<dl><dt><a name='uev'>uev<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
</table></dl>
<dl><dt><a name='units'>units<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
</table></dl>
<dl><dt><a name='uri'>uri<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
</table></dl>
<dl><dt><a name='uuid'>uuid<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='valtype'>valtype<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
|
|
|
|
|
|
|
|
|
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='treeql'>treeql</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='try'>try</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='udpcluster'>udpcluster</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
</table></dl>
<dl><dt><a name='uev'>uev</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
</table></dl>
<dl><dt><a name='units'>units</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
</table></dl>
<dl><dt><a name='uri'>uri</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
</table></dl>
<dl><dt><a name='uuid'>uuid</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='valtype'>valtype</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
| ︙ | | | ︙ | |
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
|
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_base'>virtchannel_base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
|
|
|
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
|
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_base'>virtchannel_base</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
|
| ︙ | | | ︙ | |
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
|
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_core'>virtchannel_core<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_transform'>virtchannel_transform<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
|
|
|
|
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
|
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_core'>virtchannel_core</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_transform'>virtchannel_transform</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
|
| ︙ | | | ︙ | |
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='websocket'>websocket<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='wip'>wip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='yaml'>yaml<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='zip'>zip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl></table></dl></table></dl>
</dl><hr></body></html>
|
|
|
|
|
|
>
|
|
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='websocket'>websocket</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='wip'>wip</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='yaml'>yaml</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='zip'>zip</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
</dl></dl>
</dd></dl><hr></body></html>
|
Changes to idoc/www/toc0.html.
| ︙ | | | ︙ | |
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='by_categories'>By Categories<dd>
<dl><dt><a name='argument_entry_form_mega_widget'>Argument entry form, mega widget<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='benchmark_tools'>Benchmark tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
|
|
|
|
|
|
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3>Table Of Contents</h3>
<hr><dl><dt><h2></h2></dt><dd>
<dl><dt><a name='by_categories'>By Categories</dt><dd>
<dl><dt><a name='argument_entry_form_mega_widget'>Argument entry form, mega widget</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='benchmark_tools'>Benchmark tools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
| ︙ | | | ︙ | |
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='cgi_programming'>CGI programming<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
|
|
|
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='cgi_programming'>CGI programming</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
|
| ︙ | | | ︙ | |
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='channels'>Channels<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
|
|
|
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
<td class="#doctools_tocright">JSON generation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='channels'>Channels</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
|
| ︙ | | | ︙ | |
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>Coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='data_structures'>Data structures<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
|
|
|
|
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>Coroutine</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='data_structures'>Data structures</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
|
| ︙ | | | ︙ | |
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='debugging_tracing_and_logging'>debugging, tracing, and logging<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='documentation_tools'>Documentation tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
|
|
|
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='debugging_tracing_and_logging'>debugging, tracing, and logging</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='documentation_tools'>Documentation tools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
| ︙ | | | ︙ | |
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
|
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
</table></dl>
<dl><dt><a name='file'>File<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
<dl><dt><a name='file_formats'>File formats<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
|
|
|
|
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
|
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil_expander'><a href="tcllib/files/modules/textutil/expander.html">textutil::expander</a></td>
<td class="#doctools_tocright">Procedures to process templates and expand text.</td>
</tr>
</table></dl>
<dl><dt><a name='file'>File</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
<dl><dt><a name='file_formats'>File formats</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
|
| ︙ | | | ︙ | |
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
|
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='grammars_and_finite_automata'>Grammars and finite automata<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
|
|
|
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
|
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='grammars_and_finite_automata'>Grammars and finite automata</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
|
| ︙ | | | ︙ | |
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hashes_checksums_and_encryption'>Hashes, checksums, and encryption<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
|
|
|
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
|
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hashes_checksums_and_encryption'>Hashes, checksums, and encryption</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
|
| ︙ | | | ︙ | |
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
|
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='mathematics'>Mathematics<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
|
|
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
|
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='mathematics'>Mathematics</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
| ︙ | | | ︙ | |
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
|
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='networking'>Networking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
|
|
|
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
|
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='networking'>Networking</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
|
| ︙ | | | ︙ | |
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
|
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='page_parser_generator'>Page Parser Generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
|
|
|
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
|
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='page_parser_generator'>Page Parser Generator</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page'><a href="tcllib/files/apps/page.html">page</a></td>
<td class="#doctools_tocright">Parser Generator</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
|
| ︙ | | | ︙ | |
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='parsing_and_grammars'>Parsing and Grammars<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
|
|
|
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='parsing_and_grammars'>Parsing and Grammars</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt'><a href="tcllib/files/apps/pt.html">pt</a></td>
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
|
| ︙ | | | ︙ | |
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='procedures_arguments_parameters_options'>Procedures, arguments, parameters, options<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='programming_tools'>Programming tools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
|
|
|
|
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='procedures_arguments_parameters_options'>Procedures, arguments, parameters, options</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='programming_tools'>Programming tools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
|
| ︙ | | | ︙ | |
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
|
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='system'>System<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='tcloo'>TclOO<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
</table></dl>
<dl><dt><a name='terminal_control'>Terminal control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
|
|
|
|
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
|
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='system'>System</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='tcloo'>TclOO</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
</table></dl>
<dl><dt><a name='terminal_control'>Terminal control</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
| ︙ | | | ︙ | |
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='text_formatter_plugin'>Text formatter plugin<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
|
|
|
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='text_formatter_plugin'>Text formatter plugin</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_docidx'><a href="tcllib/files/modules/doctools2idx/export_docidx.html">doctools::idx::export::docidx</a></td>
<td class="#doctools_tocright">docidx export plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx_export_html'><a href="tcllib/files/modules/doctools2idx/idx_export_html.html">doctools::idx::export::html</a></td>
|
| ︙ | | | ︙ | |
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
|
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
</table></dl>
<dl><dt><a name='text_processing'>Text processing<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
|
|
|
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
|
<td class="#doctools_tocright">doctoc import plugin</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_import_json'><a href="tcllib/files/modules/doctools2toc/toc_import_json.html">doctools::toc::import::json</a></td>
<td class="#doctools_tocright">JSON import plugin</td>
</tr>
</table></dl>
<dl><dt><a name='text_processing'>Text processing</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
|
| ︙ | | | ︙ | |
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
|
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='transfer_module'>Transfer module<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
|
|
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
|
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='transfer_module'>Transfer module</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
| ︙ | | | ︙ | |
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='unfiled'>Unfiled<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
|
|
|
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='unfiled'>Unfiled</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
|
| ︙ | | | ︙ | |
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
|
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='utilities'>Utilities<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='utility'>Utility<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
|
|
|
|
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
|
<td class="#doctools_tocright">unit conversion</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='utilities'>Utilities</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='utility'>Utility</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
|
| ︙ | | | ︙ | |
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
|
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='validation_type_checking'>Validation, Type checking<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
|
|
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
|
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='validation_type_checking'>Validation, Type checking</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
| ︙ | | | ︙ | |
1811
1812
1813
1814
1815
1816
1817
1818
1819
|
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl></table></dl>
</dl><hr></body></html>
|
|
>
|
|
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
|
<td class="#doctools_tocleft" ><a name='valtype_usnpi'><a href="tcllib/files/modules/valtype/usnpi.html">valtype::usnpi</a></td>
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
</dl>
</dd></dl><hr></body></html>
|
Changes to idoc/www/toc1.html.
| ︙ | | | ︙ | |
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='modules'>Modules<dd>
<dl><dt><a name='aes'>aes<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='amazon_s3'>amazon-s3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
</table></dl>
<dl><dt><a name='asn'>asn<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
</table></dl>
<dl><dt><a name='base32'>base32<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
</table></dl>
<dl><dt><a name='base64'>base64<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='bee'>bee<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='bench'>bench<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3>Table Of Contents</h3>
<hr><dl><dt><h2></h2></dt><dd>
<dl><dt><a name='modules'>Modules</dt><dd>
<dl><dt><a name='aes'>aes</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='aes'><a href="tcllib/files/modules/aes/aes.html">aes</a></td>
<td class="#doctools_tocright">Implementation of the AES block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='amazon_s3'>amazon-s3</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='s3'><a href="tcllib/files/modules/amazon-s3/S3.html">S3</a></td>
<td class="#doctools_tocright">Amazon S3 Web Service Interface</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='xsxp'><a href="tcllib/files/modules/amazon-s3/xsxp.html">xsxp</a></td>
<td class="#doctools_tocright">eXtremely Simple Xml Parser</td>
</tr>
</table></dl>
<dl><dt><a name='asn'>asn</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='asn'><a href="tcllib/files/modules/asn/asn.html">asn</a></td>
<td class="#doctools_tocright">ASN.1 BER encoder/decoder</td>
</tr>
</table></dl>
<dl><dt><a name='base32'>base32</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32'><a href="tcllib/files/modules/base32/base32.html">base32</a></td>
<td class="#doctools_tocright">base32 standard encoding</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base32_core'><a href="tcllib/files/modules/base32/base32core.html">base32::core</a></td>
<td class="#doctools_tocright">Expanding basic base32 maps</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='base32_hex'><a href="tcllib/files/modules/base32/base32hex.html">base32::hex</a></td>
<td class="#doctools_tocright">base32 extended hex encoding</td>
</tr>
</table></dl>
<dl><dt><a name='base64'>base64</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ascii85'><a href="tcllib/files/modules/base64/ascii85.html">ascii85</a></td>
<td class="#doctools_tocright">ascii85-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='base64'><a href="tcllib/files/modules/base64/base64.html">base64</a></td>
<td class="#doctools_tocright">base64-encode/decode binary data</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuencode'><a href="tcllib/files/modules/base64/uuencode.html">uuencode</a></td>
<td class="#doctools_tocright">UU-encode/decode binary data</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yencode'><a href="tcllib/files/modules/base64/yencode.html">yencode</a></td>
<td class="#doctools_tocright">Y-encode/decode binary data</td>
</tr>
</table></dl>
<dl><dt><a name='bee'>bee</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bee'><a href="tcllib/files/modules/bee/bee.html">bee</a></td>
<td class="#doctools_tocright">BitTorrent Serialization Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='bench'>bench</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench'><a href="tcllib/files/modules/bench/bench.html">bench</a></td>
<td class="#doctools_tocright">bench - Processing benchmark suites</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='bench_in'><a href="tcllib/files/modules/bench/bench_read.html">bench::in</a></td>
|
| ︙ | | | ︙ | |
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='bibtex'>bibtex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
</table></dl>
<dl><dt><a name='blowfish'>blowfish<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='cache'>cache<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
</table></dl>
<dl><dt><a name='clock'>clock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
</table></dl>
<dl><dt><a name='cmdline'>cmdline<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
</table></dl>
<dl><dt><a name='comm'>comm<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
</table></dl>
<dl><dt><a name='control'>control<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>coroutine<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='counter'>counter<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
</table></dl>
<dl><dt><a name='crc'>crc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
</table></dl>
<dl><dt><a name='cron'>cron<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='csv'>csv<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
</table></dl>
<dl><dt><a name='debug'>debug<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='defer'>defer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
</table></dl>
<dl><dt><a name='des'>des<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
</table></dl>
<dl><dt><a name='dicttool'>dicttool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='dns'>dns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='docstrip'>docstrip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
</table></dl>
<dl><dt><a name='doctools'>doctools<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
<td class="#doctools_tocright">bench language introduction</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bench_lang_spec'><a href="tcllib/files/modules/bench/bench_lang_spec.html">bench_lang_spec</a></td>
<td class="#doctools_tocright">bench language specification</td>
</tr>
</table></dl>
<dl><dt><a name='bibtex'>bibtex</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='bibtex'><a href="tcllib/files/modules/bibtex/bibtex.html">bibtex</a></td>
<td class="#doctools_tocright">Parse bibtex files</td>
</tr>
</table></dl>
<dl><dt><a name='blowfish'>blowfish</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='blowfish'><a href="tcllib/files/modules/blowfish/blowfish.html">blowfish</a></td>
<td class="#doctools_tocright">Implementation of the Blowfish block cipher</td>
</tr>
</table></dl>
<dl><dt><a name='cache'>cache</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cache_async'><a href="tcllib/files/modules/cache/async.html">cache::async</a></td>
<td class="#doctools_tocright">Asynchronous in-memory cache</td>
</tr>
</table></dl>
<dl><dt><a name='clock'>clock</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='clock_iso8601'><a href="tcllib/files/modules/clock/iso8601.html">clock_iso8601</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='clock_rfc2822'><a href="tcllib/files/modules/clock/rfc2822.html">clock_rfc2822</a></td>
<td class="#doctools_tocright">Parsing ISO 8601 dates/times</td>
</tr>
</table></dl>
<dl><dt><a name='cmdline'>cmdline</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cmdline'><a href="tcllib/files/modules/cmdline/cmdline.html">cmdline</a></td>
<td class="#doctools_tocright">Procedures to process command lines and options.</td>
</tr>
</table></dl>
<dl><dt><a name='comm'>comm</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='comm'><a href="tcllib/files/modules/comm/comm.html">comm</a></td>
<td class="#doctools_tocright">A remote communication facility for Tcl (8.3 and later)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='comm_wire'><a href="tcllib/files/modules/comm/comm_wire.html">comm_wire</a></td>
<td class="#doctools_tocright">The comm wire protocol</td>
</tr>
</table></dl>
<dl><dt><a name='control'>control</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='control'><a href="tcllib/files/modules/control/control.html">control</a></td>
<td class="#doctools_tocright">Procedures for control flow structures.</td>
</tr>
</table></dl>
<dl><dt><a name='coroutine'>coroutine</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='coroutine'><a href="tcllib/files/modules/coroutine/tcllib_coroutine.html">coroutine</a></td>
<td class="#doctools_tocright">Coroutine based event and IO handling</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='coroutine_auto'><a href="tcllib/files/modules/coroutine/coro_auto.html">coroutine::auto</a></td>
<td class="#doctools_tocright">Automatic event and IO coroutine awareness</td>
</tr>
</table></dl>
<dl><dt><a name='counter'>counter</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='counter'><a href="tcllib/files/modules/counter/counter.html">counter</a></td>
<td class="#doctools_tocright">Procedures for counters and histograms</td>
</tr>
</table></dl>
<dl><dt><a name='crc'>crc</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cksum'><a href="tcllib/files/modules/crc/cksum.html">cksum</a></td>
<td class="#doctools_tocright">Calculate a cksum(1) compatible checksum</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='crc16'><a href="tcllib/files/modules/crc/crc16.html">crc16</a></td>
<td class="#doctools_tocright">Perform a 16bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='crc32'><a href="tcllib/files/modules/crc/crc32.html">crc32</a></td>
<td class="#doctools_tocright">Perform a 32bit Cyclic Redundancy Check</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sum'><a href="tcllib/files/modules/crc/sum.html">sum</a></td>
<td class="#doctools_tocright">Calculate a sum(1) compatible checksum</td>
</tr>
</table></dl>
<dl><dt><a name='cron'>cron</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='cron'><a href="tcllib/files/modules/cron/cron.html">cron</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='csv'>csv</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='csv'><a href="tcllib/files/modules/csv/csv.html">csv</a></td>
<td class="#doctools_tocright">Procedures to handle CSV data.</td>
</tr>
</table></dl>
<dl><dt><a name='debug'>debug</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug'><a href="tcllib/files/modules/debug/debug.html">debug</a></td>
<td class="#doctools_tocright">debug narrative - core</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_caller'><a href="tcllib/files/modules/debug/debug_caller.html">debug::caller</a></td>
<td class="#doctools_tocright">debug narrative - caller</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='debug_heartbeat'><a href="tcllib/files/modules/debug/debug_heartbeat.html">debug::heartbeat</a></td>
<td class="#doctools_tocright">debug narrative - heartbeat</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='debug_timestamp'><a href="tcllib/files/modules/debug/debug_timestamp.html">debug::timestamp</a></td>
<td class="#doctools_tocright">debug narrative - timestamping</td>
</tr>
</table></dl>
<dl><dt><a name='defer'>defer</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='defer'><a href="tcllib/files/modules/defer/defer.html">defer</a></td>
<td class="#doctools_tocright">Defered execution</td>
</tr>
</table></dl>
<dl><dt><a name='des'>des</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='des'><a href="tcllib/files/modules/des/des.html">des</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="tcllib/files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="tcllib/files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
</table></dl>
<dl><dt><a name='dicttool'>dicttool</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dicttool'><a href="tcllib/files/modules/dicttool/dicttool.html">dicttool</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='dns'>dns</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dns'><a href="tcllib/files/modules/dns/tcllib_dns.html">dns</a></td>
<td class="#doctools_tocright">Tcl Domain Name Service Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="tcllib/files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='docstrip'>docstrip</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docstrip'><a href="tcllib/files/modules/docstrip/docstrip.html">docstrip</a></td>
<td class="#doctools_tocright">Docstrip style source code extraction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docstrip_util'><a href="tcllib/files/modules/docstrip/docstrip_util.html">docstrip_util</a></td>
<td class="#doctools_tocright">Docstrip-related utilities</td>
</tr>
</table></dl>
<dl><dt><a name='doctools'>doctools</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='docidx_intro'><a href="tcllib/files/modules/doctools/docidx_intro.html">docidx_intro</a></td>
<td class="#doctools_tocright">docidx introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='docidx_lang_cmdref'><a href="tcllib/files/modules/doctools/docidx_lang_cmdref.html">docidx_lang_cmdref</a></td>
|
| ︙ | | | ︙ | |
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
|
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2base'>doctools2base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2idx'>doctools2idx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
|
|
|
|
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
|
<td class="#doctools_tocright">doctools plugin API reference</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='mpexpand'><a href="tcllib/files/modules/doctools/mpexpand.html">mpexpand</a></td>
<td class="#doctools_tocright">Markup processor</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2base'>doctools2base</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_html_cssdefaults'><a href="tcllib/files/modules/doctools2base/html_cssdefaults.html">doctools::html::cssdefaults</a></td>
<td class="#doctools_tocright">Default CSS style for HTML export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat'><a href="tcllib/files/modules/doctools2base/tcllib_msgcat.html">doctools::msgcat</a></td>
<td class="#doctools_tocright">Message catalog management for the various document parsers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools_nroff_man_macros'><a href="tcllib/files/modules/doctools2base/nroff_manmacros.html">doctools::nroff::man_macros</a></td>
<td class="#doctools_tocright">Default CSS style for NROFF export plugins</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_tcl_parse'><a href="tcllib/files/modules/doctools2base/tcl_parse.html">doctools::tcl::parse</a></td>
<td class="#doctools_tocright">Processing text in 'subst -novariables' format</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2idx'>doctools2idx</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2idx_introduction'><a href="tcllib/files/modules/doctools2idx/idx_introduction.html">doctools2idx_introduction</a></td>
<td class="#doctools_tocright">DocTools - Keyword indices</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_idx'><a href="tcllib/files/modules/doctools2idx/idx_container.html">doctools::idx</a></td>
|
| ︙ | | | ︙ | |
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
|
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2toc'>doctools2toc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
|
|
|
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
|
<td class="#doctools_tocright">Message catalog for the docidx parser (EN)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_idx_fr'><a href="tcllib/files/modules/doctools2idx/idx_msgcat_fr.html">doctools::msgcat::idx::fr</a></td>
<td class="#doctools_tocright">Message catalog for the docidx parser (FR)</td>
</tr>
</table></dl>
<dl><dt><a name='doctools2toc'>doctools2toc</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='doctools2toc_introduction'><a href="tcllib/files/modules/doctools2toc/toc_introduction.html">doctools2toc_introduction</a></td>
<td class="#doctools_tocright">DocTools - Tables of Contents</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_msgcat_toc_c'><a href="tcllib/files/modules/doctools2toc/toc_msgcat_c.html">doctools::msgcat::toc::c</a></td>
|
| ︙ | | | ︙ | |
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
|
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
</table></dl>
<dl><dt><a name='dtplite'>dtplite<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
</table></dl>
<dl><dt><a name='fileutil'>fileutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
</table></dl>
<dl><dt><a name='ftp'>ftp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
</table></dl>
<dl><dt><a name='ftpd'>ftpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='fumagic'>fumagic<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='generator'>generator<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
</table></dl>
<dl><dt><a name='gpx'>gpx<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_aycock'>grammar_aycock<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_fa'>grammar_fa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_me'>grammar_me<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
|
<td class="#doctools_tocright">Parsing text in doctoc format</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='doctools_toc_structure'><a href="tcllib/files/modules/doctools2toc/toc_structure.html">doctools::toc::structure</a></td>
<td class="#doctools_tocright">Doctoc serialization utilities</td>
</tr>
</table></dl>
<dl><dt><a name='dtplite'>dtplite</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/modules/dtplite/pkg_dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
</table></dl>
<dl><dt><a name='fileutil'>fileutil</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil'><a href="tcllib/files/modules/fileutil/fileutil.html">fileutil</a></td>
<td class="#doctools_tocright">Procedures implementing some file utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_multi'><a href="tcllib/files/modules/fileutil/multi.html">fileutil::multi</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather, standard object</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_multi_op'><a href="tcllib/files/modules/fileutil/multiop.html">fileutil::multi::op</a></td>
<td class="#doctools_tocright">Multi-file operation, scatter/gather</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_traverse'><a href="tcllib/files/modules/fileutil/traverse.html">fileutil_traverse</a></td>
<td class="#doctools_tocright">Iterative directory traversal</td>
</tr>
</table></dl>
<dl><dt><a name='ftp'>ftp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftp'><a href="tcllib/files/modules/ftp/ftp.html">ftp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the ftp protocol</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ftp_geturl'><a href="tcllib/files/modules/ftp/ftp_geturl.html">ftp::geturl</a></td>
<td class="#doctools_tocright">Uri handler for ftp urls</td>
</tr>
</table></dl>
<dl><dt><a name='ftpd'>ftpd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ftpd'><a href="tcllib/files/modules/ftpd/ftpd.html">ftpd</a></td>
<td class="#doctools_tocright">Tcl FTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='fumagic'>fumagic</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cfront'><a href="tcllib/files/modules/fumagic/cfront.html">fileutil::magic::cfront</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_cgen'><a href="tcllib/files/modules/fumagic/cgen.html">fileutil::magic::cgen</a></td>
<td class="#doctools_tocright">Generator core for compiler of magic(5) files</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_filetype'><a href="tcllib/files/modules/fumagic/filetypes.html">fileutil::magic::filetype</a></td>
<td class="#doctools_tocright">Procedures implementing file-type recognition</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='fileutil_magic_rt'><a href="tcllib/files/modules/fumagic/rtcore.html">fileutil::magic::rt</a></td>
<td class="#doctools_tocright">Runtime core for file type recognition engines written in pure Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='generator'>generator</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='generator'><a href="tcllib/files/modules/generator/generator.html">generator</a></td>
<td class="#doctools_tocright">Procedures for creating and using generators.</td>
</tr>
</table></dl>
<dl><dt><a name='gpx'>gpx</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='gpx'><a href="tcllib/files/modules/gpx/gpx.html">gpx</a></td>
<td class="#doctools_tocright">Extracts waypoints, tracks and routes from GPX files</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_aycock'>grammar_aycock</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_aycock'><a href="tcllib/files/modules/grammar_aycock/aycock.html">grammar::aycock</a></td>
<td class="#doctools_tocright">Aycock-Horspool-Earley parser generator for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_fa'>grammar_fa</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa'><a href="tcllib/files/modules/grammar_fa/fa.html">grammar::fa</a></td>
<td class="#doctools_tocright">Create and manipulate finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dacceptor'><a href="tcllib/files/modules/grammar_fa/dacceptor.html">grammar::fa::dacceptor</a></td>
<td class="#doctools_tocright">Create and use deterministic acceptors</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_fa_dexec'><a href="tcllib/files/modules/grammar_fa/dexec.html">grammar::fa::dexec</a></td>
<td class="#doctools_tocright">Execute deterministic finite automatons</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_fa_op'><a href="tcllib/files/modules/grammar_fa/faop.html">grammar::fa::op</a></td>
<td class="#doctools_tocright">Operations on finite automatons</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_me'>grammar_me</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu'><a href="tcllib/files/modules/grammar_me/me_cpu.html">grammar::me::cpu</a></td>
<td class="#doctools_tocright">Virtual machine implementation II for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_cpu_core'><a href="tcllib/files/modules/grammar_me/me_cpucore.html">grammar::me::cpu::core</a></td>
|
| ︙ | | | ︙ | |
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
|
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_peg'>grammar_peg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hook'>hook<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
</table></dl>
<dl><dt><a name='html'>html<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
</table></dl>
<dl><dt><a name='htmlparse'>htmlparse<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
</table></dl>
<dl><dt><a name='http'>http<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
</table></dl>
<dl><dt><a name='httpd'>httpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
</table></dl>
<dl><dt><a name='ident'>ident<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
</table></dl>
<dl><dt><a name='imap4'>imap4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
</table></dl>
<dl><dt><a name='inifile'>inifile<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
</table></dl>
<dl><dt><a name='interp'>interp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
</table></dl>
<dl><dt><a name='irc'>irc<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
</table></dl>
<dl><dt><a name='javascript'>javascript<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
</table></dl>
<dl><dt><a name='jpeg'>jpeg<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='json'>json<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
</table></dl>
<dl><dt><a name='lambda'>lambda<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
</table></dl>
<dl><dt><a name='lazyset'>lazyset<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
</table></dl>
<dl><dt><a name='ldap'>ldap<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
</table></dl>
<dl><dt><a name='log'>log<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
</table></dl>
<dl><dt><a name='map'>map<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
</table></dl>
<dl><dt><a name='mapproj'>mapproj<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
</table></dl>
<dl><dt><a name='markdown'>markdown<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
</table></dl>
<dl><dt><a name='math'>math<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
|
<td class="#doctools_tocright">Introduction to virtual machines for parsing token streams</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_me_vm'><a href="tcllib/files/modules/grammar_me/me_vm.html">grammar::me_vm</a></td>
<td class="#doctools_tocright">Virtual machine for parsing token streams</td>
</tr>
</table></dl>
<dl><dt><a name='grammar_peg'>grammar_peg</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='grammar_peg'><a href="tcllib/files/modules/grammar_peg/peg.html">grammar::peg</a></td>
<td class="#doctools_tocright">Create and manipulate parsing expression grammars</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='grammar_peg_interp'><a href="tcllib/files/modules/grammar_peg/peg_interp.html">grammar::peg::interp</a></td>
<td class="#doctools_tocright">Interpreter for parsing expression grammars</td>
</tr>
</table></dl>
<dl><dt><a name='hook'>hook</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='hook'><a href="tcllib/files/modules/hook/hook.html">hook</a></td>
<td class="#doctools_tocright">Hooks</td>
</tr>
</table></dl>
<dl><dt><a name='html'>html</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='html'><a href="tcllib/files/modules/html/html.html">html</a></td>
<td class="#doctools_tocright">Procedures to generate HTML structures</td>
</tr>
</table></dl>
<dl><dt><a name='htmlparse'>htmlparse</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='htmlparse'><a href="tcllib/files/modules/htmlparse/htmlparse.html">htmlparse</a></td>
<td class="#doctools_tocright">Procedures to parse HTML strings</td>
</tr>
</table></dl>
<dl><dt><a name='http'>http</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='autoproxy'><a href="tcllib/files/modules/http/autoproxy.html">autoproxy</a></td>
<td class="#doctools_tocright">Automatic HTTP proxy usage and authentication</td>
</tr>
</table></dl>
<dl><dt><a name='httpd'>httpd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/httpd/httpd.html">tool</a></td>
<td class="#doctools_tocright">A TclOO and coroutine based web server</td>
</tr>
</table></dl>
<dl><dt><a name='ident'>ident</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ident'><a href="tcllib/files/modules/ident/ident.html">ident</a></td>
<td class="#doctools_tocright">Ident protocol client</td>
</tr>
</table></dl>
<dl><dt><a name='imap4'>imap4</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='imap4'><a href="tcllib/files/modules/imap4/imap4.html">imap4</a></td>
<td class="#doctools_tocright">imap client-side tcl implementation of imap protocol</td>
</tr>
</table></dl>
<dl><dt><a name='inifile'>inifile</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='inifile'><a href="tcllib/files/modules/inifile/ini.html">inifile</a></td>
<td class="#doctools_tocright">Parsing of Windows INI files</td>
</tr>
</table></dl>
<dl><dt><a name='interp'>interp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='deleg_method'><a href="tcllib/files/modules/interp/deleg_method.html">deleg_method</a></td>
<td class="#doctools_tocright">Creation of comm delegates (snit methods)</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='deleg_proc'><a href="tcllib/files/modules/interp/deleg_proc.html">deleg_proc</a></td>
<td class="#doctools_tocright">Creation of comm delegates (procedures)</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='interp'><a href="tcllib/files/modules/interp/tcllib_interp.html">interp</a></td>
<td class="#doctools_tocright">Interp creation and aliasing</td>
</tr>
</table></dl>
<dl><dt><a name='irc'>irc</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='irc'><a href="tcllib/files/modules/irc/irc.html">irc</a></td>
<td class="#doctools_tocright">Create IRC connection and interface.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='picoirc'><a href="tcllib/files/modules/irc/picoirc.html">picoirc</a></td>
<td class="#doctools_tocright">Small and simple embeddable IRC client.</td>
</tr>
</table></dl>
<dl><dt><a name='javascript'>javascript</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='javascript'><a href="tcllib/files/modules/javascript/javascript.html">javascript</a></td>
<td class="#doctools_tocright">Procedures to generate HTML and Java Script structures.</td>
</tr>
</table></dl>
<dl><dt><a name='jpeg'>jpeg</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='jpeg'><a href="tcllib/files/modules/jpeg/jpeg.html">jpeg</a></td>
<td class="#doctools_tocright">JPEG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='json'>json</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='json'><a href="tcllib/files/modules/json/json.html">json</a></td>
<td class="#doctools_tocright">JSON parser</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='json_write'><a href="tcllib/files/modules/json/json_write.html">json::write</a></td>
<td class="#doctools_tocright">JSON generation</td>
</tr>
</table></dl>
<dl><dt><a name='lambda'>lambda</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lambda'><a href="tcllib/files/modules/lambda/lambda.html">lambda</a></td>
<td class="#doctools_tocright">Utility commands for anonymous procedures</td>
</tr>
</table></dl>
<dl><dt><a name='lazyset'>lazyset</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='lazyset'><a href="tcllib/files/modules/lazyset/lazyset.html">lazyset</a></td>
<td class="#doctools_tocright">Lazy evaluation</td>
</tr>
</table></dl>
<dl><dt><a name='ldap'>ldap</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ldap'><a href="tcllib/files/modules/ldap/ldap.html">ldap</a></td>
<td class="#doctools_tocright">LDAP client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ldapx'><a href="tcllib/files/modules/ldap/ldapx.html">ldapx</a></td>
<td class="#doctools_tocright">LDAP extended object interface</td>
</tr>
</table></dl>
<dl><dt><a name='log'>log</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='log'><a href="tcllib/files/modules/log/log.html">log</a></td>
<td class="#doctools_tocright">Procedures to log messages of libraries and applications.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger'><a href="tcllib/files/modules/log/logger.html">logger</a></td>
<td class="#doctools_tocright">System to control logging of events.</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='logger_appender'><a href="tcllib/files/modules/log/loggerAppender.html">logger::appender</a></td>
<td class="#doctools_tocright">Collection of predefined appenders for logger</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='logger_utils'><a href="tcllib/files/modules/log/loggerUtils.html">logger::utils</a></td>
<td class="#doctools_tocright">Utilities for logger</td>
</tr>
</table></dl>
<dl><dt><a name='map'>map</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_geocode_nominatim'><a href="tcllib/files/modules/map/map_geocode_nominatim.html">map::geocode::nominatim</a></td>
<td class="#doctools_tocright">Resolving geographical names with a Nominatim service</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy'><a href="tcllib/files/modules/map/map_slippy.html">map::slippy</a></td>
<td class="#doctools_tocright">Common code for slippy based map packages</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='map_slippy_cache'><a href="tcllib/files/modules/map/map_slippy_cache.html">map::slippy::cache</a></td>
<td class="#doctools_tocright">Management of a tile cache in the local filesystem</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='map_slippy_fetcher'><a href="tcllib/files/modules/map/map_slippy_fetcher.html">map::slippy::fetcher</a></td>
<td class="#doctools_tocright">Accessing a server providing tiles for slippy-based maps</td>
</tr>
</table></dl>
<dl><dt><a name='mapproj'>mapproj</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mapproj'><a href="tcllib/files/modules/mapproj/mapproj.html">mapproj</a></td>
<td class="#doctools_tocright">Map projection routines</td>
</tr>
</table></dl>
<dl><dt><a name='markdown'>markdown</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='markdown'><a href="tcllib/files/modules/markdown/markdown.html">markdown</a></td>
<td class="#doctools_tocright">Converts Markdown text to HTML</td>
</tr>
</table></dl>
<dl><dt><a name='math'>math</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='math'><a href="tcllib/files/modules/math/math.html">math</a></td>
<td class="#doctools_tocright">Tcl Math Library</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='math_bigfloat'><a href="tcllib/files/modules/math/bigfloat.html">math::bigfloat</a></td>
|
| ︙ | | | ︙ | |
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
|
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
</table></dl>
<dl><dt><a name='md4'>md4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5'>md5<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5crypt'>md5crypt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
</table></dl>
<dl><dt><a name='mime'>mime<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
</table></dl>
<dl><dt><a name='multiplexer'>multiplexer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
</table></dl>
<dl><dt><a name='namespacex'>namespacex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
</table></dl>
<dl><dt><a name='ncgi'>ncgi<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='nettool'>nettool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
</table></dl>
<dl><dt><a name='nmea'>nmea<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
</table></dl>
<dl><dt><a name='nns'>nns<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
|
<td class="#doctools_tocright">Trigonometric anf hyperbolic functions</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="tcllib/files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
</table></dl>
<dl><dt><a name='md4'>md4</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md4'><a href="tcllib/files/modules/md4/md4.html">md4</a></td>
<td class="#doctools_tocright">MD4 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5'>md5</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5'><a href="tcllib/files/modules/md5/md5.html">md5</a></td>
<td class="#doctools_tocright">MD5 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='md5crypt'>md5crypt</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='md5crypt'><a href="tcllib/files/modules/md5crypt/md5crypt.html">md5crypt</a></td>
<td class="#doctools_tocright">MD5-based password encryption</td>
</tr>
</table></dl>
<dl><dt><a name='mime'>mime</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='mime'><a href="tcllib/files/modules/mime/mime.html">mime</a></td>
<td class="#doctools_tocright">Manipulation of MIME body parts</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='smtp'><a href="tcllib/files/modules/mime/smtp.html">smtp</a></td>
<td class="#doctools_tocright">Client-side tcl implementation of the smtp protocol</td>
</tr>
</table></dl>
<dl><dt><a name='multiplexer'>multiplexer</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='multiplexer'><a href="tcllib/files/modules/multiplexer/multiplexer.html">multiplexer</a></td>
<td class="#doctools_tocright">One-to-many communication with sockets.</td>
</tr>
</table></dl>
<dl><dt><a name='namespacex'>namespacex</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='namespacex'><a href="tcllib/files/modules/namespacex/namespacex.html">namespacex</a></td>
<td class="#doctools_tocright">Namespace utility commands</td>
</tr>
</table></dl>
<dl><dt><a name='ncgi'>ncgi</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ncgi'><a href="tcllib/files/modules/ncgi/ncgi.html">ncgi</a></td>
<td class="#doctools_tocright">Procedures to manipulate CGI values.</td>
</tr>
</table></dl>
<dl><dt><a name='nettool'>nettool</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nettool'><a href="tcllib/files/modules/nettool/nettool.html">nettool</a></td>
<td class="#doctools_tocright">Tools for networked applications</td>
</tr>
</table></dl>
<dl><dt><a name='nmea'>nmea</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nmea'><a href="tcllib/files/modules/nmea/nmea.html">nmea</a></td>
<td class="#doctools_tocright">Process NMEA data</td>
</tr>
</table></dl>
<dl><dt><a name='nns'>nns</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nameserv'><a href="tcllib/files/modules/nns/nns_client.html">nameserv</a></td>
<td class="#doctools_tocright">Name service facility, Client</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nameserv_auto'><a href="tcllib/files/modules/nns/nns_auto.html">nameserv::auto</a></td>
|
| ︙ | | | ︙ | |
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
|
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
</table></dl>
<dl><dt><a name='nntp'>nntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
</table></dl>
<dl><dt><a name='ntp'>ntp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
</table></dl>
<dl><dt><a name='oauth'>oauth<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
</table></dl>
<dl><dt><a name='oometa'>oometa<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
</table></dl>
<dl><dt><a name='ooutil'>ooutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
</table></dl>
<dl><dt><a name='otp'>otp<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
</table></dl>
<dl><dt><a name='page'>page<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
|
|
|
|
|
|
|
|
|
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
|
<td class="#doctools_tocright">Name service facility, Server</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns_intro'><a href="tcllib/files/modules/nns/nns_intro.html">nns_intro</a></td>
<td class="#doctools_tocright">Name service facility, introduction</td>
</tr>
</table></dl>
<dl><dt><a name='nntp'>nntp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='nntp'><a href="tcllib/files/modules/nntp/nntp.html">nntp</a></td>
<td class="#doctools_tocright">Tcl client for the NNTP protocol</td>
</tr>
</table></dl>
<dl><dt><a name='ntp'>ntp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ntp_time'><a href="tcllib/files/modules/ntp/ntp_time.html">ntp_time</a></td>
<td class="#doctools_tocright">Tcl Time Service Client</td>
</tr>
</table></dl>
<dl><dt><a name='oauth'>oauth</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oauth'><a href="tcllib/files/modules/oauth/oauth.html">oauth</a></td>
<td class="#doctools_tocright">oauth API base signature</td>
</tr>
</table></dl>
<dl><dt><a name='oometa'>oometa</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oometa'><a href="tcllib/files/modules/oometa/oometa.html">oometa</a></td>
<td class="#doctools_tocright">oo::meta A data registry for classess</td>
</tr>
</table></dl>
<dl><dt><a name='ooutil'>ooutil</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/ooutil/ooutil.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
</table></dl>
<dl><dt><a name='otp'>otp</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='otp'><a href="tcllib/files/modules/otp/otp.html">otp</a></td>
<td class="#doctools_tocright">One-Time Passwords</td>
</tr>
</table></dl>
<dl><dt><a name='page'>page</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_intro'><a href="tcllib/files/modules/page/page_intro.html">page_intro</a></td>
<td class="#doctools_tocright">page introduction</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='page_pluginmgr'><a href="tcllib/files/modules/page/page_pluginmgr.html">page_pluginmgr</a></td>
|
| ︙ | | | ︙ | |
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='pki'>pki<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
</table></dl>
<dl><dt><a name='pluginmgr'>pluginmgr<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
</table></dl>
<dl><dt><a name='png'>png<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='pop3'>pop3<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
</table></dl>
<dl><dt><a name='pop3d'>pop3d<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
</table></dl>
<dl><dt><a name='practcl'>practcl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
</table></dl>
<dl><dt><a name='processman'>processman<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='profiler'>profiler<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
</table></dl>
<dl><dt><a name='pt'>pt<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
|
|
|
|
|
|
|
|
|
|
|
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
|
<td class="#doctools_tocright">page PEG transformation utilities</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='page_util_quote'><a href="tcllib/files/modules/page/page_util_quote.html">page_util_quote</a></td>
<td class="#doctools_tocright">page character quoting utilities</td>
</tr>
</table></dl>
<dl><dt><a name='pki'>pki</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pki'><a href="tcllib/files/modules/pki/pki.html">pki</a></td>
<td class="#doctools_tocright">Implementation of the public key cipher</td>
</tr>
</table></dl>
<dl><dt><a name='pluginmgr'>pluginmgr</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pluginmgr'><a href="tcllib/files/modules/pluginmgr/pluginmgr.html">pluginmgr</a></td>
<td class="#doctools_tocright">Manage a plugin</td>
</tr>
</table></dl>
<dl><dt><a name='png'>png</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='png'><a href="tcllib/files/modules/png/png.html">png</a></td>
<td class="#doctools_tocright">PNG querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='pop3'>pop3</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3'><a href="tcllib/files/modules/pop3/pop3.html">pop3</a></td>
<td class="#doctools_tocright">Tcl client for POP3 email protocol</td>
</tr>
</table></dl>
<dl><dt><a name='pop3d'>pop3d</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d'><a href="tcllib/files/modules/pop3d/pop3d.html">pop3d</a></td>
<td class="#doctools_tocright">Tcl POP3 server implementation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pop3d_dbox'><a href="tcllib/files/modules/pop3d/pop3d_dbox.html">pop3d::dbox</a></td>
<td class="#doctools_tocright">Simple mailbox database for pop3d</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pop3d_udb'><a href="tcllib/files/modules/pop3d/pop3d_udb.html">pop3d::udb</a></td>
<td class="#doctools_tocright">Simple user database for pop3d</td>
</tr>
</table></dl>
<dl><dt><a name='practcl'>practcl</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='practcl'><a href="tcllib/files/modules/practcl/practcl.html">practcl</a></td>
<td class="#doctools_tocright">The Practcl Module</td>
</tr>
</table></dl>
<dl><dt><a name='processman'>processman</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='processman'><a href="tcllib/files/modules/processman/processman.html">processman</a></td>
<td class="#doctools_tocright">Tool for automating the period callback of commands</td>
</tr>
</table></dl>
<dl><dt><a name='profiler'>profiler</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='profiler'><a href="tcllib/files/modules/profiler/profiler.html">profiler</a></td>
<td class="#doctools_tocright">Tcl source code profiler</td>
</tr>
</table></dl>
<dl><dt><a name='pt'>pt</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='pt_ast'><a href="tcllib/files/modules/pt/pt_astree.html">pt::ast</a></td>
<td class="#doctools_tocright">Abstract Syntax Tree Serialization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_cparam_configuration_critcl'><a href="tcllib/files/modules/pt/pt_cparam_config_critcl.html">pt::cparam::configuration::critcl</a></td>
|
| ︙ | | | ︙ | |
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='rc4'>rc4<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
</table></dl>
<dl><dt><a name='rcs'>rcs<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
</table></dl>
<dl><dt><a name='report'>report<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
</table></dl>
<dl><dt><a name='rest'>rest<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
</table></dl>
<dl><dt><a name='ripemd'>ripemd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='sasl'>sasl<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='sha1'>sha1<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='simulation'>simulation<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='smtpd'>smtpd<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='snit'>snit<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
</table></dl>
<dl><dt><a name='soundex'>soundex<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
</table></dl>
<dl><dt><a name='stooop'>stooop<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
</table></dl>
<dl><dt><a name='string'>string<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
</table></dl>
<dl><dt><a name='stringprep'>stringprep<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
</table></dl>
<dl><dt><a name='struct'>struct<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
|
<td class="#doctools_tocright">Parser API</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='pt_peg_op'><a href="tcllib/files/modules/pt/pt_peg_op.html">pt_peg_op</a></td>
<td class="#doctools_tocright">Parser Tools PE Grammar Utility Operations</td>
</tr>
</table></dl>
<dl><dt><a name='rc4'>rc4</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rc4'><a href="tcllib/files/modules/rc4/rc4.html">rc4</a></td>
<td class="#doctools_tocright">Implementation of the RC4 stream cipher</td>
</tr>
</table></dl>
<dl><dt><a name='rcs'>rcs</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rcs'><a href="tcllib/files/modules/rcs/rcs.html">rcs</a></td>
<td class="#doctools_tocright">RCS low level utilities</td>
</tr>
</table></dl>
<dl><dt><a name='report'>report</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='report'><a href="tcllib/files/modules/report/report.html">report</a></td>
<td class="#doctools_tocright">Create and manipulate report objects</td>
</tr>
</table></dl>
<dl><dt><a name='rest'>rest</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='rest'><a href="tcllib/files/modules/rest/rest.html">rest</a></td>
<td class="#doctools_tocright">define REST web APIs and call them inline or asychronously</td>
</tr>
</table></dl>
<dl><dt><a name='ripemd'>ripemd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='ripemd128'><a href="tcllib/files/modules/ripemd/ripemd128.html">ripemd128</a></td>
<td class="#doctools_tocright">RIPEMD-128 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='ripemd160'><a href="tcllib/files/modules/ripemd/ripemd160.html">ripemd160</a></td>
<td class="#doctools_tocright">RIPEMD-160 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='sasl'>sasl</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl'><a href="tcllib/files/modules/sasl/sasl.html">SASL</a></td>
<td class="#doctools_tocright">Implementation of SASL mechanisms for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_ntlm'><a href="tcllib/files/modules/sasl/ntlm.html">SASL::NTLM</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sasl_scram'><a href="tcllib/files/modules/sasl/scram.html">SASL::SCRAM</a></td>
<td class="#doctools_tocright">Implementation of SASL SCRAM mechanism for Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sasl_xgoogletoken'><a href="tcllib/files/modules/sasl/gtoken.html">SASL::XGoogleToken</a></td>
<td class="#doctools_tocright">Implementation of SASL NTLM mechanism for Tcl</td>
</tr>
</table></dl>
<dl><dt><a name='sha1'>sha1</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='sha1'><a href="tcllib/files/modules/sha1/sha1.html">sha1</a></td>
<td class="#doctools_tocright">SHA1 Message-Digest Algorithm</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='sha256'><a href="tcllib/files/modules/sha1/sha256.html">sha256</a></td>
<td class="#doctools_tocright">SHA256 Message-Digest Algorithm</td>
</tr>
</table></dl>
<dl><dt><a name='simulation'>simulation</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_annealing'><a href="tcllib/files/modules/simulation/annealing.html">simulation::annealing</a></td>
<td class="#doctools_tocright">Simulated annealing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='simulation_montecarlo'><a href="tcllib/files/modules/simulation/montecarlo.html">simulation::montecarlo</a></td>
<td class="#doctools_tocright">Monte Carlo simulations</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='simulation_random'><a href="tcllib/files/modules/simulation/simulation_random.html">simulation::random</a></td>
<td class="#doctools_tocright">Pseudo-random number generators</td>
</tr>
</table></dl>
<dl><dt><a name='smtpd'>smtpd</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='smtpd'><a href="tcllib/files/modules/smtpd/smtpd.html">smtpd</a></td>
<td class="#doctools_tocright">Tcl SMTP server implementation</td>
</tr>
</table></dl>
<dl><dt><a name='snit'>snit</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='snit'><a href="tcllib/files/modules/snit/snit.html">snit</a></td>
<td class="#doctools_tocright">Snit's Not Incr Tcl</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='snitfaq'><a href="tcllib/files/modules/snit/snitfaq.html">snitfaq</a></td>
<td class="#doctools_tocright">Snit Frequently Asked Questions</td>
</tr>
</table></dl>
<dl><dt><a name='soundex'>soundex</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='soundex'><a href="tcllib/files/modules/soundex/soundex.html">soundex</a></td>
<td class="#doctools_tocright">Soundex</td>
</tr>
</table></dl>
<dl><dt><a name='stooop'>stooop</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stooop'><a href="tcllib/files/modules/stooop/stooop.html">stooop</a></td>
<td class="#doctools_tocright">Object oriented extension.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='switched'><a href="tcllib/files/modules/stooop/switched.html">switched</a></td>
<td class="#doctools_tocright">switch/option management.</td>
</tr>
</table></dl>
<dl><dt><a name='string'>string</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='string_token'><a href="tcllib/files/modules/string/token.html">string::token</a></td>
<td class="#doctools_tocright">Regex based iterative lexing</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='string_token_shell'><a href="tcllib/files/modules/string/token_shell.html">string::token::shell</a></td>
<td class="#doctools_tocright">Parsing of shell command line</td>
</tr>
</table></dl>
<dl><dt><a name='stringprep'>stringprep</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='stringprep'><a href="tcllib/files/modules/stringprep/stringprep.html">stringprep</a></td>
<td class="#doctools_tocright">Implementation of stringprep</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='stringprep_data'><a href="tcllib/files/modules/stringprep/stringprep_data.html">stringprep::data</a></td>
<td class="#doctools_tocright">stringprep data tables, generated, internal</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='unicode'><a href="tcllib/files/modules/stringprep/unicode.html">unicode</a></td>
<td class="#doctools_tocright">Implementation of Unicode normalization</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='unicode_data'><a href="tcllib/files/modules/stringprep/unicode_data.html">unicode::data</a></td>
<td class="#doctools_tocright">unicode data tables, generated, internal</td>
</tr>
</table></dl>
<dl><dt><a name='struct'>struct</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='struct_disjointset'><a href="tcllib/files/modules/struct/disjointset.html">struct::disjointset</a></td>
<td class="#doctools_tocright">Disjoint set data structure</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_graph'><a href="tcllib/files/modules/struct/graph.html">struct::graph</a></td>
|
| ︙ | | | ︙ | |
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='tar'>tar<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='tepam'>tepam<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='term'>term<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
|
|
|
|
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
|
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='struct_tree_v1'><a href="tcllib/files/modules/struct/struct_tree1.html">struct::tree_v1</a></td>
<td class="#doctools_tocright">Create and manipulate tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='tar'>tar</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tar'><a href="tcllib/files/modules/tar/tar.html">tar</a></td>
<td class="#doctools_tocright">Tar file creation, extraction & manipulation</td>
</tr>
</table></dl>
<dl><dt><a name='tepam'>tepam</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam'><a href="tcllib/files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_argument_dialogbox'><a href="tcllib/files/modules/tepam/tepam_argument_dialogbox.html">tepam::argument_dialogbox</a></td>
<td class="#doctools_tocright">TEPAM argument_dialogbox, reference manual</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tepam_doc_gen'><a href="tcllib/files/modules/tepam/tepam_doc_gen.html">tepam::doc_gen</a></td>
<td class="#doctools_tocright">TEPAM DOC Generation, reference manual</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tepam_procedure'><a href="tcllib/files/modules/tepam/tepam_procedure.html">tepam::procedure</a></td>
<td class="#doctools_tocright">TEPAM procedure, reference manual</td>
</tr>
</table></dl>
<dl><dt><a name='term'>term</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='term'><a href="tcllib/files/modules/term/term.html">term</a></td>
<td class="#doctools_tocright">General terminal control</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_ansi_code'><a href="tcllib/files/modules/term/ansi_code.html">term::ansi::code</a></td>
|
| ︙ | | | ︙ | |
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='textutil'>textutil<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
|
|
|
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
|
<td class="#doctools_tocright">Keyboard dispatch from terminals</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='term_send'><a href="tcllib/files/modules/term/term_send.html">term::send</a></td>
<td class="#doctools_tocright">General output to terminals</td>
</tr>
</table></dl>
<dl><dt><a name='textutil'>textutil</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='textutil'><a href="tcllib/files/modules/textutil/textutil.html">textutil</a></td>
<td class="#doctools_tocright">Procedures to manipulate texts and strings.</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_adjust'><a href="tcllib/files/modules/textutil/adjust.html">textutil::adjust</a></td>
|
| ︙ | | | ︙ | |
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
|
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
</table></dl>
<dl><dt><a name='tie'>tie<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
</table></dl>
<dl><dt><a name='tiff'>tiff<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='tool'>tool<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='transfer'>transfer<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
|
|
|
|
|
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
|
<td class="#doctools_tocright">Procedures to (un)tabify strings</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='textutil_trim'><a href="tcllib/files/modules/textutil/trim.html">textutil::trim</a></td>
<td class="#doctools_tocright">Procedures to trim strings</td>
</tr>
</table></dl>
<dl><dt><a name='tie'>tie</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie.html">tie</a></td>
<td class="#doctools_tocright">Array persistence</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tie'><a href="tcllib/files/modules/tie/tie_std.html">tie</a></td>
<td class="#doctools_tocright">Array persistence, standard data sources</td>
</tr>
</table></dl>
<dl><dt><a name='tiff'>tiff</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tiff'><a href="tcllib/files/modules/tiff/tiff.html">tiff</a></td>
<td class="#doctools_tocright">TIFF reading, writing, and querying and manipulation of meta data</td>
</tr>
</table></dl>
<dl><dt><a name='tool'>tool</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='oo_util'><a href="tcllib/files/modules/tool/meta.html">oo::util</a></td>
<td class="#doctools_tocright">Utility commands for TclOO</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tool'><a href="tcllib/files/modules/tool/tool.html">tool</a></td>
<td class="#doctools_tocright">TclOO Library (TOOL) Framework</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tool_dict_ensemble'><a href="tcllib/files/modules/tool/tool_dict_ensemble.html">tool::dict_ensemble</a></td>
<td class="#doctools_tocright">Dictionary Tools</td>
</tr>
</table></dl>
<dl><dt><a name='transfer'>transfer</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_connect'><a href="tcllib/files/modules/transfer/connect.html">transfer::connect</a></td>
<td class="#doctools_tocright">Connection setup</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='transfer_copy'><a href="tcllib/files/modules/transfer/copyops.html">transfer::copy</a></td>
|
| ︙ | | | ︙ | |
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='treeql'>treeql<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='try'>try<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='udpcluster'>udpcluster<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
</table></dl>
<dl><dt><a name='uev'>uev<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
</table></dl>
<dl><dt><a name='units'>units<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
</table></dl>
<dl><dt><a name='uri'>uri<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
</table></dl>
<dl><dt><a name='uuid'>uuid<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='valtype'>valtype<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
|
|
|
|
|
|
|
|
|
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
|
<td class="#doctools_tocright">Data source</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='transfer_transmitter'><a href="tcllib/files/modules/transfer/transmitter.html">transfer::transmitter</a></td>
<td class="#doctools_tocright">Data source</td>
</tr>
</table></dl>
<dl><dt><a name='treeql'>treeql</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='treeql'><a href="tcllib/files/modules/treeql/treeql.html">treeql</a></td>
<td class="#doctools_tocright">Query tree objects</td>
</tr>
</table></dl>
<dl><dt><a name='try'>try</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='throw'><a href="tcllib/files/modules/try/tcllib_throw.html">throw</a></td>
<td class="#doctools_tocright">throw - Throw an error exception with a message</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='try'><a href="tcllib/files/modules/try/tcllib_try.html">try</a></td>
<td class="#doctools_tocright">try - Trap and process errors and exceptions</td>
</tr>
</table></dl>
<dl><dt><a name='udpcluster'>udpcluster</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='udpcluster'><a href="tcllib/files/modules/udpcluster/udpcluster.html">udpcluster</a></td>
<td class="#doctools_tocright">UDP Peer-to-Peer cluster</td>
</tr>
</table></dl>
<dl><dt><a name='uev'>uev</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uevent'><a href="tcllib/files/modules/uev/uevent.html">uevent</a></td>
<td class="#doctools_tocright">User events</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uevent_onidle'><a href="tcllib/files/modules/uev/uevent_onidle.html">uevent::onidle</a></td>
<td class="#doctools_tocright">Request merging and deferal to idle time</td>
</tr>
</table></dl>
<dl><dt><a name='units'>units</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='units'><a href="tcllib/files/modules/units/units.html">units</a></td>
<td class="#doctools_tocright">unit conversion</td>
</tr>
</table></dl>
<dl><dt><a name='uri'>uri</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uri'><a href="tcllib/files/modules/uri/uri.html">uri</a></td>
<td class="#doctools_tocright">URI utilities</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='uri_urn'><a href="tcllib/files/modules/uri/urn-scheme.html">uri_urn</a></td>
<td class="#doctools_tocright">URI utilities, URN scheme</td>
</tr>
</table></dl>
<dl><dt><a name='uuid'>uuid</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='uuid'><a href="tcllib/files/modules/uuid/uuid.html">uuid</a></td>
<td class="#doctools_tocright">UUID generation and comparison</td>
</tr>
</table></dl>
<dl><dt><a name='valtype'>valtype</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_common'><a href="tcllib/files/modules/valtype/valtype_common.html">valtype::common</a></td>
<td class="#doctools_tocright">Validation, common code</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='valtype_creditcard_amex'><a href="tcllib/files/modules/valtype/cc_amex.html">valtype::creditcard::amex</a></td>
|
| ︙ | | | ︙ | |
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
|
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_base'>virtchannel_base<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
|
|
|
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
|
<td class="#doctools_tocright">Validation for USNPI</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='valtype_verhoeff'><a href="tcllib/files/modules/valtype/verhoeff.html">valtype::verhoeff</a></td>
<td class="#doctools_tocright">Validation for plain number with a VERHOEFF checkdigit</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_base'>virtchannel_base</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_cat'><a href="tcllib/files/modules/virtchannel_base/cat.html">tcl::chan::cat</a></td>
<td class="#doctools_tocright">Concatenation channel</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_facade'><a href="tcllib/files/modules/virtchannel_base/facade.html">tcl::chan::facade</a></td>
|
| ︙ | | | ︙ | |
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
|
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_core'>virtchannel_core<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_transform'>virtchannel_transform<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
|
|
|
|
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
|
<td class="#doctools_tocright">Zero channel</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_randomseed'><a href="tcllib/files/modules/virtchannel_base/randseed.html">tcl::randomseed</a></td>
<td class="#doctools_tocright">Utilities for random channels</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_core'>virtchannel_core</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_chan_core'><a href="tcllib/files/modules/virtchannel_core/core.html">tcl::chan::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel support</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_chan_events'><a href="tcllib/files/modules/virtchannel_core/events.html">tcl::chan::events</a></td>
<td class="#doctools_tocright">Event support for reflected/virtual channels</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_core'><a href="tcllib/files/modules/virtchannel_core/transformcore.html">tcl::transform::core</a></td>
<td class="#doctools_tocright">Basic reflected/virtual channel transform support</td>
</tr>
</table></dl>
<dl><dt><a name='virtchannel_transform'>virtchannel_transform</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_transform_adler32'><a href="tcllib/files/modules/virtchannel_transform/adler32.html">tcl::transform::adler32</a></td>
<td class="#doctools_tocright">Adler32 transformation</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_base64'><a href="tcllib/files/modules/virtchannel_transform/vt_base64.html">tcl::transform::base64</a></td>
|
| ︙ | | | ︙ | |
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='websocket'>websocket<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='wip'>wip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='yaml'>yaml<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='zip'>zip<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl></table></dl>
</dl><hr></body></html>
|
|
|
|
|
|
>
|
|
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
|
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="tcllib/files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
</table></dl>
<dl><dt><a name='websocket'>websocket</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='websocket'><a href="tcllib/files/modules/websocket/websocket.html">websocket</a></td>
<td class="#doctools_tocright">Tcl implementation of the websocket protocol</td>
</tr>
</table></dl>
<dl><dt><a name='wip'>wip</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='wip'><a href="tcllib/files/modules/wip/wip.html">wip</a></td>
<td class="#doctools_tocright">Word Interpreter</td>
</tr>
</table></dl>
<dl><dt><a name='yaml'>yaml</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='huddle'><a href="tcllib/files/modules/yaml/huddle.html">huddle</a></td>
<td class="#doctools_tocright">Create and manipulate huddle object</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='yaml'><a href="tcllib/files/modules/yaml/yaml.html">yaml</a></td>
<td class="#doctools_tocright">YAML Format Encoder/Decoder</td>
</tr>
</table></dl>
<dl><dt><a name='zip'>zip</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_decode'><a href="tcllib/files/modules/zip/decode.html">zipfile::decode</a></td>
<td class="#doctools_tocright">Access to zip archives</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='zipfile_encode'><a href="tcllib/files/modules/zip/encode.html">zipfile::encode</a></td>
<td class="#doctools_tocright">Generation of zip archives</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='zipfile_mkzip'><a href="tcllib/files/modules/zip/mkzip.html">zipfile::mkzip</a></td>
<td class="#doctools_tocright">Build a zip archive</td>
</tr>
</table></dl>
</dl>
</dd></dl><hr></body></html>
|
Changes to idoc/www/toc2.html.
| ︙ | | | ︙ | |
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3> Table Of Contents </h3>
<hr><dl><dt><h2> </h2><dd>
<dl><dt><a name='applications'>Applications<dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
|
|
|
|
|
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
<hr> [
<a href="../../../../home">Tcllib Home</a>
| <a href="index.html">Keyword Index</a>
| <a href="toc0.html">Categories</a>
| <a href="toc1.html">Modules</a>
| <a href="toc2.html">Applications</a>
] <hr>
<h3>Table Of Contents</h3>
<hr><dl><dt><h2></h2></dt><dd>
<dl><dt><a name='applications'>Applications</dt><dd>
<table class="#doctools_toc">
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='dtplite'><a href="tcllib/files/apps/dtplite.html">dtplite</a></td>
<td class="#doctools_tocright">Lightweight DocTools Markup Processor</td>
</tr>
<tr class="#doctools_tocodd" >
<td class="#doctools_tocleft" ><a name='nns'><a href="tcllib/files/apps/nns.html">nns</a></td>
|
| ︙ | | | ︙ | |
42
43
44
45
46
47
48
49
|
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
</table></dl>
</dl><hr></body></html>
|
|
|
42
43
44
45
46
47
48
49
|
<td class="#doctools_tocright">Parser Tools Application</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="tcllib/files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
</table></dl>
</dd></dl><hr></body></html>
|
Changes to modules/doctools/mpformats/_markdown.tcl.
| ︙ | | | ︙ | |
45
46
47
48
49
50
51
52
53
54
55
56
57
58
|
proc Em {text} { return *${text}* }
##
# # ## ### ##### ########
##
set __comments 0
proc MDComment {text} {
global __comments
Text "\n\[//[format %09d [incr __comments]]\]: # ($text)"
}
proc MDCDone {} {
|
>
>
|
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
proc Em {text} { return *${text}* }
##
# # ## ### ##### ########
##
set __comments 0
proc MDCInit {} { global __comments ; set __comments 0 }
proc MDComment {text} {
global __comments
Text "\n\[//[format %09d [incr __comments]]\]: # ($text)"
}
proc MDCDone {} {
|
| ︙ | | | ︙ | |
Changes to modules/doctools/mpformats/fmt.markdown.
| ︙ | | | ︙ | |
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
proc fmt_image {text {label {}}} {
# text = symbolic name of the image.
# formatting based on the available data ...
set img [dt_imgdst $text {png gif jpg}]
if {$img != {}} {
if {$label != {}} {
return "!\[\]($img \"$label\")"
} else {
return "!\[\]($img)"
}
}
|
>
|
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
proc fmt_image {text {label {}}} {
# text = symbolic name of the image.
# formatting based on the available data ...
set img [dt_imgdst $text {png gif jpg}]
if {$img != {}} {
set img [LinkTo $img [LinkHere]]
if {$label != {}} {
return "!\[\]($img \"$label\")"
} else {
return "!\[\]($img)"
}
}
|
| ︙ | | | ︙ | |
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
return $img
}
c_pass 1 fmt_manpage_begin {title section version} {c_cinit ; c_clrSections ; return}
c_pass 2 fmt_manpage_begin {title section version} {
Off
XrefInit
c_cinit
set module [dt_module]
set shortdesc [c_get_module]
set description [c_get_title]
|
>
|
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
return $img
}
c_pass 1 fmt_manpage_begin {title section version} {c_cinit ; c_clrSections ; return}
c_pass 2 fmt_manpage_begin {title section version} {
Off
MDCInit
XrefInit
c_cinit
set module [dt_module]
set shortdesc [c_get_module]
set description [c_get_title]
|
| ︙ | | | ︙ | |
Changes to modules/doctools/mpformats/idx.markdown.
| ︙ | | | ︙ | |
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
rename text_postprocess idx_postprocess
proc fmt_plain_text {text} {return {}}
################################################################
## Backend for plain text markup
proc fmt_index_begin {label title} {
if {($label != {}) && ($title != {})} {
set title "$label -- $title"
} elseif {$label != {}} {
set title $label
} elseif {$title != {}} {
# title is set
}
|
>
|
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
rename text_postprocess idx_postprocess
proc fmt_plain_text {text} {return {}}
################################################################
## Backend for plain text markup
proc fmt_index_begin {label title} {
MDCInit
if {($label != {}) && ($title != {})} {
set title "$label -- $title"
} elseif {$label != {}} {
set title $label
} elseif {$title != {}} {
# title is set
}
|
| ︙ | | | ︙ | |
Changes to modules/doctools/mpformats/toc.markdown.
| ︙ | | | ︙ | |
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
proc fmt_plain_text {text} {return {}}
################################################################
## Backend for Markdown markup
proc fmt_toc_begin {label title} {
set title "$label -- $title"
TextInitialize
MDComment "Table of contents [Provenance]"
MDCDone
|
>
|
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
proc fmt_plain_text {text} {return {}}
################################################################
## Backend for Markdown markup
proc fmt_toc_begin {label title} {
MDCInit
set title "$label -- $title"
TextInitialize
MDComment "Table of contents [Provenance]"
MDCDone
|
| ︙ | | | ︙ | |
Changes to support/devel/sak/localdoc/localdoc.tcl.
| ︙ | | | ︙ | |
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
sak::doc::imake __dummy__ $excluded
sak::doc::index __dummy__ $excluded
puts "Removing old documentation..."
# but keep the main index around, manually created, edited, not to be touched
# TODO: catch errors and restore automatically
file rename embedded/index.html e_index.html
run-embedded $baseconfig $toc $nav $cats $mods $apps
return
}
proc ::sak::localdoc::run-idoc-man {baseconfig} {
file delete -force idoc
file mkdir idoc/man
file mkdir idoc/www
|
|
|
>
>
>
>
>
>
>
>
>
>
>
>
|
|
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
sak::doc::imake __dummy__ $excluded
sak::doc::index __dummy__ $excluded
puts "Removing old documentation..."
# but keep the main index around, manually created, edited, not to be touched
# TODO: catch errors and restore automatically
file rename embedded/index.html e_index.html
file delete -force embedded
file mkdir embedded/www
# Put the saved main page back into place, early.
file rename e_index.html embedded/index.html
run-idoc-man $baseconfig
# Note: Might be better to run them separately.
# Note @: Or we shuffle the results a bit more in the post processing stage.
set map {
.man .html
modules/ tcllib/files/modules/
apps/ tcllib/files/apps/
}
set toc [string map $map [fileutil::cat support/devel/sak/doc/toc.txt]]
set apps [string map $map [fileutil::cat support/devel/sak/doc/toc_apps.txt]]
set mods [string map $map [fileutil::cat support/devel/sak/doc/toc_mods.txt]]
set cats [string map $map [fileutil::cat support/devel/sak/doc/toc_cats.txt]]
run-idoc-www $baseconfig $toc $nav $cats $mods $apps
set map {
.man .md
modules/ tcllib/files/modules/
apps/ tcllib/files/apps/
}
set toc [string map $map [fileutil::cat support/devel/sak/doc/toc.txt]]
set apps [string map $map [fileutil::cat support/devel/sak/doc/toc_apps.txt]]
set mods [string map $map [fileutil::cat support/devel/sak/doc/toc_mods.txt]]
set cats [string map $map [fileutil::cat support/devel/sak/doc/toc_cats.txt]]
run-embedded $baseconfig $toc $cats $mods $apps
return
}
proc ::sak::localdoc::run-idoc-man {baseconfig} {
file delete -force idoc
file mkdir idoc/man
file mkdir idoc/www
|
| ︙ | | | ︙ | |
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
dtplite::do $config
return
}
proc ::sak::localdoc::run-idoc-www {baseconfig toc nav cats mods apps} {
puts "Generating HTML (installation)... Pass 1, draft..."
set config $baseconfig
lappend config -exclude {*/doctools/tests/*}
lappend config -exclude {*/support/*}
lappend config -toc $toc
lappend config -nav {Tcllib Home} $nav
lappend config -post+toc Categories $cats
lappend config -post+toc Modules $mods
lappend config -post+toc Applications $apps
lappend config -merge
lappend config -o idoc/www
lappend config html .
dtplite::do $config
puts "Generating HTML (installation)... Pass 2, resolving cross-references..."
dtplite::do $config
return
}
proc ::sak::localdoc::run-embedded {baseconfig toc nav cats mods apps} {
puts "Generating HTML (online)... Pass 1, draft..."
set config $baseconfig
lappend config -exclude {*/doctools/tests/*}
lappend config -exclude {*/support/*}
lappend config -toc $toc
lappend config -post+toc Categories $cats
lappend config -post+toc Modules $mods
lappend config -post+toc Applications $apps
lappend config -merge
lappend config -raw
lappend config -o embedded/www
lappend config -header support/fossil-nav-integration.html
lappend config html .
dtplite::do $config
puts "Generating HTML (online)... Pass 2, resolving cross-references..."
dtplite::do $config
return
}
# ### ### ### ######### ######### #########
package provide sak::localdoc 1.0
##
# ###
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<
|
|
|
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
dtplite::do $config
return
}
proc ::sak::localdoc::run-idoc-www {baseconfig toc nav cats mods apps} {
puts "Generating HTML (installation)... Pass 1, draft..."
set config $baseconfig
lappend config -exclude {*/doctools/tests/*}
lappend config -exclude {*/support/*}
lappend config -toc $toc
lappend config -nav {Tcllib Home} $nav
lappend config -post+toc Categories $cats
lappend config -post+toc Modules $mods
lappend config -post+toc Applications $apps
lappend config -merge
lappend config -o idoc/www
lappend config html .
dtplite::do $config
puts "Generating HTML (installation)... Pass 2, resolving cross-references..."
dtplite::do $config
return
}
proc ::sak::localdoc::run-embedded {baseconfig toc cats mods apps} {
puts "Generating Markdown (online)... Pass 1, draft..."
set config $baseconfig
lappend config -exclude {*/doctools/tests/*}
lappend config -exclude {*/support/*}
lappend config -toc $toc
lappend config -post+toc Categories $cats
lappend config -post+toc Modules $mods
lappend config -post+toc Applications $apps
lappend config -merge
lappend config -ext md
lappend config -o embedded/md
lappend config markdown .
dtplite::do $config
puts "Generating Markdown (online)... Pass 2, resolving cross-references..."
dtplite::do $config
return
}
# ### ### ### ######### ######### #########
package provide sak::localdoc 1.0
##
# ###
|
